@homespunapps/core 1.0.0 → 1.4.2

package/dist/client.d.ts

@@ -90,6 +90,20 @@ export declare class HomespunClient {
      * self-destruct. Returns 204 with no body on success.
      */
     revokeKey(id: string): Promise<void>;
+    /**
+     * POST /v1/keys: mint a NEW sibling API key for the calling agent's OWN
+     * identity. The relay derives the identity from the bearer token, so a caller
+     * can only ever mint a sibling of itself (never another agent's key). The new
+     * key has the same scope/ownership as the caller and shows up in a subsequent
+     * `listKeys()` call made WITH the new key.
+     *
+     * The raw `api_key` is returned exactly ONCE in this response and is never
+     * retrievable again (only its hash is stored). Bootstraps a fresh CLI /
+     * process credential from an MCP-driven agent that has no key of its own to
+     * hand off. The owner can revoke any minted sibling via the normal revoke
+     * path.
+     */
+    mintKey(): Promise<KeyMintResult>;
     /**
      * POST /v1/agents/claim — bind this agent to a human via a one-shot
      * claim code the human generated in their settings UI. After a
@@ -159,6 +173,25 @@ export declare class HomespunClient {
      * stream bytes through the relay.
      */
     uploadBlob(file: Blob | Buffer | Uint8Array, opts?: UploadBlobOptions): Promise<AttachmentRef>;
+    /**
+     * Upload a attachment from INLINE base64 bytes: the no-filesystem sibling of
+     * `uploadBlob()`. Use this when the bytes were produced in memory (an image
+     * the agent generated, a document it assembled) and there is no local file to
+     * stream: an MCP client running inside a Claude session has no filesystem to
+     * point `uploadBlob()` at.
+     *
+     * The bytes are sent as base64 in a JSON body to the relay's
+     * `POST /v1/attachments` inline variant ({ content_base64, filename?, mime?,
+     * scope?, app_id? }). The relay decodes them behind a pre-decode size guard and runs
+     * the IDENTICAL validation pipeline the multipart `uploadBlob()` path runs:
+     * magic-byte MIME sniff, BLOB_MIME_ALLOWLIST, per-attachment size cap, and the
+     * per-agent / per-app / per-account quota reservation. `mime` is advisory
+     * (the relay sniffs the real type regardless), and an oversized or disallowed
+     * inline upload returns the same errors the file path would.
+     *
+     * @param contentBase64 standard base64 (e.g. `Buffer.from(bytes).toString("base64")`).
+     */
+    uploadBlobInline(contentBase64: string, opts?: UploadBlobOptions): Promise<AttachmentRef>;
     /** GET /v1/attachments/:id — download bytes as an ArrayBuffer. */
     downloadBlob(attachmentId: string): Promise<ArrayBuffer>;
     /**
@@ -219,12 +252,36 @@ export declare class HomespunClient {
         upload_url: string;
         expires_at: string;
     }>;
-    /** Finalise a presigned upload — relay HEADs the bytes, verifies, flips ready. */
+    /**
+     * Finalise a presigned upload. After the client PUTs the bytes to the
+     * `upload_url` from `presignBlob()`, the relay re-reads the stored bytes and
+     * runs the SAME validation a normal upload runs: it BYTE-SNIFFS the actual
+     * content and derives the stored/served mime from that (never the
+     * presign-declared mime), re-verifies size + sha256, enforces the allowlist +
+     * quota, and runs the scan hook, before flipping the attachment to `ready`.
+     * A finalize whose bytes fail any check leaves the attachment unready (it is
+     * never served) and returns a clean error. Returns the ready `AttachmentRef`.
+     */
     confirmBlob(attachmentId: string): Promise<AttachmentRef>;
+    /**
+     * Alias for {@link confirmBlob}: the "finalize" half of the presign ->
+     * PUT -> finalize flow, named to match the MCP `attachments` action.
+     */
+    finalizeBlob(attachmentId: string): Promise<AttachmentRef>;
     /** POST /v1/apps — create (deploy) a new App + its first AppVersion. */
     deployApp(req: DeployAppRequest): Promise<DeployAppResponse>;
     /** POST /v1/apps/:id/versions — redeploy (compat-gated unless force). */
     redeployApp(appId: string, req: RedeployAppRequest): Promise<RedeployAppResponse>;
+    /**
+     * Dry-run a deploy: validate the manifest + asset shapes, run the compat gate
+     * (for a redeploy) and compute the deploy advisories, WITHOUT creating a
+     * version or mutating anything. Posts the deploy body with `dry_run: true` to
+     * the same route the real deploy uses (`POST /v1/apps` for a create check,
+     * `POST /v1/apps/:id/versions` for a redeploy check), so the relay returns the
+     * SAME validation error a real deploy would for an invalid manifest, and the
+     * SAME warnings/compat result for a valid one. Nothing is persisted.
+     */
+    checkDeploy(req: DeployCheckRequest): Promise<DeployCheckResult>;
     /**
      * GET /v1/apps — list apps scoped to the calling agent's owning human.
      * `slug` is an exact-match filter — the one case a caller resolves a
@@ -238,10 +295,35 @@ export declare class HomespunClient {
     }): Promise<AppsPage>;
     /** GET /v1/apps/:id — full app detail (manifest, current_version, quota). */
     getApp(appId: string): Promise<AppDetail>;
-    /** PATCH /v1/apps/:id — update visibility (the only mutable app field). */
-    updateApp(appId: string, visibility: "private" | "link" | "public"): Promise<{
+    /**
+     * PATCH /v1/apps/:id updates the app's mutable settings. Both fields are
+     * optional but at least one must be given: `visibility` (private|link|public)
+     * and/or `timezone` (an IANA zone name like "Europe/Berlin", used for
+     * `schedules` reminders). Returns the updated `{ id, visibility, timezone }`.
+     * A transition INTO `link` visibility also returns a `share_url` carrying the
+     * app's freshly minted share token in its `#k=` fragment, shown ONCE (the
+     * token is hashed at rest and never recoverable). A transition AWAY from
+     * `link` clears the token (every prior share URL stops working).
+     */
+    updateApp(appId: string, update: {
+        visibility?: "private" | "link" | "public";
+        timezone?: string;
+    }): Promise<{
         id: string;
         visibility: string;
+        timezone: string | null;
+        share_url?: string;
+    }>;
+    /**
+     * POST /v1/apps/:id/share-link/rotate rotates a `link` app's share token.
+     * Mints a fresh token and returns the new `share_url` (its `#k=` fragment
+     * carries the raw token, shown ONCE). Rotating instantly revokes the previous
+     * share URL and every pass derived from it. Also serves as "generate" for a
+     * `link` app that has no share token yet. Only valid for a `link` app; a
+     * public/private app returns a conflict.
+     */
+    rotateShareLink(appId: string): Promise<{
+        share_url: string;
     }>;
     /** DELETE /v1/apps/:id — soft-delete (idempotent). */
     deleteApp(appId: string): Promise<void>;
@@ -250,6 +332,23 @@ export declare class HomespunClient {
         id: string;
         status: string;
     }>;
+    /**
+     * POST /v1/apps/:id/domain - bind a custom domain to the app. Returns the
+     * record including `dns_records`: the DNS entries the domain owner must
+     * publish (the routing CNAME plus any Cloudflare validation records).
+     */
+    setAppDomain(appId: string, domain: string): Promise<AppDomain>;
+    /**
+     * GET /v1/apps/:id/domain - the app's domain record, live-refreshed against
+     * Cloudflare when the feature is enabled (status/last_error/last_checked_at
+     * update as a side effect).
+     */
+    getAppDomain(appId: string): Promise<AppDomain>;
+    /**
+     * DELETE /v1/apps/:id/domain - remove the domain binding (Cloudflare
+     * hostname best-effort + record + quota release). Idempotent.
+     */
+    deleteAppDomain(appId: string): Promise<void>;
     /**
      * POST /v1/apps/:id/members — add or invite a member by email. If a Human
      * already exists for the email, the member row is created immediately
@@ -260,21 +359,107 @@ export declare class HomespunClient {
     addAppMember(appId: string, opts: {
         email: string;
         role?: "member";
+        customRole?: string;
     }): Promise<AddAppMemberResult>;
     /** GET /v1/apps/:id/members — list the app's owner + member rows. */
     listAppMembers(appId: string): Promise<{
         members: AppMember[];
     }>;
+    /**
+     * PATCH /v1/apps/:id/members/:humanId — change an existing member's custom
+     * role in place. `customRole: null` clears it back to a plain member. The
+     * role must be one the app's manifest declares (a reserved base role or an
+     * undeclared name is a 400), and the app owner's own membership cannot be
+     * re-roled.
+     *
+     * Unlike remove-then-re-add, this does NOT revoke the member's live app
+     * sessions: they stay signed in and pick up the new role on their next
+     * request. Roles are not cached: they are re-derived from the Member row on
+     * every request, so a downgrade takes effect immediately and a live session
+     * can never escalate.
+     */
+    setAppMemberRole(appId: string, humanId: string, opts: {
+        customRole: string | null;
+    }): Promise<{
+        member: AppMember;
+    }>;
+    /**
+     * GET /v1/apps/:id/roles — the derived roles summary: every custom role the
+     * app's manifest declares, what holding it actually allows per collection
+     * (reported separately for members and for grant-link holders, whose role
+     * floors differ), and how many members and live grant links hold it.
+     * Read-only and computed on the fly; permissions themselves stay
+     * manifest-declared. An app that declares no roles returns an empty list.
+     */
+    listAppRoles(appId: string): Promise<{
+        roles: AppRoleSummary[];
+    }>;
     /**
      * DELETE /v1/apps/:id/members/:humanId — remove a member (idempotent);
      * cascades to revoke that human's live app sessions. The app owner cannot
      * be removed — the relay refuses with a 409 conflict.
      */
     removeAppMember(appId: string, humanId: string): Promise<void>;
-    /** GET /v1/apps/:id/collections/:name — list rows (current-state page). */
+    /**
+     * GET /v1/apps/:id/ingest-hooks lists the app's inbound catch-hooks with the
+     * full secret URL (decrypted server-side), the current rule metadata
+     * (collection/mode/wake/handshake), and per-hook delivery counts by status.
+     * The URL is the app owner's to share with a sender; it is never exposed on a
+     * public path, only here to the app's own owner/agent.
+     */
+    listIngestHooks(appId: string): Promise<{
+        hooks: IngestHookInfo[];
+    }>;
+    /**
+     * POST /v1/apps/:id/ingest-hooks/:name/rotate mints a fresh secret for one
+     * hook and return its new full URL once. No redeploy needed; the old URL stops
+     * working immediately.
+     */
+    rotateIngestHook(appId: string, name: string): Promise<{
+        hook: {
+            name: string;
+            url: string;
+        };
+    }>;
+    /**
+     * POST /v1/apps/:id/grants: mint a grant link. `role` must be a declared
+     * custom role for the app. `mode` is "once" (one-time, first-browser-claims)
+     * or "multi" (shared, capped by `maxUses` within expiry); defaults to "multi".
+     * An optional `pin` NARROWS the holder to a single `rowKey` OR a `where`
+     * filter (never widens). Returns the once-only `grant_url` carrying the token.
+     */
+    mintAppGrant(appId: string, opts: {
+        role: string;
+        mode?: "once" | "multi";
+        maxUses?: number;
+        label?: string;
+        ttlSeconds?: number;
+        pin?: {
+            rowKey?: string;
+            where?: ListWhereCondition[];
+        };
+    }): Promise<MintAppGrantResult>;
+    /** GET /v1/apps/:id/grants: list the app's grant links (never any token). */
+    listAppGrants(appId: string): Promise<{
+        grants: AppGrantSummary[];
+    }>;
+    /** DELETE /v1/apps/:id/grants/:grantId: revoke one grant link (idempotent). */
+    revokeAppGrant(appId: string, grantId: string): Promise<void>;
+    /**
+     * GET /v1/apps/:id/collections/:name — list rows (current-state page).
+     *
+     * Wave C2 structured read query: pass `where` (an AND of `{field, op, value}`
+     * conditions) and/or `sort` (`{field, dir}` list) to filter/order DB-side. The
+     * relay applies read permission + author scoping FIRST, then the filter, so a
+     * filtered read is always a subset of what the caller could already read. The
+     * query is serialized into the `q` param as URL-encoded JSON. Note: a custom
+     * `sort` cannot be combined with cursor pagination (`since`) in this version.
+     */
     listAppRows(appId: string, collection: string, opts?: {
         since?: string;
         limit?: number;
+        where?: ListWhereCondition[];
+        sort?: ListSortSpec[];
     }): Promise<AppRowsPage>;
     /**
      * GET /v1/apps/:id/collections/:name/:key — read one row. A dedicated
@@ -293,10 +478,28 @@ export declare class HomespunClient {
     upsertAppRow(appId: string, collection: string, body: {
         key?: string;
         data: unknown;
+        on?: string;
     }): Promise<{
         row: AppRow;
         deduped?: true;
     }>;
+    /**
+     * POST /v1/apps/:id/collections/:name with `{ on, data }`, natural-key upsert
+     * (Wave C1). Matches the existing row whose `<field>` value equals data[field]
+     * and updates it in place (idempotent re-import), else creates a fresh row.
+     * `field` must be declared in the collection's manifest `unique` list.
+     */
+    upsertAppRowOn(appId: string, collection: string, field: string, data: unknown): Promise<{
+        row: AppRow;
+        deduped?: true;
+    }>;
+    /**
+     * DELETE /v1/apps/:id/collections/:name/:key/purge, owner/agent-only removal
+     * that bypasses an append-only collection (Wave C1). Frees the row's unique
+     * values and writes an audited delete feed entry. A missing/already-deleted key
+     * is a 404 (HomespunApiError `row_not_found`), matching a normal delete.
+     */
+    purgeAppRow(appId: string, collection: string, key: string): Promise<void>;
     /** PATCH /v1/apps/:id/collections/:name/:key — optimistic-locked update. */
     updateAppRow(appId: string, collection: string, key: string, body: {
         data: unknown;
@@ -308,6 +511,20 @@ export declare class HomespunClient {
     deleteAppRow(appId: string, collection: string, key: string, opts?: {
         ifMatch?: number;
     }): Promise<void>;
+    /**
+     * POST /v1/apps/:id/collections/:name/batch: bulk create/upsert (Wave B).
+     * Returns a per-row result array: a single invalid row is reported by index
+     * without aborting the good rows. A batch over the server's BATCH_MAX_ROWS cap
+     * is a clean 400 (throws HomespunApiError `invalid_request`). DEFAULTS TO
+     * SILENT (suppresses notify + webhooks): pass `{emitEffects:true}` or
+     * `{suppress:[]}` to fire effects. Owner/agent key only for suppression control.
+     */
+    batchRows(appId: string, collection: string, rows: BatchRowInput[], opts?: BatchWriteOptions): Promise<BatchResult>;
+    /**
+     * DELETE /v1/apps/:id/collections/:name/batch: bulk soft-delete (Wave B).
+     * Same per-row result shape + cap as `batchRows`.
+     */
+    deleteRows(appId: string, collection: string, keys: string[]): Promise<BatchResult>;
     /**
      * GET /v1/apps/:id/feed — change-feed catch-up; the long-poll fallback
      * transport for `watch` (spec-cli §2.3/§5). `wait` (0-30s) long-polls when
@@ -318,6 +535,61 @@ export declare class HomespunClient {
         limit?: number;
         wait?: number;
     }): Promise<AppFeedPage>;
+    /** POST /v1/community/publish: publish an owned app as a pending template. */
+    publishCommunityTemplate(req: PublishCommunityTemplateRequest): Promise<PublishCommunityTemplateResponse>;
+    /** GET /v1/community/pending (operator): list pending submissions. */
+    listCommunitySubmissions(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<CommunitySubmissionsPage>;
+    /** GET /v1/community/submissions/:id (operator): a submission's full content. */
+    getCommunitySubmission(snapshotId: string): Promise<CommunitySubmissionDetail>;
+    /**
+     * POST /v1/community/submissions/:id/{approve,reject} (operator): review a
+     * submission. `decision` "reject" requires a `note` (delivered to the
+     * publisher's app feed).
+     */
+    reviewCommunitySubmission(snapshotId: string, review: {
+        decision: "approve" | "reject";
+        note?: string;
+    }): Promise<CommunitySubmissionDetail>;
+    /** GET /v1/publisher: the caller's own publisher profile. */
+    getPublisher(): Promise<PublisherProfile>;
+    /** POST /v1/publisher/claim: set the handle once (permanent after claiming). */
+    claimPublisherHandle(handle: string): Promise<PublisherProfile>;
+    /** POST /v1/publisher/update: update displayName/bio/url. */
+    updatePublisher(update: PublisherProfileUpdate): Promise<PublisherProfile>;
+    /**
+     * POST /v1/community/publishers/:handle/trust (operator, marketplace PR 11):
+     * set a publisher's trust level ("new" | "established"), the MVP promotion
+     * path for the review fast-track. Operator-gated server-side; returns the
+     * updated publisher profile.
+     */
+    setPublisherTrustLevel(handle: string, trustLevel: "new" | "established"): Promise<PublisherProfile>;
+    /**
+     * POST /v1/reviews: review a template the caller installed. Identify the
+     * template by its namespaced `<handle>/<slug>` OR by explicit handle + slug.
+     */
+    createReview(req: CreateCommunityReviewRequest): Promise<CommunityReview>;
+    /** POST /v1/reviews/:id/respond: respond to a review as the publisher. */
+    respondToReview(reviewId: string, response: string | null): Promise<CommunityReview>;
+    /** POST /v1/reviews/:id/report: flag a review for operator attention. */
+    reportReview(reviewId: string, reason: string): Promise<CommunityReviewReportResult>;
+    /** POST /v1/reviews/:id/remove (operator): take a review down. */
+    removeReview(reviewId: string): Promise<CommunityReview>;
+    /** POST /v1/reviews/:id/unhold (operator): publish a held review. */
+    unholdReview(reviewId: string): Promise<CommunityReview>;
+}
+/**
+ * One multi-file-deploy asset: bytes the deployed page references by a stable,
+ * app-relative, same-origin path (e.g. `frames/000.jpg`). `content_base64` is the
+ * standard base64 of the raw bytes; `mime` is advisory (the relay sniffs the
+ * real type from the leading bytes).
+ */
+export interface AppAsset {
+    path: string;
+    content_base64: string;
+    mime?: string;
 }
 /** Request body for `POST /v1/apps` — create (deploy) a new App. */
 export interface DeployAppRequest {
@@ -327,6 +599,13 @@ export interface DeployAppRequest {
     visibility?: "private" | "link" | "public";
     /** Accepted for visibility public|private (including the omitted default); rejected for link. */
     slug?: string;
+    /**
+     * Optional asset bundle shipped alongside the HTML in ONE deploy. Each asset
+     * is validated + stored app-scoped exactly like an attachment and served at
+     * its `path` on the app's own origin, so `<img src="frames/000.jpg">` just
+     * works. Rejected atomically if any asset fails validation.
+     */
+    assets?: AppAsset[];
 }
 export interface DeployAppResponse {
     app_id: string;
@@ -335,6 +614,20 @@ export interface DeployAppResponse {
     url: string;
     version: number;
     created: true;
+    /**
+     * The tokenized share URL, present ONLY when the app was created as `link`. Its
+     * `#k=` fragment carries the raw share token and is shown exactly ONCE (the
+     * token is hashed at rest and never recoverable). Anyone with this exact URL
+     * can open the app until it is rotated (`rotateShareLink`).
+     */
+    share_url?: string;
+    /**
+     * Non-fatal deploy advisories, present only when there is at least one. Today
+     * the schedules-without-timezone case: an app that declares `schedules` but has
+     * no timezone set will fire reminders at 08:00 UTC until one is set. Relay these
+     * to the human.
+     */
+    warnings?: string[];
 }
 /** Request body for `POST /v1/apps/:id/versions` — redeploy (compat-gated). */
 export interface RedeployAppRequest {
@@ -342,6 +635,11 @@ export interface RedeployAppRequest {
     manifest: unknown;
     /** Bypass the compat gate; a narrowing collection is detached, not deleted. */
     force?: boolean;
+    /**
+     * Optional asset bundle for this version. Replaces the previous version's asset
+     * set atomically (the new version carries its own map; old assets are detached).
+     */
+    assets?: AppAsset[];
 }
 export interface RedeployAppResponse {
     app_id: string;
@@ -351,6 +649,66 @@ export interface RedeployAppResponse {
         path: string;
         message: string;
     }>;
+    /**
+     * Non-fatal deploy advisories, present only when there is at least one; see
+     * DeployAppResponse.warnings. On redeploy the schedules-without-timezone
+     * warning fires only when the app STILL has no timezone set.
+     */
+    warnings?: string[];
+}
+/**
+ * Result of a DRY-RUN deploy (`checkDeploy`): the deploy validation + compat
+ * gate run WITHOUT creating a version or mutating anything. Mirrors what a real
+ * deploy would report: the manifest is validated (a structurally invalid
+ * manifest throws the SAME error a real deploy would), asset shapes are checked,
+ * the schedule-timezone / migration-mode advisories are computed, and (for a
+ * redeploy) the compat gate runs against the current version.
+ *
+ *   - `ok` is true when a REAL deploy with the same inputs would succeed: a
+ *     clean deploy, or a narrowing redeploy with `force: true`. It is false
+ *     when a real un-forced redeploy would be REJECTED for narrowing the
+ *     manifest (see `compat: "incompatible"` + `breaks`).
+ *   - `compat` is present only for a redeploy check: "clean" (no narrowing),
+ *     "forced" (narrows, but force was set so the real deploy would detach and
+ *     proceed), or "incompatible" (narrows and force was NOT set, so the real
+ *     deploy would return manifest_incompatible_redeploy).
+ *   - `breaks` lists the narrowings, present only when there is at least one.
+ */
+export interface DeployCheckResult {
+    ok: boolean;
+    warnings: string[];
+    compat?: "clean" | "forced" | "incompatible";
+    breaks?: Array<{
+        path: string;
+        message: string;
+    }>;
+}
+/**
+ * Request for a dry-run deploy check. Omit `app_id` to check a CREATE; pass it
+ * to check a REDEPLOY of an existing app (the compat gate then runs against its
+ * current version, and `force` decides whether a narrowing would be accepted).
+ */
+export interface DeployCheckRequest {
+    app_id?: string;
+    html: string;
+    manifest: unknown;
+    force?: boolean;
+    assets?: AppAsset[];
+}
+/**
+ * Result of minting a sibling API key for the calling agent's own identity
+ * (`mintKey`). The raw `api_key` is returned exactly ONCE here and is never
+ * retrievable again (only its hash is stored). The new key has the same
+ * scope/ownership as the caller and can be revoked by the owner via the normal
+ * revoke path.
+ */
+export interface KeyMintResult {
+    agent_id: string;
+    /** The raw sibling key, shown ONCE, never returned again. */
+    api_key: string;
+    key_prefix: string;
+    name: string | null;
+    created_at: string;
 }
 /** Lean per-app summary — the shape `listApps` returns. */
 export interface AppSummary {
@@ -359,6 +717,12 @@ export interface AppSummary {
     visibility: string;
     status: string;
     url: string;
+    /**
+     * Whether the app currently has an active share token (a `link` app with a
+     * live, revocable share link). NEVER the token itself: the raw token is
+     * returned only at create/rotate. False for public/private apps.
+     */
+    has_share_token: boolean;
     created_at: string;
     last_activity_at: string;
 }
@@ -369,11 +733,35 @@ export interface AppDetail extends AppSummary {
     owner_human_id: string;
     row_count: number;
     storage_bytes: string;
+    /**
+     * The app's IANA timezone for `schedules` reminders, or null when unset. Set
+     * it with `updateApp(id, { timezone })`; an app that declares schedules with no
+     * timezone fires reminders at 08:00 UTC.
+     */
+    timezone: string | null;
 }
 export interface AppsPage {
     items: AppSummary[];
     next_cursor: string | null;
 }
+/** One DNS record the domain owner must publish (custom domains). */
+export interface AppDomainDnsRecord {
+    type: string;
+    name: string;
+    value: string;
+    purpose: "routing" | "ownership" | "certificate_validation";
+}
+/** The app's custom-domain record - the shape the /domain routes return. */
+export interface AppDomain {
+    domain: string;
+    status: "pending" | "active" | "error" | "removed";
+    dns_records: AppDomainDnsRecord[];
+    cf_hostname_id: string | null;
+    last_error: string | null;
+    last_checked_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
 /**
  * One member row — the shape `listAppMembers` returns and the `member` half
  * of `addAppMember`'s union returns. Fields are camelCase on the wire (see
@@ -383,8 +771,71 @@ export interface AppMember {
     humanId: string;
     email: string;
     role: string;
+    /** M5: an optional DECLARED custom role attached alongside base member powers. */
+    customRole?: string | null;
     createdAt: string;
 }
+/**
+ * One inbound catch-hook row from `listIngestHooks`. `url` is the full secret
+ * ingest URL to hand a sender. Rule-derived fields (collection/mode/wake/
+ * handshake) are null when the hook's rule has left the manifest (disabledAt
+ * set). `deliveries` are per-status counts of the hook's inbound journal.
+ */
+export interface IngestHookInfo {
+    name: string;
+    url: string;
+    collection: string | null;
+    mode: string | null;
+    wake: boolean | null;
+    handshake: string | null;
+    disabledAt: string | null;
+    createdAt: string;
+    deliveries: {
+        accepted: number;
+        failed: number;
+        dropped_duplicate: number;
+    };
+}
+/**
+ * Effective per-verb access from `listAppRoles`: "all" = every row, "own" =
+ * only rows the holder authored (the `:own` / author narrowing), "none" =
+ * nothing. `create` is never "own" (no pre-existing row to be the author of).
+ * The relay computes these by probing its real enforcement functions, so they
+ * report what a holder can ACTUALLY do, including floors like `anyone`.
+ */
+export interface AppRoleVerbAccess {
+    read: "all" | "own" | "none";
+    create: "all" | "none";
+    update: "all" | "own" | "none";
+    delete: "all" | "own" | "none";
+}
+/**
+ * One collection's access from `listAppRoles`, reported PER POPULATION:
+ * `member_access` is what a signed-in member holding the role can do (their
+ * principal also carries the member floor), `grant_access` what a grant-link
+ * holder of the same role can do (no member floor, so the two can differ).
+ * `append_only` is context: such a collection refuses update/delete for every
+ * role while still allowing create, and the access tables reflect that.
+ */
+export interface AppRoleCollectionAccess {
+    name: string;
+    member_access: AppRoleVerbAccess;
+    grant_access: AppRoleVerbAccess;
+    append_only: boolean;
+}
+/**
+ * One declared custom role from `listAppRoles`. `member_count` and
+ * `active_grant_count` are separate numbers, never summed: members are
+ * signed-in Humans, grant-link holders are anonymous per-holder identities.
+ */
+export interface AppRoleSummary {
+    name: string;
+    label: string;
+    description: string | null;
+    collections: AppRoleCollectionAccess[];
+    member_count: number;
+    active_grant_count: number;
+}
 /**
  * `POST /v1/apps/:id/members` response — either the member was attached
  * immediately (existing Human) or an invite email was sent (no Human yet).
@@ -396,6 +847,32 @@ export type AddAppMemberResult = {
     invited: string;
     expires_at: string;
 };
+/** `POST /v1/apps/:id/grants` response. `grant_url` carries the raw link token
+ * in its #g= fragment and is shown ONCE (it is never recoverable afterward). */
+export interface MintAppGrantResult {
+    id: string;
+    grant_url: string;
+    role: string;
+    mode: string;
+    max_uses: number | null;
+    expires_at: string;
+}
+/** One grant-link row from `listAppGrants` (never carries any token material). */
+export interface AppGrantSummary {
+    id: string;
+    role: string;
+    mode: string;
+    max_uses: number | null;
+    use_count: number;
+    claim_count: number;
+    pin_row_key: string | null;
+    pin_where: unknown;
+    label: string | null;
+    active: boolean;
+    expires_at: string;
+    revoked_at: string | null;
+    created_at: string;
+}
 /** One row in an app collection — the shape every row CRUD op returns. */
 export interface AppRow {
     key: string;
@@ -414,6 +891,68 @@ export interface AppRowsPage {
     next_cursor: string | null;
     has_more: boolean;
 }
+/** A scalar operand for a structured read-query condition (Wave C2). */
+export type ListScalar = string | number | boolean;
+/**
+ * One structured read-query condition (Wave C2). `op` is one of eq / neq / in /
+ * notIn / gt / lt / gte / lte, with the SAME type semantics as a notify `when`:
+ * comparisons are same-type only (a number never matches a string operand), and
+ * dates are compared as ISO-8601 strings. `value` is a single scalar for the
+ * scalar ops and a non-empty scalar array for `in`/`notIn`.
+ */
+export interface ListWhereCondition {
+    field: string;
+    op: "eq" | "neq" | "in" | "notIn" | "gt" | "lt" | "gte" | "lte";
+    value: ListScalar | ListScalar[];
+}
+/** One structured read-query sort key (Wave C2). `dir` defaults to "asc". */
+export interface ListSortSpec {
+    field: string;
+    dir?: "asc" | "desc";
+}
+/** One row of a batch write (Wave B). `key` absent => create; present => upsert. */
+export interface BatchRowInput {
+    key?: string;
+    data: unknown;
+}
+/**
+ * The outcome of one row in a batch, addressed by its `index` in the input array
+ * so a caller maps a failure back to the exact row it sent. `ok:true` carries the
+ * written `key`; `ok:false` carries the per-row `error`.
+ */
+export interface BatchRowResult {
+    index: number;
+    ok: boolean;
+    key?: string;
+    error?: {
+        code: string;
+        message: string;
+        status: number;
+        details?: unknown;
+    };
+}
+/** The batch write / delete envelope: per-row results plus convenience counts. */
+export interface BatchResult {
+    results: BatchRowResult[];
+    ok_count: number;
+    error_count: number;
+}
+/**
+ * Effect-suppression options for a batch (silent migration, Wave B). The batch
+ * endpoint DEFAULTS to silent (suppresses both notify and webhooks). Pass
+ * `emitEffects:true` (or `suppress:[]`) to fire effects, or `suppress` to mute a
+ * specific subset. Honored only for an owner/agent key.
+ */
+export interface BatchWriteOptions {
+    suppress?: ("notify" | "webhooks")[];
+    emitEffects?: boolean;
+    /**
+     * Wave C1 natural-key upsert: match (or create) each row on this
+     * declared-unique field's value instead of the row id, making a re-import
+     * idempotent. Mutually exclusive with per-row `key`.
+     */
+    on?: string;
+}
 /**
  * One entry in an app's change feed — the SAME shape whether it arrives via
  * `GET /v1/apps/:id/feed` (long-poll) or the `/_hs/ws` live/batch frames
@@ -438,6 +977,239 @@ export interface AppFeedPage {
     cursor: number;
     truncated: boolean;
 }
+/** Request body for `publishCommunityTemplate()`. */
+/**
+ * One typed agent-setup step (marketplace PR 9). An ordered list of these tells
+ * an installing agent what to configure after install. Carries only the
+ * publisher's own defaults + hints, never an installer's value; `secret: true`
+ * marks a step whose eventual value is sensitive (its default is masked on the
+ * public detail page). The relay validates + normalizes on publish.
+ */
+export interface CommunitySetupStep {
+    kind: "config" | "seed-data" | "connect" | "note" | "upload";
+    label: string;
+    description?: string;
+    required?: boolean;
+    secret?: boolean;
+    default?: string;
+    choices?: string[];
+    valueHint?: string;
+    /**
+     * The settings-collection field this step's answer is written into
+     * (install-config programme). Required for an `upload` step, optional for a
+     * `config` step, and not allowed on the other kinds. Field-key identifier
+     * (letters, digits, '_', up to 64 chars).
+     */
+    key?: string;
+}
+export interface PublishCommunityTemplateRequest {
+    /** The owned app to publish. */
+    appId: string;
+    /** Listing title; defaults server-side to the app's manifest name. */
+    title?: string;
+    /** Listing blurb; defaults server-side to the manifest description. */
+    description?: string;
+    /**
+     * Optional long-form description (template-experience PR 5a): richer prose
+     * rendered on the detail page below the short blurb. Plain text, length-capped
+     * server-side; blank lines become escaped paragraph breaks (never raw HTML).
+     */
+    longDescription?: string;
+    /** Optional category (validated server-side against the fixed enum). */
+    category?: string;
+    /** Optional curation tags. */
+    tags?: string[];
+    /**
+     * Optional per-publisher slug (marketplace PR 2). When set, the template gets
+     * a namespaced id `<handle>/<slug>` and joins a versioned line.
+     */
+    slug?: string;
+    /** Optional semver version; defaults server-side to "1.0.0". */
+    version?: string;
+    /** Optional note recorded in this version's changelog entry. */
+    changelogNote?: string;
+    /**
+     * Optional ordered typed setup steps (marketplace PR 9). Validated + stored
+     * server-side; read back through the detail page + get_submission.
+     */
+    setupSteps?: CommunitySetupStep[];
+    /** Optional remix/fork lineage: the snapshot id this was derived from. */
+    derivedFromSnapshotId?: string;
+    /**
+     * The example-only attestation (marketplace PR 10). Set true to attest the
+     * captured template content AND its captured seed rows contain no real
+     * personal data: publishing makes both PUBLIC to all platform users. Recorded
+     * (not a hard gate) and surfaced to the operator review payload; omitting it
+     * still publishes but is shown to the reviewer as "not attested".
+     */
+    attestExampleOnly?: boolean;
+}
+export interface PublishCommunityTemplateResponse {
+    snapshot_id: string;
+    review_status: "pending" | "approved" | "rejected";
+    name: string;
+    seeded_row_count: number;
+    slug: string | null;
+    version: string;
+    /** How many typed setup steps were stored (marketplace PR 9). */
+    setup_step_count: number;
+    /**
+     * The example-only attestation as recorded (marketplace PR 10): true/false as
+     * attested, or null when the publish carried no attestation.
+     */
+    attest_example_only: boolean | null;
+    /**
+     * Fast-track outcome (marketplace PR 11). `expedited`: the publisher is
+     * `established` and the submission still landed `pending`, flagged to sort
+     * first in the operator review queue. `auto_approved`: the publisher is
+     * `established` AND the relay enables true auto-approve, so it was approved
+     * immediately at publish (review_status === "approved"). Both false for a
+     * `new` publisher (ordinary full review).
+     */
+    expedited: boolean;
+    auto_approved: boolean;
+}
+/** A pending-submission summary in the operator review queue. */
+export interface CommunitySubmissionSummary {
+    snapshot_id: string;
+    name: string;
+    description: string | null;
+    /**
+     * Publisher-provided long-form description (template-experience PR 5a),
+     * surfaced in the review payload so the operator sees the full prose that
+     * renders on the detail page. Null when the publish carried none.
+     */
+    long_description: string | null;
+    category: string | null;
+    tags: string[];
+    review_status: "pending" | "approved" | "rejected";
+    publisher_human_id: string | null;
+    publisher_name: string | null;
+    source_app_id: string | null;
+    seeded_row_count: number;
+    published_at: string;
+    /** Namespaced identity + version (marketplace PR 2); null when unset. */
+    slug: string | null;
+    version: string | null;
+    /**
+     * Publish-time PII attestation (marketplace PR 10): true/false as attested by
+     * the publisher, or null when the publish carried no attestation. Surfaced in
+     * the review queue so a missing attestation is visible to the operator.
+     */
+    attest_example_only: boolean | null;
+    /**
+     * Fast-track flag (marketplace PR 11): true when this pending submission was
+     * expedited (published by an `established` publisher, sorted first in the
+     * queue). False for a `new` publisher and pre-PR-11 rows.
+     */
+    expedited: boolean;
+    /** The publisher's trust level (marketplace PR 11): "new" | "established". */
+    publisher_trust_level: string;
+}
+export interface CommunitySubmissionsPage {
+    items: CommunitySubmissionSummary[];
+    next_cursor: string | null;
+}
+/** One collection's captured-seed footprint (marketplace PR 10). */
+export interface CommunitySeedCollectionSummary {
+    collection: string;
+    row_count: number;
+    bytes: number;
+}
+/** A per-collection digest of a submission's captured seed rows (PR 10). */
+export interface CommunitySeedRowSummary {
+    collections: CommunitySeedCollectionSummary[];
+    total_rows: number;
+    total_bytes: number;
+}
+/** A submission's FULL content, for operator review. */
+export interface CommunitySubmissionDetail extends CommunitySubmissionSummary {
+    html: string;
+    manifest: unknown;
+    seed_rows: unknown;
+    /**
+     * A digest of seed_rows (marketplace PR 10): per-collection row counts + byte
+     * sizes plus totals, so the operator sees how much (and which) captured
+     * starter data would become public without parsing the raw rows.
+     */
+    seed_summary: CommunitySeedRowSummary;
+    version_id: string | null;
+    reviewed_at: string | null;
+    review_note: string | null;
+    superseded_at: string | null;
+    /** Namespaced identity + fork/license fields (marketplace PR 2). */
+    changelog: unknown;
+    license: string | null;
+    license_terms: string | null;
+    derived_from_snapshot_id: string | null;
+    /**
+     * Typed agent-setup steps (marketplace PR 9): the machine-readable structure
+     * an agent reads. Full structure incl. secret-flagged steps (a step stores
+     * only the publisher's default/hint, never an installer value). `null` when
+     * the template declares no steps.
+     */
+    setup_steps: CommunitySetupStep[] | null;
+}
+/** A publisher's own profile, as returned by the `/v1/publisher` routes. */
+export interface PublisherProfile {
+    handle: string;
+    display_name: string | null;
+    bio: string | null;
+    url: string | null;
+    /** True once the handle has been claimed (and is therefore permanent). */
+    claimed: boolean;
+    claimed_at: string | null;
+    created_at: string;
+    first_published_at: string | null;
+    approved_template_count: number;
+    rating_count: number;
+    rating_sum: number;
+    trust_level: string;
+}
+/**
+ * The mutable profile fields for `updatePublisher()`. A field left `undefined`
+ * is untouched; `null` clears it.
+ */
+export interface PublisherProfileUpdate {
+    displayName?: string | null;
+    bio?: string | null;
+    url?: string | null;
+}
+/** Request body for `createReview()`. Give `template` OR (`handle` + `slug`). */
+export interface CreateCommunityReviewRequest {
+    /** Namespaced template id, "<handle>/<slug>". */
+    template?: string;
+    /** Publisher handle (with `slug`, as an alternative to `template`). */
+    handle?: string;
+    /** Per-publisher slug (with `handle`). */
+    slug?: string;
+    /** Star rating, integer 1..5. */
+    stars: number;
+    /** Optional written review body. */
+    body?: string;
+}
+/** A review as returned by the `/v1/reviews` routes. */
+export interface CommunityReview {
+    id: string;
+    template_publisher_human_id: string;
+    template_slug: string | null;
+    snapshot_id: string;
+    install_id: string | null;
+    reviewer_human_id: string;
+    stars: number;
+    body: string | null;
+    /** "visible" | "held" | "removed". A body with a link/email lands "held". */
+    status: string;
+    held_reason: string | null;
+    publisher_response: string | null;
+    publisher_responded_at: string | null;
+    created_at: string;
+}
+/** Result of `reportReview()`. */
+export interface CommunityReviewReportResult {
+    report_id: string;
+    review_id: string;
+}
 /** Per-attachment metadata as returned by `POST /v1/attachments` and friends. */
 export interface AttachmentRef {
     attachment_id: string;