@homespunapps/core 1.0.0 → 1.4.2

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
@@ -305,6 +324,39 @@ export class HomespunClient {
         }
         return data;
     }
+    /**
+     * Upload a attachment from INLINE base64 bytes: the no-filesystem sibling of
+     * `uploadBlob()`. Use this when the bytes were produced in memory (an image
+     * the agent generated, a document it assembled) and there is no local file to
+     * stream: an MCP client running inside a Claude session has no filesystem to
+     * point `uploadBlob()` at.
+     *
+     * The bytes are sent as base64 in a JSON body to the relay's
+     * `POST /v1/attachments` inline variant ({ content_base64, filename?, mime?,
+     * scope?, app_id? }). The relay decodes them behind a pre-decode size guard and runs
+     * the IDENTICAL validation pipeline the multipart `uploadBlob()` path runs:
+     * magic-byte MIME sniff, BLOB_MIME_ALLOWLIST, per-attachment size cap, and the
+     * per-agent / per-app / per-account quota reservation. `mime` is advisory
+     * (the relay sniffs the real type regardless), and an oversized or disallowed
+     * inline upload returns the same errors the file path would.
+     *
+     * @param contentBase64 standard base64 (e.g. `Buffer.from(bytes).toString("base64")`).
+     */
+    async uploadBlobInline(contentBase64, opts = {}) {
+        const body = { content_base64: contentBase64 };
+        if (opts.scope)
+            body.scope = opts.scope;
+        if (opts.appId)
+            body.app_id = opts.appId;
+        if (opts.filename)
+            body.filename = opts.filename;
+        if (opts.mime)
+            body.mime = opts.mime;
+        const r = await this.call("POST", "/v1/attachments", body);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
     /** GET /v1/attachments/:id — download bytes as an ArrayBuffer. */
     async downloadBlob(attachmentId) {
         const url = this.base + "/v1/attachments/" + encodeURIComponent(attachmentId);
@@ -424,13 +476,29 @@ export class HomespunClient {
             this.fail(r);
         return r.data;
     }
-    /** Finalise a presigned upload — relay HEADs the bytes, verifies, flips ready. */
+    /**
+     * Finalise a presigned upload. After the client PUTs the bytes to the
+     * `upload_url` from `presignBlob()`, the relay re-reads the stored bytes and
+     * runs the SAME validation a normal upload runs: it BYTE-SNIFFS the actual
+     * content and derives the stored/served mime from that (never the
+     * presign-declared mime), re-verifies size + sha256, enforces the allowlist +
+     * quota, and runs the scan hook, before flipping the attachment to `ready`.
+     * A finalize whose bytes fail any check leaves the attachment unready (it is
+     * never served) and returns a clean error. Returns the ready `AttachmentRef`.
+     */
     async confirmBlob(attachmentId) {
         const r = await this.call("POST", "/v1/attachments/" + encodeURIComponent(attachmentId) + "/confirm");
         if (!r.ok)
             this.fail(r);
         return r.data;
     }
+    /**
+     * Alias for {@link confirmBlob}: the "finalize" half of the presign ->
+     * PUT -> finalize flow, named to match the MCP `attachments` action.
+     */
+    async finalizeBlob(attachmentId) {
+        return this.confirmBlob(attachmentId);
+    }
     // -------------------------------------------------------------------------
     // v2 app lifecycle (spec-cli §2.1). `:id` on every route below is always the
     // App.id (cuid) — a slug is resolved to an id via `listApps({ slug })`
@@ -443,6 +511,7 @@ export class HomespunClient {
             manifest: req.manifest,
             visibility: req.visibility,
             slug: req.slug,
+            assets: req.assets,
         });
         if (!r.ok)
             this.fail(r);
@@ -450,7 +519,39 @@ export class HomespunClient {
     }
     /** POST /v1/apps/:id/versions — redeploy (compat-gated unless force). */
     async redeployApp(appId, req) {
-        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/versions`, { html: req.html, manifest: req.manifest, force: req.force });
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/versions`, {
+            html: req.html,
+            manifest: req.manifest,
+            force: req.force,
+            assets: req.assets,
+        });
+        if (!r.ok)
+            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);
@@ -483,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);
@@ -504,6 +633,42 @@ export class HomespunClient {
         return this.asObject(r);
     }
     // -------------------------------------------------------------------------
+    // Custom domains (Cloudflare for SaaS). One primary domain per app. The
+    // relay rejects setAppDomain with `custom_domains_not_enabled` (501) when
+    // the deployment has no Cloudflare configuration.
+    // -------------------------------------------------------------------------
+    /**
+     * POST /v1/apps/:id/domain - bind a custom domain to the app. Returns the
+     * record including `dns_records`: the DNS entries the domain owner must
+     * publish (the routing CNAME plus any Cloudflare validation records).
+     */
+    async setAppDomain(appId, domain) {
+        const r = await this.call("POST", `/v1/apps/${encodeURIComponent(appId)}/domain`, { domain });
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * GET /v1/apps/:id/domain - the app's domain record, live-refreshed against
+     * Cloudflare when the feature is enabled (status/last_error/last_checked_at
+     * update as a side effect).
+     */
+    async getAppDomain(appId) {
+        const r = await this.call("GET", `/v1/apps/${encodeURIComponent(appId)}/domain`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * DELETE /v1/apps/:id/domain - remove the domain binding (Cloudflare
+     * hostname best-effort + record + quota release). Idempotent.
+     */
+    async deleteAppDomain(appId) {
+        const r = await this.call("DELETE", `/v1/apps/${encodeURIComponent(appId)}/domain`);
+        if (!r.ok)
+            this.fail(r);
+    }
+    // -------------------------------------------------------------------------
     // v2 app membership (auth spec §6, spec-cli §2.5). Auth is owner-or-agent;
     // this client always authenticates as the owning agent. Note: unlike most
     // v1/v2 wire shapes, the member fields below are camelCase on the wire
@@ -522,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);
@@ -534,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
@@ -545,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)
@@ -585,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);
@@ -599,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
@@ -616,4 +954,164 @@ export class HomespunClient {
             this.fail(r);
         return this.asObject(r);
     }
+    // -------------------------------------------------------------------------
+    // Community publish + review (M4b). publishCommunityTemplate is an OWNER
+    // action (the calling agent's owning human); the review methods are
+    // operator-gated server-side.
+    // -------------------------------------------------------------------------
+    /** POST /v1/community/publish: publish an owned app as a pending template. */
+    async publishCommunityTemplate(req) {
+        const r = await this.call("POST", "/v1/community/publish", {
+            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);
+        return this.asObject(r);
+    }
+    /** GET /v1/community/pending (operator): list pending submissions. */
+    async listCommunitySubmissions(opts = {}) {
+        const q = new URLSearchParams();
+        if (opts.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        if (opts.cursor !== undefined && opts.cursor !== "")
+            q.set("cursor", opts.cursor);
+        const qs = q.toString();
+        const r = await this.call("GET", `/v1/community/pending${qs ? "?" + qs : ""}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /** GET /v1/community/submissions/:id (operator): a submission's full content. */
+    async getCommunitySubmission(snapshotId) {
+        const r = await this.call("GET", `/v1/community/submissions/${encodeURIComponent(snapshotId)}`);
+        if (!r.ok)
+            this.fail(r);
+        return this.asObject(r);
+    }
+    /**
+     * POST /v1/community/submissions/:id/{approve,reject} (operator): review a
+     * submission. `decision` "reject" requires a `note` (delivered to the
+     * publisher's app feed).
+     */
+    async reviewCommunitySubmission(snapshotId, review) {
+        const path = `/v1/community/submissions/${encodeURIComponent(snapshotId)}/${review.decision}`;
+        const r = await this.call("POST", path, review.decision === "reject" ? { note: review.note } : undefined);
+        if (!r.ok)
+            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, DeployAppRequest, DeployAppResponse, RedeployAppRequest, RedeployAppResponse, AppSummary, AppDetail, AppsPage, 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.0",
+  "version": "1.4.2",
   "description": "Homespun relay client: typed HTTP + WebSocket operations against a Homespun relay. Framework-free.",
   "license": "MIT",
   "type": "module",
@@ -11,14 +11,9 @@
     "relay",
     "human-in-the-loop"
   ],
-  "homepage": "https://github.com/aerolalit/homespun#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aerolalit/homespun.git",
-    "directory": "packages/core"
-  },
+  "homepage": "https://docs.homespun.dev",
   "bugs": {
-    "url": "https://github.com/aerolalit/homespun/issues"
+    "url": "https://github.com/homespunapps/homespun/issues"
   },
   "engines": {
     "node": ">=20"
@@ -46,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"
   }
 }