@project-ajax/sdk 0.0.75 → 0.0.76

package/dist/capabilities/sync.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -118,13 +119,13 @@ export type SyncConfiguration<PK extends string, S extends Schema<PK>, State = u
     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;
     /**
@@ -153,6 +154,8 @@ type RuntimeContext<UserContext = unknown> = {
     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.
@@ -174,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":"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"}

package/dist/capabilities/sync.js

@@ -1,4 +1,8 @@
 import { ExecutionError, unreachable } from "../error.js";
+import {
+  getPacerState,
+  setPacerState
+} from "../pacer_internal.js";
 import { createCapabilityContext } from "./context.js";
 function createSyncCapability(key, syncConfiguration) {
   return {
@@ -13,13 +17,19 @@ function createSyncCapability(key, syncConfiguration) {
     async handler(runtimeContext) {
       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.nextState
+        nextUserContext: executionResult.nextState,
+        nextPacerState: updatedPacerState.pacers
       };
       process.stdout.write(`
 <output>${JSON.stringify(result)}</output>
@@ -33,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/index.d.ts

@@ -4,6 +4,7 @@ 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,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,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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/sdk",
-	"version": "0.0.75",
+	"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": {

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,
@@ -156,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;
 
@@ -197,6 +203,8 @@ type RuntimeContext<UserContext = unknown> = {
 	state?: UserContext;
 	/** Legacy field for user-defined/-controlled state. */
 	userContext?: UserContext;
+	/** Pacer state from the server for rate limiting. */
+	pacers?: Record<string, PacerEntry>;
 };
 
 /**
@@ -223,16 +231,27 @@ export function createSyncCapability<
 		async handler(runtimeContext?: RuntimeContext<Context>) {
 			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(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.nextState,
+				nextPacerState: updatedPacerState.pacers,
 			};
 
 			process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
@@ -249,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/index.ts

@@ -22,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;
+}