@project-ajax/create 0.0.39 → 0.0.40-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/create",
-	"version": "0.0.39",
+	"version": "0.0.40-alpha.0",
 	"description": "Initialize a new Notion Workers extensions repo.",
 	"bin": {
 		"create-ajax": "dist/index.js"
@@ -31,10 +31,10 @@
 		"template/.gitignore"
 	],
 	"dependencies": {
-		"@inquirer/prompts": "^8.0.1",
-		"@project-ajax/shared": "*"
+		"@inquirer/prompts": "^8.0.1"
 	},
 	"devDependencies": {
+		"@project-ajax/shared": "*",
 		"@types/node": "^22.19.0",
 		"tsup": "^8.5.0",
 		"typescript": "^5.9.3",

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

@@ -1,3 +1,7 @@
+/**
+ * Automations are only available in a private alpha.
+ */
+
 import { Worker } from "@project-ajax/sdk";
 
 const worker = new Worker();
@@ -33,8 +37,8 @@ worker.automation("questionAnswerAutomation", {
 			emailValue = emailProperty.rich_text.map((rt) => rt.plain_text).join("");
 		}
 
-		// Handle empty email
-		if (!emailValue) {
+		// Handle empty email or pageId
+		if (!emailValue || !pageId) {
 			return;
 		}
 

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

@@ -17,6 +17,7 @@ export default worker;
 
 // Option 1: Notion-managed provider (recommended when available).
 // Notion owns the OAuth app credentials and the backend has pre-configured provider settings.
+// Notion-managed providers are only available in a private alpha.
 const googleAuth = worker.oauth("googleAuth", {
 	name: "google-calendar",
 	provider: "google",
@@ -24,6 +25,7 @@ const googleAuth = worker.oauth("googleAuth", {
 
 // Option 2: User-managed provider (you own the OAuth app credentials).
 // Keep client credentials in worker secrets and read them from `process.env`.
+// Generally available.
 const myCustomAuth = worker.oauth("myCustomAuth", {
 	name: "my-custom-provider",
 	authorizationEndpoint: "https://provider.example.com/oauth/authorize",

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

@@ -1,3 +1,7 @@
+/**
+ * Syncs are only available in a private alpha.
+ */
+
 import { Worker } from "@project-ajax/sdk";
 import * as Builder from "@project-ajax/sdk/builder";
 import * as Schema from "@project-ajax/sdk/schema";

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

@@ -1,3 +1,7 @@
+/**
+ * Tools are generally available.
+ */
+
 import { Worker } from "@project-ajax/sdk";
 
 const worker = new Worker();

package/template/AGENTS.alpha.md

@@ -0,0 +1,209 @@
+# 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)
+
+**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", {
+				// Optionally configure a two-way relation. This will automatically create the
+				// "Tasks" property on the project synced database: there is no need
+				// to configure "Tasks" on the projectSync capability.
+				twoWay: true, relatedPropertyName: "Tasks"
+			}),
+		},
+	},
+
+	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.
+- `npx workers pack`: create a tarball; uses Git when available (respects `.gitignore`), always skips `node_modules`, `dist`, `workers.json`, `workers.*.json`, `.env`, and `.env.*`, and works in non-git repos.
+
+## Debugging & Monitoring Runs
+Use `npx workers runs` to inspect run history and logs.
+
+**List recent runs:**
+```shell
+npx workers runs list
+```
+
+**Get logs for a specific run:**
+```shell
+npx workers runs logs <runId>
+```
+
+**Get logs for the latest run (any capability):**
+```shell
+npx workers runs list --plain | head -n1 | cut -f1 | xargs npx workers runs logs
+```
+
+**Get logs for the latest run of a specific capability:**
+```shell
+npx workers runs list --plain | grep tasksSync | head -n1 | cut -f1 | xargs npx workers runs logs
+```
+
+The `--plain` flag outputs tab-separated values without formatting, making it easy to pipe to other commands.
+
+## 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/AGENTS.md

@@ -6,161 +6,58 @@
 - 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`).
+`@project-ajax/sdk` provides `Worker`, schema helpers, and builders; `@project-ajax/cli` powers `npx workers ...`.
+
+### Agent tool calls
 
 ```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}`,
+	execute: ({ name }, _context) => `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`).
+A worker with one or more tools is attachable to Notion agents. Each `tool` becomes a callable function for the agent:
+- `title` and `description` are used both in the Notion UI as well as a helpful description to your agent.
+- `schema` specifies what data the agent must supply.
 
-### Sync
-#### Strategy and Pagination
+### OAuth
 
-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)
-
-**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,
-		};
+const myOAuth = worker.oauth("myOAuth", {
+	name: "my-provider",
+	authorizationEndpoint: "https://provider.example.com/oauth/authorize",
+	tokenEndpoint: "https://provider.example.com/oauth/token",
+	scope: "read write",
+	clientId: "1234567890",
+	clientSecret: process.env.MY_CUSTOM_OAUTH_CLIENT_SECRET ?? "",
+	authorizationParams: {
+		access_type: "offline",
+		prompt: "consent",
 	},
 });
 ```
 
-#### Relations
-
-Two syncs can relate to one another using `Schema.relation(relatedSyncKey)` and `Builder.relation(primaryKey)` entries inside an array.
+The OAuth capability allows you to perform the three legged OAuth flow after specifying paramteres of your OAuth client: `name`, `authorizationEndpoint`, `tokenEndpoint`, `clientId`, `clientSecret`, and `scope` (optional: `authorizationParams`, `callbackUrl`, `accessTokenExpireMs`).
 
-```ts
-worker.sync("projectsSync", {
-	primaryKeyProperty: "Project ID",
-	...
-});
+### Other capabilities
 
-// Example sync worker that syncs sample tasks to a database
-worker.sync("tasksSync", {
-	primaryKeyProperty: "Task ID",
-	...
-	schema: {
-		...
-		properties: {
-			...
-			Project: Schema.relation("projectsSync", {
-				// Optionally configure a two-way relation. This will automatically create the
-				// "Tasks" property on the project synced database: there is no need
-				// to configure "Tasks" on the projectSync capability.
-				twoWay: true, relatedPropertyName: "Tasks"
-			}),
-		},
-	},
+There are additional capability types in the SDK but these are restricted to a private alpha. Only Agent tools and OAuth are generally available.
 
-	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,
-		};
-	},
-});
-```
+| Capability | Availability |
+|------------|--------------|
+| Agent tools | Generally available |
+| OAuth (user-managed) | Generally available |
+| OAuth (Notion-managed) | Private alpha |
+| Syncs | Private alpha |
+| Automations | Private alpha |
 
 ## Build, Test, and Development Commands
 - Node >= 22 and npm >= 10.9.2 (see `package.json` engines).
@@ -169,7 +66,7 @@ worker.sync("tasksSync", {
 - `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.
+- `npx workers exec <capability>`: run a sync or tool. Run after `deploy`.
 - `npx workers pack`: create a tarball; uses Git when available (respects `.gitignore`), always skips `node_modules`, `dist`, `workers.json`, `workers.*.json`, `.env`, and `.env.*`, and works in non-git repos.
 
 ## Debugging & Monitoring Runs

package/template/CLAUDE.md

@@ -6,161 +6,58 @@
 - 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`).
+`@project-ajax/sdk` provides `Worker`, schema helpers, and builders; `@project-ajax/cli` powers `npx workers ...`.
+
+### Agent tool calls
 
 ```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}`,
+	execute: ({ name }, _context) => `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`).
+A worker with one or more tools is attachable to Notion agents. Each `tool` becomes a callable function for the agent:
+- `title` and `description` are used both in the Notion UI as well as a helpful description to your agent.
+- `schema` specifies what data the agent must supply.
 
-### Sync
-#### Strategy and Pagination
+### OAuth
 
-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)
-
-**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,
-		};
+const myOAuth = worker.oauth("myOAuth", {
+	name: "my-provider",
+	authorizationEndpoint: "https://provider.example.com/oauth/authorize",
+	tokenEndpoint: "https://provider.example.com/oauth/token",
+	scope: "read write",
+	clientId: "1234567890",
+	clientSecret: process.env.MY_CUSTOM_OAUTH_CLIENT_SECRET ?? "",
+	authorizationParams: {
+		access_type: "offline",
+		prompt: "consent",
 	},
 });
 ```
 
-#### Relations
-
-Two syncs can relate to one another using `Schema.relation(relatedSyncKey)` and `Builder.relation(primaryKey)` entries inside an array.
+The OAuth capability allows you to perform the three legged OAuth flow after specifying paramteres of your OAuth client: `name`, `authorizationEndpoint`, `tokenEndpoint`, `clientId`, `clientSecret`, and `scope` (optional: `authorizationParams`, `callbackUrl`, `accessTokenExpireMs`).
 
-```ts
-worker.sync("projectsSync", {
-	primaryKeyProperty: "Project ID",
-	...
-});
+### Other capabilities
 
-// Example sync worker that syncs sample tasks to a database
-worker.sync("tasksSync", {
-	primaryKeyProperty: "Task ID",
-	...
-	schema: {
-		...
-		properties: {
-			...
-			Project: Schema.relation("projectsSync", {
-				// Optionally configure a two-way relation. This will automatically create the
-				// "Tasks" property on the project synced database: there is no need
-				// to configure "Tasks" on the projectSync capability.
-				twoWay: true, relatedPropertyName: "Tasks"
-			}),
-		},
-	},
+There are additional capability types in the SDK but these are restricted to a private alpha. Only Agent tools and OAuth are generally available.
 
-	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,
-		};
-	},
-});
-```
+| Capability | Availability |
+|------------|--------------|
+| Agent tools | Generally available |
+| OAuth (user-managed) | Generally available |
+| OAuth (Notion-managed) | Private alpha |
+| Syncs | Private alpha |
+| Automations | Private alpha |
 
 ## Build, Test, and Development Commands
 - Node >= 22 and npm >= 10.9.2 (see `package.json` engines).
@@ -169,7 +66,7 @@ worker.sync("tasksSync", {
 - `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.
+- `npx workers exec <capability>`: run a sync or tool. Run after `deploy`.
 - `npx workers pack`: create a tarball; uses Git when available (respects `.gitignore`), always skips `node_modules`, `dist`, `workers.json`, `workers.*.json`, `.env`, and `.env.*`, and works in non-git repos.
 
 ## Debugging & Monitoring Runs

package/template/src/index.ts

@@ -1,258 +1,25 @@
 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;
 
-const projectId = "project-123";
-const projectName = "Project 1";
+type HelloInput = { name: string };
 
-// Sample data for demonstration
-const sampleTasks = [
-	{
-		id: "task-1",
-		title: "Welcome to Notion Workers",
-		status: "Completed",
-		description: "This is a simple hello world example",
-		projectId,
-	},
-	{
-		id: "task-2",
-		title: "Build your first worker",
-		status: "In Progress",
-		description: "Create a sync or tool worker",
-		projectId,
-	},
-	{
-		id: "task-3",
-		title: "Deploy to production",
-		status: "Todo",
-		description: "Share your worker with your team",
-		projectId,
-	},
-];
-
-worker.sync("projectsSync", {
-	primaryKeyProperty: "Project ID",
-	schema: {
-		defaultName: "Projects",
-		databaseIcon: Builder.notionIcon("activity"),
-		properties: {
-			"Project Name": Schema.title(),
-			"Project ID": Schema.richText(),
-		},
-	},
-	execute: async () => {
-		return {
-			changes: [
-				{
-					type: "upsert" as const,
-					key: projectId,
-					icon: Builder.notionIcon("activity"),
-					properties: {
-						"Project Name": Builder.title(projectName),
-						"Project ID": Builder.richText(projectId),
-					},
-				},
-			],
-			hasMore: false,
-		};
-	},
-});
-
-// Example sync worker that syncs sample tasks to a database
-worker.sync("tasksSync", {
-	primaryKeyProperty: "Task ID",
-
-	// Optional: How often the sync should run. Defaults to "continuous".
-	// Use intervals like "30m", "1h", "1d" (min: 1m, max: 7d)
-	schedule: "5m",
-
-	// Sync mode:
-	// - "replace": Each sync cycle returns the complete dataset. After hasMore:false,
-	//              pages not seen in this sync run are deleted.
-	// - "incremental": Each sync cycle returns a subset of the complete dataset. Use delete markers
-	//                  (e.g., { type: "delete", key: "task-1" }) to remove pages.
-	// Defaults to "replace".
-	// mode: "replace",
-
-	schema: {
-		defaultName: "Sample Tasks",
-		databaseIcon: Builder.notionIcon("checklist"),
-		properties: {
-			"Ticket Title": Schema.title(),
-			"Task ID": Schema.richText(),
-			Description: Schema.richText(),
-			Status: Schema.select([
-				{ name: "Completed", color: "green" },
-				{ name: "In Progress", color: "blue" },
-				{ name: "Todo", color: "default" },
-			]),
-			Project: Schema.relation("projectsSync", {
-				twoWay: true,
-				relatedPropertyName: "Tasks",
-			}),
-		},
-	},
-
-	execute: async (_state, { notion: _notion }) => {
-		const emojiForStatus = (status: string) => {
-			switch (status) {
-				case "Completed":
-					return Builder.notionIcon("checkmark", "green");
-				case "In Progress":
-					return Builder.notionIcon("arrow-right", "blue");
-				case "Todo":
-					return Builder.notionIcon("clock", "lightgray");
-				default:
-					return Builder.notionIcon("question-mark", "lightgray");
-			}
-		};
-		// Return sample tasks as database entries
-		const changes = sampleTasks.map((task) => ({
-			type: "upsert" as const,
-			key: task.id,
-			icon: emojiForStatus(task.status),
-			properties: {
-				"Ticket Title": Builder.title(task.title),
-				"Task ID": Builder.richText(task.id),
-				Description: Builder.richText(task.description),
-				Status: Builder.select(task.status),
-				Project: [Builder.relation(projectId)],
-			},
-			pageContentMarkdown: `## ${task.title}\n\n${task.description}`,
-		}));
-
-		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 nextState.
-			hasMore: false,
-			// 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.).
-			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<TaskSearchInput, TaskSearchOutput>("taskSearchTool", {
-	title: "Task Search",
-	description:
-		"Look up sample tasks by ID or keyword. Helpful for demonstrating agent tool calls.",
+// Example agent tool that returns a greeting
+// Delete this when you're ready to start building your own tools.
+worker.tool<HelloInput, string>("sayHello", {
+	title: "Say Hello",
+	description: "Returns a friendly greeting for the given name.",
 	schema: {
 		type: "object",
 		properties: {
-			taskId: {
+			name: {
 				type: "string",
-				nullable: true,
-				description: "Return a single task that matches the given task ID.",
-			},
-			query: {
-				type: "string",
-				nullable: true,
-				description:
-					"Match search terms against words in the task title or description.",
+				description: "The name to greet.",
 			},
 		},
-		required: [],
+		required: ["name"],
 		additionalProperties: false,
 	},
-	execute: async (input: TaskSearchInput, { notion: _notion }) => {
-		const { taskId, query } = input;
-
-		let matchingTasks = sampleTasks;
-
-		if (taskId) {
-			matchingTasks = sampleTasks.filter((task) => task.id === taskId);
-		} else if (query) {
-			const normalizedQuery = query.trim().toLowerCase();
-
-			const terms = normalizedQuery.split(/\s+/).filter(Boolean);
-
-			if (terms.length > 0) {
-				const scoredTasks = sampleTasks
-					.map((task) => {
-						const title = task.title.toLowerCase();
-						const description = task.description.toLowerCase();
-						const matches = terms.reduce((count, term) => {
-							return title.includes(term) || description.includes(term)
-								? count + 1
-								: count;
-						}, 0);
-
-						return { task, matches };
-					})
-					.filter(({ matches }) => matches > 0)
-					.sort((a, b) => b.matches - a.matches);
-
-				matchingTasks = scoredTasks.map(({ task }) => task);
-			} else {
-				matchingTasks = [];
-			}
-		}
-
-		return {
-			count: matchingTasks.length,
-			tasks: matchingTasks.map((task) => ({
-				id: task.id,
-				title: task.title,
-				status: task.status,
-				description: task.description,
-			})),
-		} satisfies TaskSearchOutput;
-	},
-});
-
-// Example automation that runs when triggered from a database automation
-worker.automation("completeTaskAutomation", {
-	title: "Mark Task Complete",
-	description: "Automatically marks a task as complete when triggered",
-	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.
-
-		console.log(`Automation triggered for page: ${pageId}`);
-		console.log(`Action type: ${actionType}`);
-
-		if (pageData) {
-			// Access all page properties directly
-			console.log("Page properties:", pageData.properties);
-
-			// Example: Access specific properties by their name
-			// const taskName = pageData.properties.Name;
-			// const status = pageData.properties.Status;
-			// const assignee = pageData.properties.Assignee;
-
-			// The properties are in Notion's Public API format
-			// See: https://developers.notion.com/reference/property-value-object
-		}
-
-		// In a real implementation, you would:
-		// 1. Use the page properties to determine what action to take
-		// 2. Update the task status in your system
-		// 3. Call external APIs, send notifications, etc.
-
-		// Example: You could call an external API, update a database, send notifications, etc.
-		// For this demo, we just log the execution
-		console.log("Task marked as complete!");
-	},
+	execute: ({ name }) => `Hello, ${name}!`,
 });