@notionhq/workers 0.2.0 → 0.4.0

package/src/capabilities/tool.test.ts

@@ -222,6 +222,69 @@ describe("Worker.tool", () => {
 		expect(capability.config.schema).toBeDefined();
 	});
 
+	describe("hints", () => {
+		it("omits hints from config when not specified (existing tools unchanged)", () => {
+			const capability = createToolCapability<{ name: string }, string>(
+				"noHints",
+				{
+					title: "No Hints",
+					description: "A tool without hints",
+					schema: j.object({ name: j.string() }),
+					execute: ({ name }) => `Hello, ${name}`,
+				},
+			);
+
+			expect(capability.config.hints).toBeUndefined();
+		});
+
+		it("flows readOnlyHint=true through to config", () => {
+			const capability = createToolCapability<{ query: string }, string>(
+				"readOnly",
+				{
+					title: "Read Only",
+					description: "A read-only tool",
+					schema: j.object({ query: j.string() }),
+					hints: { readOnlyHint: true },
+					execute: ({ query }) => query,
+				},
+			);
+
+			expect(capability.config.hints).toEqual({ readOnlyHint: true });
+		});
+
+		it("flows readOnlyHint=false through to config", () => {
+			const capability = createToolCapability<{ pageId: string }, string>(
+				"writeTool",
+				{
+					title: "Write Tool",
+					description: "A write tool",
+					schema: j.object({ pageId: j.string() }),
+					hints: { readOnlyHint: false },
+					execute: ({ pageId }) => pageId,
+				},
+			);
+
+			expect(capability.config.hints).toEqual({ readOnlyHint: false });
+		});
+
+		it("does not affect execution behavior", async () => {
+			const capability = createToolCapability<{ x: number }, number>(
+				"doubleReadOnly",
+				{
+					title: "Double",
+					description: "Doubles a number",
+					schema: j.object({ x: j.number() }),
+					hints: { readOnlyHint: true },
+					execute: ({ x }) => x * 2,
+				},
+			);
+
+			const result = await capability.handler({ x: 7 });
+
+			expect(result).toEqual({ _tag: "success", value: 14 });
+		});
+	});
+
 	it("invalid output with custom output schema", async () => {
 		const capability = createToolCapability<
 			{ value: number },

package/src/capabilities/tool.ts

@@ -6,6 +6,7 @@ import { getSchema } from "../schema-builder.js";
 import type { HandlerOptions, JSONValue } from "../types.js";
 import type { CapabilityContext } from "./context.js";
 import { createCapabilityContext } from "./context.js";
+import { writeOutput } from "./output.js";
 
 /**
  * Validates that every object schema in the tree has all its `properties`
@@ -69,6 +70,26 @@ function validateRequiredProperties(
 	}
 }
 
+/**
+ * Hints describing a tool's behavior. Advisory metadata read by the platform
+ * (not the model) to decide whether a call is safe to auto-execute or
+ * requires user confirmation.
+ *
+ * Field names mirror the MCP tool annotation shape
+ * (`McpServerToolAnnotations`) so worker tools flow through the same
+ * confirmation / auto-execute machinery as MCP tools.
+ *
+ * Only hints with active consumers in the Notion client are included.
+ */
+export interface ToolHints {
+	/**
+	 * The tool only reads state and has no side effects. Safe to call
+	 * repeatedly; safe to auto-execute under default policy. Tools without
+	 * this hint are treated as write tools and prompt for confirmation.
+	 */
+	readOnlyHint?: boolean;
+}
+
 export interface ToolConfiguration<
 	I extends JSONValue,
 	O extends JSONValue = JSONValue,
@@ -77,6 +98,7 @@ export interface ToolConfiguration<
 	description: string;
 	schema: SchemaBuilder<I>;
 	outputSchema?: SchemaBuilder<O>;
+	hints?: ToolHints;
 	execute: (input: I, context: CapabilityContext) => O | Promise<O>;
 }
 
@@ -211,15 +233,13 @@ export function createToolCapability<
 				error: { name: error.name, message: error.message, trace: error.stack },
 			};
 
-			process.stdout.write(
-				`\n<__notion_output__>${JSON.stringify(result)}</__notion_output__>\n`,
-			);
+			writeOutput(result);
 
 			return result;
 		}
 
 		try {
-			const capabilityContext = createCapabilityContext();
+			const capabilityContext = createCapabilityContext("tool");
 			const result = await config.execute(input, capabilityContext);
 			if (validateOutput && !validateOutput(result)) {
 				const error = new InvalidToolOutputError(
@@ -239,9 +259,7 @@ export function createToolCapability<
 					},
 				};
 
-				process.stdout.write(
-					`\n<__notion_output__>${JSON.stringify(result)}</__notion_output__>\n`,
-				);
+				writeOutput(result);
 
 				return result;
 			}
@@ -250,9 +268,7 @@ export function createToolCapability<
 				return result;
 			}
 
-			process.stdout.write(
-				`\n<__notion_output__>${JSON.stringify({ _tag: "success", value: result })}</__notion_output__>\n`,
-			);
+			writeOutput({ _tag: "success", value: result });
 
 			return {
 				_tag: "success" as const,
@@ -272,9 +288,7 @@ export function createToolCapability<
 				error: { name: error.name, message: error.message, trace: error.stack },
 			};
 
-			process.stdout.write(
-				`\n<__notion_output__>${JSON.stringify(result)}</__notion_output__>\n`,
-			);
+			writeOutput(result);
 
 			return result;
 		}
@@ -288,6 +302,7 @@ export function createToolCapability<
 			description: config.description,
 			schema: inputSchema,
 			outputSchema: outputSchema,
+			hints: config.hints,
 		},
 		handler,
 	};

package/src/capabilities/webhook.ts

@@ -0,0 +1,148 @@
+import { ExecutionError } from "../error.js";
+import type { HandlerOptions } from "../types.js";
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+import { writeOutput } from "./output.js";
+
+/**
+ * A single incoming webhook request.
+ */
+export interface WebhookEvent {
+	/**
+	 * Unique ID for this webhook delivery, stable across retries.
+	 * Best-effort idempotency key — prefer using the webhook provider's
+	 * own delivery/event ID when available, since providers may redeliver
+	 * the same event with a new deliveryId.
+	 */
+	deliveryId: string;
+	/**
+	 * The parsed JSON body of the incoming request, or an empty object if
+	 * the body is not valid JSON.
+	 */
+	body: Record<string, unknown>;
+	/**
+	 * The raw request body as a string, useful for signature verification.
+	 */
+	rawBody: string;
+	/**
+	 * The HTTP headers from the incoming request
+	 */
+	headers: Record<string, string>;
+	/**
+	 * The HTTP method of the incoming request (e.g. "POST")
+	 */
+	method: string;
+}
+
+/**
+ * Throw this error from your webhook execute handler to signal that
+ * signature verification failed. After 5 consecutive verification
+ * failures, the platform will short-circuit and reject all incoming
+ * requests for this webhook without executing the handler.
+ *
+ * @example
+ * ```ts
+ * worker.webhook("onGithubPush", {
+ *   title: "GitHub Push",
+ *   description: "Handles GitHub push events",
+ *   execute: async (events) => {
+ *     const secret = process.env.GITHUB_WEBHOOK_SECRET;
+ *     if (!secret) {
+ *       throw new WebhookVerificationError("GITHUB_WEBHOOK_SECRET not set");
+ *     }
+ *     for (const event of events) {
+ *       if (!verifyGitHubSignature(event.rawBody, event.headers, secret)) {
+ *         throw new WebhookVerificationError("Invalid GitHub signature");
+ *       }
+ *       // ... handle verified event
+ *     }
+ *   },
+ * });
+ * ```
+ */
+export class WebhookVerificationError extends ExecutionError {
+	constructor(cause?: unknown) {
+		super(cause ?? "Webhook signature verification failed");
+		this.name = "WebhookVerificationError";
+	}
+}
+
+/**
+ * Configuration for a webhook capability
+ */
+export interface WebhookConfiguration {
+	/**
+	 * Title of the webhook - shown in the UI when viewing webhooks
+	 */
+	title: string;
+
+	/**
+	 * Description of what this webhook does - shown in the UI
+	 */
+	description: string;
+
+	/**
+	 * The function that executes when the webhook is triggered.
+	 * Receives an array of events (currently always a single event,
+	 * but may be batched in the future).
+	 *
+	 * To signal a verification failure, throw a `WebhookVerificationError`.
+	 * After 5 consecutive verification failures, the platform will
+	 * short-circuit and stop executing the handler.
+	 *
+	 * @param events - The incoming webhook events
+	 * @param context - The capability execution context (Notion client, etc.)
+	 * @returns A promise that resolves when the webhook processing completes
+	 */
+	execute: (
+		events: WebhookEvent[],
+		context: CapabilityContext,
+	) => Promise<void> | void;
+}
+
+export type WebhookCapability = ReturnType<typeof createWebhookCapability>;
+
+export function createWebhookCapability(
+	key: string,
+	config: WebhookConfiguration,
+) {
+	return {
+		_tag: "webhook" as const,
+		key,
+		config: {
+			title: config.title,
+			description: config.description,
+		},
+		async handler(
+			events: WebhookEvent[],
+			options?: HandlerOptions,
+		): Promise<{ status: "success" } | undefined> {
+			try {
+				const capabilityContext = createCapabilityContext("webhook");
+				await config.execute(events, capabilityContext);
+
+				if (options?.concreteOutput) {
+					return { status: "success" };
+				} else {
+					writeOutput({ _tag: "success", value: { status: "success" } });
+				}
+			} catch (err) {
+				const error =
+					err instanceof ExecutionError ? err : new ExecutionError(err);
+
+				if (!options?.concreteOutput) {
+					writeOutput({
+						_tag: "error",
+						error: {
+							name: error.name,
+							message: error.message,
+							trace: error.stack,
+						},
+					});
+				}
+
+				throw error;
+			}
+		},
+	};
+}

package/src/error.ts

@@ -11,6 +11,46 @@ export class ExecutionError extends Error {
 	}
 }
 
+/**
+ * Throw this error from your sync execute handler to signal that the
+ * external API returned a rate-limit response (e.g. HTTP 429).
+ *
+ * When the platform receives this error it applies exponential backoff
+ * instead of retrying immediately. If `retryAfter` is provided, the
+ * platform will wait at least that many seconds before the next attempt.
+ *
+ * @example
+ * ```ts
+ * worker.sync("issues", {
+ *   database: issuesDb,
+ *   execute: async (state, ctx) => {
+ *     const res = await fetch("https://api.example.com/issues");
+ *     if (res.status === 429) {
+ *       const retryAfter = Number(res.headers.get("Retry-After"));
+ *       throw new RateLimitError({
+ *         retryAfter: Number.isFinite(retryAfter) ? retryAfter : undefined,
+ *       });
+ *     }
+ *     // ...
+ *   },
+ * });
+ * ```
+ */
+export class RateLimitError extends ExecutionError {
+	/**
+	 * Optional number of seconds the external API asked us to wait
+	 * before retrying. The platform takes the max of this value and its
+	 * own exponential-backoff delay.
+	 */
+	readonly retryAfter: number | undefined;
+
+	constructor(options?: { retryAfter?: number }) {
+		super("Rate limited by external API");
+		this.name = "RateLimitError";
+		this.retryAfter = options?.retryAfter;
+	}
+}
+
 /**
  * Helper for exhaustive switch statements. TypeScript will error if a case is not handled.
  */

package/src/index.ts

@@ -1,4 +1,20 @@
 export { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
+export type {
+	AiConnectorArchetype,
+	AiConnectorCapability,
+	AiConnectorChange,
+	AiConnectorChangeUpsert,
+	AiConnectorChatAuthor,
+	AiConnectorChatChannel,
+	AiConnectorChatMessage,
+	AiConnectorChatRecord,
+	AiConnectorConfiguration,
+	AiConnectorExecutionResult,
+	AiConnectorMode,
+	AiConnectorProjectBlock,
+	AiConnectorProjectRecord,
+	AiConnectorRecordByArchetype,
+} from "./capabilities/ai_connector.js";
 export type {
 	AutomationCapability,
 	AutomationConfiguration,
@@ -21,7 +37,18 @@ export type {
 	SyncExecutionResult,
 	SyncMode,
 } from "./capabilities/sync.js";
-export type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
+export type {
+	ToolCapability,
+	ToolConfiguration,
+	ToolHints,
+} from "./capabilities/tool.js";
+export type {
+	WebhookCapability,
+	WebhookConfiguration,
+	WebhookEvent,
+} from "./capabilities/webhook.js";
+export { WebhookVerificationError } from "./capabilities/webhook.js";
+export { RateLimitError } from "./error.js";
 export type { AnyJSONSchema, JSONSchema } from "./json-schema.js";
 export type { Infer, SchemaBuilder } from "./schema-builder.js";
 export { getSchema, j } from "./schema-builder.js";

package/src/pacer_internal.ts

@@ -14,6 +14,11 @@ export type PacerState = {
 	pacers: Record<string, PacerEntry>;
 };
 
+export type PacerDeclaration = {
+	readonly key: string;
+	readonly config: { allowedRequests: number; intervalMs: number };
+};
+
 let pacerState: PacerState = { pacers: {} };
 
 export function setPacerState(state: PacerState): void {
@@ -24,6 +29,35 @@ export function getPacerState(): PacerState {
 	return pacerState;
 }
 
+/**
+ * Initialize pacer state from runtime context, falling back to the worker's
+ * own declarations for local execution.
+ * @internal
+ */
+export function initPacerState(
+	runtimePacers: Record<string, PacerEntry> | undefined,
+	declarations?: readonly PacerDeclaration[],
+): void {
+	const pacers = runtimePacers ?? {};
+	if (
+		Object.keys(pacers).length === 0 &&
+		declarations &&
+		declarations.length > 0
+	) {
+		const localPacers: Record<string, PacerEntry> = {};
+		for (const decl of declarations) {
+			localPacers[decl.key] = {
+				lastScheduledAtMs: 0,
+				allowedRequests: decl.config.allowedRequests,
+				intervalMs: decl.config.intervalMs,
+			};
+		}
+		setPacerState({ pacers: localPacers });
+	} else {
+		setPacerState({ pacers });
+	}
+}
+
 /**
  * Core wait logic for pacing API requests.
  * Sleeps if needed to stay under the rate limit.

package/src/schema.ts

@@ -68,10 +68,10 @@ export type PropertyConfiguration =
 	| {
 			type: "relation";
 			/**
-			 * The export name of the sync capability that defines the related database.
-			 * This must match the export name used when defining the related sync capability.
+			 * The key of the related database declaration.
+			 * This must match the key passed to `worker.database()`.
 			 */
-			relatedSyncKey: string;
+			relatedDatabaseKey: string;
 			config: { twoWay: false } | { twoWay: true; relatedPropertyName: string };
 	  };
 
@@ -203,32 +203,49 @@ export function place(): PropertyConfiguration {
 }
 
 /**
- * Creates a relation property definition that references another sync capability.
- * The related database must be defined by a sync capability in the same worker.
+ * Creates a relation property definition that references another database.
+ * The related database must be declared in the same worker.
  *
- * @param relatedSyncKey - The export name of the sync capability that defines the related database.
+ * @param relatedDatabaseKey - The key of the related database declaration.
  * @example
  * ```typescript
- * export const projectsSync = sync({...});
+ * const projects = worker.database("projects", {
+ *   type: "managed",
+ *   initialTitle: "Projects",
+ *   primaryKeyProperty: "Project ID",
+ *   schema: {
+ *     properties: {
+ *       "Project Name": Schema.title(),
+ *       "Project ID": Schema.richText(),
+ *     },
+ *   },
+ * });
  *
- * export const tasksSync = sync({
+ * const tasks = worker.database("tasks", {
+ *   type: "managed",
+ *   initialTitle: "Tasks",
+ *   primaryKeyProperty: "Task ID",
  *   schema: {
  *     properties: {
  *       "Task Title": Schema.title(),
- *       "Project": Schema.relation("projectsSync"),
+ *       "Project": Schema.relation("projects"),
  *     },
  *   },
- *   ...
+ * });
+ *
+ * export const tasksSync = worker.sync("tasksSync", {
+ *   database: tasks,
+ *   execute: async () => ({ changes: [], hasMore: false }),
  * });
  * ```
  */
 export function relation(
-	relatedSyncKey: string,
+	relatedDatabaseKey: string,
 	config?: { twoWay: false } | { twoWay: true; relatedPropertyName: string },
 ): PropertyConfiguration {
 	return {
 		type: "relation",
-		relatedSyncKey,
+		relatedDatabaseKey,
 		config: config ?? { twoWay: false },
 	};
 }