@homespunapps/core 1.0.0 → 1.0.1

package/dist/client.d.ts

@@ -159,6 +159,25 @@ export declare class HomespunClient {
      * stream bytes through the relay.
      */
     uploadBlob(file: Blob | Buffer | Uint8Array, opts?: UploadBlobOptions): Promise<AttachmentRef>;
+    /**
+     * Upload a attachment from INLINE base64 bytes: the no-filesystem sibling of
+     * `uploadBlob()`. Use this when the bytes were produced in memory (an image
+     * the agent generated, a document it assembled) and there is no local file to
+     * stream: an MCP client running inside a Claude session has no filesystem to
+     * point `uploadBlob()` at.
+     *
+     * The bytes are sent as base64 in a JSON body to the relay's
+     * `POST /v1/attachments` inline variant ({ content_base64, filename?, mime?,
+     * scope?, app_id? }). The relay decodes them behind a pre-decode size guard and runs
+     * the IDENTICAL validation pipeline the multipart `uploadBlob()` path runs:
+     * magic-byte MIME sniff, BLOB_MIME_ALLOWLIST, per-attachment size cap, and the
+     * per-agent / per-app / per-account quota reservation. `mime` is advisory
+     * (the relay sniffs the real type regardless), and an oversized or disallowed
+     * inline upload returns the same errors the file path would.
+     *
+     * @param contentBase64 standard base64 (e.g. `Buffer.from(bytes).toString("base64")`).
+     */
+    uploadBlobInline(contentBase64: string, opts?: UploadBlobOptions): Promise<AttachmentRef>;
     /** GET /v1/attachments/:id — download bytes as an ArrayBuffer. */
     downloadBlob(attachmentId: string): Promise<ArrayBuffer>;
     /**
@@ -219,8 +238,22 @@ export declare class HomespunClient {
         upload_url: string;
         expires_at: string;
     }>;
-    /** Finalise a presigned upload — relay HEADs the bytes, verifies, flips ready. */
+    /**
+     * Finalise a presigned upload. After the client PUTs the bytes to the
+     * `upload_url` from `presignBlob()`, the relay re-reads the stored bytes and
+     * runs the SAME validation a normal upload runs: it BYTE-SNIFFS the actual
+     * content and derives the stored/served mime from that (never the
+     * presign-declared mime), re-verifies size + sha256, enforces the allowlist +
+     * quota, and runs the scan hook, before flipping the attachment to `ready`.
+     * A finalize whose bytes fail any check leaves the attachment unready (it is
+     * never served) and returns a clean error. Returns the ready `AttachmentRef`.
+     */
     confirmBlob(attachmentId: string): Promise<AttachmentRef>;
+    /**
+     * Alias for {@link confirmBlob}: the "finalize" half of the presign ->
+     * PUT -> finalize flow, named to match the MCP `attachments` action.
+     */
+    finalizeBlob(attachmentId: string): Promise<AttachmentRef>;
     /** POST /v1/apps — create (deploy) a new App + its first AppVersion. */
     deployApp(req: DeployAppRequest): Promise<DeployAppResponse>;
     /** POST /v1/apps/:id/versions — redeploy (compat-gated unless force). */
@@ -250,6 +283,23 @@ export declare class HomespunClient {
         id: string;
         status: string;
     }>;
+    /**
+     * POST /v1/apps/:id/domain - bind a custom domain to the app. Returns the
+     * record including `dns_records`: the DNS entries the domain owner must
+     * publish (the routing CNAME plus any Cloudflare validation records).
+     */
+    setAppDomain(appId: string, domain: string): Promise<AppDomain>;
+    /**
+     * GET /v1/apps/:id/domain - the app's domain record, live-refreshed against
+     * Cloudflare when the feature is enabled (status/last_error/last_checked_at
+     * update as a side effect).
+     */
+    getAppDomain(appId: string): Promise<AppDomain>;
+    /**
+     * DELETE /v1/apps/:id/domain - remove the domain binding (Cloudflare
+     * hostname best-effort + record + quota release). Idempotent.
+     */
+    deleteAppDomain(appId: string): Promise<void>;
     /**
      * POST /v1/apps/:id/members — add or invite a member by email. If a Human
      * already exists for the email, the member row is created immediately
@@ -318,6 +368,35 @@ export declare class HomespunClient {
         limit?: number;
         wait?: number;
     }): Promise<AppFeedPage>;
+    /** POST /v1/community/publish: publish an owned app as a pending template. */
+    publishCommunityTemplate(req: PublishCommunityTemplateRequest): Promise<PublishCommunityTemplateResponse>;
+    /** GET /v1/community/pending (operator): list pending submissions. */
+    listCommunitySubmissions(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<CommunitySubmissionsPage>;
+    /** GET /v1/community/submissions/:id (operator): a submission's full content. */
+    getCommunitySubmission(snapshotId: string): Promise<CommunitySubmissionDetail>;
+    /**
+     * POST /v1/community/submissions/:id/{approve,reject} (operator): review a
+     * submission. `decision` "reject" requires a `note` (delivered to the
+     * publisher's app feed).
+     */
+    reviewCommunitySubmission(snapshotId: string, review: {
+        decision: "approve" | "reject";
+        note?: string;
+    }): Promise<CommunitySubmissionDetail>;
+}
+/**
+ * One multi-file-deploy asset: bytes the deployed page references by a stable,
+ * app-relative, same-origin path (e.g. `frames/000.jpg`). `content_base64` is the
+ * standard base64 of the raw bytes; `mime` is advisory (the relay sniffs the
+ * real type from the leading bytes).
+ */
+export interface AppAsset {
+    path: string;
+    content_base64: string;
+    mime?: string;
 }
 /** Request body for `POST /v1/apps` — create (deploy) a new App. */
 export interface DeployAppRequest {
@@ -327,6 +406,13 @@ export interface DeployAppRequest {
     visibility?: "private" | "link" | "public";
     /** Accepted for visibility public|private (including the omitted default); rejected for link. */
     slug?: string;
+    /**
+     * Optional asset bundle shipped alongside the HTML in ONE deploy. Each asset
+     * is validated + stored app-scoped exactly like an attachment and served at
+     * its `path` on the app's own origin, so `<img src="frames/000.jpg">` just
+     * works. Rejected atomically if any asset fails validation.
+     */
+    assets?: AppAsset[];
 }
 export interface DeployAppResponse {
     app_id: string;
@@ -342,6 +428,11 @@ export interface RedeployAppRequest {
     manifest: unknown;
     /** Bypass the compat gate; a narrowing collection is detached, not deleted. */
     force?: boolean;
+    /**
+     * Optional asset bundle for this version. Replaces the previous version's asset
+     * set atomically (the new version carries its own map; old assets are detached).
+     */
+    assets?: AppAsset[];
 }
 export interface RedeployAppResponse {
     app_id: string;
@@ -374,6 +465,24 @@ export interface AppsPage {
     items: AppSummary[];
     next_cursor: string | null;
 }
+/** One DNS record the domain owner must publish (custom domains). */
+export interface AppDomainDnsRecord {
+    type: string;
+    name: string;
+    value: string;
+    purpose: "routing" | "ownership" | "certificate_validation";
+}
+/** The app's custom-domain record - the shape the /domain routes return. */
+export interface AppDomain {
+    domain: string;
+    status: "pending" | "active" | "error" | "removed";
+    dns_records: AppDomainDnsRecord[];
+    cf_hostname_id: string | null;
+    last_error: string | null;
+    last_checked_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
 /**
  * One member row — the shape `listAppMembers` returns and the `member` half
  * of `addAppMember`'s union returns. Fields are camelCase on the wire (see
@@ -438,6 +547,53 @@ export interface AppFeedPage {
     cursor: number;
     truncated: boolean;
 }
+/** Request body for `publishCommunityTemplate()`. */
+export interface PublishCommunityTemplateRequest {
+    /** The owned app to publish. */
+    appId: string;
+    /** Listing title; defaults server-side to the app's manifest name. */
+    title?: string;
+    /** Listing blurb; defaults server-side to the manifest description. */
+    description?: string;
+    /** Optional single-word category. */
+    category?: string;
+    /** Optional curation tags. */
+    tags?: string[];
+}
+export interface PublishCommunityTemplateResponse {
+    snapshot_id: string;
+    review_status: "pending" | "approved" | "rejected";
+    name: string;
+    seeded_row_count: number;
+}
+/** A pending-submission summary in the operator review queue. */
+export interface CommunitySubmissionSummary {
+    snapshot_id: string;
+    name: string;
+    description: string | null;
+    category: string | null;
+    tags: string[];
+    review_status: "pending" | "approved" | "rejected";
+    publisher_human_id: string | null;
+    publisher_name: string | null;
+    source_app_id: string | null;
+    seeded_row_count: number;
+    published_at: string;
+}
+export interface CommunitySubmissionsPage {
+    items: CommunitySubmissionSummary[];
+    next_cursor: string | null;
+}
+/** A submission's FULL content, for operator review. */
+export interface CommunitySubmissionDetail extends CommunitySubmissionSummary {
+    html: string;
+    manifest: unknown;
+    seed_rows: unknown;
+    version_id: string | null;
+    reviewed_at: string | null;
+    review_note: string | null;
+    superseded_at: string | null;
+}
 /** Per-attachment metadata as returned by `POST /v1/attachments` and friends. */
 export interface AttachmentRef {
     attachment_id: string;

package/dist/client.js

@@ -305,6 +305,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 +457,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 +492,7 @@ export class HomespunClient {
             manifest: req.manifest,
             visibility: req.visibility,
             slug: req.slug,
+            assets: req.assets,
         });
         if (!r.ok)
             this.fail(r);
@@ -450,7 +500,12 @@ 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);
@@ -504,6 +559,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
@@ -616,4 +707,54 @@ 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,
+            category: req.category,
+            tags: req.tags,
+        });
+        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);
+    }
 }

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, AppSummary, AppDetail, AppsPage, AppDomain, AppDomainDnsRecord, AppMember, AddAppMemberResult, AppRow, AppRowsPage, AppFeedEntry, AppFeedPage, } 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.0.1",
   "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://homespun.dev",
   "bugs": {
-    "url": "https://github.com/aerolalit/homespun/issues"
+    "url": "mailto:support@homespun.dev"
   },
   "engines": {
     "node": ">=20"