@project-ajax/sdk 0.0.74 → 0.0.76

package/dist/capabilities/automation.d.ts

@@ -1,7 +1,8 @@
+import type { CapabilityContext } from "./context.js";
 /**
- * Context provided to automation execute functions
+ * Event provided to automation execute functions
  */
-export interface AutomationContext {
+export interface AutomationEvent {
     /**
      * The ID of the page that triggered the automation (if applicable)
      */
@@ -54,10 +55,11 @@ export interface AutomationConfiguration {
     description: string;
     /**
      * The function that executes when the automation is triggered
-     * @param context - Context about the automation trigger, including page data if applicable
+     * @param event - Event data about the automation trigger, including page data if applicable
+     * @param context - The capability execution context (Notion client, etc.)
      * @returns A promise that resolves when the automation completes
      */
-    execute: (context: AutomationContext) => Promise<void> | void;
+    execute: (event: AutomationEvent, context: CapabilityContext) => Promise<void> | void;
 }
 /**
  * Result returned from automation execution
@@ -81,6 +83,6 @@ export declare function createAutomationCapability(key: string, config: Automati
         title: string;
         description: string;
     };
-    handler(context: AutomationContext): Promise<void>;
+    handler(event: AutomationEvent): Promise<void>;
 };
 //# sourceMappingURL=automation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"automation.d.ts","sourceRoot":"","sources":["../../src/capabilities/automation.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,cAAc,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAC5C,OAAO,0BAA0B,CACjC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,uBAAuB;;;;;;;qBASP,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;EAezD"}
+{"version":3,"file":"automation.d.ts","sourceRoot":"","sources":["../../src/capabilities/automation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGtD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,cAAc,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,OAAO,EAAE,CACR,KAAK,EAAE,eAAe,EACtB,OAAO,EAAE,iBAAiB,KACtB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAC5C,OAAO,0BAA0B,CACjC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACzC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,uBAAuB;;;;;;;mBAST,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;EAgBrD"}

package/dist/capabilities/automation.js

@@ -1,4 +1,5 @@
 import { ExecutionError } from "../error.js";
+import { createCapabilityContext } from "./context.js";
 function createAutomationCapability(key, config) {
   return {
     _tag: "automation",
@@ -7,9 +8,10 @@ function createAutomationCapability(key, config) {
       title: config.title,
       description: config.description
     },
-    async handler(context) {
+    async handler(event) {
       try {
-        await config.execute(context);
+        const capabilityContext = createCapabilityContext();
+        await config.execute(event, capabilityContext);
         process.stdout.write(
           `
 <output>${JSON.stringify({ status: "success" })}</output>

package/dist/capabilities/context.d.ts

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

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

@@ -0,0 +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"}

package/dist/capabilities/context.js

@@ -0,0 +1,15 @@
+import { Client } from "@notionhq/client";
+function createCapabilityContext() {
+  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;
+  }
+  const notion = new Client(options);
+  return { notion };
+}
+export {
+  createCapabilityContext
+};

package/dist/capabilities/sync.d.ts

@@ -1,5 +1,7 @@
+import { type PacerEntry } from "../pacer_internal.js";
 import type { PropertyConfiguration, PropertySchema, Schema } from "../schema.js";
 import type { Icon, PeopleValue, PlaceValue, RelationValue, Schedule, SyncSchedule, TextValue } from "../types.js";
+import type { CapabilityContext } from "./context.js";
 /**
  * Maps a property configuration to its corresponding value type.
  */
@@ -69,7 +71,7 @@ export type SyncChange<PK extends string, S extends PropertySchema<PK>> = SyncCh
 /**
  * Result returned from the sync execute function.
  */
-export type SyncExecutionResult<PK extends string, Context = unknown> = {
+export type SyncExecutionResult<PK extends string, State = unknown> = {
     /**
      * The batch of changes to apply in this execution.
      * Can include upserts (create/update) and deletes.
@@ -77,23 +79,23 @@ export type SyncExecutionResult<PK extends string, Context = unknown> = {
     changes: SyncChange<PK, PropertySchema<PK>>[];
     /**
      * Indicates whether there is more data to fetch.
-     * - `true`: More data available, will trigger another execution with nextContext
+     * - `true`: More data available, will trigger another execution with nextState
      * - `false`: No more data to fetch, sync is complete
      */
     hasMore: boolean;
     /**
-     * Optional context data to pass to the next execution.
+     * Optional state data to pass to the next execution.
      * Required if `hasMore` is `true`, ignored if `hasMore` is `false`.
      * This can be any type of data (cursor, page number, timestamp, etc.).
-     * The same data will be provided in the context parameter of the next execution.
+     * The same data will be provided as `state` in the next execution.
      */
-    nextContext?: Context;
+    nextState?: State;
 };
 /**
  * A configuration object that enables synchronization between a data
  * source and a third-party source.
  */
-export type SyncConfiguration<PK extends string, S extends Schema<PK>, Context = unknown> = {
+export type SyncConfiguration<PK extends string, S extends Schema<PK>, State = unknown> = {
     /**
      * The property of the data source that maps to a "primary key" in the
      * third-party data. This is used to match existing pages to
@@ -117,45 +119,43 @@ export type SyncConfiguration<PK extends string, S extends Schema<PK>, Context =
     mode?: SyncMode;
     /**
      * How often the sync should run.
-     * - "continuous": Run as frequently as the system allows (default)
+     * - "continuous": Run as frequently as the system allows
      * - Interval string: Run at specified intervals, e.g. "1h", "30m", "1d"
      *
      * Minimum interval: 1 minute ("1m")
      * Maximum interval: 7 days ("7d")
      *
-     * @default "continuous"
+     * @default "30m"
      */
     schedule?: Schedule;
     /**
      * A function that fetches the data to sync from the third-party service.
      *
      * This function can return all data at once, or implement pagination by:
-     * 1. Returning a batch of changes with `hasMore: true` and a `nextContext`
-     * 2. The runtime will call execute again with that context data
+     * 1. Returning a batch of changes with `hasMore: true` and a `nextState`
+     * 2. The runtime will call execute again with that state
      * 3. Continue until `hasMore: false` is returned
      *
      * The runtime will handle diffing against the data source and creating,
      * updating, and deleting pages as necessary.
      *
-     * @param context - Optional context data from previous execution (undefined on first call)
-     * @returns A result containing changes, hasMore status, and optional nextContext
+     * @param state - User-defined state from the previous execution (undefined on first call)
+     * @param context - Runtime context, including Notion client
+     * @returns A result containing changes, hasMore status, and optional nextState
      */
-    execute: (context?: Context) => Promise<SyncExecutionResult<PK, Context>>;
-};
-export type SyncHandlerResult<PK extends string, Context = unknown> = {
-    primaryKeyProperty: PK;
-    changes: SyncChange<PK, PropertySchema<PK>>[];
-    hasMore: boolean;
-    nextContext?: Context;
-    mode?: SyncMode;
+    execute: (state: State | undefined, context: CapabilityContext) => Promise<SyncExecutionResult<PK, State>>;
 };
 export type SyncCapability = ReturnType<typeof createSyncCapability>;
 /**
- * Context object passed from the runtime to sync capability handlers.
+ * Runtime context object passed from the runtime to sync capability handlers.
  */
 type RuntimeContext<UserContext = unknown> = {
-    /** The user-defined/-controlled context (cursor, pagination state, etc.) */
+    /** The user-defined/-controlled state (cursor, pagination state, etc.) */
+    state?: UserContext;
+    /** Legacy field for user-defined/-controlled state. */
     userContext?: UserContext;
+    /** Pacer state from the server for rate limiting. */
+    pacers?: Record<string, PacerEntry>;
 };
 /**
  * Creates a special handler for syncing third-party data to a collection.
@@ -177,6 +177,7 @@ export declare function createSyncCapability<PK extends string, S extends Schema
         changes: SyncChange<PK, PropertySchema<PK>>[];
         hasMore: boolean;
         nextUserContext: Context | undefined;
+        nextPacerState: Record<string, PacerEntry>;
     }>;
 };
 export {};

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":"AACA,OAAO,EAEN,KAAK,UAAU,EAGf,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACX,qBAAqB,EACrB,cAAc,EACd,MAAM,EACN,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EACX,IAAI,EACJ,WAAW,EACX,UAAU,EACV,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,SAAS,EAET,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGtD;;GAEG;AACH,KAAK,iBAAiB,CAAC,CAAC,SAAS,qBAAqB,IAAI,CAAC,SAAS;IACnE,IAAI,EAAE,QAAQ,CAAC;CACf,GACE,WAAW,GACX,CAAC,SAAS;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B,UAAU,GACV,CAAC,SAAS;IAAE,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B,aAAa,GACb,SAAS,CAAC;AAEf;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAC3B,EAAE,SAAS,MAAM,EACjB,CAAC,SAAS,cAAc,CAAC,EAAE,CAAC,IACzB;IACH;;OAEG;IACH,IAAI,EAAE,QAAQ,CAAC;IACf;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,UAAU,EAAE;SACV,QAAQ,IAAI,MAAM,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;KACrD,CAAC;IACF;;;OAGG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B;;OAEG;IACH,IAAI,EAAE,QAAQ,CAAC;IACf;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC,SAAS,cAAc,CAAC,EAAE,CAAC,IACnE,gBAAgB,CAAC,EAAE,EAAE,CAAC,CAAC,GACvB,gBAAgB,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,KAAK,GAAG,OAAO,IAAI;IACrE;;;OAGG;IACH,OAAO,EAAE,UAAU,CAAC,EAAE,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAE9C;;;;OAIG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAC5B,EAAE,SAAS,MAAM,EACjB,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,EACpB,KAAK,GAAG,OAAO,IACZ;IACH;;;;OAIG;IACH,kBAAkB,EAAE,EAAE,CAAC;IAEvB;;OAEG;IACH,MAAM,EAAE,CAAC,CAAC;IAEV;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAEpB;;;;;;;;;;;;;;OAcG;IACH,OAAO,EAAE,CACR,KAAK,EAAE,KAAK,GAAG,SAAS,EACxB,OAAO,EAAE,iBAAiB,KACtB,OAAO,CAAC,mBAAmB,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAErE;;GAEG;AACH,KAAK,cAAc,CAAC,WAAW,GAAG,OAAO,IAAI;IAC5C,0EAA0E;IAC1E,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,uDAAuD;IACvD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,EAAE,SAAS,MAAM,EACjB,CAAC,SAAS,MAAM,CAAC,EAAE,CAAC,EACpB,OAAO,GAAG,OAAO,EAChB,GAAG,EAAE,MAAM,EAAE,iBAAiB,EAAE,iBAAiB,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,CAAC;;;;;;;;;6BAUlC,cAAc,CAAC,OAAO,CAAC;;;;;;EA+BvD"}

package/dist/capabilities/sync.js

@@ -1,4 +1,9 @@
 import { ExecutionError, unreachable } from "../error.js";
+import {
+  getPacerState,
+  setPacerState
+} from "../pacer_internal.js";
+import { createCapabilityContext } from "./context.js";
 function createSyncCapability(key, syncConfiguration) {
   return {
     _tag: "sync",
@@ -10,14 +15,21 @@ function createSyncCapability(key, syncConfiguration) {
       schedule: parseSchedule(syncConfiguration.schedule)
     },
     async handler(runtimeContext) {
-      const userContext = runtimeContext?.userContext;
-      const executionResult = await syncConfiguration.execute(userContext).catch((err) => {
+      const capabilityContext = createCapabilityContext();
+      const state = runtimeContext?.state ?? runtimeContext?.userContext;
+      const pacerState = {
+        pacers: runtimeContext?.pacers ?? {}
+      };
+      setPacerState(pacerState);
+      const executionResult = await syncConfiguration.execute(state, capabilityContext).catch((err) => {
         throw new ExecutionError(err);
       });
+      const updatedPacerState = getPacerState();
       const result = {
         changes: executionResult.changes,
         hasMore: executionResult.hasMore,
-        nextUserContext: executionResult.nextContext
+        nextUserContext: executionResult.nextState,
+        nextPacerState: updatedPacerState.pacers
       };
       process.stdout.write(`
 <output>${JSON.stringify(result)}</output>
@@ -31,10 +43,14 @@ const MS_PER_HOUR = 60 * MS_PER_MINUTE;
 const MS_PER_DAY = 24 * MS_PER_HOUR;
 const MIN_INTERVAL_MS = MS_PER_MINUTE;
 const MAX_INTERVAL_MS = 7 * MS_PER_DAY;
+const DEFAULT_INTERVAL_MS = 30 * MS_PER_MINUTE;
 function parseSchedule(schedule) {
-  if (!schedule || schedule === "continuous") {
+  if (schedule === "continuous") {
     return { type: "continuous" };
   }
+  if (!schedule) {
+    return { type: "interval", intervalMs: DEFAULT_INTERVAL_MS };
+  }
   const match = schedule.match(/^(\d+)(m|h|d)$/);
   if (!match || !match[1] || !match[2]) {
     throw new Error(

package/dist/capabilities/tool.d.ts

@@ -1,11 +1,12 @@
 import { type JSONSchemaType } from "ajv";
 import type { JSONValue } from "../types.js";
+import type { CapabilityContext } from "./context.js";
 export interface ToolConfiguration<I extends JSONValue, O extends JSONValue = JSONValue> {
     title: string;
     description: string;
     schema: JSONSchemaType<I>;
     outputSchema?: JSONSchemaType<O>;
-    execute: (input: I) => O | Promise<O>;
+    execute: (input: I, context: CapabilityContext) => O | Promise<O>;
 }
 /**
  * An error returned when the input to a tool doesn't match the input schema.

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

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/capabilities/tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,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,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1B,YAAY,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACjC,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtC;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;CAMN;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;CAMN;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;CAMN;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;;;;;;;;;mBAgBvB,SAAS,GAAG,OAAO,CACrC;QACA,IAAI,EAAE,SAAS,CAAC;QAChB,KAAK,EAAE,CAAC,CAAC;KACR,GACD;QACA,IAAI,EAAE,OAAO,CAAC;QACd,KAAK,EACF,qBAAqB,GACrB,sBAAsB,GACtB,kBAAkB,CAAC;KACrB,CACH;EA0DF"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/capabilities/tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,KAAK,cAAc,EAAE,MAAM,KAAK,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGtD,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,cAAc,CAAC,CAAC,CAAC,CAAC;IAC1B,YAAY,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACjC,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;;;;CAMN;AAED;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;CAMN;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;IAK3B,MAAM;;;;CAMN;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;;;;;;;;;mBAgBvB,SAAS,GAAG,OAAO,CACrC;QACA,IAAI,EAAE,SAAS,CAAC;QAChB,KAAK,EAAE,CAAC,CAAC;KACR,GACD;QACA,IAAI,EAAE,OAAO,CAAC;QACd,KAAK,EACF,qBAAqB,GACrB,sBAAsB,GACtB,kBAAkB,CAAC;KACrB,CACH;EA2DF"}

package/dist/capabilities/tool.js

@@ -1,4 +1,5 @@
 import { Ajv } from "ajv";
+import { createCapabilityContext } from "./context.js";
 class InvalidToolInputError extends Error {
   constructor(message) {
     super(message);
@@ -67,7 +68,8 @@ function createToolCapability(key, config) {
         return result;
       }
       try {
-        const result = await config.execute(input);
+        const capabilityContext = createCapabilityContext();
+        const result = await config.execute(input, capabilityContext);
         if (validateOutput && !validateOutput(result)) {
           const result2 = {
             _tag: "error",

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
-export type { AutomationCapability, AutomationConfiguration, AutomationContext, PageObjectResponse, } from "./capabilities/automation.js";
+export type { AutomationCapability, AutomationConfiguration, AutomationEvent, PageObjectResponse, } from "./capabilities/automation.js";
+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 { Pacer } from "./pacer.js";
 export type { Icon, ImageIcon, NoticonColor, NoticonName, PlaceValue, Schedule, } from "./types.js";
 export { Worker } from "./worker.js";
 //# sourceMappingURL=index.d.ts.map

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,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,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,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AACpB,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,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;AAEhF,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EACX,IAAI,EACJ,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,6 +1,8 @@
 import { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
+import { Pacer } from "./pacer.js";
 import { Worker } from "./worker.js";
 export {
+  Pacer,
   Worker,
   emojiIcon,
   imageIcon,

package/dist/pacer.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Pacer module for rate limiting API requests.
+ *
+ * The Pacer ensures requests are evenly spaced over time to respect third-party
+ * API rate limits. Instead of making all requests immediately until hitting a 429,
+ * Pacer paces requests throughout the rate limit window.
+ *
+ * @example
+ * ```ts
+ * import { Pacer } from "@project-ajax/sdk/pacer"
+ *
+ * // Rate limit: 10 requests per minute
+ * await Pacer.wait("salesforce-api", { requests: 10, intervalMs: 60 * 1000 })
+ *
+ * // Now make your API call
+ * const data = await fetchFromSalesforce()
+ * ```
+ *
+ * @module
+ */
+export type PacerLimit = {
+    requests: number;
+    intervalMs: number;
+};
+export declare const Pacer: {
+    /**
+     * Wait until a request can proceed under the specified rate limit.
+     *
+     * This function paces requests evenly across the rate limit interval. For example,
+     * with 60 requests allowed per hour, requests are spaced approximately 1 minute apart.
+     *
+     * @param key - Unique identifier for this rate limit scope (e.g., "salesforce-api", "jira:token123"). If you're not sure, use any string.
+     * @param limit - Rate limit configuration: `requests` per `intervalMs`.
+     *
+     * @example
+     * ```ts
+     * // Salesforce: 30,000 requests per 24 hours
+     * await Pacer.wait("salesforce", { requests: 30_000, intervalMs: 24 * 60 * 60 * 1000 })
+     *
+     * // Jira: 100 requests per minute
+     * await Pacer.wait("jira", { requests: 100, intervalMs: 60 * 1000 })
+     *
+     * // Multiple rate limits for different endpoints
+     * await Pacer.wait("api-read", { requests: 1000, intervalMs: 60 * 1000 })
+     * await Pacer.wait("api-write", { requests: 100, intervalMs: 60 * 1000 })
+     * ```
+     */
+    wait(key: string, limit: PacerLimit): Promise<void>;
+};
+//# sourceMappingURL=pacer.d.ts.map

package/dist/pacer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pacer.d.ts","sourceRoot":"","sources":["../src/pacer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,MAAM,UAAU,GAAG;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,KAAK;IACjB;;;;;;;;;;;;;;;;;;;;;OAqBG;cACa,MAAM,SAAS,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CA4BzD,CAAC"}

package/dist/pacer.js

@@ -0,0 +1,48 @@
+import { getPacerState, setPacerState } from "./pacer_internal.js";
+const Pacer = {
+  /**
+   * Wait until a request can proceed under the specified rate limit.
+   *
+   * This function paces requests evenly across the rate limit interval. For example,
+   * with 60 requests allowed per hour, requests are spaced approximately 1 minute apart.
+   *
+   * @param key - Unique identifier for this rate limit scope (e.g., "salesforce-api", "jira:token123"). If you're not sure, use any string.
+   * @param limit - Rate limit configuration: `requests` per `intervalMs`.
+   *
+   * @example
+   * ```ts
+   * // Salesforce: 30,000 requests per 24 hours
+   * await Pacer.wait("salesforce", { requests: 30_000, intervalMs: 24 * 60 * 60 * 1000 })
+   *
+   * // Jira: 100 requests per minute
+   * await Pacer.wait("jira", { requests: 100, intervalMs: 60 * 1000 })
+   *
+   * // Multiple rate limits for different endpoints
+   * await Pacer.wait("api-read", { requests: 1000, intervalMs: 60 * 1000 })
+   * await Pacer.wait("api-write", { requests: 100, intervalMs: 60 * 1000 })
+   * ```
+   */
+  async wait(key, limit) {
+    if (limit.requests <= 0) {
+      throw new Error("requests must be greater than 0");
+    }
+    if (limit.intervalMs <= 0) {
+      throw new Error("intervalMs must be greater than 0");
+    }
+    const now = Date.now();
+    const paceMs = Math.ceil(limit.intervalMs / limit.requests);
+    const state = getPacerState();
+    const existing = state.pacers[key];
+    const lastScheduledAtMs = existing?.lastScheduledAtMs ?? 0;
+    const scheduledAtMs = Math.max(lastScheduledAtMs + paceMs, now);
+    const delayMs = scheduledAtMs - now;
+    state.pacers[key] = { lastScheduledAtMs: scheduledAtMs };
+    setPacerState(state);
+    if (delayMs > 0) {
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+};
+export {
+  Pacer
+};

package/dist/pacer.test.d.ts

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

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

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

package/dist/pacer_internal.d.ts

@@ -0,0 +1,6 @@
+export type PacerState = {
+    pacers: Record<string, PacerEntry>;
+};
+export declare function setPacerState(state: PacerState): void;
+export declare function getPacerState(): PacerState;
+//# sourceMappingURL=pacer_internal.d.ts.map

package/dist/pacer_internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pacer_internal.d.ts","sourceRoot":"","sources":["../src/pacer_internal.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,UAAU,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACnC,CAAC;AAIF,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAErD;AAED,wBAAgB,aAAa,IAAI,UAAU,CAE1C"}

package/dist/pacer_internal.js

@@ -0,0 +1,11 @@
+let pacerState = { pacers: {} };
+function setPacerState(state) {
+  pacerState = state;
+}
+function getPacerState() {
+  return pacerState;
+}
+export {
+  getPacerState,
+  setPacerState
+};

package/dist/worker.d.ts

@@ -1,10 +1,11 @@
-import type { AutomationCapability, AutomationConfiguration, AutomationContext } from "./capabilities/automation.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 { Schema } from "./schema.js";
 import type { JSONValue } from "./types.js";
-export type { AutomationConfiguration, AutomationContext, OAuthConfiguration, NotionManagedOAuthConfiguration, UserManagedOAuthConfiguration, SyncConfiguration, ToolConfiguration, };
+export type { AutomationConfiguration, AutomationEvent, CapabilityContext, OAuthConfiguration, NotionManagedOAuthConfiguration, UserManagedOAuthConfiguration, SyncConfiguration, ToolConfiguration, };
 type Capability = SyncCapability | ToolCapability<any, any> | AutomationCapability | OAuthCapability;
 export declare class Worker {
     #private;
@@ -72,7 +73,7 @@ export declare class Worker {
      *     },
      *     required: ["name"],
      *   },
-     *   execute: ({ name }) => {
+     *   execute: ({ name }, { notion }) => {
      *     return `Hello, ${name}!`;
      *   },
      * })
@@ -96,8 +97,8 @@ export declare class Worker {
      * worker.automation("sendWelcomeEmail", {
      *   title: "Send Welcome Email",
      *   description: "Sends a welcome email when a new user is added",
-     *   execute: async (context) => {
-     *     const { pageId, pageData } = context;
+     *   execute: async (event, { notion }) => {
+     *     const { pageId, pageData } = event;
      *
      *     // Access page properties from the Public API format
      *     if (pageData) {

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,iBAAiB,EACjB,MAAM,8BAA8B,CAAC;AAEtC,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,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,YAAY,EACX,uBAAuB,EACvB,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;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;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;;;;;;OAMG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAyB1D"}
+{"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,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,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;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;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;;;;;;OAMG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAyB1D"}

package/dist/worker.js

@@ -73,7 +73,7 @@ class Worker {
    *     },
    *     required: ["name"],
    *   },
-   *   execute: ({ name }) => {
+   *   execute: ({ name }, { notion }) => {
    *     return `Hello, ${name}!`;
    *   },
    * })
@@ -102,8 +102,8 @@ class Worker {
    * worker.automation("sendWelcomeEmail", {
    *   title: "Send Welcome Email",
    *   description: "Sends a welcome email when a new user is added",
-   *   execute: async (context) => {
-   *     const { pageId, pageData } = context;
+   *   execute: async (event, { notion }) => {
+   *     const { pageId, pageData } = event;
    *
    *     // Access page properties from the Public API format
    *     if (pageData) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/sdk",
-	"version": "0.0.74",
+	"version": "0.0.76",
 	"description": "An SDK for building workers for the Project Ajax platform",
 	"license": "UNLICENSED",
 	"type": "module",
@@ -28,6 +28,10 @@
 		"./types": {
 			"types": "./dist/types.d.ts",
 			"default": "./dist/types.js"
+		},
+		"./pacer": {
+			"types": "./dist/pacer.d.ts",
+			"default": "./dist/pacer.js"
 		}
 	},
 	"engines": {
@@ -58,6 +62,9 @@
 		"typescript": "^5.9.3",
 		"vitest": "^4.0.8"
 	},
+	"peerDependencies": {
+		"@notionhq/client": "^2.2.15"
+	},
 	"dependencies": {
 		"ajv": "^8.17.1"
 	}

package/src/capabilities/automation.test.ts

@@ -8,7 +8,7 @@ import {
 	vi,
 } from "vitest";
 import { ExecutionError } from "../error.js";
-import type { AutomationContext, PageObjectResponse } from "./automation.js";
+import type { PageObjectResponse } from "./automation.js";
 import { createAutomationCapability } from "./automation.js";
 
 describe("createAutomationCapability", () => {
@@ -45,14 +45,19 @@ describe("createAutomationCapability", () => {
 			execute: executeFn,
 		});
 
-		const context: AutomationContext = {
+		const event = {
 			pageId: "page-123",
 			actionType: "test_action",
 		};
 
-		await capability.handler(context);
+		await capability.handler(event);
 
-		expect(executeFn).toHaveBeenCalledWith(context);
+		expect(executeFn).toHaveBeenCalledWith(
+			event,
+			expect.objectContaining({
+				notion: expect.any(Object),
+			}),
+		);
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			`\n<output>{"status":"success"}</output>\n`,
 		);
@@ -85,15 +90,20 @@ describe("createAutomationCapability", () => {
 			public_url: null,
 		};
 
-		const context: AutomationContext = {
+		const event = {
 			pageId: "page-789",
 			actionType: "process_page",
 			pageData,
 		};
 
-		await capability.handler(context);
+		await capability.handler(event);
 
-		expect(executeFn).toHaveBeenCalledWith(context);
+		expect(executeFn).toHaveBeenCalledWith(
+			event,
+			expect.objectContaining({
+				notion: expect.any(Object),
+			}),
+		);
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			`\n<output>{"status":"success"}</output>\n`,
 		);
@@ -108,12 +118,12 @@ describe("createAutomationCapability", () => {
 			},
 		});
 
-		const context: AutomationContext = {
+		const event = {
 			pageId: "page-error",
 			actionType: "error_action",
 		};
 
-		await expect(capability.handler(context)).rejects.toThrow(ExecutionError);
+		await expect(capability.handler(event)).rejects.toThrow(ExecutionError);
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			`\n<output>{"status":"error","error":{"name":"ExecutionError","message":"Error during worker execution: Error: Something went wrong"}}</output>\n`,
@@ -129,11 +139,11 @@ describe("createAutomationCapability", () => {
 			},
 		});
 
-		const context: AutomationContext = {
+		const event = {
 			actionType: "string_error_action",
 		};
 
-		await expect(capability.handler(context)).rejects.toThrow(ExecutionError);
+		await expect(capability.handler(event)).rejects.toThrow(ExecutionError);
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			`\n<output>{"status":"error","error":{"name":"ExecutionError","message":"Error during worker execution: String error"}}</output>\n`,

package/src/capabilities/automation.ts

@@ -1,9 +1,11 @@
 import { ExecutionError } from "../error.js";
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
 
 /**
- * Context provided to automation execute functions
+ * Event provided to automation execute functions
  */
-export interface AutomationContext {
+export interface AutomationEvent {
 	/**
 	 * The ID of the page that triggered the automation (if applicable)
 	 */
@@ -56,10 +58,14 @@ export interface AutomationConfiguration {
 
 	/**
 	 * The function that executes when the automation is triggered
-	 * @param context - Context about the automation trigger, including page data if applicable
+	 * @param event - Event data about the automation trigger, including page data if applicable
+	 * @param context - The capability execution context (Notion client, etc.)
 	 * @returns A promise that resolves when the automation completes
 	 */
-	execute: (context: AutomationContext) => Promise<void> | void;
+	execute: (
+		event: AutomationEvent,
+		context: CapabilityContext,
+	) => Promise<void> | void;
 }
 
 /**
@@ -92,9 +98,10 @@ export function createAutomationCapability(
 			title: config.title,
 			description: config.description,
 		},
-		async handler(context: AutomationContext): Promise<void> {
+		async handler(event: AutomationEvent): Promise<void> {
 			try {
-				await config.execute(context);
+				const capabilityContext = createCapabilityContext();
+				await config.execute(event, capabilityContext);
 				process.stdout.write(
 					`\n<output>${JSON.stringify({ status: "success" })}</output>\n`,
 				);

package/src/capabilities/context.ts

@@ -0,0 +1,23 @@
+import { Client } from "@notionhq/client";
+import type { ClientOptions } from "@notionhq/client/build/src/Client.js";
+
+export type CapabilityContext = {
+	/** Notion API SDK client for this execution. */
+	notion: Client;
+};
+
+export function createCapabilityContext(): 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;
+	}
+
+	const notion = new Client(options);
+
+	return { notion };
+}

package/src/capabilities/sync.ts

@@ -1,4 +1,10 @@
 import { ExecutionError, unreachable } from "../error.js";
+import {
+	getPacerState,
+	type PacerEntry,
+	type PacerState,
+	setPacerState,
+} from "../pacer_internal.js";
 import type {
 	PropertyConfiguration,
 	PropertySchema,
@@ -14,6 +20,8 @@ import type {
 	TextValue,
 	TimeUnit,
 } from "../types.js";
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
 
 /**
  * Maps a property configuration to its corresponding value type.
@@ -96,7 +104,7 @@ export type SyncChange<PK extends string, S extends PropertySchema<PK>> =
 /**
  * Result returned from the sync execute function.
  */
-export type SyncExecutionResult<PK extends string, Context = unknown> = {
+export type SyncExecutionResult<PK extends string, State = unknown> = {
 	/**
 	 * The batch of changes to apply in this execution.
 	 * Can include upserts (create/update) and deletes.
@@ -105,18 +113,18 @@ export type SyncExecutionResult<PK extends string, Context = unknown> = {
 
 	/**
 	 * Indicates whether there is more data to fetch.
-	 * - `true`: More data available, will trigger another execution with nextContext
+	 * - `true`: More data available, will trigger another execution with nextState
 	 * - `false`: No more data to fetch, sync is complete
 	 */
 	hasMore: boolean;
 
 	/**
-	 * Optional context data to pass to the next execution.
+	 * Optional state data to pass to the next execution.
 	 * Required if `hasMore` is `true`, ignored if `hasMore` is `false`.
 	 * This can be any type of data (cursor, page number, timestamp, etc.).
-	 * The same data will be provided in the context parameter of the next execution.
+	 * The same data will be provided as `state` in the next execution.
 	 */
-	nextContext?: Context;
+	nextState?: State;
 };
 
 /**
@@ -126,7 +134,7 @@ export type SyncExecutionResult<PK extends string, Context = unknown> = {
 export type SyncConfiguration<
 	PK extends string,
 	S extends Schema<PK>,
-	Context = unknown,
+	State = unknown,
 > = {
 	/**
 	 * The property of the data source that maps to a "primary key" in the
@@ -154,13 +162,13 @@ export type SyncConfiguration<
 
 	/**
 	 * How often the sync should run.
-	 * - "continuous": Run as frequently as the system allows (default)
+	 * - "continuous": Run as frequently as the system allows
 	 * - Interval string: Run at specified intervals, e.g. "1h", "30m", "1d"
 	 *
 	 * Minimum interval: 1 minute ("1m")
 	 * Maximum interval: 7 days ("7d")
 	 *
-	 * @default "continuous"
+	 * @default "30m"
 	 */
 	schedule?: Schedule;
 
@@ -168,35 +176,35 @@ export type SyncConfiguration<
 	 * A function that fetches the data to sync from the third-party service.
 	 *
 	 * This function can return all data at once, or implement pagination by:
-	 * 1. Returning a batch of changes with `hasMore: true` and a `nextContext`
-	 * 2. The runtime will call execute again with that context data
+	 * 1. Returning a batch of changes with `hasMore: true` and a `nextState`
+	 * 2. The runtime will call execute again with that state
 	 * 3. Continue until `hasMore: false` is returned
 	 *
 	 * The runtime will handle diffing against the data source and creating,
 	 * updating, and deleting pages as necessary.
 	 *
-	 * @param context - Optional context data from previous execution (undefined on first call)
-	 * @returns A result containing changes, hasMore status, and optional nextContext
+	 * @param state - User-defined state from the previous execution (undefined on first call)
+	 * @param context - Runtime context, including Notion client
+	 * @returns A result containing changes, hasMore status, and optional nextState
 	 */
-	execute: (context?: Context) => Promise<SyncExecutionResult<PK, Context>>;
-};
-
-export type SyncHandlerResult<PK extends string, Context = unknown> = {
-	primaryKeyProperty: PK;
-	changes: SyncChange<PK, PropertySchema<PK>>[];
-	hasMore: boolean;
-	nextContext?: Context;
-	mode?: SyncMode;
+	execute: (
+		state: State | undefined,
+		context: CapabilityContext,
+	) => Promise<SyncExecutionResult<PK, State>>;
 };
 
 export type SyncCapability = ReturnType<typeof createSyncCapability>;
 
 /**
- * Context object passed from the runtime to sync capability handlers.
+ * Runtime context object passed from the runtime to sync capability handlers.
  */
 type RuntimeContext<UserContext = unknown> = {
-	/** The user-defined/-controlled context (cursor, pagination state, etc.) */
+	/** The user-defined/-controlled state (cursor, pagination state, etc.) */
+	state?: UserContext;
+	/** Legacy field for user-defined/-controlled state. */
 	userContext?: UserContext;
+	/** Pacer state from the server for rate limiting. */
+	pacers?: Record<string, PacerEntry>;
 };
 
 /**
@@ -221,17 +229,29 @@ export function createSyncCapability<
 			schedule: parseSchedule(syncConfiguration.schedule),
 		},
 		async handler(runtimeContext?: RuntimeContext<Context>) {
-			const userContext = runtimeContext?.userContext;
+			const capabilityContext = createCapabilityContext();
+			const state = runtimeContext?.state ?? runtimeContext?.userContext;
+
+			// Initialize pacer state from runtime context
+			const pacerState: PacerState = {
+				pacers: runtimeContext?.pacers ?? {},
+			};
+			setPacerState(pacerState);
+
 			const executionResult = await syncConfiguration
-				.execute(userContext)
+				.execute(state, capabilityContext)
 				.catch((err) => {
 					throw new ExecutionError(err);
 				});
 
+			// Get updated pacer state after execution
+			const updatedPacerState = getPacerState();
+
 			const result = {
 				changes: executionResult.changes,
 				hasMore: executionResult.hasMore,
-				nextUserContext: executionResult.nextContext,
+				nextUserContext: executionResult.nextState,
+				nextPacerState: updatedPacerState.pacers,
 			};
 
 			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
@@ -248,14 +268,20 @@ const MS_PER_DAY = 24 * MS_PER_HOUR;
 const MIN_INTERVAL_MS = MS_PER_MINUTE; // 1m
 const MAX_INTERVAL_MS = 7 * MS_PER_DAY; // 7d
 
+const DEFAULT_INTERVAL_MS = 30 * MS_PER_MINUTE; // 30m
+
 /**
  * Parses a user-friendly schedule string into the normalized backend format.
  */
 function parseSchedule(schedule: Schedule | undefined): SyncSchedule {
-	if (!schedule || schedule === "continuous") {
+	if (schedule === "continuous") {
 		return { type: "continuous" };
 	}
 
+	if (!schedule) {
+		return { type: "interval", intervalMs: DEFAULT_INTERVAL_MS };
+	}
+
 	const match = schedule.match(/^(\d+)(m|h|d)$/);
 	if (!match || !match[1] || !match[2]) {
 		throw new Error(

package/src/capabilities/tool.ts

@@ -1,5 +1,7 @@
 import { Ajv, type JSONSchemaType } from "ajv";
 import type { JSONValue } from "../types.js";
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
 
 export interface ToolConfiguration<
 	I extends JSONValue,
@@ -9,7 +11,7 @@ export interface ToolConfiguration<
 	description: string;
 	schema: JSONSchemaType<I>;
 	outputSchema?: JSONSchemaType<O>;
-	execute: (input: I) => O | Promise<O>;
+	execute: (input: I, context: CapabilityContext) => O | Promise<O>;
 }
 
 /**
@@ -127,7 +129,8 @@ export function createToolCapability<
 			}
 
 			try {
-				const result = await config.execute(input);
+				const capabilityContext = createCapabilityContext();
+				const result = await config.execute(input, capabilityContext);
 				if (validateOutput && !validateOutput(result)) {
 					const result = {
 						_tag: "error" as const,

package/src/index.ts

@@ -2,9 +2,10 @@ export { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
 export type {
 	AutomationCapability,
 	AutomationConfiguration,
-	AutomationContext,
+	AutomationEvent,
 	PageObjectResponse,
 } from "./capabilities/automation.js";
+export type { CapabilityContext } from "./capabilities/context.js";
 export type {
 	NotionManagedOAuthConfiguration,
 	OAuthCapability,
@@ -21,6 +22,8 @@ export type {
 	SyncMode,
 } from "./capabilities/sync.js";
 export type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
+// Pacer module re-exported for convenience (users can also import from "@project-ajax/sdk/pacer")
+export { Pacer } from "./pacer.js";
 export type {
 	Icon,
 	ImageIcon,

package/src/pacer.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { Pacer } from "./pacer.js";
+import { getPacerState, setPacerState } from "./pacer_internal.js";
+
+describe("Pacer.wait", () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(0);
+		setPacerState({ pacers: {} });
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it("paces requests based on the rate limit", async () => {
+		const first = Pacer.wait("api", { requests: 10, intervalMs: 60_000 });
+
+		expect(getPacerState().pacers.api?.lastScheduledAtMs).toBe(6000);
+		await vi.advanceTimersByTimeAsync(6000);
+		await first;
+
+		const second = Pacer.wait("api", { requests: 10, intervalMs: 60_000 });
+		expect(getPacerState().pacers.api?.lastScheduledAtMs).toBe(12_000);
+		await vi.advanceTimersByTimeAsync(6000);
+		await second;
+	});
+
+	it("does not wait when the next slot is already in the past", async () => {
+		const first = Pacer.wait("api", { requests: 10, intervalMs: 60_000 });
+		await vi.advanceTimersByTimeAsync(6000);
+		await first;
+
+		vi.advanceTimersByTime(20_000);
+
+		const second = Pacer.wait("api", { requests: 10, intervalMs: 60_000 });
+		expect(getPacerState().pacers.api?.lastScheduledAtMs).toBe(26_000);
+		await second;
+	});
+});

package/src/pacer.ts

@@ -0,0 +1,80 @@
+/**
+ * Pacer module for rate limiting API requests.
+ *
+ * The Pacer ensures requests are evenly spaced over time to respect third-party
+ * API rate limits. Instead of making all requests immediately until hitting a 429,
+ * Pacer paces requests throughout the rate limit window.
+ *
+ * @example
+ * ```ts
+ * import { Pacer } from "@project-ajax/sdk/pacer"
+ *
+ * // Rate limit: 10 requests per minute
+ * await Pacer.wait("salesforce-api", { requests: 10, intervalMs: 60 * 1000 })
+ *
+ * // Now make your API call
+ * const data = await fetchFromSalesforce()
+ * ```
+ *
+ * @module
+ */
+
+import { getPacerState, setPacerState } from "./pacer_internal.js";
+
+export type PacerLimit = {
+	requests: number;
+	intervalMs: number;
+};
+
+export const Pacer = {
+	/**
+	 * Wait until a request can proceed under the specified rate limit.
+	 *
+	 * This function paces requests evenly across the rate limit interval. For example,
+	 * with 60 requests allowed per hour, requests are spaced approximately 1 minute apart.
+	 *
+	 * @param key - Unique identifier for this rate limit scope (e.g., "salesforce-api", "jira:token123"). If you're not sure, use any string.
+	 * @param limit - Rate limit configuration: `requests` per `intervalMs`.
+	 *
+	 * @example
+	 * ```ts
+	 * // Salesforce: 30,000 requests per 24 hours
+	 * await Pacer.wait("salesforce", { requests: 30_000, intervalMs: 24 * 60 * 60 * 1000 })
+	 *
+	 * // Jira: 100 requests per minute
+	 * await Pacer.wait("jira", { requests: 100, intervalMs: 60 * 1000 })
+	 *
+	 * // Multiple rate limits for different endpoints
+	 * await Pacer.wait("api-read", { requests: 1000, intervalMs: 60 * 1000 })
+	 * await Pacer.wait("api-write", { requests: 100, intervalMs: 60 * 1000 })
+	 * ```
+	 */
+	async wait(key: string, limit: PacerLimit): Promise<void> {
+		if (limit.requests <= 0) {
+			throw new Error("requests must be greater than 0");
+		}
+		if (limit.intervalMs <= 0) {
+			throw new Error("intervalMs must be greater than 0");
+		}
+
+		const now = Date.now();
+		const paceMs = Math.ceil(limit.intervalMs / limit.requests);
+
+		const state = getPacerState();
+		const existing = state.pacers[key];
+		const lastScheduledAtMs = existing?.lastScheduledAtMs ?? 0;
+
+		// Schedule at the later of: (last scheduled + pace) or now
+		const scheduledAtMs = Math.max(lastScheduledAtMs + paceMs, now);
+		const delayMs = scheduledAtMs - now;
+
+		// Update state with new scheduled timestamp
+		state.pacers[key] = { lastScheduledAtMs: scheduledAtMs };
+		setPacerState(state);
+
+		// Sleep if needed
+		if (delayMs > 0) {
+			await new Promise((resolve) => setTimeout(resolve, delayMs));
+		}
+	},
+};

package/src/pacer_internal.ts

@@ -0,0 +1,21 @@
+/**
+ * Internal pacer state helpers used by the runtime.
+ * @internal
+ */
+export type PacerEntry = {
+	lastScheduledAtMs: number;
+};
+
+export type PacerState = {
+	pacers: Record<string, PacerEntry>;
+};
+
+let pacerState: PacerState = { pacers: {} };
+
+export function setPacerState(state: PacerState): void {
+	pacerState = state;
+}
+
+export function getPacerState(): PacerState {
+	return pacerState;
+}

package/src/worker.ts

@@ -1,9 +1,10 @@
 import type {
 	AutomationCapability,
 	AutomationConfiguration,
-	AutomationContext,
+	AutomationEvent,
 } from "./capabilities/automation.js";
 import { createAutomationCapability } from "./capabilities/automation.js";
+import type { CapabilityContext } from "./capabilities/context.js";
 import type {
 	NotionManagedOAuthConfiguration,
 	OAuthCapability,
@@ -21,7 +22,8 @@ import type { JSONValue } from "./types.js";
 // Re-export types for convenience
 export type {
 	AutomationConfiguration,
-	AutomationContext,
+	AutomationEvent,
+	CapabilityContext,
 	OAuthConfiguration,
 	NotionManagedOAuthConfiguration,
 	UserManagedOAuthConfiguration,
@@ -120,7 +122,7 @@ export class Worker {
 	 *     },
 	 *     required: ["name"],
 	 *   },
-	 *   execute: ({ name }) => {
+	 *   execute: ({ name }, { notion }) => {
 	 *     return `Hello, ${name}!`;
 	 *   },
 	 * })
@@ -154,8 +156,8 @@ export class Worker {
 	 * worker.automation("sendWelcomeEmail", {
 	 *   title: "Send Welcome Email",
 	 *   description: "Sends a welcome email when a new user is added",
-	 *   execute: async (context) => {
-	 *     const { pageId, pageData } = context;
+	 *   execute: async (event, { notion }) => {
+	 *     const { pageId, pageData } = event;
 	 *
 	 *     // Access page properties from the Public API format
 	 *     if (pageData) {