@project-ajax/create 0.0.25 → 0.0.27

package/package.json

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

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

@@ -1,5 +1,8 @@
 import { Client } from "@notionhq/client";
-import { automation } from "@project-ajax/sdk";
+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({
@@ -19,7 +22,7 @@ type RichTextProperty = {
  * 2. Processes it (calls an API, performs logic, etc.)
  * 3. Updates the page with the answer
  */
-export const questionAnswerAutomation = automation({
+worker.automation("questionAnswerAutomation", {
 	title: "Question Answer Automation",
 	description:
 		"Reads questions from database pages and updates them with answers",

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

@@ -1,4 +1,7 @@
-import { oauth } from "@project-ajax/sdk";
+import { Worker } from "@project-ajax/sdk";
+
+const worker = new Worker();
+export default worker;
 
 /**
  * OAuth capabilities let your worker access third-party APIs.
@@ -7,38 +10,66 @@ import { oauth } from "@project-ajax/sdk";
  *
  *   npx workers oauth start <capabilityKey>
  *
- * Where `capabilityKey` is the OAuth capability’s key (see `npx workers capabilities list`).
+ * Where `capabilityKey` is the OAuth capability's key (see `npx workers capabilities list`).
  * Once OAuth completes, the worker runtime exposes the access token via an
  * environment variable and `accessToken()` reads it for you.
  */
 
 // Option 1: Notion-managed provider (recommended when available).
 // Notion owns the OAuth app credentials and the backend has pre-configured provider settings.
-export const googleAuth = oauth({
+const googleAuth = worker.oauth("googleAuth", {
 	name: "google-calendar",
 	provider: "google",
 });
 
 // Option 2: User-managed provider (you own the OAuth app credentials).
 // Keep client credentials in worker secrets and read them from `process.env`.
-export const myCustomAuth = oauth({
+const myCustomAuth = worker.oauth("myCustomAuth", {
 	name: "my-custom-provider",
 	authorizationEndpoint: "https://provider.example.com/oauth/authorize",
 	tokenEndpoint: "https://provider.example.com/oauth/token",
 	scope: "read write",
-	clientId: requireEnv("MY_CUSTOM_OAUTH_CLIENT_ID"),
-	clientSecret: requireEnv("MY_CUSTOM_OAUTH_CLIENT_SECRET"),
+	clientId: "1234567890",
+	clientSecret: process.env.MY_CUSTOM_OAUTH_CLIENT_SECRET ?? "",
 	authorizationParams: {
 		access_type: "offline",
 		prompt: "consent",
 	},
 });
 
-function requireEnv(key: string): string {
-	const value = process.env[key];
-	if (value) {
-		return value;
-	}
+// Use the OAuth handles in your capabilities
+worker.sync("googleCalendarSync", {
+	primaryKeyProperty: "eventId",
+	schema: {
+		defaultName: "Calendar Events",
+		properties: {
+			eventId: { type: "text" },
+			title: { type: "title" },
+		},
+	},
+	execute: async () => {
+		// Get the OAuth access token
+		const token = await googleAuth.accessToken();
+
+		// Use token to fetch from Google Calendar API
+		console.log("Using Google token:", `${token.slice(0, 10)}...`);
 
-	throw new Error(`Missing environment variable "${key}"`);
-}
+		return { objects: [], done: true };
+	},
+});
+
+worker.tool("customApiTool", {
+	title: "Custom API Tool",
+	description: "Calls a custom API using OAuth",
+	schema: {
+		type: "object",
+		properties: {},
+		required: [],
+		additionalProperties: false,
+	},
+	execute: async () => {
+		const token = await myCustomAuth.accessToken();
+		console.log("Using custom provider token:", `${token.slice(0, 10)}...`);
+		return { success: true };
+	},
+});

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

@@ -1,14 +1,17 @@
+import { Worker } from "@project-ajax/sdk";
 import * as Builder from "@project-ajax/sdk/builder";
 import * as Schema from "@project-ajax/sdk/schema";
-import { sync } from "@project-ajax/sdk/sync";
 
-export const mySync = sync({
+const worker = new Worker();
+export default worker;
+
+worker.sync("mySync", {
 	// Which field to use in each object as the primary key. Must be unique.
 	primaryKeyProperty: "ID",
 	// The schema of the collection to create in Notion.
 	schema: {
 		// Name of the collection to create in Notion.
-		dataSourceTitle: "My Data",
+		defaultName: "My Data",
 		properties: {
 			// See `Schema` for the full list of possible column types.
 			Title: Schema.title(),

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

@@ -1,9 +1,12 @@
-import { tool } from "@project-ajax/sdk";
+import { Worker } from "@project-ajax/sdk";
 
-export const myTool = tool<
+const worker = new Worker();
+export default worker;
+
+worker.tool<
 	{ query?: string | null; limit?: number | null },
 	{ results: string[] }
->({
+>("myTool", {
 	title: "My Tool",
 	// Description of what this tool does - shown to the AI agent
 	description: "Search for items by keyword or ID",

package/template/AGENTS.md

@@ -0,0 +1,104 @@
+# 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 (context?: { cursor?: string }) => {
+    const pageSize = 100;
+    const { items, nextCursor } = await fetchItems({ cursor: context?.cursor, limit: pageSize });
+    return {
+      objects: items.map((item) => ({
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      done: !nextCursor,
+      nextContext: nextCursor ? { cursor: nextCursor } : undefined,
+    };
+  },
+});
+
+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}`,
+});
+
+worker.automation("sendWelcomeEmail", {
+  title: "Send Welcome Email",
+  description: "Runs from a database automation",
+  execute: async () => {},
+});
+
+worker.oauth("googleAuth", { name: "my-google-auth", provider: "google" });
+```
+
+- For user-managed OAuth, supply `name`, `authorizationEndpoint`, `tokenEndpoint`, `clientId`, `clientSecret`, and `scope` (optional: `authorizationParams`, `callbackUrl`, `accessTokenExpireMs`).
+
+### Sync Pagination
+
+Implement pagination in syncs to avoid exceeding maximum output size limits. Returning too many objects in a single execution can cause the output JSON to exceed size limits and fail.
+
+**How pagination works:**
+1. Return a batch of objects with `done: false` and a `nextContext` value
+2. The runtime calls `execute` again with that context
+3. Continue until you return `done: true`
+
+```ts
+worker.sync("paginatedSync", {
+  primaryKeyProperty: "ID",
+  schema: { defaultName: "Records", properties: { Name: Schema.title(), ID: Schema.richText() } },
+  execute: async (context?: { page: number }) => {
+    const page = context?.page ?? 1;
+    const pageSize = 100;
+    const { items, hasMore } = await fetchPage(page, pageSize);
+    return {
+      objects: items.map((item) => ({
+        key: item.id,
+        properties: { Name: Builder.title(item.name), ID: Builder.richText(item.id) },
+      })),
+      done: !hasMore,
+      nextContext: 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.
+
+## 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

@@ -1,510 +1,261 @@
-# Notion Workers
+# Notion Worker
 
-Use this repo to write workers to enhance Notion. With Notion Workers, you can
-write JavaScript that syncs data into Notion collections, provides tools to
-Custom Agents, and powers database automations.
+A worker is a small Node/TypeScript program hosted by Notion
+that registers capabilities (third-party data syncs, custom agent tools, custom
+automations) to extend Notion. The worker lives in `src/index.ts` and exports a
+single `Worker` instance.
 
 ## Prerequisites
 
-### Node
-
-You need Node >= 22, npm >= 10 installed. (The repo will warn you if you don't.)
+- Node >= 22
+- npm >= 10
 
 ## Quickstart
 
-In this Quickstart, you’ll:
-
-- Create a new project using this template
-- Publish the example worker to your Notion workspace
-
-### 1. Create worker project from template
-
-Use `npm init` to setup a project template:
-
 ```shell
 npm init @project-ajax
+# choose a folder, then:
+cd my-worker
+npm install
 ```
 
-When prompted, enter a path to the new project, e.g. `my-worker`.
-
-### 2. Install packages and connect the repo to Notion
-
-Install packages:
+Connect to a Notion workspace and deploy the sample worker:
 
 ```shell
-# or whatever you chose for the pathname
-cd my-worker && npm i
-```
-
-Now, connect the repo to Notion to publish the example worker to your Notion
-workspace:
-
-```shell
-# Connect to Notion Prod
 npx workers auth login
-# Connect to Notion Dev
+# or target a specific environment:
 npx workers auth login --env=dev
-```
-
-This command will open a new page with a command that includes a token. Run that
-command locally. It will look like this:
-
-```shell
-# example
-npx workers auth login v1.user.wAFygwEZ-[...] --env=dev
-```
-
-### 3. Deploy
-
-Run the following command to deploy this repo's example workers to your Notion
-workspace:
-
-```shell
 npx workers deploy
-
-Deploying worker...
-Updating worker...
-Building worker bundle...
-Uploading bundle...
-Fetching and saving worker capabilities...
-✓ Successfully deployed worker
 ```
 
-### 4. Try out the sample worker
-
-The sample worker installs three capabilities:
-
-- [Synced database](#try-the-synced-database)
-- [Agent tool](#try-the-agent-tool)
-- [Automation](#try-the-automation)
-
-#### Try the synced database
-
-After deploying, the sync runs automatically and creates a database in your
-private pages - you can find it in your sidebar or by searching "Sample Tasks".
-
-Alternatively, run the sync via the CLI to get the URL:
+Run the sample sync to create a database:
 
 ```shell
 npx workers exec tasksSync
 ```
 
-When the command completes you will see the URL for the `Sample Tasks` database.
-
-#### Try the agent tool
-
-To exercise the sample agent tool, first navigate to a new or existing custom
-agent in Notion.
-
-On the settings tab, choose Add connection:
-
-<img src="./docs/custom-agent-add-connection.png" style="width:400px">
-
-Scroll down to find the installed worker which has the name used when you
-deployed the worker. Click Add.
-
-<img src="./docs/custom-agent-select-worker.png" style="width:400px">
-
-Save settings, then navigate to the **chat** tab. Our sample tool call allows
-for searching tasks by id or keyword - try asking Agent to find tasks related to
-"Ajax" or "worker".
-
-#### Try the automation
+## Glossary
 
-Add a column to your Sample Tasks synced database with type Button. Modify the button automation to `Run Worker` and then choose your worker and the `Mark Task Complete` automation.
+- 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`).
 
-Once configured, click the button.
+## Build a Worker
 
-You will see `Button automation ran successfully`.
+Create the worker instance and export it. Register capabilities on the same
+instance:
 
-The automation only prints to console. To see the logs:
-1. Navigate to the `Workers` tab
-2. Select your worker
-3. In `Recent runs` click `automation:completeTaskAutomation`
+```ts
+import { Worker } from "@project-ajax/sdk";
 
-## How-to build your own
-
-Begin by using `npm init @project-ajax`, and then customize `index.ts` with
-capabilities you'd like to include in your worker.
-
-### Writing a sync function
-
-[Sync functions](#sync) populate Notion collections with data from external
-sources.
-
-See the [sync example](./.examples/sync-example.ts) for a complete example.
-
-### Writing a tool for custom agents
-
-[Tools](#tools) provide custom actions that can be invoked by custom agents in
-your Notion workspace.
-
-See the [tool example](./.examples/tool-example.ts) for a complete example.
-
-### Writing an automation
-
-[Automations](#automations) provide custom actions that can be triggered from
-database automations in your Notion workspace.
-
-See the [automation example](./.examples/automation-example.ts) for a complete example.
-
-## Secrets
-
-Your function might require sensitive values, like API tokens, to run. You can
-add [**secrets**](#npx-workers-secrets) to your function's run context. Secrets
-are exposed to your function as environment variables.
-
-Run the following to add secrets:
-
-```shell
-npx workers secrets set MY_SECRET_1=my-secret-value MY_SECRET_2=my-secret-value2
+const worker = new Worker();
+export default worker;
 ```
 
-Then, you can reference these secret values in your function code using
-`process.env`, e.g. `process.env.MY_SECRET_1`.
-
-## Workers capabilities reference
-
 ### Sync
 
-The **sync** capabilityh allows you to sync any data to a Notion collection. Every
-time a sync is run, data is upserted or deleted from the target Notion
-collection so that the collection matches the source.
+Syncs create or update a Notion database from your source data.
 
-At the moment, syncs do not run automatically. Use **`exec`** to run a sync.
+```ts
+import * as Builder from "@project-ajax/sdk/builder";
+import * as Schema from "@project-ajax/sdk/schema";
 
-#### Properties
+const worker = new Worker();
+export default worker;
 
-- **`primaryKeyProperty`** (string, required): The name of the property that serves as the unique identifier for each entry in the collection (e.g. `"id"`). This property must also be defined in the schema.
-- **`schema`** (object, required): Defines the structure of the Notion collection.
-  - **`defaultName`** (string, required): The default name for the database when it is first created in Notion. The database will be a new private page. Changing this property after the database has been created will not update the database name.
-  - **`properties`** (object, required): An object mapping property names to their schema definitions. Use functions from `@project-ajax/sdk/schema` to define property types (e.g., `Schema.title()`, `Schema.richText()`).
-- **`execute`** (function, required): Async function that fetches and returns data to sync.
-  - **Parameters**: None (but can access `process.env` for secrets).
-  - **Returns**: Promise resolving to an array of entries, where each entry has:
-    - `key` (string): Unique identifier for the entry (maps to the `primaryKeyProperty`).
-    - `properties` (object): An object mapping property names to their values. Use functions from `@project-ajax/sdk/builder` to construct property values (e.g., `Builder.title()`, `Builder.richText()`).
-
-### Tools
-
-The **tool** capability allows custom agents in your Notion workspace to perform
-actions. When you connect a worker to a custom agent, the agent can invoke your
-tools based on their descriptions and schemas.
-
-Tools use JSON Schema to define their input and output structures, and the SDK
-validates data automatically.
-
-#### Properties
-
-- **`description`** (string, required): A clear description of what the tool does. This is shown to the AI agent to help it decide when to use the tool.
-- **`schema`** (JSONSchemaType, required): JSON Schema definition for the tool's input parameters. The input will be validated against this schema before execution.
-- **`outputSchema`** (JSONSchemaType, optional): JSON Schema definition for the tool's output. If provided, the output will be validated against this schema after execution.
-- **`execute`** (function, required): Async function that performs the tool's action.
-  - **Parameters**: `input` (typed according to your schema) - The validated input parameters.
-  - **Returns**: Promise resolving to output data (validated against `outputSchema` if provided).
-
-#### Error handling
-
-The tool system automatically handles three types of errors:
-
-- **`InvalidToolInputError`**: Thrown when input doesn't match the input schema.
-- **`InvalidToolOutputError`**: Thrown when output doesn't match the output schema (if provided).
-- **`ToolExecutionError`**: Thrown when the execute function throws an error.
-
-All errors are automatically caught and returned in a structured format, so you don't need to handle them in your `execute` function.
-
-#### JSON Schema types
-
-Your schemas should use standard JSON Schema format. Common patterns:
-
-**Object with required and optional properties:**
-```typescript
-{
-  type: "object",
-  properties: {
-    name: { type: "string" },
-    age: { type: "number", nullable: true },
-    active: { type: "boolean", nullable: true },
+worker.sync("tasksSync", {
+  primaryKeyProperty: "ID",
+  schema: {
+    defaultName: "Tasks",
+    properties: {
+      Name: Schema.title(),
+      ID: Schema.richText(),
+    },
   },
-  // Only 'name' is required; age and active can be omitted
-  required: ["name"],
-  additionalProperties: false,
-}
-```
-
-**Arrays:**
-```typescript
-{
-  type: "array",
-  items: { type: "string" },
-}
-```
-
-**Enums:**
-```typescript
-{
-  type: "string",
-  enum: ["option1", "option2", "option3"],
-}
+  execute: async () => ({
+    objects: [
+      {
+        key: "1",
+        properties: {
+          Name: Builder.title("Write docs"),
+          ID: Builder.richText("1"),
+        },
+      },
+    ],
+    done: true,
+  }),
+});
 ```
 
-#### Testing tools
+### Tool
 
-You can test tools using [`exec`](#npx-workers-exec):
+Tools are callable by Notion custom agents.
 
-```shell
-# Execute a tool without arguments
-npx workers exec myTool
-
-# Note: Currently, tools cannot accept arguments via CLI due to parser limitations.
-# To test tools with specific inputs, use them with a custom agent in Notion.
+```ts
+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}`,
+});
 ```
 
-### Automations
-
-The **automation** capability allows you to create custom actions that can be
-triggered from database automations in your Notion workspace. When you create a
-database automation and select "Run worker" as an action, you can choose from
-your deployed automation capabilities.
-
-#### Properties
+### Automation
 
-- **`title`** (string, required): The name of the automation shown in the UI when selecting automations.
-- **`description`** (string, required): A brief description of what this automation does.
-- **`execute`** (function, required): Async function that runs when the automation is triggered.
-  - **Parameters**: `context` (AutomationContext) - Context about the trigger, including:
-    - `actionType` (string): The type of automation action
-    - `pageId` (string, optional): ID of the page that triggered the automation
-    - `pageData` (object, optional): Full page object from Notion's Public API, including all properties
-  - **Returns**: Promise that resolves when the automation completes.
+Automations run from Notion database buttons or automations.
 
-#### Example
-
-```typescript
-automation({
+```ts
+worker.automation("sendWelcomeEmail", {
   title: "Send Welcome Email",
-  description: "Sends a welcome email when a user is added",
-  execute: async ({ pageData }) => {
-    if (pageData) {
-      const email = pageData.properties.Email;
-      await sendEmail(email);
-    }
+  description: "Runs from a database automation",
+  execute: async ({ pageId }) => {
+    console.log("Triggered for page", pageId);
   },
-})
+});
 ```
 
-## CLI reference
-
-The `workers` CLI provides commands to authenticate, deploy, execute, and manage
-your Notion functions. All commands support global flags for configuration and
-debugging.
-
-### Global flags
-
-These flags are available on all commands:
+### OAuth
 
-- **`--config <path>`**: Path to the config file to use (defaults to `workers.json`)
-- **`--debug`**: Enable debug logging
+OAuth capabilities let your worker access third-party APIs.
 
-### `npx workers auth`
+```ts
+// Notion-managed provider
+worker.oauth("googleAuth", { name: "my-google-auth", provider: "google" });
 
-Commands for managing authentication with the Project Ajax platform.
-
-#### `npx workers auth login [token] [--env=<env>]`
-
-Login to the Project Ajax platform using a Workers API token.
-
-**Arguments:**
+// User-managed provider
+worker.oauth("acmeAuth", {
+  name: "acme-oauth",
+  authorizationEndpoint: "https://provider.example.com/oauth/authorize",
+  tokenEndpoint: "https://provider.example.com/oauth/token",
+  scope: "read write",
+  clientId: "YOUR_CLIENT_ID",
+  clientSecret: "YOUR_CLIENT_SECRET",
+});
+```
 
-- `token` (optional): A Workers API token. If not provided, opens a browser to create one.
+## Local Development
 
-**Flags:**
+```shell
+npm run dev   # watch and run src/index.ts
+npm run check # type-check
+npm run build # emit dist/
+```
 
-- `--env` (optional): The environment to use (`local`, `staging`, `dev`, or `prod`). Defaults to `prod`.
+## Workers CLI Commands
 
-**Examples:**
+### `npx workers auth login`
+Log in to Notion (use `--env=dev` for dev):
 
 ```shell
-# Open browser to create a token
-npx workers auth login
-
-# Login with an existing token
-npx workers auth login v1.user.wAFygwEZ-...
-
-# Login to dev environment
 npx workers auth login --env=dev
 ```
 
-#### `npx workers auth show`
-
-Display the currently configured authentication token.
-
-**Example:**
+### `npx workers auth show`
+Show the active auth token:
 
 ```shell
 npx workers auth show
 ```
 
-#### `npx workers auth logout`
-
-Remove the currently configured authentication token.
-
-**Example:**
+### `npx workers auth logout`
+Clear the stored auth token:
 
 ```shell
 npx workers auth logout
 ```
 
 ### `npx workers deploy`
-
-Deploy your worker to the Project Ajax platform. This command builds your worker
-bundle, uploads it to Notion, and saves the worker configuration.
-
-**Example:**
+Build and upload your worker bundle:
 
 ```shell
 npx workers deploy
 ```
 
-The deploy command will:
-
-1. Build your worker bundle from the current directory
-2. Upload the bundle to Notion
-3. Fetch and save worker capabilities
-4. Store the worker ID in your config file
-
 ### `npx workers exec`
-
-Execute a worker capability with optional function and arguments.
-
-**Usage:**
-
-```shell
-npx workers exec <capabilityName> [functionName] [arg1=value1 arg2=value2...]
-```
-
-**Arguments:**
-
-- `capabilityName` (required): Name of the capability to execute
-- `arguments` (optional): Key-value pairs as arguments. Supports both `key=value` and `key value` formats.
-
-**Flags:**
-
-- `--output <mode>`: Output mode for results. Options:
-  - `none`: No output
-  - `full`: Complete output
-  - `pager`: Paginate long output (default)
-
-**Examples:**
+Run a sync or tool capability:
 
 ```shell
-# Execute a sync capability
 npx workers exec tasksSync
 ```
 
-### `npx workers capabilities`
-
-Commands for managing worker capabilities.
-
-#### `npx workers capabilities list`
-
-List all capabilities for the deployed worker.
-
-**Example:**
+### `npx workers capabilities list`
+List deployed capabilities:
 
 ```shell
 npx workers capabilities list
 ```
 
-This will display all capabilities with their names and types (e.g., `sync`,
-`tool`).
-
-### `npx workers secrets`
-
-Commands for managing worker secrets. Secrets are exposed to your functions as
-environment variables via `process.env`.
-
-#### `npx workers secrets set <key> <value> [<key2> <value2>...]`
-
-Set one or more secrets for your worker. Supports multiple formats:
-
-**Formats:**
-
-- Space-separated: `key value`
-- Equals-separated: `key=value`
-- Colon-separated: `key:value`
-
-**Examples:**
+### `npx workers capabilities enable`
+Enable a sync capability:
 
 ```shell
-# Set a single secret
-npx workers secrets set API_KEY my-secret-value
-
-# Set multiple secrets (space-separated)
-npx workers secrets set API_KEY my-key API_SECRET my-secret
+npx workers capabilities enable tasksSync
+```
 
-# Set multiple secrets (equals format)
-npx workers secrets set API_KEY=my-key API_SECRET=my-secret
+### `npx workers capabilities disable`
+Disable a sync capability:
 
-# Mix formats
-npx workers secrets set API_KEY=my-key DATABASE_URL my-db-url
+```shell
+npx workers capabilities disable tasksSync
 ```
 
-#### `npx workers secrets list`
+### `npx workers secrets set`
+Store secrets for runtime access:
 
-List all secret keys for your worker. Note: Secret values are not displayed,
-only keys and creation timestamps.
+```shell
+npx workers secrets set API_KEY=my-secret
+```
 
-**Example:**
+### `npx workers secrets list`
+List secret keys:
 
 ```shell
 npx workers secrets list
 ```
 
-#### `npx workers secrets rm <key>`
-
-Remove a secret from your worker.
-
-**Arguments:**
-
-- `key` (required): The secret key name to remove
-
-**Example:**
+### `npx workers secrets rm`
+Remove a secret:
 
 ```shell
 npx workers secrets rm API_KEY
 ```
 
-### `npx workers oauth`
+### `npx workers oauth start`
+Start an OAuth flow for a capability:
 
-Commands for managing OAuth flows for your worker.
+```shell
+npx workers oauth start googleAuth
+```
 
-#### `npx workers oauth start [capabilityKey]`
+### `npx workers env pull`
+Write remote env vars to a local `.env` file:
 
-Start an OAuth flow for an OAuth capability in your worker. The command opens
-your browser and prints a fallback link if it can’t open automatically.
+```shell
+npx workers env pull .env
+```
 
-If `capabilityKey` is omitted, the CLI will list OAuth capabilities for your
-deployed worker and prompt you to select one (TTY only). In non-interactive
-contexts, pass the key explicitly.
+### `npx workers runs list`
+List recent runs:
 
 ```shell
-# Start OAuth (interactive picker if capabilityKey is omitted)
-npx workers oauth start
-
-# Start OAuth for a specific OAuth capability
-npx workers oauth start <capabilityKey>
+npx workers runs list
 ```
 
-See the [OAuth example](./.examples/oauth-example.ts) for a complete example.
-
-### Configuration file
+### `npx workers runs logs`
+Fetch logs for a run:
 
-The CLI stores configuration in a `workers.json` file in your project directory.
-This file is automatically created and updated by the CLI commands. It contains:
+```shell
+npx workers runs logs <runId>
+```
 
-- **`environment`**: The current environment (`local`, `staging`, `dev`, or `prod`)
-- **`token`**: Your authentication token
-- **`workerId`**: The ID of your deployed worker
+### `npx workers bundle download`
+Download the deployed bundle:
 
-You can specify a different config file using the `--config` flag on any command.
+```shell
+npx workers bundle download
+```

package/template/src/index.ts

@@ -1,7 +1,10 @@
-import { automation, sync, tool } from "@project-ajax/sdk";
+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;
+
 // Sample data for demonstration
 const sampleTasks = [
 	{
@@ -25,7 +28,7 @@ const sampleTasks = [
 ];
 
 // Example sync worker that syncs sample tasks to a database
-export const tasksSync = sync({
+worker.sync("tasksSync", {
 	primaryKeyProperty: "Task ID",
 
 	// Optional: How often the sync should run. Defaults to "continuous".
@@ -85,7 +88,7 @@ export const tasksSync = sync({
 });
 
 // Example agent tool for retrieving task information
-export const taskSearchTool = tool({
+worker.tool("taskSearchTool", {
 	title: "Task Search",
 	description:
 		"Look up sample tasks by ID or keyword. Helpful for demonstrating agent tool calls.",
@@ -154,7 +157,7 @@ export const taskSearchTool = tool({
 });
 
 // Example automation that runs when triggered from a database automation
-export const completeTaskAutomation = automation({
+worker.automation("completeTaskAutomation", {
 	title: "Mark Task Complete",
 	description: "Automatically marks a task as complete when triggered",
 	execute: async ({ pageId, actionType, pageData }) => {