@project-ajax/sdk 0.0.67 → 0.0.69

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`);
+		}
+	}
+}