@proveanything/smartlinks 1.16.6 → 1.17.0

package/dist/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/dist/types/attestations.d.ts

@@ -17,6 +17,14 @@ export type AttestationSubjectType = 'container' | 'proof' | 'product' | 'tag' |
  * - `'admin'`   — visible to admin callers only
  */
 export type AttestationVisibility = 'public' | 'owner' | 'admin';
+/**
+ * Moderation state of an attestation (separate from {@link AttestationVisibility}).
+ * - `'approved'` — live; follows its declared visibility (the default)
+ * - `'pending'`  — awaiting owner review; returned only to its author and to
+ *   owner/admin audiences, never to the public, whatever its target visibility
+ * - `'rejected'` — owner declined; author + admin only
+ */
+export type AttestationModerationStatus = 'approved' | 'pending' | 'rejected';
 /**
  * Resolved audience tier returned by public endpoints.
  * Tells the client which data zones are populated in the response.
@@ -59,6 +67,19 @@ export interface Attestation {
     source?: string;
     /** User ID or service account that recorded the fact */
     authorId?: string;
+    /**
+     * When authored under a `contribute` grant (rather than by identity), the id of
+     * the granting token — provenance for a contributed record. `null`/absent for
+     * owner/admin/identity writes.
+     */
+    grantId?: string | null;
+    /**
+     * Moderation gate, orthogonal to {@link visibility} and excluded from the hash
+     * chain. `'approved'` (default) is live; `'pending'` is held for owner review
+     * (visible only to its author and owner/admin audiences); `'rejected'` was
+     * declined. Contributions under a `moderate` grant start `'pending'`.
+     */
+    moderationStatus?: AttestationModerationStatus;
     /** Arbitrary extra metadata */
     metadata?: Record<string, any>;
     /** SHA-256 digest of this record (includes `prevHash`) */
@@ -129,10 +150,18 @@ export interface CreateAttestationInput {
     metadata?: Record<string, any>;
 }
 /**
- * Owner-authored attestation input (public write). The proof OWNER adds an
- * attestation to their own item. Restricted vs {@link CreateAttestationInput}:
- * no `adminData` (business-only zone), `visibility` limited to `'public' | 'owner'`,
- * and `authorId` is forced to the caller by the server (so it's omitted here).
+ * Public attestation write input, used by {@link attestations.publicCreate}.
+ *
+ * Authorised two ways, same input shape (the server decides from the request):
+ *   1. the proof OWNER (Firebase ID token) adds an attestation to their own item;
+ *   2. a holder of a `contribute`-scope grant adds one — set the grant token with
+ *      `setGrantToken(token)` first; for a public-link (anonymous) grant, pass
+ *      `guestName` for attribution.
+ *
+ * Restricted vs {@link CreateAttestationInput}: no `adminData` (business-only
+ * zone), `visibility` limited to `'public' | 'owner'`, and `authorId` / `grantId`
+ * are server-stamped (so they're omitted here). If the contribute grant was issued
+ * with `moderate: true`, the created record comes back `moderationStatus: 'pending'`.
  */
 export interface OwnerAttestationInput {
     subjectType: AttestationSubjectType;
@@ -146,6 +175,18 @@ export interface OwnerAttestationInput {
     unit?: string;
     source?: string;
     metadata?: Record<string, any>;
+    /**
+     * Attribution for an anonymous (public-link) contribute-grant write. Ignored
+     * for owner writes and for named-grant writes (attributed to the signed-in uid).
+     */
+    guestName?: string;
+}
+/** Owner/admin decision on a pending contributed attestation. */
+export interface ModerateAttestationInput {
+    decision: 'approve' | 'reject';
+}
+export interface ModerateAttestationResponse {
+    attestation: Attestation;
 }
 export interface ListAttestationsResponse {
     attestations: Attestation[];
@@ -197,6 +238,12 @@ export interface ListAttestationsParams {
     /** Required */
     subjectId: string;
     attestationType?: string;
+    /**
+     * Filter by moderation state. Primarily for the owner review queue
+     * (`moderationStatus: 'pending'`). ANDs with the server's audience gate, so a
+     * public caller can never use it to widen access.
+     */
+    moderationStatus?: AttestationModerationStatus;
     /** ISO 8601 lower bound (inclusive) */
     recordedAfter?: string;
     /** ISO 8601 upper bound (inclusive) */

package/dist/types/index.d.ts

@@ -38,5 +38,6 @@ export * from "./appManifest";
 export * from "./appObjects";
 export * from "./loyalty";
 export * from "./translations";
+export * from "./integrations";
 export * from "./config";
 export * from "./widgets";

package/dist/types/index.js

@@ -40,5 +40,6 @@ export * from "./appManifest";
 export * from "./appObjects";
 export * from "./loyalty";
 export * from "./translations";
+export * from "./integrations";
 export * from "./config";
 export * from "./widgets";

package/dist/types/integrations.d.ts

@@ -0,0 +1,136 @@
+export type FlowDirection = 'inbound' | 'outbound';
+export type FlowStatus = 'draft' | 'active' | 'paused' | 'error';
+export type RunStatus = 'success' | 'partial' | 'error';
+/** How one source field maps to one target field during transform. */
+export type TransformType = 'direct' | 'static' | 'template' | 'jsonata' | 'ai';
+export interface FieldMapping {
+    /** Dot-path in the produced target object (required). */
+    targetPath: string;
+    /** Dot-path in the source record. Used by `direct`. */
+    sourcePath?: string;
+    transformType: TransformType;
+    /** Constant (`static`) or Liquid template (`template`), etc. */
+    transformExpression?: string;
+}
+export type FlowAuthMethod = 'api_key' | 'bearer' | 'basic' | 'webhook' | 'oauth2' | 'none';
+export interface FlowConnectionAuth {
+    method: FlowAuthMethod;
+    /** Header name for `api_key` (defaults server-side to X-API-Key). */
+    headerName?: string;
+    /** Opaque reference into the secret store; resolved server-side at execution. */
+    credentialRef?: string;
+}
+export interface FlowConnection {
+    baseUrl?: string;
+    /** Outbound: path appended to baseUrl for sends. */
+    sendEndpoint?: string;
+    /** Inbound: path appended to baseUrl for fetches. */
+    fetchEndpoint?: string;
+    defaultHeaders?: Record<string, string>;
+    auth?: FlowConnectionAuth;
+}
+export interface IntegrationFlowConfig {
+    connection?: FlowConnection;
+    fieldMappings?: FieldMapping[];
+    [key: string]: any;
+}
+export interface IntegrationFlow {
+    id: string;
+    orgId: string;
+    collectionId: string;
+    appId: string;
+    direction: FlowDirection;
+    name: string;
+    status: FlowStatus;
+    /** Event types this flow subscribes to, e.g. ['product.updated']. */
+    eventTypes: string[];
+    /** Cron/interval string for scheduled flows, or null. */
+    schedule: string | null;
+    sourceEntity: string | null;
+    targetEntity: string | null;
+    config: IntegrationFlowConfig;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt?: string | null;
+    lastRunAt?: string | null;
+    lastRunStatus?: string | null;
+    lastRunError?: string | null;
+    lastRunCount?: number | null;
+    lastPollAt?: string | null;
+    lastCursor?: string | null;
+    totalSynced?: number | null;
+}
+export interface CreateFlowInput {
+    appId: string;
+    direction: FlowDirection;
+    name: string;
+    status?: FlowStatus;
+    eventTypes?: string[];
+    schedule?: string | null;
+    sourceEntity?: string | null;
+    targetEntity?: string | null;
+    config?: IntegrationFlowConfig;
+}
+export type UpdateFlowInput = Partial<Omit<CreateFlowInput, 'direction'>> & {
+    status?: FlowStatus;
+};
+export interface ListFlowsQuery {
+    direction?: FlowDirection;
+    status?: FlowStatus;
+    appId?: string;
+}
+export interface FlowList {
+    flows: IntegrationFlow[];
+}
+/** Options for a manual flow run. */
+export interface RunFlowInput {
+    /** Run for a single source entity; omit for the flow's scheduled gather. */
+    entityId?: string;
+}
+/** Inline (synchronous) run summary. */
+export interface RunFlowSummary {
+    flowId: string;
+    direction: FlowDirection;
+    records: number;
+    sent: number;
+    failed: number;
+    status: RunStatus;
+}
+/** Response when a run is enqueued (?async=true). */
+export interface RunFlowEnqueued {
+    enqueued: true;
+    flowId: string;
+    entityId: string | null;
+}
+export type RunFlowResult = RunFlowSummary | RunFlowEnqueued;
+/** Metadata for a stored secret. NEVER includes the value or ciphertext. */
+export interface SecretMeta {
+    ref: string;
+    name: string | null;
+    purpose: string;
+    /** Masked hint (e.g. last few chars) — safe to display. */
+    hint: string;
+    keyVersion: number;
+    createdBy: string | null;
+    createdAt: string;
+    updatedAt: string;
+    rotatedAt?: string | null;
+}
+export interface SecretList {
+    secrets: SecretMeta[];
+}
+export interface SetSecretInput {
+    value: string;
+    name?: string;
+    /** Grouping/scoping label, defaults to 'integration' server-side. */
+    purpose?: string;
+}
+/** Result of set/rotate — the ref to store on a flow's connection, plus a hint. */
+export interface SetSecretResult {
+    ref: string;
+    hint: string;
+}
+export interface ListSecretsQuery {
+    purpose?: string;
+}

package/dist/types/integrations.js

@@ -0,0 +1,10 @@
+// src/types/integrations.ts
+//
+// Integration flows + the sealed-secret store that backs their credentials.
+//
+// A flow is one input/output pipeline: an inbound flow fetches from an external
+// system and writes a SmartLinks entity; an outbound flow reads a SmartLinks entity,
+// transforms it, and sends it out. Credentials are never stored on the flow — the
+// connection carries a `credentialRef` into the secret store, resolved server-side
+// only, at execution.
+export {};