@notionhq/apps 0.0.12 → 0.0.14

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/cursor.generated.ts

@@ -0,0 +1,167 @@
+// Generated by notion tool-core codegen-script-types --connections. Do not edit.
+import type { ConnectionActionInvoker } from "./connection-actions.js"
+/**
+ * Script input for the "Create Cursor agent" effect (`cursor.createAgent`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Create a new Cursor agent
+ */
+export type CreateAgentScriptInput = {
+	/**
+	 * What you want the agent to do
+	 */
+	prompt: string
+	/**
+	 * GitHub repository URL or owner/repo format (e.g. 'owner/repo' or 'https://github.com/owner/repo')
+	 */
+	repository: string
+	/**
+	 * Optional branch or ref to work from (e.g. 'main', 'develop')
+	 */
+	ref?: string
+	/**
+	 * Custom branch name for the agent to create in the target repository.
+	 */
+	branchName?: string
+	/**
+	 * Whether to open the pull request as the Cursor GitHub App instead of as the user (default: true). Only applies when a PR is auto-created.
+	 */
+	openAsCursorGithubApp?: boolean
+	/**
+	 * Whether to skip adding the user as a reviewer on the pull request. Only applies if autoCreatePr is true and the PR is opened as the Cursor GitHub App (default: false).
+	 */
+	skipReviewerRequest?: boolean
+	webhook?: {
+		/**
+		 * Webhook URL to receive agent status updates.
+		 */
+		url: string
+		/**
+		 * Optional shared secret for verifying webhook signatures.
+		 */
+		secret?: string
+	}
+}
+
+/**
+ * Canonical Tool Core output for the "Create Cursor agent" effect (`cursor.createAgent`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type CreateAgentScriptOutput = {
+	id: string
+	name: string
+	/**
+	 * One of: `CREATING`, `RUNNING`, `FINISHED`, `ERROR`, `EXPIRED`
+	 */
+	status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "EXPIRED"
+	source: {
+		repository: string
+		ref?: string
+	}
+	target: {
+		url: string
+		prUrl?: string
+		branchName?: string
+		autoCreatePr?: boolean
+		autoBranch?: boolean
+		openAsCursorGithubApp?: boolean
+		skipReviewerRequest?: boolean
+	}
+	createdAt: string
+	summary?: string
+	conversation?: {
+		id: string
+		messages: Array<{
+			id: string
+			type: string
+			text: string
+		}>
+	}
+}
+
+/**
+ * Script input for the "Get Cursor agent" effect (`cursor.getAgent`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Get a Cursor agent by ID
+ */
+export type GetAgentScriptInput = {
+	/**
+	 * The ID of the Cursor agent to get (e.g. 'agent-123')
+	 */
+	agentId: string
+}
+
+/**
+ * Canonical Tool Core output for the "Get Cursor agent" effect (`cursor.getAgent`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type GetAgentScriptOutput = {
+	id: string
+	name: string
+	/**
+	 * One of: `CREATING`, `RUNNING`, `FINISHED`, `ERROR`, `EXPIRED`
+	 */
+	status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "EXPIRED"
+	source: {
+		repository: string
+		ref?: string
+	}
+	target: {
+		url: string
+		prUrl?: string
+		branchName?: string
+		autoCreatePr?: boolean
+		autoBranch?: boolean
+		openAsCursorGithubApp?: boolean
+		skipReviewerRequest?: boolean
+	}
+	createdAt: string
+	summary?: string
+	conversation?: {
+		id: string
+		messages: Array<{
+			id: string
+			type: string
+			text: string
+		}>
+	}
+}
+
+/**
+ * Script input for the "List Cursor repositories" effect (`cursor.listRepositories`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * List accessible Cursor repositories
+ */
+export type ListRepositoriesScriptInput = Record<string, never>
+
+/**
+ * Canonical Tool Core output for the "List Cursor repositories" effect (`cursor.listRepositories`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type ListRepositoriesScriptOutput = {
+	repositories: Array<{
+		owner: string
+		name: string
+		repository: string
+	}>
+}
+
+export class CursorConnectionClient {
+	constructor(private readonly invoke: ConnectionActionInvoker) {}
+	createAgent(args: CreateAgentScriptInput): Promise<CreateAgentScriptOutput> {
+		return this.invoke<CreateAgentScriptOutput>("createAgent", args)
+	}
+	getAgent(args: GetAgentScriptInput): Promise<GetAgentScriptOutput> {
+		return this.invoke<GetAgentScriptOutput>("getAgent", args)
+	}
+	listRepositories(
+		args: ListRepositoriesScriptInput,
+	): Promise<ListRepositoriesScriptOutput> {
+		return this.invoke<ListRepositoriesScriptOutput>("listRepositories", args)
+	}
+}

package/src/custom-block.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { createCustomBlock } from "./custom-block.js";
+
+describe("createCustomBlock", () => {
+	it("supports static assets without a build command", () => {
+		expect(createCustomBlock({ path: "assets", static: true }).config.source).toEqual({
+			type: "static",
+			path: "assets",
+		});
+	});
+	it.each(["//hello", "Hello", "-hello", "", "a".repeat(65)])(
+		"rejects invalid slash command %s",
+		(slashCommand) => {
+			expect(() => createCustomBlock({ path: "blocks/hello", slashCommand })).toThrow(
+				/slashCommand/,
+			);
+		},
+	);
+});

package/src/custom-block.ts

@@ -0,0 +1,41 @@
+import type { ManifestDataSource } from "@notionhq/custom-blocks";
+
+export type CustomBlockOptions = {
+	path: string;
+	slashCommand?: string;
+	dataSources?: Record<string, ManifestDataSource>;
+} & (
+	| { static: true; command?: never; output?: never }
+	| { static?: false; command?: string; output?: string }
+);
+
+/** Declare a browser project. Its filename under src/customBlocks supplies its key. */
+export function createCustomBlock(options: CustomBlockOptions) {
+	if (typeof options.path !== "string" || options.path.trim() === "") {
+		throw new Error("createCustomBlock requires a non-empty path relative to the app root");
+	}
+	const slashCommand = options.slashCommand?.replace(/^\//, "");
+	if (slashCommand !== undefined && !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(slashCommand)) {
+		throw new Error(
+			"Custom block slashCommand must be 1–64 lowercase letters, numbers, hyphens or underscores, starting with a letter or number",
+		);
+	}
+	return {
+		_tag: "custom_block" as const,
+		config: {
+			source: options.static
+				? { type: "static" as const, path: options.path }
+				: {
+						type: "project" as const,
+						path: options.path,
+						command: options.command ?? "npx vite build",
+						output: options.output ?? "dist",
+					},
+			manifest: {
+				version: 1 as const,
+				...(slashCommand === undefined ? {} : { slashCommand }),
+				dataSources: options.dataSources ?? {},
+			},
+		},
+	};
+}

package/src/custom-blocks.ts

@@ -0,0 +1 @@
+export * from "@notionhq/custom-blocks";