@notionhq/workers 0.1.0 → 0.3.0

package/dist/worker.d.ts

@@ -1,14 +1,142 @@
+import type { AiConnectorArchetype, AiConnectorCapability, AiConnectorConfiguration } from "./capabilities/ai_connector.js";
 import type { AutomationCapability, AutomationConfiguration, AutomationEvent } from "./capabilities/automation.js";
 import type { CapabilityContext } from "./capabilities/context.js";
 import type { NotionManagedOAuthConfiguration, OAuthCapability, OAuthConfiguration, UserManagedOAuthConfiguration } from "./capabilities/oauth.js";
 import type { SyncCapability, SyncConfiguration } from "./capabilities/sync.js";
 import type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
+import type { WebhookCapability, WebhookConfiguration, WebhookEvent } from "./capabilities/webhook.js";
+import { WebhookVerificationError } from "./capabilities/webhook.js";
+import type { PacerDeclaration } from "./pacer_internal.js";
 import type { Schema } from "./schema.js";
 import type { HandlerOptions, JSONValue } from "./types.js";
-export type { AutomationConfiguration, AutomationEvent, CapabilityContext, OAuthConfiguration, NotionManagedOAuthConfiguration, UserManagedOAuthConfiguration, SyncConfiguration, ToolConfiguration, };
-type Capability = SyncCapability | ToolCapability<any, any> | AutomationCapability | OAuthCapability;
+export type { AutomationConfiguration, AutomationEvent, AiConnectorConfiguration, CapabilityContext, OAuthConfiguration, NotionManagedOAuthConfiguration, UserManagedOAuthConfiguration, SyncConfiguration, ToolConfiguration, WebhookConfiguration, WebhookEvent, };
+export { WebhookVerificationError };
+type Capability = SyncCapability | AiConnectorCapability | ToolCapability<any, any> | AutomationCapability | OAuthCapability | WebhookCapability;
+/**
+ * Configuration for a database that Notion creates and manages on behalf
+ * of the worker. The database is created on first deploy and its schema
+ * is migrated on subsequent deploys.
+ */
+export type ManagedDatabaseConfig<PK extends string, S extends Schema<PK>> = {
+    type: "managed";
+    /**
+     * The title for the database when it is first created in Notion.
+     *
+     * Updating this after the database has been created will not change the
+     * title of the database — users may rename it freely.
+     */
+    initialTitle: string;
+    /**
+     * The property that serves as the primary key for matching records.
+     * Must be a property defined in the schema. The value of this property
+     * should match the `key` field on each sync change.
+     */
+    primaryKeyProperty: PK;
+    /**
+     * The database schema. Notion will migrate the database to match
+     * the given schema on worker deploy.
+     */
+    schema: S;
+};
+/**
+ * Configuration union for all database types.
+ * Currently only `"managed"` is supported.
+ */
+export type DatabaseConfig<PK extends string, S extends Schema<PK>> = ManagedDatabaseConfig<PK, S>;
+/**
+ * An opaque handle returned by `worker.database()`. Pass this to
+ * `worker.sync()` to associate a sync capability with the database.
+ */
+export type DatabaseHandle<PK extends string, S extends Schema<PK>> = {
+    readonly key: string;
+    readonly config: DatabaseConfig<PK, S>;
+};
+/** Internal type-erased alias for storing heterogeneous databases. */
+type RegisteredDatabase = DatabaseHandle<string, Schema<string>>;
+/**
+ * Configuration for a pacer that rate-limits requests to an external API.
+ * If multiple syncs share a pacer, the server apportions the budget evenly.
+ */
+export type PacerConfig = {
+    /** Maximum number of requests allowed per interval. */
+    allowedRequests: number;
+    /** The interval window in milliseconds. */
+    intervalMs: number;
+};
+/**
+ * An opaque handle returned by `worker.pacer()`. Call `handle.wait()`
+ * before each API request to stay under the rate limit.
+ */
+export type PacerHandle = {
+    readonly key: string;
+    readonly config: PacerConfig;
+    /**
+     * Wait until a request can proceed under this pacer's rate limit.
+     *
+     * Call this before **every** API request inside your sync's `execute` function.
+     * The pacer ensures requests are evenly spaced over the interval window.
+     *
+     * @example
+     * ```ts
+     * const apiPacer = worker.pacer("myApi", { allowedRequests: 10, intervalMs: 1000 });
+     *
+     * worker.sync("mySync", {
+     *   database: myDb,
+     *   execute: async () => {
+     *     await apiPacer.wait();
+     *     const data = await fetchFromApi();
+     *     // ...
+     *   },
+     * });
+     * ```
+     */
+    wait(): Promise<void>;
+};
+export type { PacerDeclaration };
+/** A capability entry stripped of its handler, used in the manifest. */
+type CapabilityManifestEntry = Pick<Capability, "_tag" | "key" | "config">;
+/**
+ * The full worker manifest, read by the server at deploy time to discover
+ * databases, pacers, capabilities, and the SDK version.
+ */
+export type WorkerManifest = {
+    readonly sdkVersion: string;
+    readonly databases: readonly RegisteredDatabase[];
+    readonly pacers: readonly PacerDeclaration[];
+    readonly capabilities: readonly CapabilityManifestEntry[];
+};
 export declare class Worker {
     #private;
+    database<PK extends string, S extends Schema<PK>>(key: string, config: DatabaseConfig<PK, S>): DatabaseHandle<PK, S>;
+    /**
+     * Register a pacer for rate-limiting requests to an external API.
+     *
+     * Multiple syncs can share a pacer — the server will apportion the
+     * budget evenly across all syncs that reference it.
+     *
+     * Example:
+     *
+     * ```ts
+     * const jiraPacer = worker.pacer("jira", {
+     *   allowedRequests: 10,
+     *   intervalMs: 1000,
+     * });
+     *
+     * worker.sync("jiraSync", {
+     *   database: tasks,
+     *   execute: async (state, { notion }) => {
+     *     await jiraPacer.wait();
+     *     const data = await fetchFromJira();
+     *     // ...
+     *   },
+     * });
+     * ```
+     *
+     * @param key - The unique key for this pacer.
+     * @param config - The rate limit configuration.
+     * @returns A pacer handle. Call `handle.wait()` before each API request.
+     */
+    pacer(key: string, config: PacerConfig): PacerHandle;
     /**
      * Register a sync capability.
      *
@@ -22,26 +150,29 @@ export declare class Worker {
      * const worker = new Worker();
      * export default worker;
      *
-     * worker.sync("tasksSync", {
-     *   primaryKeyProperty: "Task ID",
+     * const tasks = worker.database("tasks", {
+     *   type: "managed",
+     *   initialTitle: "Tasks",
      *   schema: {
-     *     defaultName: "Tasks",
      *     properties: {
      *       "Task Name": Schema.title(),
-     *       "Task ID": Schema.richText(),
      *       Status: Schema.select([
      *         { name: "Open", color: "default" },
      *         { name: "Done", color: "green" },
      *       ]),
      *     },
      *   },
+     * });
+     *
+     * worker.sync("tasksSync", {
+     *   database: tasks,
      *   execute: async () => {
      *     const changes = [
      *       {
      *         key: "task-1",
+     *         type: "upsert",
      *         properties: {
      *           "Task Name": Builder.title("Write docs"),
-     *           "Task ID": Builder.richText("task-1"),
      *           Status: Builder.select("Open"),
      *         },
      *       },
@@ -57,6 +188,60 @@ export declare class Worker {
      * @returns The capability object.
      */
     sync<PK extends string, S extends Schema<PK>, Context = unknown>(key: string, config: SyncConfiguration<PK, S, Context>): SyncCapability;
+    /**
+     * Register an AI connector capability.
+     *
+     * Example:
+     *
+     * ```ts
+     * const worker = new Worker();
+     * export default worker;
+     *
+     * worker.aiConnector("supportChats", {
+     *   aiConnectorId: "connector-record-id",
+     *   archetype: "chat",
+     *   mode: "incremental",
+     *   schedule: "15m",
+     *   execute: async (state) => ({
+     *     changes: [
+     *       {
+     *         type: "upsert",
+     *         key: "thread-1",
+     *         record: {
+     *           createdAt: "2026-01-01T00:00:00Z",
+     *           updatedAt: "2026-01-01T00:00:00Z",
+     *           channel: {
+     *             id: "channel-1",
+     *             name: "Support",
+     *           },
+     *           threadId: "thread-1",
+     *           messages: [
+     *             {
+     *               id: "message-1",
+     *               content: "Hello from support",
+     *               timestamp: "2026-01-01T00:00:00Z",
+     *               author: {
+     *                 id: "user-1",
+     *                 username: "alice",
+     *               },
+     *             },
+     *           ],
+     *         },
+     *       },
+     *     ],
+     *     hasMore: false,
+     *   }),
+     * });
+     * ```
+     *
+     * `aiConnectorId` must be the Notion record ID of an existing custom
+     * connector in the workspace where you deploy this worker.
+     *
+     * @param key - The unique key for this capability.
+     * @param config - The AI connector configuration.
+     * @returns The capability object.
+     */
+    aiConnector<A extends AiConnectorArchetype, Context = unknown>(key: string, config: AiConnectorConfiguration<A, Context>): AiConnectorCapability;
     /**
      * Register a tool capability.
      *
@@ -113,6 +298,35 @@ export declare class Worker {
      * @returns The capability object.
      */
     automation(key: string, config: AutomationConfiguration): AutomationCapability;
+    /**
+     * Register a webhook capability.
+     *
+     * Webhooks expose an HTTP endpoint that external services can call.
+     * When hit, the request is processed by the worker's execute function.
+     *
+     * Example:
+     *
+     * ```ts
+     * const worker = new Worker();
+     * export default worker;
+     *
+     * worker.webhook("onGithubPush", {
+     *   title: "GitHub Push Webhook",
+     *   description: "Handles push events from GitHub",
+     *   execute: async (events, { notion }) => {
+     *    for (const event of events) {
+     *      console.log("Received webhook:", event.body);
+     *      console.log("Headers:", event.headers);
+     *    }
+     *   },
+     * })
+     * ```
+     *
+     * @param key - The unique key for this capability. Used as the webhook name in the URL.
+     * @param config - The webhook configuration.
+     * @returns The capability object.
+     */
+    webhook(key: string, config: WebhookConfiguration): WebhookCapability;
     /**
      * Register an OAuth capability.
      *
@@ -159,6 +373,7 @@ export declare class Worker {
      * Get all registered capabilities (for discovery) without their handlers.
      */
     get capabilities(): Pick<Capability, "_tag" | "key" | "config">[];
+    get manifest(): WorkerManifest;
     /**
      * Execute a capability by key.
      *

package/dist/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,EACf,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EACX,+BAA+B,EAC/B,eAAe,EACf,kBAAkB,EAClB,6BAA6B,EAC7B,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5D,YAAY,EACX,uBAAuB,EACvB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,+BAA+B,EAC/B,6BAA6B,EAC7B,iBAAiB,EACjB,iBAAiB,GACjB,CAAC;AAMF,KAAK,UAAU,GACZ,cAAc,GAEd,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,GACxB,oBAAoB,GACpB,eAAe,CAAC;AAMnB,qBAAa,MAAM;;IAGlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,EAC9D,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC,GACvC,cAAc;IAOjB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,IAAI,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,SAAS,SAAS,GAAG,SAAS,EACxD,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;IAQvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,UAAU,CACT,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,uBAAuB,GAC7B,oBAAoB;IAOvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwCG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,eAAe;IAO/D;;OAEG;IACH,IAAI,YAAY,IAAI,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC,EAAE,CAMhE;IAED;;;;;;;OAOG;IACG,GAAG,CACR,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,cAAmB,GAC1B,OAAO,CAAC,OAAO,CAAC;CAyBnB"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}

package/dist/worker.js

@@ -1,9 +1,69 @@
+import { createAiConnectorCapability } from "./capabilities/ai_connector.js";
 import { createAutomationCapability } from "./capabilities/automation.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 { pacerWait } from "./pacer_internal.js";
+import { createRequire } from "node:module";
+const SDK_VERSION = (() => {
+  const require2 = createRequire(import.meta.url);
+  const packageJson = require2("../package.json");
+  if (typeof packageJson !== "object" || packageJson === null || !("version" in packageJson) || typeof packageJson.version !== "string") {
+    throw new Error("Failed to read SDK version from package.json");
+  }
+  return packageJson.version;
+})();
 class Worker {
   #capabilities = /* @__PURE__ */ new Map();
+  #databases = /* @__PURE__ */ new Map();
+  #pacers = /* @__PURE__ */ new Map();
+  database(key, config) {
+    this.#validateUniqueKey(key);
+    const database = { key, config };
+    this.#databases.set(key, { key, config });
+    return database;
+  }
+  /**
+   * Register a pacer for rate-limiting requests to an external API.
+   *
+   * Multiple syncs can share a pacer — the server will apportion the
+   * budget evenly across all syncs that reference it.
+   *
+   * Example:
+   *
+   * ```ts
+   * const jiraPacer = worker.pacer("jira", {
+   *   allowedRequests: 10,
+   *   intervalMs: 1000,
+   * });
+   *
+   * worker.sync("jiraSync", {
+   *   database: tasks,
+   *   execute: async (state, { notion }) => {
+   *     await jiraPacer.wait();
+   *     const data = await fetchFromJira();
+   *     // ...
+   *   },
+   * });
+   * ```
+   *
+   * @param key - The unique key for this pacer.
+   * @param config - The rate limit configuration.
+   * @returns A pacer handle. Call `handle.wait()` before each API request.
+   */
+  pacer(key, config) {
+    this.#validateUniqueKey(key);
+    this.#pacers.set(key, { key, config });
+    return {
+      key,
+      config,
+      wait: () => pacerWait(key)
+    };
+  }
   /**
    * Register a sync capability.
    *
@@ -17,26 +77,29 @@ class Worker {
    * const worker = new Worker();
    * export default worker;
    *
-   * worker.sync("tasksSync", {
-   *   primaryKeyProperty: "Task ID",
+   * const tasks = worker.database("tasks", {
+   *   type: "managed",
+   *   initialTitle: "Tasks",
    *   schema: {
-   *     defaultName: "Tasks",
    *     properties: {
    *       "Task Name": Schema.title(),
-   *       "Task ID": Schema.richText(),
    *       Status: Schema.select([
    *         { name: "Open", color: "default" },
    *         { name: "Done", color: "green" },
    *       ]),
    *     },
    *   },
+   * });
+   *
+   * worker.sync("tasksSync", {
+   *   database: tasks,
    *   execute: async () => {
    *     const changes = [
    *       {
    *         key: "task-1",
+   *         type: "upsert",
    *         properties: {
    *           "Task Name": Builder.title("Write docs"),
-   *           "Task ID": Builder.richText("task-1"),
    *           Status: Builder.select("Open"),
    *         },
    *       },
@@ -53,7 +116,74 @@ class Worker {
    */
   sync(key, config) {
     this.#validateUniqueKey(key);
-    const capability = createSyncCapability(key, config);
+    const capability = createSyncCapability(
+      key,
+      config,
+      Array.from(this.#pacers.values())
+    );
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
+  /**
+   * Register an AI connector capability.
+   *
+   * Example:
+   *
+   * ```ts
+   * const worker = new Worker();
+   * export default worker;
+   *
+   * worker.aiConnector("supportChats", {
+   *   aiConnectorId: "connector-record-id",
+   *   archetype: "chat",
+   *   mode: "incremental",
+   *   schedule: "15m",
+   *   execute: async (state) => ({
+   *     changes: [
+   *       {
+   *         type: "upsert",
+   *         key: "thread-1",
+   *         record: {
+   *           createdAt: "2026-01-01T00:00:00Z",
+   *           updatedAt: "2026-01-01T00:00:00Z",
+   *           channel: {
+   *             id: "channel-1",
+   *             name: "Support",
+   *           },
+   *           threadId: "thread-1",
+   *           messages: [
+   *             {
+   *               id: "message-1",
+   *               content: "Hello from support",
+   *               timestamp: "2026-01-01T00:00:00Z",
+   *               author: {
+   *                 id: "user-1",
+   *                 username: "alice",
+   *               },
+   *             },
+   *           ],
+   *         },
+   *       },
+   *     ],
+   *     hasMore: false,
+   *   }),
+   * });
+   * ```
+   *
+   * `aiConnectorId` must be the Notion record ID of an existing custom
+   * connector in the workspace where you deploy this worker.
+   *
+   * @param key - The unique key for this capability.
+   * @param config - The AI connector configuration.
+   * @returns The capability object.
+   */
+  aiConnector(key, config) {
+    this.#validateUniqueKey(key);
+    const capability = createAiConnectorCapability(
+      key,
+      config,
+      Array.from(this.#pacers.values())
+    );
     this.#capabilities.set(key, capability);
     return capability;
   }
@@ -123,6 +253,40 @@ class Worker {
     this.#capabilities.set(key, capability);
     return capability;
   }
+  /**
+   * Register a webhook capability.
+   *
+   * Webhooks expose an HTTP endpoint that external services can call.
+   * When hit, the request is processed by the worker's execute function.
+   *
+   * Example:
+   *
+   * ```ts
+   * const worker = new Worker();
+   * export default worker;
+   *
+   * worker.webhook("onGithubPush", {
+   *   title: "GitHub Push Webhook",
+   *   description: "Handles push events from GitHub",
+   *   execute: async (events, { notion }) => {
+   *    for (const event of events) {
+   *      console.log("Received webhook:", event.body);
+   *      console.log("Headers:", event.headers);
+   *    }
+   *   },
+   * })
+   * ```
+   *
+   * @param key - The unique key for this capability. Used as the webhook name in the URL.
+   * @param config - The webhook configuration.
+   * @returns The capability object.
+   */
+  webhook(key, config) {
+    this.#validateUniqueKey(key);
+    const capability = createWebhookCapability(key, config);
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
   /**
    * Register an OAuth capability.
    *
@@ -180,6 +344,14 @@ class Worker {
       config: c.config
     }));
   }
+  get manifest() {
+    return {
+      sdkVersion: SDK_VERSION,
+      databases: Array.from(this.#databases.values()),
+      pacers: Array.from(this.#pacers.values()),
+      capabilities: this.capabilities
+    };
+  }
   /**
    * Execute a capability by key.
    *
@@ -198,17 +370,21 @@ class Worker {
         `Cannot run OAuth capability "${key}" - OAuth capabilities only provide configuration`
       );
     }
+    if (!capability.handler) {
+      throw new Error(`Capability "${key}" cannot be executed`);
+    }
     return capability.handler(context, options);
   }
   #validateUniqueKey(key) {
     if (!key || typeof key !== "string") {
       throw new Error("Capability key must be a non-empty string");
     }
-    if (this.#capabilities.has(key)) {
-      throw new Error(`Capability with key "${key}" already registered`);
+    if (this.#capabilities.has(key) || this.#databases.has(key) || this.#pacers.has(key)) {
+      throw new Error(`Worker item with key "${key}" already registered`);
     }
   }
 }
 export {
+  WebhookVerificationError,
   Worker
 };

package/dist/worker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=worker.test.d.ts.map

package/dist/worker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.test.d.ts","sourceRoot":"","sources":["../src/worker.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/workers",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"description": "An SDK for building workers for the Notion Workers platform",
 	"license": "MIT",
 	"type": "module",
@@ -32,6 +32,10 @@
 		"./types": {
 			"types": "./dist/types.d.ts",
 			"default": "./dist/types.js"
+		},
+		"./pacer": {
+			"types": "./dist/pacer.d.ts",
+			"default": "./dist/pacer.js"
 		}
 	},
 	"engines": {
@@ -69,6 +73,7 @@
 		"@notionhq/client": "^2.2.15"
 	},
 	"dependencies": {
-		"ajv": "^8.17.1"
+		"ajv": "^8.17.1",
+		"ajv-formats": "^3.0.1"
 	}
 }

package/src/ajv-formats.d.ts

@@ -0,0 +1,7 @@
+// ajv-formats is CJS-only and doesn't ship types compatible with
+// moduleResolution: "nodenext". This declaration provides the correct
+// callable default export signature so we can import it without suppression.
+declare module "ajv-formats" {
+	import type { Ajv } from "ajv";
+	export default function addFormats(ajv: Ajv): Ajv;
+}