@fytkit/sdk 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ 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).
 
+## [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

@@ -117,17 +117,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.
@@ -143,6 +146,76 @@ after `reauth_required`) is a plain `auth_required` and leaves the current
 session alone. 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 (`appConfig.get`), 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):
@@ -158,9 +231,13 @@ await fytkit.preferences.updateNotifications({ streakAlerts: false }); // partia
 - `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`
+- Data namespaces: `workouts`, `programs`, `recipes`, `nutrition`, `nutritionLog`, `profile`, `preferences`, `articles`, `enrollments`, `sessionLogs`, `progression`, `progress`, `bodyMetrics`, `checkIns`, `messages`, `media`, `appConfig`, `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`
+- 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)