@notionhq/workers 0.7.0 → 0.8.1

package/dist/worker.js

@@ -1,10 +1,17 @@
 import { createAiConnectorCapability } from "./capabilities/ai_connector.js";
 import { createAutomationCapability } from "./capabilities/automation.js";
+import { createCustomBlockCapability } from "./capabilities/custom-block.js";
 import { createOAuthCapability } from "./capabilities/oauth.js";
 import { createSyncCapability } from "./capabilities/sync.js";
 import { createToolCapability } from "./capabilities/tool.js";
 import { createWebhookCapability, WebhookVerificationError } from "./capabilities/webhook.js";
 import { createWorkflowCapability } from "./capabilities/workflow.js";
+import {
+  createCredentialDeclaration,
+  MAX_CREDENTIAL_DECLARATIONS_BYTES,
+  MAX_CREDENTIALS,
+  validateCredentialDeclarationConflicts
+} from "./credential.js";
 import { pacerWait } from "./pacer_internal.js";
 import { createRequire } from "node:module";
 const SDK_VERSION = (() => {
@@ -17,8 +24,28 @@ const SDK_VERSION = (() => {
 })();
 class Worker {
   #capabilities = /* @__PURE__ */ new Map();
+  #credentials = /* @__PURE__ */ new Map();
   #databases = /* @__PURE__ */ new Map();
   #pacers = /* @__PURE__ */ new Map();
+  /**
+   * Declare a credential that is injected into matching outbound HTTPS
+   * requests without exposing its value to Worker code.
+   */
+  credential(key, config) {
+    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(key, config) {
     this.#validateUniqueKey(key);
     const database = { key, config };
@@ -365,6 +392,50 @@ class Worker {
     this.#capabilities.set(key, capability);
     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, config) {
+    this.#validateUniqueKey(key);
+    const capability = createCustomBlockCapability(key, config);
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
   /**
    * Get all registered capabilities (for discovery) without their handlers.
    */
@@ -378,6 +449,7 @@ class Worker {
   get manifest() {
     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
@@ -401,6 +473,11 @@ class Worker {
         `Cannot run OAuth capability "${key}" - OAuth capabilities only provide configuration`
       );
     }
+    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`);
     }
@@ -410,7 +487,7 @@ 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`);
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/workers",
-	"version": "0.7.0",
+	"version": "0.8.1",
 	"description": "An SDK for building workers for the Notion Workers platform",
 	"license": "MIT",
 	"bin": {

package/src/alpha/workflow.test.ts

@@ -1,8 +1,8 @@
-import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
+import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi, type Mock } from "vitest";
 
 import { ExecutionError } from "./error.js";
 import { triggers, type NotionPageCreatedEvent } from "./triggers.generated.js";
-import { createWorkflow } from "./workflow.js";
+import { createWorkflow, type StepContext, type WorkflowContext } from "./workflow.js";
 
 let stdoutSpy: Mock<typeof process.stdout.write>;
 
@@ -16,6 +16,128 @@ afterEach(() => {
 
 const event = { type: "notion.page.created" } as NotionPageCreatedEvent;
 
+async function createWorkflowContext(): Promise<WorkflowContext> {
+	let context: WorkflowContext | undefined;
+	const workflow = createWorkflow({
+		title: "Test workflow",
+		description: "Captures its workflow context",
+		triggers: [triggers.notionPageCreated()],
+		handler: (_event, workflowContext) => {
+			context = workflowContext;
+		},
+	});
+
+	await workflow.handler(event, { concreteOutput: true });
+
+	if (!context) {
+		throw new Error("Workflow context was not created");
+	}
+
+	return context;
+}
+
+describe("step", () => {
+	it("runs a synchronous callback and writes success events in order", async () => {
+		const { step } = await createWorkflowContext();
+		let context: StepContext | undefined;
+		const resultPromise = step("Fetch page", (stepContext) => {
+			context = stepContext;
+			return { pageId: "page-1" } as const;
+		});
+
+		expectTypeOf(resultPromise).toEqualTypeOf<Promise<{ readonly pageId: "page-1" }>>();
+		await expect(resultPromise).resolves.toEqual({ pageId: "page-1" });
+
+		expect(context).toBeDefined();
+		const id = context!.id;
+		expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+		expect(stdoutSpy.mock.calls.map(([output]) => output)).toEqual([
+			`\n<__notion_step_started__>{"id":"${id}","name":"Fetch page"}</__notion_step_started__>\n`,
+			`\n<__notion_step_success__>{"id":"${id}","name":"Fetch page","value":{"pageId":"page-1"}}</__notion_step_success__>\n`,
+			`\n<__notion_step_completed__>{"id":"${id}","name":"Fetch page","type":"success"}</__notion_step_completed__>\n`,
+		]);
+	});
+
+	it("embeds the invocation timestamp in the UUID v7", async () => {
+		const { step } = await createWorkflowContext();
+		const now = 1_721_234_567_890;
+		const nowSpy = vi.spyOn(Date, "now").mockReturnValue(now);
+		let id = "";
+
+		try {
+			await step("Timestamped", async (context) => {
+				id = context.id;
+			});
+		} finally {
+			nowSpy.mockRestore();
+		}
+
+		expect(Number.parseInt(id.replaceAll("-", "").slice(0, 12), 16)).toBe(now);
+	});
+
+	it("uses a distinct UUID for each invocation", async () => {
+		const { step } = await createWorkflowContext();
+		const ids: string[] = [];
+
+		await step("First", ({ id }) => {
+			ids.push(id);
+		});
+		await step("Second", ({ id }) => {
+			ids.push(id);
+		});
+
+		expect(new Set(ids).size).toBe(2);
+	});
+
+	it("writes failure events in order and rethrows the original error", async () => {
+		const { step } = await createWorkflowContext();
+		const originalError = new Error("boom");
+		let id = "";
+		const fn = vi.fn((context: StepContext) => {
+			id = context.id;
+			throw originalError;
+		});
+
+		await expect(step("Explode", fn)).rejects.toBe(originalError);
+
+		expect(fn).toHaveBeenCalledOnce();
+		expect(stdoutSpy).toHaveBeenCalledTimes(3);
+		expect(stdoutSpy.mock.calls[0]?.[0]).toBe(
+			`\n<__notion_step_started__>{"id":"${id}","name":"Explode"}</__notion_step_started__>\n`,
+		);
+		expect(stdoutSpy.mock.calls[1]?.[0]).toEqual(
+			expect.stringContaining(
+				`<__notion_step_failure__>{"id":"${id}","name":"Explode","error":{"name":"ExecutionError","message":"Error during worker execution: Error: boom","trace":`,
+			),
+		);
+		expect(stdoutSpy.mock.calls[2]?.[0]).toBe(
+			`\n<__notion_step_completed__>{"id":"${id}","name":"Explode","type":"failure"}</__notion_step_completed__>\n`,
+		);
+	});
+
+	it("writes step events under concreteOutput", async () => {
+		const workflow = createWorkflow({
+			title: "Log Pages",
+			description: "Logs created pages",
+			triggers: [triggers.notionPageCreated()],
+			handler: async (_event, context) => {
+				await context.step("Always visible", () => "done");
+			},
+		});
+
+		await workflow.handler(event, { concreteOutput: true });
+
+		expect(stdoutSpy).toHaveBeenCalledTimes(3);
+		expect(stdoutSpy.mock.calls[0]?.[0]).toEqual(
+			expect.stringContaining("<__notion_step_started__>"),
+		);
+		expect(stdoutSpy.mock.calls[1]?.[0]).toEqual(
+			expect.stringContaining("<__notion_step_success__>"),
+		);
+		expect(stdoutSpy.mock.calls[2]?.[0]).toEqual(expect.stringContaining('"type":"success"'));
+	});
+});
+
 describe("createWorkflow", () => {
 	it("is tagged and exposes triggers in config", () => {
 		const workflow = createWorkflow({

package/src/alpha/workflow.ts

@@ -37,7 +37,7 @@ export type WorkflowConfiguration<
 
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
-		context: CapabilityContext,
+		context: WorkflowContext,
 	) => Promise<void> | void;
 };
 
@@ -81,8 +81,12 @@ export type Workflow<
  *   title: "Send Welcome Email",
  *   description: "Sends a welcome email when a new page is added",
  *   triggers: [triggers.notionPageCreated()],
- *   handler: async (event) => {
+ *   handler: async (event, context) => {
  *     console.log(event.page);
+ *     await context.step("Process page", async ({ id }) => {
+ *       console.log(`Running step ${id}`);
+ *       return processPage(event.page);
+ *     });
  *   },
  * });
  * ```
@@ -102,7 +106,10 @@ export function createWorkflow<
 			options?: HandlerOptions,
 		): Promise<{ status: "success" } | undefined> {
 			try {
-				const capabilityContext = createCapabilityContext("workflow");
+				const capabilityContext: WorkflowContext = {
+					...createCapabilityContext("workflow"),
+					step,
+				};
 				await configuration.handler(event, capabilityContext);
 
 				if (options?.concreteOutput) {
@@ -129,3 +136,85 @@ export function createWorkflow<
 		},
 	};
 }
+
+/** Context passed to a workflow step. */
+export type StepContext = {
+	/** An identifier for this invocation of the step. May be used as an idempotency key. */
+	id: string;
+};
+
+/** Context passed to a workflow handler. */
+export type WorkflowContext = CapabilityContext & {
+	/**
+	 * Run an observable unit of work within the workflow.
+	 *
+	 * The callback may be synchronous or asynchronous, but `step` always returns
+	 * a promise. Its return value must be JSON-serializable so it can be included
+	 * in the success event written to stdout.
+	 *
+	 * @example
+	 * ```ts
+	 * const page = await context.step("Fetch page", async ({ id }) => {
+	 *   console.log(`Running step ${id}`);
+	 *   return context.notion.pages.retrieve({ page_id: pageId });
+	 * });
+	 * ```
+	 */
+	step: <T>(name: string, fn: (context: StepContext) => T | Promise<T>) => Promise<T>;
+};
+
+type StepCompletionType = "success" | "failure";
+
+function generateUuidV7(): string {
+	const bytes = crypto.getRandomValues(new Uint8Array(16));
+	let timestamp = Date.now();
+
+	// UUID v7 stores the Unix timestamp in milliseconds in its first 48 bits.
+	for (let index = 5; index >= 0; index--) {
+		bytes[index] = timestamp % 256;
+		timestamp = Math.floor(timestamp / 256);
+	}
+
+	bytes[6] = (bytes[6]! & 0x0f) | 0x70;
+	bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function writeStepEvent(event: "started" | "success" | "failure" | "completed", value: unknown) {
+	const tag = `__notion_step_${event}__`;
+	process.stdout.write(`\n<${tag}>${JSON.stringify(value)}</${tag}>\n`);
+}
+
+async function step<T>(name: string, fn: (context: StepContext) => T | Promise<T>): Promise<T> {
+	const context: StepContext = { id: generateUuidV7() };
+	const event = { id: context.id, name };
+
+	writeStepEvent("started", event);
+
+	try {
+		const value = await fn(context);
+		writeStepEvent("success", { ...event, value });
+		writeStepEvent("completed", {
+			...event,
+			type: "success" satisfies StepCompletionType,
+		});
+		return value;
+	} catch (err) {
+		const error = new ExecutionError(err);
+		writeStepEvent("failure", {
+			...event,
+			error: {
+				name: error.name,
+				message: error.message,
+				trace: error.stack,
+			},
+		});
+		writeStepEvent("completed", {
+			...event,
+			type: "failure" satisfies StepCompletionType,
+		});
+		throw err;
+	}
+}

package/src/capabilities/custom-block.ts

@@ -0,0 +1,181 @@
+// ============================================================================
+// Custom Block Authoring API
+// ============================================================================
+
+/**
+ * Icon for a custom block data source. Mirrors the server/client
+ * `CustomBlockManifestIcon` (`@notionhq/shared/customViews/customBlockManifestTypes`).
+ */
+export type CustomBlockManifestIcon =
+	| { type: "emoji"; emoji: string }
+	| { type: "external"; url: string };
+
+/**
+ * Public-API-shaped property type names usable in a custom block manifest.
+ */
+export type CustomBlockManifestPropertyType =
+	| "title"
+	| "rich_text"
+	| "number"
+	| "select"
+	| "multi_select"
+	| "status"
+	| "date"
+	| "people"
+	| "files"
+	| "checkbox"
+	| "url"
+	| "email"
+	| "phone_number"
+	| "formula"
+	| "relation"
+	| "rollup"
+	| "created_time"
+	| "created_by"
+	| "last_edited_time"
+	| "last_edited_by"
+	| "last_visited_time"
+	| "button"
+	| "unique_id"
+	| "location"
+	| "verification"
+	| "place";
+
+/**
+ * Describes a single property exposed by a custom block data source.
+ */
+export type CustomBlockManifestProperty = {
+	name: string;
+	description?: string;
+	type: CustomBlockManifestPropertyType;
+};
+
+/**
+ * Rich schema describing one of a custom block's data sources.
+ */
+export type CustomBlockManifestDataSource = {
+	/** Display name for the data source. */
+	name: string;
+	/** Optional human-readable description of the data source. */
+	description?: string;
+	/** Optional icon for the data source. */
+	icon?: CustomBlockManifestIcon;
+	/** Optional property schema keyed by property key. */
+	properties?: Record<string, CustomBlockManifestProperty>;
+};
+
+export type CustomBlockManifest = {
+	version: 1;
+	/**
+	 * The block's datasources schema, mapping keys you name to {@link CustomBlockManifestDataSource}
+	 *
+	 * @example
+	 *
+	 * {
+	 *   "myDataSource": {
+	 *     "name": "My Data Source",
+	 *     "description": "A description of my data source",
+	 *     "icon": "icon.png",
+	 *     "properties": {
+	 *       "property1": {
+	 *         "name": "Property 1",
+	 *         "type": "string"
+	 *       }
+	 *     }
+	 *   }
+	 * }
+	 */
+	dataSources: Record<string, CustomBlockManifestDataSource>;
+};
+
+/**
+ * A custom block is a front-end web app served in an iframe in the client with live data access.
+ *
+ * Available `type`s are `project` (a buildable project dir) and `static` (an already-built dir served as-is).
+ */
+export type CustomBlockConfiguration = (
+	| {
+			/** Buildable project dir (the default). */
+			type?: "project";
+			/** Path to the project dir, relative to the worker root (e.g. `"./blocks/foo"`). */
+			path: string;
+			/** Build command run in `path`. Defaults to `npm run build`. */
+			command?: string;
+			/** Built-output dir relative to `path`. Defaults to `dist`. */
+			output?: string;
+	  }
+	| {
+			/** An already-built browser-bundle dir; served as-is, no build step. */
+			type: "static";
+			/** Path to the prebuilt dir, relative to the worker root. */
+			path: string;
+			command?: never;
+			output?: never;
+	  }
+) &
+	Partial<CustomBlockManifest>;
+
+/**
+ * The build source of a custom block, mirroring the server's
+ * `BlockSourceDeclaration`. `project` is a buildable dir (`command` defaults to
+ * `npm run build`, `output` to `dist`); `static` is an already-built dir served
+ * as-is.
+ */
+export type BlockSourceDeclaration =
+	| { type: "project"; path: string; command?: string; output?: string }
+	| { type: "static"; path: string };
+
+/**
+ * Config payload carried in the runtime manifest for a `_tag: "custom_block"`
+ * capability entry. The server parses this (see `RawBlockCapabilityConfig` in
+ * `capabilities-service.ts`): `source` is the build entry and `manifest` is the
+ * author-declared {@link CustomBlockManifest} describing the block's data-source
+ * schema. Data-source *bindings* are instance-level and are not carried here.
+ */
+export type CustomBlockCapabilityConfig = {
+	source: BlockSourceDeclaration;
+	manifest: CustomBlockManifest;
+};
+
+/**
+ * A custom-block capability entry. Unlike other capabilities it has no runtime
+ * handler — it is a build-time/deploy-time declaration only, carried through
+ * the manifest so the server can build and bind the block on deploy.
+ */
+export type CustomBlockCapability = {
+	readonly _tag: "custom_block";
+	readonly key: string;
+	readonly config: CustomBlockCapabilityConfig;
+};
+
+/**
+ * Builds a custom-block capability entry from its authoring configuration. The
+ * author-declared `dataSources` schema is carried verbatim into the block
+ * {@link CustomBlockManifest}; no bindings are emitted.
+ */
+export function createCustomBlockCapability(
+	key: string,
+	config: CustomBlockConfiguration,
+): CustomBlockCapability {
+	const source: BlockSourceDeclaration =
+		config.type === "static"
+			? { type: "static", path: config.path }
+			: {
+					type: "project",
+					path: config.path,
+					...(config.command !== undefined ? { command: config.command } : {}),
+					...(config.output !== undefined ? { output: config.output } : {}),
+				};
+
+	return {
+		_tag: "custom_block",
+		key,
+		config: {
+			source,
+			manifest: {
+				version: config.version ?? 1,
+				dataSources: config.dataSources ?? {},
+			},
+		},
+	};
+}