@notionhq/apps 0.0.13 → 0.0.15

package/src/cli/build.test.ts

@@ -54,9 +54,7 @@ describe("buildApp", () => {
 			},
 		]);
 		const worker = await fs.promises.readFile(bundlePath, "utf8");
-		expect(worker).not.toMatch(
-			/custom_block|createCustomBlock|react|createRoot|NotionCustomBlock/,
-		);
+		expect(worker).not.toMatch(/custom_block|customBlock|react|createRoot|NotionCustomBlock/);
 		expect(fs.existsSync(path.join(root, ".notion/blocks.js"))).toBe(false);
 	});
 	it("names the block file when path is missing", async () => {
@@ -66,7 +64,7 @@ describe("buildApp", () => {
 	});
 	it("rejects a block file that exports a different capability", async () => {
 		await expect(buildApp(fixture("custom-block-wrong-tag"))).rejects.toThrow(
-			/hello.ts.*createCustomBlock/,
+			/hello.ts.*customBlock/,
 		);
 	});
 
@@ -216,6 +214,39 @@ describe("buildApp", () => {
 		});
 	});
 
+	it("removes provisioning when a rebuild no longer declares Notion resources", async () => {
+		const root = await fs.promises.mkdtemp(path.join(FIXTURES, "provisioning-rebuild-"));
+		try {
+			await fs.promises.cp(
+				path.join(FIXTURES, "notion-as-code", "src"),
+				path.join(root, "src"),
+				{
+					recursive: true,
+				},
+			);
+			await buildApp(root);
+			const provisioningPath = path.join(root, "dist", "provisioning.json");
+			const provisioning = JSON.parse(await fs.promises.readFile(provisioningPath, "utf8"));
+			expect(provisioning.intents).toEqual(
+				expect.arrayContaining([expect.objectContaining({ resourceId: "issues-db" })]),
+			);
+
+			await fs.promises.rm(path.join(root, "src"), { recursive: true });
+			await fs.promises.cp(path.join(EXAMPLES, "workflow", "src"), path.join(root, "src"), {
+				recursive: true,
+			});
+			const { manifest } = await buildApp(root);
+			expect(manifest.capabilities).toEqual([
+				expect.objectContaining({ type: "workflow", key: "onPageCreated" }),
+			]);
+			await expect(fs.promises.readFile(provisioningPath)).rejects.toMatchObject({
+				code: "ENOENT",
+			});
+		} finally {
+			await fs.promises.rm(root, { recursive: true, force: true });
+		}
+	});
+
 	it("builds a workflow bundle and manifest", async () => {
 		const { manifest, bundlePath, manifestPath } = await buildApp(example("workflow"));
 

package/src/cli/build.ts

@@ -72,13 +72,14 @@ async function emitProvisioningArtifact(
 	capabilities: readonly DiscoveredCapability[],
 ): Promise<void> {
 	const entityProvisioning = await buildMetadata(projectRoot, capabilities);
-	if (entityProvisioning.intents.length === 0) return;
+	const provisioningPath = path.join(projectRoot, "dist", "provisioning.json");
+	if (entityProvisioning.intents.length === 0) {
+		await fs.promises.rm(provisioningPath, { force: true });
+		return;
+	}
 
 	const artifact = createProvisioningArtifact(entityProvisioning.intents);
-	await fs.promises.writeFile(
-		path.join(projectRoot, "dist", "provisioning.json"),
-		`${JSON.stringify(artifact, null, "\t")}\n`,
-	);
+	await fs.promises.writeFile(provisioningPath, `${JSON.stringify(artifact, null, "\t")}\n`);
 }
 
 /** Bundle capabilities separately to record their Notion-as-Code declarations without shipping them. */

package/src/cli/emit-manifest.ts

@@ -233,7 +233,7 @@ export async function extractManifest(
 		if (!tagged || tagged._tag !== capability.tag) {
 			throw new Error(
 				`${capability.sourcePath}: default export is not a ${capability.type} — ` +
-					`files under this directory must default-export create${capability.type === "custom_block" ? "CustomBlock" : capitalize(capability.type)}(...)`,
+					`files under this directory must default-export ${capability.type === "custom_block" ? "customBlock" : capability.type}(...)`,
 			);
 		}
 
@@ -342,10 +342,6 @@ function getCapabilityRegistry(
 	return bundle.capabilities as Record<string, Record<string, unknown> | 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 manifest configuration fails during the build.

package/src/confluence.generated.ts

@@ -0,0 +1,109 @@
+// Generated by notion tool-core codegen-script-types --connections. Do not edit.
+import type { ConnectionActionInvoker } from "./connection-actions.js"
+/**
+ * Script input for the "Query Confluence with CQL" effect (`confluence.cqlQuery`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Run a CQL query and return results.
+ */
+export type CqlQueryScriptInput = {
+	/**
+	 * CQL query string. Only read-only queries are supported. Example: type=page AND space=DEV AND text~"deployment"
+	 */
+	query: string
+	/**
+	 * Maximum number of results to return. Defaults to 20.
+	 */
+	maxResults?: number
+}
+
+/**
+ * Canonical Tool Core output for the "Query Confluence with CQL" effect (`confluence.cqlQuery`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type CqlQueryScriptOutput = {
+	results: Array<{
+		id: string
+		title: string
+		blocks: Array<string>
+	}>
+	query: string
+	baseUrl: string
+}
+
+/**
+ * Script input for the "Load Confluence page" effect (`confluence.loadPage`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Load a Confluence page by ID.
+ */
+export type LoadPageScriptInput = {
+	/**
+	 * The Confluence page ID to load.
+	 */
+	pageId: string
+}
+
+/**
+ * Canonical Tool Core output for the "Load Confluence page" effect (`confluence.loadPage`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type LoadPageScriptOutput = {
+	type: "confluence-page"
+	title: string
+	blocks: Array<string>
+	pageId: string
+}
+
+/**
+ * Script input for the "Search Confluence" effect (`confluence.search`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Search Confluence via the configured connector.
+ */
+export type SearchScriptInput = {
+	/**
+	 * A single, focused question to search for.
+	 */
+	question: string
+	/**
+	 * Brief keywords capturing the core entities.
+	 */
+	keywords?: string
+	/**
+	 * Optional time window. Use only "default", "all_time", a duration matching /^\d+[dwmy]$/ (for example, "7d", "2w", "3m", or "1y"), or a date in "YYYY-MM-DD" format. Do not use natural-language durations or combine units.
+	 */
+	lookback?: string
+}
+
+/**
+ * Canonical Tool Core output for the "Search Confluence" effect (`confluence.search`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type SearchScriptOutput = {
+	results: Array<{
+		id: string
+		title: string
+		path: string
+		text: string
+		lastEdited: string
+		isPrivate: boolean
+		pageId: string
+	}>
+}
+
+export class ConfluenceConnectionClient {
+	constructor(private readonly invoke: ConnectionActionInvoker) {}
+	cqlQuery(args: CqlQueryScriptInput): Promise<CqlQueryScriptOutput> {
+		return this.invoke<CqlQueryScriptOutput>("cqlQuery", args)
+	}
+	loadPage(args: LoadPageScriptInput): Promise<LoadPageScriptOutput> {
+		return this.invoke<LoadPageScriptOutput>("loadPage", args)
+	}
+	search(args: SearchScriptInput): Promise<SearchScriptOutput> {
+		return this.invoke<SearchScriptOutput>("search", args)
+	}
+}

package/src/connection-actions.ts

@@ -0,0 +1,2 @@
+/** @internal Transport used by generated Tool Core provider clients. */
+export type ConnectionActionInvoker = <Result>(action: string, args: object) => Promise<Result>;

package/src/connection-trigger-definitions.generated.ts

@@ -0,0 +1,48 @@
+// Generated by notion tool-core codegen-script-types --connections. Do not edit.
+export const connectionTriggerDefinitions = [
+	{
+		type: "calendar.event.created",
+		provider: "calendar",
+		description: "Triggers immediately when a calendar event is created",
+	},
+	{
+		type: "calendar.event.updated",
+		provider: "calendar",
+		description: "Triggers immediately when a calendar event is updated",
+	},
+	{
+		type: "calendar.event.canceled",
+		provider: "calendar",
+		description: "Triggers immediately when a calendar event is canceled",
+	},
+	{
+		type: "slack.message",
+		provider: "slack",
+		description:
+			"Triggers immediately after a new message is posted in Slack (includes new threads and replies)",
+	},
+	{
+		type: "slack.reaction.added",
+		provider: "slack",
+		description:
+			"Triggers immediately after a reaction is added to a message in Slack",
+	},
+	{
+		type: "slack.app.mention",
+		provider: "slack",
+		description:
+			"Triggers when the agent is mentioned in a Slack channel or direct message",
+	},
+	{
+		type: "googleDriveOauth.filesChanged",
+		provider: "googleDriveOauth",
+		description:
+			"Watches for file changes in a specific Google Drive folder (direct children only) or shared drive. The My Drive root is not supported. Fires on a schedule and provides change tokens for fetching the list of changes.",
+	},
+	{
+		type: "discord.interaction",
+		provider: "discord",
+		description:
+			"Triggers when a user invokes the /ai slash command in a configured Discord channel",
+	},
+] as const

package/src/connections.test.ts

@@ -0,0 +1,157 @@
+import { Client } from "@notionhq/client";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+	connections,
+	createWorkflowConnections,
+	validateConnectionRequirements,
+} from "./connections.js";
+
+afterEach(() => {
+	vi.unstubAllEnvs();
+	vi.restoreAllMocks();
+});
+
+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("rejects duplicate keys across providers", () => {
+		expect(() =>
+			validateConnectionRequirements([
+				connections.calendar({ key: "work" }),
+				connections.slack({ key: "work" }),
+			]),
+		).toThrow("Duplicate");
+	});
+	it("rejects invalid keys and excessive requirements", () => {
+		expect(() =>
+			validateConnectionRequirements([connections.slack({ key: "bad/key" })]),
+		).toThrow("Invalid");
+		expect(() =>
+			validateConnectionRequirements(
+				Array.from({ length: 101 }, (_, i) => connections.slack({ key: `team${i}` })),
+			),
+		).toThrow("100");
+	});
+});
+
+describe("workflow connection runtime", () => {
+	it("preserves pagination through a generated OAuth provider method", async () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			'[{"key":"documents","type":"googleDriveOauth","id":"drive-id"}]',
+		);
+		const notion = new Client({ auth: "test" });
+		const request = vi
+			.spyOn(notion, "request")
+			.mockResolvedValue({ result: { files: [], nextPageToken: "next" } });
+		const result = await createWorkflowConnections(notion)
+			.googleDriveOauth("documents")
+			.listFiles({ folderId: "folder", pageToken: "previous" });
+		expect(result.nextPageToken).toBe("next");
+		expect(request).toHaveBeenCalledWith({
+			path: "tools/run/internal",
+			method: "post",
+			body: {
+				connection: "drive-id",
+				action: "listFiles",
+				args: { folderId: "folder", pageToken: "previous" },
+			},
+		});
+	});
+	it("uses the configured connector binding without choosing a user in the SDK", async () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			'[{"key":"documents","type":"box","id":"box-id"}]',
+		);
+		const notion = new Client({ auth: "test" });
+		const request = vi.spyOn(notion, "request").mockResolvedValue({ result: [] });
+		await createWorkflowConnections(notion)
+			.box("documents")
+			.search({ question: "Quarterly report" });
+		expect(request).toHaveBeenCalledWith({
+			path: "tools/run/internal",
+			method: "post",
+			body: {
+				connection: "box-id",
+				action: "search",
+				args: { question: "Quarterly report" },
+			},
+		});
+	});
+
+	it("rejects a mismatched provider before sending requests", () => {
+		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(request).not.toHaveBeenCalled();
+	});
+	it("invokes a typed Calendar method with the default binding", async () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			'[{"key":"calendar","type":"calendar","id":"calendar-id"}]',
+		);
+		const notion = new Client({ auth: "test" });
+		const request = vi.spyOn(notion, "request").mockResolvedValue({ result: { accounts: [] } });
+		const result = await createWorkflowConnections(notion).calendar().listCalendars({});
+		expect(result.accounts).toEqual([]);
+		expect(request).toHaveBeenCalledWith({
+			path: "tools/run/internal",
+			method: "post",
+			body: { connection: "calendar-id", action: "listCalendars", args: {} },
+		});
+	});
+
+	it("invokes the exact named binding and unwraps its result", async () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			JSON.stringify([{ key: "support", type: "slack", id: "configured-id" }]),
+		);
+		const notion = new Client({ auth: "test" });
+		const request = vi.spyOn(notion, "request").mockResolvedValue({ result: { ok: true } });
+		const runtime = createWorkflowConnections(notion);
+		await expect(
+			runtime.slack("support").findUserByEmail({ email: "person@example.com" }),
+		).resolves.toEqual({
+			ok: true,
+		});
+		expect(request).toHaveBeenCalledWith({
+			path: "tools/run/internal",
+			method: "post",
+			body: {
+				connection: "configured-id",
+				action: "findUserByEmail",
+				args: { email: "person@example.com" },
+			},
+		});
+		expect(() => runtime.slack("slack")).toThrow("not bound");
+		expect(request).toHaveBeenCalledTimes(1);
+	});
+	it.each([
+		"{}",
+		'[{"key":"support","type":"slack","id":1}]',
+		'[{"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();
+	});
+	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" }),
+		).rejects.toThrow("forbidden");
+		expect(request).toHaveBeenCalledTimes(1);
+	});
+});

package/src/connections.ts

@@ -0,0 +1,126 @@
+import { connectionTriggerDefinitions } from "./connection-trigger-definitions.generated.js";
+import type { WorkflowTrigger } from "./triggers.generated.js";
+import type { Client } from "@notionhq/client";
+import { createConnectionProviders, type ConnectionProviders } from "./providers.generated.js";
+import type { ConnectionActionInvoker } from "./connection-actions.js";
+
+/** A setup requirement. The server decides which providers are available. */
+export type WorkflowConnection<TProvider extends string = string, TKey extends string = string> = {
+	type: TProvider;
+	key?: TKey;
+};
+
+/** Keys declared for one provider in a workflow. */
+export type WorkflowConnectionKeys<
+	TConnections extends readonly WorkflowConnection[],
+	TProvider extends string,
+> = WorkflowConnectionKey<Extract<TConnections[number], { type: TProvider }>>;
+
+type WorkflowConnectionKey<TConnection extends WorkflowConnection> =
+	TConnection extends WorkflowConnection
+		? "key" extends keyof TConnection
+			? Exclude<TConnection["key"], undefined>
+			: TConnection["type"]
+		: never;
+type ConnectionBinding = { key: string; type: string; id: string };
+
+/** Requirements are declarations, not credentials or permission grants. */
+export { connections } from "./providers.generated.js";
+
+export type WorkflowConnections<
+	TConnections extends readonly WorkflowConnection[] = readonly WorkflowConnection[],
+> = Pick<ConnectionProviders, Extract<keyof ConnectionProviders, TConnections[number]["type"]>>;
+
+/** @internal */
+export function validateConnectionRequirements(requirements: readonly WorkflowConnection[]): void {
+	if (requirements.length > 100) throw new Error("Workflows support at most 100 connections.");
+	const keys = new Set<string>();
+	for (const requirement of requirements) {
+		if (!requirement.type) throw new Error("A workflow connection needs a provider type.");
+		const key = requirement.key ?? requirement.type;
+		if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,127}$/.test(key)) {
+			throw new Error("Invalid workflow connection key: " + key);
+		}
+		if (keys.has(key)) throw new Error("Duplicate workflow connection: " + key);
+		keys.add(key);
+	}
+}
+
+/** @internal */
+export function validateTriggerConnections(
+	triggers: readonly WorkflowTrigger[],
+	requirements: readonly WorkflowConnection[],
+): void {
+	const seen = new Set<string>();
+	for (const trigger of triggers) {
+		if (!("connectionKey" in trigger) || trigger.connectionKey === undefined) continue;
+		const requirement = requirements.find(
+			(connection) => (connection.key ?? connection.type) === trigger.connectionKey,
+		);
+		const definition = connectionTriggerDefinitions.find(
+			(definition) => definition.type === trigger.type,
+		);
+		if (!requirement || requirement.type !== definition?.provider) {
+			throw new Error(
+				`Trigger "${trigger.type}" requires a declared ${definition?.provider ?? "supported"} connection: ${trigger.connectionKey}`,
+			);
+		}
+		const identity = JSON.stringify([trigger.type, trigger.connectionKey]);
+		if (seen.has(identity))
+			throw new Error(
+				`Duplicate connection trigger: ${trigger.type} (${trigger.connectionKey})`,
+			);
+		seen.add(identity);
+	}
+}
+
+/** @internal */
+export function createWorkflowConnections(notion: Client): WorkflowConnections {
+	// Capture the execution's bindings; defer parsing so non-connection workflows
+	// remain usable without runtime connection metadata.
+	const rawBindings = process.env.NOTION_CONNECTION_BINDINGS;
+	function resolveBinding(key: string): ConnectionBinding {
+		const bindings: unknown = JSON.parse(rawBindings ?? "[]");
+		if (!Array.isArray(bindings) || !bindings.every(isConnectionBinding)) {
+			throw new Error("Invalid NOTION_CONNECTION_BINDINGS metadata.");
+		}
+		const matches = bindings.filter((binding: ConnectionBinding) => binding.key === key);
+		if (matches.length !== 1 || !matches[0]) {
+			throw new Error(
+				`Workflow connection "${key}" is not bound. Deploy and configure this requirement before running it.`,
+			);
+		}
+		return { ...matches[0] };
+	}
+	function invoker(provider: string, key: string): ConnectionActionInvoker {
+		const binding = resolveBinding(key);
+		if (binding.type !== provider) {
+			throw new Error(`Workflow connection "${key}" is ${binding.type}, not ${provider}.`);
+		}
+		return async <Result>(action: string, args: object): Promise<Result> => {
+			const response = await notion.request<{ result: Result }>({
+				path: "tools/run/internal",
+				method: "post",
+				body: { connection: binding.id, action, args },
+			});
+			return response.result;
+		};
+	}
+	return createConnectionProviders(invoker);
+}
+
+function isConnectionBinding(value: unknown): value is ConnectionBinding {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"key" in value &&
+		typeof value.key === "string" &&
+		value.key.length > 0 &&
+		"type" in value &&
+		typeof value.type === "string" &&
+		value.type.length > 0 &&
+		"id" in value &&
+		typeof value.id === "string" &&
+		value.id.length > 0
+	);
+}

package/src/context.test.ts

@@ -0,0 +1,26 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createCapabilityContext } from "./context.js";
+
+afterEach(() => {
+	delete process.env.NOTION_API_TOKEN;
+	delete process.env.NOTION_WORKFLOW_STEP_DIRECTORY;
+});
+
+describe("createCapabilityContext", () => {
+	it("explains how to configure local Notion API access", () => {
+		const context = createCapabilityContext();
+
+		expect(() => context.notion.pages).toThrow(
+			"NOTION_API_TOKEN is not set. context.notion requires an API token when an app capability runs locally.",
+		);
+	});
+
+	it("explains how to grant deployed workflow access", () => {
+		process.env.NOTION_WORKFLOW_STEP_DIRECTORY = "/tmp/notion-run/steps";
+		const context = createCapabilityContext();
+
+		expect(() => context.notion.pages).toThrow(
+			"Notion API access is not configured for this deployed workflow. In Notion, open Developer Tools → Workers",
+		);
+	});
+});

package/src/context.ts

@@ -13,6 +13,14 @@ const LOCAL_FIX_STEPS =
 	"Deployed apps receive Notion API credentials automatically. Do not push NOTION_API_TOKEN.";
 
 function missingTokenMessage(): string {
+	if (process.env.NOTION_WORKFLOW_STEP_DIRECTORY) {
+		return (
+			"Notion API access is not configured for this deployed workflow. " +
+			"In Notion, open Developer Tools → Workers, select this workflow, and grant access to the pages or databases it uses. " +
+			"The runtime provides NOTION_API_TOKEN automatically after access is configured; do not set or push it yourself."
+		);
+	}
+
 	return (
 		"NOTION_API_TOKEN is not set. " +
 		"context.notion requires an API token when an app capability runs locally." +