@project-ajax/sdk 0.0.62 → 0.0.63

package/dist/capabilities/automation.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Context provided to automation execute functions
+ */
+export interface AutomationContext {
+    /**
+     * The ID of the page that triggered the automation (if applicable)
+     */
+    pageId?: string;
+    /**
+     * The type of automation action that was triggered
+     */
+    actionType: string;
+    /**
+     * The full page object from Notion's Public API (if triggered by a database page)
+     */
+    pageData?: PageObjectResponse;
+}
+/**
+ * Page object from Notion's Public API
+ * This represents a database page with all its properties.
+ * Properties are in Notion's Public API format.
+ * See: https://developers.notion.com/reference/page
+ */
+export interface PageObjectResponse {
+    object: "page";
+    id: string;
+    created_time: string;
+    last_edited_time: string;
+    created_by: {
+        id: string;
+    };
+    last_edited_by: {
+        id: string;
+    };
+    cover: unknown;
+    icon: unknown;
+    parent: unknown;
+    archived: boolean;
+    properties: Record<string, unknown>;
+    url: string;
+    public_url?: string | null;
+}
+/**
+ * Configuration for an automation capability
+ */
+export interface AutomationConfiguration {
+    /**
+     * Title of the automation - shown in the UI when selecting automations
+     */
+    title: string;
+    /**
+     * Description of what this automation does - shown in the UI
+     */
+    description: string;
+    /**
+     * The function that executes when the automation is triggered
+     * @param context - Context about the automation trigger, including page data if applicable
+     * @returns A promise that resolves when the automation completes
+     */
+    execute: (context: AutomationContext) => Promise<void> | void;
+}
+/**
+ * Result returned from automation execution
+ */
+export interface AutomationHandlerResult {
+    title: string;
+    description: string;
+}
+/**
+ * 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);
+ *   },
+ * })
+ * ```
+ *
+ * @param config - The configuration for the automation.
+ * @returns A capability definition for the automation.
+ */
+export declare function automation(config: AutomationConfiguration): {
+    _tag: string;
+    config: {
+        title: string;
+        description: string;
+    };
+    handler(context: AutomationContext): Promise<void>;
+};
+//# sourceMappingURL=automation.d.ts.map

package/dist/capabilities/automation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automation.d.ts","sourceRoot":"","sources":["../../src/capabilities/automation.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3B,cAAc,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9D;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,uBAAuB;;;;;;qBAOjC,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;EAiBzD"}

package/dist/capabilities/automation.js

@@ -0,0 +1,31 @@
+import { ExecutionError } from "../error.js";
+function automation(config) {
+  return {
+    _tag: "automation",
+    config: {
+      title: config.title,
+      description: config.description
+    },
+    async handler(context) {
+      try {
+        await config.execute(context);
+        process.stdout.write(
+          `
+<output>${JSON.stringify({ status: "success" })}</output>
+`
+        );
+      } catch (err) {
+        const error = new ExecutionError(err);
+        process.stdout.write(
+          `
+<output>${JSON.stringify({ status: "error", error: { name: error.name, message: error.message } })}</output>
+`
+        );
+        throw error;
+      }
+    }
+  };
+}
+export {
+  automation
+};

package/dist/capabilities/automation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=automation.test.d.ts.map

package/dist/capabilities/automation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"automation.test.d.ts","sourceRoot":"","sources":["../../src/capabilities/automation.test.ts"],"names":[],"mappings":""}

package/dist/error.d.ts

@@ -1,5 +1,5 @@
 /**
- * An error that occurred during the execution of a sync.
+ * An error that occurred during the execution of a worker capability.
  */
 export declare class ExecutionError extends Error {
     readonly cause: unknown;

package/dist/error.js

@@ -1,7 +1,7 @@
 class ExecutionError extends Error {
   cause;
   constructor(cause) {
-    super(`Error during sync execution: ${cause}`);
+    super(`Error during worker execution: ${cause}`);
     this.name = "ExecutionError";
     this.cause = cause;
   }

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { emojiIcon, notionIcon } from "./builder.js";
+export type { AutomationConfiguration, AutomationContext, PageObjectResponse, } from "./capabilities/automation.js";
+export { automation } from "./capabilities/automation.js";
 export type { SyncConfiguration, SyncExecutionResult, SyncedObject, } from "./capabilities/sync.js";
 export { sync } from "./capabilities/sync.js";
 export { tool } from "./capabilities/tool.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EACX,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EACX,uBAAuB,EACvB,iBAAiB,EACjB,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,YAAY,EACX,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAC9C,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,7 +1,9 @@
 import { emojiIcon, notionIcon } from "./builder.js";
+import { automation } from "./capabilities/automation.js";
 import { sync } from "./capabilities/sync.js";
 import { tool } from "./capabilities/tool.js";
 export {
+  automation,
   emojiIcon,
   notionIcon,
   sync,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@project-ajax/sdk",
-	"version": "0.0.62",
+	"version": "0.0.63",
 	"description": "An SDK for building workers for the Project Ajax platform",
 	"license": "UNLICENSED",
 	"type": "module",

package/src/capabilities/automation.test.ts

@@ -0,0 +1,148 @@
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	type Mock,
+	vi,
+} from "vitest";
+import { ExecutionError } from "../error.js";
+import {
+	type AutomationConfiguration,
+	type AutomationContext,
+	automation,
+	type PageObjectResponse,
+} from "./automation.js";
+
+describe("automation", () => {
+	let stdoutSpy: Mock<typeof process.stdout.write>;
+
+	beforeEach(() => {
+		stdoutSpy = vi
+			.spyOn(process.stdout, "write")
+			.mockImplementation(() => true);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("creates automation capability with correct structure", () => {
+		const config: AutomationConfiguration = {
+			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");
+	});
+
+	it("executes automation without page data", async () => {
+		const executeFn = vi.fn();
+		const myAutomation = automation({
+			title: "Sync Automation",
+			description: "Executes synchronously",
+			execute: executeFn,
+		});
+
+		const context: AutomationContext = {
+			pageId: "page-123",
+			actionType: "test_action",
+		};
+
+		await myAutomation.handler(context);
+
+		expect(executeFn).toHaveBeenCalledWith(context);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"status":"success"}</output>\n`,
+		);
+	});
+
+	it("executes automation with page data", async () => {
+		const executeFn = vi.fn();
+		const myAutomation = automation({
+			title: "Page Automation",
+			description: "Processes page data",
+			execute: executeFn,
+		});
+
+		const pageData: PageObjectResponse = {
+			object: "page",
+			id: "page-789",
+			created_time: "2023-01-01T00:00:00.000Z",
+			last_edited_time: "2023-01-02T00:00:00.000Z",
+			created_by: { id: "user-1" },
+			last_edited_by: { id: "user-2" },
+			cover: null,
+			icon: null,
+			parent: { type: "database_id", database_id: "db-123" },
+			archived: false,
+			properties: {
+				Name: { id: "title", type: "title", title: [] },
+				Status: { id: "status", type: "status", status: { name: "Done" } },
+			},
+			url: "https://notion.so/page-789",
+			public_url: null,
+		};
+
+		const context: AutomationContext = {
+			pageId: "page-789",
+			actionType: "process_page",
+			pageData,
+		};
+
+		await myAutomation.handler(context);
+
+		expect(executeFn).toHaveBeenCalledWith(context);
+		expect(stdoutSpy).toHaveBeenCalledWith(
+			`\n<output>{"status":"success"}</output>\n`,
+		);
+	});
+
+	it("handles execution error from function", async () => {
+		const myAutomation = automation({
+			title: "Error Automation",
+			description: "Throws an error",
+			execute: () => {
+				throw new Error("Something went wrong");
+			},
+		});
+
+		const context: AutomationContext = {
+			pageId: "page-error",
+			actionType: "error_action",
+		};
+
+		await expect(myAutomation.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`,
+		);
+	});
+
+	it("handles execution error with non-Error object", async () => {
+		const myAutomation = automation({
+			title: "Non-Error Automation",
+			description: "Throws a non-Error object",
+			execute: () => {
+				throw "String error";
+			},
+		});
+
+		const context: AutomationContext = {
+			actionType: "string_error_action",
+		};
+
+		await expect(myAutomation.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

@@ -0,0 +1,126 @@
+import { ExecutionError } from "../error.js";
+
+/**
+ * Context provided to automation execute functions
+ */
+export interface AutomationContext {
+	/**
+	 * The ID of the page that triggered the automation (if applicable)
+	 */
+	pageId?: string;
+	/**
+	 * The type of automation action that was triggered
+	 */
+	actionType: string;
+	/**
+	 * The full page object from Notion's Public API (if triggered by a database page)
+	 */
+	pageData?: PageObjectResponse;
+}
+
+/**
+ * Page object from Notion's Public API
+ * This represents a database page with all its properties.
+ * Properties are in Notion's Public API format.
+ * See: https://developers.notion.com/reference/page
+ */
+export interface PageObjectResponse {
+	object: "page";
+	id: string;
+	created_time: string;
+	last_edited_time: string;
+	created_by: { id: string };
+	last_edited_by: { id: string };
+	cover: unknown;
+	icon: unknown;
+	parent: unknown;
+	archived: boolean;
+	properties: Record<string, unknown>;
+	url: string;
+	public_url?: string | null;
+}
+
+/**
+ * Configuration for an automation capability
+ */
+export interface AutomationConfiguration {
+	/**
+	 * Title of the automation - shown in the UI when selecting automations
+	 */
+	title: string;
+
+	/**
+	 * Description of what this automation does - shown in the UI
+	 */
+	description: string;
+
+	/**
+	 * The function that executes when the automation is triggered
+	 * @param context - Context about the automation trigger, including page data if applicable
+	 * @returns A promise that resolves when the automation completes
+	 */
+	execute: (context: AutomationContext) => Promise<void> | void;
+}
+
+/**
+ * Result returned from automation execution
+ */
+export interface AutomationHandlerResult {
+	title: string;
+	description: string;
+}
+
+/**
+ * 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);
+ *   },
+ * })
+ * ```
+ *
+ * @param config - The configuration for the automation.
+ * @returns A capability definition for the automation.
+ */
+export function automation(config: AutomationConfiguration) {
+	return {
+		_tag: "automation",
+		config: {
+			title: config.title,
+			description: config.description,
+		},
+		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`,
+				);
+				throw error;
+			}
+		},
+	};
+}

package/src/error.ts

@@ -1,11 +1,11 @@
 /**
- * An error that occurred during the execution of a sync.
+ * An error that occurred during the execution of a worker capability.
  */
 export class ExecutionError extends Error {
 	readonly cause: unknown;
 
 	constructor(cause: unknown) {
-		super(`Error during sync execution: ${cause}`);
+		super(`Error during worker execution: ${cause}`);
 		this.name = "ExecutionError";
 		this.cause = cause;
 	}

package/src/index.ts

@@ -1,4 +1,10 @@
 export { emojiIcon, notionIcon } from "./builder.js";
+export type {
+	AutomationConfiguration,
+	AutomationContext,
+	PageObjectResponse,
+} from "./capabilities/automation.js";
+export { automation } from "./capabilities/automation.js";
 export type {
 	SyncConfiguration,
 	SyncExecutionResult,