# Beauty API Connection Report

**Date:** 2026-07-26  
**Client:** `modules/beauty/services/beauty-business-api.ts`  
**BFF:** `/api/beauty-business/*` → `:8011`

---

## Connection Architecture

```
Browser (beauty pages)
  → beautyBusinessApi (tenant + JWT)
  → Next.js BFF /api/beauty-business/[...path]
  → beauty-business-service :8011
```

No mock data. All list/create/mutation calls use `beautyBusinessApi` with `X-Tenant-ID` and Bearer token.

---

## API Resources — Frontend Coverage

| API Resource | Methods in Client | UI Surfaces |
|--------------|-------------------|-------------|
| `/health`, `/capabilities`, `/metrics` | GET | Hub, dashboards, monitoring |
| `organizations` | list, get, create, update, delete | Owner, admin |
| `branches` | list, get, create, update, delete | Owner, admin, booking forms |
| `customers` | list, get, create | Owner, admin, customer portal, booking |
| `staff` | list, get, create | Owner, admin, staff portal, schedules |
| `service-categories` | list, get, create | Owner catalog |
| `services` | list, get, create | Owner catalog, public site, booking |
| `staff-schedules` | list, get, create | Owner booking, staff portal |
| `waiting-list` | list, get, create | Owner, reception queue/walk-in |
| `treatment-rooms` | list, get, create | Owner salon |
| `stations` | list, get, create | Owner salon |
| `branch-policies` | list, get, create | Owner salon |
| `package-definitions` | list, get, create | Owner, customer, public |
| `membership-plans` | list, get, create | Owner, customer |
| `commission-rules` | list, get, create | Owner, staff commission page |
| `marketing-campaigns` | list, get, create | Owner, public campaigns |
| `loyalty-integrations` | list, get, create | Owner integrations tab |
| `communication-integrations` | list, get, create | Owner integrations tab |
| `integration-dispatches` | list, get, create | Owner integrations tab |
| `appointments` | list, get, create, update, confirm, check-in, complete, cancel, no-show, history | Owner, reception, customer, staff, public book |
| `settings` | list, upsert | Owner settings, admin settings |
| `permissions/catalog` | GET | Owner settings, admin permissions |
| `audit` | list | Workspace detail drawers |
| `external-providers` | list, get, create, update, delete | Owner integration pages |

---

## Workflow Actions Connected

| Action | API Endpoint | UI Trigger |
|--------|--------------|------------|
| Confirm appointment | `POST .../confirm` | Owner table, reception check-in |
| Check-in | `POST .../check-in` | Owner table, reception check-in |
| Complete | `POST .../complete` | Owner table, reception check-out |
| Cancel | `POST .../cancel` | Owner table, reception |
| No-show | `POST .../no-show` | Owner table, reception |

---

## Cross-Module Integrations (Real Links, Not Mocks)

| UI Surface | External Module | Behavior |
|------------|-----------------|----------|
| Customer invoices/payments | `/accounting/*` | Navigation + empty state |
| Customer loyalty | Loyalty API via beauty integrations list | Read from `loyaltyIntegrations` |
| Reception payments | `/accounting` | Explicit link |
| Owner CRM/accounting integration | `externalProviders` filtered by kind | Real list from API |

---

## API Methods Not in Backend (Documented)

These permissions exist in backend definitions but routes are create/list/get only — client has no update/delete stubs:

- customers, staff, service-categories, services, schedules, waiting-list, rooms, stations, policies, packages, memberships, commissions, marketing campaigns, integrations

When backend adds PATCH/`/delete`, add methods to `beauty-business-api.ts` and enable `updateFn`/`deleteFn` in resource configs.

---

## TanStack Query Keys

Pattern: `["beauty", tenantId, resource, ...params]`  
Lookups: `["beauty", tenantId, "lookups", entity]`  
Invalidation on mutation: resource queryKey + lookups

---

## Error Handling

- `BeautyBusinessApiError` → toast message + ErrorState retry
- 401 → session refresh via `getValidAccessToken` / `refreshSession`
- 403 → `PermissionDeniedState`
- Network failure → Persian connection error message