@proveanything/smartlinks 1.15.16 → 1.15.18

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,6 +36,8 @@ 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)
@@ -44,6 +49,9 @@ For the full list of functions and types, see the API summary:
 **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/navigation.js

@@ -122,7 +122,7 @@ export var navigation;
                         type: 'smartlinks-navigate',
                         appId: link.appId,
                         path: link.kind === 'deep' ? deepPath(link.deepLinkId) : '/',
-                        params: link.kind === 'deep' ? ((_b = link.params) !== null && _b !== void 0 ? _b : {}) : {},
+                        params: (link.kind === 'deep' || link.kind === 'app') ? ((_b = link.params) !== null && _b !== void 0 ? _b : {}) : {},
                         target: (_c = link.target) !== null && _c !== void 0 ? _c : '_self',
                     }, '*');
                     return;
@@ -134,7 +134,8 @@ export var navigation;
                 const hash = link.kind === 'deep'
                     ? `#${deepPath(link.deepLinkId)}${qs(link.params)}`
                     : `#/`;
-                const url = `${win.location.pathname}?appId=${encodeURIComponent(link.appId)}${hash}`;
+                const appParams = link.kind === 'app' && link.params ? qs(link.params).replace(/^\?/, '&') : '';
+                const url = `${win.location.pathname}?appId=${encodeURIComponent(link.appId)}${appParams}${hash}`;
                 if (link.target === '_blank') {
                     win.open(url, '_blank', windowFeatures());
                 }

package/dist/api/proof.d.ts

@@ -1,4 +1,4 @@
-import { ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest } from "../types/proof";
+import { ProofResponse, ProofCreateRequest, ProofUpdateRequest, ProofClaimRequest, ProofGrant, CreateGrantOptions, RedeemGrantOptions, RedeemGrantResult } from "../types/proof";
 export declare namespace proof {
     /**
      * Retrieves a single Proof by Collection ID, Product ID, and Proof ID.
@@ -104,4 +104,22 @@ export declare namespace proof {
     data: {
         targetProductId: string;
     }): Promise<ProofResponse>;
+    /**
+     * Create a share grant on a proof (owner / collection admin only). The returned
+     * grant includes `token` — the opaque bearer secret, available ONLY on this
+     * response. Embed it in a share link and hand recipients {@link redeemGrant} /
+     * {@link setGrantToken}.
+     */
+    function createGrant(collectionId: string, productId: string, proofId: string, options: CreateGrantOptions): Promise<ProofGrant>;
+    /** List the active + past grants on a proof (owner / collection admin only). Tokens are never returned here. */
+    function listGrants(collectionId: string, productId: string, proofId: string): Promise<ProofGrant[]>;
+    /** Revoke a grant by id (owner / collection admin only). Takes effect immediately. */
+    function revokeGrant(collectionId: string, productId: string, proofId: string, grantId: string): Promise<void>;
+    /**
+     * Redeem a grant token (anonymous or signed-in). Records the redemption and
+     * returns the granted scope, or — for a `verify_owner` grant — an ownership
+     * assertion (never the account). After redeeming, call
+     * {@link setGrantToken} so subsequent data requests carry the token.
+     */
+    function redeemGrant(collectionId: string, productId: string, proofId: string, token: string, options?: RedeemGrantOptions): Promise<RedeemGrantResult>;
 }

package/dist/api/proof.js

@@ -156,4 +156,48 @@ export var proof;
         return post(path, data);
     }
     proof.migrate = migrate;
+    // ---------------------------------------------------------------------------
+    // Share grants — delegated, scoped, revocable bearer access to this proof
+    // ---------------------------------------------------------------------------
+    function grantBase(collectionId, productId, proofId) {
+        return `/public/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}/proof/${encodeURIComponent(proofId)}/grant`;
+    }
+    /**
+     * Create a share grant on a proof (owner / collection admin only). The returned
+     * grant includes `token` — the opaque bearer secret, available ONLY on this
+     * response. Embed it in a share link and hand recipients {@link redeemGrant} /
+     * {@link setGrantToken}.
+     */
+    async function createGrant(collectionId, productId, proofId, options) {
+        const body = { scope: options.scope };
+        if (options.audience)
+            body.audience = options.audience;
+        if (options.expiresAt)
+            body.expiresAt = options.expiresAt instanceof Date ? options.expiresAt.toISOString() : options.expiresAt;
+        return post(grantBase(collectionId, productId, proofId), body);
+    }
+    proof.createGrant = createGrant;
+    /** List the active + past grants on a proof (owner / collection admin only). Tokens are never returned here. */
+    async function listGrants(collectionId, productId, proofId) {
+        return request(grantBase(collectionId, productId, proofId));
+    }
+    proof.listGrants = listGrants;
+    /** Revoke a grant by id (owner / collection admin only). Takes effect immediately. */
+    async function revokeGrant(collectionId, productId, proofId, grantId) {
+        return del(`${grantBase(collectionId, productId, proofId)}/${encodeURIComponent(grantId)}`);
+    }
+    proof.revokeGrant = revokeGrant;
+    /**
+     * Redeem a grant token (anonymous or signed-in). Records the redemption and
+     * returns the granted scope, or — for a `verify_owner` grant — an ownership
+     * assertion (never the account). After redeeming, call
+     * {@link setGrantToken} so subsequent data requests carry the token.
+     */
+    async function redeemGrant(collectionId, productId, proofId, token, options) {
+        const body = { token };
+        if (options === null || options === void 0 ? void 0 : options.guestName)
+            body.guestName = options.guestName;
+        return post(`${grantBase(collectionId, productId, proofId)}/redeem`, body);
+    }
+    proof.redeemGrant = redeemGrant;
 })(proof || (proof = {}));

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.15.16  |  Generated: 2026-08-15T11:42:50.997Z
+Version: 1.15.18  |  Generated: 2026-08-19T06:40:47.505Z
 
 This is a concise summary of all available API functions and types.
 
@@ -170,6 +170,12 @@ Replace or augment globally applied custom headers.
 **setBearerToken**(token: string | undefined) → `void`
 Allows setting the bearerToken at runtime (e.g. after login/logout). Clears the HTTP cache whenever the token actually changes so that stale user-scoped responses (e.g. /account/profile) are not served after a login or logout event.
 
+**setGrantToken**(token: string | undefined) → `void`
+Set (or clear) the per-proof share-grant token. When set, it is attached as the `X-Grant-Token` header on every request, so a recipient who has opened a shared link can read/comment on the granted proof's data. Pass `undefined` to clear it. The server re-checks the grant against the database on every request, so calling `revokeGrant` invalidates an in-flight token immediately. Clears the GET cache on change so grant-tier responses are not served after the token changes. ```ts // On opening ?proofId=…&shareToken=abc setGrantToken(shareToken) const { attestations } = await proof.get(...)  // now sees owner-tier memories ```
+
+**getGrantToken**() → `string | undefined`
+Returns the currently-set share-grant token, or `undefined`.
+
 **getBearerToken**() → `string | undefined`
 Returns the bearer token currently held by the SDK, or `undefined` if none is set. In proxy mode, credentials are held by the parent frame, not the local SDK, so this returns `undefined` even when the caller is authenticated.
 
@@ -1987,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
 }
 ```
 
@@ -7287,6 +7297,50 @@ interface ProofFieldsConfig {
 }
 ```
 
+**GrantAudience** (interface)
+```typescript
+interface GrantAudience {
+  kind: 'public_link' | 'named'
+  email?: string
+  userId?: string
+}
+```
+
+**ProofGrant** (interface)
+```typescript
+interface ProofGrant {
+  grantId: string
+  proofId: string
+  productId?: string | null
+  scope: GrantScope[]
+  audience: GrantAudience
+  createdBy: string
+  expiresAt?: string | null
+  revokedAt?: string | null
+  redeemedBy?: { userId?: string; guestName?: string; redeemedAt: string }
+  redeemCount: number
+  createdAt: string
+  updatedAt: string
+  token?: string
+}
+```
+
+**CreateGrantOptions** (interface)
+```typescript
+interface CreateGrantOptions {
+  scope: GrantScope[]
+  audience?: GrantAudience
+  expiresAt?: Date | string
+}
+```
+
+**RedeemGrantOptions** (interface)
+```typescript
+interface RedeemGrantOptions {
+  guestName?: string
+}
+```
+
 **ProofResponse** = `Proof`
 
 **ProofUpdateRequest** = `Partial<ProofCreateRequest>`
@@ -7297,6 +7351,10 @@ interface ProofFieldsConfig {
 
 **ProofFieldDef** = `ScopedFieldDef & { scope?: ProofFieldScope }`
 
+**GrantScope** = `'read' | 'comment' | 'admin' | 'verify_owner'`
+
+**RedeemGrantResult** = ``
+
 ### qr
 
 **QrShortCodeLookupResponse** (interface)
@@ -8381,6 +8439,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,
@@ -9937,6 +10002,30 @@ Get proofs for a batch (admin only). GET /admin/collection/:collectionId/product
     data: { targetProductId: string }) → `Promise<ProofResponse>`
 Migrate a proof to a different product within the same collection (admin only). Because the Firestore ledger document ID is `{productId}-{proofId}`, a proof cannot simply be re-assigned to another product by updating a field — the document must be re-keyed. This endpoint handles that atomically: 1. Reads the source ledger document (`{sourceProductId}-{proofId}`). 2. Writes a new document (`{targetProductId}-{proofId}`) with `productId` and `proofGroup` updated. The short `proofId` (nanoid) is unchanged. 3. Writes a migration history entry to the new document's `history` subcollection (snapshot of the original proof + migration metadata). 4. Copies all subcollections — `assets`, `attestations`, `history` — from the old document to the new one. 5. Deletes the old subcollections and then the old document. Repeated migrations are safe — each one appends a history record; no migration metadata is stored on the proof document itself. ```typescript const migrated = await proof.migrate('coll_123', 'prod_old', 'proof_abc', { targetProductId: 'prod_new', }) console.log(migrated.productId) // 'prod_new' ```
 
+**createGrant**(collectionId: string,
+    productId: string,
+    proofId: string,
+    options: CreateGrantOptions) → `Promise<ProofGrant>`
+Create a share grant on a proof (owner / collection admin only). The returned grant includes `token` — the opaque bearer secret, available ONLY on this response. Embed it in a share link and hand recipients {@link redeemGrant} / {@link setGrantToken}.
+
+**listGrants**(collectionId: string,
+    productId: string,
+    proofId: string) → `Promise<ProofGrant[]>`
+List the active + past grants on a proof (owner / collection admin only). Tokens are never returned here.
+
+**revokeGrant**(collectionId: string,
+    productId: string,
+    proofId: string,
+    grantId: string) → `Promise<void>`
+Revoke a grant by id (owner / collection admin only). Takes effect immediately.
+
+**redeemGrant**(collectionId: string,
+    productId: string,
+    proofId: string,
+    token: string,
+    options?: RedeemGrantOptions) → `Promise<RedeemGrantResult>`
+Redeem a grant token (anonymous or signed-in). Records the redemption and returns the granted scope, or — for a `verify_owner` grant — an ownership assertion (never the account). After redeeming, call {@link setGrantToken} so subsequent data requests carry the token.
+
 ### publicClient
 
 **chat**(collectionId: 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.