@project-ajax/sdk 0.0.68 → 0.0.69

package/dist/worker.js

@@ -0,0 +1,218 @@
+import { createAutomationCapability } from "./capabilities/automation.js";
+import { createOAuthCapability } from "./capabilities/oauth.js";
+import { createSyncCapability } from "./capabilities/sync.js";
+import { createToolCapability } from "./capabilities/tool.js";
+class Worker {
+  #capabilities = /* @__PURE__ */ new Map();
+  /**
+   * Register a sync capability.
+   *
+   * Example:
+   *
+   * ```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: "Task ID",
+   *   schema: {
+   *     defaultName: "Tasks",
+   *     properties: {
+   *       "Task Name": Schema.title(),
+   *       "Task ID": Schema.richText(),
+   *       Status: Schema.select([
+   *         { name: "Open", color: "default" },
+   *         { name: "Done", color: "green" },
+   *       ]),
+   *     },
+   *   },
+   *   execute: async () => {
+   *     const objects = [
+   *       {
+   *         key: "task-1",
+   *         properties: {
+   *           "Task Name": Builder.title("Write docs"),
+   *           "Task ID": Builder.richText("task-1"),
+   *           Status: Builder.select("Open"),
+   *         },
+   *       },
+   *     ];
+   *
+   *     return { objects, done: true };
+   *   },
+   * });
+   * ```
+   *
+   * @param key - The unique key for this capability.
+   * @param config - The sync configuration.
+   * @returns The capability object.
+   */
+  sync(key, config) {
+    this.#validateUniqueKey(key);
+    const capability = createSyncCapability(key, config);
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
+  /**
+   * Register a tool capability.
+   *
+   * Example:
+   *
+   * ```ts
+   * worker.tool<{ name: string }, string>("sayHello", {
+   *   title: "Say Hello",
+   *   description: "Say hello to the user",
+   *   schema: {
+   *     type: "object",
+   *     properties: {
+   *       name: { type: "string" },
+   *     },
+   *     required: ["name"],
+   *   },
+   *   execute: ({ name }) => {
+   *     return `Hello, ${name}!`;
+   *   },
+   * })
+   * ```
+   *
+   *
+   * @param key - The unique key for this capability.
+   * @param config - The tool configuration.
+   * @returns The capability object.
+   */
+  tool(key, config) {
+    this.#validateUniqueKey(key);
+    const capability = createToolCapability(key, config);
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
+  /**
+   * Register an automation capability.
+   *
+   * Example:
+   *
+   * ```ts
+   * const worker = new Worker();
+   * export default worker;
+   *
+   * worker.automation("sendWelcomeEmail", {
+   *   title: "Send Welcome Email",
+   *   description: "Sends a welcome email when a new user is added",
+   *   execute: async (context) => {
+   *     const { pageId, pageData } = context;
+   *
+   *     // Access page properties from the Public API format
+   *     if (pageData) {
+   *       const name = pageData.properties.Name; // Access any property
+   *       const status = pageData.properties.Status;
+   *       console.log(`Processing: ${name}`);
+   *     }
+   *
+   *     // Your automation logic here
+   *     await sendEmail(pageId);
+   *   },
+   * })
+   * ```
+   *
+   * @param key - The unique key for this capability.
+   * @param config - The automation configuration.
+   * @returns The capability object.
+   */
+  automation(key, config) {
+    this.#validateUniqueKey(key);
+    const capability = createAutomationCapability(key, config);
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
+  /**
+   * Register an OAuth capability.
+   *
+   * There are two ways to configure OAuth:
+   *
+   * 1. Notion-managed providers:
+   * ```ts
+   * const worker = new Worker();
+   * export default worker;
+   *
+   * worker.oauth("googleAuth", {
+   *   type: "notion_managed",
+   *   name: "my-google-auth",
+   *   provider: "google"
+   * })
+   * ```
+   *
+   * 2. User-managed OAuth configuration:
+   * ```ts
+   * const worker = new Worker();
+   * export default worker;
+   *
+   * worker.oauth("myCustomAuth", {
+   *   type: "user_managed",
+   *   name: "my-custom-oauth",
+   *   authorizationEndpoint: "https://provider.com/oauth/authorize",
+   *   tokenEndpoint: "https://provider.com/oauth/token",
+   *   scope: "read write",
+   *   clientId: process.env.CLIENT_ID,
+   *   clientSecret: process.env.CLIENT_SECRET,
+   *   authorizationParams: {
+   *     access_type: "offline",
+   *     prompt: "consent"
+   *   }
+   * })
+   * ```
+   *
+   * @param key - The unique key used to register this OAuth capability.
+   * @param config - The OAuth configuration (Notion-managed or user-managed) for this capability.
+   * @returns The registered OAuth capability.
+   */
+  oauth(key, config) {
+    this.#validateUniqueKey(key);
+    const capability = createOAuthCapability(key, config);
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
+  /**
+   * Get all registered capabilities (for discovery) without their handlers.
+   */
+  get capabilities() {
+    return Array.from(this.#capabilities.values()).map((c) => ({
+      _tag: c._tag,
+      key: c.key,
+      config: c.config
+    }));
+  }
+  /**
+   * Execute a capability by key.
+   *
+   * @param key - The key of the capability to execute.
+   * @param context - The context to pass to the capability.
+   * @returns The result of the capability execution.
+   */
+  async run(key, context) {
+    const capability = this.#capabilities.get(key);
+    if (!capability) {
+      throw new Error(`Capability "${key}" not found`);
+    }
+    if (capability._tag === "oauth") {
+      throw new Error(
+        `Cannot run OAuth capability "${key}" - OAuth capabilities only provide configuration`
+      );
+    }
+    return capability.handler(context);
+  }
+  #validateUniqueKey(key) {
+    if (!key || typeof key !== "string") {
+      throw new Error("Capability key must be a non-empty string");
+    }
+    if (this.#capabilities.has(key)) {
+      throw new Error(`Capability with key "${key}" already registered`);
+    }
+  }
+}
+export {
+  Worker
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/sdk",
-	"version": "0.0.68",
+	"version": "0.0.69",
 	"description": "An SDK for building workers for the Project Ajax platform",
 	"license": "UNLICENSED",
 	"type": "module",
@@ -28,10 +28,6 @@
 		"./types": {
 			"types": "./dist/types.d.ts",
 			"default": "./dist/types.js"
-		},
-		"./sync": {
-			"types": "./dist/capabilities/sync.d.ts",
-			"default": "./dist/capabilities/sync.js"
 		}
 	},
 	"engines": {

package/src/capabilities/automation.test.ts

@@ -8,14 +8,10 @@ import {
 	vi,
 } from "vitest";
 import { ExecutionError } from "../error.js";
-import {
-	type AutomationConfiguration,
-	type AutomationContext,
-	automation,
-	type PageObjectResponse,
-} from "./automation.js";
+import type { AutomationContext, PageObjectResponse } from "./automation.js";
+import { createAutomationCapability } from "./automation.js";
 
-describe("automation", () => {
+describe("createAutomationCapability", () => {
 	let stdoutSpy: Mock<typeof process.stdout.write>;
 
 	beforeEach(() => {
@@ -29,23 +25,21 @@ describe("automation", () => {
 	});
 
 	it("creates automation capability with correct structure", () => {
-		const config: AutomationConfiguration = {
+		const capability = createAutomationCapability("testAutomation", {
 			title: "Test Automation",
 			description: "Test automation description",
 			execute: () => {},
-		};
-
-		const result = automation(config);
+		});
 
-		expect(result._tag).toBe("automation");
-		expect(result.config.title).toBe("Test Automation");
-		expect(result.config.description).toBe("Test automation description");
-		expect(typeof result.handler).toBe("function");
+		expect(capability).toBeDefined();
+		expect(capability?._tag).toBe("automation");
+		expect(capability.config.title).toBe("Test Automation");
+		expect(capability.config.description).toBe("Test automation description");
 	});
 
 	it("executes automation without page data", async () => {
 		const executeFn = vi.fn();
-		const myAutomation = automation({
+		const capability = createAutomationCapability("syncAutomation", {
 			title: "Sync Automation",
 			description: "Executes synchronously",
 			execute: executeFn,
@@ -56,7 +50,7 @@ describe("automation", () => {
 			actionType: "test_action",
 		};
 
-		await myAutomation.handler(context);
+		await capability.handler(context);
 
 		expect(executeFn).toHaveBeenCalledWith(context);
 		expect(stdoutSpy).toHaveBeenCalledWith(
@@ -66,7 +60,7 @@ describe("automation", () => {
 
 	it("executes automation with page data", async () => {
 		const executeFn = vi.fn();
-		const myAutomation = automation({
+		const capability = createAutomationCapability("pageAutomation", {
 			title: "Page Automation",
 			description: "Processes page data",
 			execute: executeFn,
@@ -97,7 +91,7 @@ describe("automation", () => {
 			pageData,
 		};
 
-		await myAutomation.handler(context);
+		await capability.handler(context);
 
 		expect(executeFn).toHaveBeenCalledWith(context);
 		expect(stdoutSpy).toHaveBeenCalledWith(
@@ -106,7 +100,7 @@ describe("automation", () => {
 	});
 
 	it("handles execution error from function", async () => {
-		const myAutomation = automation({
+		const capability = createAutomationCapability("errorAutomation", {
 			title: "Error Automation",
 			description: "Throws an error",
 			execute: () => {
@@ -119,7 +113,7 @@ describe("automation", () => {
 			actionType: "error_action",
 		};
 
-		await expect(myAutomation.handler(context)).rejects.toThrow(ExecutionError);
+		await expect(capability.handler(context)).rejects.toThrow(ExecutionError);
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			`\n<output>{"status":"error","error":{"name":"ExecutionError","message":"Error during worker execution: Error: Something went wrong"}}</output>\n`,
@@ -127,7 +121,7 @@ describe("automation", () => {
 	});
 
 	it("handles execution error with non-Error object", async () => {
-		const myAutomation = automation({
+		const capability = createAutomationCapability("nonErrorAutomation", {
 			title: "Non-Error Automation",
 			description: "Throws a non-Error object",
 			execute: () => {
@@ -139,7 +133,7 @@ describe("automation", () => {
 			actionType: "string_error_action",
 		};
 
-		await expect(myAutomation.handler(context)).rejects.toThrow(ExecutionError);
+		await expect(capability.handler(context)).rejects.toThrow(ExecutionError);
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			`\n<output>{"status":"error","error":{"name":"ExecutionError","message":"Error during worker execution: String error"}}</output>\n`,

package/src/capabilities/automation.ts

@@ -70,38 +70,24 @@ export interface AutomationHandlerResult {
 	description: string;
 }
 
+export type AutomationCapability = ReturnType<
+	typeof createAutomationCapability
+>;
+
 /**
- * Creates a capability definition for an automation that can be triggered
- * from database automations in Notion.
- *
- * Example:
- *
- * ```ts
- * automation({
- *   title: "Send Welcome Email",
- *   description: "Sends a welcome email when a new user is added",
- *   execute: async (context) => {
- *     const { pageId, pageData } = context;
- *
- *     // Access page properties from the Public API format
- *     if (pageData) {
- *       const name = pageData.properties.Name; // Access any property
- *       const status = pageData.properties.Status;
- *       console.log(`Processing: ${name}`);
- *     }
- *
- *     // Your automation logic here
- *     await sendEmail(pageId);
- *   },
- * })
- * ```
+ * Creates an automation capability from configuration.
  *
- * @param config - The configuration for the automation.
- * @returns A capability definition for the automation.
+ * @param key - The unique name for this capability.
+ * @param config - The automation configuration.
+ * @returns The capability object.
  */
-export function automation(config: AutomationConfiguration) {
+export function createAutomationCapability(
+	key: string,
+	config: AutomationConfiguration,
+) {
 	return {
-		_tag: "automation",
+		_tag: "automation" as const,
+		key,
 		config: {
 			title: config.title,
 			description: config.description,
@@ -109,12 +95,10 @@ export function automation(config: AutomationConfiguration) {
 		async handler(context: AutomationContext): Promise<void> {
 			try {
 				await config.execute(context);
-				// Write success result
 				process.stdout.write(
 					`\n<output>${JSON.stringify({ status: "success" })}</output>\n`,
 				);
 			} catch (err) {
-				// Convert error to ExecutionError and write it
 				const error = new ExecutionError(err);
 				process.stdout.write(
 					`\n<output>${JSON.stringify({ status: "error", error: { name: error.name, message: error.message } })}</output>\n`,

package/src/capabilities/oauth.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from "vitest";
-import { oauth } from "./oauth.js";
+import { createOAuthCapability } from "./oauth.js";
 
 describe("oauth", () => {
 	afterEach(() => {
@@ -9,42 +9,43 @@ describe("oauth", () => {
 	});
 
 	it("creates notion-managed oauth capability with accessToken helper", async () => {
-		const myOauth = oauth({
+		const capability = createOAuthCapability("googleAuth", {
 			name: "googleAuth",
 			provider: "google",
 			accessTokenExpireMs: 60_000,
 		});
 
-		expect(myOauth._tag).toBe("oauth");
-		expect(myOauth.config.type).toBe("notion_managed");
-		expect(myOauth.config.accessTokenExpireMs).toBe(60_000);
-		expect(myOauth.envKey).toBe("OAUTH_676F6F676C6541757468_ACCESS_TOKEN");
-		expect(typeof myOauth.accessToken).toBe("function");
+		expect(capability).toBeDefined();
+		expect(capability?._tag).toBe("oauth");
+		expect(capability.config.type).toBe("notion_managed");
+		expect(capability.config.accessTokenExpireMs).toBe(60_000);
+
+		expect(typeof capability.accessToken).toBe("function");
 
 		process.env.OAUTH_676F6F676C6541757468_ACCESS_TOKEN = "token-123";
-		await expect(myOauth.accessToken()).resolves.toBe("token-123");
+		await expect(capability.accessToken()).resolves.toBe("token-123");
 	});
 
 	it("normalizes non-alphanumeric characters in the identifier", () => {
-		const myOauth = oauth({
+		const capability = createOAuthCapability("googleCalendar", {
 			name: "google-calendar",
 			provider: "google",
 			accessTokenExpireMs: 3600_000,
 		});
 
-		expect(myOauth.envKey).toBe(
-			"OAUTH_676F6F676C652D63616C656E646172_ACCESS_TOKEN",
-		);
-		expect(myOauth.config.accessTokenExpireMs).toBe(3600_000);
+		expect(capability).toBeDefined();
+		expect(capability?._tag).toBe("oauth");
+		expect(capability.config.type).toBe("notion_managed");
+		expect(capability.config.accessTokenExpireMs).toBe(3600_000);
 	});
 
 	it("throws a helpful error when the token env var is missing", async () => {
-		const myOauth = oauth({
+		const capability = createOAuthCapability("googleAuthMissing", {
 			name: "googleAuth",
 			provider: "google",
 		});
 
-		await expect(myOauth.accessToken()).rejects.toThrow(
+		await expect(capability.accessToken()).rejects.toThrow(
 			/Missing OAuth access token env var "OAUTH_676F6F676C6541757468_ACCESS_TOKEN"/,
 		);
 	});

package/src/capabilities/oauth.ts

@@ -88,46 +88,21 @@ export type OAuthConfiguration =
 	| NotionManagedOAuthConfiguration
 	| UserManagedOAuthConfiguration;
 
+export type OAuthCapability = ReturnType<typeof createOAuthCapability>;
+
 /**
  * Creates an OAuth provider configuration for authenticating with third-party services.
  *
- * There are two ways to configure OAuth:
- *
- * 1. Notion-managed providers:
- * ```ts
- * oauth({
- *   type: "notion_managed",
- *   name: "my-google-auth",
- *   provider: "google"
- * })
- * ```
- *
- * 2. User-managed OAuth configuration:
- * ```ts
- * oauth({
- *   type: "user_managed",
- *   name: "my-custom-oauth",
- *   authorizationEndpoint: "https://provider.com/oauth/authorize",
- *   tokenEndpoint: "https://provider.com/oauth/token",
- *   scope: "read write",
- *   clientId: process.env.CLIENT_ID,
- *   clientSecret: process.env.CLIENT_SECRET,
- *   authorizationParams: {
- *     access_type: "offline",
- *     prompt: "consent"
- *   }
- * })
- * ```
- *
  * @param config - The OAuth configuration (Notion-managed or user-managed).
  * @returns An OAuth provider definition.
  */
-export function oauth(config: OAuthConfiguration) {
+export function createOAuthCapability(key: string, config: OAuthConfiguration) {
 	const envKey = oauthNameToEnvKey(config.name);
 
 	if ("provider" in config) {
 		return {
-			_tag: "oauth",
+			_tag: "oauth" as const,
+			key,
 			envKey,
 			async accessToken(): Promise<string> {
 				return readRequiredEnvVar(envKey, { name: config.name });
@@ -142,7 +117,8 @@ export function oauth(config: OAuthConfiguration) {
 	}
 
 	return {
-		_tag: "oauth",
+		_tag: "oauth" as const,
+		key,
 		envKey,
 		async accessToken(): Promise<string> {
 			return readRequiredEnvVar(envKey, { name: config.name });

package/src/capabilities/sync.ts

@@ -139,6 +139,8 @@ export type SyncHandlerResult<PK extends string, Context = unknown> = {
 	deleteUnreturnedPages?: boolean;
 };
 
+export type SyncCapability = ReturnType<typeof createSyncCapability>;
+
 /**
  * Creates a special handler for syncing third-party data to a collection.
  *
@@ -146,13 +148,14 @@ export type SyncHandlerResult<PK extends string, Context = unknown> = {
  * @returns A handler function that executes the sync function, and passes data
  * needed to complete the sync back to the platform.
  */
-export function sync<
+export function createSyncCapability<
 	PK extends string,
 	S extends Schema<PK>,
 	Context = unknown,
->(syncConfiguration: SyncConfiguration<PK, S, Context>) {
+>(key: string, syncConfiguration: SyncConfiguration<PK, S, Context>) {
 	return {
-		_tag: "sync",
+		_tag: "sync" as const,
+		key,
 		config: {
 			primaryKeyProperty: syncConfiguration.primaryKeyProperty,
 			schema: syncConfiguration.schema,