@proveanything/smartlinks 2.0.69 → 2.0.70

package/dist/api/authKit.d.ts

@@ -1,4 +1,4 @@
-import type { AuthLoginResponse, AppleLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, AuthKitConfigInput, AuthKitSetIdentityResponse, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaEnrolledResponse, MfaFactorsResponse, TrustedDevice } from "../types/authKit.js";
+import type { AuthLoginResponse, AppleLoginOptions, RefreshResponse, LogoutResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, AuthKitConfig, AuthKitConfigInput, AuthKitSetIdentityResponse, AuthKitInviteRequest, AuthKitInviteResponse, MagicLinkSendResponse, MagicLinkVerifyResponse, UserProfile, UpdateProfileResponse, ProfileUpdateData, SuccessResponse, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, MfaChallengeSendResponse, MfaFinalizeResponse, MfaEnrollSendResponse, MfaTotpEnrollResponse, MfaEnrolledResponse, MfaFactor, MfaFactorsResponse, TrustedDevice } from "../types/authKit.js";
 /**
  * Namespace containing helper functions for the new AuthKit API.
  * Legacy collection-based authKit helpers retained (marked as *Legacy*).
@@ -208,8 +208,11 @@ export declare namespace authKit {
     function verifyEmailChange(clientId: string, token: string): Promise<SuccessResponse>;
     function updatePhone(clientId: string, phoneNumber: string, verificationCode: string): Promise<SuccessResponse>;
     function deleteAccount(clientId: string, password: string, confirmText: string): Promise<SuccessResponse>;
-    /** Send (or resend) an MFA challenge code to the given factor (public). */
-    function mfaChallengeSend(clientId: string, mfaSessionToken: string, factor: 'email' | 'sms'): Promise<MfaChallengeSendResponse>;
+    /**
+     * Send (or resend) an MFA challenge code to the given factor (public). For `totp` nothing is sent —
+     * it tells the server the code will come from their authenticator app; then {@link mfaChallengeVerify}.
+     */
+    function mfaChallengeSend(clientId: string, mfaSessionToken: string, factor: MfaFactor): Promise<MfaChallengeSendResponse>;
     /**
      * Verify an MFA challenge code and finalize the login (public). On success this behaves
      * like {@link login} — the bearer token is adopted and the cache invalidated.
@@ -233,6 +236,15 @@ export declare namespace authKit {
     function enrollSmsMfa(clientId: string, phoneNumber: string): Promise<MfaEnrollSendResponse>;
     /** Confirm SMS-factor enrollment with the code sent by {@link enrollSmsMfa} (authenticated). */
     function confirmSmsMfa(clientId: string, mfaSessionToken: string, code: string): Promise<MfaEnrolledResponse>;
+    /**
+     * Begin authenticator-app enrollment (authenticated): a new secret for Google Authenticator,
+     * Microsoft Authenticator, 1Password and the like. Show `otpauthUri` as a QR code (and `secret` for
+     * typing in), then {@link confirmTotpMfa} with the code the app shows. Nothing is kept until then;
+     * setting up again replaces the previous app once confirmed.
+     */
+    function enrollTotpMfa(clientId: string): Promise<MfaTotpEnrollResponse>;
+    /** Confirm authenticator-app enrollment with the 6-digit code the app shows (authenticated). */
+    function confirmTotpMfa(clientId: string, mfaSessionToken: string, code: string): Promise<MfaEnrolledResponse>;
     /**
      * Generate a fresh set of recovery codes, invalidating any previous set (authenticated).
      * Returned **in plaintext, exactly once** — nothing else in the API ever returns them
@@ -242,7 +254,7 @@ export declare namespace authKit {
         recoveryCodes: string[];
     }>;
     /** Remove an enrolled MFA factor (authenticated). Server route is DELETE with a body. */
-    function removeMfaFactor(clientId: string, factor: 'email' | 'sms', password: string): Promise<SuccessResponse>;
+    function removeMfaFactor(clientId: string, factor: MfaFactor, password: string): Promise<SuccessResponse>;
     /** List devices trusted to skip MFA challenges for the current user (authenticated). */
     function listTrustedDevices(clientId: string): Promise<{
         devices: TrustedDevice[];
@@ -281,5 +293,17 @@ export declare namespace authKit {
     function setIdentity(collectionId: string, authKitId: string, body: {
         mode: 'own';
     }): Promise<AuthKitSetIdentityResponse>;
+    /**
+     * Invite someone to be a member of a site with its own logins (admin). Makes their account if they have
+     * none (the only way in when the site is invitation only — `signUp: 'invite'`), finds or creates their
+     * contact in this collection with the `customFields` you pass (their level), links the two, and emails
+     * them a sign-in link to the site (`redirectUrl`, default the kit's) that works once for 7 days. The page
+     * it opens handles it like any magic link: `mode=magicLink&token=…` → {@link verifyMagicLink}.
+     * Inviting someone again sends a fresh link.
+     *
+     * Errors: `OWN_LOGINS_REQUIRED` (409), `INVALID_EMAIL` (400), `INVALID_REDIRECT_URL` (400, not one of
+     * this site's addresses), `TOO_MANY_INVITES` (429, 5 an hour per address).
+     */
+    function invite(collectionId: string, authKitId: string, body: AuthKitInviteRequest): Promise<AuthKitInviteResponse>;
     function remove(collectionId: string, authKitId: string): Promise<void>;
 }

package/dist/api/authKit.js

@@ -380,7 +380,10 @@ export var authKit;
      * challenge/send can be called again on the same token (while unexpired/unburned) to
      * switch factors or resend.
      * =================================== */
-    /** Send (or resend) an MFA challenge code to the given factor (public). */
+    /**
+     * Send (or resend) an MFA challenge code to the given factor (public). For `totp` nothing is sent —
+     * it tells the server the code will come from their authenticator app; then {@link mfaChallengeVerify}.
+     */
     async function mfaChallengeSend(clientId, mfaSessionToken, factor) {
         return post(`/authkit/${encodeURIComponent(clientId)}/mfa/challenge/send`, { mfaSessionToken, factor });
     }
@@ -442,6 +445,21 @@ export var authKit;
         return post(`/authkit/${encodeURIComponent(clientId)}/mfa/factors/sms/confirm`, { mfaSessionToken, code });
     }
     authKit.confirmSmsMfa = confirmSmsMfa;
+    /**
+     * Begin authenticator-app enrollment (authenticated): a new secret for Google Authenticator,
+     * Microsoft Authenticator, 1Password and the like. Show `otpauthUri` as a QR code (and `secret` for
+     * typing in), then {@link confirmTotpMfa} with the code the app shows. Nothing is kept until then;
+     * setting up again replaces the previous app once confirmed.
+     */
+    async function enrollTotpMfa(clientId) {
+        return post(`/authkit/${encodeURIComponent(clientId)}/mfa/factors/totp/enroll`, {});
+    }
+    authKit.enrollTotpMfa = enrollTotpMfa;
+    /** Confirm authenticator-app enrollment with the 6-digit code the app shows (authenticated). */
+    async function confirmTotpMfa(clientId, mfaSessionToken, code) {
+        return post(`/authkit/${encodeURIComponent(clientId)}/mfa/factors/totp/confirm`, { mfaSessionToken, code });
+    }
+    authKit.confirmTotpMfa = confirmTotpMfa;
     /**
      * Generate a fresh set of recovery codes, invalidating any previous set (authenticated).
      * Returned **in plaintext, exactly once** — nothing else in the API ever returns them
@@ -525,6 +543,22 @@ export var authKit;
         return post(path, body);
     }
     authKit.setIdentity = setIdentity;
+    /**
+     * Invite someone to be a member of a site with its own logins (admin). Makes their account if they have
+     * none (the only way in when the site is invitation only — `signUp: 'invite'`), finds or creates their
+     * contact in this collection with the `customFields` you pass (their level), links the two, and emails
+     * them a sign-in link to the site (`redirectUrl`, default the kit's) that works once for 7 days. The page
+     * it opens handles it like any magic link: `mode=magicLink&token=…` → {@link verifyMagicLink}.
+     * Inviting someone again sends a fresh link.
+     *
+     * Errors: `OWN_LOGINS_REQUIRED` (409), `INVALID_EMAIL` (400), `INVALID_REDIRECT_URL` (400, not one of
+     * this site's addresses), `TOO_MANY_INVITES` (429, 5 an hour per address).
+     */
+    async function invite(collectionId, authKitId, body) {
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/authKit/${encodeURIComponent(authKitId)}/invite`;
+        return post(path, body);
+    }
+    authKit.invite = invite;
     async function remove(collectionId, authKitId) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/authKit/${encodeURIComponent(authKitId)}`;
         return del(path);

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.69  |  Generated: 2026-10-20T19:38:11.744Z
+Version: 2.0.70  |  Generated: 2026-10-24T08:16:51.896Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2808,7 +2808,7 @@ interface ServerFunctionSl {
   tags: { resolve(id: string): Promise<ResolvedTag | null> };
   contacts: {
   upsert(details: ContactUpsertDetails): Promise<{ contactId: string; created: boolean }>;
-  forCaller(): Promise<{ contactId: string } | null>;
+  forCaller(): Promise<CallerContact | null>;
   };
   interactions: { record(event: ServerFunctionInteractionEvent): Promise<{ eventId: string }> };
   tools: { run<T = any>(name: string, args?: Record<string, any>): Promise<T> };
@@ -2830,6 +2830,20 @@ interface ServerFunctionCaller {
 }
 ```
 
+**CallerContact** (interface)
+```typescript
+interface CallerContact {
+  contactId: string;
+  email: string | null;
+  phone: string | null;
+  firstName: string | null;
+  lastName: string | null;
+  displayName: string | null;
+  tags: string[];
+  customFields: Record<string, unknown>;
+}
+```
+
 **ServerFunctionContext** (interface)
 ```typescript
 interface ServerFunctionContext {
@@ -4565,9 +4579,9 @@ interface AppleLoginOptions {
 ```typescript
 interface MfaRequiredDetails {
   mfaSessionToken: string
-  availableFactors: Array<'email' | 'sms'>
-  preferredFactor: 'email' | 'sms'
-  maskedDestinations: { email?: string; sms?: string }
+  availableFactors: MfaFactor[]
+  preferredFactor: MfaFactor
+  maskedDestinations: { email?: string; sms?: string; totp?: string }
 }
 ```
 
@@ -4575,7 +4589,7 @@ interface MfaRequiredDetails {
 ```typescript
 interface MfaChallengeSendResponse {
   success: true
-  factor: 'email' | 'sms'
+  factor: MfaFactor
   destination: string
   expiresAt: string
 }
@@ -4590,11 +4604,23 @@ interface MfaEnrollSendResponse {
 }
 ```
 
+**MfaTotpEnrollResponse** (interface)
+```typescript
+interface MfaTotpEnrollResponse {
+  mfaSessionToken: string
+  secret: string
+  otpauthUri: string
+  issuer: string
+  account: string
+  expiresAt: string
+}
+```
+
 **MfaEnrolledResponse** (interface)
 ```typescript
 interface MfaEnrolledResponse {
   enrolled: true
-  factor: 'email' | 'sms'
+  factor: MfaFactor
 }
 ```
 
@@ -4604,6 +4630,7 @@ interface MfaFactorsResponse {
   enrolledFactors: {
   email?: { enrolledAt: string; destination: string }
   sms?: { enrolledAt: string; destination: string }
+  totp?: { enrolledAt: string; destination: string }
   }
   recoveryCodesRemaining: number
   mfaEnabledForClient: boolean
@@ -4866,6 +4893,30 @@ interface AuthKitConfig {
   security?: AuthKitSecurityConfig
   collectionIds?: string[]
   identity?: AuthKitIdentity
+  signUp?: 'open' | 'invite'
+}
+```
+
+**AuthKitInviteRequest** (interface)
+```typescript
+interface AuthKitInviteRequest {
+  email: string
+  firstName?: string
+  lastName?: string
+  displayName?: string
+  customFields?: Record<string, unknown>
+  redirectUrl?: string
+}
+```
+
+**AuthKitInviteResponse** (interface)
+```typescript
+interface AuthKitInviteResponse {
+  ok: true
+  userId: string
+  contactId: string
+  created: boolean
+  expiresAt: string
 }
 ```
 
@@ -4934,6 +4985,8 @@ interface AuthKitLockoutPolicy {
 
 **AuthKitErrorCode** = ``
 
+**MfaFactor** = `'email' | 'sms' | 'totp'`
+
 **MfaErrorCode** = ``
 
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
@@ -11291,8 +11344,8 @@ Update the authenticated user's profile and replace the bearer token when refres
 **deleteAccount**(clientId: string, password: string, confirmText: string) → `Promise<SuccessResponse>`
 Update the authenticated user's profile and replace the bearer token when refreshed claims are returned.
 
-**mfaChallengeSend**(clientId: string, mfaSessionToken: string, factor: 'email' | 'sms') → `Promise<MfaChallengeSendResponse>`
-Send (or resend) an MFA challenge code to the given factor (public).
+**mfaChallengeSend**(clientId: string, mfaSessionToken: string, factor: MfaFactor) → `Promise<MfaChallengeSendResponse>`
+Send (or resend) an MFA challenge code to the given factor (public). For `totp` nothing is sent — it tells the server the code will come from their authenticator app; then {@link mfaChallengeVerify}.
 
 **mfaChallengeVerify**(clientId: string, mfaSessionToken: string, code: string, trustDevice?: boolean, deviceLabel?: string) → `Promise<MfaFinalizeResponse>`
 Verify an MFA challenge code and finalize the login (public). On success this behaves like {@link login} — the bearer token is adopted and the cache invalidated. it and pass it to future {@link login} calls to skip the challenge on this device.
@@ -11315,10 +11368,16 @@ Begin SMS-factor enrollment; sends a code to the given phone number (authenticat
 **confirmSmsMfa**(clientId: string, mfaSessionToken: string, code: string) → `Promise<MfaEnrolledResponse>`
 Confirm SMS-factor enrollment with the code sent by {@link enrollSmsMfa} (authenticated).
 
+**enrollTotpMfa**(clientId: string) → `Promise<MfaTotpEnrollResponse>`
+Begin authenticator-app enrollment (authenticated): a new secret for Google Authenticator, Microsoft Authenticator, 1Password and the like. Show `otpauthUri` as a QR code (and `secret` for typing in), then {@link confirmTotpMfa} with the code the app shows. Nothing is kept until then; setting up again replaces the previous app once confirmed.
+
+**confirmTotpMfa**(clientId: string, mfaSessionToken: string, code: string) → `Promise<MfaEnrolledResponse>`
+Confirm authenticator-app enrollment with the 6-digit code the app shows (authenticated).
+
 **generateMfaRecoveryCodes**(clientId: string, password: string) → `Promise<`
 Generate a fresh set of recovery codes, invalidating any previous set (authenticated). Returned **in plaintext, exactly once** — nothing else in the API ever returns them again, so the caller must display/export them immediately.
 
-**removeMfaFactor**(clientId: string, factor: 'email' | 'sms', password: string) → `Promise<SuccessResponse>`
+**removeMfaFactor**(clientId: string, factor: MfaFactor, password: string) → `Promise<SuccessResponse>`
 Remove an enrolled MFA factor (authenticated). Server route is DELETE with a body.
 
 **listTrustedDevices**(clientId: string) → `Promise<`
@@ -11345,8 +11404,11 @@ Update an AuthKit client config (admin). This is how the account **security poli
 **setIdentity**(collectionId: string, authKitId: string, body: { mode: 'own' }) → `Promise<AuthKitSetIdentityResponse>`
 Give this AuthKit its **own logins** (admin): its members become accounts of this site only — the same email can be a separate account, with its own password, on another site — rather than SmartLinks accounts shared across sites. One way: a site with its own members can't go back to the shared pool. Members who signed up before keep their SmartLinks account until moved across. Errors: `MEMBER_POOL_CONFLICT` (409) when another AuthKit already gives one of its collections its own logins (one per collection); `PERMISSION_DENIED` (403) unless you administer every collection it serves.
 
+**invite**(collectionId: string, authKitId: string, body: AuthKitInviteRequest) → `Promise<AuthKitInviteResponse>`
+Invite someone to be a member of a site with its own logins (admin). Makes their account if they have none (the only way in when the site is invitation only — `signUp: 'invite'`), finds or creates their contact in this collection with the `customFields` you pass (their level), links the two, and emails them a sign-in link to the site (`redirectUrl`, default the kit's) that works once for 7 days. The page it opens handles it like any magic link: `mode=magicLink&token=…` → {@link verifyMagicLink}. Inviting someone again sends a fresh link. Errors: `OWN_LOGINS_REQUIRED` (409), `INVALID_EMAIL` (400), `INVALID_REDIRECT_URL` (400, not one of this site's addresses), `TOO_MANY_INVITES` (429, 5 an hour per address).
+
 **remove**(collectionId: string, authKitId: string) → `Promise<void>`
-Give this AuthKit its **own logins** (admin): its members become accounts of this site only — the same email can be a separate account, with its own password, on another site — rather than SmartLinks accounts shared across sites. One way: a site with its own members can't go back to the shared pool. Members who signed up before keep their SmartLinks account until moved across. Errors: `MEMBER_POOL_CONFLICT` (409) when another AuthKit already gives one of its collections its own logins (one per collection); `PERMISSION_DENIED` (403) unless you administer every collection it serves.
+Invite someone to be a member of a site with its own logins (admin). Makes their account if they have none (the only way in when the site is invitation only — `signUp: 'invite'`), finds or creates their contact in this collection with the `customFields` you pass (their level), links the two, and emails them a sign-in link to the site (`redirectUrl`, default the kit's) that works once for 7 days. The page it opens handles it like any magic link: `mode=magicLink&token=…` → {@link verifyMagicLink}. Inviting someone again sends a fresh link. Errors: `OWN_LOGINS_REQUIRED` (409), `INVALID_EMAIL` (400), `INVALID_REDIRECT_URL` (400, not one of this site's addresses), `TOO_MANY_INVITES` (429, 5 an hour per address).
 
 ### batch
 

package/dist/docs/auth-kit.md

@@ -305,11 +305,16 @@ clearPersistedTokens();
 
 ---
 
-## Step-up MFA (Phase 1)
+## Step-up MFA
 
-Backend-only for now — **no admin-console UI and no challenge UI ship with this pass.**
-Factors: **email OTP, SMS OTP, recovery codes**. WhatsApp OTP, TOTP, and passkeys as
-*factors* are deferred to a later phase; don't build against them yet.
+Factors: **email code, SMS code, authenticator app (`totp`), recovery codes**. The shared login UI
+(`@proveanything/smartlinks-auth-ui`) has the challenge and the Settings → Security screens. WhatsApp
+codes and passkeys are planned; don't build against them yet.
+
+**Authenticator apps** (Google Authenticator, Microsoft Authenticator, 1Password, Authy…) are the
+recommended second step: nothing is sent (no SMS cost, nothing to intercept), and they are offered first
+when someone has one. A client can switch any factor off with `mfa.factorsEnabled` (e.g.
+`{ totp: false }`).
 
 The step-up gate applies to **every login method that issues a session**:
 
@@ -408,15 +413,25 @@ await authKit.confirmEmailMfa(clientId, mfaSessionToken, code);
 const { mfaSessionToken: smsToken } = await authKit.enrollSmsMfa(clientId, '+61400000000');
 await authKit.confirmSmsMfa(clientId, smsToken, code);
 
+// Enroll an authenticator app: show otpauthUri as a QR code (and secret for typing in),
+// then confirm with the 6-digit code the app shows
+const { mfaSessionToken: appToken, otpauthUri, secret } = await authKit.enrollTotpMfa(clientId);
+await authKit.confirmTotpMfa(clientId, appToken, codeFromApp);
+
 // Recovery codes — plaintext, shown exactly once; nothing else in the API returns them again
 const { recoveryCodes } = await authKit.generateMfaRecoveryCodes(clientId, password);
 
 // Inspect / remove
 const factors = await authKit.getMfaFactors(clientId);
-// factors: { enrolledFactors: { email?, sms? }, recoveryCodesRemaining, mfaEnabledForClient }
+// factors: { enrolledFactors: { email?, sms?, totp? }, recoveryCodesRemaining, mfaEnabledForClient }
 await authKit.removeMfaFactor(clientId, 'sms', password);
 ```
 
+At sign-in, `MFA_REQUIRED` lists `availableFactors` with `preferredFactor` (`totp`, then `sms`, then
+`email`). For `totp`, `mfaChallengeSend(clientId, token, 'totp')` sends nothing; it just says the code
+comes from the app. Then call `mfaChallengeVerify` with that code, as for the others. Each authenticator
+code works once. The secret is sealed on the server and never returned after `enrollTotpMfa`.
+
 > Enrollment endpoints don't currently check the client's `mfa.mode` — enrolling is possible
 > even when MFA is configured `'off'` for a client. Those factors simply won't be challenged
 > at login until an admin turns the mode on (via the existing admin AuthKit config update,
@@ -633,6 +648,31 @@ await authKit.setIdentity(collectionId, authKitId, { mode: 'own' })
   resets) works the same way; nothing changes in the login UI or your code.
 - `identity` is read-only on `create` / `update`; it is shown on the config (`authKit.get`).
 
+### Invitation only
+
+A site with its own logins can let in only the people it invites:
+
+```ts
+await authKit.update(collectionId, authKitId, { signUp: 'invite' })   // 'open' (default) | 'invite'
+await authKit.invite(collectionId, authKitId, { email: 'jo@example.com', firstName: 'Jo', customFields: { level: 'member' } })
+```
+
+- **Enforced on the server, for every route.** Nobody without an account can get one: `register`,
+  `verifyMagicLink`, `verifyPhoneCode`, Google, Apple, LinkedIn and WhatsApp answer `SIGN_UP_CLOSED`
+  (403). `sendMagicLink` and `sendPhoneCode` answer as if sent, but send nothing to someone who isn't a
+  member, so nobody can find out who is.
+- **`invite`** makes the person's account if they have none, finds or creates their contact in that
+  collection with the fields you pass, links the two, and emails a sign-in link to the site (`redirectUrl`,
+  default the kit's) that works once for 7 days. It lands like any magic link (`mode=magicLink&token=…`).
+  Inviting someone again sends a fresh link. The link is never returned to the admin.
+- **Invited members then sign in any way the site offers.** A magic link, "forgot password" to set a
+  password, or Google/Apple/LinkedIn with the same verified email: an invited account nobody has signed
+  in to yet can be claimed that way.
+- `signUp` is on the public config (`load`): hide "Create an account" when it's `invite`. Setting it
+  needs own logins first (`OWN_LOGINS_REQUIRED`, 409).
+- On any site, a member signing in with a verified email or phone is attached to the contact the
+  collection already has for it, so fields the staff set beforehand (a level) are theirs.
+
 ## Relationship to other parts of the SDK
 
 | Concern | Where it lives |
@@ -646,5 +686,6 @@ await authKit.setIdentity(collectionId, authKitId, { mode: 'own' })
 
 ## Further reading
 
+- [members.md](members.md) — members with a level: clubs, leagues, members-only content
 - [app-data-storage.md](app-data-storage.md) — storing user-specific data after login
 - [app-manifest.md](app-manifest.md) — `app.admin.json` setup questions for configuring `clientId`

package/dist/docs/members.md

@@ -0,0 +1,182 @@
+# Members: signed-in people with a level
+
+A club, a league, a wine club, a members' area. SmartLinks has **no separate "membership" object**,
+and you don't need one:
+
+| Piece | Where it lives |
+|---|---|
+| A member's login | The **auth kit**: the site's own logins (auth-kit.md → "Own logins") |
+| The member | Their **contact** (one per person, created when they sign in or fill in a form) |
+| What they are (gold, silver, junior, pending) | A **contact custom field**, e.g. `customFields.level` |
+| Who may see or change it | The contact field's **public** setting: hidden, visible or editable |
+| Members-only content | A **server function** that checks the level, then returns the content |
+| Managing members | **Studio → Customers**: find people, set their level, email a segment |
+
+**The contract: whoever manages membership writes the member's `level` field.** That can be the owner
+by hand in Studio, a memberships app after a payment, or a connector syncing a club's existing system.
+The site only ever reads the field, so the way people become members can change without rebuilding
+the site.
+
+---
+
+## Questions to settle first
+
+Ask these before building, because they change what you build:
+
+1. **Who can join?** Anyone; anyone, but the club confirms them; or **only people the club invites**
+   (no sign-up at all)?
+2. **Who sets the level?** The owner (people sign up, then the owner confirms them), or the person
+   themselves? Let people choose only a level that unlocks nothing, like "junior / adult".
+3. **What does each level get?** Pages, results, discounts, early access, booking.
+4. **Fees?** If the club takes payment by hand, the owner sets the level once they've been paid. Paying
+   on the site is a memberships app's job. Never take card details in a site.
+5. **Do members see each other?** A members' directory needs consent: a "show me in the directory"
+   field the member sets themselves.
+
+---
+
+## 1. Sign-in: the site's own logins
+
+- A site's members sign in through its auth kit. The collection's kit is `collection.defaultAuthKitId`
+  (`SL.collection.get(collectionId)`).
+- A club should have **its own logins**, so its members are accounts of this site only. In Forge: the
+  Site tab → Members → "Set up member sign-in" (or "Use my own members" on a site that has the shared
+  login). That creates the kit if needed, makes it the site's, and switches it to its own members.
+- Use the flows in auth-kit.md: register, login, magic link, Google, password reset, email verification.
+  Never build a login of your own, and never store passwords.
+- On sign-in, the SDK keeps the member's session (`setBearerToken`). Persist `session.token`
+  (respect `rememberMe`), restore it on load with `SL.setBearerToken(token)`, and clear it on sign-out.
+
+By default anyone can create a login, and **being a member is the level, not the login**: an approval
+club is just "signed in, no level yet".
+
+**Invitation only.** A site with its own logins can turn sign-up off: `SL.authKit.update(collectionId,
+authKitId, { signUp: 'invite' })` (or the owner, in the Customer Login app: Members → Who can join). Then nobody can
+create an account by any route: password, magic link, phone, Google and the rest refuse with
+`SIGN_UP_CLOSED`, and "email me a link" answers the same for strangers without sending anything. The
+site's admins invite people instead:
+
+```ts
+// admin session (the site's admin page, Studio): their account, their contact with a level, and an email
+await SL.authKit.invite(collectionId, authKitId, {
+  email: "jo@example.com", firstName: "Jo",
+  customFields: { level: "member" },
+  redirectUrl: "https://club.example.com/sign-in", // the site's sign-in page (one of its own addresses)
+})
+```
+
+The email's link works once for 7 days and opens the sign-in page with `mode=magicLink&token=…`: handle
+it with `SL.authKit.verifyMagicLink(clientId, token)`, as for any magic link. After that the member
+signs in however the site offers (a magic link to their email, "forgot password" to set one, Google
+with the same email). Build the sign-in page with no "Create an account" option when the kit's
+`signUp` is `invite` (it's on the public config, `SL.authKit.load(authKitId)`), and say "Members only.
+Ask the club for an invitation."
+
+**Added by the staff first?** When someone signs in with a verified email or phone, their login is
+attached to the contact the site already has for it: an invite, someone the staff added in Studio, a
+form they filled in. So the level set on that contact is theirs from the first sign-in.
+
+## 2. The level field
+
+In a **website**, contact fields are part of its cloud blueprint (`cloud/contacts.json`, applied with
+`forge-cloud`):
+
+```json
+{
+  "fields": {
+    "level": { "title": "Membership", "type": "string", "enum": ["pending", "member", "gold"], "public": "visible" },
+    "memberUntil": { "title": "Member until", "type": "date", "public": "visible" },
+    "showInDirectory": { "title": "Show me in the members' list", "type": "boolean", "public": "editable" }
+  }
+}
+```
+
+| `public` | Member can see it | Member can change it | Use for |
+|---|---|---|---|
+| `hidden` (default) | no | no | Staff notes, a paid-until the member shouldn't see |
+| `visible` | yes | **no** | **The level**, an expiry date |
+| `editable` | yes | yes | Preferences and consent the member owns |
+
+A member's own reads and writes (`SL.contact.publicGetMine`, `SL.contact.publicUpdateMine`) and public
+forms follow these settings on the server, so a `visible` level can't be changed from the browser.
+
+Outside a website (a plain app), the same settings live in the collection's `contactCustomFields`
+(field definitions, a SchemaFormConfig) and `contacts` settings groups (`publicVisibleFields`,
+`publicEditableFields`, paths like `customFields.level`). Those lists replace what's stored: read
+them, add to them, and write back the whole list, defaults included. Prefer letting the owner set
+fields up in Studio → Customers.
+
+## 3. Showing members their status
+
+```ts
+const me = await SL.contact.publicGetMine(collectionId) // needs the member's session
+// me.contact?.customFields?.level → "gold"; only fields the member may see are returned
+```
+
+Use it for the "My membership" page and to decide what to **show**. It is not a lock: anything
+members-only must come from a server function.
+
+## 4. Members-only content: check in a server function
+
+```ts
+// visibility: public, authority: collection, elevated: true
+// capabilities: sl:contacts:write (forCaller), sl:records:read
+export async function memberNews(ctx, event) {
+  const me = await ctx.sl.contacts.forCaller() // null when signed out
+  if (!me) return { ok: false, reason: "sign-in" }
+  const level = me.customFields.level
+  if (level !== "member" && level !== "gold") return { ok: false, reason: "not-a-member" }
+  const until = me.customFields.memberUntil
+  if (until && String(until) < new Date().toISOString().slice(0, 10)) return { ok: false, reason: "expired" }
+  const news = await ctx.sl.appRecords.query({ recordType: "member-news" })
+  return { ok: true, level, news } // never return me.contactId or staff-only fields
+}
+```
+
+- `forCaller()` returns the member's contact with its tags and **all** custom fields, staff-only ones
+  included. Decide with them and return only what the member may see.
+- A site's `callFunction` sends the member's session with the call. Without it, the function sees an
+  anonymous caller. Check that `src/site/lib/call-function.ts` adds `authorization: Bearer <token>`
+  from `sl().getBearerToken()`; older sites may need it added.
+- Do the same check in every function that acts for members: booking a court, entering a result,
+  claiming a discount.
+
+## 5. Joining rules
+
+| Club | How it works |
+|---|---|
+| **Open** (sign up = member) | Signed in is enough; no level needed, or a `level` the site never gates on |
+| **Approval** ("sign up and I'll add you") | Anyone signs up; the owner sets `level` in Studio → Customers; until then the site says "We'll confirm your membership" |
+| **Invite only** (no sign-up) | `signUp: 'invite'`; the owner invites people with their level (`SL.authKit.invite`): the Customer Login app's Members card, or an "Invite a member" screen on the site's admin page; the sign-in page has no sign-up |
+| **Tiers** (silver, gold) | `level` with an `enum`; each gated function lists the levels it allows |
+| **Paid** | By hand: the owner sets `level` (and `memberUntil`) once paid. Online: a memberships app or connector writes the same fields after payment |
+
+Record joining as an interaction (`ctx.sl.interactions.record`, e.g. `member-joined`), and a
+`cloud/flows.json` flow can welcome the member and tell the team someone is waiting for approval.
+
+## 6. The owner's side
+
+- **Studio → Customers**: everyone who signed up, their level, and when they joined. Filter by level
+  and set it on the contact.
+- **Inviting**: the Customer Login app's Members card (Who can join, Invite a member), or the site's own
+  admin screen calling `SL.authKit.invite`; inviting someone again sends a fresh link.
+- **Email a level**: a segment on `customFields.level`, sent from Studio (comms.md).
+- **Tags** suit many-valued labels (`committee`, `coach`); a member has one `level`.
+
+## Don't
+
+- Keep members in app records, a table of your own, or the site's code. The contact is the member.
+- Trust the browser's idea of the level. Check it in a server function.
+- Let a member set a level that unlocks anything (`public: "editable"`).
+- Return contact ids, other members' details, or staff-only fields to the browser.
+- Build payments into a site. A memberships app or connector owns fees.
+- Hide the sign-up button and call that invitation only. Set `signUp: 'invite'`, so the server refuses.
+
+## Example: a tennis box league
+
+- **Players** are members: own logins, `level` = `pending` or `player`, set by the organiser.
+- **Fixtures, results and standings** are a custom app's records.
+- Only a `player` can enter a result: the function checks `forCaller()`, then that the player is in
+  that fixture.
+- **Standings** are public; contact details stay hidden.
+- **New player signs up**: the flow emails the organiser, who sets them to `player` in Studio.