@fytkit/sdk 3.4.0 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to `@fytkit/sdk` are documented in this file.
 Format: [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/).
 Versioning: [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
+## 4.0.0
+
+To be published by hand (release-please, which runs on GitHub Actions, does not cut this release; the manifest records 4.0.0 so the next automated release bumps from it). Create the tag and GitHub release `@fytkit/sdk@4.0.0` when it is published, or release-please proposes 4.0.0 again.
+
+### ⚠ BREAKING CHANGES
+
+* `appConfig.get` is removed, with no deprecation window: the `appConfig` namespace is gone from `FytkitClient`, and `GET /api/v1/app-config` and `POST /rpc/appConfig/get` answer 404. Use `app.bootstrap` instead. Its colours become the app theme's curated palette (`primaryColor` → `data.theme.palette.primary`, and so on), `appName` → `data.studio.name`, the links → `data.links`, `realtime` → `data.realtime`; the icon URLs, `buildStatus`, `buildVersion`, the social sign-in ids (`auth`), `id` and `trainerId` are gone. Field-by-field migration: [docs/developer/reference/app-bootstrap.md](https://github.com/cbarlow1993/fytkit-web/blob/main/docs/developer/reference/app-bootstrap.md#migrating-from-appconfigget) ([#535](https://github.com/cbarlow1993/fytkit-web/issues/535))
+* `MessagesRealtimeSource` reads the Realtime settings from `app.bootstrap()` (`{ status: "ok", data: { realtime } }`) instead of `appConfig.get()`. A `FytkitClient` still satisfies it; a hand-written source must rename `appConfig.get` to `app.bootstrap` ([#535](https://github.com/cbarlow1993/fytkit-web/issues/535))
+
+### Features
+
+* `app.bootstrap({ etag? })`: the app's launch read. The studio's display name and logo, the effective app theme (template, theme, palette, derived variants and the oldest app release that paints it), every template's minimum app version, feature overrides, the studio's minimum app version, the terms, privacy and help links, the Realtime settings and the payment policy, in one request that needs the client id alone. Resolves to `{ status: "ok", data, etag }`, or to `{ status: "unchanged", etag }` when the `etag` you stored is still current (the server answers 304 with no body). New types `AppBootstrapData`, `AppBootstrapOptions`, `AppBootstrapResult` and `AppNamespace`; `FytkitClient.clientId` names the client id the client was created with, to key per-studio caches by ([#535](https://github.com/cbarlow1993/fytkit-web/issues/535))
+* `app.bootstrap`'s `data.paymentPolicy` and `resolvePaymentMode(policy, { platform, storefront, conditionsMet? })`: whether the app shows "Subscribe" (a link out to the studio's checkout) or "What your plan includes" for the storefront the device's store reports (StoreKit's alpha-3 `Storefront.countryCode` on iOS, Play Billing's alpha-2 country code on Android; case-insensitive). The policy is Fytkit's reviewed list of storefronts where linking out is allowed, with any conditions the app must meet first; every other storefront, and any unmet or unknown condition, is plan info. New types `PaymentMode`, `PaymentPlatform`, `PaymentPolicy` and `ResolvePaymentModeOptions` ([#538](https://github.com/cbarlow1993/fytkit-web/issues/538))
+* `resolveJoinCode(code, { baseUrl?, fetch? })`: resolves a studio's join code (the code on its Fytkit Coach QR code or join link) to the studio's client id, name, logo URL and app theme, with no client id or session. An unknown or replaced code rejects with `{ kind: "not_found", refusal: { reason: "join_code_inactive" } }`; new types `JoinCodeResolution`, `JoinCodeTheme` and `ResolveJoinCodeOptions` ([#529](https://github.com/cbarlow1993/fytkit-web/issues/529))
+* `resolveJoinCode`'s `studio` gains `coaches` (at most 3; today the studio's own public coach profile alone: `name` and the public profile image as `avatarUrl`, null when there is none; never staff names or emails) and `programCount` (published programmes, any access level; drafts and archived ones never count), for a welcome screen's "Coached by" row and programme count. Additive. New type `JoinCodeCoach` ([#600](https://github.com/cbarlow1993/fytkit-web/issues/600))
+* `FytkitRefusalReason` gains `join_code_inactive` ([#529](https://github.com/cbarlow1993/fytkit-web/issues/529))
+* `auth.resendVerification()`: mails a new email-verification link to the signed-in member's own address (a session is required; there is no email input), for a "Send it again" link on a confirm-your-email screen. Resolves to `{ status: "sent" }`, or to `{ status: "already_verified" }` with nothing sent when the address is verified already. Throttled per account (one send a minute, five an hour): over the limit it rejects with `{ kind: "rate_limited" }`. Fytkit Coach members get the app-link URL, as at sign-up. A bearer call, so a 401 refreshes or signs out as usual. Additive. New type `ResendVerificationResult` ([#615](https://github.com/cbarlow1993/fytkit-web/issues/615))
+* `auth.confirmEmailChange({ token })`: applies an email change from the token in the confirmation link, for an app that opens that link itself (Fytkit Coach's app link). Needs no session; idempotent while the address still holds ([#532](https://github.com/cbarlow1993/fytkit-web/issues/532))
+* `sessionLogs.create` and `sessionLogs.addSet` take an optional `clientRequestId` (a UUID) so an offline queue or a retry can replay a write safely: a replay with the same key returns the stored log or set instead of creating a duplicate log or failing the set with `conflict`, and a key reused for another log or set is `conflict`. On a replayed `create`, `sets` holds the log's current sets, so its type is now the set array instead of `never[]`. Calls without a key are unchanged ([#603](https://github.com/cbarlow1993/fytkit-web/issues/603))
+* `bodyMetrics.record` and `nutritionLog.logFood` take an optional `clientRequestId` (a UUID) for the same offline replay: a replay with the same key returns the stored weigh-in (with the warning `update` would give it) or food log entry, with their current values, instead of recording a second one, and writes no second timeline event. A `logFood` key reused for another `loggedFor` day is `conflict`; a weigh-in's values can all be edited, so a `record` replay returns the stored weigh-in whatever it sends. Keys are scoped to the trainee. `nutritionLog.updateFood` and `nutritionLog.setTargets` take no key: they set absolute values, so a replay is already safe. Calls without a key are unchanged (W17, W18)
+* `sessionLogs.delete({ id })`: deletes one of the member's own session logs, in progress or finished, with its sets, personal records and any staff review, comments and reactions; its timeline events go too, and the streak, personal records and program enrollment completion are recomputed. Resolves to `{ data: { id, deleted: true } }`; another member's log or an unknown id is `not_found`, and the call is refused while a member is impersonated ([#602](https://github.com/cbarlow1993/fytkit-web/issues/602))
+* member coaching loop Phase 2: the `bodyMeasurements`, `progressPhotos`, `timeline`, `health` and `habits` namespaces, `progress.getVolume`, `progression.getE1rmTrend`, `bodyMetrics.update`, and the refusal reasons `staff_entered`, `checkin_sourced`, `consent_required`, `consent_outdated`, `too_many_pending`, `photo_limit_reached`, `invalid_uploads` and `poses_differ`, with the `coaching_habits` entitlement refusal and the `first_party_account` error code ([#461](https://github.com/cbarlow1993/fytkit-web/issues/461)) ([#487](https://github.com/cbarlow1993/fytkit-web/issues/487))
+
+## [3.5.0](https://github.com/cbarlow1993/fytkit-web/compare/@fytkit/sdk@3.4.0...@fytkit/sdk@3.5.0) (2026-10-10)
+
+
+### Features
+
+* member coaching loop ([#461](https://github.com/cbarlow1993/fytkit-web/issues/461)) [integration branch] ([#482](https://github.com/cbarlow1993/fytkit-web/issues/482)) ([75291c1](https://github.com/cbarlow1993/fytkit-web/commit/75291c1ba29b142b96fe3452b61a25e37f016c8b))
+
 ## [3.4.0](https://github.com/cbarlow1993/fytkit-web/compare/@fytkit/sdk@3.3.0...@fytkit/sdk@3.4.0) (2026-10-04)
 
 

package/README.md

@@ -48,6 +48,42 @@ await fytkit.auth.signOut();
 off();
 ```
 
+## Joining a studio and launching
+
+A Fytkit Coach style app starts from a studio's join code (its QR code or
+join link) and reads the studio's launch settings once per launch:
+
+```ts
+import { createFytkitClient, resolveJoinCode, resolvePaymentMode } from "@fytkit/sdk";
+
+// Once, when the member scans or types the code: keep the client id.
+const studio = await resolveJoinCode(scannedCode);
+const fytkit = createFytkitClient({ clientId: studio.clientId });
+
+// Every launch: revalidate the stored settings with their ETag.
+const stored = await loadStoredBootstrap(); // { data, etag } | null, your storage
+const result = await fytkit.app.bootstrap({ etag: stored?.etag });
+if (result.status === "ok") await saveStoredBootstrap({ data: result.data, etag: result.etag });
+const settings = result.status === "ok" ? result.data : stored?.data;
+// settings.studio (name, logoUrl), settings.theme (palette, variants),
+// settings.featureOverrides, settings.minAppVersion, settings.links,
+// settings.realtime, settings.paymentPolicy
+
+// "Subscribe" (a link out to the studio's checkout) only where the store allows it.
+const { mode } = resolvePaymentMode(settings.paymentPolicy, {
+  platform: "ios",
+  storefront: storefrontCountryCode, // StoreKit's Storefront.current?.countryCode
+});
+```
+
+`app.bootstrap` resolves to `{ status: "unchanged" }` (a 304, no body) while
+the `etag` you sent is current. It replaced `appConfig.get` in 4.0.0:
+[`app.bootstrap`](../../docs/developer/reference/app-bootstrap.md), with the
+field-by-field migration. [`resolveJoinCode`](../../docs/developer/reference/resolveJoinCode.md)
+needs no client. `resolvePaymentMode` is plan info ("What your plan includes")
+for every storefront the policy doesn't list:
+[Subscribe or what your plan includes](../../docs/developer/reference/app-bootstrap.md#subscribe-or-what-your-plan-includes).
+
 ## Tracking a workout
 
 Log a workout ad-hoc (no program enrollment needed), record sets, complete
@@ -117,17 +153,20 @@ await fytkit.auth.regenerateBackupCodes({ password });
 await fytkit.auth.disableTwoFactor({ password });
 
 // Password change (verifies the current password server-side). With
-// revokeOtherSessions the SDK adopts the rotated token transparently.
+// revokeOtherSessions every other session of the account ends, in any app,
+// and the SDK adopts the rotated token transparently.
 await fytkit.auth.changePassword({ currentPassword, newPassword, revokeOtherSessions: true });
 
 // Email change — a confirmation link is emailed to the new address;
 // nothing changes until the trainee opens it.
 await fytkit.auth.changeEmail({ newEmail });
 
-// Devices: revokeId is an opaque id (never the bearer token).
+// Devices signed in through this app (plus the calling one); the trainee's
+// sessions elsewhere are never listed. revokeId is an opaque id (never the
+// bearer token).
 const sessions = await fytkit.auth.listSessions();
 await fytkit.auth.revokeSession({ revokeId: sessions.find((s) => !s.isCurrent)!.revokeId });
-await fytkit.auth.revokeOtherSessions(); // "sign out of all other devices"
+await fytkit.auth.revokeOtherSessions(); // "sign out of your other devices" on this app
 
 // Permanently close the account (re-verifies email + password). On success the
 // SDK clears the session and emits signed_out.
@@ -140,9 +179,83 @@ fresh sign-in is `{ kind: "forbidden", code: "reauth_required" }`. None of
 these sign the trainee out — only a 401 on an authenticated call means the
 session is gone. A wrong password on `signIn` (for example, signing in again
 after `reauth_required`) is a plain `auth_required` and leaves the current
-session alone. Enrolling twice in a program is `{ kind: "conflict" }` with the
+session alone. An account that also runs or works at a trainer on Fytkit can't
+sign in, sign up or complete two-factor through an app, and an existing app
+session can't change its password or email or close it:
+`{ kind: "forbidden", code: "first_party_account" }`; point it to Fytkit's own
+sign-in. Enrolling twice in a program is `{ kind: "conflict" }` with the
 existing `enrollmentId`.
 
+## Refusals
+
+When the server says no for a reason your app can act on (a coaching feature
+the plan lacks, a check-in already sent, a messaging limit, a studio that is
+full), the error carries `refusal: { reason, data }` beside its usual fields.
+Branch on `refusal.reason`, never on message text; `refusalData` reads a
+known reason's data typed:
+
+```ts
+import { refusalData } from "@fytkit/sdk";
+
+try {
+  await fytkit.messages.send({ body, clientRequestId });
+} catch (err) {
+  const plan = refusalData(err, "entitlement_required");
+  if (plan) return showUpgrade(plan.entitlement);
+  const daily = refusalData(err, "daily_limit");
+  if (daily) return keepDraftUntil(daily.retryAt);
+  throw err;
+}
+```
+
+Every reason and its data: [`docs/developer/reference/errors.md`](../../docs/developer/reference/errors.md#refusals).
+
+## Live chat
+
+`subscribeToMessages` keeps a conversation screen current over Supabase
+Realtime: it fetches a token (`messages.realtimeToken`) and fytkit's public
+connection settings (`app.bootstrap`), joins the trainee's own private
+channel (and joins it afresh after Realtime closes it), renews the token
+before it expires, and reports when to poll instead. Events carry no message content: `onChange` means "read the
+conversation and the unread count again".
+
+The SDK has no dependency on supabase-js. Add `@supabase/supabase-js` to
+your app (`npm install @supabase/supabase-js@^2.97.0`) and pass a factory
+that creates a client for the subscription alone. It must be 2.87.1 or
+later: the helper sets the trainee's token on the socket by hand, and
+earlier 2.x clients swap it for the anon key on the next heartbeat, which
+leaves the subscription in `fallback`. Keep the `auth` options below: the
+client carries the trainee's token only, and must not keep or refresh a
+session, or read a sign-in from your page's URL that would replace it.
+
+```ts
+import { createClient } from "@supabase/supabase-js";
+import { MESSAGES_FALLBACK_POLL_MS, subscribeToMessages } from "@fytkit/sdk";
+
+const unsubscribe = subscribeToMessages(fytkit, {
+  realtime: ({ url, anonKey }) =>
+    createClient(url, anonKey, {
+      auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
+    }),
+  onChange: () => refreshConversation(), // messages.list + messages.unreadCount
+  onStatus: (status) => {
+    // "live": stop polling. "connecting" / "fallback": poll the conversation
+    // every MESSAGES_FALLBACK_POLL_MS.conversation (10 s) and the count every
+    // MESSAGES_FALLBACK_POLL_MS.unreadCount (60 s). "refused": no trainee to
+    // listen for (signed out); the subscription has stopped.
+    setPolling(status === "connecting" || status === "fallback");
+  },
+});
+
+// On leaving the screen or signing out:
+unsubscribe();
+```
+
+Polling spends your app's per-minute request limit, which all its users
+share, so stop as soon as the status is `live`. The full guide:
+[`messages.realtimeToken`](../../docs/developer/reference/data-namespaces.md#messagesrealtimetoken)
+and the recipe [Chat screen with live updates](../../docs/developer/recipes/chat-screen-with-live-updates.md).
+
 ## Notification preferences
 
 Per-member toggles stored server-side (defaults apply until first write):
@@ -154,13 +267,18 @@ await fytkit.preferences.updateNotifications({ streakAlerts: false }); // partia
 
 ## What's included in this preview
 
+- `resolveJoinCode` (a studio's join code to its client id, name, logo and app theme, with no client) and `app.bootstrap` (the launch read, revalidated with its ETag), with `resolvePaymentMode` ("Subscribe" link-out or "What your plan includes", per storefront)
 - `auth.signUp` / `signIn` / `signOut` / `getSession` / `onAuthStateChange`
 - `auth.requestPasswordReset` / `confirmPasswordReset` / `confirmEmail`
 - Two-factor: `auth.verifyTotp` / `verifyBackupCode` / `requestEmailOtp` / `verifyEmailOtp` (sign-in), `enableTotp` / `verifyTotpSetup` / `disableTwoFactor` / `regenerateBackupCodes` / `getSecurityStatus` (management)
-- Account security: `auth.changePassword` / `changeEmail` / `listSessions` / `revokeSession` / `revokeOtherSessions` / `closeAccount`
-- Data namespaces: `workouts`, `programs`, `recipes`, `nutrition`, `nutritionLog`, `profile`, `preferences`, `articles`, `enrollments`, `sessionLogs`, `progression`, `progress`, `bodyMetrics`, `media`, `appConfig`, `subscription`
+- Account security: `auth.changePassword` / `changeEmail` / `confirmEmailChange` / `listSessions` / `revokeSession` / `revokeOtherSessions` / `closeAccount`
+- Data namespaces: `workouts`, `programs`, `recipes`, `nutrition`, `nutritionLog`, `profile`, `preferences`, `articles`, `enrollments`, `sessionLogs`, `progression`, `progress`, `bodyMetrics`, `bodyMeasurements`, `progressPhotos`, `checkIns`, `messages`, `timeline`, `health`, `habits`, `media`, `subscription`
 - Workout tracking: program session logs and ad-hoc workout logs (`sessionLogs.create` with `workoutId`), set logging, per-workout history (`sessionLogs.list({ workoutId })`)
-- Progress: `progress.getSummary` / `getAdherence` / `getStreak` (stored streaks), `progression.getPrSummary` / `listPrHistory` (stored PR history) / `getHistory`, `bodyMetrics.list` / `record` / `delete`
+- Progress: `progress.getSummary` / `getAdherence` / `getStreak` (stored streaks) / `getVolume` (last week's hard sets per muscle group), `progression.getPrSummary` / `listPrHistory` (stored PR history) / `getE1rmTrend` (estimated 1-rep max per session, per lift) / `getHistory`, `bodyMetrics.list` / `record` / `update` / `delete`
+- Coach feedback on logged sessions: `sessionLogs.getFeedback` / `markFeedbackSeen` / `unseenFeedbackCount`
+- Check-ins: `checkIns.current` / `submit` / `update` / `list` / `get` / `markReplySeen` / `requestPhotoUpload` (weekly or fortnightly check-ins a coach reviews; needs a plan with `coaching_checkins`)
+- Messages: `messages.list` / `send` / `requestAttachmentUpload` / `markRead` / `delete` / `unreadCount` / `realtimeToken` (the trainee's conversation with their coaches; starting one needs a plan with `coaching_messages`, answering a coach does not; `requestAttachmentUpload` reserves a photo to send with a message)
+- Live chat: `subscribeToMessages` (joins the trainee's private Realtime channel with `messages.realtimeToken`, renews the token, and says when to poll instead; see [Live chat](#live-chat))
 - Automatic header injection (`X-Fytkit-Client-Id`, `Authorization: Bearer …`)
 - Proactive refresh ~60 s before token expiry (retried with backoff when offline) + reactive 401 retry; only a server-rejected refresh signs out
 - Pluggable token storage (`localStorage` default, in-memory + cookie for SSR)