@proveanything/smartlinks 1.15.17 → 1.15.19

package/README.md

@@ -22,6 +22,9 @@ If you're new to the SDK, this is the easiest path:
 
 - [docs/ai.md](docs/ai.md) — AI responses, chat, RAG, voice, streaming, and product assistants
 - [docs/analytics.md](docs/analytics.md) — fire-and-forget web analytics, tag scan telemetry, and dashboard queries
+- [docs/proof-share-grants.md](docs/proof-share-grants.md) — delegated, scoped, revocable share links for a proof (album sharing, guest comments, proof-of-ownership)
+- [docs/assets.md](docs/assets.md) — asset uploads, including resumable uploads for large files (video)
+- [docs/app-objects.md](docs/app-objects.md) — cases, threads (comments), and records
 - [docs/translations.md](docs/translations.md) — runtime translation lookup, browser-side caching, and translation admin flows
 - [docs/widgets.md](docs/widgets.md) — embeddable React components
 - [docs/realtime.md](docs/realtime.md) — subscriptions and live updates
@@ -33,17 +36,22 @@ If you're new to the SDK, this is the easiest path:
 - **Build an AI assistant** → start with [docs/ai.md](docs/ai.md)
 - **Track page views, clicks, or tag scans** → start with [docs/analytics.md](docs/analytics.md)
 - **Translate dynamic content with local browser caching** → start with [docs/translations.md](docs/translations.md)
+- **Share a proof / album by link, or add guest comments** → start with [docs/proof-share-grants.md](docs/proof-share-grants.md)
+- **Upload large video with resume-on-reconnect** → see [Resumable uploads](docs/assets.md#resumable-uploads-large-files-eg-video)
 - **Fetch collections/products** → see [Quick start](README.md#quick-start)
 - **Authenticate admins or end users** → see [Authentication](README.md#authentication)
 - **Upload and manage files** → see [Assets](README.md#assets)
-- **Browse the full surface area** → use [API_SUMMARY.md](API_SUMMARY.md) as reference
+- **Browse the full surface area** → use [API_SUMMARY.md](docs/API_SUMMARY.md) as reference
 
 For the full list of functions and types, see the API summary:
-→ [API Summary](API_SUMMARY.md)
+→ [API Summary](docs/API_SUMMARY.md)
 
 **Documentation:**
 - [AI & Chat Completions](docs/ai.md) - Chat completions, RAG, voice integration
 - [Analytics](docs/analytics.md) - Fire-and-forget analytics tracking, tag scans, and dashboard queries
+- [Proof Share Grants](docs/proof-share-grants.md) - Delegated, revocable share links; guest comments; proof-of-ownership
+- [Assets](docs/assets.md) - Uploads, resumable large-file uploads, token uploads, replace/versioning
+- [App Objects](docs/app-objects.md) - Cases, threads (comments), records
 - [Translations](docs/translations.md) - Runtime translation lookup, browser-side IndexedDB caching, and admin translation management
 - [Widgets](docs/widgets.md) - Embeddable React components
 - [Realtime](docs/realtime.md) - Realtime data updates

package/dist/api/appObjects.d.ts

@@ -85,6 +85,12 @@ export declare namespace app {
          * Atomically appends to replies array, increments replyCount, updates lastReplyAt
          */
         function reply(collectionId: string, appId: string, threadId: string, input: ReplyInput, admin?: boolean): Promise<AppThread>;
+        /**
+         * Delete a single reply from a thread by its reply id (moderation).
+         * DELETE /threads/:threadId/reply/:replyId
+         * Authorised for the reply's author, the proof owner, or a collection admin.
+         */
+        function deleteReply(collectionId: string, appId: string, threadId: string, replyId: string, admin?: boolean): Promise<AppThread>;
         /**
          * Get aggregate statistics for threads
          * POST /threads/aggregate

package/dist/api/appObjects.js

@@ -164,6 +164,16 @@ export var app;
             return post(path, input);
         }
         threads.reply = reply;
+        /**
+         * Delete a single reply from a thread by its reply id (moderation).
+         * DELETE /threads/:threadId/reply/:replyId
+         * Authorised for the reply's author, the proof owner, or a collection admin.
+         */
+        async function deleteReply(collectionId, appId, threadId, replyId, admin = false) {
+            const path = `${basePath(collectionId, appId, admin)}/${encodeURIComponent(threadId)}/reply/${encodeURIComponent(replyId)}`;
+            return del(path);
+        }
+        threads.deleteReply = deleteReply;
         /**
          * Get aggregate statistics for threads
          * POST /threads/aggregate

package/dist/api/authKit.d.ts

@@ -18,6 +18,11 @@ export declare namespace authKit {
      *   `trustDevice: true`), pass it here to skip the challenge entirely as long as it's
      *   still valid. If it's revoked/expired, the server silently falls back to requiring a
      *   fresh challenge — `login()` just returns `MFA_REQUIRED` again, no special handling.
+     *
+     * Security errors (thrown as `SmartlinksApiError`, see {@link LoginSecurityErrorCode}):
+     * - `ACCOUNT_TEMPORARILY_LOCKED` (429) — `err.details.retryAfterSeconds` says how long to wait.
+     * - `PASSWORD_EXPIRED` (403) — `err.details.resetToken` is short-lived; route into
+     *   {@link completePasswordReset} to change the password in place.
      */
     function login(clientId: string, email: string, password: string, trustedDeviceToken?: string): Promise<AuthLoginResponse>;
     /**
@@ -25,6 +30,11 @@ export declare namespace authKit {
      *
      * Not gated by step-up MFA — a brand-new user has no enrolled factors yet, so there's
      * nothing to challenge against.
+     *
+     * The new password is validated against the collection's `passwordPolicy` — may throw
+     * a {@link PasswordPolicyErrorCode} (400). The same validation applies to
+     * {@link completePasswordReset} and {@link changePassword}. Read the policy for a live
+     * checklist from `authKit.load(clientId)` → `config.security.passwordPolicy`.
      */
     function register(clientId: string, data: {
         email: string;

package/dist/api/authKit.js

@@ -22,6 +22,11 @@ export var authKit;
      *   `trustDevice: true`), pass it here to skip the challenge entirely as long as it's
      *   still valid. If it's revoked/expired, the server silently falls back to requiring a
      *   fresh challenge — `login()` just returns `MFA_REQUIRED` again, no special handling.
+     *
+     * Security errors (thrown as `SmartlinksApiError`, see {@link LoginSecurityErrorCode}):
+     * - `ACCOUNT_TEMPORARILY_LOCKED` (429) — `err.details.retryAfterSeconds` says how long to wait.
+     * - `PASSWORD_EXPIRED` (403) — `err.details.resetToken` is short-lived; route into
+     *   {@link completePasswordReset} to change the password in place.
      */
     async function login(clientId, email, password, trustedDeviceToken) {
         const body = { email, password };
@@ -40,6 +45,11 @@ export var authKit;
      *
      * Not gated by step-up MFA — a brand-new user has no enrolled factors yet, so there's
      * nothing to challenge against.
+     *
+     * The new password is validated against the collection's `passwordPolicy` — may throw
+     * a {@link PasswordPolicyErrorCode} (400). The same validation applies to
+     * {@link completePasswordReset} and {@link changePassword}. Read the policy for a live
+     * checklist from `authKit.load(clientId)` → `config.security.passwordPolicy`.
      */
     async function register(clientId, data) {
         return post(`/authkit/${encodeURIComponent(clientId)}/auth/register`, data);

package/dist/api/proof.d.ts

@@ -12,11 +12,34 @@ export declare namespace proof {
     /**
      * Create a proof for a product (admin only).
      * POST /admin/collection/:collectionId/product/:productId/proof
+     *
+     * Pass the proof's content in a `proof` block, keyed by zone (see {@link ProofWrite}):
+     * ```ts
+     * proof.create(collectionId, productId, {
+     *   proof: {
+     *     values: { colour: 'red' },   // public + owner readable, owner + admin writable
+     *     data:   { serialNo: 1001 },  // public + owner readable, ADMIN-only writable
+     *     admin:  { costPrice: 4.20 }, // admin-only
+     *   },
+     *   claimable: true,
+     * })
+     * ```
+     * Note: a top-level `data`/`admin` on the request body is legacy — top-level
+     * `data` gets folded into the values bag, so use `proof.data` for `proof.data`.
      */
-    function create(collectionId: string, productId: string, values: ProofCreateRequest): Promise<ProofResponse>;
+    function create(collectionId: string, productId: string, request: ProofCreateRequest): Promise<ProofResponse>;
     /**
      * Update a proof for a product (admin only).
      * PUT /admin/collection/:collectionId/product/:productId/proof/:proofId
+     *
+     * Pass the fields to change **at the root**, keyed by zone (see {@link ProofWrite}):
+     * ```ts
+     * proof.update(collectionId, productId, proofId, {
+     *   data:   { serialNo: 1002 },   // → proof.data (admin-only writable)
+     *   values: { colour: 'blue' },   // → proof.values
+     * })
+     * ```
+     * Object zones deep-merge, so you can change one field without wiping the rest.
      */
     function update(collectionId: string, productId: string, proofId: string, values: ProofUpdateRequest): Promise<ProofResponse>;
     /**

package/dist/api/proof.js

@@ -26,15 +26,38 @@ export var proof;
     /**
      * Create a proof for a product (admin only).
      * POST /admin/collection/:collectionId/product/:productId/proof
+     *
+     * Pass the proof's content in a `proof` block, keyed by zone (see {@link ProofWrite}):
+     * ```ts
+     * proof.create(collectionId, productId, {
+     *   proof: {
+     *     values: { colour: 'red' },   // public + owner readable, owner + admin writable
+     *     data:   { serialNo: 1001 },  // public + owner readable, ADMIN-only writable
+     *     admin:  { costPrice: 4.20 }, // admin-only
+     *   },
+     *   claimable: true,
+     * })
+     * ```
+     * Note: a top-level `data`/`admin` on the request body is legacy — top-level
+     * `data` gets folded into the values bag, so use `proof.data` for `proof.data`.
      */
-    async function create(collectionId, productId, values) {
+    async function create(collectionId, productId, request) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}/proof`;
-        return post(path, values);
+        return post(path, request);
     }
     proof.create = create;
     /**
      * Update a proof for a product (admin only).
      * PUT /admin/collection/:collectionId/product/:productId/proof/:proofId
+     *
+     * Pass the fields to change **at the root**, keyed by zone (see {@link ProofWrite}):
+     * ```ts
+     * proof.update(collectionId, productId, proofId, {
+     *   data:   { serialNo: 1002 },   // → proof.data (admin-only writable)
+     *   values: { colour: 'blue' },   // → proof.values
+     * })
+     * ```
+     * Object zones deep-merge, so you can change one field without wiping the rest.
      */
     async function update(collectionId, productId, proofId, values) {
         const path = `/admin/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}/proof/${encodeURIComponent(proofId)}`;

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.17  |  Generated: 2026-08-18T08:10:50.608Z
+Version: 1.15.19  |  Generated: 2026-08-20T18:06:08.134Z
 
 This is a concise summary of all available API functions and types.
 
@@ -1993,6 +1993,10 @@ interface CreateThreadInput {
   data?: Record<string, unknown>
   owner?: Record<string, unknown>
   admin?: Record<string, unknown> // admin only
+  * 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
 }
 ```
 
@@ -3460,6 +3464,55 @@ 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
+}
+```
+
+**AuthKitSecurityConfig** (interface)
+```typescript
+interface AuthKitSecurityConfig {
+  passwordPolicy?: AuthKitPasswordPolicy
+  session?: AuthKitSessionPolicy
+  lockout?: AuthKitLockoutPolicy
+}
+```
+
+**AuthKitPasswordPolicy** (interface)
+```typescript
+interface AuthKitPasswordPolicy {
+  minLength?: number
+  requireUppercase?: boolean
+  requireLowercase?: boolean
+  requireNumber?: boolean
+  requireSymbol?: boolean
+  blockCommonPasswords?: boolean
+  expiryDays?: number
+  historyCount?: number
+}
+```
+
+**AuthKitSessionPolicy** (interface)
+```typescript
+interface AuthKitSessionPolicy {
+  inactivityTimeoutMinutes?: number
+  inactivityWarningSeconds?: number
+  absoluteTimeoutHours?: number
+  rememberMe?: boolean
+}
+```
+
+**AuthKitLockoutPolicy** (interface)
+```typescript
+interface AuthKitLockoutPolicy {
+  enabled?: boolean
+  maxFailedAttempts?: number
+  attemptWindowMinutes?: number
+  lockoutMinutes?: number
+  notifyUserOnLockout?: boolean
 }
 ```
 
@@ -3471,6 +3524,10 @@ interface AuthKitConfig {
 
 **VerifyStatus** = `'pending' | 'verified' | 'failed' | 'expired' | 'unknown'`
 
+**PasswordPolicyErrorCode** = ``
+
+**LoginSecurityErrorCode** = ``
+
 ### batch
 
 **FirebaseTimestamp** (interface)
@@ -7275,14 +7332,36 @@ interface Proof {
 }
 ```
 
-**ProofCreateRequest** (interface)
+**ProofWrite** (interface)
 ```typescript
-interface ProofCreateRequest {
-  values: ProofValues
+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
+  values?: ProofValues
   data?: Record<string, JsonValue>
   admin?: Record<string, JsonValue>
+  owner?: Record<string, JsonValue>
+  claimable?: boolean
+  [key: string]: JsonValue | Record<string, JsonValue> | ProofValues | undefined
+}
+```
+
+**ProofCreateRequest** (interface)
+```typescript
+interface ProofCreateRequest {
+  * The proof to create, by zone (mirrors the proof document). This is the clear,
+  * recommended shape — `create(collectionId, productId, { proof: {...} })`.
+  proof?: ProofWrite
+  values?: ProofValues
   claimable?: boolean
   virtual?: boolean
+  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>
+  admin?: Record<string, JsonValue>
 }
 ```
 
@@ -7339,7 +7418,7 @@ interface RedeemGrantOptions {
 
 **ProofResponse** = `Proof`
 
-**ProofUpdateRequest** = `Partial<ProofCreateRequest>`
+**ProofUpdateRequest** = `Partial<ProofWrite> & { proof?: ProofWrite }`
 
 **ProofClaimRequest** = `Record<string, any>`
 
@@ -8435,6 +8514,13 @@ Soft delete a thread DELETE /threads/:threadId
     admin: boolean = false) → `Promise<AppThread>`
 Add a reply to a thread POST /threads/:threadId/reply Atomically appends to replies array, increments replyCount, updates lastReplyAt
 
+**deleteReply**(collectionId: string,
+    appId: string,
+    threadId: string,
+    replyId: string,
+    admin: boolean = false) → `Promise<AppThread>`
+Delete a single reply from a thread by its reply id (moderation). DELETE /threads/:threadId/reply/:replyId Authorised for the reply's author, the proof owner, or a collection admin.
+
 **aggregate**(collectionId: string,
     appId: string,
     request: AggregateRequest,
@@ -8737,10 +8823,10 @@ Gets current account information for the logged in user. Returns user, owner, ac
 ### authKit
 
 **login**(clientId: string, email: string, password: string, trustedDeviceToken?: string) → `Promise<AuthLoginResponse>`
-Login with email + password (public). When the client's MFA policy requires a step-up, the server returns **403 `MFA_REQUIRED`** instead of a session — `login()` throws a `SmartlinksApiError` with `err.errorResponse?.errorCode === 'MFA_REQUIRED'` and the challenge details in `err.details` (see {@link MfaRequiredDetails}). Route the caller to {@link mfaChallengeSend} on that error; this method's return type is unchanged. returned one (via {@link mfaChallengeVerify}/{@link mfaRecoveryCode} with `trustDevice: true`), pass it here to skip the challenge entirely as long as it's still valid. If it's revoked/expired, the server silently falls back to requiring a fresh challenge — `login()` just returns `MFA_REQUIRED` again, no special handling.
+Login with email + password (public). When the client's MFA policy requires a step-up, the server returns **403 `MFA_REQUIRED`** instead of a session — `login()` throws a `SmartlinksApiError` with `err.errorResponse?.errorCode === 'MFA_REQUIRED'` and the challenge details in `err.details` (see {@link MfaRequiredDetails}). Route the caller to {@link mfaChallengeSend} on that error; this method's return type is unchanged. returned one (via {@link mfaChallengeVerify}/{@link mfaRecoveryCode} with `trustDevice: true`), pass it here to skip the challenge entirely as long as it's still valid. If it's revoked/expired, the server silently falls back to requiring a fresh challenge — `login()` just returns `MFA_REQUIRED` again, no special handling. Security errors (thrown as `SmartlinksApiError`, see {@link LoginSecurityErrorCode}): - `ACCOUNT_TEMPORARILY_LOCKED` (429) — `err.details.retryAfterSeconds` says how long to wait. - `PASSWORD_EXPIRED` (403) — `err.details.resetToken` is short-lived; route into {@link completePasswordReset} to change the password in place.
 
 **register**(clientId: string, data: { email: string; password: string; displayName?: string; accountData?: Record<string, any> }) → `Promise<AuthLoginResponse>`
-Register a new user (public). Not gated by step-up MFA — a brand-new user has no enrolled factors yet, so there's nothing to challenge against.
+Register a new user (public). Not gated by step-up MFA — a brand-new user has no enrolled factors yet, so there's nothing to challenge against. The new password is validated against the collection's `passwordPolicy` — may throw a {@link PasswordPolicyErrorCode} (400). The same validation applies to {@link completePasswordReset} and {@link changePassword}. Read the policy for a live checklist from `authKit.load(clientId)` → `config.security.passwordPolicy`.
 
 **googleLogin**(clientId: string, idToken: string, trustedDeviceToken?: string) → `Promise<AuthLoginResponse>`
 Google OAuth login via ID token (public). Gated by step-up MFA — see {@link login} for the `MFA_REQUIRED` error shape. {@link mfaChallengeVerify}/{@link mfaRecoveryCode} (with `trustDevice: true`) to skip the challenge on this device, same as {@link login}.
@@ -9941,14 +10027,14 @@ List all Proofs for a Collection.
 
 **create**(collectionId: string,
     productId: string,
-    values: ProofCreateRequest) → `Promise<ProofResponse>`
-Create a proof for a product (admin only). POST /admin/collection/:collectionId/product/:productId/proof
+    request: ProofCreateRequest) → `Promise<ProofResponse>`
+Create a proof for a product (admin only). POST /admin/collection/:collectionId/product/:productId/proof Pass the proof's content in a `proof` block, keyed by zone (see {@link ProofWrite}): ```ts proof.create(collectionId, productId, { proof: { values: { colour: 'red' },   // public + owner readable, owner + admin writable data:   { serialNo: 1001 },  // public + owner readable, ADMIN-only writable admin:  { costPrice: 4.20 }, // admin-only }, claimable: true, }) ``` Note: a top-level `data`/`admin` on the request body is legacy — top-level `data` gets folded into the values bag, so use `proof.data` for `proof.data`.
 
 **update**(collectionId: string,
     productId: string,
     proofId: string,
     values: ProofUpdateRequest) → `Promise<ProofResponse>`
-Update a proof for a product (admin only). PUT /admin/collection/:collectionId/product/:productId/proof/:proofId
+Update a proof for a product (admin only). PUT /admin/collection/:collectionId/product/:productId/proof/:proofId Pass the fields to change **at the root**, keyed by zone (see {@link ProofWrite}): ```ts proof.update(collectionId, productId, proofId, { data:   { serialNo: 1002 },   // → proof.data (admin-only writable) values: { colour: 'blue' },   // → proof.values }) ``` Object zones deep-merge, so you can change one field without wiping the rest.
 
 **claim**(collectionId: string,
     productId: string,

package/dist/docs/app-objects.md

@@ -429,6 +429,71 @@ const productComments = await app.threads.list(collectionId, appId, {
 });
 ```
 
+### Anchoring to app entities and proofs
+
+Anchor a thread to your own entity with `parentType` + `parentId`. `parentId` is a
+free-form string (SmartLinks short ids, not just UUIDs), so you can use your app's
+native ids directly — no need to stash them in `body` or a tag.
+
+```typescript
+await app.threads.create(collectionId, appId, {
+  parentType: 'memory',
+  parentId: memoryId,          // e.g. "dVdthBQLAjQEnitU7aWy" — text, not a UUID
+  proofId,                     // anchor to a proof (enables grant-tier reads)
+  body: { text: 'Lovely photo' },
+});
+```
+
+List filters that pair with this (see `ThreadListQueryParams`):
+
+| Param | Purpose |
+|-------|---------|
+| `parentType` / `parentId` | one app entity's threads |
+| `parentIds` | **batch** — every thread for many entities in one call (e.g. a feed) |
+| `proofId` / `productId` | threads anchored to a proof / product |
+
+```typescript
+// One request for the 30 memories currently on screen:
+const feed = await app.threads.list(collectionId, appId, {
+  parentType: 'memory',
+  parentIds: visibleMemoryIds,
+  sort: 'createdAt:desc',
+});
+```
+
+### Atomic first comment (`firstReply`)
+
+Posting the first comment no longer needs a create-thread-then-reply two-step (which
+could leave an orphan empty thread if the reply failed). Pass `firstReply` to create
+the thread and its first reply in one atomic call:
+
+```typescript
+await app.threads.create(collectionId, appId, {
+  parentType: 'memory', parentId: memoryId, proofId,
+  firstReply: { text: 'Lovely photo', authorName: 'Sam' },
+});
+```
+
+### Deleting a reply (moderation)
+
+Replies carry a stable `id`. Remove a single one — authorised for the reply's author,
+the proof owner, or a collection admin:
+
+```typescript
+await app.threads.deleteReply(collectionId, appId, threadId, replyId);
+```
+
+### Grant-tier access (private, shareable comments)
+
+A comment thread on a shared album should be `visibility: 'owner'` (private to the
+proof), with access coming from a **share grant** rather than opening the data to the
+world. A holder of an active `read`/`comment` grant on the proof is treated as
+owner-tier **for that proof only**. Enable it with the `publicCreate.threads.grant`
+policy branch and carry the token via `setGrantToken`.
+
+See **[Proof Share Grants](proof-share-grants.md)** for the full flow (create/redeem
+grants, guest commenting, revocation, and the app config).
+
 ---
 
 ## Records

package/dist/docs/assets.md

@@ -243,6 +243,87 @@ await Api.asset.bulkDelete({
 
 ---
 
+## Resumable uploads (large files, e.g. video)
+
+`asset.upload()` is a single request — if the connection drops, the whole file
+restarts. For large files on flaky connections (e.g. phone video), use a
+**resumable** upload: the file is chunked directly to storage and can be paused,
+resumed, and — crucially — **continued after a page reload or app restart**.
+
+```typescript
+import { asset } from '@proveanything/smartlinks'
+
+// 1. Open a resumable upload.
+const handle = await asset.createResumableUpload({
+  file,                                   // a File (input[type=file] / drag-drop)
+  scope: { type: 'proof', collectionId, productId, proofId },
+  appId: 'photo-memory',
+  // token: uploadToken,                  // for public/token uploads (see below)
+})
+
+// 2. Persist handle.id so the upload survives a reload.
+localStorage.setItem('pendingUpload', handle.id)
+
+// 3. Upload. Resumes automatically from the offset storage already holds.
+const uploaded = await handle.start({
+  onProgress: (pct) => setProgress(pct),  // 0–100
+  signal: abortController.signal,         // optional: cancel a stalled upload
+})
+localStorage.removeItem('pendingUpload')
+```
+
+### Pause / resume, and resume after a reload
+
+```typescript
+handle.pause()                            // stop after the current chunk
+await handle.resume({ onProgress })       // continue
+
+// After a reload / app kill — rehydrate from the persisted id and the same file:
+const saved = localStorage.getItem('pendingUpload')
+if (saved) {
+  const handle = await asset.resumeUpload(saved, file)
+  await handle.start({ onProgress })      // continues, does not restart
+}
+```
+
+### API
+
+```typescript
+namespace asset {
+  createResumableUpload(options: CreateResumableUploadOptions): Promise<ResumableUploadHandle>
+  resumeUpload(handleId: string, file: File): Promise<ResumableUploadHandle>
+}
+
+interface CreateResumableUploadOptions {
+  file: File
+  scope: { type: 'collection'; collectionId: string }
+       | { type: 'product'; collectionId: string; productId: string }
+       | { type: 'proof'; collectionId: string; productId: string; proofId: string }
+  name?: string
+  metadata?: Record<string, any>
+  appId?: string
+  admin?: boolean          // admin route (default is the public route)
+  token?: string           // upload token for public/unauthenticated uploads
+}
+
+interface ResumableUploadHandle {
+  readonly id: string      // durable, persistable — pass to resumeUpload() after a reload
+  readonly size: number    // total bytes
+  start(opts?: { onProgress?: (pct: number) => void; signal?: AbortSignal }): Promise<Asset>
+  pause(): void
+  resume(opts?: { onProgress?: (pct: number) => void; signal?: AbortSignal }): Promise<Asset>
+}
+```
+
+**Notes**
+
+- `handle.id` is an opaque string that carries everything needed to resume — persist it as-is.
+- On completion, `start()`/`resume()` resolves to the finalized `Asset` record.
+- `pause()` causes the in-flight `start()`/`resume()` promise to reject with an `UploadPausedError`; call `resume()` to continue.
+- `asset.upload()` also now accepts an `AbortSignal` (`upload({ ..., signal })`) for cancelling a stalled single-shot upload.
+
+---
+
 ## Public (token-based) uploads
 
 For anonymous or contact-initiated uploads from the portal — no admin auth required.

package/dist/docs/auth-kit.md

@@ -502,6 +502,79 @@ await authKit.completePasswordReset(clientId, tokenFromUrl, 'newSecurePassword')
 
 ---
 
+## Account security policy
+
+Each collection can configure account-security rules (via the admin console). **The API
+enforces all of it**; your login UI reads the policy for UX only (a live password checklist,
+idle sign-out). Read it from the config:
+
+```ts
+const config = await authKit.load(clientId);
+const policy  = config.security?.passwordPolicy; // min length, char classes, block-common
+const session = config.security?.session;        // inactivity + absolute timeouts, rememberMe
+```
+
+`lockout` values are admin-only and never returned here.
+
+### Password policy
+
+`register`, `completePasswordReset`, and `changePassword` validate the new password
+server-side and throw a `SmartlinksApiError` with a {@link PasswordPolicyErrorCode}:
+
+| `errorCode` (400) | Meaning |
+|---|---|
+| `PASSWORD_TOO_SHORT` | below `minLength` |
+| `PASSWORD_REQUIREMENTS_NOT_MET` | missing a required character class |
+| `PASSWORD_TOO_COMMON` | on the common/breached list |
+| `PASSWORD_RECENTLY_USED` | matched one of the last `historyCount` passwords |
+
+Render a live checklist from `policy` so users see the rules before submitting.
+
+### Lockout
+
+After too many failed logins the account is temporarily locked. `login` throws:
+
+```ts
+try {
+  await authKit.login(clientId, email, password);
+} catch (err) {
+  if (err.errorCode === 'ACCOUNT_TEMPORARILY_LOCKED') {
+    const mins = Math.ceil(err.details.retryAfterSeconds / 60);
+    show(`Too many attempts. Try again in ${mins} minute(s).`);
+  }
+}
+```
+
+Failed MFA challenges count toward the same lock. Locking responds identically for unknown
+accounts (no enumeration).
+
+### Password expiry
+
+If a password is older than `passwordPolicy.expiryDays`, a valid login is refused with
+**403 `PASSWORD_EXPIRED`** carrying a short-lived `resetToken` — send the user straight into
+the reset form to change it in place:
+
+```ts
+catch (err) {
+  if (err.errorCode === 'PASSWORD_EXPIRED') {
+    await authKit.completePasswordReset(clientId, err.details.resetToken, newPassword);
+  }
+}
+```
+
+### Session lifetime
+
+- **Absolute timeout** (`session.absoluteTimeoutHours`) is enforced server-side on the native
+  refresh path: once the session is too old, `refreshToken` throws **401 `SESSION_EXPIRED`**
+  (see {@link RefreshErrorCode}) — clear storage and route to login. Web sessions use the
+  stateless bearer token and rely on inactivity sign-out below.
+- **Inactivity timeout** (`session.inactivityTimeoutMinutes` / `inactivityWarningSeconds`) is
+  **client-enforced** — sign the user out after idle, warning first. Sync across tabs.
+- **`session.rememberMe: false`** → don't persist tokens to durable storage; treat the session
+  as browser-scoped.
+
+---
+
 ## Relationship to other parts of the SDK
 
 | Concern | Where it lives |