@notionhq/workers 0.7.0 → 0.8.1

package/src/worker.test.ts

@@ -1,11 +1,26 @@
 import { describe, expect, it } from "vitest";
 
+import { CREDENTIAL_VALUE } from "./credential.js";
 import * as Schema from "./schema.js";
 import { Worker } from "./worker.js";
 
 describe("Worker", () => {
-	it("includes sdkVersion, databases, and capabilities in manifest", () => {
+	it("includes sdkVersion, credentials, databases, and capabilities in manifest", () => {
 		const worker = new Worker();
+		worker.credential("LINEAR_API_TOKEN", {
+			network: [
+				{
+					domain: "api.linear.com",
+					transform: [
+						{
+							headers: {
+								Authorization: `Bearer ${CREDENTIAL_VALUE}`,
+							},
+						},
+					],
+				},
+			],
+		});
 		const tasks = worker.database("tasks", {
 			type: "managed",
 			initialTitle: "Tasks",
@@ -26,6 +41,23 @@ describe("Worker", () => {
 		});
 
 		expect(worker.manifest.sdkVersion).toMatch(/^\d+\.\d+\.\d+/);
+		expect(worker.manifest.credentials).toEqual([
+			{
+				key: "LINEAR_API_TOKEN",
+				network: [
+					{
+						domain: "api.linear.com",
+						transform: [
+							{
+								headers: {
+									Authorization: "Bearer {{credential}}",
+								},
+							},
+						],
+					},
+				],
+			},
+		]);
 		expect(worker.manifest.databases).toEqual([
 			{
 				key: "tasks",
@@ -141,7 +173,154 @@ describe("Worker", () => {
 		]);
 	});
 
-	it("rejects duplicate keys across databases, pacers, and capabilities", () => {
+	it("registers a project custom block from a folder path (type defaults to project)", () => {
+		const worker = new Worker();
+
+		worker.customBlock("visualBlock", {
+			path: "./views/visual",
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "visualBlock",
+				config: {
+					source: { type: "project", path: "./views/visual" },
+					manifest: {
+						version: 1,
+						dataSources: {},
+					},
+				},
+			},
+		]);
+	});
+
+	it("carries a project's custom build command and output dir", () => {
+		const worker = new Worker();
+
+		worker.customBlock("built", {
+			path: "./app",
+			command: "npm run build-prod",
+			output: "build",
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "built",
+				config: {
+					source: {
+						type: "project",
+						path: "./app",
+						command: "npm run build-prod",
+						output: "build",
+					},
+					manifest: { version: 1, dataSources: {} },
+				},
+			},
+		]);
+	});
+
+	it("registers a static custom block served as-is", () => {
+		const worker = new Worker();
+
+		worker.customBlock("prebuilt", { type: "static", path: "./dist" });
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "prebuilt",
+				config: {
+					source: { type: "static", path: "./dist" },
+					manifest: { version: 1, dataSources: {} },
+				},
+			},
+		]);
+	});
+
+	it("carries the author-declared data-source schema verbatim into the manifest", () => {
+		const worker = new Worker();
+
+		worker.customBlock("issueBoard", {
+			path: "./views/issueBoard",
+			dataSources: {
+				issues: {
+					name: "Issues",
+					description: "The team's issues",
+					icon: { type: "emoji", emoji: "🐛" },
+					properties: {
+						title: { name: "Title", type: "title" },
+						status: {
+							name: "Status",
+							description: "Workflow state",
+							type: "status",
+						},
+					},
+				},
+			},
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "issueBoard",
+				config: {
+					source: { type: "project", path: "./views/issueBoard" },
+					manifest: {
+						version: 1,
+						dataSources: {
+							issues: {
+								name: "Issues",
+								description: "The team's issues",
+								icon: { type: "emoji", emoji: "🐛" },
+								properties: {
+									title: { name: "Title", type: "title" },
+									status: {
+										name: "Status",
+										description: "Workflow state",
+										type: "status",
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		]);
+	});
+
+	it("threads a top-level manifest version into the generated manifest", () => {
+		const worker = new Worker();
+
+		worker.customBlock("versioned", {
+			path: "./views/versioned",
+			version: 1,
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "versioned",
+				config: {
+					source: { type: "project", path: "./views/versioned" },
+					manifest: { version: 1, dataSources: {} },
+				},
+			},
+		]);
+	});
+
+	it("cannot run a custom block capability", async () => {
+		const worker = new Worker();
+		worker.customBlock("visualBlock", {
+			path: "./views/visual",
+		});
+
+		await expect(worker.run("visualBlock", {})).rejects.toThrow(
+			'Cannot run custom block capability "visualBlock"',
+		);
+	});
+
+	it("rejects duplicate keys across credentials, databases, pacers, and capabilities", () => {
 		const worker = new Worker();
 		const db = worker.database("shared-key", {
 			type: "managed",
@@ -154,6 +333,23 @@ describe("Worker", () => {
 			},
 		});
 
+		expect(() =>
+			worker.credential("shared-key", {
+				network: [
+					{
+						domain: "api.example.com",
+						transform: [
+							{
+								headers: {
+									Authorization: CREDENTIAL_VALUE,
+								},
+							},
+						],
+					},
+				],
+			}),
+		).toThrow('Worker item with key "shared-key" already registered');
+
 		expect(() =>
 			worker.sync("shared-key", {
 				database: db,
@@ -164,4 +360,106 @@ describe("Worker", () => {
 			}),
 		).toThrow('Worker item with key "shared-key" already registered');
 	});
+
+	it("does not reserve a key when registration fails", () => {
+		const worker = new Worker();
+
+		expect(() =>
+			worker.credential("REUSABLE_KEY", {
+				network: [],
+			}),
+		).toThrow("must declare at least one network rule");
+
+		expect(() =>
+			worker.pacer("REUSABLE_KEY", {
+				allowedRequests: 10,
+				intervalMs: 1_000,
+			}),
+		).not.toThrow();
+	});
+
+	it("rejects credentials that target the same domain and header", () => {
+		const worker = new Worker();
+		worker.credential("FIRST_TOKEN", {
+			network: [
+				{
+					domain: "api.example.com",
+					transform: [{ headers: { Authorization: `Bearer ${CREDENTIAL_VALUE}` } }],
+				},
+			],
+		});
+
+		expect(() =>
+			worker.credential("SECOND_TOKEN", {
+				network: [
+					{
+						domain: "API.EXAMPLE.COM",
+						transform: [{ headers: { authorization: CREDENTIAL_VALUE } }],
+					},
+				],
+			}),
+		).toThrow('conflicts with credential "FIRST_TOKEN"');
+	});
+
+	it("limits the number of credential declarations", () => {
+		const worker = new Worker();
+		for (let index = 0; index < 100; index += 1) {
+			worker.credential(`TOKEN_${index}`, {
+				network: [
+					{
+						domain: `api${index}.example.com`,
+						transform: [{ headers: { Authorization: CREDENTIAL_VALUE } }],
+					},
+				],
+			});
+		}
+
+		expect(() =>
+			worker.credential("ONE_TOO_MANY", {
+				network: [
+					{
+						domain: "overflow.example.com",
+						transform: [{ headers: { Authorization: CREDENTIAL_VALUE } }],
+					},
+				],
+			}),
+		).toThrow("cannot declare more than 100 credentials");
+	});
+
+	it("matches the service limit for the credential declaration payload", () => {
+		const worker = new Worker();
+		for (let index = 0; index < 32; index += 1) {
+			worker.credential(`TOKEN_${index}`, {
+				network: [
+					{
+						domain: `api${index}.example.com`,
+						transform: [
+							{
+								headers: {
+									Authorization: `${"x".repeat(8_000)}${CREDENTIAL_VALUE}`,
+								},
+							},
+						],
+					},
+				],
+			});
+		}
+
+		expect(() =>
+			worker.credential("TOKEN_32", {
+				network: [
+					{
+						domain: "api32.example.com",
+						transform: [
+							{
+								headers: {
+									Authorization: `${"x".repeat(8_000)}${CREDENTIAL_VALUE}`,
+								},
+							},
+						],
+					},
+				],
+			}),
+		).toThrow("credential declarations must be at most 262144 bytes");
+	});
 });

package/src/worker.ts

@@ -11,6 +11,11 @@ import type {
 } from "./capabilities/automation.js";
 import { createAutomationCapability } from "./capabilities/automation.js";
 import type { CapabilityContext } from "./capabilities/context.js";
+import type {
+	CustomBlockCapability,
+	CustomBlockConfiguration,
+} from "./capabilities/custom-block.js";
+import { createCustomBlockCapability } from "./capabilities/custom-block.js";
 import type {
 	NotionManagedOAuthConfiguration,
 	OAuthCapability,
@@ -34,6 +39,17 @@ import type {
 	WorkflowEvent,
 } from "./capabilities/workflow.js";
 import { createWorkflowCapability } from "./capabilities/workflow.js";
+import type {
+	CredentialConfiguration,
+	CredentialDeclaration,
+	CredentialKey,
+} from "./credential.js";
+import {
+	createCredentialDeclaration,
+	MAX_CREDENTIAL_DECLARATIONS_BYTES,
+	MAX_CREDENTIALS,
+	validateCredentialDeclarationConflicts,
+} from "./credential.js";
 import type { PacerDeclaration } from "./pacer_internal.js";
 import { pacerWait } from "./pacer_internal.js";
 import type { Schema } from "./schema.js";
@@ -69,7 +85,8 @@ type Capability =
 	| AutomationCapability
 	| WorkflowCapability
 	| OAuthCapability
-	| WebhookCapability;
+	| WebhookCapability
+	| CustomBlockCapability;
 
 export type CapabilityType = Capability["_tag"];
 
@@ -105,6 +122,7 @@ type StoredCapability =
 	| AutomationCapability
 	| StoredWorkflowCapability
 	| OAuthCapability
+	| CustomBlockCapability
 	| WebhookCapability;
 
 /**
@@ -205,6 +223,7 @@ type CapabilityManifestEntry = Pick<Capability, "_tag" | "key" | "config">;
  */
 export type WorkerManifest = {
 	readonly sdkVersion: string;
+	readonly credentials: readonly CredentialDeclaration[];
 	readonly databases: readonly RegisteredDatabase[];
 	readonly pacers: readonly PacerDeclaration[];
 	readonly capabilities: readonly CapabilityManifestEntry[];
@@ -236,9 +255,33 @@ const SDK_VERSION = (() => {
 
 export class Worker {
 	#capabilities: Map<string, StoredCapability> = new Map();
+	#credentials: Map<string, CredentialDeclaration> = new Map();
 	#databases: Map<string, RegisteredDatabase> = new Map();
 	#pacers: Map<string, PacerDeclaration> = new Map();
 
+	/**
+	 * Declare a credential that is injected into matching outbound HTTPS
+	 * requests without exposing its value to Worker code.
+	 */
+	credential(key: CredentialKey, config: CredentialConfiguration): void {
+		this.#validateUniqueKey(key);
+		if (this.#credentials.size >= MAX_CREDENTIALS) {
+			throw new Error(`Worker cannot declare more than ${MAX_CREDENTIALS} credentials`);
+		}
+		const declaration = createCredentialDeclaration(key, config);
+		validateCredentialDeclarationConflicts(this.#credentials.values(), declaration);
+		const declarations = [...this.#credentials.values(), declaration];
+		if (
+			new TextEncoder().encode(JSON.stringify(declarations)).byteLength >
+			MAX_CREDENTIAL_DECLARATIONS_BYTES
+		) {
+			throw new Error(
+				`Worker credential declarations must be at most ${MAX_CREDENTIAL_DECLARATIONS_BYTES} bytes`,
+			);
+		}
+		this.#credentials.set(key, declaration);
+	}
+
 	database<PK extends string, S extends Schema<PK>>(
 		key: string,
 		config: DatabaseConfig<PK, S>,
@@ -609,6 +652,51 @@ export class Worker {
 		return capability;
 	}
 
+	/**
+	 * Register a custom block capability.
+	 *
+	 * A custom block is a front-end view that the deploy pipeline builds from
+	 * the source entry into a deployable bundle. It can optionally declare a
+	 * data-source *schema* (`name`, and optional `description`, `icon`, and
+	 * `properties`) that the block reads.
+	 *
+	 * Example:
+	 *
+	 * ```ts
+	 * const worker = new Worker();
+	 * export default worker;
+	 *
+	 * worker.customBlock("issueBoard", {
+	 *   version: 1,
+	 *   path: "./views/issueBoard",
+	 *   dataSources: {
+	 *     issues: {
+	 *       name: "Issues",
+	 *       properties: {
+	 *         title: { name: "Title", type: "title" },
+	 *         status: { name: "Status", type: "status" },
+	 *       },
+	 *     },
+	 *   },
+	 * });
+	 * ```
+	 *
+	 * The manifest keys (`version`, `dataSources`) are top-level on the config;
+	 * the SDK assembles the deploy-wire `CustomBlockManifest` from them. Binding
+	 * each declared data source to a concrete managed database is instance-level
+	 * and handled at deploy time — the worker does not emit bindings.
+	 *
+	 * @param key - The unique key for this block (the block declaration key).
+	 * @param config - The custom block configuration (a `project`/`static` source folder + optional `version`/`dataSources` schema).
+	 * @returns The custom block capability.
+	 */
+	customBlock(key: string, config: CustomBlockConfiguration): CustomBlockCapability {
+		this.#validateUniqueKey(key);
+		const capability = createCustomBlockCapability(key, config);
+		this.#capabilities.set(key, capability);
+		return capability;
+	}
+
 	/**
 	 * Get all registered capabilities (for discovery) without their handlers.
 	 */
@@ -623,6 +711,7 @@ export class Worker {
 	get manifest(): WorkerManifest {
 		return {
 			sdkVersion: SDK_VERSION,
+			credentials: Array.from(this.#credentials.values()),
 			databases: Array.from(this.#databases.values()),
 			pacers: Array.from(this.#pacers.values()),
 			capabilities: this.capabilities,
@@ -650,6 +739,12 @@ export class Worker {
 			);
 		}
 
+		if (capability._tag === "custom_block") {
+			throw new Error(
+				`Cannot run custom block capability "${key}" - custom blocks only provide configuration`,
+			);
+		}
+
 		if (!capability.handler) {
 			throw new Error(`Capability "${key}" cannot be executed`);
 		}
@@ -665,7 +760,12 @@ export class Worker {
 		if (!key || typeof key !== "string") {
 			throw new Error("Capability key must be a non-empty string");
 		}
-		if (this.#capabilities.has(key) || this.#databases.has(key) || this.#pacers.has(key)) {
+		if (
+			this.#capabilities.has(key) ||
+			this.#credentials.has(key) ||
+			this.#databases.has(key) ||
+			this.#pacers.has(key)
+		) {
 			throw new Error(`Worker item with key "${key}" already registered`);
 		}
 	}