@notionhq/apps 0.0.13 → 0.0.15

package/src/workflow-types.test.ts

@@ -0,0 +1,144 @@
+import { resolve } from "node:path";
+import ts from "typescript";
+import { expect, it } from "vitest";
+
+it("checks provider keys on callback arguments and returned triggers", () => {
+	const cases = [
+		{
+			name: "valid",
+			valid: true,
+			connections: '[connections.slack({ key: "support" }), connections.calendar()]',
+			trigger:
+				'triggers.slackMessage({ connectionKey: "support" }), triggers.calendarEventCreated({ connectionKey: "calendar" })',
+		},
+		{
+			name: "default",
+			valid: true,
+			connections: "[connections.slack()]",
+			trigger: 'triggers.slackMessage({ connectionKey: "slack" })',
+		},
+		{
+			name: "unbound",
+			valid: true,
+			connections: "[]",
+			trigger: "triggers.slackMessage(), triggers.notionPageCreated()",
+		},
+		{
+			name: "global_valid",
+			valid: true,
+			connections: '[connections.slack({ key: "support" })]',
+			trigger: 'globalTriggers.slackMessage({ connectionKey: "support" })',
+		},
+		{
+			name: "undeclared",
+			valid: false,
+			connections: '[connections.slack({ key: "support" })]',
+			trigger: 'triggers.slackMessage({ connectionKey: "typo" })',
+		},
+		{
+			name: "wrong_provider",
+			valid: false,
+			connections: '[connections.calendar({ key: "support" })]',
+			trigger: 'triggers.slackMessage({ connectionKey: "support" })',
+		},
+		{
+			name: "custom_not_default",
+			valid: false,
+			connections: '[connections.slack({ key: "support" })]',
+			trigger: 'triggers.slackMessage({ connectionKey: "slack" })',
+		},
+		{
+			name: "missing",
+			valid: false,
+			connections: undefined,
+			trigger: 'triggers.slackMessage({ connectionKey: "slack" })',
+		},
+		{
+			name: "global_invalid",
+			valid: false,
+			connections: '[connections.calendar({ key: "support" })]',
+			trigger: 'globalTriggers.slackMessage({ connectionKey: "support" })',
+		},
+		{
+			name: "literal_invalid",
+			valid: false,
+			connections: '[connections.calendar({ key: "support" })]',
+			trigger: '{ type: "slack.message", connectionKey: "support" }',
+		},
+		{
+			name: "generic_without_key",
+			valid: false,
+			connections: '[connections.slack<"support">()]',
+			trigger: 'triggers.slackMessage({ connectionKey: "support" })',
+		},
+		{
+			name: "literal_default",
+			valid: true,
+			connections: '[{ type: "slack" }]',
+			trigger: 'triggers.slackMessage({ connectionKey: "slack" })',
+		},
+		{
+			name: "saved",
+			valid: true,
+			connections: "[support]",
+			trigger: 'triggers.slackMessage({ connectionKey: "support" })',
+		},
+		{
+			name: "saved_invalid",
+			valid: false,
+			connections: "[support]",
+			trigger: 'triggers.slackMessage({ connectionKey: "slack" })',
+		},
+	];
+	const fixtures = new Map(
+		cases.map((testCase) => [
+			resolve("src", `__workflow_types_${testCase.name}.ts`),
+			`import { connections, workflow } from "./workflow.js";
+		import { triggers as globalTriggers } from "./triggers.generated.js";
+		const support = connections.slack({ key: "support" });
+		workflow({
+			name: "Type check", description: "Type check",
+			${testCase.connections === undefined ? "" : `connections: ${testCase.connections},`}
+			triggers: ({ triggers }) => [${testCase.trigger}],
+			handler: () => {},
+		});`,
+		]),
+	);
+	const config = ts.readConfigFile(resolve("tsconfig.json"), ts.sys.readFile);
+	expect(config.error).toBeUndefined();
+	const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, process.cwd());
+	expect(parsed.errors).toEqual([]);
+	const host = ts.createCompilerHost(parsed.options);
+	const getSourceFile = host.getSourceFile.bind(host);
+	host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => {
+		const fixture = fixtures.get(fileName);
+		return fixture === undefined
+			? getSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile)
+			: ts.createSourceFile(fileName, fixture, languageVersion, true);
+	};
+	const program = ts.createProgram(
+		[...fixtures.keys()],
+		{ ...parsed.options, noEmit: true },
+		host,
+	);
+	const diagnostics = ts.getPreEmitDiagnostics(program);
+	const unrelated = diagnostics.filter(
+		(diagnostic) => !diagnostic.file || !fixtures.has(diagnostic.file.fileName),
+	);
+	expect(
+		unrelated.map((diagnostic) =>
+			ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"),
+		),
+	).toEqual([]);
+	for (const testCase of cases) {
+		const errors = diagnostics.filter(
+			(diagnostic) =>
+				diagnostic.file?.fileName ===
+				resolve("src", `__workflow_types_${testCase.name}.ts`),
+		);
+		expect(
+			errors.length === 0,
+			`${testCase.name}: ${errors.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n")).join("\n")}`,
+		).toBe(testCase.valid);
+	}
+}, 30_000);

package/src/workflow.test.ts

@@ -8,7 +8,7 @@ import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi, type Moc
 import { ExecutionError } from "./error.js";
 import type { RunMetadata } from "./runtime-metadata.js";
 import { triggers, type NotionPageCreatedEvent } from "./triggers.generated.js";
-import { connections, createWorkflow, type StepContext, type WorkflowContext } from "./workflow.js";
+import { connections, workflow, type StepContext, type WorkflowContext } from "./workflow.js";
 
 let stdoutSpy: Mock<typeof process.stdout.write>;
 let checkpointDirectory: string | undefined;
@@ -37,9 +37,9 @@ afterEach(async () => {
 
 const event = { type: "notion.page.created" } as NotionPageCreatedEvent;
 
-async function createWorkflowContext(): Promise<WorkflowContext> {
-	let context: WorkflowContext | undefined;
-	const workflow = createWorkflow({
+async function createWorkflowContext(): Promise<WorkflowContext<readonly []>> {
+	let context: WorkflowContext<readonly []> | undefined;
+	const definition = workflow({
 		name: "Test workflow",
 		description: "Captures its workflow context",
 		triggers: [triggers.notionPageCreated()],
@@ -48,7 +48,7 @@ async function createWorkflowContext(): Promise<WorkflowContext> {
 		},
 	});
 
-	await workflow.handler(event, { concreteOutput: true });
+	await definition.handler(event, { concreteOutput: true });
 
 	if (!context) {
 		throw new Error("Workflow context was not created");
@@ -638,7 +638,7 @@ describe("step", () => {
 
 	it("resets duplicate key tracking for each workflow call", async () => {
 		const keys: string[] = [];
-		const workflow = createWorkflow({
+		const definition = workflow({
 			name: "Reuse step key",
 			description: "Checks that a key can be reused in a new invocation",
 			triggers: [triggers.notionPageCreated()],
@@ -654,14 +654,14 @@ describe("step", () => {
 			},
 		});
 
-		await workflow.handler(event, { concreteOutput: true });
-		await workflow.handler(event, { concreteOutput: true });
+		await definition.handler(event, { concreteOutput: true });
+		await definition.handler(event, { concreteOutput: true });
 
 		expect(keys).toEqual([workflowStepKey(["First"]), workflowStepKey(["First"])]);
 	});
 
 	it("writes step events under concreteOutput", async () => {
-		const workflow = createWorkflow({
+		const definition = workflow({
 			name: "Log Pages",
 			description: "Logs created pages",
 			triggers: [triggers.notionPageCreated()],
@@ -670,7 +670,7 @@ describe("step", () => {
 			},
 		});
 
-		await workflow.handler(event, { concreteOutput: true });
+		await definition.handler(event, { concreteOutput: true });
 
 		expect(stdoutSpy).toHaveBeenCalledTimes(3);
 		expect(stdoutSpy.mock.calls[0]?.[0]).toEqual(
@@ -721,17 +721,17 @@ async function writeRunMetadata(overrides: Partial<RunMetadata> = {}): Promise<v
 	process.env.NOTION_RUN_METADATA_PATH = metadataPath;
 }
 
-describe("createWorkflow", () => {
+describe("workflow", () => {
 	it("is tagged and exposes triggers in config", () => {
-		const workflow = createWorkflow({
+		const definition = workflow({
 			name: "Log Pages",
 			description: "Logs created pages",
 			triggers: [triggers.notionPageCreated()],
 			handler: () => {},
 		});
 
-		expect(workflow._tag).toBe("workflow");
-		expect(workflow.config).toEqual({
+		expect(definition._tag).toBe("workflow");
+		expect(definition.config).toEqual({
 			name: "Log Pages",
 			description: "Logs created pages",
 			triggers: [{ type: "notion.page.created" }],
@@ -739,7 +739,7 @@ describe("createWorkflow", () => {
 	});
 
 	it("declares a Calendar connection requirement", () => {
-		const workflow = createWorkflow({
+		const definition = workflow({
 			name: "Schedule Follow-up",
 			description: "Schedules a follow-up after a page is created",
 			triggers: [triggers.notionPageCreated()],
@@ -747,12 +747,12 @@ describe("createWorkflow", () => {
 			handler: () => {},
 		});
 
-		expect(workflow.config.connections).toEqual([{ type: "calendar" }]);
+		expect(definition.config.connections).toEqual([{ type: "calendar" }]);
 	});
 
 	it("rejects duplicate connection requirements", () => {
 		expect(() =>
-			createWorkflow({
+			workflow({
 				name: "Schedule Follow-up",
 				description: "Schedules a follow-up after a page is created",
 				triggers: [triggers.notionPageCreated()],
@@ -764,14 +764,14 @@ describe("createWorkflow", () => {
 
 	it("writes a success envelope after the handler runs", async () => {
 		const handler = vi.fn();
-		const workflow = createWorkflow({
+		const definition = workflow({
 			name: "Log Pages",
 			description: "Logs created pages",
 			triggers: [triggers.notionPageCreated()],
 			handler,
 		});
 
-		await workflow.handler(event);
+		await definition.handler(event);
 
 		expect(handler).toHaveBeenCalledWith(event, expect.anything());
 		expect(stdoutSpy).toHaveBeenCalledWith(
@@ -784,7 +784,7 @@ describe("createWorkflow", () => {
 			throw new Error("Metadata directory was not created");
 		}
 		const handler = vi.fn();
-		const workflow = createWorkflow({
+		const definition = workflow({
 			name: "Log Pages",
 			description: "Logs created pages",
 			triggers: [triggers.notionPageCreated()],
@@ -795,27 +795,27 @@ describe("createWorkflow", () => {
 		await writeFile(inputPath, JSON.stringify(fileEvent));
 		process.env.NOTION_INPUT_PAYLOAD_PATH = inputPath;
 
-		await workflow.handler(event, { concreteOutput: true });
+		await definition.handler(event, { concreteOutput: true });
 
 		expect(handler).toHaveBeenCalledWith(fileEvent, expect.anything());
 	});
 
 	it("returns the status without an envelope under concreteOutput", async () => {
-		const workflow = createWorkflow({
+		const definition = workflow({
 			name: "Log Pages",
 			description: "Logs created pages",
 			triggers: [triggers.notionPageCreated()],
 			handler: () => {},
 		});
 
-		await expect(workflow.handler(event, { concreteOutput: true })).resolves.toEqual({
+		await expect(definition.handler(event, { concreteOutput: true })).resolves.toEqual({
 			status: "success",
 		});
 		expect(stdoutSpy).not.toHaveBeenCalled();
 	});
 
 	it("writes an error envelope and throws ExecutionError on failure", async () => {
-		const workflow = createWorkflow({
+		const definition = workflow({
 			name: "Log Pages",
 			description: "Logs created pages",
 			triggers: [triggers.notionPageCreated()],
@@ -824,7 +824,7 @@ describe("createWorkflow", () => {
 			},
 		});
 
-		await expect(workflow.handler(event)).rejects.toBeInstanceOf(ExecutionError);
+		await expect(definition.handler(event)).rejects.toBeInstanceOf(ExecutionError);
 		expect(stdoutSpy).toHaveBeenCalledWith(
 			expect.stringContaining(
 				`<__notion_output__>{"_tag":"error","error":{"name":"ExecutionError","message":"Error during app execution: Error: boom"`,
@@ -832,3 +832,113 @@ describe("createWorkflow", () => {
 		);
 	});
 });
+
+describe("connection-bound triggers", () => {
+	it("resolves typed trigger callbacks once and preserves event inference", () => {
+		let calls = 0;
+		const definition = workflow({
+			name: "Typed triggers",
+			description: "Uses only declared provider keys",
+			connections: [connections.slack({ key: "support" }), connections.calendar()],
+			triggers: ({ triggers }) => {
+				calls += 1;
+				expectTypeOf(triggers.slackMessage)
+					.parameter(0)
+					.toEqualTypeOf<{ connectionKey: "support" } | undefined>();
+				expectTypeOf(triggers.calendarEventCreated)
+					.parameter(0)
+					.toEqualTypeOf<{ connectionKey: "calendar" } | undefined>();
+				expectTypeOf(triggers.discordInteraction)
+					.parameter(0)
+					.toEqualTypeOf<{ connectionKey: never } | undefined>();
+				return [
+					triggers.slackMessage({ connectionKey: "support" }),
+					triggers.calendarEventCreated({ connectionKey: "calendar" }),
+				];
+			},
+			handler: (event, context) => {
+				expectTypeOf(event.type).toEqualTypeOf<
+					"slack.message" | "calendar.event.created"
+				>();
+				expectTypeOf<keyof typeof context.connections>().toEqualTypeOf<
+					"slack" | "calendar"
+				>();
+			},
+		});
+		expect(calls).toBe(1);
+		expect(definition.config.triggers).toEqual([
+			{ type: "slack.message", connectionKey: "support" },
+			{ type: "calendar.event.created", connectionKey: "calendar" },
+		]);
+	});
+
+	it("preserves the binding in the manifest and infers the event", () => {
+		const definition = workflow({
+			name: "Support",
+			description: "Watch support messages",
+			connections: [connections.slack({ key: "support" })],
+			triggers: [triggers.slackMessage({ connectionKey: "support" })],
+			handler(event) {
+				expectTypeOf(event.type).toEqualTypeOf<"slack.message">();
+			},
+		});
+		expect(definition.config.triggers).toEqual([
+			{ type: "slack.message", connectionKey: "support" },
+		]);
+	});
+	it.each([
+		{ requirements: [] },
+		{ requirements: [connections.calendar({ key: "support" })] },
+		{ requirements: [connections.slack({ key: "other" })] },
+	])("rejects missing or incompatible declarations: %j", ({ requirements }) => {
+		expect(() =>
+			workflow({
+				name: "Support",
+				description: "",
+				connections: requirements,
+				triggers: [triggers.slackMessage({ connectionKey: "support" })],
+				handler() {},
+			}),
+		).toThrow("requires a declared slack connection");
+	});
+	it("rejects duplicate bindings while allowing distinct connections", () => {
+		const configuration = {
+			name: "Support",
+			description: "",
+			connections: [
+				connections.slack({ key: "support" }),
+				connections.slack({ key: "internal" }),
+			],
+			handler() {},
+		};
+		expect(() =>
+			workflow({
+				...configuration,
+				triggers: [
+					triggers.slackMessage({ connectionKey: "support" }),
+					triggers.slackMessage({ connectionKey: "support" }),
+				],
+			}),
+		).toThrow("Duplicate");
+		expect(() =>
+			workflow({
+				...configuration,
+				triggers: [
+					triggers.slackMessage({ connectionKey: "support" }),
+					triggers.slackMessage({ connectionKey: "internal" }),
+				],
+			}),
+		).not.toThrow();
+	});
+	it("preserves existing unkeyed helpers", () => {
+		expect(triggers.slackMessage()).toEqual({ type: "slack.message" });
+		expect(() =>
+			workflow({
+				name: "Existing",
+				description: "",
+				triggers: [triggers.slackMessage()],
+				handler() {},
+			}),
+		).not.toThrow();
+	});
+});

package/src/workflow.ts

@@ -1,3 +1,10 @@
+import {
+	createWorkflowConnections,
+	validateConnectionRequirements,
+	validateTriggerConnections,
+	type WorkflowConnection,
+	type WorkflowConnections,
+} from "./connections.js";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -8,7 +15,13 @@ import { ExecutionError } from "./error.js";
 import { writeOutput } from "./output.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
 import { readRunMetadata, type RunMetadata } from "./runtime-metadata.js";
-import type { WorkflowEventMap, WorkflowTrigger } from "./triggers.generated.js";
+import { createWorkflowTriggers } from "./triggers.generated.js";
+import type {
+	WorkflowEventMap,
+	WorkflowTrigger,
+	WorkflowTriggerCreators,
+	WorkflowTriggerForConnections,
+} from "./triggers.generated.js";
 
 type HandlerOptions = {
 	/** Return the concrete result instead of writing the output envelope. */
@@ -22,24 +35,14 @@ export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMa
 export type WorkflowEventForTriggers<T extends readonly WorkflowTrigger[]> =
 	WorkflowEventForTrigger<T[number]>;
 
-/** A connection that a workflow needs before it can run. */
-export type WorkflowConnection = {
-	type: "calendar";
-};
-
-/** Connection requirements supported by workflow capabilities. */
-export const connections = {
-	/** Require an authorized Calendar connection. */
-	calendar(): WorkflowConnection {
-		return { type: "calendar" };
-	},
-};
+export { connections, type WorkflowConnection, type WorkflowConnections } from "./connections.js";
 
 /**
- * Configuration passed to {@link createWorkflow}.
+ * Configuration passed to {@link workflow}.
  */
 export type WorkflowConfiguration<
 	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+	TConnections extends readonly WorkflowConnection[] = readonly WorkflowConnection[],
 > = {
 	/**
 	 * A human-readable name for the workflow, shown in the UI when viewing workflows
@@ -61,16 +64,24 @@ export type WorkflowConfiguration<
 	/**
 	 * Connections that must be set up before this workflow can run.
 	 */
-	connections?: readonly WorkflowConnection[];
+	connections?: TConnections;
 
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
-		context: WorkflowContext,
+		context: WorkflowContext<TConnections>,
 	) => Promise<void> | void;
 };
 
+/** Configuration that checks trigger keys against declared connections. */
+export type WorkflowTriggerConfiguration<
+	TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+	TConnections extends readonly WorkflowConnection[],
+> = Omit<WorkflowConfiguration<TTriggers, TConnections>, "triggers"> & {
+	triggers: (context: { triggers: WorkflowTriggerCreators<NoInfer<TConnections>> }) => TTriggers;
+};
+
 /**
- * A workflow capability as returned by {@link createWorkflow}.
+ * A workflow capability as returned by {@link workflow}.
  *
  * Note that a workflow carries no key of its own — the build tool derives
  * the capability key from the file the workflow is default-exported from.
@@ -104,9 +115,9 @@ export type Workflow<
  * ```ts
  * // src/workflows/onPageCreated.ts
  * import { triggers } from "@notionhq/apps/triggers";
- * import { createWorkflow } from "@notionhq/apps/workflow";
+ * import { workflow } from "@notionhq/apps/workflow";
  *
- * export default createWorkflow({
+ * export default workflow({
  *   name: "Send Welcome Email",
  *   description: "Sends a welcome email when a new page is added",
  *   triggers: [triggers.notionPageCreated()],
@@ -120,25 +131,38 @@ export type Workflow<
  * });
  * ```
  */
-export function createWorkflow<
+export function workflow<
+	const TTriggers extends readonly [
+		WorkflowTriggerForConnections<NoInfer<TConnections>>,
+		...WorkflowTriggerForConnections<NoInfer<TConnections>>[],
+	],
+	const TConnections extends readonly WorkflowConnection[] = readonly [],
+>(configuration: WorkflowTriggerConfiguration<TTriggers, TConnections>): Workflow<TTriggers>;
+export function workflow<
 	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
->(configuration: WorkflowConfiguration<TTriggers>): Workflow<TTriggers> {
-	if (configuration.connections !== undefined) {
-		const connectionTypes = new Set<string>();
-		for (const connection of configuration.connections) {
-			if (connectionTypes.has(connection.type)) {
-				throw new Error(`Duplicate workflow connection: ${connection.type}`);
-			}
-			connectionTypes.add(connection.type);
-		}
-	}
+	const TConnections extends readonly WorkflowConnection[] = readonly [],
+>(configuration: WorkflowConfiguration<TTriggers, TConnections>): Workflow<TTriggers>;
+export function workflow<
+	const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]],
+	const TConnections extends readonly WorkflowConnection[] = readonly [],
+>(
+	configuration:
+		| WorkflowConfiguration<TTriggers, TConnections>
+		| WorkflowTriggerConfiguration<TTriggers, TConnections>,
+): Workflow<TTriggers> {
+	const triggers =
+		typeof configuration.triggers === "function"
+			? configuration.triggers({ triggers: createWorkflowTriggers<TConnections>() })
+			: configuration.triggers;
+	validateConnectionRequirements(configuration.connections ?? []);
+	validateTriggerConnections(triggers, configuration.connections ?? []);
 
 	return {
 		_tag: "workflow",
 		config: {
 			name: configuration.name,
 			description: configuration.description,
-			triggers: configuration.triggers,
+			triggers,
 			...(configuration.connections === undefined
 				? {}
 				: { connections: configuration.connections }),
@@ -150,8 +174,10 @@ export function createWorkflow<
 			try {
 				event = await resolveRuntimeInput(event);
 				const runMetadata = readRunMetadata();
+				const baseContext = createCapabilityContext();
 				const capabilityContext: WorkflowContext = {
-					...createCapabilityContext(),
+					...baseContext,
+					connections: createWorkflowConnections(baseContext.notion),
 					...runMetadata,
 					step: createStep(runMetadata),
 				};
@@ -213,8 +239,11 @@ type WorkflowStep = {
 };
 
 /** Context passed to a workflow handler. */
-export type WorkflowContext = CapabilityContext &
-	RunMetadata & {
+export type WorkflowContext<
+	TConnections extends readonly WorkflowConnection[] = readonly WorkflowConnection[],
+> = CapabilityContext & {
+	connections: WorkflowConnections<TConnections>;
+} & RunMetadata & {
 		/**
 		 * Run an observable unit of work within the workflow.
 		 *