@project-ajax/sdk 0.0.68 → 0.0.69

package/src/capabilities/tool.test.ts

@@ -8,13 +8,13 @@ import {
 	vi,
 } from "vitest";
 import {
+	createToolCapability,
 	InvalidToolInputError,
 	InvalidToolOutputError,
 	ToolExecutionError,
-	tool,
 } from "./tool.js";
 
-describe("tool", () => {
+describe("Worker.tool", () => {
 	let stdoutSpy: Mock<typeof process.stdout.write>;
 
 	beforeEach(() => {
@@ -28,28 +28,28 @@ describe("tool", () => {
 	});
 
 	it("sync execution", async () => {
-		const myTool = tool<{ name: string }, string>({
-			title: "Say Hello",
-			description: "Greet a user",
-			schema: {
-				type: "object",
-				properties: {
-					name: { type: "string" },
+		const capability = createToolCapability<{ name: string }, string>(
+			"sayHello",
+			{
+				title: "Say Hello",
+				description: "Greet a user",
+				schema: {
+					type: "object",
+					properties: {
+						name: { type: "string" },
+					},
+					required: ["name"],
+					additionalProperties: false,
+				},
+				execute: (input: { name: string }) => {
+					return `Hello, ${input.name}!`;
 				},
-				required: ["name"],
-				additionalProperties: false,
-			},
-			execute: (input) => {
-				return `Hello, ${input.name}!`;
 			},
-		});
+		);
 
-		const result = await myTool.handler({ name: "Alice" });
+		const result = await capability.handler({ name: "Alice" });
 
-		expect(result._tag).toBe("success");
-		if (result._tag === "success") {
-			expect(result.value).toBe("Hello, Alice!");
-		}
+		expect(result).toEqual({ _tag: "success", value: "Hello, Alice!" });
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			`\n<output>"Hello, Alice!"</output>\n`,
@@ -57,30 +57,33 @@ describe("tool", () => {
 	});
 
 	it("async execution", async () => {
-		const myTool = tool<{ id: number }, { data: string }>({
-			title: "Fetch Data",
-			description: "Fetch data asynchronously",
-			schema: {
-				type: "object",
-				properties: {
-					id: { type: "number" },
+		const capability = createToolCapability<{ id: number }, { data: string }>(
+			"fetchData",
+			{
+				title: "Fetch Data",
+				description: "Fetch data asynchronously",
+				schema: {
+					type: "object",
+					properties: {
+						id: { type: "number" },
+					},
+					required: ["id"],
+					additionalProperties: false,
+				},
+				execute: async (input: { id: number }) => {
+					// Simulate async operation
+					await new Promise((resolve) => setTimeout(resolve, 10));
+					return { data: `Data for ID ${input.id}` };
 				},
-				required: ["id"],
-				additionalProperties: false,
-			},
-			execute: async (input) => {
-				// Simulate async operation
-				await new Promise((resolve) => setTimeout(resolve, 10));
-				return { data: `Data for ID ${input.id}` };
 			},
-		});
+		);
 
-		const result = await myTool.handler({ id: 42 });
+		const result = await capability.handler({ id: 42 });
 
-		expect(result._tag).toBe("success");
-		if (result._tag === "success") {
-			expect(result.value).toEqual({ data: "Data for ID 42" });
-		}
+		expect(result).toEqual({
+			_tag: "success",
+			value: { data: "Data for ID 42" },
+		});
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			`\n<output>{"data":"Data for ID 42"}</output>\n`,
@@ -88,27 +91,31 @@ describe("tool", () => {
 	});
 
 	it("execution error", async () => {
-		const myTool = tool<Record<string, never>, string>({
-			title: "Throw Error",
-			description: "Throws an error",
-			schema: {
-				type: "object",
-				properties: {},
-				required: [],
-				additionalProperties: false,
-			},
-			execute: () => {
-				throw new Error("Something went wrong");
+		const capability = createToolCapability<Record<string, never>, string>(
+			"throwError",
+			{
+				title: "Throw Error",
+				description: "Throws an error",
+				schema: {
+					type: "object",
+					properties: {},
+					required: [],
+					additionalProperties: false,
+				},
+				execute: () => {
+					throw new Error("Something went wrong");
+				},
 			},
-		});
+		);
 
-		const result = await myTool.handler({});
+		const result = (await capability.handler({})) as {
+			_tag: "error";
+			error: ToolExecutionError;
+		};
 
 		expect(result._tag).toBe("error");
-		if (result._tag === "error") {
-			expect(result.error).toBeInstanceOf(ToolExecutionError);
-			expect(result.error.message).toBe("Something went wrong");
-		}
+		expect(result.error).toBeInstanceOf(ToolExecutionError);
+		expect(result.error.message).toBe("Something went wrong");
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			`\n<output>{"_tag":"error","error":{"name":"ToolExecutionError","message":"Something went wrong"}}</output>\n`,
@@ -116,29 +123,33 @@ describe("tool", () => {
 	});
 
 	it("invalid input", async () => {
-		const myTool = tool<{ name: string }, string>({
-			title: "Say Hello",
-			description: "Requires a name property",
-			schema: {
-				type: "object",
-				properties: {
-					name: { type: "string" },
+		const capability = createToolCapability<{ name: string }, string>(
+			"sayHelloStrict",
+			{
+				title: "Say Hello",
+				description: "Requires a name property",
+				schema: {
+					type: "object",
+					properties: {
+						name: { type: "string" },
+					},
+					required: ["name"],
+					additionalProperties: false,
+				},
+				execute: (input: { name: string }) => {
+					return `Hello, ${input.name}!`;
 				},
-				required: ["name"],
-				additionalProperties: false,
-			},
-			execute: (input) => {
-				return `Hello, ${input.name}!`;
 			},
-		});
+		);
 
-		const result = await myTool.handler({ age: 25 });
+		const result = (await capability.handler({ age: 25 })) as {
+			_tag: "error";
+			error: InvalidToolInputError;
+		};
 
 		expect(result._tag).toBe("error");
-		if (result._tag === "error") {
-			expect(result.error).toBeInstanceOf(InvalidToolInputError);
-			expect(result.error.message).toContain("name");
-		}
+		expect(result.error).toBeInstanceOf(InvalidToolInputError);
+		expect(result.error.message).toContain("name");
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			expect.stringContaining(
@@ -148,7 +159,10 @@ describe("tool", () => {
 	});
 
 	it("invalid output", async () => {
-		const myTool = tool<Record<string, never>, { result: string }>({
+		const capability = createToolCapability<
+			Record<string, never>,
+			{ result: string }
+		>("invalidOutput", {
 			title: "Return Invalid Output",
 			description: "Returns output that doesn't match schema",
 			schema: {
@@ -171,13 +185,14 @@ describe("tool", () => {
 			},
 		});
 
-		const result = await myTool.handler({});
+		const result = (await capability.handler({})) as {
+			_tag: "error";
+			error: InvalidToolOutputError;
+		};
 
 		expect(result._tag).toBe("error");
-		if (result._tag === "error") {
-			expect(result.error).toBeInstanceOf(InvalidToolOutputError);
-			expect(result.error.message).toContain("result");
-		}
+		expect(result.error).toBeInstanceOf(InvalidToolOutputError);
+		expect(result.error.message).toContain("result");
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			expect.stringContaining(
@@ -187,10 +202,10 @@ describe("tool", () => {
 	});
 
 	it("invalid output with custom output schema", async () => {
-		const myTool = tool<
+		const capability = createToolCapability<
 			{ value: number },
 			{ doubled: number; message: string }
-		>({
+		>("customOutput", {
 			title: "Custom Output",
 			description: "Has custom output schema",
 			schema: {
@@ -211,20 +226,21 @@ describe("tool", () => {
 				additionalProperties: false,
 			},
 			// @ts-expect-error Testing invalid output - intentionally missing message property
-			execute: (input) => {
+			execute: (input: { value: number }) => {
 				return {
 					doubled: input.value * 2,
 				};
 			},
 		});
 
-		const result = await myTool.handler({ value: 5 });
+		const result = (await capability.handler({ value: 5 })) as {
+			_tag: "error";
+			error: InvalidToolOutputError;
+		};
 
 		expect(result._tag).toBe("error");
-		if (result._tag === "error") {
-			expect(result.error).toBeInstanceOf(InvalidToolOutputError);
-			expect(result.error.message).toContain("message");
-		}
+		expect(result.error).toBeInstanceOf(InvalidToolOutputError);
+		expect(result.error.message).toContain("message");
 
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			expect.stringContaining(

package/src/capabilities/tool.ts

@@ -1,12 +1,5 @@
 import { Ajv, type JSONSchemaType } from "ajv";
-
-type JSONValue =
-	| string
-	| number
-	| boolean
-	| null
-	| JSONValue[]
-	| { [key: string]: JSONValue };
+import type { JSONValue } from "../types.js";
 
 export interface ToolConfiguration<
 	I extends JSONValue,
@@ -70,34 +63,21 @@ export class ToolExecutionError extends Error {
 	}
 }
 
+export type ToolCapability<
+	I extends JSONValue,
+	O extends JSONValue = JSONValue,
+> = ReturnType<typeof createToolCapability<I, O>>;
+
 /**
  * Creates a capability definition for a tool to be used by an agent.
  *
- * Example:
- *
- * ```ts
- * tool<{ name: string }>({
- *   title: "Say Hello",
- *   description: "Say hello to the user",
- *   schema: {
- *     type: "object",
- *     properties: {
- *       name: { type: "string" },
- *     },
- *     required: ["name"],
- *   },
- *   execute: ({ name }) => {
- *     return `Hello, ${name}!`;
- *   },
- * })
- * ```
- *
  * @param config - The configuration for the tool.
  * @returns A capability definition for the tool.
  */
-export function tool<I extends JSONValue, O extends JSONValue = JSONValue>(
-	config: ToolConfiguration<I, O>,
-) {
+export function createToolCapability<
+	I extends JSONValue,
+	O extends JSONValue = JSONValue,
+>(key: string, config: ToolConfiguration<I, O>) {
 	const ajv = new Ajv();
 	const validateInput = ajv.compile(config.schema);
 	const validateOutput = config.outputSchema
@@ -105,7 +85,8 @@ export function tool<I extends JSONValue, O extends JSONValue = JSONValue>(
 		: null;
 
 	return {
-		_tag: "tool",
+		_tag: "tool" as const,
+		key,
 		config: {
 			title: config.title,
 			description: config.description,

package/src/index.ts

@@ -1,23 +1,23 @@
 export { emojiIcon, imageIcon, notionIcon, place } from "./builder.js";
 export type {
+	AutomationCapability,
 	AutomationConfiguration,
 	AutomationContext,
 	PageObjectResponse,
 } from "./capabilities/automation.js";
-export { automation } from "./capabilities/automation.js";
 export type {
 	NotionManagedOAuthConfiguration,
+	OAuthCapability,
 	OAuthConfiguration,
 	UserManagedOAuthConfiguration,
 } from "./capabilities/oauth.js";
-export { oauth } from "./capabilities/oauth.js";
 export type {
+	SyncCapability,
 	SyncConfiguration,
 	SyncExecutionResult,
 	SyncedObject,
 } from "./capabilities/sync.js";
-export { sync } from "./capabilities/sync.js";
-export { tool } from "./capabilities/tool.js";
+export type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
 export type {
 	Icon,
 	ImageIcon,
@@ -26,3 +26,4 @@ export type {
 	PlaceValue,
 	Schedule,
 } from "./types.js";
+export { Worker } from "./worker.js";

package/src/types.ts

@@ -1,3 +1,14 @@
+/**
+ * A JSON value is a string, number, boolean, null, array, or object.
+ */
+export type JSONValue =
+	| string
+	| number
+	| boolean
+	| null
+	| JSONValue[]
+	| { [key: string]: JSONValue };
+
 /**
  * A text token is a tuple where the first element is the text content
  * and optional subsequent elements are formatting annotations.

package/src/worker.ts

@@ -0,0 +1,278 @@
+import type {
+	AutomationCapability,
+	AutomationConfiguration,
+	AutomationContext,
+} from "./capabilities/automation.js";
+import { createAutomationCapability } from "./capabilities/automation.js";
+import type {
+	NotionManagedOAuthConfiguration,
+	OAuthCapability,
+	OAuthConfiguration,
+	UserManagedOAuthConfiguration,
+} from "./capabilities/oauth.js";
+import { createOAuthCapability } from "./capabilities/oauth.js";
+import type { SyncCapability, SyncConfiguration } from "./capabilities/sync.js";
+import { createSyncCapability } from "./capabilities/sync.js";
+import type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
+import { createToolCapability } from "./capabilities/tool.js";
+import type { Schema } from "./schema.js";
+import type { JSONValue } from "./types.js";
+
+// Re-export types for convenience
+export type {
+	AutomationConfiguration,
+	AutomationContext,
+	OAuthConfiguration,
+	NotionManagedOAuthConfiguration,
+	UserManagedOAuthConfiguration,
+	SyncConfiguration,
+	ToolConfiguration,
+};
+
+// ============================================================================
+// Capability types
+// ============================================================================
+
+type Capability =
+	| SyncCapability
+	// biome-ignore lint/suspicious/noExplicitAny: any is used to allow any input and output types
+	| ToolCapability<any, any>
+	| AutomationCapability
+	| OAuthCapability;
+
+// ============================================================================
+// Worker class
+// ============================================================================
+
+export class Worker {
+	#capabilities: Map<string, Capability> = 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<PK extends string, S extends Schema<PK>, Context = unknown>(
+		key: string,
+		config: SyncConfiguration<PK, S, Context>,
+	): SyncCapability {
+		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<I extends JSONValue, O extends JSONValue = JSONValue>(
+		key: string,
+		config: ToolConfiguration<I, O>,
+	): ToolCapability<I, O> {
+		this.#validateUniqueKey(key);
+		const capability = createToolCapability(key, config);
+		// biome-ignore lint/suspicious/noExplicitAny: any is used to allow any input and output types
+		this.#capabilities.set(key, capability as ToolCapability<any, any>);
+		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: string,
+		config: AutomationConfiguration,
+	): AutomationCapability {
+		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: string, config: OAuthConfiguration): OAuthCapability {
+		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(): Pick<Capability, "_tag" | "key" | "config">[] {
+		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: string, context: unknown): Promise<unknown> {
+		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`,
+			);
+		}
+
+		// biome-ignore lint/suspicious/noExplicitAny: context is unknown, passed by external non-typed code.
+		return capability.handler(context as any);
+	}
+
+	#validateUniqueKey(key: string): void {
+		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`);
+		}
+	}
+}