@notionhq/apps 0.0.1

package/src/context.ts

@@ -0,0 +1,49 @@
+import { Client } from "@notionhq/client";
+import type { ClientOptions } from "@notionhq/client/build/src/Client.js";
+
+export type CapabilityContext = {
+	/** Notion API SDK client for this execution. */
+	notion: Client;
+};
+
+const FIX_STEPS =
+	"\n\nTo fix this:\n" +
+	"1. Create a personal access token at https://app.notion.com/developers/tokens\n" +
+	"2. Add NOTION_API_TOKEN=<your-token> to your .env file\n" +
+	"3. For deployed apps, run: ntn apps env push";
+
+function missingTokenMessage(): string {
+	return (
+		"NOTION_API_TOKEN is not set. " +
+		"context.notion requires an API token to make requests in workflow capabilities to Notion." +
+		FIX_STEPS
+	);
+}
+
+function createUnauthenticatedNotionProxy(): Client {
+	return new Proxy({} as Client, {
+		get(_target, prop) {
+			if (prop === "then" || typeof prop === "symbol") {
+				return undefined;
+			}
+			throw new Error(missingTokenMessage());
+		},
+	});
+}
+
+export function createCapabilityContext(): CapabilityContext {
+	const options: ClientOptions = {};
+
+	if (process.env.NOTION_API_BASE_URL) {
+		options.baseUrl = process.env.NOTION_API_BASE_URL;
+	}
+
+	if (!process.env.NOTION_API_TOKEN) {
+		return { notion: createUnauthenticatedNotionProxy() };
+	}
+
+	options.auth = process.env.NOTION_API_TOKEN;
+	const notion = new Client(options);
+
+	return { notion };
+}

package/src/error.ts

@@ -0,0 +1,12 @@
+/**
+ * An error that occurred during the execution of an app capability.
+ */
+export class ExecutionError extends Error {
+	override readonly cause: unknown;
+
+	constructor(cause: unknown) {
+		super(`Error during app execution: ${cause}`);
+		this.name = "ExecutionError";
+		this.cause = cause;
+	}
+}

package/src/manifest.ts

@@ -0,0 +1,26 @@
+/** The only capability type supported by this SDK. */
+export type CapabilityType = "workflow";
+
+/**
+ * One capability in the manifest: its type, its key (derived from its
+ * filename), and its handler-free configuration.
+ */
+export type CapabilityManifestEntry = {
+	type: CapabilityType;
+	key: string;
+	config: unknown;
+};
+
+/**
+ * The full app manifest, emitted by `notion-apps build` as
+ * `dist/manifest.json` and read by the platform at deploy time. This is a
+ * complete, static description of the app.
+ */
+export type AppManifest = {
+	sdkVersion: string;
+	/** Reserved platform fields; workflow-only apps always emit empty arrays. */
+	databases: never[];
+	xldbs: never[];
+	pacers: never[];
+	capabilities: CapabilityManifestEntry[];
+};

package/src/output.ts

@@ -0,0 +1,8 @@
+/**
+ * Writes a notion_output envelope to stdout using the shared wire format.
+ * The platform runner scans a run's log stream for this envelope to
+ * recover the capability's result.
+ */
+export function writeOutput(value: unknown): void {
+	process.stdout.write(`\n<__notion_output__>${JSON.stringify(value)}</__notion_output__>\n`);
+}

package/src/runtime-metadata.test.ts

@@ -0,0 +1,54 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { readRunMetadata } from "./runtime-metadata.js";
+
+const temporaryDirectories: string[] = [];
+
+function temporaryPath(name: string): string {
+	const directory = fs.mkdtempSync(path.join(os.tmpdir(), "notion-apps-metadata-"));
+	temporaryDirectories.push(directory);
+	return path.join(directory, name);
+}
+
+afterEach(() => {
+	vi.unstubAllEnvs();
+	for (const directory of temporaryDirectories.splice(0)) {
+		fs.rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+describe("readRunMetadata", () => {
+	it("throws when the metadata path is not configured", () => {
+		vi.stubEnv("NOTION_RUN_METADATA_PATH", undefined);
+
+		expect(() => readRunMetadata()).toThrow("Workflow run metadata path is not configured");
+	});
+
+	it("reads workflow run metadata", () => {
+		const metadataPath = temporaryPath("metadata.json");
+		const metadata = {
+			workspaceId: "workspace-id",
+			workerId: "worker-id",
+			runGroupId: "run-group-id",
+			runId: "run-id",
+			capabilityType: "workflow" as const,
+			attemptNumber: 2,
+		};
+		fs.writeFileSync(metadataPath, JSON.stringify(metadata));
+		vi.stubEnv("NOTION_RUN_METADATA_PATH", metadataPath);
+
+		expect(readRunMetadata()).toEqual(metadata);
+	});
+
+	it("rejects invalid workflow run metadata", () => {
+		const metadataPath = temporaryPath("metadata.json");
+		fs.writeFileSync(metadataPath, JSON.stringify({ runId: "run-id" }));
+		vi.stubEnv("NOTION_RUN_METADATA_PATH", metadataPath);
+
+		expect(() => readRunMetadata()).toThrow("Invalid workflow run metadata");
+	});
+});

package/src/runtime-metadata.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+
+import { Ajv, type JSONSchemaType } from "ajv";
+
+export type RunMetadata = {
+	workspaceId: string;
+	workerId: string;
+	runGroupId: string;
+	runId: string;
+	capabilityType: "workflow";
+	attemptNumber: number;
+};
+
+const runMetadataSchema: JSONSchemaType<RunMetadata> = {
+	type: "object",
+	properties: {
+		workspaceId: { type: "string" },
+		workerId: { type: "string" },
+		runGroupId: { type: "string" },
+		runId: { type: "string" },
+		capabilityType: { type: "string", const: "workflow" },
+		attemptNumber: { type: "number" },
+	},
+	required: ["workspaceId", "workerId", "runGroupId", "runId", "capabilityType", "attemptNumber"],
+	additionalProperties: false,
+};
+
+const ajv = new Ajv();
+const validateRunMetadata = ajv.compile(runMetadataSchema);
+
+/** @internal */
+export function readRunMetadata(): RunMetadata {
+	const runMetadataPath = process.env.NOTION_RUN_METADATA_PATH;
+	if (runMetadataPath === undefined) {
+		throw new Error("Workflow run metadata path is not configured");
+	}
+
+	const parsed: unknown = JSON.parse(readFileSync(runMetadataPath, "utf8"));
+	if (!validateRunMetadata(parsed)) {
+		throw new Error(
+			`Invalid workflow run metadata: ${ajv.errorsText(validateRunMetadata.errors)}`,
+		);
+	}
+
+	return parsed;
+}

package/src/triggers.generated.ts

@@ -0,0 +1,489 @@
+// Generated by scripts/generate-triggers.ts — do not edit by hand.
+// Regenerate with: pnpm run generate
+
+import type {
+	CalendarEventCanceledEvent,
+	CalendarEventCreatedEvent,
+	CalendarEventUpdatedEvent,
+	DiscordInteractionEvent,
+	GoogleDriveOauthFilesChangedEvent,
+	MailEmailReceivedEvent,
+	MailEmailSentEvent,
+	MailLabelAppliedEvent,
+	NotionAgentMentionedEvent,
+	NotionButtonPressedEvent,
+	NotionCommentAddedEvent,
+	NotionDatabaseAgentUpdatedEvent,
+	NotionMeetingNoteSummaryCompletedEvent,
+	NotionPageCreatedEvent,
+	NotionPageDeletedEvent,
+	NotionPageUpdatedEvent,
+	RecurrenceEvent,
+	SlackAppMentionEvent,
+	SlackMessageEvent,
+	SlackReactionAddedEvent,
+	WebhookEvent,
+} from "./triggers.js";
+
+export type {
+	Actor,
+	ActorLike,
+	CalendarEventCanceledEvent,
+	CalendarEventCreatedEvent,
+	CalendarEventLike,
+	CalendarEventUpdatedEvent,
+	ChatMessageLike,
+	ChatThreadMessage,
+	DiscordChatThreadMessage,
+	DiscordInteractionEvent,
+	EmailMessageLike,
+	EmailThreadLike,
+	EmailTriggerMessage,
+	GoogleDriveOauthFilesChangedEvent,
+	LinkLike,
+	MailEmailReceivedEvent,
+	MailEmailSentEvent,
+	MailLabelAppliedEvent,
+	MessageLike,
+	NotionAgentMentionedEvent,
+	NotionButtonPressedEvent,
+	NotionCommentAddedEvent,
+	NotionDatabaseAgentUpdatedEvent,
+	NotionMeetingNoteSummaryCompletedEvent,
+	NotionPageCreatedEvent,
+	NotionPageDeletedEvent,
+	NotionPageEdit,
+	NotionPageUpdatedEvent,
+	RecurrenceEvent,
+	RecurrenceFrequency,
+	SlackAppMentionEvent,
+	SlackChatThreadMessage,
+	SlackMessageEvent,
+	SlackReactionAddedEvent,
+	ThreadLike,
+	ThreadMessage,
+	TimestampLike,
+	TriggerEvent,
+	TriggerEventBase,
+	TriggerEventMap,
+	TriggerType,
+	VendorActor,
+	VendorExtensions,
+	WebhookEvent,
+} from "./triggers.js";
+
+/** A message was posted in a subscribed Slack channel. */
+export type SlackMessageTrigger = {
+	type: "slack.message";
+};
+
+/** A reaction was added to a Slack message. */
+export type SlackReactionAddedTrigger = {
+	type: "slack.reaction.added";
+};
+
+/** The Notion app was mentioned in a Slack message. */
+export type SlackAppMentionTrigger = {
+	type: "slack.app.mention";
+};
+
+/** A Discord interaction was received. */
+export type DiscordInteractionTrigger = {
+	type: "discord.interaction";
+};
+
+/** An email was received. */
+export type MailEmailReceivedTrigger = {
+	type: "mail.email.received";
+};
+
+/** An email was sent. */
+export type MailEmailSentTrigger = {
+	type: "mail.email.sent";
+};
+
+/** A label was applied to an email. */
+export type MailLabelAppliedTrigger = {
+	type: "mail.label.applied";
+};
+
+/** A calendar event was created. */
+export type CalendarEventCreatedTrigger = {
+	type: "calendar.event.created";
+};
+
+/** A calendar event was updated. */
+export type CalendarEventUpdatedTrigger = {
+	type: "calendar.event.updated";
+};
+
+/** A calendar event was canceled. */
+export type CalendarEventCanceledTrigger = {
+	type: "calendar.event.canceled";
+};
+
+/** A page has been added to a database. */
+export type NotionPageCreatedTrigger = {
+	type: "notion.page.created";
+};
+
+/** A page was updated. */
+export type NotionPageUpdatedTrigger = {
+	type: "notion.page.updated";
+};
+
+/** A page was deleted. */
+export type NotionPageDeletedTrigger = {
+	type: "notion.page.deleted";
+};
+
+/** A meeting note's AI summary finished generating. */
+export type NotionMeetingNoteSummaryCompletedTrigger = {
+	type: "notion.meetingNote.summary.completed";
+};
+
+/** A comment was added to a page discussion. */
+export type NotionCommentAddedTrigger = {
+	type: "notion.page.discussion.comment.added";
+};
+
+/** An agent was mentioned in page content or a person property. */
+export type NotionAgentMentionedTrigger = {
+	type: "notion.agent.mentioned";
+};
+
+/** A button block was pressed. */
+export type NotionButtonPressedTrigger = {
+	type: "notion.button.pressed";
+};
+
+/** A database agent's configuration was updated. */
+export type NotionDatabaseAgentUpdatedTrigger = {
+	type: "notion.database.agent.updated";
+};
+
+/** An incoming webhook request was received. */
+export type WebhookTrigger = {
+	type: "webhooks.webhook";
+};
+
+/** Files changed in a watched Google Drive folder or drive. */
+export type GoogleDriveOauthFilesChangedTrigger = {
+	type: "googleDriveOauth.filesChanged";
+};
+
+/** A recurring schedule fired. */
+export type RecurrenceTrigger = {
+	type: "recurrence";
+};
+
+/** Creators for each event that can trigger a workflow. */
+export const triggers = {
+	/**
+	 * Declare that a workflow can run on `slack.message` events.
+	 *
+	 * A message was posted in a subscribed Slack channel.
+	 */
+	slackMessage(): SlackMessageTrigger {
+		return {
+			type: "slack.message",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `slack.reaction.added` events.
+	 *
+	 * A reaction was added to a Slack message.
+	 */
+	slackReactionAdded(): SlackReactionAddedTrigger {
+		return {
+			type: "slack.reaction.added",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `slack.app.mention` events.
+	 *
+	 * The Notion app was mentioned in a Slack message.
+	 */
+	slackAppMention(): SlackAppMentionTrigger {
+		return {
+			type: "slack.app.mention",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `discord.interaction` events.
+	 *
+	 * A Discord interaction was received.
+	 */
+	discordInteraction(): DiscordInteractionTrigger {
+		return {
+			type: "discord.interaction",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `mail.email.received` events.
+	 *
+	 * An email was received.
+	 */
+	mailEmailReceived(): MailEmailReceivedTrigger {
+		return {
+			type: "mail.email.received",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `mail.email.sent` events.
+	 *
+	 * An email was sent.
+	 */
+	mailEmailSent(): MailEmailSentTrigger {
+		return {
+			type: "mail.email.sent",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `mail.label.applied` events.
+	 *
+	 * A label was applied to an email.
+	 */
+	mailLabelApplied(): MailLabelAppliedTrigger {
+		return {
+			type: "mail.label.applied",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `calendar.event.created` events.
+	 *
+	 * A calendar event was created.
+	 */
+	calendarEventCreated(): CalendarEventCreatedTrigger {
+		return {
+			type: "calendar.event.created",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `calendar.event.updated` events.
+	 *
+	 * A calendar event was updated.
+	 */
+	calendarEventUpdated(): CalendarEventUpdatedTrigger {
+		return {
+			type: "calendar.event.updated",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `calendar.event.canceled` events.
+	 *
+	 * A calendar event was canceled.
+	 */
+	calendarEventCanceled(): CalendarEventCanceledTrigger {
+		return {
+			type: "calendar.event.canceled",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.page.created` events.
+	 *
+	 * A page has been added to a database.
+	 */
+	notionPageCreated(): NotionPageCreatedTrigger {
+		return {
+			type: "notion.page.created",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.page.updated` events.
+	 *
+	 * A page was updated.
+	 */
+	notionPageUpdated(): NotionPageUpdatedTrigger {
+		return {
+			type: "notion.page.updated",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.page.deleted` events.
+	 *
+	 * A page was deleted.
+	 */
+	notionPageDeleted(): NotionPageDeletedTrigger {
+		return {
+			type: "notion.page.deleted",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.meetingNote.summary.completed` events.
+	 *
+	 * A meeting note's AI summary finished generating.
+	 */
+	notionMeetingNoteSummaryCompleted(): NotionMeetingNoteSummaryCompletedTrigger {
+		return {
+			type: "notion.meetingNote.summary.completed",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.page.discussion.comment.added` events.
+	 *
+	 * A comment was added to a page discussion.
+	 */
+	notionCommentAdded(): NotionCommentAddedTrigger {
+		return {
+			type: "notion.page.discussion.comment.added",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.agent.mentioned` events.
+	 *
+	 * An agent was mentioned in page content or a person property.
+	 */
+	notionAgentMentioned(): NotionAgentMentionedTrigger {
+		return {
+			type: "notion.agent.mentioned",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.button.pressed` events.
+	 *
+	 * A button block was pressed.
+	 */
+	notionButtonPressed(): NotionButtonPressedTrigger {
+		return {
+			type: "notion.button.pressed",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `notion.database.agent.updated` events.
+	 *
+	 * A database agent's configuration was updated.
+	 */
+	notionDatabaseAgentUpdated(): NotionDatabaseAgentUpdatedTrigger {
+		return {
+			type: "notion.database.agent.updated",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `webhooks.webhook` events.
+	 *
+	 * An incoming webhook request was received.
+	 */
+	webhook(): WebhookTrigger {
+		return {
+			type: "webhooks.webhook",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `googleDriveOauth.filesChanged` events.
+	 *
+	 * Files changed in a watched Google Drive folder or drive.
+	 */
+	googleDriveOauthFilesChanged(): GoogleDriveOauthFilesChangedTrigger {
+		return {
+			type: "googleDriveOauth.filesChanged",
+		};
+	},
+
+	/**
+	 * Declare that a workflow can run on `recurrence` events.
+	 *
+	 * A recurring schedule fired.
+	 */
+	recurrence(): RecurrenceTrigger {
+		return {
+			type: "recurrence",
+		};
+	},
+} as const;
+
+/** Event that can trigger a workflow. */
+export type WorkflowTrigger =
+	| SlackMessageTrigger
+	| SlackReactionAddedTrigger
+	| SlackAppMentionTrigger
+	| DiscordInteractionTrigger
+	| MailEmailReceivedTrigger
+	| MailEmailSentTrigger
+	| MailLabelAppliedTrigger
+	| CalendarEventCreatedTrigger
+	| CalendarEventUpdatedTrigger
+	| CalendarEventCanceledTrigger
+	| NotionPageCreatedTrigger
+	| NotionPageUpdatedTrigger
+	| NotionPageDeletedTrigger
+	| NotionMeetingNoteSummaryCompletedTrigger
+	| NotionCommentAddedTrigger
+	| NotionAgentMentionedTrigger
+	| NotionButtonPressedTrigger
+	| NotionDatabaseAgentUpdatedTrigger
+	| WebhookTrigger
+	| GoogleDriveOauthFilesChangedTrigger
+	| RecurrenceTrigger;
+
+/** All workflow trigger type strings. */
+export const WORKFLOW_TRIGGER_TYPES = [
+	"slack.message",
+	"slack.reaction.added",
+	"slack.app.mention",
+	"discord.interaction",
+	"mail.email.received",
+	"mail.email.sent",
+	"mail.label.applied",
+	"calendar.event.created",
+	"calendar.event.updated",
+	"calendar.event.canceled",
+	"notion.page.created",
+	"notion.page.updated",
+	"notion.page.deleted",
+	"notion.meetingNote.summary.completed",
+	"notion.page.discussion.comment.added",
+	"notion.agent.mentioned",
+	"notion.button.pressed",
+	"notion.database.agent.updated",
+	"webhooks.webhook",
+	"googleDriveOauth.filesChanged",
+	"recurrence",
+] as const;
+
+/** A workflow trigger type string. */
+export type WorkflowTriggerType = (typeof WORKFLOW_TRIGGER_TYPES)[number];
+
+/** Maps each supported workflow trigger to the event its handler receives. */
+export type WorkflowEventMap = {
+	"slack.message": SlackMessageEvent;
+	"slack.reaction.added": SlackReactionAddedEvent;
+	"slack.app.mention": SlackAppMentionEvent;
+	"discord.interaction": DiscordInteractionEvent;
+	"mail.email.received": MailEmailReceivedEvent;
+	"mail.email.sent": MailEmailSentEvent;
+	"mail.label.applied": MailLabelAppliedEvent;
+	"calendar.event.created": CalendarEventCreatedEvent;
+	"calendar.event.updated": CalendarEventUpdatedEvent;
+	"calendar.event.canceled": CalendarEventCanceledEvent;
+	"notion.page.created": NotionPageCreatedEvent;
+	"notion.page.updated": NotionPageUpdatedEvent;
+	"notion.page.deleted": NotionPageDeletedEvent;
+	"notion.meetingNote.summary.completed": NotionMeetingNoteSummaryCompletedEvent;
+	"notion.page.discussion.comment.added": NotionCommentAddedEvent;
+	"notion.agent.mentioned": NotionAgentMentionedEvent;
+	"notion.button.pressed": NotionButtonPressedEvent;
+	"notion.database.agent.updated": NotionDatabaseAgentUpdatedEvent;
+	"webhooks.webhook": WebhookEvent;
+	"googleDriveOauth.filesChanged": GoogleDriveOauthFilesChangedEvent;
+	recurrence: RecurrenceEvent;
+};