Studio settings JSON

Studio has two JSON columns. settings is a bag of feature flags, integration state and server-written stamps. branding is the trainee app’s brand skin. Neither has a full Zod schema. Each feature reads its own keys defensively and ignores the rest.

`Studio.settings`

{
  "calendarEnabled": true,
  "mbpEnabled": true,
  "mbpProteinKcal": 180,
  "mbpCarbKcal": 160,
  "mbpFatKcal": 180,
  "mbpUnitLabel": null,
  "contactWhatsapp": "+972 50 000 0000",
  "contactWhatsappEnabled": true,
  "subscriptionStartMode": "ASSIGNMENT",
  "onboarding": { "bootstrappedAt": "2026-10-01T08:00:00.000Z", "completedAt": "2026-10-01T08:20:00.000Z" },
  "smartsend": { "apiKey": "SMARTSEND_ORG_KEY", "zapId": "perform-STUDIO_ID", "orgSlug": "my-studio", "userMap": {} },
  "agent": { "apiKey": "STUDIO_API_KEY" },
  "demoMode": false
}

How it is written

There are two write paths and they behave differently.

Route	Roles	Behaviour
`PATCH /v1/web/studios/current` with a `settings` object	`OWNER`, `HEAD_COACH`	Replaces the whole blob. `withStoredMbpSettings` carries the stored `mbp*` keys over whatever the body says, because those may only change through the settings route.
`PATCH /v1/web/studios/current/settings`	`OWNER`, `HEAD_COACH`	Merges a validated patch (`patchStudioSettingsBody`) into the stored object. Runs under a lock on the studio row, so concurrent saves never lose each other’s keys.

Other modules write their own sub-objects directly (smartsend, agent, onboarding, demoMode). They read the current object, spread it, and write it back.

PATCH /v1/web/studios/current replaces the blob. A client that sends a partial settings object through it drops every key it did not include, apart from the mbp* keys. Use the settings route for the keys it covers.

Keys validated by `patchStudioSettingsBody`

Defined in apps/core-api/src/modules/studios/studios.schema.ts.

Key	Type	Default when absent	Read by	Effect
`calendarEnabled`	boolean	on. Only an explicit `false` turns it off	`studioCalendarEnabled` in `trainee.service.ts`	Whether trainees can book meetings in the app.
`mbpEnabled`	boolean	off. Only an explicit `true` turns it on	`mbpEnabled` in `foods/mbp.ts`, used by the trainee nutrition endpoints, the inbox context and the meal analysis	Whether nutrition is shown in portions.
`mbpProteinKcal`	number, 20 to 2000	180	`readMbpAnchors`	Calories in one protein portion.
`mbpCarbKcal`	number, 20 to 2000	160	`readMbpAnchors`	Calories in one carb portion.
`mbpFatKcal`	number, 20 to 2000	180	`readMbpAnchors`	Calories in one fat portion.
`mbpUnitLabel`	string up to 20 characters, or null	null, meaning the per-locale default	`readMbpUnitLabel`	The word shown for “portion”. Blank is stored as null.
`contactWhatsapp`	string up to 32 characters, or null	null	The trainee app’s contact button. Falls back to the coach’s phone	The studio’s WhatsApp contact number. `normalizeContactWhatsapp` requires 8 to 15 digits and stores the trimmed input.
`contactWhatsappEnabled`	boolean	on. Only an explicit `false` turns it off	`trainee/coach-whatsapp.ts`	Whether the trainee app offers the WhatsApp contact button.
`subscriptionStartMode`	`ASSIGNMENT`, `INTAKE_FORM`, `FIRST_PLAN`, `FIRST_WORKOUT`	`ASSIGNMENT`	`subscriptionStartMode` in `client-subscriptions/start-mode.ts`	When a new subscription starts. `ASSIGNMENT` starts it immediately with dates. The other three create an `AWAITING_START` row with that `startTrigger`.

Changing an anchor re-prices foods

When a patch changes any of the three anchors, patchSettings calls repriceStudioFoods in the same transaction, using the anchors stored just before the change as the “from” values. The response includes a foodRepricing summary, or null when the anchors did not change. This is why the anchors are bounded and why the generic studio update is not allowed to touch them.

`onboarding`

Server-written stamps about the signup wizard.

Key	Written by	Meaning
`onboarding.bootstrappedAt`	`apps/core-api/src/modules/onboarding/onboarding.service.ts`	ISO timestamp. The wizard created this studio.
`onboarding.completedAt`	`packages/auth/src/lib/studio-lifecycle.ts`	ISO timestamp. The owner finished the wizard.

Read by onboardingOf in billing/billing.repository.ts. Plan limits use these stamps, and never User.onboardingComplete, to decide whether a studio is still in the wizard and exempt from the seat check. See Billing models.

`smartsend`

State of the studio’s SmartSend WhatsApp connection. Read by readSmartSendSettings in whatsapp/whatsapp.service.ts.

Key	Written by	Meaning
`smartsend.apiKey`	`POST /v1/web/whatsapp/connect`	The studio’s SmartSend organization key. It is stored in plaintext in this JSON column. Sends fail with “whatsapp is not connected for this studio” when it is missing.
`smartsend.zapId`	`connect`	`perform-<studioId>`. Identifier used when registering the inbound webhook.
`smartsend.orgSlug`	`PUT /v1/web/whatsapp/smartsend/org-slug`	The studio’s slug inside the SmartSend app. Needed to build deep links to a conversation. Entered by hand because nothing on Perform’s side can derive it. Clearing it removes the key.
`smartsend.userMap`	`PUT /v1/web/whatsapp/smartsend/user-map`	Map of Perform coach id to `{ id, name }` of a SmartSend user. Used by the embedded chat and to attribute partner API notes to a coach.

One query filters on this path directly: settings with JSON path ['smartsend', 'apiKey']. See SmartSend WhatsApp.

`agent`

State of the WhatsApp AI assistant for this studio. Written by apps/core-api/src/modules/agent/agent.service.ts.

Key	Meaning
`agent.apiKey`	The plaintext of a studio API key the assistant minted for itself. The matching `StudioApiKey` row is visible in the coach’s integrations list and acts as the kill switch.
`agent.revokedAt`	ISO timestamp. Written when the assistant’s key was found revoked. It replaces the whole `agent` object, so the key is gone. The assistant stays disconnected until the coach asks to reconnect.

See WhatsApp webhooks and the agent.

`demoMode`

Key	Written by	Read by
`demoMode`	`apps/core-api/src/scripts/setup-demo-studio.ts`	`demo-activity/demo-mode.ts` and the loader, which selects studios with JSON path `['demoMode']` equal to `true`

When true, the hourly demo activity job fabricates trainee activity for the studio so a sales demo looks alive. Never set it on a real studio.

Reading settings safely

Follow the pattern every reader uses:

function toSettingsObject(value: unknown): Record<string, unknown> {
  return value && typeof value === 'object' && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : {};
}

The column can be null, and nothing guarantees a key’s type. Check the type of each value you read, and choose the default deliberately. Note that calendarEnabled defaults to on and mbpEnabled defaults to off.

`Studio.branding`

The brand skin of the trainee app. The web panel sends the whole object on every save. The frontend type is Branding in apps/saas/modules/shared/lib/branding.ts. Every key is nullable, and null means “use the default”.

Key	Meaning
`logoUrl`	Studio logo.
`iconUrl`	Square icon.
`logoScale`	Logo size adjustment.
`primaryColor`	Main brand colour.
`onPrimaryColor`	Text colour on top of the primary colour.
`secondaryColor`, `accentColor`	Supporting colours.
`radius`	Corner radius.
`fontFamily`	App font.
`iconColor`, `iconStrokeWidth`	Icon styling.
`appTheme`	`dark` or `light`.
`homeTheme`	Home screen skin: `classic`, `glass`, `poster` or `bento`. Null means `classic`.
`selfieExampleUrl`	Example image shown when the app asks for a progress photo.
`storyBackgroundUrl`	Background of the share-to-story template.
`storyShareText`	Text on the shared story.
`instagramHandle`	Stamped on shared story templates.
`coachAvatarUrl`	Coach portrait shown on coach-message form fields.
`storyProfileImage`	Round avatar on the story chrome of the share screen.

Validation

normalizeBrandingInput in apps/core-api/src/modules/studios/branding.ts passes every key through untouched except two, so no existing blob ever fails to save:

Key	Rule	Error detail
`instagramHandle`	Lowercased, leading `@` removed, blank becomes null. Must match `a-z`, `0-9`, `.` and `_`, up to 30 characters. A handle stored before the rule existed is tolerated when it is sent back unchanged	`INSTAGRAM_HANDLE_INVALID`
`storyProfileImage`	An `https` URL up to 2000 characters, or null	`STORY_PROFILE_IMAGE_INVALID`

Both fail with ErrorCode.VALIDATION and a details entry whose path is ['branding', '<field>'].

​Studio.settings

​How it is written

​Keys validated by patchStudioSettingsBody

​Changing an anchor re-prices foods

​onboarding

​smartsend

​agent

​demoMode

​Reading settings safely

​Studio.branding

​Validation

`Studio.settings`

How it is written

Keys validated by `patchStudioSettingsBody`

Changing an anchor re-prices foods

`onboarding`

`smartsend`

`agent`

`demoMode`

Reading settings safely

`Studio.branding`

Validation