@homespunapps/core 1.0.1 → 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
@@ -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,32 @@ export declare class HomespunClient {
         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,
@@ -421,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 {
@@ -442,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 {
@@ -450,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;
 }
@@ -460,6 +733,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 +771,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 +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;
@@ -523,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
@@ -548,6 +978,30 @@ 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;
+}
 export interface PublishCommunityTemplateRequest {
     /** The owned app to publish. */
     appId: string;
@@ -555,22 +1009,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 +1088,127 @@ 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;
+}
+/** 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 {

package/dist/client.js

@@ -143,6 +143,25 @@ export class HomespunClient {
         if (!r.ok)
             this.fail(r);
     }
+    /**
+     * 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.
+     */
+    async mintKey() {
+        const r = await this.call("POST", "/v1/keys");
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /**
      * 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
@@ -510,6 +529,33 @@ export class HomespunClient {
             this.fail(r);
         return this.asObject(r);
     }
+    /**
+     * 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.
+     */
+    async checkDeploy(req) {
+        const path = req.app_id !== undefined
+            ? `/v1/apps/${encodeURIComponent(req.app_id)}/versions`
+            : "/v1/apps";
+        const body = {
+            html: req.html,
+            manifest: req.manifest,
+            dry_run: true,
+        };
+        if (req.app_id !== undefined && req.force !== undefined)
+            body["force"] = req.force;
+        if (req.assets !== undefined)
+            body["assets"] = req.assets;
+        const r = await this.call("POST", path, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /**
      * 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
@@ -538,9 +584,37 @@ export class HomespunClient {
             this.fail(r);
         return this.asObject(r);
     }
-    /** PATCH /v1/apps/:id — update visibility (the only mutable app field). */
-    async updateApp(appId, visibility) {
-        const r = await this.call("PATCH", `/v1/apps/${encodeURIComponent(appId)}`, { visibility });
+    /**
+     * 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).
+     */
+    async updateApp(appId, update) {
+        const body = {};
+        if (update.visibility !== undefined)
+            body["visibility"] = update.visibility;
+        if (update.timezone !== undefined)
+            body["timezone"] = update.timezone;
+        const r = await this.call("PATCH", `/v1/apps/${encodeURIComponent(appId)}`, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * 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.
+     */
+    async rotateShareLink(appId) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/share-link/rotate`, {});
         if (!r.ok)
             this.fail(r);
         return this.asObject(r);
@@ -613,7 +687,7 @@ export class HomespunClient {
      * EMAIL_PROVIDER=none (no invite-email path available).
      */
     async addAppMember(appId, opts) {
-        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/members`, { email: opts.email, role: opts.role });
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/members`, { email: opts.email, role: opts.role, custom_role: opts.customRole });
         if (!r.ok)
             this.fail(r);
         return this.asObject(r);
@@ -625,6 +699,39 @@ export class HomespunClient {
             this.fail(r);
         return this.asObject(r);
     }
+    /**
+     * 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.
+     */
+    async setAppMemberRole(appId, humanId, opts) {
+        const r = await this.call("PATCH", `/v1/apps/${encodeURIComponent(appId)}/members/${encodeURIComponent(humanId)}`, { custom_role: opts.customRole });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * 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.
+     */
+    async listAppRoles(appId) {
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/roles`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /**
      * DELETE /v1/apps/:id/members/:humanId — remove a member (idempotent);
      * cascades to revoke that human's live app sessions. The app owner cannot
@@ -636,17 +743,106 @@ export class HomespunClient {
             this.fail(r);
     }
     // -------------------------------------------------------------------------
+    // Inbound catch-hooks (inbound-webhooks PR 3). Read + rotate the smallest
+    // surface an agent needs: list an app's declared hooks with their full secret
+    // URL (so the agent can tell its owner the exact URL to paste into an external
+    // system during app setup), and rotate a leaked secret. Hooks themselves are
+    // manifest-declared, so there is no create/delete here.
+    // -------------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    async listIngestHooks(appId) {
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/ingest-hooks`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * 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.
+     */
+    async rotateIngestHook(appId, name) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/ingest-hooks/${encodeURIComponent(name)}/rotate`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    // -------------------------------------------------------------------------
+    // v2 grant links (M5). An owner/agent mints a capability URL carrying a
+    // DECLARED custom role (x-homespun-manifest.roles) plus an optional row/filter
+    // pin. The raw link token rides the returned grant_url's FRAGMENT (#g=), never
+    // a query param, so it is never logged; the page SDK exchanges it once for a
+    // per-holder credential. A grant can NEVER carry a built-in role and never
+    // escalates past its custom role on a stable per-holder identity.
+    // -------------------------------------------------------------------------
+    /**
+     * 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.
+     */
+    async mintAppGrant(appId, opts) {
+        const pin = opts.pin
+            ? opts.pin.rowKey !== undefined
+                ? { row_key: opts.pin.rowKey }
+                : { where: opts.pin.where }
+            : undefined;
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/grants`, {
+            role: opts.role,
+            mode: opts.mode,
+            max_uses: opts.maxUses,
+            label: opts.label,
+            ttl_seconds: opts.ttlSeconds,
+            pin,
+        });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** GET /v1/apps/:id/grants: list the app's grant links (never any token). */
+    async listAppGrants(appId) {
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/grants`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** DELETE /v1/apps/:id/grants/:grantId: revoke one grant link (idempotent). */
+    async revokeAppGrant(appId, grantId) {
+        const r = await this.call("DELETE", `/v1/apps/${encodeURIComponent(appId)}/grants/${encodeURIComponent(grantId)}`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    // -------------------------------------------------------------------------
     // v2 collection row CRUD + feed catch-up (spec-cli §2.2/§2.3). Same wire
     // shapes as the v1 homespun-records methods above, mounted under
     // /v1/apps/:id/collections/:name instead of /v1/apps/:id/records/:name.
     // -------------------------------------------------------------------------
-    /** GET /v1/apps/:id/collections/:name — list rows (current-state page). */
+    /**
+     * 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.
+     */
     async listAppRows(appId, collection, opts = {}) {
         const q = new URLSearchParams();
         if (opts.since !== undefined)
             q.set("since", opts.since);
         if (opts.limit !== undefined)
             q.set("limit", String(opts.limit));
+        const query = buildListQueryParam(opts.where, opts.sort);
+        if (query !== undefined)
+            q.set("q", query);
         const qs = q.toString();
         const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}${qs ? "?" + qs : ""}`);
         if (!r.ok)
@@ -676,6 +872,26 @@ export class HomespunClient {
             this.fail(r);
         return this.asObject(r);
     }
+    /**
+     * 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.
+     */
+    async upsertAppRowOn(appId, collection, field, data) {
+        return this.upsertAppRow(appId, collection, { on: field, data });
+    }
+    /**
+     * 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.
+     */
+    async purgeAppRow(appId, collection, key) {
+        const r = await this.call("DELETE", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(key)}/purge`);
+        if (!r.ok)
+            this.fail(r);
+    }
     /** PATCH /v1/apps/:id/collections/:name/:key — optimistic-locked update. */
     async updateAppRow(appId, collection, key, body) {
         const r = await this.call("PATCH", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}/${encodeURIComponent(key)}`, body);
@@ -690,6 +906,37 @@ export class HomespunClient {
         if (!r.ok)
             this.fail(r);
     }
+    /**
+     * 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.
+     */
+    async batchRows(appId, collection, rows, opts = {}) {
+        const body = { rows };
+        if (opts.suppress !== undefined)
+            body.suppress = opts.suppress;
+        if (opts.emitEffects !== undefined)
+            body.emitEffects = opts.emitEffects;
+        if (opts.on !== undefined)
+            body.on = opts.on;
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}/batch`, body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/apps/:id/collections/:name/batch: bulk soft-delete (Wave B).
+     * Same per-row result shape + cap as `batchRows`.
+     */
+    async deleteRows(appId, collection, keys) {
+        const r = await this.call("DELETE", `/v1/apps/${encodeURIComponent(appId)}/collections/${encodeURIComponent(collection)}/batch`, { keys });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /**
      * 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
@@ -718,8 +965,15 @@ export class HomespunClient {
             app_id: req.appId,
             title: req.title,
             description: req.description,
+            long_description: req.longDescription,
             category: req.category,
             tags: req.tags,
+            slug: req.slug,
+            version: req.version,
+            changelog_note: req.changelogNote,
+            setup_steps: req.setupSteps,
+            derived_from_snapshot_id: req.derivedFromSnapshotId,
+            attest_example_only: req.attestExampleOnly,
         });
         if (!r.ok)
             this.fail(r);
@@ -757,4 +1011,107 @@ export class HomespunClient {
             this.fail(r);
         return this.asObject(r);
     }
+    // -------------------------------------------------------------------------
+    // Community publisher identity (marketplace PR 1). All three act AS the
+    // calling agent's owning human. claim/update additionally need a verified
+    // email server-side.
+    // -------------------------------------------------------------------------
+    /** GET /v1/publisher: the caller's own publisher profile. */
+    async getPublisher() {
+        const r = await this.call("GET", "/v1/publisher");
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** POST /v1/publisher/claim: set the handle once (permanent after claiming). */
+    async claimPublisherHandle(handle) {
+        const r = await this.call("POST", "/v1/publisher/claim", { handle });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** POST /v1/publisher/update: update displayName/bio/url. */
+    async updatePublisher(update) {
+        const r = await this.call("POST", "/v1/publisher/update", {
+            display_name: update.displayName,
+            bio: update.bio,
+            url: update.url,
+        });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * 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.
+     */
+    async setPublisherTrustLevel(handle, trustLevel) {
+        const r = await this.call("POST", `/v1/community/publishers/${encodeURIComponent(handle)}/trust`, { trust_level: trustLevel });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    // -------------------------------------------------------------------------
+    // Community reviews (marketplace PR 7). createReview / respondToReview /
+    // reportReview act AS the calling agent's owning human; the moderation
+    // methods (removeReview / unholdReview) are operator-gated server-side.
+    // -------------------------------------------------------------------------
+    /**
+     * POST /v1/reviews: review a template the caller installed. Identify the
+     * template by its namespaced `<handle>/<slug>` OR by explicit handle + slug.
+     */
+    async createReview(req) {
+        const r = await this.call("POST", "/v1/reviews", {
+            template: req.template,
+            handle: req.handle,
+            slug: req.slug,
+            stars: req.stars,
+            body: req.body,
+        });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** POST /v1/reviews/:id/respond: respond to a review as the publisher. */
+    async respondToReview(reviewId, response) {
+        const r = await this.call("POST", `/v1/reviews/${encodeURIComponent(reviewId)}/respond`, { response });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** POST /v1/reviews/:id/report: flag a review for operator attention. */
+    async reportReview(reviewId, reason) {
+        const r = await this.call("POST", `/v1/reviews/${encodeURIComponent(reviewId)}/report`, { reason });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** POST /v1/reviews/:id/remove (operator): take a review down. */
+    async removeReview(reviewId) {
+        const r = await this.call("POST", `/v1/reviews/${encodeURIComponent(reviewId)}/remove`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** POST /v1/reviews/:id/unhold (operator): publish a held review. */
+    async unholdReview(reviewId) {
+        const r = await this.call("POST", `/v1/reviews/${encodeURIComponent(reviewId)}/unhold`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+}
+// Serialize `where`/`sort` into the `q` query param (URL-encoded JSON), or
+// undefined when neither is given. URLSearchParams handles the percent-encoding.
+function buildListQueryParam(where, sort) {
+    const q = {};
+    if (where !== undefined && where.length > 0)
+        q.where = where;
+    if (sort !== undefined && sort.length > 0)
+        q.sort = sort;
+    if (q.where === undefined && q.sort === undefined)
+        return undefined;
+    return JSON.stringify(q);
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { HomespunClient, HomespunApiError } from "./client.js";
-export type { ClientOptions, RelayResponse, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, QueryResponse, AppAsset, DeployAppRequest, DeployAppResponse, RedeployAppRequest, RedeployAppResponse, AppSummary, AppDetail, AppsPage, AppDomain, AppDomainDnsRecord, AppMember, AddAppMemberResult, AppRow, AppRowsPage, AppFeedEntry, AppFeedPage, } from "./client.js";
+export type { ClientOptions, RelayResponse, AttachmentRef, UploadBlobOptions, PresignBlobOptions, AttachmentTokenMintResponse, ListBlobsOptions, AttachmentTokenAuditEntry, AttachmentTokenListResponse, QueryResponse, AppAsset, DeployAppRequest, DeployAppResponse, RedeployAppRequest, RedeployAppResponse, DeployCheckRequest, DeployCheckResult, KeyMintResult, AppSummary, AppDetail, AppsPage, AppDomain, AppDomainDnsRecord, AppMember, AddAppMemberResult, AppRow, AppRowsPage, ListScalar, ListWhereCondition, ListSortSpec, BatchRowInput, BatchRowResult, BatchResult, BatchWriteOptions, AppFeedEntry, AppFeedPage, CommunitySetupStep, } from "./client.js";
 export { openStream } from "./stream.js";
 export type { OpenStreamOptions, StreamHandlers, StreamHandle, } from "./stream.js";
 export { openAppStream, appWsUrlFromAppUrl } from "./app-stream.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/core",
-  "version": "1.0.1",
+  "version": "1.4.2",
   "description": "Homespun relay client: typed HTTP + WebSocket operations against a Homespun relay. Framework-free.",
   "license": "MIT",
   "type": "module",
@@ -11,9 +11,9 @@
     "relay",
     "human-in-the-loop"
   ],
-  "homepage": "https://homespun.dev",
+  "homepage": "https://docs.homespun.dev",
   "bugs": {
-    "url": "mailto:support@homespun.dev"
+    "url": "https://github.com/homespunapps/homespun/issues"
   },
   "engines": {
     "node": ">=20"
@@ -41,13 +41,18 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "ws": "^8.20.1",
+    "ws": "^8.21.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.9.2",
+    "@types/node": "^26.1.1",
     "@types/ws": "^8.18.1",
-    "typescript": "^6.0.3",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/homespunapps/homespun.git",
+    "directory": "packages/core"
   }
 }