@project-ajax/create 0.0.15 → 0.0.17

package/template/README.md

@@ -1,6 +1,8 @@
-# README
+# Notion Workers
 
-Use this repo to write extensions to enhance Notion. With Notion extensions, you can write JavaScript that syncs data into Notion collections, adds new slash-commands, or provides new actions to Custom Agents.
+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, or runs automation tasks.
 
 ## Prerequisites
 
@@ -8,80 +10,56 @@ Use this repo to write extensions to enhance Notion. With Notion extensions, you
 
 You need Node >= 22, npm >= 10 installed. (The repo will warn you if you don't.)
 
-### Access to the feature
-
-This feature is behind a feature flag (i.e. Statsig gate) in Notion.
-
-See a `#proj-ajax` team member to gain access.
-
 ## Quickstart
 
 In this Quickstart, you’ll:
 
-- Clone this extensions template
-- Publish example extensions to your Notion workspace
+- 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
 ```
 
-When prompted, enter a path to the new project, e.g. `my-extensions`.
+When prompted, enter a path to the new project, e.g. `my-worker`.
 
 ### 2. Install packages and connect the repo to Notion
 
 Install packages:
 
-```
+```shell
 # or whatever you chose for the pathname
-cd my-extensions && npm i
+cd my-worker && npm i
 ```
 
-Now, run `npx workers` to verify the tool has installed:
-
-```
-npx workers
+Now, connect the repo to Notion to publish the example worker to your Notion
+workspace:
 
-USAGE
-  workers auth login|show|logout ...
-  workers deploy [--config value] [--debug]
-  workers secrets set|list|rm ...
-  workers --help
-  workers --version
-
-A CLI for the Project Ajax platform
-
-[ ... ]
-```
-
-Then, connect the repo to Notion to publish the example extensions to your Notion workspace:
-
-```
+```shell
 # Connect to Notion Prod
 npx workers auth login
 # Connect to Notion Dev
 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:
+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
 ```
 
-> **Note**
->
-> If the command opens a page that 404s, you likely do not have Statsig access to extensions. See a #proj-virtual-databases team member for access.
-
 ### 3. Deploy
 
-Run the following command to deploy this repo's example extensions to your Notion workspace:
+Run the following command to deploy this repo's example workers to your Notion
+workspace:
 
-```
+```shell
 npx workers deploy
 
 Deploying worker...
@@ -98,15 +76,15 @@ The sample worker installs three capabilities:
 
 - [Synced database](#try-the-synced-database)
 - [Agent tool](#try-the-agent-tool)
-- [Slash command](#try-the-slash-command)
 
 #### 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".
+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:
 
-```
+```shell
 npx workers exec tasksSync
 ```
 
@@ -114,275 +92,63 @@ 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.
+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.
+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 slash command
-
-In your Notion workspace, **first refresh**. Then, type forward-slash (`/insert`) and select the "Insert Sample Task" capability:
-
-<img src="./docs/insert-sample-task.png" style="width:300px" />
-
-In the search field that appears, type `ajax` to preview matching sample tasks:
-
-<img src="./docs/select-ajax.png" style="width:400px" />
-
-After execution, the function will insert blocks into the page:
-
-<img src="./docs/inserted-blocks.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".
 
 ## How-to build your own
 
-### 1. Create repo from template
+Begin by using `npm init @project-ajax`, and then customize `index.ts` with
+capabilities you'd like to include in your worker.
 
-If you haven't already, use the GitHub CLI to create a new repo from this template:
+### Writing a sync function
 
-```
-gh repo create notion-extensions -p makenotion/project-ajax-template --private
-git clone git@github.com:[YOUR-USER]/notion-extensions my-extensions
-```
-
-Alternatively, you can click "Create from template" on the repo's page [on GitHub](https://github.com/makenotion/project-ajax-template).
-
-### 2. Install packages and connect the repo to Notion
-
-Install packages:
-
-```
-cd my-extensions && npm i
-```
-
-Then, connect the repo to Notion to publish the example extensions to your Notion workspace:
-
-```
-# Connect to Notion Prod
-npx workers auth login
-# Connect to Notion Dev
-npx workers auth login --env=dev
-```
-
-This command will open a new page with a command that includes a token. Run that command locally.
+[Sync functions](#sync) populate Notion collections with data from external
+sources.
 
-### 3. Write your extension(s)
+See the [sync example](./.examples/sync-example.ts) for a complete example.
 
-You can write three types of extensions: **slash commands**, **syncs**, and **tools**.
+### Writing a tool for custom agents
 
-#### Writing a slash command function
+[Tools](#tools) provide custom actions that can be invoked by custom agents in
+your Notion workspace.
 
-[Slash commands](#slash-commands) add custom `/` commands to your Notion workspace.
+See the [tool example](./.examples/tool-example.ts) for a complete example.
 
-Basic structure:
-
-```typescript
-import { slashCommand } from "@project-ajax/sdk/slashCommand";
-
-export const myCommand = slashCommand({
-  // Title in slash command menu
-  menuTitle: "My Command",
-  // Description in slash command menu
-  menuDescription: "Description shown in menu",
-  search: {
-    // Placeholder shown in search bar
-    placeholder: "Search...",
-    // Debounce when user types into the search bar, in milliseconds
-    debounce: 300,
-  },
-  // Called when the user enters a search query. Return results to show to user in search menu.
-  executeSearch: async (query: string) => {
-    // Return search results
-    return { items: [{ id: "1", title: "Result", description: "..." }] };
-  },
-  // Called when the user has selected a search item from the search menu.
-  executeSelect: async (id: string) => {
-    // Return Notion blocks to insert
-    return [
-      /* array of blocks */
-    ];
-  },
-});
-```
+## Secrets
 
-#### Writing a sync function
-
-[Sync functions](#sync) populate Notion collections with data from external sources.
-
-Basic structure:
-
-```typescript
-import { sync } from "@project-ajax/sdk/sync";
-import * as Schema from "@project-ajax/sdk/schema";
-import * as Builder from "@project-ajax/sdk/builder";
-
-export const mySync = sync({
-  // 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",
-    properties: {
-      // See `Schema` for the full list of possible column types.
-      Title: Schema.title(),
-      ID: Schema.richText(),
-    },
-  },
-  execute: async () => {
-    // Fetch and return data
-    return [
-      // Each object must match the shape of `properties` above.
-      {
-        key: "1",
-        properties: {
-          Title: Builder.title("Item 1"),
-          ID: Builder.richText("1"),
-        },
-      },
-    ];
-  },
-});
-```
-
-#### Writing a tool for custom agents
-
-[Tools](#tools) provide custom actions that can be invoked by custom agents in your Notion workspace.
-
-Basic structure:
-
-```typescript
-import { tool } from "@project-ajax/sdk";
-
-export const myTool = tool({
-  // Description of what this tool does - shown to the AI agent
-  description: "Search for items by keyword or ID",
-  // JSON Schema for the input the tool accepts
-  schema: {
-    type: "object",
-    properties: {
-      query: {
-        type: "string",
-        nullable: true,
-        description: "The search query"
-      },
-      limit: {
-        type: "number",
-        nullable: true,
-        description: "Maximum number of results"
-      },
-    },
-    required: [],
-    additionalProperties: false,
-  },
-  // Optional: JSON Schema for the output the tool returns
-  outputSchema: {
-    type: "object",
-    properties: {
-      results: {
-        type: "array",
-        items: { type: "string" },
-      },
-    },
-    required: ["results"],
-    additionalProperties: false,
-  },
-  // The function that executes when the tool is called
-  execute: async (input: { query?: string | null; limit?: number | null }) => {
-    // Destructure input with default values
-    const { query, limit = 10 } = input;
-    
-    // Perform your logic here
-    const results = await searchItems(query, limit);
-    
-    // Return data matching your outputSchema (if provided)
-    return { results };
-  },
-});
-```
-
-### 4. Deploy your function
-
-Deploy your functions to your Notion workspace with [**deploy**](#npx-workers-deploy):
-
-```bash
-npx workers deploy
-```
-
-This will build your worker bundle, upload it to Notion, and make your functions available in your workspace.
-
-### 5. Add 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.
+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
 ```
 
-Then, you can reference these secret values in your function code using `process.env`, e.g. `process.env.MY_SECRET_1`.
-
-### 6. Run your function
-
-For slash commands, you can test your function in the Notion workspace you deployed to.
-
-For sync commands, your function is run automatically in the background. You can also run it via the CLI with [`exec`](#npx-workers-exec):
-
-```
-npx workers exec nameOfSyncCapability
-```
-
-When the command has finished executing, you should see a collection in your Notion sidebar that contains the synced data.
-
-You can also test slash commands using [`exec`](#npx-workers-exec). Specify which function inside the slash command you want to run (i.e. `executeSearch` or `executeSelect`). Pass in arguments using `arg=value` syntax:
-
-```
-npx workers exec mySlashCommand executeSearch query="myquery"
-```
-
-## Extensions reference
-
-### Slash commands
-
-You can write an extension that adds a new **slash command** to a Notion workspace. The slash command currently supported is a "search-then-execute" flow.
-
-For example, you can write a slash command to insert a Linear ticket:
-
-1. First, after selecting your slash command, the user enters a search query for a particular Linear ticket:
-
-<img src="./docs/select-ajax.png" style="width:400px" />
+Then, you can reference these secret values in your function code using
+`process.env`, e.g. `process.env.MY_SECRET_1`.
 
-2. After they select a ticket from the list, your extension will insert blocks into the page.
-
-The search query is powered by `executeSearch` and the select action triggers `executeSelect`.
-
-#### Properties
-
-- **`menuTitle`** (string, required): The title that appears in the slash command menu when users type `/`.
-- **`menuDescription`** (string, required): A description of what the slash command does, shown in the menu.
-- **`search`** (object, required): Configuration for the search interface.
-  - **`placeholder`** (string, required): Placeholder text shown in the search field.
-  - **`debounce`** (number, required): Milliseconds to wait before executing search after user stops typing.
-- **`executeSearch`** (function, required): Async function that handles search queries.
-  - **Parameters**: `query` (string) - The user's search input.
-  - **Returns**: Promise resolving to an object with `items` array, where each item has:
-    - `id` (string): Unique identifier for the item.
-    - `title` (string): Title displayed in search results.
-    - `description` (string, optional): Additional description text.
-- **`executeSelect`** (function, required): Async function that handles when a user selects an item.
-  - **Parameters**: `id` (string) - The id of the selected item.
-  - **Returns**: Promise resolving to an array of Notion blocks to insert into the page.
+## Workers capabilities reference
 
 ### Sync
 
-The **sync** extension 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.
+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.
 
 At the moment, syncs do not run automatically. Use **`exec`** to run a sync.
 
@@ -400,9 +166,12 @@ At the moment, syncs do not run automatically. Use **`exec`** to run a sync.
 
 ### Tools
 
-The **tool** extension 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.
+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.
+Tools use JSON Schema to define their input and output structures, and the SDK
+validates data automatically.
 
 #### Properties
 
@@ -462,7 +231,7 @@ Your schemas should use standard JSON Schema format. Common patterns:
 
 You can test tools using [`exec`](#npx-workers-exec):
 
-```bash
+```shell
 # Execute a tool without arguments
 npx workers exec myTool
 
@@ -472,7 +241,9 @@ npx workers exec myTool
 
 ## 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.
+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
 
@@ -499,7 +270,7 @@ Login to the Project Ajax platform using a Workers API token.
 
 **Examples:**
 
-```bash
+```shell
 # Open browser to create a token
 npx workers auth login
 
@@ -516,7 +287,7 @@ Display the currently configured authentication token.
 
 **Example:**
 
-```bash
+```shell
 npx workers auth show
 ```
 
@@ -526,17 +297,18 @@ Remove the currently configured authentication token.
 
 **Example:**
 
-```bash
+```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.
+Deploy your worker to the Project Ajax platform. This command builds your worker
+bundle, uploads it to Notion, and saves the worker configuration.
 
 **Example:**
 
-```bash
+```shell
 npx workers deploy
 ```
 
@@ -553,14 +325,13 @@ Execute a worker capability with optional function and arguments.
 
 **Usage:**
 
-```bash
+```shell
 npx workers exec <capabilityName> [functionName] [arg1=value1 arg2=value2...]
 ```
 
 **Arguments:**
 
 - `capabilityName` (required): Name of the capability to execute
-- `functionName` (optional): For slash commands, specify which function to run (`executeSearch` or `executeSelect`)
 - `arguments` (optional): Key-value pairs as arguments. Supports both `key=value` and `key value` formats.
 
 **Flags:**
@@ -572,15 +343,9 @@ npx workers exec <capabilityName> [functionName] [arg1=value1 arg2=value2...]
 
 **Examples:**
 
-```bash
+```shell
 # Execute a sync capability
 npx workers exec tasksSync
-
-# Execute a slash command's search function
-npx workers exec taskSearch executeSearch query="ajax"
-
-# Execute with specific output mode
-npx workers exec taskSearch executeSearch query="test" --output=full
 ```
 
 ### `npx workers capabilities`
@@ -593,15 +358,17 @@ List all capabilities for the deployed worker.
 
 **Example:**
 
-```bash
+```shell
 npx workers capabilities list
 ```
 
-This will display all capabilities with their names and types (e.g., `sync`, `slashCommand`).
+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`.
+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>...]`
 
@@ -615,7 +382,7 @@ Set one or more secrets for your worker. Supports multiple formats:
 
 **Examples:**
 
-```bash
+```shell
 # Set a single secret
 npx workers secrets set API_KEY my-secret-value
 
@@ -631,11 +398,12 @@ npx workers secrets set API_KEY=my-key DATABASE_URL my-db-url
 
 #### `npx workers secrets list`
 
-List all secret keys for your worker. Note: Secret values are not displayed, only keys and creation timestamps.
+List all secret keys for your worker. Note: Secret values are not displayed,
+only keys and creation timestamps.
 
 **Example:**
 
-```bash
+```shell
 npx workers secrets list
 ```
 
@@ -649,35 +417,40 @@ Remove a secret from your worker.
 
 **Example:**
 
-```bash
+```shell
 npx workers secrets rm API_KEY
 ```
 
 ### `npx workers connect`
 
-Commands for managing OAuth connections that store provider tokens as worker secrets. Connections appear in your runtime as environment variables (e.g., `process.env.NOTION_OAUTH_GOOGLE`).
+Commands for managing OAuth connections that store provider tokens as worker
+secrets. Connections appear in your runtime as environment variables (e.g.,
+`process.env.NOTION_OAUTH_GOOGLE`).
 
 #### `npx workers connect providers`
 
 List the OAuth providers that are currently available for your workspace.
 
-```bash
+```shell
 npx workers connect providers
 ```
 
 #### `npx workers connect add <provider>`
 
-Start the OAuth flow in your browser for the specified provider. The command opens your default browser and also prints a fallback link.
+Start the OAuth flow in your browser for the specified provider. The command
+opens your default browser and also prints a fallback link.
 
-```bash
+```shell
 npx workers connect add google
 ```
 
 #### `npx workers connect list`
 
-Display all active OAuth connections for the deployed worker. The output includes the provider name, the environment variable exposed to your code, and when the connection was created.
+Display all active OAuth connections for the deployed worker. The output
+includes the provider name, the environment variable exposed to your code, and
+when the connection was created.
 
-```bash
+```shell
 npx workers connect list
 ```
 
@@ -685,13 +458,14 @@ npx workers connect list
 
 Remove an OAuth connection (and the stored tokens) for the specified provider.
 
-```bash
+```shell
 npx workers connect rm google
 ```
 
 ### Configuration file
 
-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:
+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:
 
 - **`environment`**: The current environment (`local`, `staging`, `dev`, or `prod`)
 - **`token`**: Your authentication token