@homespunapps/core 1.0.1 → 1.4.3

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
@@ -258,6 +272,16 @@ export declare class HomespunClient {
     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
@@ -271,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>;
@@ -310,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
@@ -343,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;
@@ -358,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
@@ -386,6 +553,48 @@ export declare class HomespunClient {
         decision: "approve" | "reject";
         note?: string;
     }): Promise<CommunitySubmissionDetail>;
+    /**
+     * GET /v1/community/templates/:ref/config-contract: the install-time config
+     * contract for an installable template (its settings collection + the ordered
+     * keyed config/upload steps). Use it to discover what a template needs and to
+     * pre-upload files for `upload` steps (POST /v1/attachments) before install.
+     */
+    getCommunityConfigContract(ref: string): Promise<CommunityConfigContract>;
+    /**
+     * POST /v1/community/templates/:ref/install: install a community template for
+     * the calling agent's owning human. `config` is `{ [stepKey]: value }` where a
+     * `config` step's value is a string and an `upload` step's value is an
+     * attachment id the agent pre-uploaded (agent-scoped) via `uploadBlob()` /
+     * `uploadBlobInline()`; the relay re-points it to the new app on install.
+     * Installs always create; returns the new app's id, slug, and url.
+     */
+    installCommunityTemplate(ref: string, config?: Record<string, unknown>): Promise<CommunityInstallResult>;
+    /** 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,
@@ -421,6 +630,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 {
@@ -442,6 +665,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 {
@@ -450,6 +733,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;
 }
@@ -460,6 +749,12 @@ 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[];
@@ -492,7 +787,70 @@ 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
@@ -505,6 +863,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;
@@ -523,6 +907,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
@@ -548,6 +994,85 @@ export interface AppFeedPage {
     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;
+    /**
+     * The manifest `ingest` rule this step wires up (D7). Allowed ONLY on a
+     * `connect` step, optional there. Publish rejects a name the manifest does
+     * not declare. After install, the installer pastes that rule's freshly
+     * provisioned hook URL into the external service.
+     */
+    ingestRule?: string;
+}
+/**
+ * One keyed config/upload step in a template's install-time config contract
+ * (install-config programme, PR 4). Field names are the wire shape (snake_case
+ * `value_hint`). An `upload` step's answer is an attachment id string.
+ */
+export interface CommunityConfigStep {
+    key: string;
+    kind: "config" | "upload";
+    label: string;
+    description?: string;
+    required: boolean;
+    secret: boolean;
+    choices?: string[];
+    default?: string;
+    value_hint?: string;
+}
+/**
+ * One `connect` step in a template's contract that wires up an INBOUND hook:
+ * after install, the app's own freshly provisioned hook URL for `ingest_rule`
+ * has to be pasted into the external service the step describes. Read the URLs
+ * from `GET /v1/apps/:app_id/ingest-hooks` once the install returns.
+ */
+export interface CommunityConnectStep {
+    label: string;
+    description?: string;
+    ingest_rule: string;
+    /** Collection the hook writes into, or null when the rule went missing. */
+    collection: string | null;
+    mode: "append" | "upsert" | null;
+}
+/** The install-time config contract for an installable community template. */
+export interface CommunityConfigContract {
+    snapshot_id: string;
+    name: string;
+    slug: string | null;
+    /** The manifest's declared settings collection, or null when none. */
+    settings_collection: string | null;
+    /** Ordered keyed config/upload steps; empty when the template needs none. */
+    config_steps: CommunityConfigStep[];
+    /** Ordered connect steps that name an ingest rule; empty when none. */
+    connect_steps: CommunityConnectStep[];
+}
+/** Result of an agent-key community install (installs always create). */
+export interface CommunityInstallResult {
+    app_id: string;
+    slug: string;
+    url: string;
+}
 export interface PublishCommunityTemplateRequest {
     /** The owned app to publish. */
     appId: string;
@@ -555,22 +1080,77 @@ export interface PublishCommunityTemplateRequest {
     title?: string;
     /** Listing blurb; defaults server-side to the manifest description. */
     description?: string;
-    /** Optional single-word category. */
+    /**
+     * 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";
@@ -579,20 +1159,147 @@ export interface CommunitySubmissionSummary {
     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;
+    /**
+     * Every external destination the manifest declares (D6 disclosure): outbound
+     * webhook targets, the app's fetch allowance and its framing allowance,
+     * deduplicated and HOSTS ONLY, so a reviewer sees where the app can send
+     * data without reading the raw manifest. Empty when it talks to nothing
+     * outside Homespun.
+     */
+    external_destinations: CommunityExternalDestination[];
+}
+/** One disclosed external destination on a submission (D6). */
+export interface CommunityExternalDestination {
+    /** `webhook` = the relay POSTs row data there; `fetch` / `embed` = the app's
+     *  own page may call or frame it. */
+    kind: "webhook" | "embed" | "fetch";
+    /** Destination host, or null when the manifest alone cannot name it. */
+    host: string | null;
+    /** Settings field an install-time webhook target is read from. */
+    fromSetting?: string;
+    /** Stored connection a relative webhook target resolves against. */
+    viaConnection?: string;
+}
+/** 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 {