@proveanything/smartlinks 1.15.17 → 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/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.18  |  Generated: 2026-08-19T06:40:47.505Z
 
 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
 }
 ```
 
@@ -8435,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,

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/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/openapi.yaml

@@ -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:

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/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.18  |  Generated: 2026-08-19T06:40:47.505Z
 
 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
 }
 ```
 
@@ -8435,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,

package/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/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/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/openapi.yaml

@@ -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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.15.17",
+  "version": "1.15.18",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",