@notionhq/apps 0.0.16 → 0.0.18

package/src/sync.ts

@@ -3,8 +3,8 @@ import { createCapabilityContext } from "./context.js";
 import type { Database } from "./database.js";
 import { ExecutionError, RateLimitError } from "./error.js";
 import type { DataSourceHandle } from "./notion-as-code/database.js";
-import type { NotionAsCodeProperty } from "./notion-as-code/intents.js";
-import type { AppsSchemaForProperties } from "./notion-as-code/schema.js";
+import type { NotionAsCodeSchema } from "./notion-as-code/intents.js";
+import type { AppsSchemaForSchema } from "./notion-as-code/schema.js";
 import { writeOutput } from "./output.js";
 import { initPacerState, pacerStates, type PacerEntry } from "./pacer.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
@@ -45,12 +45,50 @@ type PropertyValue<T extends PropertyConfiguration> = T extends { type: "people"
 			? RelationValue
 			: TextValue;
 
+type SyncPropertyName<S extends DatabaseSchema> = Extract<keyof S, string>;
+
+/**
+ * Collect unknown property names across the whole inferred change union before checking it.
+ * Otherwise a valid subset properties object could structurally hide an invalid sibling row.
+ */
+type SyncUnknownPropertyNames<AllowedPropertyNames extends string, Change> = Change extends {
+	type: "upsert";
+	properties: infer Properties extends object;
+}
+	? Exclude<keyof Properties, AllowedPropertyNames>
+	: never;
+
+/** Require at least one key while keeping all other keys optional. */
+type AtLeastOne<T extends object> = Partial<T> &
+	{
+		[RequiredKey in keyof T]-?: Required<Pick<T, RequiredKey>>;
+	}[keyof T];
+
+type SyncUpsertProperties<
+	S extends DatabaseSchema,
+	PrimaryKey extends KeyPropertyName<S>,
+> = AtLeastOne<{
+	[P in Exclude<SyncPropertyName<S>, PrimaryKey>]: PropertyValue<S[P]>;
+}>;
+
+type ExactSyncHandlerResult<
+	AllowedPropertyNames extends string,
+	Result extends { changes: readonly unknown[] },
+> = Result & {
+	changes: [SyncUnknownPropertyNames<AllowedPropertyNames, Result["changes"][number]>] extends [
+		never,
+	]
+		? Result["changes"]
+		: never;
+};
+
 export type SyncMode = "replace" | "incremental";
 
+/** Upsert one or more known non-primary-key properties; the key is supplied separately. */
 export type SyncChangeUpsert<S extends DatabaseSchema, PrimaryKey extends KeyPropertyName<S>> = {
 	type: "upsert";
 	key: string;
-	properties: Omit<{ [P in keyof S]: PropertyValue<S[P]> }, PrimaryKey>;
+	properties: SyncUpsertProperties<S, PrimaryKey>;
 	upstreamUpdatedAt?: string;
 	icon?: Icon;
 	cover?: Cover;
@@ -77,6 +115,11 @@ export type SyncConfiguration<
 	S extends DatabaseSchema,
 	PrimaryKey extends KeyPropertyName<S>,
 	State,
+	Result extends SyncHandlerResult<S, PrimaryKey, State> = SyncHandlerResult<
+		S,
+		PrimaryKey,
+		State
+	>,
 > = {
 	database: Database<S>;
 	primaryKey: PrimaryKey;
@@ -85,25 +128,25 @@ export type SyncConfiguration<
 	handler: (
 		state: State | undefined,
 		context: CapabilityContext,
-	) => Promise<SyncHandlerResult<NoInfer<S>, NoInfer<PrimaryKey>, State>>;
+	) => Promise<
+		// NoInfer prevents handler output from widening the source schema or primary-key inference.
+		SyncHandlerResult<NoInfer<S>, NoInfer<PrimaryKey>, State> &
+			ExactSyncHandlerResult<
+				Exclude<SyncPropertyName<NoInfer<S>>, NoInfer<PrimaryKey>>,
+				Result
+			>
+	>;
 };
 
 /** Configuration for a sync backed by a Notion-as-Code data source. */
 export type DataSourceSyncConfiguration<
-	Properties extends readonly NotionAsCodeProperty[],
-	PrimaryKey extends KeyPropertyName<AppsSchemaForProperties<Properties>>,
+	Schema extends NotionAsCodeSchema,
+	PrimaryKey extends KeyPropertyName<AppsSchemaForSchema<Schema>>,
 	State,
-> = {
-	dataSource: DataSourceHandle<Properties>;
-	primaryKey: PrimaryKey;
-	mode?: SyncMode;
-	schedule?: Schedule;
-	handler: (
-		state: State | undefined,
-		context: CapabilityContext,
-	) => Promise<
-		SyncHandlerResult<NoInfer<AppsSchemaForProperties<Properties>>, NoInfer<PrimaryKey>, State>
-	>;
+	Result extends SyncHandlerResult<AppsSchemaForSchema<Schema>, PrimaryKey, State> =
+		SyncHandlerResult<AppsSchemaForSchema<Schema>, PrimaryKey, State>,
+> = Omit<SyncConfiguration<AppsSchemaForSchema<Schema>, PrimaryKey, State, Result>, "database"> & {
+	dataSource: DataSourceHandle<Schema>;
 };
 
 export type SyncRuntimeContext = {
@@ -160,16 +203,23 @@ export function createSync<
 	const S extends DatabaseSchema,
 	const PrimaryKey extends KeyPropertyName<S>,
 	State = unknown,
->(configuration: SyncConfiguration<S, PrimaryKey, State>): Sync {
+	const Result extends SyncHandlerResult<S, PrimaryKey, State> = SyncHandlerResult<
+		S,
+		PrimaryKey,
+		State
+	>,
+>(configuration: SyncConfiguration<S, PrimaryKey, State, Result>): Sync {
 	return createSyncDefinition(configuration);
 }
 
 /** Create a sync backed by a Notion-as-Code data source. */
 export function sync<
-	const Properties extends readonly NotionAsCodeProperty[],
-	const PrimaryKey extends KeyPropertyName<AppsSchemaForProperties<Properties>>,
+	const Schema extends NotionAsCodeSchema,
+	const PrimaryKey extends KeyPropertyName<AppsSchemaForSchema<Schema>>,
 	State = unknown,
->(configuration: DataSourceSyncConfiguration<Properties, PrimaryKey, State>): Sync {
+	const Result extends SyncHandlerResult<AppsSchemaForSchema<Schema>, PrimaryKey, State> =
+		SyncHandlerResult<AppsSchemaForSchema<Schema>, PrimaryKey, State>,
+>(configuration: DataSourceSyncConfiguration<Schema, PrimaryKey, State, Result>): Sync {
 	return createSyncDefinition(configuration);
 }
 
@@ -199,6 +249,20 @@ function createSyncDefinition<State>(configuration: SyncDefinitionConfiguration<
 					if (change.type === "delete") {
 						return { ...change, targetDatabaseKey: database.key };
 					}
+
+					let hasOwnEnumerableProperty = false;
+					for (const propertyName in change.properties) {
+						if (Object.hasOwn(change.properties, propertyName)) {
+							hasOwnEnumerableProperty = true;
+							break;
+						}
+					}
+					if (!hasOwnEnumerableProperty) {
+						throw new Error(
+							"Sync upsert properties must include at least one property.",
+						);
+					}
+
 					return {
 						...change,
 						properties: {

package/src/triggers.generated.ts

@@ -1,7 +1,7 @@
 // Generated by scripts/generate-triggers.ts — do not edit by hand.
 // Regenerate with: pnpm run generate
 
-import type { WorkflowConnection, WorkflowConnectionKeys } from "./connections.js";
+import type { WorkflowConnectionDeclarations, WorkflowConnectionKeys } from "./connections.js";
 
 import type {
 	CalendarEventCanceledEvent,
@@ -438,7 +438,7 @@ export const triggers = {
 } as const;
 
 /** Trigger creators restricted to the workflow's declared provider keys. */
-export type WorkflowTriggerCreators<TConnections extends readonly WorkflowConnection[]> = {
+export type WorkflowTriggerCreators<TConnections extends WorkflowConnectionDeclarations> = {
 	slackMessage(options?: { connectionKey: WorkflowConnectionKeys<TConnections, "slack"> }): SlackMessageTrigger<WorkflowConnectionKeys<TConnections, "slack">>;
 	slackReactionAdded(options?: { connectionKey: WorkflowConnectionKeys<TConnections, "slack"> }): SlackReactionAddedTrigger<WorkflowConnectionKeys<TConnections, "slack">>;
 	slackAppMention(options?: { connectionKey: WorkflowConnectionKeys<TConnections, "slack"> }): SlackAppMentionTrigger<WorkflowConnectionKeys<TConnections, "slack">>;
@@ -463,7 +463,7 @@ export type WorkflowTriggerCreators<TConnections extends readonly WorkflowConnec
 };
 
 /** Triggers whose connection keys belong to the declared provider. */
-export type WorkflowTriggerForConnections<TConnections extends readonly WorkflowConnection[]> =
+export type WorkflowTriggerForConnections<TConnections extends WorkflowConnectionDeclarations> =
 	| SlackMessageTrigger<WorkflowConnectionKeys<TConnections, "slack">>
 	| SlackReactionAddedTrigger<WorkflowConnectionKeys<TConnections, "slack">>
 	| SlackAppMentionTrigger<WorkflowConnectionKeys<TConnections, "slack">>
@@ -487,7 +487,7 @@ export type WorkflowTriggerForConnections<TConnections extends readonly Workflow
 	| RecurrenceTrigger;
 
 /** @internal */
-export function createWorkflowTriggers<TConnections extends readonly WorkflowConnection[]>(): WorkflowTriggerCreators<TConnections> {
+export function createWorkflowTriggers<TConnections extends WorkflowConnectionDeclarations>(): WorkflowTriggerCreators<TConnections> {
 	return triggers;
 }
 

package/src/workflow-connections-types.test.ts

@@ -1,26 +1,32 @@
 import { expectTypeOf, it } from "vitest";
 import { triggers } from "./triggers.generated.js";
-import { connections, workflow, type WorkflowConnection } from "./workflow.js";
+import { connections, workflow, type WorkflowConnectionDeclarations } from "./workflow.js";
 
 it("infers only the declared provider clients", () => {
 	workflow({
 		name: "Calendar",
 		description: "Calendar only",
 		triggers: [triggers.notionPageCreated()],
-		connections: [connections.calendar({ key: "work" })],
+		connections: { work: connections.calendar() },
 		handler(_event, context) {
-			expectTypeOf<keyof typeof context.connections>().toEqualTypeOf<"calendar">();
-			expectTypeOf(context.connections.calendar).toBeFunction();
+			expectTypeOf<keyof typeof context.connections>().toEqualTypeOf<"work">();
+			expectTypeOf(context.connections.work.listCalendars).toBeFunction();
 		},
 	});
-	const requirements = [connections.calendar(), connections.slack({ key: "support" })];
+	const requirements = {
+		calendar: connections.calendar(),
+		support: connections.slack(),
+		team: connections.slack(),
+	};
 	workflow({
 		name: "Multiple providers",
-		description: "Preserves providers in a separately declared array",
+		description: "Preserves clients in a separately declared object",
 		triggers: [triggers.notionPageCreated()],
 		connections: requirements,
 		handler(_event, context) {
-			expectTypeOf<keyof typeof context.connections>().toEqualTypeOf<"calendar" | "slack">();
+			expectTypeOf<keyof typeof context.connections>().toEqualTypeOf<
+				"calendar" | "support" | "team"
+			>();
 		},
 	});
 });
@@ -38,7 +44,7 @@ it("exposes no providers for omitted or empty connections", () => {
 		name: "No connections",
 		description: "Empty",
 		triggers: [triggers.notionPageCreated()],
-		connections: [],
+		connections: {},
 		handler(_event, context) {
 			expectTypeOf<keyof typeof context.connections>().toEqualTypeOf<never>();
 		},
@@ -46,14 +52,14 @@ it("exposes no providers for omitted or empty connections", () => {
 });
 
 it("preserves literal declarations checked with satisfies", () => {
-	const requirements = [connections.slack()] satisfies readonly WorkflowConnection[];
+	const requirements = { support: connections.slack() } satisfies WorkflowConnectionDeclarations;
 	workflow({
 		name: "Slack",
 		description: "Slack only",
 		triggers: [triggers.notionPageCreated()],
 		connections: requirements,
 		handler(_event, context) {
-			expectTypeOf<keyof typeof context.connections>().toEqualTypeOf<"slack">();
+			expectTypeOf<keyof typeof context.connections>().toEqualTypeOf<"support">();
 		},
 	});
 });

package/src/workflow-state.ts

@@ -0,0 +1,152 @@
+import type { RunMetadata } from "./runtime-metadata.js";
+
+export type WorkflowStateValue =
+	| null
+	| boolean
+	| number
+	| string
+	| ReadonlyArray<WorkflowStateValue>
+	| { readonly [key: string]: WorkflowStateValue };
+
+export type WorkflowState = {
+	get(key: string): Promise<WorkflowStateValue | undefined>;
+	set(key: string, value: WorkflowStateValue | undefined): void;
+};
+
+type WorkflowStateMutation =
+	| { operation: "set"; key: string; value: WorkflowStateValue }
+	| { operation: "delete"; key: string };
+
+type WorkflowStepScope = {
+	id: string;
+	active: boolean;
+	mutations: Map<string, WorkflowStateMutation>;
+};
+
+const MAX_STATE_KEY_BYTES = 256;
+const WORKFLOW_CAPABILITY_KEY_ENV = "NOTION_WORKFLOW_CAPABILITY_KEY";
+
+export function createWorkflowStepState(
+	metadata: Pick<RunMetadata, "workerId">,
+	stepId: string,
+): {
+	state: WorkflowState;
+	run<T>(fn: () => T | Promise<T>): Promise<T>;
+} {
+	const scope: WorkflowStepScope = {
+		id: stepId,
+		active: true,
+		mutations: new Map(),
+	};
+	const state: WorkflowState = {
+		async get(key: string): Promise<WorkflowStateValue | undefined> {
+			requireActiveStep(scope, "get");
+			validateStateKey(key);
+			const pending = scope.mutations.get(key);
+			if (pending?.operation === "set") {
+				return pending.value;
+			}
+			if (pending?.operation === "delete") {
+				return undefined;
+			}
+
+			const response = await requestWorkflowState(metadata, {
+				operation: "get",
+				key,
+			});
+			const body: { exists: boolean; value?: WorkflowStateValue } = JSON.parse(
+				await response.text(),
+			);
+			if (!body.exists) {
+				return undefined;
+			}
+			return body.value;
+		},
+		set(key: string, value: WorkflowStateValue | undefined): void {
+			requireActiveStep(scope, "set");
+			validateStateKey(key);
+			if (value === undefined) {
+				recordMutation(scope, { operation: "delete", key });
+				return;
+			}
+			recordMutation(scope, { operation: "set", key, value });
+		},
+	};
+
+	return {
+		state,
+		async run<T>(fn: () => T | Promise<T>): Promise<T> {
+			try {
+				const result = await fn();
+				if (scope.mutations.size > 0) {
+					await requestWorkflowState(metadata, {
+						operation: "commit",
+						operationId: scope.id,
+						mutations: [...scope.mutations.values()],
+					});
+				}
+				return result;
+			} finally {
+				scope.active = false;
+			}
+		},
+	};
+}
+
+function requireActiveStep(expectedScope: WorkflowStepScope, operation: keyof WorkflowState): void {
+	if (!expectedScope.active) {
+		throw new Error(`state.${operation}() must be called inside context.step().`);
+	}
+}
+
+function recordMutation(scope: WorkflowStepScope, mutation: WorkflowStateMutation): void {
+	scope.mutations.set(mutation.key, mutation);
+}
+
+async function requestWorkflowState(
+	metadata: Pick<RunMetadata, "workerId">,
+	request:
+		| { operation: "get"; key: string }
+		| {
+				operation: "commit";
+				operationId: string;
+				mutations: WorkflowStateMutation[];
+		  },
+): Promise<Response> {
+	const baseUrl = process.env.NOTION_API_BASE_URL;
+	const token = process.env.NOTION_API_TOKEN;
+	const capabilityKey = process.env[WORKFLOW_CAPABILITY_KEY_ENV];
+	if (!baseUrl || !token || !capabilityKey) {
+		throw new Error(
+			`Workflow state is only available when the workflow runtime provides NOTION_API_BASE_URL, NOTION_API_TOKEN, and ${WORKFLOW_CAPABILITY_KEY_ENV}.`,
+		);
+	}
+
+	const response = await fetch(`${baseUrl.replace(/\/$/, "")}/api/v3/workersWorkflowState`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json",
+		},
+		body: JSON.stringify({
+			...request,
+			workerId: metadata.workerId,
+			capabilityKey,
+		}),
+	});
+	if (!response.ok) {
+		throw new Error(
+			`Workflow state ${request.operation} failed with status ${response.status}.`,
+		);
+	}
+	return response;
+}
+
+function validateStateKey(key: string): void {
+	if (key.length === 0) {
+		throw new Error("Workflow state keys must not be empty.");
+	}
+	if (Buffer.byteLength(key) > MAX_STATE_KEY_BYTES) {
+		throw new Error(`Workflow state keys must be at most ${MAX_STATE_KEY_BYTES} UTF-8 bytes.`);
+	}
+}

package/src/workflow-types.test.ts

@@ -7,44 +7,44 @@ it("checks provider keys on callback arguments and returned triggers", () => {
 		{
 			name: "valid",
 			valid: true,
-			connections: '[connections.slack({ key: "support" }), connections.calendar()]',
+			connections: "{ support: connections.slack(), calendar: connections.calendar() }",
 			trigger:
 				'triggers.slackMessage({ connectionKey: "support" }), triggers.calendarEventCreated({ connectionKey: "calendar" })',
 		},
 		{
 			name: "default",
 			valid: true,
-			connections: "[connections.slack()]",
+			connections: "{ slack: connections.slack() }",
 			trigger: 'triggers.slackMessage({ connectionKey: "slack" })',
 		},
 		{
 			name: "unbound",
 			valid: true,
-			connections: "[]",
+			connections: "{}",
 			trigger: "triggers.slackMessage(), triggers.notionPageCreated()",
 		},
 		{
 			name: "global_valid",
 			valid: true,
-			connections: '[connections.slack({ key: "support" })]',
+			connections: "{ support: connections.slack() }",
 			trigger: 'globalTriggers.slackMessage({ connectionKey: "support" })',
 		},
 		{
 			name: "undeclared",
 			valid: false,
-			connections: '[connections.slack({ key: "support" })]',
+			connections: "{ support: connections.slack() }",
 			trigger: 'triggers.slackMessage({ connectionKey: "typo" })',
 		},
 		{
 			name: "wrong_provider",
 			valid: false,
-			connections: '[connections.calendar({ key: "support" })]',
+			connections: "{ support: connections.calendar() }",
 			trigger: 'triggers.slackMessage({ connectionKey: "support" })',
 		},
 		{
 			name: "custom_not_default",
 			valid: false,
-			connections: '[connections.slack({ key: "support" })]',
+			connections: "{ support: connections.slack() }",
 			trigger: 'triggers.slackMessage({ connectionKey: "slack" })',
 		},
 		{
@@ -56,51 +56,123 @@ it("checks provider keys on callback arguments and returned triggers", () => {
 		{
 			name: "global_invalid",
 			valid: false,
-			connections: '[connections.calendar({ key: "support" })]',
+			connections: "{ support: connections.calendar() }",
 			trigger: 'globalTriggers.slackMessage({ connectionKey: "support" })',
 		},
 		{
 			name: "literal_invalid",
 			valid: false,
-			connections: '[connections.calendar({ key: "support" })]',
+			connections: "{ support: connections.calendar() }",
 			trigger: '{ type: "slack.message", connectionKey: "support" }',
 		},
 		{
-			name: "generic_without_key",
+			name: "old_key_option",
 			valid: false,
-			connections: '[connections.slack<"support">()]',
+			connections: '{ support: connections.slack({ key: "support" }) }',
 			trigger: 'triggers.slackMessage({ connectionKey: "support" })',
 		},
 		{
 			name: "literal_default",
 			valid: true,
-			connections: '[{ type: "slack" }]',
+			connections: '{ slack: { type: "slack" } }',
 			trigger: 'triggers.slackMessage({ connectionKey: "slack" })',
 		},
 		{
 			name: "saved",
 			valid: true,
-			connections: "[support]",
+			connections: "{ support }",
 			trigger: 'triggers.slackMessage({ connectionKey: "support" })',
 		},
 		{
 			name: "saved_invalid",
 			valid: false,
-			connections: "[support]",
+			connections: "{ support }",
 			trigger: 'triggers.slackMessage({ connectionKey: "slack" })',
 		},
+		{
+			name: "old_array",
+			valid: false,
+			connections: "[connections.slack()]",
+			trigger: "triggers.slackMessage()",
+		},
+		{
+			name: "two_slack",
+			valid: true,
+			connections: "{ support: connections.slack(), team: connections.slack() }",
+			trigger: 'triggers.slackMessage({ connectionKey: "team" })',
+		},
+
+		{
+			name: "keyed_clients",
+			valid: true,
+			connections:
+				"{ support: connections.slack(), team: connections.slack(), work: connections.calendar() }",
+			trigger: "triggers.notionPageCreated()",
+			handler:
+				'(_event, ctx) => { ctx.connections.support.findUserByEmail({ email: "a@example.com" }); ctx.connections.team.findUserByEmail({ email: "b@example.com" }); ctx.connections.work.listCalendars({}); }',
+		},
+		{
+			name: "wrong_client_method",
+			valid: false,
+			connections: "{ support: connections.slack() }",
+			trigger: "triggers.notionPageCreated()",
+			handler: "(_event, ctx) => { ctx.connections.support.listCalendars({}); }",
+		},
+		{
+			name: "undeclared_client",
+			valid: false,
+			connections: "{ support: connections.slack() }",
+			trigger: "triggers.notionPageCreated()",
+			handler:
+				'(_event, ctx) => { ctx.connections.slack.findUserByEmail({ email: "a@example.com" }); }',
+		},
+		{
+			name: "old_provider_call",
+			valid: false,
+			connections: "{ support: connections.slack() }",
+			trigger: "triggers.notionPageCreated()",
+			handler: '(_event, ctx) => { ctx.connections.support("support"); }',
+		},
+		{
+			name: "oauth_keyed_client",
+			valid: true,
+			connections: "{ github: connections.oauth(oauthConfig), support: connections.slack() }",
+			trigger: 'triggers.slackMessage({ connectionKey: "support" })',
+			handler:
+				"async (_event, ctx) => { const token: string = await ctx.connections.github.accessToken(); void token; }",
+		},
+		{
+			name: "oauth_wrong_trigger",
+			valid: false,
+			connections: "{ github: connections.oauth(oauthConfig) }",
+			trigger: 'triggers.slackMessage({ connectionKey: "github" })',
+		},
+		{
+			name: "oauth_old_key_option",
+			valid: false,
+			connections: '{ github: connections.oauth({ ...oauthConfig, key: "github" }) }',
+			trigger: "triggers.notionPageCreated()",
+		},
+		{
+			name: "oauth_old_provider_call",
+			valid: false,
+			connections: "{ github: connections.oauth(oauthConfig) }",
+			trigger: "triggers.notionPageCreated()",
+			handler: '(_event, ctx) => { ctx.connections.oauth("github"); }',
+		},
 	];
 	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" });
+		const support = connections.slack();
+		const oauthConfig = { authorizationEndpoint: "https://example.com/authorize", tokenEndpoint: "https://example.com/token", clientId: "client", clientSecretEnv: "CLIENT_SECRET", scope: "read" };
 		workflow({
 			name: "Type check", description: "Type check",
 			${testCase.connections === undefined ? "" : `connections: ${testCase.connections},`}
 			triggers: ({ triggers }) => [${testCase.trigger}],
-			handler: () => {},
+			handler: ${testCase.handler ?? "() => {}"},
 		});`,
 		]),
 	);