@notionhq/apps 0.0.15 → 0.0.17

package/skills/workflow/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: workflow
+description: Build or review Notion App workflows for typed triggers, durable replay-safe steps, and idempotent effects.
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Workflow
+
+Use this skill to add or review a workflow in this template.
+
+## Build or change a workflow
+
+1. Read `AGENTS.md` and the existing files in `src/workflows/`.
+2. Inspect the installed workflow and trigger declarations.
+3. Choose the trigger, outcome, step boundaries, and required configuration.
+4. Create one camelCase file directly in `src/workflows/`.
+5. Default-export `workflow(...)` and use typed trigger creators.
+6. Put all non-deterministic work in awaited `context.step(...)` calls.
+7. Give each step a stable display name. For repeated steps, keep the name
+   constant and pass a stable, unique composite `key`, such as
+   `{ key: ["process-page", page.id] }`.
+8. Return JSON-safe values needed by later steps.
+9. Use the step `id` as an idempotency key when supported.
+10. Run `npm run check` and `npm run build`.
+
+Each direct `src/workflows/*.ts` file must default-export `workflow(...)`.
+The camelCase file name becomes its workflow key.
+Keep workflow-specific helpers in `src/workflows/lib/` and shared helpers in
+`src/lib/`; direct children of `src/workflows/` are discovered as workflows.
+
+For provider triggers, follow [trigger connection binding](../connections/SKILL.md#bind-triggers-to-connections).
+Use the typed trigger callback to check `connectionKey` against the declared
+provider connections.
+
+Use a step for every value that can change and every external effect: network
+and Notion API calls, mutable state reads, timestamps, random values, generated
+IDs, messages, creates, and updates. Keep deterministic transforms of the event
+and completed step results outside a step.
+
+Completed steps replay saved results. Do not rely on in-memory mutations inside
+a step. Return the values required by later code. Keep calls in a stable order
+and give every step a stable display name. The name is the replay key by
+default. For a repeated step, do not interpolate an item ID or loop index into
+the name; pass a stable composite key instead:
+
+```ts
+await context.step("Process page", { key: ["process-page", page.id] }, async ({ id }) =>
+	processPage(page, { idempotencyKey: id }),
+);
+```
+
+Keys must be stable across retries and unique within one workflow run.
+
+An external effect can succeed before its step result is saved. Pass the
+callback `id` as an idempotency key when supported; otherwise use a stable
+external ID, upsert, or duplicate check.
+
+Do not write credentials. Add only environment variable names and safe
+placeholders to `.env.example` when configuration is required. Return only
+JSON-serializable step values, throw on failed requests and missing required
+configuration, and do not log secrets or private payloads.
+
+## Resources created with the App
+
+Use [Notion as Code](../notion-as-code/SKILL.md) for pages and databases that
+should be created during deployment. Prefer it over equivalent manual setup
+or API calls that create the App's resources. Use runtime API calls for dynamic
+data changes, not as a substitute for supported Notion as Code setup.
+Keep declarations at module scope in
+an imported helper. For example, declare a guide page in `src/lib/resources.ts`:
+
+```ts
+import { page } from "@notionhq/apps";
+
+export const guide = page({
+	resourceId: "workflow-guide",
+	content: "# Workflow guide\nThis App runs a scheduled workflow.",
+});
+```
+
+Import the module from `src/workflows/sayHello.ts` so the build records it:
+
+```ts
+import "../lib/resources";
+import { workflow } from "@notionhq/apps";
+import { triggers } from "@notionhq/apps/triggers";
+
+export default workflow({
+	name: "Say Hello",
+	description: "Says hello on a recurring schedule.",
+	triggers: [triggers.scheduled()],
+	handler: async (_event, context) => {
+		await context.step("Say hello", () => {
+			console.log("Hello from your workflow!");
+		});
+	},
+});
+```
+
+The page is provisioned during deployment, not on every workflow run.
+Database declarations follow the same import pattern; see the
+[sync example](../sync/SKILL.md#choose-the-database-source) for using a Notion as Code
+data source in a sync. Notion as Code resource IDs are declaration identities, not live
+Notion UUIDs to pass to `context.notion`. Runtime API calls still belong in
+durable steps and need actual resolved Notion IDs.
+
+## Review a workflow
+
+Review every file in `src/workflows/` and the modules it calls. Report each
+finding with its file, line, impact, and fix. Treat these as errors:
+
+1. A workflow is not a direct file or does not default-export `workflow`.
+2. Trigger-specific event fields are used without type narrowing.
+3. Non-deterministic work occurs outside an awaited step.
+4. Step order or names can change between retries.
+5. A step result is not JSON-serializable, or later code needs an in-memory mutation.
+6. A retry-sensitive write lacks an idempotency key or duplicate guard.
+7. External failures are ignored, or credentials are hard-coded or logged.
+8. An explicit trigger connection key is undeclared, belongs to the wrong
+   provider, or repeats the same trigger-type/key pair.
+
+Run `npm run check` and `npm run build` when dependencies are installed.

package/src/cli/build.test.ts

@@ -2,9 +2,101 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, expectTypeOf, it } from "vitest";
 
 import { buildApp } from "./build.js";
+import {
+	notion,
+	type DataSourceHandle,
+	type SingleSourceDatabaseHandle,
+} from "../notion-as-code/index.js";
+import { finishMetadataRecording, startMetadataRecording } from "../notion-as-code/recorder.js";
+
+describe("Notion-as-Code database shorthand", () => {
+	it("keeps provisioning and sync identity equivalent to an explicit source", () => {
+		const recorder = startMetadataRecording();
+		const database = notion.database({
+			resourceId: "issues",
+			name: "Issues",
+			properties: [
+				{ resourceId: "title", name: "Name", type: "title" },
+				{ resourceId: "count", name: "Count", type: "number" },
+			],
+		});
+		expectTypeOf(database).toExtend<
+			SingleSourceDatabaseHandle<typeof database.dataSource.schema>
+		>();
+		expectTypeOf(
+			database.dataSource.database.config.schema.Count.type,
+		).toEqualTypeOf<"number">();
+		database.dataSource.addPage({ resourceId: "issue" });
+		const shorthand = finishMetadataRecording(recorder).intents;
+
+		const explicitRecorder = startMetadataRecording();
+		const explicit = notion.database({
+			resourceId: "issues",
+			name: "Issues",
+			dataSources: [
+				{
+					resourceId: "issues-source",
+					name: "Issues",
+					properties: database.dataSource.schema,
+				},
+			],
+		});
+		explicit.dataSources["issues-source"].addPage({ resourceId: "issue" });
+		// @ts-expect-error Explicit databases do not guarantee a single source.
+		void explicit.dataSource;
+		expect(shorthand).toEqual(finishMetadataRecording(explicitRecorder).intents);
+		expect(database.dataSource.database.key).toBe("issues-source");
+		expect(shorthand[1]).toEqual({
+			type: "page",
+			resourceId: "issue",
+			parent: { type: "resourceId", resourceId: "issues-source" },
+		});
+	});
+
+	it("preserves parent binding and inferred source types through child helpers", () => {
+		const recorder = startMetadataRecording();
+		const page = notion.page({ resourceId: "page" });
+		const team = notion.teamspace({ resourceId: "team", name: "Team", accessLevel: "private" });
+		for (const parent of [page, team]) {
+			const database = parent.addDatabase({
+				resourceId: `${parent.resourceId}-db`,
+				name: "Child",
+				properties: [
+					{ resourceId: `${parent.resourceId}-title`, name: "Title", type: "title" },
+				],
+			});
+			expectTypeOf(database.dataSource).toExtend<
+				DataSourceHandle<typeof database.dataSource.schema>
+			>();
+			expectTypeOf(database.dataSource.schema[0].name).toEqualTypeOf<"Title">();
+		}
+		const intents = finishMetadataRecording(recorder).intents;
+		expect(
+			intents.filter((intent) => intent.type === "database").map((intent) => intent.parent),
+		).toEqual([
+			{ type: "resourceId", resourceId: "page" },
+			{ type: "resourceId", resourceId: "team" },
+		]);
+	});
+
+	it("rejects mixed forms before recording an intent", () => {
+		const recorder = startMetadataRecording();
+		const declareMixedDatabase = () => {
+			// @ts-expect-error The shorthand and explicit forms are mutually exclusive.
+			notion.database({
+				resourceId: "mixed",
+				name: "Mixed",
+				properties: [],
+				dataSources: [],
+			});
+		};
+		expect(declareMixedDatabase).toThrow();
+		expect(finishMetadataRecording(recorder).intents).toEqual([]);
+	});
+});
 
 const FIXTURES = fileURLToPath(new URL("../../test/fixtures/", import.meta.url));
 const EXAMPLES = fileURLToPath(new URL("../../examples/", import.meta.url));
@@ -89,7 +181,7 @@ describe("buildApp", () => {
 					},
 				},
 				{
-					key: "homebase-meetings-source",
+					key: "homebase-meetings-db-source",
 					config: {
 						initialTitle: "Meetings",
 						schema: {
@@ -120,7 +212,7 @@ describe("buildApp", () => {
 					type: "sync",
 					key: "notionAsCodeIssues",
 					config: {
-						databaseKey: "homebase-meetings-source",
+						databaseKey: "homebase-meetings-db-source",
 						primaryKeyProperty: "Meeting ID",
 						mode: "incremental",
 						schedule: { type: "interval", intervalMs: 3_600_000 },

package/src/connections.test.ts

@@ -1,9 +1,10 @@
 import { Client } from "@notionhq/client";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, expectTypeOf, it, vi } from "vitest";
 import {
 	connections,
 	createWorkflowConnections,
-	validateConnectionRequirements,
+	normalizeConnectionRequirements,
+	type WorkflowConnections,
 } from "./connections.js";
 
 afterEach(() => {
@@ -12,37 +13,95 @@ afterEach(() => {
 });
 
 describe("connection requirements", () => {
-	it("declares generated providers", () => {
-		expect(connections.calendar()).toEqual({ type: "calendar" });
-		expect(connections.box({ key: "documents" })).toEqual({ type: "box", key: "documents" });
-		expect(connections.googleDriveOauth()).toEqual({ type: "googleDriveOauth" });
-		expect(connections.discord({ key: "community" })).toEqual({
-			type: "discord",
-			key: "community",
-		});
+	it("normalizes object keys into manifest requirements", () => {
+		expect(
+			normalizeConnectionRequirements({
+				work: connections.calendar(),
+				support: connections.slack(),
+				team: connections.slack(),
+			}),
+		).toEqual([
+			{ type: "calendar", key: "work" },
+			{ type: "slack", key: "support" },
+			{ type: "slack", key: "team" },
+		]);
 	});
-
-	it("rejects duplicate keys across providers", () => {
-		expect(() =>
-			validateConnectionRequirements([
-				connections.calendar({ key: "work" }),
-				connections.slack({ key: "work" }),
-			]),
-		).toThrow("Duplicate");
+	it.each(["bad/key", "__proto__", "constructor", "prototype"])(
+		"rejects invalid or prototype-sensitive keys: %s",
+		(key) => {
+			expect(() => normalizeConnectionRequirements({ [key]: connections.slack() })).toThrow(
+				"Invalid",
+			);
+		},
+	);
+	it("rejects excessive requirements", () => {
+		const requirements: Record<string, { type: string }> = {};
+		for (let i = 0; i < 101; i++) requirements[`team${i}`] = connections.slack();
+		expect(() => normalizeConnectionRequirements(requirements)).toThrow("100");
 	});
-	it("rejects invalid keys and excessive requirements", () => {
-		expect(() =>
-			validateConnectionRequirements([connections.slack({ key: "bad/key" })]),
-		).toThrow("Invalid");
+	it("rejects old arrays and declarations with hidden or inherited keys", () => {
 		expect(() =>
-			validateConnectionRequirements(
-				Array.from({ length: 101 }, (_, i) => connections.slack({ key: `team${i}` })),
-			),
-		).toThrow("100");
+			Reflect.apply(normalizeConnectionRequirements, undefined, [[connections.slack()]]),
+		).toThrow("must be an object");
+		const inherited = { support: connections.slack() };
+		Object.setPrototypeOf(inherited, { hidden: connections.calendar() });
+		expect(() => normalizeConnectionRequirements(inherited)).toThrow("only own");
+		const hidden = { support: connections.slack() };
+		Object.defineProperty(hidden, "hidden", { value: connections.calendar() });
+		expect(() => normalizeConnectionRequirements(hidden)).toThrow("enumerable strings");
+		const symbolic = { [Symbol("support")]: connections.slack() };
+		expect(() => normalizeConnectionRequirements(symbolic)).toThrow("enumerable strings");
+		const legacyDeclaration = { support: { ...connections.slack(), key: "other" } };
+		expect(() => normalizeConnectionRequirements(legacyDeclaration)).toThrow("object property");
 	});
 });
 
 describe("workflow connection runtime", () => {
+	it("invokes separate bindings for multiple keys of the same provider", async () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			JSON.stringify([
+				{ key: "support", type: "slack", id: "support-id" },
+				{ key: "team", type: "slack", id: "team-id" },
+				{ key: "undeclared", type: "slack", id: "hidden-id" },
+			]),
+		);
+		const notion = new Client({ auth: "test" });
+		const request = vi.spyOn(notion, "request").mockResolvedValue({ result: undefined });
+		const declarations = { support: connections.slack(), team: connections.slack() };
+		const runtime = createWorkflowConnections(notion, declarations);
+		Object.assign(declarations, {
+			support: connections.calendar(),
+			injected: connections.slack(),
+		});
+		await runtime.support.findUserByEmail({ email: "support@example.com" });
+		await runtime.team.findUserByEmail({ email: "team@example.com" });
+		expect(request.mock.calls.map(([input]) => input.body)).toEqual([
+			{
+				connection: "support-id",
+				action: "findUserByEmail",
+				args: { email: "support@example.com" },
+			},
+			{
+				connection: "team-id",
+				action: "findUserByEmail",
+				args: { email: "team@example.com" },
+			},
+		]);
+		expect(Object.keys(runtime)).toEqual(["support", "team"]);
+		expect(Reflect.get(runtime, "undeclared")).toBeUndefined();
+		expect(Reflect.get(runtime, "injected")).toBeUndefined();
+		expect(Reflect.get(runtime, "toString")).toBeUndefined();
+		expect(runtime.support).toBe(runtime.support);
+	});
+	it("does not parse missing or malformed bindings until a declared client is used", () => {
+		vi.stubEnv("NOTION_CONNECTION_BINDINGS", "not json");
+		const runtime = createWorkflowConnections(new Client(), { support: connections.slack() });
+		expect(Object.keys(runtime)).toEqual(["support"]);
+		expect(() => runtime.support).toThrow();
+		expect(Object.keys(createWorkflowConnections(new Client(), {}))).toEqual([]);
+	});
+
 	it("preserves pagination through a generated OAuth provider method", async () => {
 		vi.stubEnv(
 			"NOTION_CONNECTION_BINDINGS",
@@ -52,9 +111,9 @@ describe("workflow connection runtime", () => {
 		const request = vi
 			.spyOn(notion, "request")
 			.mockResolvedValue({ result: { files: [], nextPageToken: "next" } });
-		const result = await createWorkflowConnections(notion)
-			.googleDriveOauth("documents")
-			.listFiles({ folderId: "folder", pageToken: "previous" });
+		const result = await createWorkflowConnections(notion, {
+			documents: connections.googleDriveOauth(),
+		}).documents.listFiles({ folderId: "folder", pageToken: "previous" });
 		expect(result.nextPageToken).toBe("next");
 		expect(request).toHaveBeenCalledWith({
 			path: "tools/run/internal",
@@ -73,9 +132,9 @@ describe("workflow connection runtime", () => {
 		);
 		const notion = new Client({ auth: "test" });
 		const request = vi.spyOn(notion, "request").mockResolvedValue({ result: [] });
-		await createWorkflowConnections(notion)
-			.box("documents")
-			.search({ question: "Quarterly report" });
+		await createWorkflowConnections(notion, { documents: connections.box() }).documents.search({
+			question: "Quarterly report",
+		});
 		expect(request).toHaveBeenCalledWith({
 			path: "tools/run/internal",
 			method: "post",
@@ -91,7 +150,9 @@ describe("workflow connection runtime", () => {
 		vi.stubEnv("NOTION_CONNECTION_BINDINGS", '[{"key":"support","type":"calendar","id":"a"}]');
 		const notion = new Client({ auth: "test" });
 		const request = vi.spyOn(notion, "request");
-		expect(() => createWorkflowConnections(notion).slack("support")).toThrow("not slack");
+		expect(
+			() => createWorkflowConnections(notion, { support: connections.slack() }).support,
+		).toThrow("not slack");
 		expect(request).not.toHaveBeenCalled();
 	});
 	it("invokes a typed Calendar method with the default binding", async () => {
@@ -101,7 +162,9 @@ describe("workflow connection runtime", () => {
 		);
 		const notion = new Client({ auth: "test" });
 		const request = vi.spyOn(notion, "request").mockResolvedValue({ result: { accounts: [] } });
-		const result = await createWorkflowConnections(notion).calendar().listCalendars({});
+		const result = await createWorkflowConnections(notion, {
+			calendar: connections.calendar(),
+		}).calendar.listCalendars({});
 		expect(result.accounts).toEqual([]);
 		expect(request).toHaveBeenCalledWith({
 			path: "tools/run/internal",
@@ -117,9 +180,12 @@ describe("workflow connection runtime", () => {
 		);
 		const notion = new Client({ auth: "test" });
 		const request = vi.spyOn(notion, "request").mockResolvedValue({ result: { ok: true } });
-		const runtime = createWorkflowConnections(notion);
+		const runtime = createWorkflowConnections(notion, {
+			support: connections.slack(),
+			team: connections.slack(),
+		});
 		await expect(
-			runtime.slack("support").findUserByEmail({ email: "person@example.com" }),
+			runtime.support.findUserByEmail({ email: "person@example.com" }),
 		).resolves.toEqual({
 			ok: true,
 		});
@@ -132,7 +198,7 @@ describe("workflow connection runtime", () => {
 				args: { email: "person@example.com" },
 			},
 		});
-		expect(() => runtime.slack("slack")).toThrow("not bound");
+		expect(() => runtime.team).toThrow("not bound");
 		expect(request).toHaveBeenCalledTimes(1);
 	});
 	it.each([
@@ -141,17 +207,115 @@ describe("workflow connection runtime", () => {
 		'[{"key":"support","type":"slack","id":"a"},{"key":"support","type":"slack","id":"b"}]',
 	])("rejects malformed or ambiguous bindings: %s", (metadata) => {
 		vi.stubEnv("NOTION_CONNECTION_BINDINGS", metadata);
-		expect(() => createWorkflowConnections(new Client()).slack("support")).toThrow();
+		expect(
+			() => createWorkflowConnections(new Client(), { support: connections.slack() }).support,
+		).toThrow();
 	});
 	it("propagates permission failures without retrying an alternate connection", async () => {
 		vi.stubEnv("NOTION_CONNECTION_BINDINGS", '[{"key":"support","type":"slack","id":"a"}]');
 		const notion = new Client({ auth: "test" });
 		const request = vi.spyOn(notion, "request").mockRejectedValue(new Error("forbidden"));
 		await expect(
-			createWorkflowConnections(notion)
-				.slack("support")
-				.findUserByEmail({ email: "person@example.com" }),
+			createWorkflowConnections(notion, {
+				support: connections.slack(),
+			}).support.findUserByEmail({ email: "person@example.com" }),
 		).rejects.toThrow("forbidden");
 		expect(request).toHaveBeenCalledTimes(1);
 	});
 });
+
+describe("generic OAuth connections", () => {
+	const config = {
+		authorizationEndpoint: "https://github.com/login/oauth/authorize",
+		tokenEndpoint: "https://github.com/login/oauth/access_token",
+		clientId: "client",
+		clientSecretEnv: "GITHUB_CLIENT_SECRET",
+		scope: "repo",
+	};
+	it("declares configuration with a secret reference", () => {
+		expect(connections.oauth(config)).toEqual({ type: "oauth", oauth: config });
+		const declaration = connections.oauth(config);
+		expectTypeOf(declaration.type).toEqualTypeOf<"oauth">();
+		expectTypeOf<
+			keyof WorkflowConnections<{ github: typeof declaration }>
+		>().toEqualTypeOf<"github">();
+		expectTypeOf<keyof WorkflowConnections<Record<never, never>>>().toEqualTypeOf<never>();
+		expect(normalizeConnectionRequirements({ github: declaration })).toEqual([
+			{ type: "oauth", key: "github", oauth: config },
+		]);
+	});
+	it("returns only the token bound to this workflow execution", async () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			JSON.stringify([{ key: "github", type: "oauth", id: "ab-cd" }]),
+		);
+		vi.stubEnv("NOTION_OAUTH_CONNECTION_ABCD", "scoped-token");
+		const notion = new Client({ auth: "test" });
+		const request = vi.spyOn(notion, "request");
+		expect(
+			await createWorkflowConnections(notion, {
+				github: connections.oauth(config),
+			}).github.accessToken(),
+		).toBe("scoped-token");
+		expect(request).not.toHaveBeenCalled();
+		expect(
+			() => createWorkflowConnections(notion, { other: connections.oauth(config) }).other,
+		).toThrow("not bound");
+	});
+	it("keeps separately keyed OAuth tokens isolated and omits undeclared bindings", async () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			JSON.stringify([
+				{ key: "github", type: "oauth", id: "first-id" },
+				{ key: "other", type: "oauth", id: "second-id" },
+				{ key: "undeclared", type: "oauth", id: "hidden-id" },
+			]),
+		);
+		vi.stubEnv("NOTION_OAUTH_CONNECTION_FIRSTID", "first-token");
+		vi.stubEnv("NOTION_OAUTH_CONNECTION_SECONDID", "second-token");
+		const runtime = createWorkflowConnections(new Client({ auth: "test" }), {
+			github: connections.oauth(config),
+			other: connections.oauth(config),
+		});
+		expect(await runtime.github.accessToken()).toBe("first-token");
+		expect(await runtime.other.accessToken()).toBe("second-token");
+		expect(Object.keys(runtime)).toEqual(["github", "other"]);
+		expect(Reflect.get(runtime, "undeclared")).toBeUndefined();
+	});
+
+	it("requires explicit authorization and does not fall back to worker OAuth", async () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			JSON.stringify([{ key: "github", type: "oauth", id: "unconfigured" }]),
+		);
+		vi.stubEnv("OAUTH_676974687562_ACCESS_TOKEN", "global-token");
+		await expect(
+			createWorkflowConnections(new Client({ auth: "test" }), {
+				github: connections.oauth(config),
+			}).github.accessToken(),
+		).rejects.toThrow("requires authorization");
+	});
+	it("rejects a provider connection used as generic OAuth", () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			JSON.stringify([{ key: "github", type: "slack", id: "connection" }]),
+		);
+		expect(
+			() =>
+				createWorkflowConnections(new Client({ auth: "test" }), {
+					github: connections.oauth(config),
+				}).github,
+		).toThrow("not oauth");
+	});
+	it.each(["http://localhost/token", "https://user:password@example.com/token"])(
+		"rejects unsafe token endpoint %s",
+		(tokenEndpoint) => {
+			expect(() => connections.oauth({ ...config, tokenEndpoint })).toThrow("HTTPS URLs");
+		},
+	);
+	it("protects the callback state and PKCE parameters", () => {
+		expect(() =>
+			connections.oauth({ ...config, authorizationParams: { state: "forged" } }),
+		).toThrow("protocol fields");
+	});
+});