@theholocron/netlify-client 1.36.0 → 1.38.0

package/README.md

@@ -32,12 +32,17 @@ await netlify.sites.update("site-id", { custom_domain: "example.com" });
 // Trigger a build from a git-linked site's default branch
 const { deploy_id } = await netlify.sites.triggerBuild("site-id");
 
-// Create a deployment directly from source files — zipped in-memory, no
-// dependency. Netlify runs no build step for a raw zip upload, unlike a
-// Git-linked deploy — resolve dependencies into the file set yourself first.
-const deploy = await netlify.deploys.createFromZip("site-id", {
-  "api/webhook.mjs": "export default () => new Response('ok');",
-  "package.json": '{"name":"fn"}',
+// Create a deploy — static files (plain text) and/or functions (pre-built
+// zips). This is the digest-based flow: real, invokable functions — not
+// the single-whole-zip method, which only deploys static assets.
+import { buildZip } from "@theholocron/netlify-client";
+
+const functionZip = buildZip({
+  "webhook.mjs": "exports.handler = async () => ({ statusCode: 200, body: 'ok' });",
+});
+const deploy = await netlify.deploys.create("site-id", {
+  files: { "index.html": "<!doctype html><title>status</title>" },
+  functions: [{ name: "webhook", zip: functionZip }],
 });
 
 // Get a deploy by id
@@ -53,15 +58,39 @@ await netlify.env.set("account-id", "site-id", "API_URL", "production", "https:/
 
 ## Notes
 
-- **No build step on a raw zip upload.** `deploys.createFromZip()` deploys
-  exactly the file tree you give it — Netlify doesn't run `npm install` or
-  any configured build command the way a Git-linked deploy (or `netlify
-deploy` run locally via the CLI) does. If your files need dependencies
-  installed, resolve them into the file set before calling this.
+- **Functions need the digest flow — the single-zip method doesn't deploy
+  functions at all.** Confirmed live: a function file placed inside a
+  single whole-site zip (`POST .../deploys` with `Content-Type:
+application/zip`) is served as an inert static asset, never wired up
+  as a Lambda. `deploys.create()`'s `functions` field uses the real flow
+  (SHA1 file manifest + SHA256 function manifest, then
+  `PUT .../functions/{name}?runtime=js`) — this is the only way to ship
+  an actually-invokable function through this API.
+- **A function's zip entry file basename must exactly match the function
+  name.** Confirmed live: naming the function `webhook` but the zip's
+  entry file `handler.mjs` fails at invoke time with
+  `Runtime.ImportModuleError: Cannot find module 'webhook'`. No nested
+  paths either (unlike Vercel's `api/webhook.mjs`) — the file needs to
+  sit at the zip root as `<name>.mjs` (or `.js`).
+- **`runtime: "js"` expects a classic CommonJS/Lambda handler, not the
+  modern `(Request) => Response` style.** Confirmed live: `export default
+(req) => new Response(...)` deploys without error but fails at invoke
+  time with `Runtime.HandlerNotFound: <name>.handler is undefined or not
+exported`. Use `exports.handler = async (event, context) => ({
+statusCode, headers, body })` (or the ESM equivalent, `export const
+handler = ...`) instead.
+- **No build step on a function upload.** Netlify runs no `npm install`
+  or configured build command for a raw API-uploaded function, unlike a
+  Git-linked deploy (or `netlify deploy` run locally via the CLI). If the
+  function imports anything beyond Node builtins, its `zip` needs a real
+  `node_modules` included — resolve dependencies into the zip yourself
+  before calling `create()`.
 - **Sites are account-slug-scoped to create, account-id-scoped for env
   vars.** Netlify's own API is inconsistent here — `POST /{account_slug}/sites`
   but `GET/POST/PUT /accounts/{account_id}/env`. Not something this client
-  can paper over; pass whichever one each method asks for.
+  can paper over; pass whichever one each method asks for. The slug is
+  also mutable (an account/team can rename it in settings) — don't treat
+  a previously-observed slug as permanent.
 - **`state` on a deploy is a free-form string**, not a published enum.
   Known values seen in practice: `new`, `building`, `uploading`,
   `uploaded`, `preparing`, `prepared`, `processing`, `ready`, `error`,

package/dist/index.d.mts

@@ -52,7 +52,36 @@ interface NetlifyDeploy {
   error_message?: string | null;
   created_at: string;
 }
-/** Raw transport details `createFromZip` needs beyond the generic `RestClient` — it sends a binary body, which `RestClient.request()` can't carry (always JSON-encodes a given body). */
+/**
+ * One function to deploy. `zip` is a pre-built archive — the function's
+ * own code plus, if it imports anything beyond Node builtins, a real
+ * `node_modules` (Netlify's raw deploy API runs no build/install step,
+ * unlike a Git-linked deploy — `src/zip.ts`'s `buildZip()` builds this
+ * from `{ path: content }` entries, text or binary).
+ *
+ * Netlify's classic function runtime (`runtime: "js"`) expects a
+ * CommonJS-style `exports.handler` or ESM `export const handler` entry
+ * point — confirmed live: a V2-style `export default (req) => Response`
+ * handler deploys without error but fails at invoke time with
+ * `Runtime.HandlerNotFound`. The entry file's basename (minus extension)
+ * inside the zip should match `name`.
+ */
+interface NetlifyDeployFunctionSpec {
+  /** Becomes invokable at `/.netlify/functions/<name>`. */
+  name: string;
+  /** Lambda runtime: `"js"` (Node.js, zipped) or `"go"` (zipped binary). */
+  runtime?: "js" | "go";
+  zip: Uint8Array;
+}
+interface NetlifyCreateDeployInput {
+  /** Static files, plain text — served as-is, no build step. */
+  files?: Record<string, string>;
+  /** Functions to deploy alongside (or instead of) static files. */
+  functions?: NetlifyDeployFunctionSpec[];
+  /** Process normally but don't make this the published deploy. */
+  draft?: boolean;
+}
+/** Raw transport details `create()` needs beyond the generic `RestClient` — file/function uploads send a binary body, which `RestClient.request()` can't carry (always JSON-encodes a given body). */
 interface NetlifyRawTransport {
   token: string;
   baseUrl?: string;
@@ -95,8 +124,13 @@ interface NetlifyUser {
  * real timestamp would only make otherwise-identical deploys look
  * different in diffs/caches for no benefit.
  */
-/** Builds a STORED-method ZIP archive from `{ path: utf8-content }` entries. */
-declare function buildZip(files: Record<string, string>): Uint8Array;
+/**
+ * Builds a STORED-method ZIP archive from `{ path: content }` entries.
+ * `content` may be a utf8 string (text files) or raw bytes (binary —
+ * native addons, wasm, anything under a real `node_modules` tree a
+ * function's own dependencies need).
+ */
+declare function buildZip(files: Record<string, string | Uint8Array>): Uint8Array;
 //#endregion
 //#region ../../../../../src/index.d.ts
 declare function createNetlifyClient(opts: NetlifyClientOptions): {
@@ -111,9 +145,7 @@ declare function createNetlifyClient(opts: NetlifyClientOptions): {
   };
   deploys: {
     get: (deployId: string) => Promise<NetlifyDeploy>;
-    createFromZip(siteId: string, files: Record<string, string>, opts?: {
-      draft?: boolean;
-    }): Promise<NetlifyDeploy>;
+    create(siteId: string, input?: NetlifyCreateDeployInput): Promise<NetlifyDeploy>;
   };
   env: {
     list: (accountId: string, siteId: string) => Promise<NetlifyEnvVar[]>;
@@ -125,4 +157,4 @@ declare function createNetlifyClient(opts: NetlifyClientOptions): {
 };
 type NetlifyClient = ReturnType<typeof createNetlifyClient>;
 //#endregion
-export { NetlifyClient, type NetlifyClientOptions, type NetlifyCreateSiteInput, type NetlifyDeploy, type NetlifyEnvContext, type NetlifyEnvVar, type NetlifyEnvVarValue, type NetlifyRawTransport, type NetlifySite, type NetlifyUpdateSiteInput, type NetlifyUser, buildZip, createNetlifyClient };
+export { NetlifyClient, type NetlifyClientOptions, type NetlifyCreateDeployInput, type NetlifyCreateSiteInput, type NetlifyDeploy, type NetlifyDeployFunctionSpec, type NetlifyEnvContext, type NetlifyEnvVar, type NetlifyEnvVarValue, type NetlifyRawTransport, type NetlifySite, type NetlifyUpdateSiteInput, type NetlifyUser, buildZip, createNetlifyClient };

package/dist/index.mjs

@@ -1,4 +1,166 @@
+import { createHash } from "node:crypto";
 import { ProviderApiError, createRestClient } from "@theholocron/http-client";
+//#region ../../../../../src/deploys/deploys.ts
+function sha1Hex(bytes) {
+	return createHash("sha1").update(bytes).digest("hex");
+}
+function sha256Hex(bytes) {
+	return createHash("sha256").update(bytes).digest("hex");
+}
+function deploys(rest, raw) {
+	async function uploadRaw(path, body) {
+		const fetchImpl = raw.fetch ?? globalThis.fetch;
+		let baseUrl = raw.baseUrl ?? "https://api.netlify.com/api/v1";
+		while (baseUrl.endsWith("/")) baseUrl = baseUrl.slice(0, -1);
+		const tag = `Netlify PUT ${path}`;
+		let res;
+		try {
+			res = await fetchImpl(`${baseUrl}${path}`, {
+				method: "PUT",
+				headers: {
+					authorization: `Bearer ${raw.token}`,
+					accept: "application/json",
+					"content-type": "application/octet-stream"
+				},
+				body
+			});
+		} catch (err) {
+			const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+			throw new ProviderApiError(`${tag} failed: ${detail}`, 0, void 0);
+		}
+		if (!res.ok) {
+			const resBody = await res.text().catch(() => "");
+			throw new ProviderApiError(`${tag} → ${res.status}`, res.status, resBody);
+		}
+	}
+	return {
+		get: (deployId) => rest.request(`/deploys/${encodeURIComponent(deployId)}`),
+		/**
+		* The digest-based deploy flow: send a manifest of file/function
+		* hashes, then upload only the content Netlify doesn't already have
+		* cached (`required`/`required_functions` in the response — in
+		* practice, for a fresh deploy that's everything). This is the
+		* *only* flow that deploys real, invokable functions — the
+		* single-request whole-zip method (`POST .../deploys` with
+		* `Content-Type: application/zip`) only deploys static assets; a
+		* function file placed in that zip is served as an inert static
+		* file, never wired up as a Lambda (confirmed live).
+		*/
+		async create(siteId, input = {}) {
+			const files = input.files ?? {};
+			const functions = input.functions ?? [];
+			const fileHashes = Object.fromEntries(Object.entries(files).map(([path, content]) => [path, sha1Hex(new TextEncoder().encode(content))]));
+			const functionHashes = Object.fromEntries(functions.map((f) => [f.name, sha256Hex(f.zip)]));
+			const deploy = await rest.request(`/sites/${encodeURIComponent(siteId)}/deploys`, {
+				method: "POST",
+				body: {
+					files: fileHashes,
+					...functions.length > 0 ? { functions: functionHashes } : {},
+					...input.draft ? { draft: true } : {}
+				}
+			});
+			const requiredFiles = new Set(deploy.required ?? []);
+			for (const [path, hash] of Object.entries(fileHashes)) {
+				if (!requiredFiles.has(hash)) continue;
+				await uploadRaw(`/deploys/${deploy.id}/files/${path.replace(/^\//, "")}`, new TextEncoder().encode(files[path]));
+			}
+			const requiredFunctions = new Set(deploy.required_functions ?? []);
+			for (const fn of functions) {
+				if (!requiredFunctions.has(functionHashes[fn.name])) continue;
+				await uploadRaw(`/deploys/${deploy.id}/functions/${encodeURIComponent(fn.name)}?runtime=${fn.runtime ?? "js"}`, fn.zip);
+			}
+			return deploy;
+		}
+	};
+}
+//#endregion
+//#region ../../../../../src/env/env.ts
+function env(rest) {
+	const list = (accountId, siteId) => rest.request(`/accounts/${encodeURIComponent(accountId)}/env`, { query: { site_id: siteId } });
+	return {
+		list,
+		/**
+		* Upsert one value for one context on one key. Netlify's env API has
+		* no single "upsert a value" endpoint — `PUT /env/{key}` replaces the
+		* entire `values` array, and there's no documented "get one key"
+		* endpoint either (only list + PUT/DELETE by key) — so a genuine
+		* upsert needs the key's current full value list first.
+		*/
+		async set(accountId, siteId, key, context, value) {
+			const query = { site_id: siteId };
+			const existing = (await list(accountId, siteId)).find((v) => v.key === key);
+			if (!existing) {
+				await rest.request(`/accounts/${encodeURIComponent(accountId)}/env`, {
+					method: "POST",
+					query,
+					body: {
+						key,
+						scopes: ["functions", "runtime"],
+						values: [{
+							value,
+							context
+						}]
+					}
+				});
+				return;
+			}
+			const values = existing.values.filter((v) => v.context !== context);
+			values.push({
+				value,
+				context
+			});
+			await rest.request(`/accounts/${encodeURIComponent(accountId)}/env/${encodeURIComponent(key)}`, {
+				method: "PUT",
+				query,
+				body: {
+					key,
+					scopes: existing.scopes ?? ["functions", "runtime"],
+					values
+				}
+			});
+		}
+	};
+}
+//#endregion
+//#region ../../../../../src/sites/sites.ts
+function sites(rest) {
+	return {
+		list: () => rest.request("/sites"),
+		get: (siteId) => rest.request(`/sites/${encodeURIComponent(siteId)}`),
+		/** Scoped to `/{account_slug}/sites` — Netlify has no account-id-based create path. */
+		create: (accountSlug, input) => rest.request(`/${encodeURIComponent(accountSlug)}/sites`, {
+			method: "POST",
+			body: input
+		}),
+		update: (siteId, input) => rest.request(`/sites/${encodeURIComponent(siteId)}`, {
+			method: "PATCH",
+			body: input
+		}),
+		/** Triggers a new build from the latest commit on a git-linked site's default branch. */
+		triggerBuild: (siteId) => rest.request(`/sites/${encodeURIComponent(siteId)}/builds`, {
+			method: "POST",
+			body: { clear_cache: false }
+		})
+	};
+}
+//#endregion
+//#region ../../../../../src/user/user.ts
+function user(rest) {
+	return { get: () => rest.request("/user") };
+}
+//#endregion
+//#region ../../../../../src/utils.ts
+function createNetlifyRestClient(opts) {
+	return createRestClient({
+		baseUrl: opts.baseUrl ?? "https://api.netlify.com/api/v1",
+		token: opts.token,
+		vendor: "Netlify",
+		fetch: opts.fetch,
+		logger: opts.logger,
+		errors: opts.errors
+	});
+}
+//#endregion
 //#region ../../../../../src/zip.ts
 /**
 * Minimal ZIP archive builder — STORED (uncompressed) entries only, no
@@ -42,11 +204,16 @@ function crc32(data) {
 	for (const byte of data) crc = CRC_TABLE[(crc ^ byte) & 255] ^ crc >>> 8;
 	return (crc ^ 4294967295) >>> 0;
 }
-/** Builds a STORED-method ZIP archive from `{ path: utf8-content }` entries. */
+/**
+* Builds a STORED-method ZIP archive from `{ path: content }` entries.
+* `content` may be a utf8 string (text files) or raw bytes (binary —
+* native addons, wasm, anything under a real `node_modules` tree a
+* function's own dependencies need).
+*/
 function buildZip(files) {
 	const entries = Object.entries(files).map(([path, content]) => ({
 		path: path.startsWith("/") ? path.slice(1) : path,
-		content: new TextEncoder().encode(content)
+		content: typeof content === "string" ? new TextEncoder().encode(content) : content
 	}));
 	const localParts = [];
 	const centralParts = [];
@@ -113,136 +280,6 @@ function buildZip(files) {
 	return total;
 }
 //#endregion
-//#region ../../../../../src/deploys/deploys.ts
-function deploys(rest, raw) {
-	return {
-		get: (deployId) => rest.request(`/deploys/${encodeURIComponent(deployId)}`),
-		/**
-		* Zips `files` (plain text) and uploads as a one-shot deploy via
-		* `POST /sites/{id}/deploys` with `Content-Type: application/zip`.
-		* Netlify runs no build step for a raw zip upload (unlike a
-		* Git-linked deploy) — the caller is responsible for having already
-		* resolved dependencies into the file set.
-		*/
-		async createFromZip(siteId, files, opts = {}) {
-			const fetchImpl = raw.fetch ?? globalThis.fetch;
-			let baseUrl = raw.baseUrl ?? "https://api.netlify.com/api/v1";
-			while (baseUrl.endsWith("/")) baseUrl = baseUrl.slice(0, -1);
-			const url = new URL(`${baseUrl}/sites/${encodeURIComponent(siteId)}/deploys`);
-			if (opts.draft) url.searchParams.set("draft", "true");
-			const zip = buildZip(files);
-			const tag = `Netlify POST /sites/${siteId}/deploys`;
-			let res;
-			try {
-				res = await fetchImpl(url.toString(), {
-					method: "POST",
-					headers: {
-						authorization: `Bearer ${raw.token}`,
-						accept: "application/json",
-						"content-type": "application/zip"
-					},
-					body: zip
-				});
-			} catch (err) {
-				const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
-				throw new ProviderApiError(`${tag} failed: ${detail}`, 0, void 0);
-			}
-			if (!res.ok) {
-				const body = await res.text().catch(() => "");
-				throw new ProviderApiError(`${tag} → ${res.status}`, res.status, body);
-			}
-			return await res.json();
-		}
-	};
-}
-//#endregion
-//#region ../../../../../src/env/env.ts
-function env(rest) {
-	const list = (accountId, siteId) => rest.request(`/accounts/${encodeURIComponent(accountId)}/env`, { query: { site_id: siteId } });
-	return {
-		list,
-		/**
-		* Upsert one value for one context on one key. Netlify's env API has
-		* no single "upsert a value" endpoint — `PUT /env/{key}` replaces the
-		* entire `values` array, and there's no documented "get one key"
-		* endpoint either (only list + PUT/DELETE by key) — so a genuine
-		* upsert needs the key's current full value list first.
-		*/
-		async set(accountId, siteId, key, context, value) {
-			const query = { site_id: siteId };
-			const existing = (await list(accountId, siteId)).find((v) => v.key === key);
-			if (!existing) {
-				await rest.request(`/accounts/${encodeURIComponent(accountId)}/env`, {
-					method: "POST",
-					query,
-					body: {
-						key,
-						scopes: ["functions", "runtime"],
-						values: [{
-							value,
-							context
-						}]
-					}
-				});
-				return;
-			}
-			const values = existing.values.filter((v) => v.context !== context);
-			values.push({
-				value,
-				context
-			});
-			await rest.request(`/accounts/${encodeURIComponent(accountId)}/env/${encodeURIComponent(key)}`, {
-				method: "PUT",
-				query,
-				body: {
-					key,
-					scopes: existing.scopes ?? ["functions", "runtime"],
-					values
-				}
-			});
-		}
-	};
-}
-//#endregion
-//#region ../../../../../src/sites/sites.ts
-function sites(rest) {
-	return {
-		list: () => rest.request("/sites"),
-		get: (siteId) => rest.request(`/sites/${encodeURIComponent(siteId)}`),
-		/** Scoped to `/{account_slug}/sites` — Netlify has no account-id-based create path. */
-		create: (accountSlug, input) => rest.request(`/${encodeURIComponent(accountSlug)}/sites`, {
-			method: "POST",
-			body: input
-		}),
-		update: (siteId, input) => rest.request(`/sites/${encodeURIComponent(siteId)}`, {
-			method: "PATCH",
-			body: input
-		}),
-		/** Triggers a new build from the latest commit on a git-linked site's default branch. */
-		triggerBuild: (siteId) => rest.request(`/sites/${encodeURIComponent(siteId)}/builds`, {
-			method: "POST",
-			body: { clear_cache: false }
-		})
-	};
-}
-//#endregion
-//#region ../../../../../src/user/user.ts
-function user(rest) {
-	return { get: () => rest.request("/user") };
-}
-//#endregion
-//#region ../../../../../src/utils.ts
-function createNetlifyRestClient(opts) {
-	return createRestClient({
-		baseUrl: opts.baseUrl ?? "https://api.netlify.com/api/v1",
-		token: opts.token,
-		vendor: "Netlify",
-		fetch: opts.fetch,
-		logger: opts.logger,
-		errors: opts.errors
-	});
-}
-//#endregion
 //#region ../../../../../src/index.ts
 function createNetlifyClient(opts) {
 	const rest = createNetlifyRestClient(opts);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/netlify-client",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "description": "A TypeScript client for the Netlify API",
   "keywords": [
     "netlify",
@@ -33,7 +33,7 @@
   ],
   "dependencies": {
     "@theholocron/observability": "^0.3.0",
-    "@theholocron/http-client": "^1.36.0"
+    "@theholocron/http-client": "^1.38.0"
   },
   "devDependencies": {
     "@theholocron/cli": "5.0.0-alpha.79",