run402 1.42.0 → 1.44.0

package/sdk/dist/node/canonicalize.js

@@ -0,0 +1,62 @@
+/**
+ * RFC 8785 (JCS) canonical JSON for the v1.32 deploy-plan manifest digest.
+ *
+ * MUST stay byte-for-byte identical to the gateway's
+ * `services/deploy-plans.ts:canonicalizeJson`. A digest mismatch breaks
+ * idempotency: the SDK's hash won't match the gateway's, so retrying a
+ * plan creates a NEW plan instead of finding the existing one.
+ *
+ * Spec for our value domain:
+ *   - object keys sorted ASCII-ascending
+ *   - arrays comma-separated, no whitespace
+ *   - strings/numbers via JSON.stringify (matches RFC 8785 for ASCII paths,
+ *     hex sha256, integer sizes, ASCII content_types)
+ */
+export function canonicalizeJson(value) {
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number")
+        return JSON.stringify(value);
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return "[" + value.map(canonicalizeJson).join(",") + "]";
+    if (typeof value === "object") {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const pairs = keys.map((k) => JSON.stringify(k) + ":" + canonicalizeJson(obj[k]));
+        return "{" + pairs.join(",") + "}";
+    }
+    throw new Error("canonicalizeJson: unsupported value type");
+}
+/**
+ * Build the canonical manifest object the gateway hashes: `{ files: [...] }`
+ * with entries sorted by path and only the four expected keys per entry.
+ * `content_type` defaults to `"application/octet-stream"` when absent.
+ */
+export function buildCanonicalManifest(entries) {
+    const files = entries
+        .map((e) => ({
+        path: e.path,
+        sha256: e.sha256,
+        size: e.size,
+        content_type: e.content_type ?? "application/octet-stream",
+    }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return { files };
+}
+/**
+ * Compute the hex SHA-256 of the canonical JSON encoding of a manifest.
+ * Matches the gateway's `computeManifestDigest`.
+ */
+export async function computeManifestDigest(manifest) {
+    const canonical = canonicalizeJson(manifest);
+    const bytes = new TextEncoder().encode(canonical);
+    const hash = await crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(hash))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+//# sourceMappingURL=canonicalize.js.map

package/sdk/dist/node/canonicalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalize.js","sourceRoot":"","sources":["../../src/node/canonicalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAaH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAChE,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC5D,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACnF,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClF,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACrC,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAqF;IAErF,MAAM,KAAK,GAAoB,OAAO;SACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,0BAA0B;KAC3D,CAAC,CAAC;SACF,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,OAAO,EAAE,KAAK,EAAE,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,QAAkB;IAC5D,MAAM,SAAS,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAClD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAgC,CAAC,CAAC;IACrF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;SACpC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC"}

package/sdk/dist/node/index.d.ts

@@ -5,15 +5,22 @@
  *   - default API base from `RUN402_API_BASE` (via core/config)
  *   - {@link NodeCredentialsProvider} backed by the local keystore + allowance
  *   - an x402-wrapped fetch built lazily on first request
+ *   - {@link NodeSites}: the `sites` namespace enriched with `deployDir(dir)`
  *
  * Usage:
  * ```ts
  * import { run402 } from "@run402/sdk/node";
  * const r = run402();
  * const project = await r.projects.provision({ tier: "prototype" });
+ * await r.sites.deployDir({ project: project.project_id, dir: "./my-site" });
  * ```
+ *
+ * `deployDir` uses the v1.32 plan/commit transport and only uploads the
+ * bytes the gateway doesn't already have. Re-deploying an unchanged tree
+ * issues no S3 PUTs.
  */
 import { Run402 } from "../index.js";
+import { NodeSites } from "./sites-node.js";
 export interface NodeRun402Options {
     /** Override the API base URL. Defaults to `getApiBase()` (env var or production URL). */
     apiBase?: string;
@@ -29,16 +36,26 @@ export interface NodeRun402Options {
     /** Fully custom fetch implementation. Takes precedence over `disablePaidFetch`. */
     fetch?: typeof globalThis.fetch;
 }
+/** Run402 instance with the Node-only `sites.deployDir` helper wired in. */
+export type NodeRun402 = Omit<Run402, "sites"> & {
+    sites: NodeSites;
+};
 /**
  * Construct a Run402 client wired with Node defaults.
  *
  * Behavior matches today's `run402-mcp` / `run402` CLI: reads keystore and
  * allowance from disk, signs SIWX headers, and retries 402 responses via
  * `@x402/fetch` when the allowance wallet has USDC balance.
+ *
+ * The returned instance's `sites` namespace is a {@link NodeSites}, which
+ * adds a `deployDir({ dir })` helper on top of the isomorphic `deploy()`
+ * and `getDeployment()` methods.
  */
-export declare function run402(opts?: NodeRun402Options): Run402;
+export declare function run402(opts?: NodeRun402Options): NodeRun402;
+export { NodeSites } from "./sites-node.js";
+export type { DeployDirOptions } from "./sites-node.js";
 export { NodeCredentialsProvider } from "./credentials.js";
 export { setupPaidFetch, createLazyPaidFetch } from "./paid-fetch.js";
-export { Run402, Run402Error, PaymentRequired, ProjectNotFound, Unauthorized, ApiError, NetworkError, } from "../index.js";
+export { Run402, Run402Error, PaymentRequired, ProjectNotFound, Unauthorized, ApiError, NetworkError, LocalError, } from "../index.js";
 export type { Run402Options, CredentialsProvider, ProjectKeys, RequestOptions, Client, } from "../index.js";
 //# sourceMappingURL=index.d.ts.map

package/sdk/dist/node/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,MAAM,EAAsB,MAAM,aAAa,CAAC;AAIzD,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,IAAI,GAAE,iBAAsB,GAAG,MAAM,CAY3D;AAED,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EACL,MAAM,EACN,WAAW,EACX,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,MAAM,GACP,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAE,MAAM,EAAsB,MAAM,aAAa,CAAC;AAIzD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtE;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,IAAI,GAAE,iBAAsB,GAAG,UAAU,CAqB/D;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtE,OAAO,EACL,MAAM,EACN,WAAW,EACX,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,MAAM,GACP,MAAM,aAAa,CAAC"}

package/sdk/dist/node/index.js

@@ -5,24 +5,35 @@
  *   - default API base from `RUN402_API_BASE` (via core/config)
  *   - {@link NodeCredentialsProvider} backed by the local keystore + allowance
  *   - an x402-wrapped fetch built lazily on first request
+ *   - {@link NodeSites}: the `sites` namespace enriched with `deployDir(dir)`
  *
  * Usage:
  * ```ts
  * import { run402 } from "@run402/sdk/node";
  * const r = run402();
  * const project = await r.projects.provision({ tier: "prototype" });
+ * await r.sites.deployDir({ project: project.project_id, dir: "./my-site" });
  * ```
+ *
+ * `deployDir` uses the v1.32 plan/commit transport and only uploads the
+ * bytes the gateway doesn't already have. Re-deploying an unchanged tree
+ * issues no S3 PUTs.
  */
 import { getApiBase } from "../../core-dist/config.js";
 import { Run402 } from "../index.js";
 import { NodeCredentialsProvider } from "./credentials.js";
 import { createLazyPaidFetch } from "./paid-fetch.js";
+import { NodeSites } from "./sites-node.js";
 /**
  * Construct a Run402 client wired with Node defaults.
  *
  * Behavior matches today's `run402-mcp` / `run402` CLI: reads keystore and
  * allowance from disk, signs SIWX headers, and retries 402 responses via
  * `@x402/fetch` when the allowance wallet has USDC balance.
+ *
+ * The returned instance's `sites` namespace is a {@link NodeSites}, which
+ * adds a `deployDir({ dir })` helper on top of the isomorphic `deploy()`
+ * and `getDeployment()` methods.
  */
 export function run402(opts = {}) {
     const runOpts = {
@@ -34,10 +45,18 @@ export function run402(opts = {}) {
         fetch: opts.fetch ??
             (opts.disablePaidFetch ? globalThis.fetch.bind(globalThis) : createLazyPaidFetch()),
     };
-    return new Run402(runOpts);
+    const base = new Run402(runOpts);
+    // Upgrade `sites` to the Node-aware variant, sharing the kernel `Client`
+    // that the isomorphic Sites was constructed with. Access to `client` goes
+    // through a cast because it is `private` on `Sites` — runtime still exposes
+    // the field; this keeps a single Client per instance (no divergent state).
+    const client = base.sites.client;
+    base.sites = new NodeSites(client);
+    return base;
 }
+export { NodeSites } from "./sites-node.js";
 export { NodeCredentialsProvider } from "./credentials.js";
 export { setupPaidFetch, createLazyPaidFetch } from "./paid-fetch.js";
 // Re-export the isomorphic surface so Node consumers don't need two imports.
-export { Run402, Run402Error, PaymentRequired, ProjectNotFound, Unauthorized, ApiError, NetworkError, } from "../index.js";
+export { Run402, Run402Error, PaymentRequired, ProjectNotFound, Unauthorized, ApiError, NetworkError, LocalError, } from "../index.js";
 //# sourceMappingURL=index.js.map

package/sdk/dist/node/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,MAAM,EAAsB,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAkBtD;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CAAC,OAA0B,EAAE;IACjD,MAAM,OAAO,GAAkB;QAC7B,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,UAAU,EAAE;QACrC,WAAW,EAAE,IAAI,uBAAuB,CAAC;YACvC,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC;QACF,KAAK,EACH,IAAI,CAAC,KAAK;YACV,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC;KACtF,CAAC;IACF,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtE,6EAA6E;AAC7E,OAAO,EACL,MAAM,EACN,WAAW,EACX,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,YAAY,GACb,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,OAAO,EAAE,MAAM,EAAsB,MAAM,aAAa,CAAC;AAEzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAqB5C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,MAAM,CAAC,OAA0B,EAAE;IACjD,MAAM,OAAO,GAAkB;QAC7B,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,UAAU,EAAE;QACrC,WAAW,EAAE,IAAI,uBAAuB,CAAC;YACvC,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,YAAY,EAAE,IAAI,CAAC,YAAY;SAChC,CAAC;QACF,KAAK,EACH,IAAI,CAAC,KAAK;YACV,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC;KACtF,CAAC;IACF,MAAM,IAAI,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;IAEjC,yEAAyE;IACzE,0EAA0E;IAC1E,4EAA4E;IAC5E,2EAA2E;IAC3E,MAAM,MAAM,GAAI,IAAI,CAAC,KAAuC,CAAC,MAAM,CAAC;IACnE,IAAwC,CAAC,KAAK,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC;IAExE,OAAO,IAA6B,CAAC;AACvC,CAAC;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtE,6EAA6E;AAC7E,OAAO,EACL,MAAM,EACN,WAAW,EACX,eAAe,EACf,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC"}

package/sdk/dist/node/sites-node.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Node-only augmentation of the `sites` namespace.
+ *
+ * `deployDir(dir)` walks a directory, computes per-file SHA-256 + size,
+ * builds a canonical manifest, and ships it via the v1.32 plan/commit
+ * transport:
+ *
+ *   1. POST /deploy/v1/plan { manifest_digest, manifest } — returns per-file
+ *      state (`present`, `satisfied_by_plan`, or `missing` + presigned URLs).
+ *   2. PUT each `missing` file's bytes to its presigned S3 URL(s),
+ *      sending `x-amz-checksum-sha256` to satisfy the signed checksum
+ *      algorithm. Single-PUT covers small files; multipart covers large
+ *      files (the gateway picks per-part sizing).
+ *   3. POST /deploy/v1/commit { plan_id } — Stage 1 (DB) returns
+ *      synchronously with `applied`, `noop`, `copying`, or `failed`.
+ *      `copying` triggers a poll loop on `GET /deployments/v1/:id` until
+ *      `ready` (or `failed`).
+ *
+ * The canonicalize used to compute `manifest_digest` MUST match the
+ * gateway's byte-for-byte (see `./canonicalize.ts`).
+ *
+ * Imports `node:fs/promises` and so cannot run in a V8 isolate. Wired into
+ * the SDK via the `@run402/sdk/node` entry point only.
+ */
+import { Sites, type SiteDeployResult } from "../namespaces/sites.js";
+import { type ManifestEntry } from "./canonicalize.js";
+export interface DeployDirOptions {
+    /** Project ID the deployment is linked to. */
+    project: string;
+    /** Local directory to walk. Paths in the manifest are relative to this root. */
+    dir: string;
+    /** Deployment target label, e.g. `"production"`. */
+    target?: string;
+}
+/** One walked file plus everything we need to hash, plan, and upload it. */
+interface WalkedFile {
+    path: string;
+    size: number;
+    sha256: string;
+    content_type: string;
+    bytes: Buffer;
+}
+interface PlanFilePresent {
+    sha256: string;
+    present: true;
+    size: number;
+    content_type: string;
+}
+interface PlanFileSatisfied {
+    sha256: string;
+    satisfied_by_plan: true;
+    size: number;
+    content_type: string;
+}
+interface PlanFileMissing {
+    sha256: string;
+    missing: true;
+    upload_id: string;
+    mode: "single" | "multipart";
+    key: string;
+    staging_key: string;
+    part_size_bytes: number;
+    part_count: number;
+    parts: Array<{
+        part_number: number;
+        url: string;
+        byte_start: number;
+        byte_end: number;
+    }>;
+    expires_at: string;
+}
+type PlanFileResponse = PlanFilePresent | PlanFileSatisfied | PlanFileMissing;
+interface PlanResponse {
+    plan_id: string;
+    files: PlanFileResponse[];
+}
+interface CommitResponse {
+    deployment_id: string;
+    url: string;
+    status: "applied" | "noop" | "copying" | "failed";
+    bytes_total?: number;
+    bytes_uploaded?: number;
+}
+/**
+ * Sites namespace enriched with the Node-only `deployDir` convenience.
+ * All existing `Sites` methods are inherited unchanged.
+ */
+export declare class NodeSites extends Sites {
+    /**
+     * Deploy every file under `dir` as a static site. Walks the tree, hashes
+     * each file, plans the deploy with the gateway (which dedupes against
+     * already-uploaded content), uploads only the missing bytes, then
+     * commits.
+     *
+     * Files named `.git`, `node_modules`, or `.DS_Store` are skipped at every
+     * depth. Symlinks cause a {@link LocalError} — they are not followed.
+     */
+    deployDir(opts: DeployDirOptions): Promise<SiteDeployResult>;
+}
+/**
+ * Normalize a relative path to POSIX forward slashes. Exposed for tests;
+ * not part of the public SDK API.
+ */
+export declare function normalizeRelPath(rel: string): string;
+/** @internal — exposed for tests, not part of the public SDK API. */
+export declare function _collectFilesForTest(root: string): Promise<WalkedFile[]>;
+/** @internal — exposed for tests, not part of the public SDK API. */
+export type { WalkedFile, PlanResponse, CommitResponse, ManifestEntry };
+//# sourceMappingURL=sites-node.d.ts.map

package/sdk/dist/node/sites-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sites-node.d.ts","sourceRoot":"","sources":["../../src/node/sites-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAAE,KAAK,EAAE,KAAK,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EAIL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAa3B,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,4EAA4E;AAC5E,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AACD,UAAU,iBAAiB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AACD,UAAU,eAAe;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzF,UAAU,EAAE,MAAM,CAAC;CACpB;AACD,KAAK,gBAAgB,GAAG,eAAe,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAE9E,UAAU,YAAY;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED,UAAU,cAAc;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC;;;;;;;;OAQG;IACG,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAwFnE;AAoOD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpD;AA2DD,qEAAqE;AACrE,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAE9E;AAED,qEAAqE;AACrE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC"}

package/sdk/dist/node/sites-node.js

@@ -0,0 +1,347 @@
+/**
+ * Node-only augmentation of the `sites` namespace.
+ *
+ * `deployDir(dir)` walks a directory, computes per-file SHA-256 + size,
+ * builds a canonical manifest, and ships it via the v1.32 plan/commit
+ * transport:
+ *
+ *   1. POST /deploy/v1/plan { manifest_digest, manifest } — returns per-file
+ *      state (`present`, `satisfied_by_plan`, or `missing` + presigned URLs).
+ *   2. PUT each `missing` file's bytes to its presigned S3 URL(s),
+ *      sending `x-amz-checksum-sha256` to satisfy the signed checksum
+ *      algorithm. Single-PUT covers small files; multipart covers large
+ *      files (the gateway picks per-part sizing).
+ *   3. POST /deploy/v1/commit { plan_id } — Stage 1 (DB) returns
+ *      synchronously with `applied`, `noop`, `copying`, or `failed`.
+ *      `copying` triggers a poll loop on `GET /deployments/v1/:id` until
+ *      `ready` (or `failed`).
+ *
+ * The canonicalize used to compute `manifest_digest` MUST match the
+ * gateway's byte-for-byte (see `./canonicalize.ts`).
+ *
+ * Imports `node:fs/promises` and so cannot run in a V8 isolate. Wired into
+ * the SDK via the `@run402/sdk/node` entry point only.
+ */
+import { readdir, readFile, lstat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { Sites } from "../namespaces/sites.js";
+import { ApiError, LocalError, Run402Error } from "../errors.js";
+import { buildCanonicalManifest, computeManifestDigest, } from "./canonicalize.js";
+const DEFAULT_IGNORE = new Set([".git", "node_modules", ".DS_Store"]);
+const CONTEXT = "deploying directory";
+/** Cap on total time spent waiting for Stage 2 copy to drain. */
+const COPY_POLL_TIMEOUT_MS = 10 * 60 * 1000;
+/** Initial poll interval; we hold this for ~30 s, then back off. */
+const COPY_POLL_INITIAL_MS = 1_000;
+const COPY_POLL_MAX_MS = 30_000;
+/** Time after which we re-call /deploy/v1/plan to refresh presigned URLs (1 h TTL). */
+const URL_REFRESH_AT_MS = 50 * 60 * 1000;
+/**
+ * Sites namespace enriched with the Node-only `deployDir` convenience.
+ * All existing `Sites` methods are inherited unchanged.
+ */
+export class NodeSites extends Sites {
+    /**
+     * Deploy every file under `dir` as a static site. Walks the tree, hashes
+     * each file, plans the deploy with the gateway (which dedupes against
+     * already-uploaded content), uploads only the missing bytes, then
+     * commits.
+     *
+     * Files named `.git`, `node_modules`, or `.DS_Store` are skipped at every
+     * depth. Symlinks cause a {@link LocalError} — they are not followed.
+     */
+    async deployDir(opts) {
+        const files = await collectFiles(opts.dir);
+        if (files.length === 0) {
+            throw new LocalError(`directory ${opts.dir} contains no deployable files`, CONTEXT);
+        }
+        const manifest = buildCanonicalManifest(files.map((f) => ({
+            path: f.path,
+            sha256: f.sha256,
+            size: f.size,
+            content_type: f.content_type,
+        })));
+        const manifestDigest = await computeManifestDigest(manifest);
+        // Map sha → bytes so we can satisfy the plan response without re-walking.
+        // Multiple paths may share the same sha (identical files); any copy works.
+        const bytesBySha = new Map();
+        for (const f of files)
+            bytesBySha.set(f.sha256, f.bytes);
+        // Reach through to the kernel client. `Sites.client` is `private` in TS
+        // but enumerable at runtime; the cast bypasses the visibility check.
+        const client = this.client;
+        const planClient = new ClientFromBase(client);
+        const plan = await planClient.requestPlan(opts.project, manifest, manifestDigest);
+        const planAt = Date.now();
+        let activePlan = plan;
+        let activePlanAt = planAt;
+        for (const entry of activePlan.files) {
+            if (!isMissing(entry))
+                continue;
+            // Refresh the plan if the URL TTL window is about to close.
+            if (Date.now() - activePlanAt > URL_REFRESH_AT_MS) {
+                activePlan = await planClient.requestPlan(opts.project, manifest, manifestDigest);
+                activePlanAt = Date.now();
+            }
+            const refreshed = activePlan.files.find((e) => e.sha256 === entry.sha256);
+            const target = refreshed && isMissing(refreshed) ? refreshed : entry;
+            const bytes = bytesBySha.get(target.sha256);
+            if (!bytes) {
+                throw new LocalError(`internal: no local bytes for sha ${target.sha256.slice(0, 12)}…`, CONTEXT);
+            }
+            try {
+                await uploadOne(client.fetch, target, bytes);
+            }
+            catch (err) {
+                // S3 returns 403 when the presigned URL has expired. Refresh once.
+                if (err instanceof ApiError && err.status === 403) {
+                    activePlan = await planClient.requestPlan(opts.project, manifest, manifestDigest);
+                    activePlanAt = Date.now();
+                    const fresh = activePlan.files.find((e) => e.sha256 === target.sha256);
+                    if (fresh && isMissing(fresh)) {
+                        await uploadOne(client.fetch, fresh, bytes);
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        const commit = await planClient.commit(opts.project, activePlan.plan_id);
+        if (commit.status === "applied" || commit.status === "noop") {
+            return shapeResult(commit);
+        }
+        if (commit.status === "copying") {
+            const final = await pollUntilReady(this, commit.deployment_id);
+            return { deployment_id: commit.deployment_id, url: commit.url, ...final };
+        }
+        // status === "failed": stage 2 exhausted retries. Surface as ApiError so
+        // callers can decide whether to re-call deployDir (which re-commits).
+        throw new ApiError(`Deploy commit failed for plan ${activePlan.plan_id} after copy retries`, 500, commit, "committing deploy");
+    }
+}
+class ClientFromBase {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async requestPlan(projectId, manifest, manifestDigest) {
+        return this.client.request("/deploy/v1/plan", {
+            method: "POST",
+            body: { project: projectId, manifest_digest: manifestDigest, manifest },
+            context: "planning deploy",
+        });
+    }
+    async commit(projectId, planId) {
+        return this.client.request("/deploy/v1/commit", {
+            method: "POST",
+            body: { project: projectId, plan_id: planId },
+            context: "committing deploy",
+        });
+    }
+}
+function isMissing(entry) {
+    return entry.missing === true;
+}
+function shapeResult(commit) {
+    const out = { deployment_id: commit.deployment_id, url: commit.url };
+    if (commit.bytes_total !== undefined)
+        out.bytes_total = commit.bytes_total;
+    if (commit.bytes_uploaded !== undefined)
+        out.bytes_uploaded = commit.bytes_uploaded;
+    return out;
+}
+// ─── Upload ──────────────────────────────────────────────────────────────────
+async function uploadOne(fetchFn, entry, bytes) {
+    if (entry.mode === "single") {
+        if (entry.parts.length !== 1) {
+            throw new LocalError(`internal: single-mode upload for ${entry.sha256.slice(0, 12)}… returned ${entry.parts.length} parts`, CONTEXT);
+        }
+        const part = entry.parts[0];
+        const slice = bytes.subarray(part.byte_start, part.byte_end + 1);
+        // For single-PUT, the URL pre-commits the whole-object SHA — we send
+        // the same value (in base64, not hex) on the PUT.
+        const checksum = base64FromHex(entry.sha256);
+        await putToS3(fetchFn, part.url, slice, checksum, part.part_number);
+        return;
+    }
+    // multipart: each part PUT carries its own per-part SHA-256 base64.
+    for (const part of entry.parts) {
+        const slice = bytes.subarray(part.byte_start, part.byte_end + 1);
+        const checksum = await sha256Base64(slice);
+        await putToS3(fetchFn, part.url, slice, checksum, part.part_number);
+    }
+}
+async function putToS3(fetchFn, url, body, checksumBase64, partNumber) {
+    let res;
+    try {
+        res = await fetchFn(url, {
+            method: "PUT",
+            headers: { "x-amz-checksum-sha256": checksumBase64 },
+            body: body,
+        });
+    }
+    catch (err) {
+        throw new ApiError(`S3 PUT failed for part ${partNumber}: ${err.message}`, 0, null, "uploading deploy bytes");
+    }
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new ApiError(`S3 PUT failed for part ${partNumber} (HTTP ${res.status})${text ? ": " + text.slice(0, 200) : ""}`, res.status, text, "uploading deploy bytes");
+    }
+}
+async function pollUntilReady(sites, deploymentId) {
+    const start = Date.now();
+    let interval = COPY_POLL_INITIAL_MS;
+    while (Date.now() - start < COPY_POLL_TIMEOUT_MS) {
+        await sleep(interval);
+        let info;
+        try {
+            info = await sites.getDeployment(deploymentId);
+        }
+        catch (err) {
+            // Transient lookup failure: keep polling unless we're a hard error.
+            if (err instanceof Run402Error && err.status !== null && err.status >= 500) {
+                continue;
+            }
+            throw err;
+        }
+        if (info.status === "ready" || info.status === "applied") {
+            return { status: info.status, url: info.url };
+        }
+        if (info.status === "failed") {
+            throw new ApiError(`Deployment ${deploymentId} entered failed state during copy`, 500, info, "polling deploy");
+        }
+        // Hold the initial cadence for the first 30 s, then back off to a max.
+        if (Date.now() - start > 30_000) {
+            interval = Math.min(Math.floor(interval * 1.5), COPY_POLL_MAX_MS);
+        }
+    }
+    throw new ApiError(`Timed out waiting for deployment ${deploymentId} to reach ready (${COPY_POLL_TIMEOUT_MS / 60_000} min)`, 504, null, "polling deploy");
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ─── Filesystem walk + hashing ───────────────────────────────────────────────
+async function collectFiles(root) {
+    let rootStat;
+    try {
+        rootStat = await lstat(root);
+    }
+    catch (err) {
+        throw new LocalError(`cannot read directory ${root}: ${err.message}`, CONTEXT, err);
+    }
+    if (rootStat.isSymbolicLink()) {
+        throw new LocalError(`symlink found at ${root} (following symlinks is not supported)`, CONTEXT);
+    }
+    if (!rootStat.isDirectory()) {
+        throw new LocalError(`path ${root} is not a directory`, CONTEXT);
+    }
+    const out = [];
+    await walkInto(root, root, out);
+    return out;
+}
+async function walkInto(root, current, out) {
+    let entries;
+    try {
+        entries = await readdir(current, { withFileTypes: true });
+    }
+    catch (err) {
+        throw new LocalError(`cannot read directory ${current}: ${err.message}`, CONTEXT, err);
+    }
+    for (const entry of entries) {
+        if (DEFAULT_IGNORE.has(entry.name))
+            continue;
+        const fullPath = join(current, entry.name);
+        if (entry.isSymbolicLink()) {
+            throw new LocalError(`symlink found at ${fullPath} (following symlinks is not supported)`, CONTEXT);
+        }
+        if (entry.isDirectory()) {
+            await walkInto(root, fullPath, out);
+            continue;
+        }
+        if (entry.isFile()) {
+            let bytes;
+            try {
+                bytes = await readFile(fullPath);
+            }
+            catch (err) {
+                throw new LocalError(`cannot read file ${fullPath}: ${err.message}`, CONTEXT, err);
+            }
+            const rel = normalizeRelPath(relative(root, fullPath));
+            out.push({
+                path: rel,
+                size: bytes.byteLength,
+                sha256: await sha256Hex(bytes),
+                content_type: guessContentType(rel),
+                bytes,
+            });
+        }
+    }
+}
+/**
+ * Normalize a relative path to POSIX forward slashes. Exposed for tests;
+ * not part of the public SDK API.
+ */
+export function normalizeRelPath(rel) {
+    return sep === "/" ? rel : rel.split(sep).join("/");
+}
+async function sha256Hex(bytes) {
+    const hash = await crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(hash))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+async function sha256Base64(bytes) {
+    const hash = await crypto.subtle.digest("SHA-256", bytes);
+    return Buffer.from(hash).toString("base64");
+}
+function base64FromHex(hex) {
+    if (!/^[0-9a-f]*$/i.test(hex) || hex.length % 2 !== 0) {
+        throw new LocalError(`invalid hex sha256: ${hex}`, CONTEXT);
+    }
+    return Buffer.from(hex, "hex").toString("base64");
+}
+const CONTENT_TYPES = {
+    html: "text/html; charset=utf-8",
+    htm: "text/html; charset=utf-8",
+    css: "text/css; charset=utf-8",
+    js: "application/javascript; charset=utf-8",
+    mjs: "application/javascript; charset=utf-8",
+    json: "application/json; charset=utf-8",
+    svg: "image/svg+xml",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    ico: "image/x-icon",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+    eot: "application/vnd.ms-fontobject",
+    otf: "font/otf",
+    txt: "text/plain; charset=utf-8",
+    md: "text/markdown; charset=utf-8",
+    xml: "application/xml",
+    pdf: "application/pdf",
+    wasm: "application/wasm",
+    map: "application/json; charset=utf-8",
+};
+function guessContentType(path) {
+    const dot = path.lastIndexOf(".");
+    if (dot === -1)
+        return "application/octet-stream";
+    const ext = path.slice(dot + 1).toLowerCase();
+    return CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
+// ─── Test-only exports ───────────────────────────────────────────────────────
+// Kept exported so the unit tests can drive the walk + hash logic without
+// having to spin up an HTTP mock for every concern.
+/** @internal — exposed for tests, not part of the public SDK API. */
+export async function _collectFilesForTest(root) {
+    return collectFiles(root);
+}
+//# sourceMappingURL=sites-node.js.map