@proveanything/smartlinks 1.15.17 → 1.15.19

package/dist/docs/proof-share-grants.md

@@ -0,0 +1,232 @@
+# Proof Share Grants
+
+Delegated, scoped, **revocable** bearer access to a single proof — the middle tier
+between "public" (everyone) and "owner" (only the signed-in owner).
+
+A grant lets an owner hand out a link that lets specific recipients **see or do
+specific things on one proof for a limited time**, without those recipients needing
+a SmartLinks account or a proof claim. Typical uses: sharing a private photo album,
+letting guests comment on it, or publishing a verifiable "I own this" assertion.
+
+---
+
+## Concepts
+
+A **grant** is a row issued by the proof owner (or a collection admin) and redeemed
+by a bearer holding an opaque token. Every data request that touches the proof
+re-checks the grant **server-side** against the database, so revocation is immediate.
+
+### Scopes — what a grant authorises
+
+| Scope | Grants the bearer… |
+|-------|--------------------|
+| `read` | read owner-tier data on the proof (attestations, threads, records, cases) |
+| `comment` | create threads/replies on the proof (guest comments) |
+| `admin` | read owner-tier data (reserved for elevated share cases; never exposes the platform admin zone) |
+| `verify_owner` | redeem a shareable ownership **assertion** (not the account) |
+
+A grant can carry several scopes, e.g. `['read', 'comment']` for a shareable,
+commentable album.
+
+### Security & lifecycle
+
+- The token is opaque, unguessable, and returned to the issuer **exactly once** (on `createGrant`). It is never returned by `listGrants`.
+- **Revocation is immediate** — the grant is re-checked on every request, so `revokeGrant` invalidates a token across all clients at once.
+- **Auto-invalidation on transfer** — every grant is voided the moment the proof's `ownerId` changes (e.g. a resale/re-claim), so a stale "I own this" link cannot keep resolving.
+- A grant is scoped to **one proof**; it can never widen access to other proofs or collection-level data.
+
+---
+
+## Owner flow — create, list, revoke
+
+```typescript
+import { proof } from '@proveanything/smartlinks'
+
+// Create a read+comment grant that expires in 7 days.
+const grant = await proof.createGrant(collectionId, productId, proofId, {
+  scope: ['read', 'comment'],
+  audience: { kind: 'public_link' },
+  expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
+})
+
+// `grant.token` is available ONLY here — embed it in your share link now.
+const shareUrl = `https://app.example.com/album?proofId=${proofId}&shareToken=${grant.token}`
+
+// List active + past grants (tokens are never included).
+const grants = await proof.listGrants(collectionId, productId, proofId)
+
+// Stop sharing — takes effect on the very next request from any client.
+await proof.revokeGrant(collectionId, productId, proofId, grant.grantId)
+```
+
+`createGrant` / `listGrants` / `revokeGrant` require the caller to be the **proof
+owner** (or a collection admin) — i.e. a signed-in user whose `bearerToken` is set.
+
+---
+
+## Recipient flow — redeem, then carry the token
+
+A recipient opens the share link, redeems the token once, then sets it as the
+active grant token. From then on **every** SDK request carries the token
+(`X-Grant-Token`), so all proof reads/writes are evaluated against the grant.
+
+```typescript
+import { proof, setGrantToken } from '@proveanything/smartlinks'
+
+const shareToken = new URLSearchParams(location.search).get('shareToken')!
+
+// Redeem once (anonymous or signed-in). Records the redemption; optionally names the guest.
+await proof.redeemGrant(collectionId, productId, proofId, shareToken, {
+  guestName: 'Sam',            // stamped on guest activity when not signed in
+})
+
+// Attach the token to every subsequent request.
+setGrantToken(shareToken)
+
+// Now grant-tier reads succeed — e.g. owner-visibility memories on the proof:
+const { attestations } = await attestation.publicList(collectionId, {
+  subjectType: 'proof', subjectId: proofId,
+})
+
+// Clear it when leaving the shared view:
+setGrantToken(undefined)
+```
+
+> **Persisting across reloads.** `setGrantToken` holds the token in memory. To keep a
+> shared session across reloads, persist `shareToken` yourself (e.g. in `localStorage`)
+> and call `setGrantToken` again on load.
+
+---
+
+## Guest commenting
+
+With a `comment` scope grant, a bearer can post comments even when they are not
+signed in. The app must enable the **grant branch** of the thread create policy
+(see [App config](#app-config)); comments are then created at `visibility: 'owner'`
+(private to the proof) and stamped `authorType: 'guest'`.
+
+```typescript
+import { app } from '@proveanything/smartlinks'
+// setGrantToken(shareToken) has already been called.
+
+// One atomic call — no separate create-then-reply round trip.
+await app.threads.create(collectionId, 'photo-memory', {
+  parentType: 'memory',
+  parentId: memoryId,          // text — SmartLinks short ids are fine (not just UUIDs)
+  proofId,                     // anchor to the proof so grant readers see it
+  firstReply: { text: 'Lovely photo', authorName: 'Sam' },
+})
+```
+
+Other grant holders (and the owner) see these comments because a `read` grant reveals
+`owner`-visibility threads for the proof. See
+[App Objects → Threads](app-objects.md#threads) for the full threads API.
+
+---
+
+## Proof of ownership — `verify_owner`
+
+Ownership itself is **not** a grant — it is `proof.ownerId`, established via the
+existing [claim flow](proof-claiming-methods.md). A `verify_owner` grant only
+publishes a shareable, verifiable **assertion** derived from that ownership, without
+handing over the account:
+
+```typescript
+const grant = await proof.createGrant(collectionId, productId, proofId, {
+  scope: ['verify_owner'],
+})
+
+// The recipient redeems it and gets the assertion — never the account:
+const result = await proof.redeemGrant(collectionId, productId, proofId, grant.token)
+// { proofId, assertsOwnership: true, ownerDisplayName?, issuedAt, expiresAt }
+```
+
+Because grants auto-invalidate on transfer, a resale cannot leave a stale
+"I own this" link in circulation.
+
+---
+
+## What a grant gates
+
+When a valid grant token is present, these public reads elevate to owner-tier for the
+granted proof (and only that proof):
+
+- **Attestations** — `attestation.publicList({ subjectType: 'proof', subjectId })`
+- **Threads / Records / Cases** — `app.threads.list`, `app.records.*`, `app.cases.list`, and the single-item GETs, filtered to the granted proof
+- **Thread creation / replies** — with a `comment` scope grant (see below)
+
+The token never exposes the platform `admin` zone, and only reveals `owner`-visibility
+rows for the granted `proofId`.
+
+---
+
+## App config
+
+Grant-based commenting is opt-in per app, configured on the app's Firestore config
+at `sites/{collectionId}/apps/{appId}` — a `grant` branch alongside
+`anonymous` / `authenticated`:
+
+```jsonc
+{
+  "publicCreate": {
+    "threads": {
+      "grant": {
+        "allow": true,
+        "requireScope": "comment",
+        "enforce": { "visibility": "owner", "status": "open" }
+      }
+    }
+  }
+}
+```
+
+This enables grant-scoped commenting **without** opening up anonymous creation. The
+`enforce.visibility: "owner"` keeps comments private to the proof (visible to the
+owner and other grant holders, not the wider public).
+
+---
+
+## API reference
+
+```typescript
+namespace proof {
+  createGrant(collectionId, productId, proofId, options: CreateGrantOptions): Promise<ProofGrant>
+  listGrants(collectionId, productId, proofId): Promise<ProofGrant[]>
+  revokeGrant(collectionId, productId, proofId, grantId): Promise<void>
+  redeemGrant(collectionId, productId, proofId, token, options?: RedeemGrantOptions): Promise<RedeemGrantResult>
+}
+
+// Attach / clear the active grant token (sent as X-Grant-Token on every request).
+function setGrantToken(token: string | undefined): void
+function getGrantToken(): string | undefined
+
+type GrantScope = 'read' | 'comment' | 'admin' | 'verify_owner'
+
+interface CreateGrantOptions {
+  scope: GrantScope[]                                   // at least one
+  audience?: { kind: 'public_link' } | { kind: 'named'; email?: string; userId?: string }
+  expiresAt?: Date | string
+}
+
+interface RedeemGrantOptions { guestName?: string }
+
+type RedeemGrantResult =
+  | { scope: GrantScope[]; redeemedAt: string }
+  | { proofId: string; assertsOwnership: true; ownerDisplayName?: string; issuedAt?: string; expiresAt?: string }
+
+interface ProofGrant {
+  grantId: string
+  proofId: string
+  productId?: string | null
+  scope: GrantScope[]
+  audience: { kind: 'public_link' | 'named'; email?: string; userId?: string }
+  createdBy: string
+  expiresAt?: string | null
+  revokedAt?: string | null
+  redeemedBy?: { userId?: string; guestName?: string; redeemedAt: string }
+  redeemCount: number
+  createdAt: string
+  updatedAt: string
+  token?: string   // present ONLY on the createGrant response
+}
+```

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export type { AdditionalGtin, ISODateString, JsonPrimitive, JsonValue, ProductCr
 export type { TranslationLookupMode, TranslationContentType, TranslationQuality, TranslationItemStatus, TranslationContextValue, TranslationContext, TranslationLookupRequestBase, TranslationLookupSingleRequest, TranslationLookupBatchRequest, TranslationLookupRequest, TranslationLookupItem, TranslationLookupResponse, ResolvedTranslationItem, ResolvedTranslationResponse, TranslationHashOptions, TranslationResolveOptions, TranslationRecord, TranslationListParams, TranslationListResponse, TranslationUpdateRequest, } from "./types/translations";
 export type { FacetBucket, FacetDefinition, FacetDefinitionWriteInput, FacetGetParams, FacetListParams, FacetListResponse, FacetNamespaceListResponse, FacetQueryRequest, FacetQueryResponse, FacetValue, FacetValueDefinition, FacetValueGetParams, FacetValueListParams, FacetValueListResponse, FacetValueResponse, FacetValueWriteInput, PublicFacetListParams, } from "./types/facets";
 export type { Collection, CollectionResponse, CollectionCreateRequest, CollectionUpdateRequest, DomainTarget, HubAvailabilityResponse, } from "./types/collection";
-export type { Proof, ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, GrantScope, GrantAudience, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, } from "./types/proof";
+export type { Proof, ProofResponse, ProofWrite, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, GrantScope, GrantAudience, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult, } from "./types/proof";
 export type { QrShortCodeLookupResponse, } from "./types/qr";
 export type { ReverseTagLookupParams, ReverseTagLookupResponse, } from "./types/tags";
 export type { AdminMobileCapability, ActionableCapability, AdminMobileHostId, AdminMobileEvent, AdminMobileEventCallback, AdminMobileEventSubscriber, ScannerEventSubscriber, // @deprecated — use AdminMobileEventCallback
@@ -25,4 +25,4 @@ AdminMobileHostContext, AdminMobileComponentManifest, AdminMobileBundleManifest,
 MobileAdminBundleManifest, } from './mobile-admin/types';
 export { HostCapabilityUnavailableError, HostPermissionDeniedError, HostTimeoutError, } from './mobile-admin/errors';
 export type { NativeCapability, NativeFacade, ShareFacade, ClipboardFacade, HapticImpactStyle, HapticNotificationStyle, HapticsFacade, NetworkStatus, NetworkFacade, DeviceInfo, DeviceFacade, StorageFacade, QrScanOptions, QrFacade, AuthFacade, NfcReadResult, NfcFacade, RfidScanOptions, RfidFacade, EventsFacade, WebSourceMode, WebSourceConfig, WebSourceFacade, } from './native/types';
-export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, RefreshResponse, LogoutResponse, RefreshErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, } from './types/authKit';
+export type { AuthKitUser, UserProfile, ProfileUpdateData, UpdateProfileResponse, SuccessResponse, AuthLoginResponse, AppleLoginOptions, AuthKitErrorCode, RefreshResponse, LogoutResponse, RefreshErrorCode, MagicLinkSendResponse, MagicLinkVerifyResponse, PhoneSendCodeResponse, PhoneVerifyResponse, PasswordResetRequestResponse, VerifyResetTokenResponse, PasswordResetCompleteResponse, EmailVerificationActionResponse, EmailVerifyTokenResponse, VerifyStatus, WhatsAppReplyCta, WhatsAppReplyOptions, WhatsAppContactData, SendWhatsAppRequest, SendWhatsAppResponse, ExchangeWhatsAppSessionResponse, VerifyWhatsAppResponse, WhatsAppStatusResponse, SendSmsVerifyRequest, SendSmsVerifyResponse, VerifySmsResponse, UpsertContactRequest, UpsertContactResponse, AuthKitBrandingConfig, AuthKitConfig, AuthKitSecurityConfig, AuthKitPasswordPolicy, AuthKitSessionPolicy, AuthKitLockoutPolicy, PasswordPolicyErrorCode, LoginSecurityErrorCode, } from './types/authKit';

package/dist/openapi.yaml

@@ -8401,7 +8401,7 @@ paths:
     post:
       tags:
         - authKit
-      summary: Login with email + password (public).
+      summary: authKit.login
       operationId: authKit_login
       security: []
       parameters:
@@ -13941,6 +13941,23 @@ paths:
           required: false
           schema:
             type: string
+        - name: parentIds
+          in: query
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
+        - name: proofId
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: productId
+          in: query
+          required: false
+          schema:
+            type: string
         - name: tag
           in: query
           required: false
@@ -14182,6 +14199,52 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/ReplyInput"
+  /{zone}/collection/{collectionId}/app/{appId}/threads/{threadId}/reply/{replyId}:
+    delete:
+      tags:
+        - threads
+      summary: Delete a single reply from a thread by its reply id (moderation).
+      operationId: threads_deleteReply
+      security: []
+      parameters:
+        - name: zone
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: appId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: threadId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: replyId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AppThread"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
 components:
   securitySchemes:
     bearerAuth:
@@ -16967,6 +17030,8 @@ components:
         admin:
           type: object
           additionalProperties: true
+        firstReply:
+          $ref: "#/components/schemas/ReplyInput"
     UpdateThreadInput:
       type: object
       properties:
@@ -17012,6 +17077,14 @@ components:
           type: string
         parentId:
           type: string
+        parentIds:
+          type: array
+          items:
+            type: string
+        proofId:
+          type: string
+        productId:
+          type: string
         tag:
           type: string
         contactId:
@@ -19308,8 +19381,69 @@ components:
           type: string
         updatedAt:
           type: string
+        security:
+          $ref: "#/components/schemas/AuthKitSecurityConfig"
       required:
         - id
+    AuthKitSecurityConfig:
+      type: object
+      properties:
+        passwordPolicy:
+          $ref: "#/components/schemas/AuthKitPasswordPolicy"
+        session:
+          $ref: "#/components/schemas/AuthKitSessionPolicy"
+        lockout:
+          $ref: "#/components/schemas/AuthKitLockoutPolicy"
+    AuthKitPasswordPolicy:
+      type: object
+      properties:
+        minLength:
+          type: number
+        requireUppercase:
+          type: boolean
+        requireLowercase:
+          type: boolean
+        requireNumber:
+          type: boolean
+        requireSymbol:
+          type: boolean
+        blockCommonPasswords:
+          type: boolean
+        expiryDays:
+          type: number
+        historyCount:
+          type: number
+    AuthKitSessionPolicy:
+      type: object
+      properties:
+        inactivityTimeoutMinutes:
+          type: number
+        inactivityWarningSeconds:
+          type: number
+        absoluteTimeoutHours:
+          type: number
+        rememberMe:
+          type: boolean
+    AuthKitLockoutPolicy:
+      type: object
+      properties:
+        enabled:
+          type: boolean
+        maxFailedAttempts:
+          type: number
+        attemptWindowMinutes:
+          type: number
+        lockoutMinutes:
+          type: number
+        notifyUserOnLockout:
+          type: boolean
+    PasswordPolicyErrorCode:
+      type: string
+      enum:
+        - PASSWORD_TOO_SHORT
+        - PASSWORD_REQUIREMENTS_NOT_MET
+        - PASSWORD_TOO_COMMON
+        - PASSWORD_RECENTLY_USED
     FirebaseTimestamp:
       type: object
       properties:
@@ -24921,9 +25055,11 @@ components:
         - tokenId
         - userId
         - values
-    ProofCreateRequest:
+    ProofWrite:
       type: object
       properties:
+        id:
+          type: string
         values:
           $ref: "#/components/schemas/ProofValues"
         data:
@@ -24934,12 +25070,33 @@ components:
           type: object
           additionalProperties:
             $ref: "#/components/schemas/JsonValue"
+        owner:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
+        claimable:
+          type: boolean
+    ProofCreateRequest:
+      type: object
+      properties:
+        proof:
+          $ref: "#/components/schemas/ProofWrite"
+        values:
+          $ref: "#/components/schemas/ProofValues"
         claimable:
           type: boolean
         virtual:
           type: boolean
-      required:
-        - values
+        core:
+          $ref: "#/components/schemas/ProofWrite"
+        data:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
+        admin:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/JsonValue"
     ProofFieldsConfig:
       type: object
       properties:
@@ -25023,9 +25180,6 @@ components:
       properties:
         guestName:
           type: string
-    ProofResponse:
-      type: object
-      additionalProperties: true
     QrShortCodeLookupResponse:
       type: object
       properties:

package/dist/types/appObjects.d.ts

@@ -250,6 +250,12 @@ export interface CreateThreadInput {
     data?: Record<string, unknown>;
     owner?: Record<string, unknown>;
     admin?: Record<string, unknown>;
+    /**
+     * Optional atomic first reply. Posting a comment no longer needs a separate
+     * create-thread-then-reply round trip (which could orphan an empty thread on
+     * partial failure). The reply is stored with a generated `id` and timestamp.
+     */
+    firstReply?: ReplyInput;
 }
 /**
  * Input for updating a thread
@@ -279,8 +285,16 @@ export interface ReplyInput {
 export interface ThreadListQueryParams extends ListQueryParams {
     slug?: string;
     authorId?: string;
+    /** Disambiguates the parent entity kind (e.g. "memory", "case", "proof"). */
     parentType?: string;
+    /** Anchor to a single app entity id (text — SmartLinks short ids, not UUIDs). */
     parentId?: string;
+    /** Batch-fetch threads for many app entities in one call (e.g. a memory feed). */
+    parentIds?: string[];
+    /** Anchor threads to a proof. For grant-token callers this is the enforced filter. */
+    proofId?: string;
+    /** Anchor threads to a product (one tier up from proof). */
+    productId?: string;
     tag?: string;
     contactId?: string;
 }

package/dist/types/authKit.d.ts

@@ -89,8 +89,11 @@ export interface LogoutResponse {
  * - `INVALID_REFRESH_TOKEN` (401) — unknown / expired / revoked / wrong client → `logout()` + route to login.
  * - `REFRESH_TOKEN_REUSE_DETECTED` (401) — a consumed token was replayed; the **entire session
  *   family was revoked server-side**. Hard logout: clear storage, force re-login.
+ * - `SESSION_EXPIRED` (401) — the session hit the collection's absolute session timeout
+ *   (`security.session.absoluteTimeoutHours`). Clear storage and route to login. Distinct from
+ *   `INVALID_REFRESH_TOKEN` so the UI can message "your session expired" rather than an error.
  */
-export type RefreshErrorCode = 'MISSING_REFRESH_TOKEN' | 'INVALID_REFRESH_TOKEN' | 'REFRESH_TOKEN_REUSE_DETECTED';
+export type RefreshErrorCode = 'MISSING_REFRESH_TOKEN' | 'INVALID_REFRESH_TOKEN' | 'REFRESH_TOKEN_REUSE_DETECTED' | 'SESSION_EXPIRED';
 /**
  * Options for {@link authKit.appleLogin}. All fields are optional — only the
  * `identityToken` (passed as a positional argument) is required by the server.
@@ -397,4 +400,67 @@ export interface AuthKitConfig {
     supportEmail?: string;
     redirectUrl?: string;
     updatedAt?: string;
+    /**
+     * Per-collection security policy. On the public config endpoint only
+     * `passwordPolicy` + `session` are returned (the client renders password
+     * checklists / idle sign-out from them); `lockout` is admin-only and enforced
+     * server-side. See {@link AuthKitSecurityConfig}.
+     */
+    security?: AuthKitSecurityConfig;
+}
+/**
+ * Per-collection account-security policy. The API **enforces** all of this; the
+ * client uses `passwordPolicy` (live checklist) and `session` (idle sign-out) for UX.
+ */
+export interface AuthKitSecurityConfig {
+    passwordPolicy?: AuthKitPasswordPolicy;
+    session?: AuthKitSessionPolicy;
+    /** Admin-only; never returned on the public config endpoint. */
+    lockout?: AuthKitLockoutPolicy;
+}
+export interface AuthKitPasswordPolicy {
+    minLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumber?: boolean;
+    requireSymbol?: boolean;
+    blockCommonPasswords?: boolean;
+    /** 0 = never expires. */
+    expiryDays?: number;
+    /** 0 = reuse allowed. */
+    historyCount?: number;
+}
+export interface AuthKitSessionPolicy {
+    /** 0 = never (client-enforced idle sign-out). */
+    inactivityTimeoutMinutes?: number;
+    inactivityWarningSeconds?: number;
+    /** 0 = use token lifetime. Enforced server-side on the native refresh path (→ `SESSION_EXPIRED`). */
+    absoluteTimeoutHours?: number;
+    rememberMe?: boolean;
+}
+/** Admin-only lockout policy (operational; not exposed publicly). */
+export interface AuthKitLockoutPolicy {
+    enabled?: boolean;
+    maxFailedAttempts?: number;
+    attemptWindowMinutes?: number;
+    lockoutMinutes?: number;
+    notifyUserOnLockout?: boolean;
 }
+/**
+ * Password-policy validation errors (400) returned by `register`, `completePasswordReset`,
+ * and `changePassword`. Surfaced via `SmartlinksApiError.errorCode`.
+ * - `PASSWORD_TOO_SHORT` — below `passwordPolicy.minLength`.
+ * - `PASSWORD_REQUIREMENTS_NOT_MET` — missing a required character class.
+ * - `PASSWORD_TOO_COMMON` — matched the common/breached list.
+ * - `PASSWORD_RECENTLY_USED` — matched one of the last `historyCount` passwords.
+ */
+export type PasswordPolicyErrorCode = 'PASSWORD_TOO_SHORT' | 'PASSWORD_REQUIREMENTS_NOT_MET' | 'PASSWORD_TOO_COMMON' | 'PASSWORD_RECENTLY_USED';
+/**
+ * Security errors returned by `login`. Surfaced via `SmartlinksApiError.errorCode`,
+ * with extra fields in `SmartlinksApiError.details`:
+ * - `ACCOUNT_TEMPORARILY_LOCKED` (429) — too many failed attempts; `details.retryAfterSeconds`
+ *   says how long to wait. Show a "try again in N minutes" message.
+ * - `PASSWORD_EXPIRED` (403) — password older than `passwordPolicy.expiryDays`; `details.resetToken`
+ *   is a short-lived token — send the user straight into `completePasswordReset()` to change it in place.
+ */
+export type LoginSecurityErrorCode = 'ACCOUNT_TEMPORARILY_LOCKED' | 'PASSWORD_EXPIRED';

package/dist/types/proof.d.ts

@@ -40,16 +40,71 @@ export interface Proof {
     values: ProofValues;
 }
 export type ProofResponse = Proof;
-export interface ProofCreateRequest {
-    values: ProofValues;
-    /** Business-writable public spec data. */
+/**
+ * The proof's writable content, addressed by zone. Its keys mirror the proof
+ * document, so what you pass is what the proof looks like. Each zone has its own
+ * read/write visibility:
+ *
+ * | Zone     | Stored at      | Readable by            | Writable by   |
+ * |----------|----------------|------------------------|---------------|
+ * | `values` | `proof.values` | public + owner + admin | owner + admin |
+ * | `data`   | `proof.data`   | public + owner + admin | admin only    |
+ * | `admin`  | `proof.admin`  | admin only             | admin only    |
+ * | `owner`  | `proof.owner`  | admin only             | admin only    |
+ *
+ * Use `data` for business fields everyone should *see* but only the business
+ * should *set* (e.g. a serial number). Use `admin` for fields only the business
+ * should see at all. On update, object zones deep-merge.
+ */
+export interface ProofWrite {
+    /**
+     * Choose the proof's ID (serial, NFC id, etc.). Honoured **on create only** —
+     * the ledger doc becomes `{productId}-{id}`. Omit to auto-generate. Ignored on
+     * update (a proof's ID is immutable).
+     */
+    id?: string;
+    /** Owner + business-writable consumer data. Public + owner readable. → `proof.values` */
+    values?: ProofValues;
+    /** Business spec data (e.g. serialNo). Public + owner readable, admin-only writable. → `proof.data` */
     data?: Record<string, JsonValue>;
-    /** Business-only spec data. */
+    /** Business-only spec data — admin-only read & write (stripped from public + owner). → `proof.admin` */
     admin?: Record<string, JsonValue>;
+    /** Business-only root data — admin-only. → `proof.owner` */
+    owner?: Record<string, JsonValue>;
+    /** Is this proof available to be claimed. */
+    claimable?: boolean;
+    /** Any other named root field. */
+    [key: string]: JsonValue | Record<string, JsonValue> | ProofValues | undefined;
+}
+export interface ProofCreateRequest {
+    /**
+     * The proof to create, by zone (mirrors the proof document). This is the clear,
+     * recommended shape — `create(collectionId, productId, { proof: {...} })`.
+     */
+    proof?: ProofWrite;
+    /** Owner + business-writable consumer data (→ `proof.values`). Same as `proof.values`. */
+    values?: ProofValues;
+    /** Canonical root `claimable` flag (also accepted as `proof.claimable`). */
     claimable?: boolean;
     virtual?: boolean;
+    /** @deprecated Legacy alias for `proof`. Use `proof`. */
+    core?: ProofWrite;
+    /**
+     * @deprecated On the request body this is folded into the **values bag**
+     * (public + owner-writable) — NOT `proof.data`. Use `proof.data`.
+     */
+    data?: Record<string, JsonValue>;
+    /** @deprecated Not routed to `proof.admin` on create — use `proof.admin`. */
+    admin?: Record<string, JsonValue>;
 }
-export type ProofUpdateRequest = Partial<ProofCreateRequest>;
+/**
+ * Update passes the proof's fields **at the root** — `update(c, p, id, { data: {...} })`
+ * sets `proof.data`, `{ values: {...} }` sets `proof.values`, etc. (A `proof` block is
+ * also accepted and routed the same way.) Object zones deep-merge.
+ */
+export type ProofUpdateRequest = Partial<ProofWrite> & {
+    proof?: ProofWrite;
+};
 export type ProofClaimRequest = Record<string, any>;
 /**
  * `'public'` (default, omitted) reads/writes `proof.values[key]`.