@project-ajax/sdk 0.0.68 → 0.0.70

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

@@ -26,44 +26,90 @@ type PropertyValueType<T extends PropertyConfiguration> = T extends {
 		: TextValue;
 
 /**
- * An object representing a third-party record to be synced.
+ * Sync mode determines how the sync handles data lifecycle.
  */
-export type SyncedObject<PK extends string, S extends PropertySchema<PK>> = {
+export type SyncMode = "replace" | "incremental";
+
+/**
+ * A change representing a record to be created or updated.
+ */
+export type SyncChangeUpsert<
+	PK extends string,
+	S extends PropertySchema<PK>,
+> = {
+	/**
+	 * The type of change. Use `"upsert"` to create or update a record.
+	 */
+	type: "upsert";
+	/**
+	 * A unique identifier for this record, used to match against existing pages.
+	 * This value will be stored in the property specified by `primaryKeyProperty`.
+	 */
 	key: string;
+	/**
+	 * The property values for this record.
+	 * Keys must match the property names defined in the schema.
+	 * Use the Builder helpers (e.g., `Builder.title()`, `Builder.richText()`) to create values.
+	 */
 	properties: {
 		[Property in keyof S]: PropertyValueType<S[Property]>;
 	};
 	/**
 	 * Optional icon to use as the icon for this row's page.
-	 * Use the `icon()` builder to create an icon value.
+	 * Use the `Builder.emojiIcon()`, `Builder.notionIcon()`, or `Builder.imageIcon()` helpers.
 	 */
 	icon?: Icon;
 	/**
-	 * Optional markdown content to add to the page.
-	 * This will be converted to blocks and added as page content.
+	 * Optional markdown content to add to the page body.
+	 * This will be converted to Notion blocks and added as page content.
 	 */
 	pageContentMarkdown?: string;
 };
 
+/**
+ * A change representing a record to be deleted.
+ * Only applicable when using `mode: "incremental"`.
+ */
+export type SyncChangeDelete = {
+	/**
+	 * The type of change. Use `"delete"` to remove a record.
+	 */
+	type: "delete";
+	/**
+	 * The unique identifier of the record to delete.
+	 * Must match the `key` of a previously upserted record.
+	 */
+	key: string;
+};
+
+/**
+ * A change to be applied to the synced database.
+ * Can be either an upsert (create/update) or a delete.
+ */
+export type SyncChange<PK extends string, S extends PropertySchema<PK>> =
+	| SyncChangeUpsert<PK, S>
+	| SyncChangeDelete;
+
 /**
  * Result returned from the sync execute function.
  */
 export type SyncExecutionResult<PK extends string, Context = unknown> = {
 	/**
-	 * The batch of objects fetched in this execution.
+	 * The batch of changes to apply in this execution.
+	 * Can include upserts (create/update) and deletes.
 	 */
-	objects: SyncedObject<PK, PropertySchema<PK>>[];
+	changes: SyncChange<PK, PropertySchema<PK>>[];
 
 	/**
-	 * Indicates whether the sync is complete.
-	 * - `true`: No more data to fetch, sync is complete
-	 * - `false`: More data available, will trigger another execution with nextContext
+	 * Indicates whether there is more data to fetch.
+	 * - `true`: More data available, will trigger another execution with nextContext
+	 * - `false`: No more data to fetch, sync is complete
 	 */
-	done: boolean;
+	hasMore: boolean;
 
 	/**
 	 * Optional context data to pass to the next execution.
-	 * Required if `done` is `false`, ignored if `done` is `true`.
+	 * Required if `hasMore` is `true`, ignored if `hasMore` is `false`.
 	 * This can be any type of data (cursor, page number, timestamp, etc.).
 	 * The same data will be provided in the context parameter of the next execution.
 	 */
@@ -92,15 +138,16 @@ export type SyncConfiguration<
 	schema: S;
 
 	/**
-	 * Whether to delete pages from the collection that are not returned
-	 * from any of the sync executions (mark-and-sweep deletion).
-	 *
-	 * - `true`: Pages not seen in any execution batch will be deleted
-	 * - `false` (default): Only upsert pages, never delete
+	 * How the sync handles data lifecycle:
+	 * - "replace": Each sync returns the complete dataset. After hasMore:false,
+	 *              pages not seen in this sync run are deleted.
+	 * - "incremental": Sync returns changes only. After hasMore:false, sync
+	 *                  continues from saved cursor. Use delete markers
+	 *                  to explicitly remove pages.
 	 *
-	 * @default false
+	 * @default "replace"
 	 */
-	deleteUnreturnedPages?: boolean;
+	mode?: SyncMode;
 
 	/**
 	 * How often the sync should run.
@@ -118,27 +165,29 @@ export type SyncConfiguration<
 	 * A function that fetches the data to sync from the third-party service.
 	 *
 	 * This function can return all data at once, or implement pagination by:
-	 * 1. Returning a batch of objects with `done: false` and a `nextContext`
+	 * 1. Returning a batch of changes with `hasMore: true` and a `nextContext`
 	 * 2. The runtime will call execute again with that context data
-	 * 3. Continue until `done: true` is returned
+	 * 3. Continue until `hasMore: false` is returned
 	 *
 	 * The runtime will handle diffing against the data source and creating,
 	 * updating, and deleting pages as necessary.
 	 *
 	 * @param context - Optional context data from previous execution (undefined on first call)
-	 * @returns A result containing objects, done status, and optional nextContext
+	 * @returns A result containing changes, hasMore status, and optional nextContext
 	 */
 	execute: (context?: Context) => Promise<SyncExecutionResult<PK, Context>>;
 };
 
 export type SyncHandlerResult<PK extends string, Context = unknown> = {
 	primaryKeyProperty: PK;
-	objects: SyncedObject<PK, PropertySchema<PK>>[];
-	done: boolean;
+	changes: SyncChange<PK, PropertySchema<PK>>[];
+	hasMore: boolean;
 	nextContext?: Context;
-	deleteUnreturnedPages?: boolean;
+	mode?: SyncMode;
 };
 
+export type SyncCapability = ReturnType<typeof createSyncCapability>;
+
 /**
  * Creates a special handler for syncing third-party data to a collection.
  *
@@ -146,17 +195,18 @@ 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,
-			deleteUnreturnedPages: syncConfiguration.deleteUnreturnedPages,
+			mode: syncConfiguration.mode,
 			schedule: parseSchedule(syncConfiguration.schedule),
 		},
 		async handler(context?: Context) {
@@ -167,8 +217,8 @@ export function sync<
 				});
 
 			const result = {
-				objects: executionResult.objects,
-				done: executionResult.done,
+				changes: executionResult.changes,
+				hasMore: executionResult.hasMore,
 				nextContext: executionResult.nextContext,
 			};
 

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,26 @@
 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,
+	SyncChange,
+	SyncChangeDelete,
+	SyncChangeUpsert,
 	SyncConfiguration,
 	SyncExecutionResult,
-	SyncedObject,
+	SyncMode,
 } 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 +29,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.