@notionhq/apps 0.0.13 → 0.0.14

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, createWorkflow } from "./workflow.js";
+		import { triggers as globalTriggers } from "./triggers.generated.js";
+		const support = connections.slack({ key: "support" });
+		createWorkflow({
+			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

@@ -37,8 +37,8 @@ afterEach(async () => {
 
 const event = { type: "notion.page.created" } as NotionPageCreatedEvent;
 
-async function createWorkflowContext(): Promise<WorkflowContext> {
-	let context: WorkflowContext | undefined;
+async function createWorkflowContext(): Promise<WorkflowContext<readonly []>> {
+	let context: WorkflowContext<readonly []> | undefined;
 	const workflow = createWorkflow({
 		name: "Test workflow",
 		description: "Captures its workflow context",
@@ -832,3 +832,113 @@ describe("createWorkflow", () => {
 		);
 	});
 });
+
+describe("connection-bound triggers", () => {
+	it("resolves typed trigger callbacks once and preserves event inference", () => {
+		let calls = 0;
+		const workflow = createWorkflow({
+			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(workflow.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 workflow = createWorkflow({
+			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(workflow.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(() =>
+			createWorkflow({
+				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(() =>
+			createWorkflow({
+				...configuration,
+				triggers: [
+					triggers.slackMessage({ connectionKey: "support" }),
+					triggers.slackMessage({ connectionKey: "support" }),
+				],
+			}),
+		).toThrow("Duplicate");
+		expect(() =>
+			createWorkflow({
+				...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(() =>
+			createWorkflow({
+				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}.
  */
 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,14 +64,22 @@ 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}.
  *
@@ -120,25 +131,38 @@ export type Workflow<
  * });
  * ```
  */
+export function createWorkflow<
+	const TTriggers extends readonly [
+		WorkflowTriggerForConnections<NoInfer<TConnections>>,
+		...WorkflowTriggerForConnections<NoInfer<TConnections>>[],
+	],
+	const TConnections extends readonly WorkflowConnection[] = readonly [],
+>(configuration: WorkflowTriggerConfiguration<TTriggers, TConnections>): Workflow<TTriggers>;
 export function createWorkflow<
 	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 createWorkflow<
+	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.
 		 *