@proveanything/smartlinks 1.16.6 → 1.17.0

package/docs/proof-share-grants.md

@@ -22,11 +22,12 @@ re-checks the grant **server-side** against the database, so revocation is immed
 |-------|--------------------|
 | `read` | read owner-tier data on the proof (attestations, threads, records, cases) |
 | `comment` | create threads/replies on the proof (guest comments) |
+| `contribute` | add attestations / records to the proof for the life of the grant (temporary contribute access) — optionally held for owner review via `moderate` |
 | `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.
+commentable album, or `['read', 'contribute']` to let someone add photos.
 
 ### Security & lifecycle
 
@@ -124,6 +125,65 @@ Other grant holders (and the owner) see these comments because a `read` grant re
 
 ---
 
+## Contribute access — let someone add to a proof
+
+A `contribute` scope grant is **temporary write access**: the bearer can add
+attestations (a photo, a video reference, a check-in) and app records to the proof
+for the life of the grant — no account or proof claim required. It's the successor
+to ad-hoc "claim windows": properly time-boxed (`expiresAt`), revocable, and voided
+on ownership transfer like every other grant.
+
+```typescript
+// Owner issues a contribute grant that expires in 48h and holds contributions
+// for review before they go public.
+const grant = await proof.createGrant(collectionId, productId, proofId, {
+  scope: ['read', 'contribute'],
+  moderate: true,                                   // contributions land 'pending'
+  expiresAt: new Date(Date.now() + 48 * 60 * 60 * 1000),
+})
+
+// Contributor (on the shared link) adds a photo attestation.
+setGrantToken(shareToken)
+await attestation.publicCreate(collectionId, {
+  subjectType: 'proof', subjectId: proofId,
+  attestationType: 'photo',
+  value: { url: 'https://…/photo.jpg' },
+  visibility: 'public',
+  guestName: 'Sam',                                 // attribution for a public-link bearer
+})
+```
+
+### Moderation — the two-step review
+
+When the grant is issued with `moderate: true`, each contribution is created with
+`moderationStatus: 'pending'` and is **held to the owner**: it is returned only to
+its own author and to owner/admin audiences — never to the public, whatever its
+target `visibility`. The owner reviews and approves (or rejects) it:
+
+```typescript
+// Owner lists what's waiting (owner-tier read = identity or an owner session):
+const { attestations } = await attestation.publicList(collectionId, {
+  subjectType: 'proof', subjectId: proofId,
+  moderationStatus: 'pending',
+})
+
+// Approve → the record goes live at its declared visibility; reject → author+admin only.
+await attestation.moderate(collectionId, attestations[0].id, { decision: 'approve' })
+```
+
+The moderation gate is enforced **server-side** — a front end may badge a pending
+item, but it is the server that withholds it from other viewers. Only
+`moderationStatus` changes on approve/reject; the hashed fact and its chain are
+untouched. Contributions under a grant issued with `moderate: false` (the default)
+go live immediately.
+
+> **Media note.** A contributed photo/video is best modelled as an attestation
+> (`attestationType: 'photo'`, `value: { url }`) so it rides this moderation model.
+> The legacy per-proof asset upload path is unchanged and is not grant- or
+> moderation-aware.
+
+---
+
 ## Proof of ownership — `verify_owner`
 
 Ownership itself is **not** a grant — it is `proof.ownerId`, established via the
@@ -154,6 +214,7 @@ 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)
+- **Attestation / record creation** — with a `contribute` scope grant (see [Contribute access](#contribute-access--let-someone-add-to-a-proof))
 
 The token never exposes the platform `admin` zone, and only reveals `owner`-visibility
 rows for the granted `proofId`.
@@ -175,14 +236,24 @@ at `sites/{collectionId}/apps/{appId}` — a `grant` branch alongside
         "requireScope": "comment",
         "enforce": { "visibility": "owner", "status": "open" }
       }
+    },
+    "records": {
+      "grant": {
+        "allow": true,
+        "requireScope": "contribute",
+        "enforce": { "visibility": "owner" }   // held to the owner until promoted
+      }
     }
   }
 }
 ```
 
-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).
+This enables grant-scoped commenting and contribution **without** opening up
+anonymous creation. The `enforce.visibility: "owner"` keeps the created object
+private to the proof (visible to the owner and other grant holders, not the wider
+public). Attestation contribution is gated the same way, by the `contribute` scope;
+whether those contributions are held for review is set per-grant with `moderate`,
+not in app config.
 
 ---
 
@@ -200,12 +271,13 @@ namespace proof {
 function setGrantToken(token: string | undefined): void
 function getGrantToken(): string | undefined
 
-type GrantScope = 'read' | 'comment' | 'admin' | 'verify_owner'
+type GrantScope = 'read' | 'comment' | 'contribute' | 'admin' | 'verify_owner'
 
 interface CreateGrantOptions {
   scope: GrantScope[]                                   // at least one
   audience?: { kind: 'public_link' } | { kind: 'named'; email?: string; userId?: string }
   expiresAt?: Date | string
+  moderate?: boolean                                    // 'contribute' only — hold for review
 }
 
 interface RedeemGrantOptions { guestName?: string }
@@ -219,6 +291,7 @@ interface ProofGrant {
   proofId: string
   productId?: string | null
   scope: GrantScope[]
+  moderate?: boolean   // 'contribute' grants: contributions held for review when true
   audience: { kind: 'public_link' | 'named'; email?: string; userId?: string }
   createdBy: string
   expiresAt?: string | null

package/openapi.yaml

@@ -1261,6 +1261,11 @@ paths:
           required: false
           schema:
             type: string
+        - name: moderationStatus
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/AttestationModerationStatus"
         - name: recordedAfter
           in: query
           required: false
@@ -10237,6 +10242,11 @@ paths:
           required: false
           schema:
             type: string
+        - name: moderationStatus
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/AttestationModerationStatus"
         - name: recordedAfter
           in: query
           required: false
@@ -10273,7 +10283,7 @@ paths:
     post:
       tags:
         - attestations
-      summary: "Create an OWNER-authored attestation (public write) — the counterpart to the admin {@link create}."
+      summary: attestations.publicCreate
       operationId: attestations_publicCreate
       security: []
       parameters:
@@ -10505,6 +10515,43 @@ paths:
           description: Unauthorized
         404:
           description: Not found
+  /public/collection/{collectionId}/attestations/{attestationId}/moderate:
+    post:
+      tags:
+        - attestations
+      summary: Moderate a contributed attestation (proof OWNER by identity, or collection admin).
+      operationId: attestations_moderate
+      security: []
+      parameters:
+        - name: collectionId
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: attestationId
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ModerateAttestationResponse"
+        400:
+          description: Bad request
+        401:
+          description: Unauthorized
+        404:
+          description: Not found
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ModerateAttestationInput"
   /public/collection/{collectionId}/comm/email/register:
     post:
       tags:
@@ -11115,6 +11162,11 @@ paths:
           required: false
           schema:
             type: string
+        - name: moderationStatus
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/AttestationModerationStatus"
         - name: recordedAfter
           in: query
           required: false
@@ -18720,6 +18772,10 @@ components:
           type: string
         authorId:
           type: string
+        grantId:
+          type: string
+        moderationStatus:
+          $ref: "#/components/schemas/AttestationModerationStatus"
         metadata:
           type: object
           additionalProperties: true
@@ -18842,10 +18898,29 @@ components:
         metadata:
           type: object
           additionalProperties: true
+        guestName:
+          type: string
       required:
         - subjectType
         - subjectId
         - attestationType
+    ModerateAttestationInput:
+      type: object
+      properties:
+        decision:
+          type: string
+          enum:
+            - approve
+            - reject
+      required:
+        - decision
+    ModerateAttestationResponse:
+      type: object
+      properties:
+        attestation:
+          $ref: "#/components/schemas/Attestation"
+      required:
+        - attestation
     ListAttestationsResponse:
       type: object
       properties:
@@ -18985,6 +19060,8 @@ components:
           type: string
         attestationType:
           type: string
+        moderationStatus:
+          $ref: "#/components/schemas/AttestationModerationStatus"
         recordedAfter:
           type: string
         recordedBefore:
@@ -22783,6 +22860,276 @@ components:
     UploadMessage:
       type: object
       additionalProperties: true
+    FieldMapping:
+      type: object
+      properties:
+        targetPath:
+          type: string
+        sourcePath:
+          type: string
+        transformType:
+          $ref: "#/components/schemas/TransformType"
+        transformExpression:
+          type: string
+      required:
+        - targetPath
+        - transformType
+    FlowConnectionAuth:
+      type: object
+      properties:
+        method:
+          $ref: "#/components/schemas/FlowAuthMethod"
+        headerName:
+          type: string
+        credentialRef:
+          type: string
+      required:
+        - method
+    FlowConnection:
+      type: object
+      properties:
+        baseUrl:
+          type: string
+        sendEndpoint:
+          type: string
+        fetchEndpoint:
+          type: string
+        defaultHeaders:
+          type: object
+          additionalProperties:
+            type: string
+        auth:
+          $ref: "#/components/schemas/FlowConnectionAuth"
+    IntegrationFlowConfig:
+      type: object
+      properties:
+        connection:
+          $ref: "#/components/schemas/FlowConnection"
+        fieldMappings:
+          type: array
+          items:
+            $ref: "#/components/schemas/FieldMapping"
+    IntegrationFlow:
+      type: object
+      properties:
+        id:
+          type: string
+        orgId:
+          type: string
+        collectionId:
+          type: string
+        appId:
+          type: string
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        name:
+          type: string
+        status:
+          $ref: "#/components/schemas/FlowStatus"
+        eventTypes:
+          type: array
+          items:
+            type: string
+        schedule:
+          type: string
+        sourceEntity:
+          type: string
+        targetEntity:
+          type: string
+        config:
+          $ref: "#/components/schemas/IntegrationFlowConfig"
+        createdBy:
+          type: string
+        createdAt:
+          type: string
+        updatedAt:
+          type: string
+        deletedAt:
+          type: string
+        lastRunAt:
+          type: string
+        lastRunStatus:
+          type: string
+        lastRunError:
+          type: string
+        lastRunCount:
+          type: number
+        lastPollAt:
+          type: string
+        lastCursor:
+          type: string
+        totalSynced:
+          type: number
+      required:
+        - id
+        - orgId
+        - collectionId
+        - appId
+        - direction
+        - name
+        - status
+        - eventTypes
+        - schedule
+        - sourceEntity
+        - targetEntity
+        - config
+        - createdBy
+        - createdAt
+        - updatedAt
+    CreateFlowInput:
+      type: object
+      properties:
+        appId:
+          type: string
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        name:
+          type: string
+        status:
+          $ref: "#/components/schemas/FlowStatus"
+        eventTypes:
+          type: array
+          items:
+            type: string
+        schedule:
+          type: string
+        sourceEntity:
+          type: string
+        targetEntity:
+          type: string
+        config:
+          $ref: "#/components/schemas/IntegrationFlowConfig"
+      required:
+        - appId
+        - direction
+        - name
+    ListFlowsQuery:
+      type: object
+      properties:
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        status:
+          $ref: "#/components/schemas/FlowStatus"
+        appId:
+          type: string
+    FlowList:
+      type: object
+      properties:
+        flows:
+          type: array
+          items:
+            $ref: "#/components/schemas/IntegrationFlow"
+      required:
+        - flows
+    RunFlowInput:
+      type: object
+      properties:
+        entityId:
+          type: string
+    RunFlowSummary:
+      type: object
+      properties:
+        flowId:
+          type: string
+        direction:
+          $ref: "#/components/schemas/FlowDirection"
+        records:
+          type: number
+        sent:
+          type: number
+        failed:
+          type: number
+        status:
+          $ref: "#/components/schemas/RunStatus"
+      required:
+        - flowId
+        - direction
+        - records
+        - sent
+        - failed
+        - status
+    RunFlowEnqueued:
+      type: object
+      properties:
+        enqueued:
+          type: object
+          additionalProperties: true
+        flowId:
+          type: string
+        entityId:
+          type: string
+      required:
+        - enqueued
+        - flowId
+        - entityId
+    SecretMeta:
+      type: object
+      properties:
+        ref:
+          type: string
+        name:
+          type: string
+        purpose:
+          type: string
+        hint:
+          type: string
+        keyVersion:
+          type: number
+        createdBy:
+          type: string
+        createdAt:
+          type: string
+        updatedAt:
+          type: string
+        rotatedAt:
+          type: string
+      required:
+        - ref
+        - name
+        - purpose
+        - hint
+        - keyVersion
+        - createdBy
+        - createdAt
+        - updatedAt
+    SecretList:
+      type: object
+      properties:
+        secrets:
+          type: array
+          items:
+            $ref: "#/components/schemas/SecretMeta"
+      required:
+        - secrets
+    SetSecretInput:
+      type: object
+      properties:
+        value:
+          type: string
+        name:
+          type: string
+        purpose:
+          type: string
+      required:
+        - value
+    SetSecretResult:
+      type: object
+      properties:
+        ref:
+          type: string
+        hint:
+          type: string
+      required:
+        - ref
+        - hint
+    ListSecretsQuery:
+      type: object
+      properties:
+        purpose:
+          type: string
+    RunFlowResult:
+      type: object
+      additionalProperties: true
     AdminInteractionsQueryRequest:
       type: object
       properties:
@@ -25832,6 +26179,8 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/GrantScope"
+        moderate:
+          type: boolean
         audience:
           $ref: "#/components/schemas/GrantAudience"
         createdBy:
@@ -25872,6 +26221,8 @@ components:
         expiresAt:
           type: object
           additionalProperties: true
+        moderate:
+          type: boolean
       required:
         - scope
     RedeemGrantOptions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.16.6",
+  "version": "1.17.0",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,7 +28,7 @@
   "keywords": [
     "smartlinks",
     "api",
-    "authentication", 
+    "authentication",
     "traceability",
     "blockchain",
     "typescript",