@notionhq/workers 0.5.0 → 0.7.0

package/src/alpha/context.ts

@@ -0,0 +1,61 @@
+import { Client } from "@notionhq/client";
+import type { ClientOptions } from "@notionhq/client/build/src/Client.js";
+
+import type { CapabilityType } from "./manifest.js";
+
+export type CapabilityContext = {
+	/** Notion API SDK client for this execution. */
+	notion: Client;
+};
+
+const FIX_STEPS =
+	"\n\nTo fix this:\n" +
+	"1. Create a personal access token at https://app.notion.com/developers/tokens\n" +
+	"2. Add NOTION_API_TOKEN=<your-token> to your .env file\n" +
+	"3. For deployed workers, run: ntn workers env push";
+
+function missingTokenMessage(capabilityType: CapabilityType): string {
+	if (capabilityType === "tool") {
+		return (
+			"NOTION_API_TOKEN is not set. " +
+			"When tools are called through a Custom Agent, the platform sets NOTION_API_TOKEN automatically, " +
+			"using the permissions of the Custom Agent. " +
+			"Outside of that context (e.g. ntn workers exec), you must set it yourself." +
+			FIX_STEPS
+		);
+	}
+
+	return (
+		"NOTION_API_TOKEN is not set. " +
+		`context.notion requires an API token to make requests in ${capabilityType} capabilities to Notion.` +
+		FIX_STEPS
+	);
+}
+
+function createUnauthenticatedNotionProxy(capabilityType: CapabilityType): Client {
+	return new Proxy({} as Client, {
+		get(_target, prop) {
+			if (prop === "then" || typeof prop === "symbol") {
+				return undefined;
+			}
+			throw new Error(missingTokenMessage(capabilityType));
+		},
+	});
+}
+
+export function createCapabilityContext(capabilityType: CapabilityType): CapabilityContext {
+	const options: ClientOptions = {};
+
+	if (process.env.NOTION_API_BASE_URL) {
+		options.baseUrl = process.env.NOTION_API_BASE_URL;
+	}
+
+	if (!process.env.NOTION_API_TOKEN) {
+		return { notion: createUnauthenticatedNotionProxy(capabilityType) };
+	}
+
+	options.auth = process.env.NOTION_API_TOKEN;
+	const notion = new Client(options);
+
+	return { notion };
+}

package/src/alpha/database.ts

@@ -0,0 +1,102 @@
+import type { PropertySchema, Schema } from "./schema.js";
+
+/**
+ * Configuration for a database that Notion creates and manages on behalf
+ * of the worker. The database is created on first deploy and its schema
+ * is migrated on subsequent deploys.
+ */
+export type ManagedDatabaseConfig<S extends PropertySchema = PropertySchema> = {
+	type: "managed";
+	/**
+	 * The title for the database when it is first created in Notion.
+	 * Defaults to the database's name.
+	 *
+	 * Updating this after the database has been created will not change the
+	 * title of the database — users may rename it freely.
+	 */
+	initialTitle?: string;
+	/**
+	 * The property that serves as the primary key for matching records.
+	 * Must be a property defined in the schema. The value of this property
+	 * should match the `key` field on each sync change.
+	 */
+	primaryKey: Extract<keyof S, string>;
+	/**
+	 * The database schema. Notion will migrate the database to match
+	 * the given schema on worker deploy.
+	 */
+	schema: Schema<S>;
+};
+
+/**
+ * Configuration union for all database types.
+ * Currently only `"managed"` is supported.
+ */
+export type DatabaseConfig<S extends PropertySchema = PropertySchema> = ManagedDatabaseConfig<S>;
+
+/**
+ * A database declaration as returned by {@link createDatabase}.
+ */
+export type Database<S extends PropertySchema = PropertySchema> = {
+	_tag: "database";
+	name: string;
+	config: DatabaseConfig<S>;
+};
+
+/**
+ * Declare a database.
+ *
+ * A database can be declared anywhere — inline in a sync's config, in the
+ * sync's file, or in a shared module that several syncs import. The build
+ * discovers databases by walking capability configs: any database attached
+ * to a sync (or referenced by a `Schema.relation(...)`) is included in the
+ * manifest and created on deploy.
+ *
+ * The `name` is the database's stable identity across deploys — it is how
+ * the platform matches the declaration to the actual Notion database it
+ * created previously. Renaming it orphans that database, so treat it like a
+ * primary key: pick it once and leave it alone. Two distinct
+ * `createDatabase(...)` calls sharing a name fail the build; share one
+ * instance via import instead.
+ *
+ * @example
+ * ```ts
+ * // src/lib/databases.ts — shared by several syncs
+ * import { createDatabase } from "@notionhq/workers/alpha/database";
+ * import { Schema } from "@notionhq/workers/alpha/schema";
+ *
+ * export const projects = createDatabase("projects", {
+ *   type: "managed",
+ *   primaryKey: "Project ID",
+ *   schema: {
+ *     properties: {
+ *       Name: Schema.title(),
+ *       "Project ID": Schema.richText(),
+ *     },
+ *   },
+ * });
+ *
+ * export const tasks = createDatabase("tasks", {
+ *   type: "managed",
+ *   initialTitle: "Tasks",
+ *   primaryKey: "Task ID",
+ *   schema: {
+ *     properties: {
+ *       Title: Schema.title(),
+ *       "Task ID": Schema.richText(),
+ *       Project: Schema.relation(projects),
+ *     },
+ *   },
+ * });
+ * ```
+ */
+export function createDatabase<S extends PropertySchema>(
+	name: string,
+	config: DatabaseConfig<S>,
+): Database<S> {
+	if (!name || typeof name !== "string") {
+		throw new Error("Database name must be a non-empty string");
+	}
+
+	return { _tag: "database", name, config };
+}

package/src/alpha/error.ts

@@ -0,0 +1,49 @@
+/**
+ * An error that occurred during the execution of a worker capability.
+ */
+export class ExecutionError extends Error {
+	override readonly cause: unknown;
+
+	constructor(cause: unknown) {
+		super(`Error during worker execution: ${cause}`);
+		this.name = "ExecutionError";
+		this.cause = cause;
+	}
+}
+
+/**
+ * Throw this error from your sync handler to signal that the external API
+ * returned a rate-limit response (e.g. HTTP 429).
+ *
+ * When the platform receives this error it applies exponential backoff
+ * instead of retrying immediately. If `retryAfter` is provided, the
+ * platform will wait at least that many seconds before the next attempt.
+ *
+ * @example
+ * ```ts
+ * handler: async () => {
+ *   const res = await fetch("https://api.example.com/issues");
+ *   if (res.status === 429) {
+ *     const retryAfter = Number(res.headers.get("Retry-After"));
+ *     throw new RateLimitError({
+ *       retryAfter: Number.isFinite(retryAfter) ? retryAfter : undefined,
+ *     });
+ *   }
+ *   // ...
+ * },
+ * ```
+ */
+export class RateLimitError extends ExecutionError {
+	/**
+	 * Optional number of seconds the external API asked us to wait
+	 * before retrying. The platform takes the max of this value and its
+	 * own exponential-backoff delay.
+	 */
+	readonly retryAfter: number | undefined;
+
+	constructor(options?: { retryAfter?: number }) {
+		super("Rate limited by external API");
+		this.name = "RateLimitError";
+		this.retryAfter = options?.retryAfter;
+	}
+}