@project-ajax/sdk 0.0.67 → 0.0.69

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

@@ -7,6 +7,7 @@ import type {
 import type {
 	Icon,
 	PeopleValue,
+	PlaceValue,
 	Schedule,
 	SyncSchedule,
 	TextValue,
@@ -20,7 +21,9 @@ type PropertyValueType<T extends PropertyConfiguration> = T extends {
 	type: "people";
 }
 	? PeopleValue
-	: TextValue;
+	: T extends { type: "place" }
+		? PlaceValue
+		: TextValue;
 
 /**
  * An object representing a third-party record to be synced.
@@ -136,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.
  *
@@ -143,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,

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,27 +1,29 @@
-export { emojiIcon, imageIcon, notionIcon } from "./builder.js";
+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,
 	NoticonColor,
 	NoticonName,
+	PlaceValue,
 	Schedule,
 } from "./types.js";
+export { Worker } from "./worker.js";

package/src/schema.ts

@@ -22,7 +22,8 @@ export type PropertyType =
 	| "select"
 	| "multi_select"
 	| "status"
-	| "people";
+	| "people"
+	| "place";
 
 /**
  * Definition of a single property in a sync schema.
@@ -62,10 +63,17 @@ export type PropertyConfiguration =
 			type: "status";
 			groups: StatusGroup[];
 	  }
-	| { type: "people" };
+	| { type: "people" }
+	| { type: "place" };
 
 export type Schema<PK extends string> = {
-	dataSourceTitle: string;
+	/**
+	 * The default name for the database when it is first created.
+	 *
+	 * Updating this after the database has been created will not change the
+	 * name of the database.
+	 */
+	defaultName: string;
 	/**
 	 * Optional icon to use as the icon for the database page.
 	 * If not provided, defaults to 📋.
@@ -176,3 +184,10 @@ export function status(config: {
 export function people(): PropertyConfiguration {
 	return { type: "people" };
 }
+
+/**
+ * Creates a place property definition for storing geographic locations.
+ */
+export function place(): PropertyConfiguration {
+	return { type: "place" };
+}

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.
@@ -188,6 +199,33 @@ export type PeopleValue = PersonReference[];
 
 export type { NoticonName } from "./icon-names.js";
 
+/**
+ * Place value representing a geographic location.
+ * Used for place properties in databases.
+ */
+export interface PlaceValue {
+	/**
+	 * Latitude coordinate (required)
+	 */
+	lat: number;
+	/**
+	 * Longitude coordinate (required)
+	 */
+	lon: number;
+	/**
+	 * Optional display name for the location
+	 */
+	name?: string;
+	/**
+	 * Optional street address
+	 */
+	address?: string;
+	/**
+	 * Optional Google Place ID for the location
+	 */
+	googlePlaceId?: string;
+}
+
 /**
  * Time units for schedule intervals.
  * - "m": minutes