@notionhq/workers 0.3.0 → 0.4.0

package/dist/capabilities/ai_connector.js

@@ -19,7 +19,7 @@ function createAiConnectorCapability(key, configuration, pacerDeclarations) {
       ...configuration.schedule === void 0 ? {} : { schedule: parseSchedule(configuration.schedule) }
     },
     async handler(runtimeContext, options) {
-      const capabilityContext = createCapabilityContext();
+      const capabilityContext = createCapabilityContext("ai_connector");
       const state = runtimeContext?.state ?? runtimeContext?.userContext;
       initPacerState(runtimeContext?.pacers, pacerDeclarations);
       let executionResult;

package/dist/capabilities/automation.js

@@ -11,7 +11,7 @@ function createAutomationCapability(key, config) {
     },
     async handler(event, options) {
       try {
-        const capabilityContext = createCapabilityContext();
+        const capabilityContext = createCapabilityContext("automation");
         await config.execute(event, capabilityContext);
         if (options?.concreteOutput) {
           return { status: "success" };

package/dist/capabilities/context.d.ts

@@ -1,7 +1,8 @@
 import { Client } from "@notionhq/client";
+import type { CapabilityType } from "../worker.js";
 export type CapabilityContext = {
     /** Notion API SDK client for this execution. */
     notion: Client;
 };
-export declare function createCapabilityContext(): CapabilityContext;
+export declare function createCapabilityContext(capabilityType: CapabilityType): CapabilityContext;
 //# sourceMappingURL=context.d.ts.map

package/dist/capabilities/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/capabilities/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAG1C,MAAM,MAAM,iBAAiB,GAAG;IAC/B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,wBAAgB,uBAAuB,IAAI,iBAAiB,CAc3D"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/capabilities/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,MAAM,iBAAiB,GAAG;IAC/B,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;CACf,CAAC;AAwCF,wBAAgB,uBAAuB,CACtC,cAAc,EAAE,cAAc,GAC5B,iBAAiB,CAenB"}

package/dist/capabilities/context.js

@@ -1,12 +1,30 @@
 import { Client } from "@notionhq/client";
-function createCapabilityContext() {
+const FIX_STEPS = "\n\nTo fix this:\n1. Create an internal integration at https://www.notion.so/profile/integrations/internal\n2. Give the integration access to the relevant pages/databases\n3. Add NOTION_API_TOKEN=<your-token> to your .env file\n4. For deployed workers, run: ntn workers env push";
+function missingTokenMessage(capabilityType) {
+  if (capabilityType === "tool") {
+    return "NOTION_API_TOKEN is not set. When tools are called through a Custom Agent, the platform sets NOTION_API_TOKEN automatically, using the permissions of the Custom Agent. Outside of that context (e.g. ntn workers exec), you must set it yourself." + FIX_STEPS;
+  }
+  return `NOTION_API_TOKEN is not set. context.notion requires an API token to make requests in ${capabilityType} capabilities to Notion.` + FIX_STEPS;
+}
+function createUnauthenticatedNotionProxy(capabilityType) {
+  return new Proxy({}, {
+    get(_target, prop) {
+      if (prop === "then" || typeof prop === "symbol") {
+        return void 0;
+      }
+      throw new Error(missingTokenMessage(capabilityType));
+    }
+  });
+}
+function createCapabilityContext(capabilityType) {
   const options = {};
   if (process.env.NOTION_API_BASE_URL) {
     options.baseUrl = process.env.NOTION_API_BASE_URL;
   }
-  if (process.env.NOTION_API_TOKEN) {
-    options.auth = process.env.NOTION_API_TOKEN;
+  if (!process.env.NOTION_API_TOKEN) {
+    return { notion: createUnauthenticatedNotionProxy(capabilityType) };
   }
+  options.auth = process.env.NOTION_API_TOKEN;
   const notion = new Client(options);
   return { notion };
 }

package/dist/capabilities/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/capabilities/sync.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/capabilities/sync.ts"],"names":[],"mappings":"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"}

package/dist/capabilities/sync.js

@@ -1,4 +1,4 @@
-import { ExecutionError } from "../error.js";
+import { ExecutionError, RateLimitError } from "../error.js";
 import {
   getPacerState,
   initPacerState
@@ -19,7 +19,7 @@ function createSyncCapability(key, syncConfiguration, pacerDeclarations) {
       schedule: syncConfiguration.schedule ? parseSchedule(syncConfiguration.schedule) : void 0
     },
     async handler(runtimeContext, options) {
-      const capabilityContext = createCapabilityContext();
+      const capabilityContext = createCapabilityContext("sync");
       const state = runtimeContext?.state ?? runtimeContext?.userContext;
       initPacerState(runtimeContext?.pacers, pacerDeclarations);
       let executionResult;
@@ -29,12 +29,32 @@ function createSyncCapability(key, syncConfiguration, pacerDeclarations) {
           capabilityContext
         );
       } catch (err) {
+        if (err instanceof RateLimitError) {
+          if (!options?.concreteOutput) {
+            const envelope = {
+              _tag: "error",
+              error: {
+                _tag: "rate_limit",
+                name: err.name,
+                message: err.message,
+                ...err.retryAfter !== void 0 ? { retryAfter: err.retryAfter } : {}
+              }
+            };
+            writeOutput(envelope);
+          }
+          throw err;
+        }
         const error = new ExecutionError(err);
         if (!options?.concreteOutput) {
-          writeOutput({
+          const envelope = {
             _tag: "error",
-            error: { name: error.name, message: error.message }
-          });
+            error: {
+              _tag: "generic",
+              name: error.name,
+              message: error.message
+            }
+          };
+          writeOutput(envelope);
         }
         throw error;
       }

package/dist/capabilities/tool.d.ts

@@ -1,11 +1,31 @@
 import type { SchemaBuilder } from "../schema-builder.js";
 import type { HandlerOptions, JSONValue } from "../types.js";
 import type { CapabilityContext } from "./context.js";
+/**
+ * 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> {
     title: string;
     description: string;
     schema: SchemaBuilder<I>;
     outputSchema?: SchemaBuilder<O>;
+    hints?: ToolHints;
     execute: (input: I, context: CapabilityContext) => O | Promise<O>;
 }
 /**
@@ -56,6 +76,7 @@ export declare function createToolCapability<I extends JSONValue, O extends JSON
         description: string;
         schema: import("../json-schema.js").JSONSchema<I>;
         outputSchema: import("../json-schema.js").JSONSchema<O> | undefined;
+        hints: ToolHints | undefined;
     };
     handler: {
         (input: JSONValue, options: HandlerOptions): Promise<O>;

package/dist/capabilities/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/capabilities/tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAkEtD,MAAM,WAAW,iBAAiB,CACjC,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,SAAS,GAAG,SAAS;IAE/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACzB,YAAY,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAChC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;;CAON;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;;CAON;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;;CAON;AAED,MAAM,MAAM,cAAc,CACzB,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,SAAS,GAAG,SAAS,IAC5B,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,SAAS,GAAG,SAAS,EAC9B,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC;;;;;;;;;;gBAiBf,SAAS,WAAW,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;gBAC/C,SAAS,GAAG,OAAO,CAC9C;YACA,IAAI,EAAE,SAAS,CAAC;YAChB,KAAK,EAAE,CAAC,CAAC;SACR,GACD;YACA,IAAI,EAAE,OAAO,CAAC;YACd,KAAK,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;aAAE,CAAC;SACnE,CACH;;EA4GD"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/capabilities/tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAkEtD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB,CACjC,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,SAAS,GAAG,SAAS;IAE/B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IACzB,YAAY,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,iBAAiB,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClE;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;;CAON;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;;CAON;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;;CAON;AAED,MAAM,MAAM,cAAc,CACzB,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,SAAS,GAAG,SAAS,IAC5B,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CACnC,CAAC,SAAS,SAAS,EACnB,CAAC,SAAS,SAAS,GAAG,SAAS,EAC9B,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC;;;;;;;;;;;gBAiBf,SAAS,WAAW,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;gBAC/C,SAAS,GAAG,OAAO,CAC9C;YACA,IAAI,EAAE,SAAS,CAAC;YAChB,KAAK,EAAE,CAAC,CAAC;SACR,GACD;YACA,IAAI,EAAE,OAAO,CAAC;YACd,KAAK,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,OAAO,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;aAAE,CAAC;SACnE,CACH;;EA6GD"}

package/dist/capabilities/tool.js

@@ -114,7 +114,7 @@ function createToolCapability(key, config) {
       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(
@@ -164,7 +164,8 @@ function createToolCapability(key, config) {
       title: config.title,
       description: config.description,
       schema: inputSchema,
-      outputSchema
+      outputSchema,
+      hints: config.hints
     },
     handler
   };

package/dist/capabilities/webhook.js

@@ -17,7 +17,7 @@ function createWebhookCapability(key, config) {
     },
     async handler(events, options) {
       try {
-        const capabilityContext = createCapabilityContext();
+        const capabilityContext = createCapabilityContext("webhook");
         await config.execute(events, capabilityContext);
         if (options?.concreteOutput) {
           return { status: "success" };

package/dist/error.d.ts

@@ -5,6 +5,42 @@ export declare class ExecutionError extends Error {
     readonly cause: unknown;
     constructor(cause: unknown);
 }
+/**
+ * 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 declare 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;
+    });
+}
 /**
  * Helper for exhaustive switch statements. TypeScript will error if a case is not handled.
  */

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,KAAK,EAAE,OAAO;CAK1B;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAE/C"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;gBAEZ,KAAK,EAAE,OAAO;CAK1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAe,SAAQ,cAAc;IACjD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE5B,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;CAK7C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAE/C"}

package/dist/error.js

@@ -6,10 +6,24 @@ class ExecutionError extends Error {
     this.cause = cause;
   }
 }
+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.
+   */
+  retryAfter;
+  constructor(options) {
+    super("Rate limited by external API");
+    this.name = "RateLimitError";
+    this.retryAfter = options?.retryAfter;
+  }
+}
 function unreachable(value) {
   throw new Error(`Unreachable: ${value}`);
 }
 export {
   ExecutionError,
+  RateLimitError,
   unreachable
 };

package/dist/index.d.ts

@@ -4,9 +4,10 @@ export type { AutomationCapability, AutomationConfiguration, AutomationEvent, Pa
 export type { CapabilityContext } from "./capabilities/context.js";
 export type { NotionManagedOAuthConfiguration, OAuthCapability, OAuthConfiguration, UserManagedOAuthConfiguration, } from "./capabilities/oauth.js";
 export type { SyncCapability, SyncChange, SyncChangeDelete, SyncChangeUpsert, SyncConfiguration, 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/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACvE,YAAY,EACX,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,eAAe,EACf,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,GAC5B,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACX,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,YAAY,EACX,+BAA+B,EAC/B,eAAe,EACf,kBAAkB,EAClB,6BAA6B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,QAAQ,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EACX,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,GACZ,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACX,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AACpB,YAAY,EACX,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,cAAc,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACvE,YAAY,EACX,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,eAAe,EACf,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,GAC5B,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACX,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,YAAY,EACX,+BAA+B,EAC/B,eAAe,EACf,kBAAkB,EAClB,6BAA6B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,QAAQ,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACX,cAAc,EACd,iBAAiB,EACjB,SAAS,GACT,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACX,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,GACZ,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACX,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AACpB,YAAY,EACX,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,cAAc,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,8 +1,10 @@
 import { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
 import { WebhookVerificationError } from "./capabilities/webhook.js";
+import { RateLimitError } from "./error.js";
 import { getSchema, j } from "./schema-builder.js";
 import { Worker } from "./worker.js";
 export {
+  RateLimitError,
   WebhookVerificationError,
   Worker,
   emojiIcon,

package/dist/worker.d.ts

@@ -12,6 +12,7 @@ import type { HandlerOptions, JSONValue } from "./types.js";
 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;
+export type CapabilityType = Capability["_tag"];
 /**
  * Configuration for a database that Notion creates and manages on behalf
  * of the worker. The database is created on first deploy and its schema

package/dist/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/workers",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "An SDK for building workers for the Notion Workers platform",
 	"license": "MIT",
 	"type": "module",
@@ -70,7 +70,7 @@
 		"vitest": "^4.0.8"
 	},
 	"peerDependencies": {
-		"@notionhq/client": "^2.2.15"
+		"@notionhq/client": ">=2.2.15"
 	},
 	"dependencies": {
 		"ajv": "^8.17.1",

package/src/capabilities/ai_connector.ts

@@ -154,7 +154,7 @@ export function createAiConnectorCapability<
 			runtimeContext?: StatefulRuntimeContext<State>,
 			options?: HandlerOptions,
 		) {
-			const capabilityContext = createCapabilityContext();
+			const capabilityContext = createCapabilityContext("ai_connector");
 			const state = runtimeContext?.state ?? runtimeContext?.userContext;
 
 			initPacerState(runtimeContext?.pacers, pacerDeclarations);

package/src/capabilities/automation.ts

@@ -105,7 +105,7 @@ export function createAutomationCapability(
 			options?: HandlerOptions,
 		): Promise<{ status: "success" } | undefined> {
 			try {
-				const capabilityContext = createCapabilityContext();
+				const capabilityContext = createCapabilityContext("automation");
 				await config.execute(event, capabilityContext);
 
 				if (options?.concreteOutput) {

package/src/capabilities/context.ts

@@ -1,22 +1,64 @@
 import { Client } from "@notionhq/client";
 import type { ClientOptions } from "@notionhq/client/build/src/Client.js";
+import type { CapabilityType } from "../worker.js";
 
 export type CapabilityContext = {
 	/** Notion API SDK client for this execution. */
 	notion: Client;
 };
 
-export function createCapabilityContext(): 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" +
+	"3. Add NOTION_API_TOKEN=<your-token> to your .env file\n" +
+	"4. For deployed workers, run: ntn workers env push";
+
+function missingTokenMessage(capabilityType: CapabilityType): string {
+	if (capabilityType === "tool") {
+		return (
+			"NOTION_API_TOKEN is not set. " +
+			"When tools are called through a Custom Agent, the platform sets NOTION_API_TOKEN automatically, " +
+			"using the permissions of the Custom Agent. " +
+			"Outside of that context (e.g. ntn workers exec), you must set it yourself." +
+			FIX_STEPS
+		);
+	}
+
+	return (
+		"NOTION_API_TOKEN is not set. " +
+		`context.notion requires an API token to make requests in ${capabilityType} capabilities to Notion.` +
+		FIX_STEPS
+	);
+}
+
+function createUnauthenticatedNotionProxy(
+	capabilityType: CapabilityType,
+): Client {
+	return new Proxy({} as Client, {
+		get(_target, prop) {
+			if (prop === "then" || typeof prop === "symbol") {
+				return undefined;
+			}
+			throw new Error(missingTokenMessage(capabilityType));
+		},
+	});
+}
+
+export function createCapabilityContext(
+	capabilityType: CapabilityType,
+): CapabilityContext {
 	const options: ClientOptions = {};
 
 	if (process.env.NOTION_API_BASE_URL) {
 		options.baseUrl = process.env.NOTION_API_BASE_URL;
 	}
 
-	if (process.env.NOTION_API_TOKEN) {
-		options.auth = process.env.NOTION_API_TOKEN;
+	if (!process.env.NOTION_API_TOKEN) {
+		return { notion: createUnauthenticatedNotionProxy(capabilityType) };
 	}
 
+	options.auth = process.env.NOTION_API_TOKEN;
 	const notion = new Client(options);
 
 	return { notion };

package/src/capabilities/sync.test.ts

@@ -8,7 +8,7 @@ import {
 	vi,
 } from "vitest";
 import * as Builder from "../builder.js";
-import { ExecutionError } from "../error.js";
+import { ExecutionError, RateLimitError } from "../error.js";
 import { getPacerState } from "../pacer_internal.js";
 import * as Schema from "../schema.js";
 import { Worker } from "../worker.js";
@@ -251,6 +251,113 @@ describe("Worker.sync", () => {
 			);
 		});
 
+		it("wraps RateLimitError in error envelope with _tag rate_limit", async () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: {
+					properties: {
+						ID: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("rateLimitSync", {
+				database: db,
+				execute: async () => {
+					throw new RateLimitError();
+				},
+			});
+
+			await expect(capability.handler()).rejects.toThrow(RateLimitError);
+
+			expect(stdoutSpy).toHaveBeenCalledWith(
+				expect.stringContaining(`"_tag":"rate_limit"`),
+			);
+			expect(stdoutSpy).toHaveBeenCalledWith(
+				expect.stringContaining(`"name":"RateLimitError"`),
+			);
+		});
+
+		it("includes retryAfter in rate_limit error envelope when provided", async () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: {
+					properties: {
+						ID: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("rateLimitSync", {
+				database: db,
+				execute: async () => {
+					throw new RateLimitError({ retryAfter: 30 });
+				},
+			});
+
+			await expect(capability.handler()).rejects.toThrow(RateLimitError);
+
+			const output = stdoutSpy.mock.calls
+				.map((call) => String(call[0]))
+				.find((s) => s.includes(`"_tag":"rate_limit"`)) as string;
+			const parsed = JSON.parse(
+				output.replace(
+					/\n<__notion_output__>(.*)<\/__notion_output__>\n/,
+					"$1",
+				),
+			);
+			expect(parsed).toEqual({
+				_tag: "error",
+				error: {
+					_tag: "rate_limit",
+					name: "RateLimitError",
+					message:
+						"Error during worker execution: Rate limited by external API",
+					retryAfter: 30,
+				},
+			});
+		});
+
+		it("wraps RateLimitError without retryAfter correctly", async () => {
+			const worker = new Worker();
+			const db = worker.database("test", {
+				type: "managed",
+				initialTitle: "Test",
+				primaryKeyProperty: "ID",
+				schema: {
+					properties: {
+						ID: Schema.title(),
+					},
+				},
+			});
+
+			const capability = createSyncCapability("rateLimitSync", {
+				database: db,
+				execute: async () => {
+					throw new RateLimitError();
+				},
+			});
+
+			await expect(capability.handler()).rejects.toThrow(RateLimitError);
+
+			const output = stdoutSpy.mock.calls
+				.map((call) => String(call[0]))
+				.find((s) => s.includes(`"_tag":"rate_limit"`)) as string;
+			const parsed = JSON.parse(
+				output.replace(
+					/\n<__notion_output__>(.*)<\/__notion_output__>\n/,
+					"$1",
+				),
+			);
+			expect(parsed.error.retryAfter).toBeUndefined();
+		});
+
 		it("emits sync output with key and default targetDatabaseKey", async () => {
 			const worker = new Worker();
 			const tasks = worker.database("tasks", {

package/src/capabilities/sync.ts

@@ -1,4 +1,4 @@
-import { ExecutionError } from "../error.js";
+import { ExecutionError, RateLimitError } from "../error.js";
 import {
 	getPacerState,
 	initPacerState,
@@ -28,6 +28,18 @@ import {
 	type RuntimeContext as StatefulRuntimeContext,
 } from "./stateful-capability.js";
 
+type SyncErrorEnvelope =
+	| { _tag: "error"; error: { _tag: "generic"; name: string; message: string } }
+	| {
+			_tag: "error";
+			error: {
+				_tag: "rate_limit";
+				name: string;
+				message: string;
+				retryAfter?: number;
+			};
+	  };
+
 /**
  * Maps a property configuration to its corresponding value type.
  */
@@ -239,7 +251,7 @@ export function createSyncCapability<
 			runtimeContext?: StatefulRuntimeContext<Context>,
 			options?: HandlerOptions,
 		) {
-			const capabilityContext = createCapabilityContext();
+			const capabilityContext = createCapabilityContext("sync");
 			const state = runtimeContext?.state ?? runtimeContext?.userContext;
 
 			initPacerState(runtimeContext?.pacers, pacerDeclarations);
@@ -251,12 +263,35 @@ export function createSyncCapability<
 					capabilityContext,
 				);
 			} catch (err) {
+				if (err instanceof RateLimitError) {
+					if (!options?.concreteOutput) {
+						const envelope: SyncErrorEnvelope = {
+							_tag: "error",
+							error: {
+								_tag: "rate_limit",
+								name: err.name,
+								message: err.message,
+								...(err.retryAfter !== undefined
+									? { retryAfter: err.retryAfter }
+									: {}),
+							},
+						};
+						writeOutput(envelope);
+					}
+					throw err;
+				}
+
 				const error = new ExecutionError(err);
 				if (!options?.concreteOutput) {
-					writeOutput({
+					const envelope: SyncErrorEnvelope = {
 						_tag: "error",
-						error: { name: error.name, message: error.message },
-					});
+						error: {
+							_tag: "generic",
+							name: error.name,
+							message: error.message,
+						},
+					};
+					writeOutput(envelope);
 				}
 				throw error;
 			}

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

@@ -70,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,
@@ -78,6 +98,7 @@ export interface ToolConfiguration<
 	description: string;
 	schema: SchemaBuilder<I>;
 	outputSchema?: SchemaBuilder<O>;
+	hints?: ToolHints;
 	execute: (input: I, context: CapabilityContext) => O | Promise<O>;
 }
 
@@ -218,7 +239,7 @@ export function createToolCapability<
 		}
 
 		try {
-			const capabilityContext = createCapabilityContext();
+			const capabilityContext = createCapabilityContext("tool");
 			const result = await config.execute(input, capabilityContext);
 			if (validateOutput && !validateOutput(result)) {
 				const error = new InvalidToolOutputError(
@@ -281,6 +302,7 @@ export function createToolCapability<
 			description: config.description,
 			schema: inputSchema,
 			outputSchema: outputSchema,
+			hints: config.hints,
 		},
 		handler,
 	};

package/src/capabilities/webhook.ts

@@ -118,7 +118,7 @@ export function createWebhookCapability(
 			options?: HandlerOptions,
 		): Promise<{ status: "success" } | undefined> {
 			try {
-				const capabilityContext = createCapabilityContext();
+				const capabilityContext = createCapabilityContext("webhook");
 				await config.execute(events, capabilityContext);
 
 				if (options?.concreteOutput) {

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

@@ -37,13 +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/worker.ts

@@ -65,6 +65,8 @@ type Capability =
 	| OAuthCapability
 	| WebhookCapability;
 
+export type CapabilityType = Capability["_tag"];
+
 /**
  * Configuration for a database that Notion creates and manages on behalf
  * of the worker. The database is created on first deploy and its schema