@notionhq/workers 0.4.0 → 0.6.0

package/src/builder.ts

@@ -1,5 +1,6 @@
 import type { NoticonName } from "./icon-names.js";
 import type {
+	Cover,
 	DateValue,
 	Icon,
 	NoticonColor,
@@ -233,9 +234,7 @@ export function relation(primaryKey: string): RelationReference {
  */
 function validateDateString(dateString: string): void {
 	if (!/^\d{4}-\d{2}-\d{2}$/.test(dateString)) {
-		throw new Error(
-			`Invalid date format: ${dateString}. Expected YYYY-MM-DD format.`,
-		);
+		throw new Error(`Invalid date format: ${dateString}. Expected YYYY-MM-DD format.`);
 	}
 
 	const date = new Date(dateString);
@@ -289,10 +288,7 @@ export function emojiIcon(emoji: string): Icon {
  * @param icon - The name of the Notion icon (e.g., "checkmark", "pizza", "rocket")
  * @param color - The color variant (defaults to "gray")
  */
-export function notionIcon(
-	icon: NoticonName,
-	color: NoticonColor = "gray",
-): Icon {
+export function notionIcon(icon: NoticonName, color: NoticonColor = "gray"): Icon {
 	return {
 		type: "notion",
 		icon,
@@ -310,3 +306,20 @@ export function imageIcon(url: string): Icon {
 		url,
 	};
 }
+
+/**
+ * Creates an image cover from an external URL.
+ * @param url - The URL of the image (e.g., "https://example.com/cover.png")
+ * @param position - Vertical image position, from 0 (top) to 1 (bottom). Defaults to 0.5.
+ */
+export function imageCover(url: string, position = 0.5): Cover {
+	if (!Number.isFinite(position) || position < 0 || position > 1) {
+		throw new Error(`Invalid cover position: ${position}. Expected a number between 0 and 1.`);
+	}
+
+	return {
+		type: "image",
+		url,
+		position,
+	};
+}

package/src/capabilities/ai_connector.test.ts

@@ -1,12 +1,5 @@
-import {
-	afterEach,
-	beforeEach,
-	describe,
-	expect,
-	it,
-	type Mock,
-	vi,
-} from "vitest";
+import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from "vitest";
+
 import { ExecutionError } from "../error.js";
 import { getPacerState } from "../pacer_internal.js";
 import { Worker } from "../worker.js";
@@ -17,9 +10,7 @@ describe("Worker.aiConnector", () => {
 	let stdoutSpy: Mock<typeof process.stdout.write>;
 
 	beforeEach(() => {
-		stdoutSpy = vi
-			.spyOn(process.stdout, "write")
-			.mockImplementation(() => true);
+		stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 	});
 
 	afterEach(() => {
@@ -86,12 +77,8 @@ describe("Worker.aiConnector", () => {
 
 		await capability.handler();
 
-		expect(stdoutSpy).toHaveBeenCalledWith(
-			expect.stringContaining(`"_tag":"success"`),
-		);
-		expect(stdoutSpy).toHaveBeenCalledWith(
-			expect.stringContaining(`"thread-1"`),
-		);
+		expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining(`"_tag":"success"`));
+		expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining(`"thread-1"`));
 	});
 
 	it("passes state through from legacy runtime userContext", async () => {
@@ -106,15 +93,9 @@ describe("Worker.aiConnector", () => {
 			execute,
 		});
 
-		await capability.handler(
-			{ userContext: { cursor: "cursor-1" } },
-			{ concreteOutput: true },
-		);
+		await capability.handler({ userContext: { cursor: "cursor-1" } }, { concreteOutput: true });
 
-		expect(execute).toHaveBeenCalledWith(
-			{ cursor: "cursor-1" },
-			expect.anything(),
-		);
+		expect(execute).toHaveBeenCalledWith({ cursor: "cursor-1" }, expect.anything());
 		expect(stdoutSpy).not.toHaveBeenCalled();
 	});
 
@@ -161,9 +142,7 @@ describe("Worker.aiConnector", () => {
 				},
 			},
 		});
-		expect(
-			result.nextPacerStates.api?.lastScheduledAtMs,
-		).toBeGreaterThanOrEqual(before);
+		expect(result.nextPacerStates.api?.lastScheduledAtMs).toBeGreaterThanOrEqual(before);
 	});
 
 	describe("pacer local fallback", () => {
@@ -243,9 +222,7 @@ describe("Worker.aiConnector", () => {
 		});
 
 		await expect(capability.handler()).rejects.toThrow(ExecutionError);
-		expect(stdoutSpy).toHaveBeenCalledWith(
-			expect.stringContaining(`"_tag":"error"`),
-		);
+		expect(stdoutSpy).toHaveBeenCalledWith(expect.stringContaining(`"_tag":"error"`));
 	});
 
 	it("accepts chat records at compile time", () => {

package/src/capabilities/ai_connector.ts

@@ -85,18 +85,14 @@ export type AiConnectorChangeUpsert<A extends AiConnectorArchetype> = {
 	record: AiConnectorRecordByArchetype[A];
 };
 
-export type AiConnectorChange<A extends AiConnectorArchetype> =
-	AiConnectorChangeUpsert<A>;
+export type AiConnectorChange<A extends AiConnectorArchetype> = AiConnectorChangeUpsert<A>;
 
 export type AiConnectorExecutionResult<
 	A extends AiConnectorArchetype,
 	State = unknown,
 > = StatefulExecutionResult<AiConnectorChange<A>, State>;
 
-export type AiConnectorConfiguration<
-	A extends AiConnectorArchetype,
-	State = unknown,
-> = {
+export type AiConnectorConfiguration<A extends AiConnectorArchetype, State = unknown> = {
 	/**
 	 * The Notion record ID of an existing custom connector in the target workspace.
 	 *
@@ -113,9 +109,7 @@ export type AiConnectorConfiguration<
 	) => Promise<AiConnectorExecutionResult<A, State>>;
 };
 
-export type AiConnectorCapability = ReturnType<
-	typeof createAiConnectorCapability
->;
+export type AiConnectorCapability = ReturnType<typeof createAiConnectorCapability>;
 
 type NormalizedAiConnectorConfiguration<A extends AiConnectorArchetype> = {
 	aiConnectorId: string;
@@ -131,10 +125,7 @@ type AiConnectorHandlerResult<A extends AiConnectorArchetype, State> = {
 	nextPacerStates: Record<string, PacerEntry>;
 };
 
-export function createAiConnectorCapability<
-	A extends AiConnectorArchetype,
-	State = unknown,
->(
+export function createAiConnectorCapability<A extends AiConnectorArchetype, State = unknown>(
 	key: string,
 	configuration: AiConnectorConfiguration<A, State>,
 	pacerDeclarations?: readonly PacerDeclaration[],
@@ -150,10 +141,7 @@ export function createAiConnectorCapability<
 				? {}
 				: { schedule: parseSchedule(configuration.schedule) }),
 		} satisfies NormalizedAiConnectorConfiguration<A>,
-		async handler(
-			runtimeContext?: StatefulRuntimeContext<State>,
-			options?: HandlerOptions,
-		) {
+		async handler(runtimeContext?: StatefulRuntimeContext<State>, options?: HandlerOptions) {
 			const capabilityContext = createCapabilityContext("ai_connector");
 			const state = runtimeContext?.state ?? runtimeContext?.userContext;
 

package/src/capabilities/automation.test.ts

@@ -1,12 +1,5 @@
-import {
-	afterEach,
-	beforeEach,
-	describe,
-	expect,
-	it,
-	type Mock,
-	vi,
-} from "vitest";
+import { afterEach, beforeEach, describe, expect, it, type Mock, vi } from "vitest";
+
 import { ExecutionError } from "../error.js";
 import type { PageObjectResponse } from "./automation.js";
 import { createAutomationCapability } from "./automation.js";
@@ -15,9 +8,7 @@ describe("createAutomationCapability", () => {
 	let stdoutSpy: Mock<typeof process.stdout.write>;
 
 	beforeEach(() => {
-		stdoutSpy = vi
-			.spyOn(process.stdout, "write")
-			.mockImplementation(() => true);
+		stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
 	});
 
 	afterEach(() => {

package/src/capabilities/automation.ts

@@ -64,10 +64,7 @@ export interface AutomationConfiguration {
 	 * @param context - The capability execution context (Notion client, etc.)
 	 * @returns A promise that resolves when the automation completes
 	 */
-	execute: (
-		event: AutomationEvent,
-		context: CapabilityContext,
-	) => Promise<void> | void;
+	execute: (event: AutomationEvent, context: CapabilityContext) => Promise<void> | void;
 }
 
 /**
@@ -78,9 +75,7 @@ export interface AutomationHandlerResult {
 	description: string;
 }
 
-export type AutomationCapability = ReturnType<
-	typeof createAutomationCapability
->;
+export type AutomationCapability = ReturnType<typeof createAutomationCapability>;
 
 /**
  * Creates an automation capability from configuration.
@@ -89,10 +84,7 @@ export type AutomationCapability = ReturnType<
  * @param config - The automation configuration.
  * @returns The capability object.
  */
-export function createAutomationCapability(
-	key: string,
-	config: AutomationConfiguration,
-) {
+export function createAutomationCapability(key: string, config: AutomationConfiguration) {
 	return {
 		_tag: "automation" as const,
 		key,

package/src/capabilities/context.ts

@@ -1,5 +1,6 @@
 import { Client } from "@notionhq/client";
 import type { ClientOptions } from "@notionhq/client/build/src/Client.js";
+
 import type { CapabilityType } from "../worker.js";
 
 export type CapabilityContext = {
@@ -9,8 +10,8 @@ export type CapabilityContext = {
 
 const FIX_STEPS =
 	"\n\nTo fix this:\n" +
-	"1. Create an internal integration at https://www.notion.so/profile/integrations/internal\n" +
-	"2. Give the integration access to the relevant pages/databases\n" +
+	"1. Create a connection at https://app.notion.com/developers/connections\n" +
+	"2. Give the connection access to the relevant pages/databases\n" +
 	"3. Add NOTION_API_TOKEN=<your-token> to your .env file\n" +
 	"4. For deployed workers, run: ntn workers env push";
 
@@ -32,9 +33,7 @@ function missingTokenMessage(capabilityType: CapabilityType): string {
 	);
 }
 
-function createUnauthenticatedNotionProxy(
-	capabilityType: CapabilityType,
-): Client {
+function createUnauthenticatedNotionProxy(capabilityType: CapabilityType): Client {
 	return new Proxy({} as Client, {
 		get(_target, prop) {
 			if (prop === "then" || typeof prop === "symbol") {
@@ -45,9 +44,7 @@ function createUnauthenticatedNotionProxy(
 	});
 }
 
-export function createCapabilityContext(
-	capabilityType: CapabilityType,
-): CapabilityContext {
+export function createCapabilityContext(capabilityType: CapabilityType): CapabilityContext {
 	const options: ClientOptions = {};
 
 	if (process.env.NOTION_API_BASE_URL) {

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 ?? {},
+			},
+		},
+	};
+}

package/src/capabilities/oauth.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, describe, expect, it } from "vitest";
+
 import { createOAuthCapability } from "./oauth.js";
 
 describe("oauth", () => {

package/src/capabilities/oauth.ts

@@ -84,9 +84,7 @@ export interface UserManagedOAuthConfiguration {
 /**
  * Union type representing either Notion-managed or user-managed OAuth configuration.
  */
-export type OAuthConfiguration =
-	| NotionManagedOAuthConfiguration
-	| UserManagedOAuthConfiguration;
+export type OAuthConfiguration = NotionManagedOAuthConfiguration | UserManagedOAuthConfiguration;
 
 export type OAuthCapability = ReturnType<typeof createOAuthCapability>;
 

package/src/capabilities/output.ts

@@ -2,7 +2,5 @@
  * Writes a notion_output envelope to stdout using the shared wire format.
  */
 export function writeOutput(value: unknown): void {
-	process.stdout.write(
-		`\n<__notion_output__>${JSON.stringify(value)}</__notion_output__>\n`,
-	);
+	process.stdout.write(`\n<__notion_output__>${JSON.stringify(value)}</__notion_output__>\n`);
 }

package/src/capabilities/stateful-capability.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+
 import { parseSchedule } from "./stateful-capability.js";
 
 describe("stateful capability shared primitives", () => {

package/src/capabilities/stateful-capability.ts

@@ -48,7 +48,7 @@ export function parseSchedule(schedule: Schedule): SyncSchedule {
 	}
 
 	const match = schedule.match(/^(\d+)(m|h|d)$/);
-	if (!match || !match[1] || !match[2]) {
+	if (!match?.[1] || !match[2]) {
 		throw new Error(
 			`Invalid schedule format: "${schedule}". Use "continuous" or an interval like "30m", "1h", "1d".`,
 		);
@@ -73,14 +73,10 @@ export function parseSchedule(schedule: Schedule): SyncSchedule {
 	}
 
 	if (intervalMs < MIN_INTERVAL_MS) {
-		throw new Error(
-			`Schedule interval must be at least 1 minute. Got: "${schedule}"`,
-		);
+		throw new Error(`Schedule interval must be at least 1 minute. Got: "${schedule}"`);
 	}
 	if (intervalMs > MAX_INTERVAL_MS) {
-		throw new Error(
-			`Schedule interval must be at most 7 days. Got: "${schedule}"`,
-		);
+		throw new Error(`Schedule interval must be at most 7 days. Got: "${schedule}"`);
 	}
 
 	return { type: "interval", intervalMs };