@project-ajax/create 0.0.30 → 0.0.32

package/README.md

@@ -25,6 +25,4 @@ npm init @project-ajax -- --directory my-worker --project my-worker
 
 ### Scheduling
 
-Generated sync workers default to `continuous`, meaning the sync runs continuously/as fast as possible. To slow cadence, set `schedule` in `src/index.ts` to an interval like `30m`, `1h`, or `1d` (min `1m`, max `7d`), which runs the sync once per interval.
-
-This can be useful for minding rate limits.
+Sync workers default to running every 30 minutes. To change the cadence, set `schedule` in `src/index.ts` to an interval like `15m`, `1h`, or `1d` (min `1m`, max `7d`), or `continuous` to run as fast as possible.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/create",
-	"version": "0.0.30",
+	"version": "0.0.32",
 	"description": "Initialize a new Notion Project Ajax extensions repo.",
 	"bin": {
 		"create-ajax": "dist/index.js"

package/template/.examples/automation-example.ts

@@ -1,14 +1,8 @@
-import { Client } from "@notionhq/client";
 import { Worker } from "@project-ajax/sdk";
 
 const worker = new Worker();
 export default worker;
 
-// Initialize the Notion client with OAuth token from environment
-const notion = new Client({
-	auth: process.env.NOTION_API_TOKEN,
-});
-
 type RichTextProperty = {
 	type: "rich_text";
 	rich_text: Array<{ plain_text: string }>;
@@ -26,7 +20,8 @@ worker.automation("questionAnswerAutomation", {
 	title: "Question Answer Automation",
 	description:
 		"Reads questions from database pages and updates them with answers",
-	execute: async ({ pageId, pageData }) => {
+	execute: async (event, { notion }) => {
+		const { pageId, pageData } = event;
 		// Extract email from the page dat
 		const emailProperty = pageData?.properties?.Email as
 			| RichTextProperty

package/template/.examples/sync-example.ts

@@ -54,7 +54,7 @@ worker.sync("mySync", {
 			Project: Schema.relation("projectsSync"),
 		},
 	},
-	execute: async () => {
+	execute: async (_state, { notion: _notion }) => {
 		// Fetch and return data
 		return {
 			changes: [

package/template/.examples/tool-example.ts

@@ -41,7 +41,7 @@ worker.tool<
 		additionalProperties: false,
 	},
 	// The function that executes when the tool is called
-	execute: async (input) => {
+	execute: async (input, { notion: _notion }) => {
 		// Destructure input with default values
 		const { query: _query, limit: _limit = 10 } = input;
 

package/template/AGENTS.md

@@ -20,7 +20,7 @@ export default worker;
 worker.sync("tasksSync", {
   primaryKeyProperty: "ID",
   schema: { defaultName: "Tasks", properties: { Name: Schema.title(), ID: Schema.richText() } },
-  execute: async () => ({
+  execute: async (_state, { notion }) => ({
     changes: [{ type: "upsert", key: "1", properties: { Name: Builder.title("Write docs"), ID: Builder.richText("1") } }],
     hasMore: false,
   }),
@@ -30,37 +30,40 @@ worker.tool("sayHello", {
   title: "Say Hello",
   description: "Return a greeting",
   schema: { type: "object", properties: { name: { type: "string" } }, required: ["name"], additionalProperties: false },
-  execute: ({ name }) => `Hello, ${name}`,
+  execute: ({ name }, { notion }) => `Hello, ${name}`,
 });
 
 worker.automation("sendWelcomeEmail", {
   title: "Send Welcome Email",
   description: "Runs from a database automation",
-  execute: async () => {},
+  execute: async (event, { notion }) => {},
 });
 
 worker.oauth("googleAuth", { name: "my-google-auth", provider: "google" });
 ```
 
+- All `execute` handlers receive a Notion SDK client in the second argument as `context.notion`.
+
 - For user-managed OAuth, supply `name`, `authorizationEndpoint`, `tokenEndpoint`, `clientId`, `clientSecret`, and `scope` (optional: `authorizationParams`, `callbackUrl`, `accessTokenExpireMs`).
 
 ### Sync
 #### Strategy and Pagination
 
-Syncs run in a "sync cycle": a back-to-back chain of `execute` calls that starts at a scheduled trigger and ends when an execution returns `hasMore: false`.
+Syncs run in a "sync cycle": a back-to-back chain of `execute` calls that starts at a scheduled trigger and ends when an execution returns `hasMore: false`. By default, syncs run every 30 minutes. Set `schedule` to an interval like `"15m"`, `"1h"`, `"1d"` (min `"1m"`, max `"7d"`), or `"continuous"` to run as fast as possible.
 
 - Always use pagination, when available. Returning too many changes in one execution will fail. Start with batch sizes of ~100 changes.
 - `mode=replace` is simpler, and fine for smaller syncs (<10k)
 - Use `mode=incremental` when the sync could return a lot of data (>10k), eg for SaaS tools like Salesforce or Stripe
 - When using `mode=incremental`, emit delete markers as needed if easy to do (below)
+- Use `Pacer.wait` to respect upstream rate limits during `execute` calls; pick a stable key per API or endpoint.
 
 **Sync strategy (`mode`):**
 - `replace`: each sync cycle must return the full dataset. After the final `hasMore: false`, any records not seen during that cycle are deleted.
 - `incremental`: each sync cycle returns a subset of the full dataset (usually the changes since the last run). Deletions must be explicit via `{ type: "delete", key: "..." }`. Records not mentioned are left unchanged.
 
 **How pagination works:**
-1. Return a batch of changes with `hasMore: true` and a `nextContext` value
-2. The runtime calls `execute` again with that context
+1. Return a batch of changes with `hasMore: true` and a `nextState` value
+2. The runtime calls `execute` again with that state
 3. Continue until you return `hasMore: false`
 
 **Example replace sync:**
@@ -70,8 +73,8 @@ worker.sync("paginatedSync", {
   mode: "replace",
   primaryKeyProperty: "ID",
   schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
-  execute: async (context?: { page: number }) => {
-    const page = context?.page ?? 1;
+  execute: async (state, { notion }) => {
+    const page = state?.page ?? 1;
     const pageSize = 100;
     const { items, hasMore } = await fetchPage(page, pageSize);
     return {
@@ -81,13 +84,13 @@ worker.sync("paginatedSync", {
         properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
       })),
       hasMore,
-      nextContext: hasMore ? { page: page + 1 } : undefined,
+      nextState: hasMore ? { page: page + 1 } : undefined,
     };
   },
 });
 ```
 
-**Context types:** The `nextContext` can be any serializable value—a cursor string, page number, timestamp, or complex object. Type your execute function's context parameter to match.
+**State types:** The `nextState` can be any serializable value—a cursor string, page number, timestamp, or complex object. Type your execute function's `state` to match.
 
 **Incremental example (changes only, with deletes):**
 ```ts
@@ -95,8 +98,8 @@ worker.sync("incrementalSync", {
   primaryKeyProperty: "ID",
   mode: "incremental",
   schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
-  execute: async (context?: { cursor?: string }) => {
-    const { upserts, deletes, nextCursor } = await fetchChanges(context?.cursor);
+  execute: async (state, { notion }) => {
+    const { upserts, deletes, nextCursor } = await fetchChanges(state?.cursor);
     return {
       changes: [
         ...upserts.map((item) => ({
@@ -107,7 +110,7 @@ worker.sync("incrementalSync", {
         ...deletes.map((id) => ({ type: "delete", key: id })),
       ],
       hasMore: Boolean(nextCursor),
-      nextContext: nextCursor ? { cursor: nextCursor } : undefined,
+      nextState: nextCursor ? { cursor: nextCursor } : undefined,
     };
   },
 });

package/template/CLAUDE.md

@@ -0,0 +1,179 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/index.ts` defines the worker and capabilities.
+- `.examples/` has focused samples (sync, tool, automation, OAuth).
+- Generated: `dist/` build output, `workers.json` CLI config.
+
+## Worker & Capability API (SDK)
+- `@project-ajax/sdk` provides `Worker`, schema helpers, and builders; `@project-ajax/cli` powers `npx workers ...`.
+- Capability keys are unique strings used by the CLI (e.g., `npx workers exec tasksSync`).
+
+```ts
+import { Worker } from "@project-ajax/sdk";
+import * as Builder from "@project-ajax/sdk/builder";
+import * as Schema from "@project-ajax/sdk/schema";
+
+const worker = new Worker();
+export default worker;
+
+worker.sync("tasksSync", {
+  primaryKeyProperty: "ID",
+  schema: { defaultName: "Tasks", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (_state, { notion }) => ({
+    changes: [{ type: "upsert", key: "1", properties: { Name: Builder.title("Write docs"), ID: Builder.richText("1") } }],
+    hasMore: false,
+  }),
+});
+
+worker.tool("sayHello", {
+  title: "Say Hello",
+  description: "Return a greeting",
+  schema: { type: "object", properties: { name: { type: "string" } }, required: ["name"], additionalProperties: false },
+  execute: ({ name }, { notion }) => `Hello, ${name}`,
+});
+
+worker.automation("sendWelcomeEmail", {
+  title: "Send Welcome Email",
+  description: "Runs from a database automation",
+  execute: async (event, { notion }) => {},
+});
+
+worker.oauth("googleAuth", { name: "my-google-auth", provider: "google" });
+```
+
+- All `execute` handlers receive a Notion SDK client in the second argument as `context.notion`.
+
+- For user-managed OAuth, supply `name`, `authorizationEndpoint`, `tokenEndpoint`, `clientId`, `clientSecret`, and `scope` (optional: `authorizationParams`, `callbackUrl`, `accessTokenExpireMs`).
+
+### Sync
+#### Strategy and Pagination
+
+Syncs run in a "sync cycle": a back-to-back chain of `execute` calls that starts at a scheduled trigger and ends when an execution returns `hasMore: false`. By default, syncs run every 30 minutes. Set `schedule` to an interval like `"15m"`, `"1h"`, `"1d"` (min `"1m"`, max `"7d"`), or `"continuous"` to run as fast as possible.
+
+- Always use pagination, when available. Returning too many changes in one execution will fail. Start with batch sizes of ~100 changes.
+- `mode=replace` is simpler, and fine for smaller syncs (<10k)
+- Use `mode=incremental` when the sync could return a lot of data (>10k), eg for SaaS tools like Salesforce or Stripe
+- When using `mode=incremental`, emit delete markers as needed if easy to do (below)
+- Use `Pacer.wait` to respect upstream rate limits during `execute` calls; pick a stable key per API or endpoint.
+
+**Sync strategy (`mode`):**
+- `replace`: each sync cycle must return the full dataset. After the final `hasMore: false`, any records not seen during that cycle are deleted.
+- `incremental`: each sync cycle returns a subset of the full dataset (usually the changes since the last run). Deletions must be explicit via `{ type: "delete", key: "..." }`. Records not mentioned are left unchanged.
+
+**How pagination works:**
+1. Return a batch of changes with `hasMore: true` and a `nextState` value
+2. The runtime calls `execute` again with that state
+3. Continue until you return `hasMore: false`
+
+**Example replace sync:**
+
+```ts
+worker.sync("paginatedSync", {
+  mode: "replace",
+  primaryKeyProperty: "ID",
+  schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (state, { notion }) => {
+    const page = state?.page ?? 1;
+    const pageSize = 100;
+    const { items, hasMore } = await fetchPage(page, pageSize);
+    return {
+      changes: items.map((item) => ({
+        type: "upsert",
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      hasMore,
+      nextState: hasMore ? { page: page + 1 } : undefined,
+    };
+  },
+});
+```
+
+**State types:** The `nextState` can be any serializable value—a cursor string, page number, timestamp, or complex object. Type your execute function's `state` to match.
+
+**Incremental example (changes only, with deletes):**
+```ts
+worker.sync("incrementalSync", {
+  primaryKeyProperty: "ID",
+  mode: "incremental",
+  schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (state, { notion }) => {
+    const { upserts, deletes, nextCursor } = await fetchChanges(state?.cursor);
+    return {
+      changes: [
+        ...upserts.map((item) => ({
+          type: "upsert",
+          key: item.id,
+          properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+        })),
+        ...deletes.map((id) => ({ type: "delete", key: id })),
+      ],
+      hasMore: Boolean(nextCursor),
+      nextState: nextCursor ? { cursor: nextCursor } : undefined,
+    };
+  },
+});
+```
+
+#### Relations
+
+Two syncs can relate to one another using `Schema.relation(relatedSyncKey)` and `Builder.relation(primaryKey)` entries inside an array.
+
+```ts
+worker.sync("projectsSync", {
+	primaryKeyProperty: "Project ID",
+  ...
+});
+
+// Example sync worker that syncs sample tasks to a database
+worker.sync("tasksSync", {
+	primaryKeyProperty: "Task ID",
+  ...
+	schema: {
+    ...
+		properties: {
+      ...
+			Project: Schema.relation("projectsSync"),
+		},
+	},
+
+	execute: async () => {
+		// Return sample tasks as database entries
+    const tasks = fetchTasks()
+		const changes = tasks.map((task) => ({
+			type: "upsert" as const,
+			key: task.id,
+			properties: {
+        ...
+				Project: [Builder.relation(task.projectId)],
+			},
+		}));
+
+		return {
+			changes,
+			hasMore: false,
+		};
+	},
+});
+```
+
+## Build, Test, and Development Commands
+- Node >= 22 and npm >= 10.9.2 (see `package.json` engines).
+- `npm run dev`: run `src/index.ts` with live reload.
+- `npm run build`: compile TypeScript to `dist/`.
+- `npm run check`: type-check only (no emit).
+- `npx workers auth login [--env=dev]`: connect to a Notion workspace.
+- `npx workers deploy`: build and publish capabilities.
+- `npx workers exec <capability>`: run a sync or tool.
+
+## Coding Style & Naming Conventions
+- TypeScript with `strict` enabled; keep types explicit when shaping I/O.
+- Use tabs for indentation; capability keys in lowerCamelCase.
+
+## Testing Guidelines
+- No test runner configured; validate with `npm run check` and a deploy/exec loop.
+
+## Commit & Pull Request Guidelines
+- Messages typically use `feat(scope): ...`, `TASK-123: ...`, or version bumps.
+- PRs should describe changes, list commands run, and update examples if behavior changes.

package/template/README.md

@@ -13,7 +13,7 @@ single `Worker` instance.
 ## Quickstart
 
 ```shell
-npm init @project-ajax
+npm init @project-ajax@latest
 # choose a folder, then:
 cd my-worker
 npm install
@@ -37,7 +37,7 @@ npx workers exec tasksSync
 
 - Worker: The Node/TypeScript program you deploy, defined in `src/index.ts`.
 - Capability: A named sync, tool, automation, or OAuth definition registered on a worker.
-- Secret: A key/value stored with `npx workers secrets`, exposed as environment variables (for example, `process.env.SECRET_NAME`).
+- Secret: A key/value stored with `npx workers secrets`, exposed as environment variables (for example, `process.env.SECRET_NAME`). Use `KEY=VALUE` pairs when setting secrets.
 
 ## Build a Worker
 
@@ -73,7 +73,8 @@ worker.sync("tasksSync", {
       ID: Schema.richText(),
     },
   },
-  execute: async () => ({
+  execute: async (_state, { notion }) => ({
+    // `notion` is the Notion API SDK client.
     changes: [
       {
         type: "upsert",
@@ -95,15 +96,15 @@ Notion will delete stale rows after each run. A stale row is a row that was in t
 
 When your sync is pulling in many rows of data (>1k), you'll want to use pagination. Breaking down pages to ~100 is a good starting point.
 
-You can use **context** to persist things like pagination tokens between `execute` runs. Notion passes `context` as the first argument to `execute`. Return `nextContext` to set the `context` for the next run:
+You can use `state` to persist things like pagination tokens between `execute` runs. Notion passes `state` as the first argument to `execute`, plus a `context` object that includes the Notion client at `context.notion`. Return `nextState` to set the `state` for the next run:
 
 ```ts
 worker.sync("fullSync", {
   primaryKeyProperty: "ID",
   mode: "replace",
   schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
-  execute: async (context?: { page: number }) => {
-    const { items , nextCursor } = await fetchPage(context?.page);
+  execute: async (state, { notion }) => {
+    const { items , nextCursor } = await fetchPage(state?.page);
     return {
       changes: items.map((item) => ({
         type: "upsert",
@@ -111,13 +112,13 @@ worker.sync("fullSync", {
         properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
       })),
       hasMore: nextCursor ? true : false,
-      nextCursor
+      nextState: nextCursor ? { cursor: nextCursor } : undefined,
     };
   },
 });
 ```
 
-Return `hasMore=false` for each run until you reach the end. On the last run, return `hasMore=true`. At the start of the next cycle, Notion will start anew and call `execute` with `context=null`.
+Return `hasMore=false` for each run until you reach the end. On the last run, return `hasMore=true`. At the start of the next cycle, Notion will start anew and call `execute` with `state` undefined.
 
 #### Write a sync that syncs incrementally
 
@@ -130,8 +131,8 @@ worker.sync("incrementalSync", {
   primaryKeyProperty: "ID",
   mode: "incremental",
   schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
-  execute: async (context?: { cursor?: string }) => {
-    const { upserts, deletes, nextCursor } = await fetchChanges(context?.cursor);
+  execute: async (state, { notion }) => {
+    const { upserts, deletes, nextCursor } = await fetchChanges(state?.cursor);
     return {
       changes: [
         ...upserts.map((item) => ({
@@ -142,13 +143,13 @@ worker.sync("incrementalSync", {
         ...deletes.map((id) => ({ type: "delete", key: id })),
       ],
       hasMore: Boolean(nextCursor),
-      nextContext: nextCursor ? { cursor: nextCursor } : undefined,
+      nextState: nextCursor ? { cursor: nextCursor } : undefined,
     };
   },
 });
 ```
 
-Unlike the `replace` sync mode, Notion will not drop "stale" rows and `context` will persist between sync cycles.
+Unlike the `replace` sync mode, Notion will not drop "stale" rows and `state` will persist between sync cycles.
 
 **Deletes**
 
@@ -170,6 +171,33 @@ changes: [
 ]
 ```
 
+#### Respect rate limits
+
+
+If the source API has a rate limit, call `Pacer.wait` inside `execute` to pace requests (for example, 10 requests per minute):
+
+```ts
+import { Pacer } from "@project-ajax/sdk/pacer";
+
+worker.sync("tasksSync", {
+  primaryKeyProperty: "ID",
+  schema: { defaultName: "Tasks", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async () => {
+    const oneMinute = 60 * 1000;
+    await Pacer.wait("tasks-api", { requests: 10, intervalMs: oneMinute });
+    const items = await fetchTasks();
+    return {
+      changes: items.map((item) => ({
+        type: "upsert",
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      hasMore: false,
+    };
+  },
+});
+```
+
 ### Tool
 
 Tools are callable by Notion custom agents.
@@ -184,7 +212,7 @@ worker.tool("sayHello", {
     required: ["name"],
     additionalProperties: false,
   },
-  execute: ({ name }) => `Hello, ${name}`,
+  execute: ({ name }, { notion }) => `Hello, ${name}`,
 });
 ```
 
@@ -196,7 +224,8 @@ Automations run from Notion database buttons or automations.
 worker.automation("sendWelcomeEmail", {
   title: "Send Welcome Email",
   description: "Runs from a database automation",
-  execute: async ({ pageId }) => {
+  execute: async (event, { notion }) => {
+    const { pageId } = event;
     console.log("Triggered for page", pageId);
   },
 });
@@ -297,6 +326,12 @@ Store secrets for runtime access:
 npx workers secrets set API_KEY=my-secret
 ```
 
+You can pass multiple secrets and quote values that contain spaces or `=`:
+
+```shell
+npx workers secrets set FOO=bar BAZ="qux" ASDF="x=y" GREETING="hello world"
+```
+
 ### `npx workers secrets list`
 List secret keys:
 

package/template/src/index.ts

@@ -93,7 +93,7 @@ worker.sync("tasksSync", {
 		},
 	},
 
-	execute: async () => {
+	execute: async (_state, { notion: _notion }) => {
 		const emojiForStatus = (status: string) => {
 			switch (status) {
 				case "Completed":
@@ -124,17 +124,33 @@ worker.sync("tasksSync", {
 		return {
 			// List of changes to apply to the Notion database.
 			changes,
-			// Indicates whether there is more data to fetch this sync cycle. If true, the runtime will call `execute` again with the nextContext.
+			// Indicates whether there is more data to fetch this sync cycle. If true, the runtime will call `execute` again with the nextState.
 			hasMore: false,
-			// Optional context data Notion will pass back in the next execution.
+			// Optional state data Notion will pass back as `state`
+			// in the next execution.
 			// This can be any type of data (cursor, page number, timestamp, etc.).
-			nextContext: undefined,
+			nextState: undefined,
 		};
 	},
 });
 
+type TaskSearchInput = {
+	taskId?: string | null;
+	query?: string | null;
+};
+
+type TaskSearchOutput = {
+	count: number;
+	tasks: {
+		id: string;
+		title: string;
+		status: string;
+		description: string;
+	}[];
+};
+
 // Example agent tool for retrieving task information
-worker.tool("taskSearchTool", {
+worker.tool<TaskSearchInput, TaskSearchOutput>("taskSearchTool", {
 	title: "Task Search",
 	description:
 		"Look up sample tasks by ID or keyword. Helpful for demonstrating agent tool calls.",
@@ -156,7 +172,7 @@ worker.tool("taskSearchTool", {
 		required: [],
 		additionalProperties: false,
 	},
-	execute: async (input: { taskId?: string | null; query?: string | null }) => {
+	execute: async (input: TaskSearchInput, { notion: _notion }) => {
 		const { taskId, query } = input;
 
 		let matchingTasks = sampleTasks;
@@ -198,7 +214,7 @@ worker.tool("taskSearchTool", {
 				status: task.status,
 				description: task.description,
 			})),
-		};
+		} satisfies TaskSearchOutput;
 	},
 });
 
@@ -206,7 +222,8 @@ worker.tool("taskSearchTool", {
 worker.automation("completeTaskAutomation", {
 	title: "Mark Task Complete",
 	description: "Automatically marks a task as complete when triggered",
-	execute: async ({ pageId, actionType, pageData }) => {
+	execute: async (event, { notion: _notion }) => {
+		const { pageId, actionType, pageData } = event;
 		// The pageData parameter contains the full page object from Notion's Public API
 		// with all the database properties already encoded and ready to use.