@fytkit/sdk 3.5.0 → 4.1.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.1.0
+
+To be published by hand with sdk-publish.yml (the manifest records 4.1.0). Create the tag and GitHub release `@fytkit/sdk@4.1.0` when it is published.
+
+### Features
+
+* `subscribeToMessages` takes an optional `onCoachTyping`, for a "Sam is writing…" line: who on the trainee's coaching team is writing to them right now, as `{ kind: "typing", names }` (staff display names, as the conversation shows them) or `{ kind: "idle" }`. Heard only while the status is `live`; a name drops out by itself `COACH_TYPING_EXPIRY_MS` (8 seconds) after its last sign, so a lost stop never leaves it showing, and the state goes `idle` when the channel is lost. Additive. New type `CoachTypingState` and constant `COACH_TYPING_EXPIRY_MS` (W16)
+* `programs.get` and `programs.getSession` carry `durationMinutes` on each session's workout: the trainer's planned time for the workout, null when unset. Additive (W13)
+* `auth.getSecurityStatus()` adds `passwordChangedAt` (when the password was last set or changed, ISO 8601; null when the account has no password) and `backupCodesRemaining` (unused backup codes left; null when two-factor is off, 0 when every code is used), and `SecurityStatus` gains both fields. Additive (W20)
+* `profile.get` and `profile.update` carry `lengthUnit` (`"in"` or `"cm"`), the member's unit for body measurements, beside `weightUnit`; `profile.update` takes it optionally. Additive (W19)
+* `bodyMeasurements.record` takes an optional `clientRequestId` (a UUID) for offline replay, as `bodyMetrics.record` does: a replay with the same key returns the stored measurements instead of recording them twice. Calls without a key are unchanged (W21)
+
+### Bug Fixes
+
+* `auth.disableTwoFactor` now signs out every other device, and the server rotates the caller's session; the SDK swaps its stored token transparently, so the caller stays signed in ([#494](https://github.com/cbarlow1993/fytkit-web/pull/494))
+
+## 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)
 
 

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
@@ -125,6 +161,13 @@ await fytkit.auth.changePassword({ currentPassword, newPassword, revokeOtherSess
 // nothing changes until the trainee opens it.
 await fytkit.auth.changeEmail({ newEmail });
 
+// Resend the sign-up verification email to the trainee's own address (there
+// is no email input). Resolves to { status: "sent" } or, when the address is
+// already verified and nothing is sent, { status: "already_verified" }.
+// Throttled per account (one a minute, five an hour): over the limit it
+// rejects with { kind: "rate_limited", retryAfter } (milliseconds).
+const { status } = await fytkit.auth.resendVerification();
+
 // 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).
@@ -143,7 +186,11 @@ 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, resend its verification 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
@@ -174,7 +221,7 @@ Every reason and its data: [`docs/developer/reference/errors.md`](../../docs/dev
 
 `subscribeToMessages` keeps a conversation screen current over Supabase
 Realtime: it fetches a token (`messages.realtimeToken`) and fytkit's public
-connection settings (`appConfig.get`), joins the trainee's own private
+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".
@@ -211,6 +258,23 @@ const unsubscribe = subscribeToMessages(fytkit, {
 unsubscribe();
 ```
 
+To show "Sam is writing…" while someone on the trainee's coaching team
+writes a reply, pass `onCoachTyping`. It reports `{ kind: "typing", names }`
+(display names, as the conversation shows them on their messages) and
+`{ kind: "idle" }`. It is live only: a name drops out by itself 8 seconds
+after its last sign (`COACH_TYPING_EXPIRY_MS`), so a lost "stopped" never
+leaves it showing, it goes `idle` when the channel is lost, and while you
+poll it never shows.
+
+```ts
+subscribeToMessages(fytkit, {
+  realtime,
+  onChange: () => refreshConversation(),
+  onCoachTyping: (typing) =>
+    setWritingLine(typing.kind === "typing" ? `${firstName(typing.names[0])} is writing…` : null),
+});
+```
+
 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)
@@ -227,13 +291,14 @@ 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`
+- `auth.requestPasswordReset` / `confirmPasswordReset` / `confirmEmail` / `resendVerification`
 - 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`, `checkIns`, `messages`, `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)