@proveanything/smartlinks 1.16.6 → 1.17.0

package/dist/api/attestations.d.ts

@@ -1,4 +1,4 @@
-import type { Attestation, CreateAttestationInput, ListAttestationsParams, ListAttestationsResponse, AttestationSummaryParams, AttestationSummaryResponse, PublicAttestationSummaryResponse, AttestationLatestParams, AttestationLatestResponse, PublicAttestationLatestResponse, AttestationVerifyParams, ChainVerifyResult, AttestationTreeSummaryParams, AttestationTreeSummaryResponse, PublicAttestationTreeSummaryResponse, AttestationTreeLatestParams, AttestationTreeLatestResponse, PublicAttestationTreeLatestResponse, PublicListAttestationsResponse, OwnerAttestationInput, CreateOwnerAttestationResponse } from "../types/attestations";
+import type { Attestation, CreateAttestationInput, ListAttestationsParams, ListAttestationsResponse, AttestationSummaryParams, AttestationSummaryResponse, PublicAttestationSummaryResponse, AttestationLatestParams, AttestationLatestResponse, PublicAttestationLatestResponse, AttestationVerifyParams, ChainVerifyResult, AttestationTreeSummaryParams, AttestationTreeSummaryResponse, PublicAttestationTreeSummaryResponse, AttestationTreeLatestParams, AttestationTreeLatestResponse, PublicAttestationTreeLatestResponse, PublicListAttestationsResponse, OwnerAttestationInput, CreateOwnerAttestationResponse, ModerateAttestationInput, ModerateAttestationResponse } from "../types/attestations";
 /**
  * Postgres-backed Attestations API (v2).
  *
@@ -13,9 +13,11 @@ import type { Attestation, CreateAttestationInput, ListAttestationsParams, ListA
  *   admin session or bearer token.  All three data zones are returned, and the
  *   business can write any zone/visibility ({@link create}).
  * - **Public** endpoints (`/public/collection/:id/attestations`) are read-only,
- *   EXCEPT {@link publicCreate}: the proof OWNER may author an attestation on
- *   their own item (value + ownerData, visibility public|owner — never the admin
- *   zone). Owner elevation is via `Authorization: Bearer <Firebase ID token>`.
+ *   EXCEPT {@link publicCreate} (the proof OWNER, or a `contribute`-grant holder,
+ *   authors an attestation — value + ownerData, visibility public|owner, never the
+ *   admin zone) and {@link moderate} (owner/admin approves or rejects a contributed
+ *   record). Owner elevation is via `Authorization: Bearer <Firebase ID token>`;
+ *   contributor access via a grant token set with `setGrantToken`.
  *
  * @see docs/attestations.md
  */
@@ -211,22 +213,49 @@ export declare namespace attestations {
      */
     function publicList(collectionId: string, params: ListAttestationsParams): Promise<PublicListAttestationsResponse>;
     /**
-     * Create an OWNER-authored attestation (public write) — the counterpart to the
-     * admin {@link create}. The authenticated caller must OWN the linked proof
-     * (identity, not a read grant). Guardrails enforced server-side: they may write
-     * `value` + `ownerData` only (`adminData` is dropped), `visibility` is clamped
-     * to `'public' | 'owner'`, and `authorId` is forced to the caller. The record
-     * joins the same tamper-evident hash chain.
+     * Create a public attestation — the counterpart to the admin {@link create}.
+     * Authorised two ways, same call (the server decides from the request):
+     *   1. the proof OWNER (identity, via `Authorization: Bearer <Firebase ID token>`)
+     *      adds an attestation to their own item; or
+     *   2. a holder of a `contribute`-scope grant adds one — call
+     *      {@link setGrantToken} with the grant token first; for a public-link
+     *      (anonymous) grant, pass `guestName` for attribution.
+     *
+     * Guardrails (server-enforced): `value` + `ownerData` only (`adminData` dropped),
+     * `visibility` clamped to `'public' | 'owner'`, `authorId`/`grantId` server-stamped.
+     * If the contribute grant was issued with `moderate: true`, the returned record
+     * has `moderationStatus: 'pending'` — held to the owner until {@link moderate}.
+     * The record joins the same tamper-evident hash chain.
      * POST /public/collection/:collectionId/attestations
      * ```ts
+     * // Owner:
      * await attestations.publicCreate('coll_123', {
      *   subjectType: 'proof', subjectId: 'proof_1',
      *   attestationType: 'condition-report',
      *   value: { grade: 'excellent' }, visibility: 'public',
      * })
+     * // Contributor on a shared link:
+     * setGrantToken(shareToken)
+     * await attestations.publicCreate('coll_123', {
+     *   subjectType: 'proof', subjectId: 'proof_1',
+     *   attestationType: 'photo', value: { url }, visibility: 'public',
+     *   guestName: 'Sam',
+     * })
      * ```
      */
     function publicCreate(collectionId: string, data: OwnerAttestationInput): Promise<CreateOwnerAttestationResponse>;
+    /**
+     * Moderate a contributed attestation (proof OWNER by identity, or collection
+     * admin). `'approve'` releases it to its declared visibility; `'reject'` keeps
+     * it author + admin only. Only the `moderationStatus` changes — the hashed fact
+     * and its chain are untouched. Find pending items with
+     * {@link publicList} + `moderationStatus: 'pending'`.
+     * POST /public/collection/:collectionId/attestations/:attestationId/moderate
+     * ```ts
+     * await attestations.moderate('coll_123', 'att_uuid', { decision: 'approve' })
+     * ```
+     */
+    function moderate(collectionId: string, attestationId: string, input: ModerateAttestationInput): Promise<ModerateAttestationResponse>;
     /**
      * Time-series summary (public).
      *

package/dist/api/attestations.js

@@ -26,9 +26,11 @@ function buildAttestationQuery(params) {
  *   admin session or bearer token.  All three data zones are returned, and the
  *   business can write any zone/visibility ({@link create}).
  * - **Public** endpoints (`/public/collection/:id/attestations`) are read-only,
- *   EXCEPT {@link publicCreate}: the proof OWNER may author an attestation on
- *   their own item (value + ownerData, visibility public|owner — never the admin
- *   zone). Owner elevation is via `Authorization: Bearer <Firebase ID token>`.
+ *   EXCEPT {@link publicCreate} (the proof OWNER, or a `contribute`-grant holder,
+ *   authors an attestation — value + ownerData, visibility public|owner, never the
+ *   admin zone) and {@link moderate} (owner/admin approves or rejects a contributed
+ *   record). Owner elevation is via `Authorization: Bearer <Firebase ID token>`;
+ *   contributor access via a grant token set with `setGrantToken`.
  *
  * @see docs/attestations.md
  */
@@ -277,19 +279,34 @@ export var attestations;
     }
     attestations.publicList = publicList;
     /**
-     * Create an OWNER-authored attestation (public write) — the counterpart to the
-     * admin {@link create}. The authenticated caller must OWN the linked proof
-     * (identity, not a read grant). Guardrails enforced server-side: they may write
-     * `value` + `ownerData` only (`adminData` is dropped), `visibility` is clamped
-     * to `'public' | 'owner'`, and `authorId` is forced to the caller. The record
-     * joins the same tamper-evident hash chain.
+     * Create a public attestation — the counterpart to the admin {@link create}.
+     * Authorised two ways, same call (the server decides from the request):
+     *   1. the proof OWNER (identity, via `Authorization: Bearer <Firebase ID token>`)
+     *      adds an attestation to their own item; or
+     *   2. a holder of a `contribute`-scope grant adds one — call
+     *      {@link setGrantToken} with the grant token first; for a public-link
+     *      (anonymous) grant, pass `guestName` for attribution.
+     *
+     * Guardrails (server-enforced): `value` + `ownerData` only (`adminData` dropped),
+     * `visibility` clamped to `'public' | 'owner'`, `authorId`/`grantId` server-stamped.
+     * If the contribute grant was issued with `moderate: true`, the returned record
+     * has `moderationStatus: 'pending'` — held to the owner until {@link moderate}.
+     * The record joins the same tamper-evident hash chain.
      * POST /public/collection/:collectionId/attestations
      * ```ts
+     * // Owner:
      * await attestations.publicCreate('coll_123', {
      *   subjectType: 'proof', subjectId: 'proof_1',
      *   attestationType: 'condition-report',
      *   value: { grade: 'excellent' }, visibility: 'public',
      * })
+     * // Contributor on a shared link:
+     * setGrantToken(shareToken)
+     * await attestations.publicCreate('coll_123', {
+     *   subjectType: 'proof', subjectId: 'proof_1',
+     *   attestationType: 'photo', value: { url }, visibility: 'public',
+     *   guestName: 'Sam',
+     * })
      * ```
      */
     async function publicCreate(collectionId, data) {
@@ -297,6 +314,22 @@ export var attestations;
         return post(path, data);
     }
     attestations.publicCreate = publicCreate;
+    /**
+     * Moderate a contributed attestation (proof OWNER by identity, or collection
+     * admin). `'approve'` releases it to its declared visibility; `'reject'` keeps
+     * it author + admin only. Only the `moderationStatus` changes — the hashed fact
+     * and its chain are untouched. Find pending items with
+     * {@link publicList} + `moderationStatus: 'pending'`.
+     * POST /public/collection/:collectionId/attestations/:attestationId/moderate
+     * ```ts
+     * await attestations.moderate('coll_123', 'att_uuid', { decision: 'approve' })
+     * ```
+     */
+    async function moderate(collectionId, attestationId, input) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/attestations/${encodeURIComponent(attestationId)}/moderate`;
+        return post(path, input);
+    }
+    attestations.moderate = moderate;
     /**
      * Time-series summary (public).
      *

package/dist/api/index.d.ts

@@ -37,6 +37,8 @@ export { containers } from "./containers";
 export { lots } from "./lots";
 export { loyalty } from "./loyalty";
 export { translations } from "./translations";
+export { integrations } from "./integrations";
+export { secrets } from "./secrets";
 export { config } from "./config";
 export { http } from "./http";
 export { navigation } from "./navigation";

package/dist/api/index.js

@@ -40,6 +40,8 @@ export { containers } from "./containers";
 export { lots } from "./lots";
 export { loyalty } from "./loyalty";
 export { translations } from "./translations";
+export { integrations } from "./integrations";
+export { secrets } from "./secrets";
 export { config } from "./config";
 export { http } from "./http";
 export { navigation } from "./navigation";

package/dist/api/integrations.d.ts

@@ -0,0 +1,28 @@
+import type { IntegrationFlow, CreateFlowInput, UpdateFlowInput, ListFlowsQuery, FlowList, RunFlowInput, RunFlowResult, RunFlowSummary, RunFlowEnqueued } from "../types/integrations";
+export declare namespace integrations {
+    /** List flows in a collection. GET /integrations/flows */
+    function listFlows(collectionId: string, query?: ListFlowsQuery): Promise<FlowList>;
+    /** Create a flow. POST /integrations/flows */
+    function createFlow(collectionId: string, input: CreateFlowInput): Promise<IntegrationFlow>;
+    /** Get one flow. GET /integrations/flows/:id */
+    function getFlow(collectionId: string, id: string): Promise<IntegrationFlow>;
+    /** Update whitelisted fields. PUT /integrations/flows/:id */
+    function updateFlow(collectionId: string, id: string, input: UpdateFlowInput): Promise<IntegrationFlow>;
+    /** Soft-delete a flow. DELETE /integrations/flows/:id */
+    function deleteFlow(collectionId: string, id: string): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Run a flow now. POST /integrations/flows/:id/run
+     *   - inline (default): resolves and returns the run summary.
+     *   - options.async: enqueue on the worker, returns { enqueued: true }.
+     * Pass options.entityId to run for a single source entity.
+     */
+    function runFlow(collectionId: string, id: string, options?: RunFlowInput & {
+        async?: boolean;
+    }): Promise<RunFlowResult>;
+    /** Type guard: the run executed inline and returned a summary. */
+    function isRunSummary(r: RunFlowResult): r is RunFlowSummary;
+    /** Type guard: the run was enqueued (async). */
+    function isRunEnqueued(r: RunFlowResult): r is RunFlowEnqueued;
+}

package/dist/api/integrations.js

@@ -0,0 +1,82 @@
+// src/api/integrations.ts
+//
+// Integration flow management + execution. Flows model input/output pipelines
+// (inbound: fetch external -> write entity; outbound: read entity -> transform ->
+// send). Credentials live in the secret store (see the `secrets` namespace); a flow
+// only carries an opaque credentialRef in config.connection.auth.
+//
+// Endpoints: /admin/collection/:collectionId/integrations/flows
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { request, post, put, del } from "../http";
+function enc(v) { return encodeURIComponent(v); }
+function encodeQuery(params = {}) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        search.set(key, typeof value === "boolean" ? (value ? "true" : "false") : String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+}
+export var integrations;
+(function (integrations) {
+    const base = (collectionId) => `/admin/collection/${enc(collectionId)}/integrations/flows`;
+    /** List flows in a collection. GET /integrations/flows */
+    async function listFlows(collectionId, query = {}) {
+        return request(`${base(collectionId)}${encodeQuery(query)}`);
+    }
+    integrations.listFlows = listFlows;
+    /** Create a flow. POST /integrations/flows */
+    async function createFlow(collectionId, input) {
+        return post(base(collectionId), input);
+    }
+    integrations.createFlow = createFlow;
+    /** Get one flow. GET /integrations/flows/:id */
+    async function getFlow(collectionId, id) {
+        return request(`${base(collectionId)}/${enc(id)}`);
+    }
+    integrations.getFlow = getFlow;
+    /** Update whitelisted fields. PUT /integrations/flows/:id */
+    async function updateFlow(collectionId, id, input) {
+        return put(`${base(collectionId)}/${enc(id)}`, input);
+    }
+    integrations.updateFlow = updateFlow;
+    /** Soft-delete a flow. DELETE /integrations/flows/:id */
+    async function deleteFlow(collectionId, id) {
+        return del(`${base(collectionId)}/${enc(id)}`);
+    }
+    integrations.deleteFlow = deleteFlow;
+    /**
+     * Run a flow now. POST /integrations/flows/:id/run
+     *   - inline (default): resolves and returns the run summary.
+     *   - options.async: enqueue on the worker, returns { enqueued: true }.
+     * Pass options.entityId to run for a single source entity.
+     */
+    async function runFlow(collectionId, id, options = {}) {
+        const { async: runAsync } = options, body = __rest(options, ["async"]);
+        const qs = runAsync ? "?async=true" : "";
+        return post(`${base(collectionId)}/${enc(id)}/run${qs}`, body);
+    }
+    integrations.runFlow = runFlow;
+    /** Type guard: the run executed inline and returned a summary. */
+    function isRunSummary(r) {
+        return r.status !== undefined;
+    }
+    integrations.isRunSummary = isRunSummary;
+    /** Type guard: the run was enqueued (async). */
+    function isRunEnqueued(r) {
+        return r.enqueued === true;
+    }
+    integrations.isRunEnqueued = isRunEnqueued;
+})(integrations || (integrations = {}));

package/dist/api/proof.js

@@ -222,6 +222,9 @@ export var proof;
             body.audience = options.audience;
         if (options.expiresAt)
             body.expiresAt = options.expiresAt instanceof Date ? options.expiresAt.toISOString() : options.expiresAt;
+        // Only applied server-side when scope includes 'contribute'.
+        if (options.moderate !== undefined)
+            body.moderate = options.moderate;
         return post(grantBase(collectionId, productId, proofId), body);
     }
     proof.createGrant = createGrant;

package/dist/api/secrets.d.ts

@@ -0,0 +1,15 @@
+import type { SecretMeta, SecretList, SetSecretInput, SetSecretResult, ListSecretsQuery } from "../types/integrations";
+export declare namespace secrets {
+    /** List secrets as refs + masked hints + metadata (never values). GET /secrets */
+    function list(collectionId: string, query?: ListSecretsQuery): Promise<SecretList>;
+    /** Create a secret. POST /secrets → { ref, hint }. Store the ref on a flow. */
+    function set(collectionId: string, input: SetSecretInput): Promise<SetSecretResult>;
+    /** Metadata for one secret (never the value). GET /secrets/:ref */
+    function get(collectionId: string, ref: string): Promise<SecretMeta>;
+    /** Rotate/update a secret's value (and optionally name/purpose). PUT /secrets/:ref → { ref, hint } */
+    function rotate(collectionId: string, ref: string, input: SetSecretInput): Promise<SetSecretResult>;
+    /** Soft-delete a secret. DELETE /secrets/:ref */
+    function remove(collectionId: string, ref: string): Promise<{
+        deleted: boolean;
+    }>;
+}

package/dist/api/secrets.js

@@ -0,0 +1,52 @@
+// src/api/secrets.ts
+//
+// Sealed-secret store — the credentials that back integration flows and other
+// server-side handlers. WRITE-ONLY from the client: you can set, rotate, list
+// (refs + masked hints + metadata) and delete, but a value NEVER comes back over the
+// API. It is sealed at rest and resolved server-side only, at execution time.
+//
+// Typical use: `set` a credential, take the returned `ref`, and put it on a flow's
+// config.connection.auth.credentialRef.
+//
+// Endpoints: /admin/collection/:collectionId/secrets
+import { request, post, put, del } from "../http";
+function enc(v) { return encodeURIComponent(v); }
+function encodeQuery(params = {}) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        search.set(key, String(value));
+    }
+    const qs = search.toString();
+    return qs ? `?${qs}` : "";
+}
+export var secrets;
+(function (secrets) {
+    const base = (collectionId) => `/admin/collection/${enc(collectionId)}/secrets`;
+    /** List secrets as refs + masked hints + metadata (never values). GET /secrets */
+    async function list(collectionId, query = {}) {
+        return request(`${base(collectionId)}${encodeQuery(query)}`);
+    }
+    secrets.list = list;
+    /** Create a secret. POST /secrets → { ref, hint }. Store the ref on a flow. */
+    async function set(collectionId, input) {
+        return post(base(collectionId), input);
+    }
+    secrets.set = set;
+    /** Metadata for one secret (never the value). GET /secrets/:ref */
+    async function get(collectionId, ref) {
+        return request(`${base(collectionId)}/${enc(ref)}`);
+    }
+    secrets.get = get;
+    /** Rotate/update a secret's value (and optionally name/purpose). PUT /secrets/:ref → { ref, hint } */
+    async function rotate(collectionId, ref, input) {
+        return put(`${base(collectionId)}/${enc(ref)}`, input);
+    }
+    secrets.rotate = rotate;
+    /** Soft-delete a secret. DELETE /secrets/:ref */
+    async function remove(collectionId, ref) {
+        return del(`${base(collectionId)}/${enc(ref)}`);
+    }
+    secrets.remove = remove;
+})(secrets || (secrets = {}));