@notionhq/workers 0.0.82

package/src/capabilities/oauth.ts

@@ -0,0 +1,157 @@
+/**
+ * Configuration for a Notion-managed OAuth provider.
+ *
+ * Notion owns the OAuth app credentials (client ID/secret) and the backend has
+ * pre-configured provider settings.
+ */
+export interface NotionManagedOAuthConfiguration {
+	/**
+	 * The unique identifier for this OAuth provider instance.
+	 */
+	name: string;
+
+	/**
+	 * The pre-configured provider to use (e.g., "google", "github", "salesforce").
+	 * The backend will use this to look up the OAuth configuration.
+	 */
+	provider: string;
+
+	/**
+	 * Optional default access token expiry (in milliseconds) to use when the OAuth provider
+	 * does not return `expires_in` in token responses.
+	 *
+	 * Some providers (e.g. Salesforce in certain configurations) may omit expiry information.
+	 */
+	accessTokenExpireMs?: number;
+}
+
+/**
+ * Configuration for a user-managed OAuth provider.
+ *
+ * You own the OAuth app credentials and must explicitly provide endpoints and
+ * other OAuth parameters.
+ */
+export interface UserManagedOAuthConfiguration {
+	/**
+	 * The unique identifier for this OAuth provider instance.
+	 */
+	name: string;
+
+	/**
+	 * The client ID for the OAuth app.
+	 */
+	clientId: string;
+
+	/**
+	 * The client secret for the OAuth app.
+	 */
+	clientSecret: string;
+
+	/**
+	 * The OAuth 2.0 authorization endpoint URL.
+	 */
+	authorizationEndpoint: string;
+
+	/**
+	 * The OAuth 2.0 token endpoint URL.
+	 */
+	tokenEndpoint: string;
+
+	/**
+	 * The OAuth scope(s) to request.
+	 */
+	scope: string;
+
+	/**
+	 * Optional additional authorization parameters to include in the authorization request.
+	 */
+	authorizationParams?: Record<string, string>;
+
+	/**
+	 * Optional callback URL for OAuth redirect.
+	 */
+	callbackUrl?: string;
+
+	/**
+	 * Optional default access token expiry (in milliseconds) to use when the OAuth provider
+	 * does not return `expires_in` in token responses.
+	 *
+	 * Some providers (e.g. Salesforce in certain configurations) may omit expiry information.
+	 */
+	accessTokenExpireMs?: number;
+}
+
+/**
+ * Union type representing either Notion-managed or user-managed OAuth configuration.
+ */
+export type OAuthConfiguration =
+	| NotionManagedOAuthConfiguration
+	| UserManagedOAuthConfiguration;
+
+export type OAuthCapability = ReturnType<typeof createOAuthCapability>;
+
+/**
+ * Creates an OAuth provider configuration for authenticating with third-party services.
+ *
+ * @param config - The OAuth configuration (Notion-managed or user-managed).
+ * @returns An OAuth provider definition.
+ */
+export function createOAuthCapability(key: string, config: OAuthConfiguration) {
+	const envKey = oauthNameToEnvKey(config.name);
+
+	if ("provider" in config) {
+		return {
+			_tag: "oauth" as const,
+			key,
+			envKey,
+			async accessToken(): Promise<string> {
+				return readRequiredEnvVar(envKey, { name: config.name });
+			},
+			config: {
+				type: "notion_managed" as const,
+				name: config.name,
+				provider: config.provider,
+				accessTokenExpireMs: config.accessTokenExpireMs,
+			},
+		};
+	}
+
+	return {
+		_tag: "oauth" as const,
+		key,
+		envKey,
+		async accessToken(): Promise<string> {
+			return readRequiredEnvVar(envKey, { name: config.name });
+		},
+		config: {
+			type: "user_managed" as const,
+			name: config.name,
+			authorizationEndpoint: config.authorizationEndpoint,
+			tokenEndpoint: config.tokenEndpoint,
+			scope: config.scope,
+			clientId: config.clientId,
+			clientSecret: config.clientSecret,
+			authorizationParams: config.authorizationParams,
+			callbackUrl: config.callbackUrl,
+			accessTokenExpireMs: config.accessTokenExpireMs,
+		},
+	};
+}
+
+function oauthNameToEnvKey(identifier: string): string {
+	const encoded = Buffer.from(identifier).toString("hex").toUpperCase();
+
+	return `OAUTH_${encoded}_ACCESS_TOKEN`;
+}
+
+function readRequiredEnvVar(key: string, context: { name: string }): string {
+	const value = process.env[key];
+	if (value) {
+		return value;
+	}
+
+	throw new Error(
+		`Missing OAuth access token env var "${key}" (name: "${context.name}"). ` +
+			`Make sure you've completed OAuth for this capability and are running inside the worker runtime.`,
+	);
+}

package/src/capabilities/sync.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import * as Builder from "../builder.js";
+import * as Schema from "../schema.js";
+import { createSyncCapability } from "./sync.js";
+
+describe("Worker.sync", () => {
+	describe("Schema.relation", () => {
+		it("creates a relation property configuration", () => {
+			const relationProp = Schema.relation("projectsSync");
+
+			expect(relationProp).toEqual({
+				type: "relation",
+				relatedSyncKey: "projectsSync",
+				config: { twoWay: false },
+			});
+		});
+
+		it("can be used in a schema definition", () => {
+			const capability = createSyncCapability("tasksSync", {
+				primaryKeyProperty: "Task ID",
+				schema: {
+					defaultName: "Tasks",
+					properties: {
+						"Task ID": Schema.title(),
+						Project: Schema.relation("projectsSync"),
+					},
+				},
+				execute: async () => ({
+					changes: [],
+					hasMore: false,
+				}),
+			});
+
+			expect(capability.config.schema.properties.Project).toEqual({
+				type: "relation",
+				relatedSyncKey: "projectsSync",
+				config: { twoWay: false },
+			});
+		});
+	});
+
+	describe("Builder.relation", () => {
+		it("creates a relation reference from a primary key", () => {
+			const value = Builder.relation("project-123");
+
+			expect(value).toEqual({ type: "primaryKey", value: "project-123" });
+		});
+
+		it("can be used to build relation arrays", () => {
+			const value = [
+				Builder.relation("project-123"),
+				Builder.relation("project-456"),
+			];
+
+			expect(value).toEqual([
+				{ type: "primaryKey", value: "project-123" },
+				{ type: "primaryKey", value: "project-456" },
+			]);
+		});
+	});
+
+	describe("SyncedObject with relation properties", () => {
+		it("allows relation values in synced objects", async () => {
+			const capability = createSyncCapability("tasksSync", {
+				primaryKeyProperty: "Task ID",
+				schema: {
+					defaultName: "Tasks",
+					properties: {
+						"Task ID": Schema.title(),
+						Project: Schema.relation("projectsSync"),
+					},
+				},
+				execute: async () => ({
+					changes: [
+						{
+							type: "upsert",
+							key: "task-1",
+							properties: {
+								"Task ID": Builder.title("TASK-001"),
+								Project: [Builder.relation("project-123")],
+							},
+						},
+						{
+							type: "upsert",
+							key: "task-2",
+							properties: {
+								"Task ID": Builder.title("TASK-002"),
+								Project: [
+									Builder.relation("project-123"),
+									Builder.relation("project-456"),
+								],
+							},
+						},
+					],
+					hasMore: false,
+				}),
+			});
+
+			// Verify the capability is properly configured
+			expect(capability._tag).toBe("sync");
+			expect(capability.config.primaryKeyProperty).toBe("Task ID");
+		});
+	});
+});

package/src/capabilities/sync.ts

@@ -0,0 +1,311 @@
+import { ExecutionError, unreachable } from "../error.js";
+import type {
+	PropertyConfiguration,
+	PropertySchema,
+	Schema,
+} from "../schema.js";
+import type {
+	HandlerOptions,
+	Icon,
+	PeopleValue,
+	PlaceValue,
+	RelationValue,
+	Schedule,
+	SyncSchedule,
+	TextValue,
+	TimeUnit,
+} from "../types.js";
+import type { CapabilityContext } from "./context.js";
+import { createCapabilityContext } from "./context.js";
+
+/**
+ * Maps a property configuration to its corresponding value type.
+ */
+type PropertyValueType<T extends PropertyConfiguration> = T extends {
+	type: "people";
+}
+	? PeopleValue
+	: T extends { type: "place" }
+		? PlaceValue
+		: T extends { type: "relation" }
+			? RelationValue
+			: TextValue;
+
+/**
+ * Sync mode determines how the sync handles data lifecycle.
+ */
+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 `Builder.emojiIcon()`, `Builder.notionIcon()`, or `Builder.imageIcon()` helpers.
+	 */
+	icon?: Icon;
+	/**
+	 * 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, State = unknown> = {
+	/**
+	 * The batch of changes to apply in this execution.
+	 * Can include upserts (create/update) and deletes.
+	 */
+	changes: SyncChange<PK, PropertySchema<PK>>[];
+
+	/**
+	 * Indicates whether there is more data to fetch.
+	 * - `true`: More data available, will trigger another execution with nextState
+	 * - `false`: No more data to fetch, sync is complete
+	 */
+	hasMore: boolean;
+
+	/**
+	 * Optional state data to pass to the next execution.
+	 * 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 as `state` in the next execution.
+	 */
+	nextState?: State;
+};
+
+/**
+ * A configuration object that enables synchronization between a data
+ * source and a third-party source.
+ */
+export type SyncConfiguration<
+	PK extends string,
+	S extends Schema<PK>,
+	State = unknown,
+> = {
+	/**
+	 * The property of the data source that maps to a "primary key" in the
+	 * third-party data. This is used to match existing pages to
+	 * records in the third-party service. Must be a property defined in the schema.
+	 */
+	primaryKeyProperty: PK;
+
+	/**
+	 * The schema defining the structure of properties in the collection.
+	 */
+	schema: S;
+
+	/**
+	 * 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 "replace"
+	 */
+	mode?: SyncMode;
+
+	/**
+	 * How often the sync should run.
+	 * - "continuous": Run as frequently as the system allows
+	 * - Interval string: Run at specified intervals, e.g. "1h", "30m", "1d"
+	 *
+	 * Minimum interval: 1 minute ("1m")
+	 * Maximum interval: 7 days ("7d")
+	 *
+	 * @default "30m"
+	 */
+	schedule?: Schedule;
+
+	/**
+	 * 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 changes with `hasMore: true` and a `nextState`
+	 * 2. The runtime will call execute again with that state
+	 * 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 state - User-defined state from the previous execution (undefined on first call)
+	 * @param context - Runtime context, including Notion client
+	 * @returns A result containing changes, hasMore status, and optional nextState
+	 */
+	execute: (
+		state: State | undefined,
+		context: CapabilityContext,
+	) => Promise<SyncExecutionResult<PK, State>>;
+};
+
+export type SyncCapability = ReturnType<typeof createSyncCapability>;
+
+/**
+ * Runtime context object passed from the runtime to sync capability handlers.
+ */
+type RuntimeContext<UserContext = unknown> = {
+	/** The user-defined/-controlled state (cursor, pagination state, etc.) */
+	state?: UserContext;
+	/** Legacy field for user-defined/-controlled state. */
+	userContext?: UserContext;
+};
+
+/**
+ * Creates a special handler for syncing third-party data to a collection.
+ *
+ * @param syncConfiguration - The configuration for the sync.
+ * @returns A handler function that executes the sync function, and passes data
+ * needed to complete the sync back to the platform.
+ */
+export function createSyncCapability<
+	PK extends string,
+	S extends Schema<PK>,
+	Context = unknown,
+>(key: string, syncConfiguration: SyncConfiguration<PK, S, Context>) {
+	return {
+		_tag: "sync" as const,
+		key,
+		config: {
+			primaryKeyProperty: syncConfiguration.primaryKeyProperty,
+			schema: syncConfiguration.schema,
+			mode: syncConfiguration.mode,
+			schedule: parseSchedule(syncConfiguration.schedule),
+		},
+		async handler(
+			runtimeContext?: RuntimeContext<Context>,
+			options?: HandlerOptions,
+		) {
+			const capabilityContext = createCapabilityContext();
+			const state = runtimeContext?.state ?? runtimeContext?.userContext;
+			const executionResult = await syncConfiguration
+				.execute(state, capabilityContext)
+				.catch((err) => {
+					throw new ExecutionError(err);
+				});
+
+			const result = {
+				changes: executionResult.changes,
+				hasMore: executionResult.hasMore,
+				nextUserContext: executionResult.nextState,
+			};
+
+			if (options?.concreteOutput) {
+				return result;
+			} else {
+				process.stdout.write(`\n<output>${JSON.stringify(result)}</output>\n`);
+			}
+
+			return result;
+		},
+	};
+}
+
+const MS_PER_MINUTE = 60 * 1000;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+
+const MIN_INTERVAL_MS = MS_PER_MINUTE; // 1m
+const MAX_INTERVAL_MS = 7 * MS_PER_DAY; // 7d
+
+const DEFAULT_INTERVAL_MS = 30 * MS_PER_MINUTE; // 30m
+
+/**
+ * Parses a user-friendly schedule string into the normalized backend format.
+ */
+function parseSchedule(schedule: Schedule | undefined): SyncSchedule {
+	if (schedule === "continuous") {
+		return { type: "continuous" };
+	}
+
+	if (!schedule) {
+		return { type: "interval", intervalMs: DEFAULT_INTERVAL_MS };
+	}
+
+	const match = schedule.match(/^(\d+)(m|h|d)$/);
+	if (!match || !match[1] || !match[2]) {
+		throw new Error(
+			`Invalid schedule format: "${schedule}". Use "continuous" or an interval like "30m", "1h", "1d".`,
+		);
+	}
+
+	const value = parseInt(match[1], 10);
+	const unit = match[2] as TimeUnit;
+
+	let intervalMs: number;
+	switch (unit) {
+		case "m":
+			intervalMs = value * MS_PER_MINUTE;
+			break;
+		case "h":
+			intervalMs = value * MS_PER_HOUR;
+			break;
+		case "d":
+			intervalMs = value * MS_PER_DAY;
+			break;
+		default:
+			unreachable(unit);
+	}
+
+	if (intervalMs < MIN_INTERVAL_MS) {
+		throw new Error(
+			`Schedule interval must be at least 1 minute. Got: "${schedule}"`,
+		);
+	}
+	if (intervalMs > MAX_INTERVAL_MS) {
+		throw new Error(
+			`Schedule interval must be at most 7 days. Got: "${schedule}"`,
+		);
+	}
+
+	return { type: "interval", intervalMs };
+}