@notionhq/apps 0.0.4 → 0.0.7

package/src/cli/emit-manifest.ts

@@ -3,13 +3,14 @@ import { pathToFileURL } from "node:url";
 
 import { Ajv } from "ajv";
 
-import type { AppManifest } from "../manifest.js";
+import { APPS_MANIFEST_SCHEMA } from "../manifest.js";
+import type { AppManifest, DatabaseManifestEntry, PacerManifestEntry } from "../manifest.js";
+import { clearRegisteredPacers, registeredPacers } from "../pacer.js";
 import type { DiscoveredCapability } from "./discover.js";
 
 const SDK_VERSION = (() => {
 	const require = createRequire(import.meta.url);
 	const packageJson: unknown = require("../../package.json");
-
 	if (
 		typeof packageJson !== "object" ||
 		packageJson === null ||
@@ -18,23 +19,61 @@ const SDK_VERSION = (() => {
 	) {
 		throw new Error("Failed to read SDK version from package.json");
 	}
-
 	return packageJson.version;
 })();
 
 const MANIFEST_SCHEMA = {
 	type: "object",
 	properties: {
+		$schema: { type: "string", enum: [APPS_MANIFEST_SCHEMA] },
 		sdkVersion: { type: "string" },
-		databases: { type: "array", maxItems: 0 },
+		databases: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					key: { type: "string" },
+					config: {
+						type: "object",
+						properties: {
+							initialTitle: { type: "string" },
+							schema: { type: "object" },
+						},
+						required: ["schema"],
+						additionalProperties: false,
+					},
+				},
+				required: ["key", "config"],
+				additionalProperties: false,
+			},
+		},
 		xldbs: { type: "array", maxItems: 0 },
-		pacers: { type: "array", maxItems: 0 },
+		pacers: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					key: { type: "string" },
+					config: {
+						type: "object",
+						properties: {
+							allowedRequests: { type: "number", exclusiveMinimum: 0 },
+							intervalMs: { type: "number", exclusiveMinimum: 0 },
+						},
+						required: ["allowedRequests", "intervalMs"],
+						additionalProperties: false,
+					},
+				},
+				required: ["key", "config"],
+				additionalProperties: false,
+			},
+		},
 		capabilities: {
 			type: "array",
 			items: {
 				type: "object",
 				properties: {
-					type: { type: "string", const: "workflow" },
+					type: { type: "string", enum: ["workflow", "sync"] },
 					key: { type: "string" },
 					config: {},
 				},
@@ -43,44 +82,204 @@ const MANIFEST_SCHEMA = {
 			},
 		},
 	},
-	required: ["sdkVersion", "databases", "xldbs", "pacers", "capabilities"],
+	required: ["$schema", "sdkVersion", "databases", "xldbs", "pacers", "capabilities"],
 	additionalProperties: false,
 } as const;
 
-type TaggedWorkflow = {
-	_tag: "workflow";
-	config: Record<string, unknown>;
-};
+type TaggedCapability = { _tag: string; config: Record<string, unknown> };
+type DatabaseObject = TaggedCapability & { _tag: "database"; key: string };
+
+function asTagged(value: unknown): TaggedCapability | undefined {
+	if (
+		typeof value === "object" &&
+		value !== null &&
+		"_tag" in value &&
+		typeof value._tag === "string" &&
+		"config" in value &&
+		typeof value.config === "object" &&
+		value.config !== null
+	) {
+		return value as TaggedCapability;
+	}
+	return undefined;
+}
+
+function asDatabase(value: unknown): DatabaseObject | undefined {
+	const tagged = asTagged(value);
+	if (tagged?._tag === "database" && "key" in tagged && typeof tagged.key === "string") {
+		return tagged as DatabaseObject;
+	}
+	return undefined;
+}
+
+function schemaProperties(database: DatabaseObject): Record<string, unknown> {
+	const schema = database.config.schema;
+	if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+		throw new Error(`Database "${database.key}" must have a schema object`);
+	}
+	return schema as Record<string, unknown>;
+}
+
+function isRelationProperty(
+	value: unknown,
+): value is Record<string, unknown> & { database: unknown } {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"type" in value &&
+		value.type === "relation" &&
+		"database" in value
+	);
+}
 
-/** Extract the workflow-only app manifest from a built bundle. */
+class DatabaseCollector {
+	#keys = new Map<unknown, string>();
+	#byKey = new Map<string, DatabaseObject>();
+	#order: string[] = [];
+
+	collect(value: unknown, referencedFrom: string): string {
+		const known = this.#keys.get(value);
+		if (known !== undefined) return known;
+
+		const database = asDatabase(value);
+		if (!database) {
+			throw new Error(
+				`${referencedFrom}: expected a database created with createDatabase(...)`,
+			);
+		}
+		const duplicate = this.#byKey.get(database.key);
+		if (duplicate && duplicate !== database) {
+			throw new Error(`Two distinct databases use the key "${database.key}"`);
+		}
+
+		this.#keys.set(database, database.key);
+		this.#byKey.set(database.key, database);
+		this.#order.push(database.key);
+
+		for (const [propertyName, property] of Object.entries(schemaProperties(database))) {
+			if (isRelationProperty(property)) {
+				this.collect(
+					property.database,
+					`relation property "${propertyName}" of database "${database.key}"`,
+				);
+			}
+		}
+		return database.key;
+	}
+
+	get(key: string): DatabaseObject | undefined {
+		return this.#byKey.get(key);
+	}
+
+	entries(): DatabaseManifestEntry[] {
+		return this.#order.map((key) => {
+			const database = this.#byKey.get(key)!;
+			const properties: Record<string, unknown> = {};
+			for (const [propertyName, property] of Object.entries(schemaProperties(database))) {
+				if (isRelationProperty(property)) {
+					const { database: target, ...rest } = property;
+					properties[propertyName] = {
+						...rest,
+						relatedDatabaseKey: this.#keys.get(target),
+					};
+				} else {
+					properties[propertyName] = property;
+				}
+			}
+
+			return {
+				key,
+				config: {
+					...(typeof database.config.initialTitle === "string"
+						? { initialTitle: database.config.initialTitle }
+						: {}),
+					schema: {
+						properties,
+						...(database.config.databaseIcon === undefined
+							? {}
+							: { databaseIcon: database.config.databaseIcon }),
+						...(database.config.subItems === undefined
+							? {}
+							: { subItems: database.config.subItems }),
+					},
+				},
+			};
+		});
+	}
+}
+
+/** Extract the app manifest from a built bundle. */
 export async function extractManifest(
 	bundlePath: string,
 	capabilities: readonly DiscoveredCapability[],
 ): Promise<AppManifest> {
+	clearRegisteredPacers();
 	const bundle = await importBundle(bundlePath);
-	const capabilityRegistry = getCapabilityRegistry(bundle);
+	const registry = getCapabilityRegistry(bundle);
+	const databases = new DatabaseCollector();
+	const primaryKeyByDatabase = new Map<string, string>();
 
 	const capabilityEntries = capabilities.map((capability) => {
-		const value = capabilityRegistry.workflow?.[capability.key];
-		const workflow = asWorkflow(value);
-
-		if (!workflow) {
+		const tagged = asTagged(registry[capability.type]?.[capability.key]);
+		if (!tagged || tagged._tag !== capability.tag) {
 			throw new Error(
-				`${capability.sourcePath}: default export is not a workflow — ` +
-					`files under src/workflows/ must default-export createWorkflow(...)`,
+				`${capability.sourcePath}: default export is not a ${capability.type} — ` +
+					`files under this directory must default-export create${capitalize(capability.type)}(...)`,
 			);
 		}
 
-		assertJsonSafe(workflow.config, `${capability.sourcePath} config`);
-		return { type: "workflow" as const, key: capability.key, config: workflow.config };
+		let config: Record<string, unknown> = { ...tagged.config };
+		if (capability.type === "sync") {
+			const databaseKey = databases.collect(config.database, capability.sourcePath);
+			const database = databases.get(databaseKey)!;
+			const primaryKey = config.primaryKeyProperty;
+			const property =
+				typeof primaryKey === "string" ? schemaProperties(database)[primaryKey] : undefined;
+			if (
+				typeof primaryKey !== "string" ||
+				typeof property !== "object" ||
+				property === null ||
+				!("type" in property) ||
+				(property.type !== "title" && property.type !== "text")
+			) {
+				throw new Error(
+					`${capability.sourcePath}: primaryKey "${String(primaryKey)}" must name a title or rich-text property`,
+				);
+			}
+
+			const existingPrimaryKey = primaryKeyByDatabase.get(databaseKey);
+			if (existingPrimaryKey !== undefined && existingPrimaryKey !== primaryKey) {
+				throw new Error(
+					`Syncs for database "${databaseKey}" disagree on its primary key: ` +
+						`"${existingPrimaryKey}" and "${primaryKey}"`,
+				);
+			}
+			primaryKeyByDatabase.set(databaseKey, primaryKey);
+			const { database: _database, ...rest } = config;
+			config = { ...rest, databaseKey };
+		}
+
+		assertJsonSafe(config, `${capability.sourcePath} config`);
+		return { type: capability.type, key: capability.key, config };
 	});
 
+	const pacerEntries: PacerManifestEntry[] = registeredPacers().map((pacer) => ({
+		key: pacer.name,
+		config: pacer.config,
+	}));
+	for (const pacer of pacerEntries) assertJsonSafe(pacer.config, `pacer "${pacer.key}" config`);
+	const databaseEntries = databases.entries();
+	for (const database of databaseEntries) {
+		assertJsonSafe(database.config, `database "${database.key}" config`);
+	}
+
 	const manifest: unknown = JSON.parse(
 		JSON.stringify({
+			$schema: APPS_MANIFEST_SCHEMA,
 			sdkVersion: SDK_VERSION,
-			databases: [],
+			databases: databaseEntries,
 			xldbs: [],
-			pacers: [],
+			pacers: pacerEntries,
 			capabilities: capabilityEntries,
 		} satisfies AppManifest),
 	);
@@ -89,7 +288,6 @@ export async function extractManifest(
 	if (!ajv.validate(MANIFEST_SCHEMA, manifest)) {
 		throw new Error(`Generated manifest is invalid: ${ajv.errorsText(ajv.errors)}`);
 	}
-
 	return manifest as AppManifest;
 }
 
@@ -100,9 +298,8 @@ async function importBundle(bundlePath: string): Promise<unknown> {
 		return await import(`${pathToFileURL(bundlePath).href}?import=${importNonce++}`);
 	} catch (error) {
 		throw new Error(
-			`Failed to import built app bundle. Workflow modules must be importable ` +
-				`without secrets or network access — check for top-level code that throws.\n` +
-				`Caused by: ${error instanceof Error ? error.message : String(error)}`,
+			`Failed to import built app bundle. Capability modules must be importable without ` +
+				`secrets or network access. Caused by: ${error instanceof Error ? error.message : String(error)}`,
 		);
 	}
 }
@@ -119,29 +316,16 @@ function getCapabilityRegistry(
 	) {
 		throw new Error("Built app bundle does not export a capability registry");
 	}
-
 	return bundle.capabilities as Record<string, Record<string, unknown> | undefined>;
 }
 
-function asWorkflow(value: unknown): TaggedWorkflow | undefined {
-	if (
-		typeof value === "object" &&
-		value !== null &&
-		"_tag" in value &&
-		value._tag === "workflow" &&
-		"config" in value &&
-		typeof value.config === "object" &&
-		value.config !== null
-	) {
-		return value as TaggedWorkflow;
-	}
-
-	return undefined;
+function capitalize(value: string): string {
+	return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
 }
 
 /**
  * Throw if `value` contains anything `JSON.stringify` would silently drop or
- * rewrite, so invalid workflow configuration fails during the build.
+ * rewrite, so invalid manifest configuration fails during the build.
  */
 export function assertJsonSafe(value: unknown, path: string): void {
 	const reject = (reason: string): never => {
@@ -150,13 +334,9 @@ export function assertJsonSafe(value: unknown, path: string): void {
 
 	switch (typeof value) {
 		case "function":
-			reject("function");
-			break;
 		case "symbol":
-			reject("symbol");
-			break;
 		case "bigint":
-			reject("bigint");
+			reject(typeof value);
 			break;
 		case "number":
 			if (!Number.isFinite(value)) reject(String(value));
@@ -166,9 +346,7 @@ export function assertJsonSafe(value: unknown, path: string): void {
 		case "undefined":
 			return;
 	}
-
 	if (value === null) return;
-
 	if (Array.isArray(value)) {
 		value.forEach((element, index) => {
 			if (element === undefined) reject(`undefined at [${index}]`);
@@ -182,9 +360,7 @@ export function assertJsonSafe(value: unknown, path: string): void {
 	if (prototype !== null && prototype !== Object.prototype) {
 		reject(object.constructor?.name ?? "non-plain object");
 	}
-
 	for (const [key, property] of Object.entries(object as Record<string, unknown>)) {
-		if (property === undefined) continue;
-		assertJsonSafe(property, `${path}.${key}`);
+		if (property !== undefined) assertJsonSafe(property, `${path}.${key}`);
 	}
 }

package/src/context.ts

@@ -6,17 +6,17 @@ export type CapabilityContext = {
 	notion: Client;
 };
 
-const FIX_STEPS =
-	"\n\nTo fix this:\n" +
+const LOCAL_FIX_STEPS =
+	"\n\nFor local execution:\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 apps, run: ntn apps env push";
+	"2. Add NOTION_API_TOKEN=<your-token> to your .env file\n\n" +
+	"Deployed apps receive Notion API credentials automatically. Do not push NOTION_API_TOKEN.";
 
 function missingTokenMessage(): string {
 	return (
 		"NOTION_API_TOKEN is not set. " +
-		"context.notion requires an API token to make requests in workflow capabilities to Notion." +
-		FIX_STEPS
+		"context.notion requires an API token when an app capability runs locally." +
+		LOCAL_FIX_STEPS
 	);
 }
 

package/src/database.ts

@@ -0,0 +1,25 @@
+import type { DatabaseSchema, DatabaseSchemaOptions } from "./schema.js";
+
+export type DatabaseConfiguration<S extends DatabaseSchema = DatabaseSchema> =
+	DatabaseSchemaOptions & {
+		initialTitle?: string;
+		schema: S;
+	};
+
+export type Database<S extends DatabaseSchema = DatabaseSchema> = {
+	_tag: "database";
+	key: string;
+	config: DatabaseConfiguration<S>;
+};
+
+/** Declare a Notion database that a user will attach to this app. */
+export function createDatabase<const S extends DatabaseSchema>(
+	key: string,
+	config: DatabaseConfiguration<S>,
+): Database<S> {
+	if (typeof key !== "string" || key.length === 0) {
+		throw new Error("Database key must be a non-empty string");
+	}
+
+	return { _tag: "database", key, config };
+}

package/src/error.ts

@@ -10,3 +10,14 @@ export class ExecutionError extends Error {
 		this.cause = cause;
 	}
 }
+
+/** Tell the platform that an external service asked the sync to slow down. */
+export class RateLimitError extends ExecutionError {
+	readonly retryAfter: number | undefined;
+
+	constructor(options?: { retryAfter?: number }) {
+		super("Rate limited by external API");
+		this.name = "RateLimitError";
+		this.retryAfter = options?.retryAfter;
+	}
+}

package/src/manifest.ts

@@ -1,5 +1,32 @@
-/** The only capability type supported by this SDK. */
-export type CapabilityType = "workflow";
+import type { NormalizedSchedule } from "./types.js";
+
+/** Identifies the schema used to validate this manifest independently of the SDK package version. */
+export const APPS_MANIFEST_SCHEMA = "notion:apps-manifest:v1" as const;
+
+/** Capability types supported by this SDK. */
+export type CapabilityType = "workflow" | "sync";
+
+export type DatabaseManifestConfig = {
+	initialTitle?: string;
+	schema: unknown;
+};
+
+export type DatabaseManifestEntry = {
+	key: string;
+	config: DatabaseManifestConfig;
+};
+
+export type PacerManifestEntry = {
+	key: string;
+	config: { allowedRequests: number; intervalMs: number };
+};
+
+export type SyncManifestConfig = {
+	databaseKey: string;
+	primaryKeyProperty: string;
+	mode?: "replace" | "incremental";
+	schedule?: NormalizedSchedule;
+};
 
 /**
  * One capability in the manifest: its type, its key (derived from its
@@ -17,10 +44,11 @@ export type CapabilityManifestEntry = {
  * complete, static description of the app.
  */
 export type AppManifest = {
+	$schema: typeof APPS_MANIFEST_SCHEMA;
 	sdkVersion: string;
-	/** Reserved platform fields; workflow-only apps always emit empty arrays. */
-	databases: never[];
+	databases: DatabaseManifestEntry[];
+	/** Reserved platform field; the Apps SDK does not support XLDB. */
 	xldbs: never[];
-	pacers: never[];
+	pacers: PacerManifestEntry[];
 	capabilities: CapabilityManifestEntry[];
 };

package/src/pacer.ts

@@ -0,0 +1,82 @@
+export type PacerConfig = {
+	allowedRequests: number;
+	intervalMs: number;
+};
+
+export type PacerEntry = PacerConfig & { lastScheduledAtMs: number };
+
+export type Pacer = {
+	_tag: "pacer";
+	name: string;
+	config: PacerConfig;
+	wait(): Promise<void>;
+};
+
+const REGISTRY_KEY = Symbol.for("@notionhq/apps/pacer-registry");
+const STATE_KEY = Symbol.for("@notionhq/apps/pacer-state");
+
+function registry(): Map<string, Pacer> {
+	const holder = globalThis as { [REGISTRY_KEY]?: Map<string, Pacer> };
+	holder[REGISTRY_KEY] ??= new Map();
+	return holder[REGISTRY_KEY];
+}
+
+function state(): Map<string, PacerEntry> {
+	const holder = globalThis as { [STATE_KEY]?: Map<string, PacerEntry> };
+	holder[STATE_KEY] ??= new Map();
+	return holder[STATE_KEY];
+}
+
+export function createPacer(name: string, config: PacerConfig): Pacer {
+	if (typeof name !== "string" || name.length === 0) {
+		throw new Error("Pacer name must be a non-empty string");
+	}
+	if (!Number.isFinite(config.allowedRequests) || config.allowedRequests <= 0) {
+		throw new Error("Pacer allowedRequests must be greater than zero");
+	}
+	if (!Number.isFinite(config.intervalMs) || config.intervalMs <= 0) {
+		throw new Error("Pacer intervalMs must be greater than zero");
+	}
+	if (registry().has(name)) {
+		throw new Error(`Two distinct pacers are named "${name}"`);
+	}
+
+	const pacer: Pacer = {
+		_tag: "pacer",
+		name,
+		config,
+		async wait() {
+			const entry = state().get(name) ?? { ...config, lastScheduledAtMs: 0 };
+			const stepMs = Math.ceil(entry.intervalMs / entry.allowedRequests);
+			const now = Date.now();
+			const scheduledAtMs = Math.max(entry.lastScheduledAtMs + stepMs, now);
+			state().set(name, { ...entry, lastScheduledAtMs: scheduledAtMs });
+			if (scheduledAtMs > now) {
+				await new Promise((resolve) => setTimeout(resolve, scheduledAtMs - now));
+			}
+		},
+	};
+	registry().set(name, pacer);
+	return pacer;
+}
+
+/** @internal */
+export function initPacerState(entries: Record<string, PacerEntry> | undefined): void {
+	state().clear();
+	for (const [name, entry] of Object.entries(entries ?? {})) state().set(name, entry);
+}
+
+/** @internal */
+export function pacerStates(): Record<string, PacerEntry> {
+	return Object.fromEntries(state());
+}
+
+/** @internal */
+export function registeredPacers(): Pacer[] {
+	return [...registry().values()];
+}
+
+/** @internal */
+export function clearRegisteredPacers(): void {
+	registry().clear();
+}

package/src/runtime-input.test.ts

@@ -0,0 +1,65 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { resolveRuntimeInput } from "./runtime-input.js";
+
+let inputDirectory: string | undefined;
+
+afterEach(async () => {
+	vi.unstubAllEnvs();
+	if (inputDirectory !== undefined) {
+		await rm(inputDirectory, { recursive: true, force: true });
+		inputDirectory = undefined;
+	}
+});
+
+describe("resolveRuntimeInput", () => {
+	it("returns the inline input when no payload path is configured", async () => {
+		const fallback = { state: { cursor: "inline" } };
+
+		await expect(resolveRuntimeInput(fallback)).resolves.toBe(fallback);
+	});
+
+	it("reads and parses the configured input payload", async () => {
+		const fileInput = { state: { cursor: "file" } };
+		const inputPath = await writeInputPayload(JSON.stringify(fileInput));
+
+		vi.stubEnv("NOTION_INPUT_PAYLOAD_PATH", inputPath);
+
+		await expect(resolveRuntimeInput({ state: { cursor: "inline" } })).resolves.toEqual(
+			fileInput,
+		);
+	});
+
+	it("returns the inline input when the configured payload is missing", async () => {
+		const fallback = { state: { cursor: "inline" } };
+		const directory = await createInputDirectory();
+
+		vi.stubEnv("NOTION_INPUT_PAYLOAD_PATH", join(directory, "missing.json"));
+
+		await expect(resolveRuntimeInput(fallback)).resolves.toBe(fallback);
+	});
+
+	it("rejects malformed input payloads", async () => {
+		const inputPath = await writeInputPayload("{");
+
+		vi.stubEnv("NOTION_INPUT_PAYLOAD_PATH", inputPath);
+
+		await expect(resolveRuntimeInput(undefined)).rejects.toBeInstanceOf(SyntaxError);
+	});
+});
+
+async function writeInputPayload(contents: string): Promise<string> {
+	const directory = await createInputDirectory();
+	const inputPath = join(directory, "input.json");
+	await writeFile(inputPath, contents);
+	return inputPath;
+}
+
+async function createInputDirectory(): Promise<string> {
+	inputDirectory = await mkdtemp(join(tmpdir(), "notion-apps-input-"));
+	return inputDirectory;
+}

package/src/runtime-input.ts

@@ -0,0 +1,30 @@
+import { readFile } from "node:fs/promises";
+
+/**
+ * Resolve a capability input from the sandbox input payload when configured.
+ *
+ * The input argument remains the fallback for compatibility with runners
+ * that have not adopted the file-backed transport.
+ *
+ * @internal
+ */
+export async function resolveRuntimeInput<T>(fallback: T): Promise<T> {
+	const inputPayloadPath = process.env.NOTION_INPUT_PAYLOAD_PATH;
+	if (inputPayloadPath === undefined) {
+		return fallback;
+	}
+
+	let serializedInput: string;
+
+	try {
+		serializedInput = await readFile(inputPayloadPath, "utf8");
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+			return fallback;
+		}
+
+		throw error;
+	}
+
+	return JSON.parse(serializedInput) as T;
+}