@notionhq/workers 0.4.0 → 0.6.0

package/src/triggers.ts

@@ -0,0 +1,504 @@
+/**
+ * Agent Trigger Types — Public API
+ *
+ * Shared type definitions for agent triggers between @notionhq/workers and the Notion repository.
+ * This file MUST be kept identical in both repositories.
+ *
+ * Conventions:
+ *   - Protocols define the standard fields every consumer can rely on.
+ *   - Vendor-specific fields use `x-<vendor>-` prefix (e.g., "x-slack-threadId").
+ *   - Only public URLs — no internal URIs.
+ *   - No `data` sub-object — vendor fields live at the top level with `x-<vendor>-`.
+ *   - Types only — no runtime values.
+ *   - All fields are required. Nullable fields use `T | null` (no `?:`) so they
+ *     map directly to required + nullable in JSON Schema for LLM structured output.
+ *   - Conversions must always provide explicit values (use `null` when absent).
+ */
+
+// ============================================================
+// Vendor extension pattern
+// ============================================================
+
+/** Allows arbitrary vendor-specific fields prefixed with `x-<vendor>-`. */
+export type VendorExtensions = {
+	[key: `x-${string}`]: unknown
+}
+
+// ============================================================
+// Protocols (composable capabilities)
+// ============================================================
+
+/** Has a human-readable message / summary. */
+export type MessageLike = {
+	message: string
+}
+
+/** Has an actor who performed the action. */
+export type ActorLike = {
+	actor: Actor | null
+}
+
+/** Has a navigable URL. */
+export type LinkLike = {
+	url: string | null
+}
+
+/** Has a timestamp. */
+export type TimestampLike = {
+	/** ISO 8601 */
+	timestamp: string | null
+}
+
+/** Has a conversation thread. */
+export type ThreadLike<M = ThreadMessage> = {
+	thread: Array<M>
+	/** Whether this event is a follow-up in a previously subscribed thread. */
+	isFollowUpMessage: boolean | null
+}
+
+/**
+ * A chat message. Any chat platform (Slack, Discord, MS Teams, etc.) implements this.
+ * Composes MessageLike, ActorLike, LinkLike, TimestampLike.
+ */
+export type ChatMessageLike = MessageLike &
+	ActorLike &
+	LinkLike &
+	TimestampLike & {
+		id: string
+		channelId: string
+		channelName: string | null
+	}
+
+/** An email message. Any mail provider (Gmail, Outlook, etc.) implements this. */
+export type EmailMessageLike = MessageLike &
+	LinkLike &
+	TimestampLike & {
+		id: string
+		subject: string
+		from: string
+		fromName: string | null
+		to: Array<string>
+		cc: Array<string> | null
+		bcc: Array<string> | null
+		/** Plain-text or HTML body content. */
+		body: string
+		isRead: boolean | null
+		hasAttachments: boolean | null
+		labels: Array<string> | null
+	}
+
+/** An email thread. Any mail provider implements this. */
+export type EmailThreadLike = {
+	id: string
+	subject: string
+	participants: Array<string>
+	messageCount: number
+	/** ISO 8601 */
+	lastMessageAt: string
+	hasUnread: boolean
+}
+
+/** A calendar event. Any calendar provider (Google, Outlook, iCal, etc.) implements this. */
+export type CalendarEventLike = LinkLike &
+	TimestampLike & {
+		eventId: string
+		summary: string
+		description: string | null
+		location: string | null
+		/** ISO 8601 */
+		startTime: string
+		/** ISO 8601 */
+		endTime: string | null
+		isAllDay: boolean | null
+		isRecurring: boolean | null
+		attendees: Array<Actor> | null
+		calendarId: string
+		accountId: string
+	}
+
+// ============================================================
+// Core types
+// ============================================================
+
+/**
+ * An actor who performed an action.
+ *
+ * `id` / `displayName` / `email` are the Notion-resolved identity.
+ * `vendorActor` carries the identity in the originating system.
+ */
+export type Actor = {
+	/** Notion user ID (when resolved). */
+	id: string | null
+	displayName: string | null
+	email: string | null
+	/** The actor's identity in the vendor system. */
+	vendorActor: VendorActor | null
+}
+
+/** Vendor-specific actor identity. */
+export type VendorActor = {
+	/** Vendor name: "slack", "gmail", "discord", "notion", etc. */
+	vendor: string
+	/** Vendor-specific ID. */
+	id: string
+	displayName: string | null
+	/** Handle / username (e.g., Slack @handle). */
+	handle: string | null
+	/** "user", "bot", or a vendor-specific string. */
+	type: "user" | "bot" | string | null
+	/** URL to the actor's profile in the vendor system. */
+	url: string | null
+}
+
+// ============================================================
+// Thread message
+// ============================================================
+
+/**
+ * A single message inside a thread.
+ * Implements MessageLike, ActorLike, LinkLike, TimestampLike.
+ * Vendor-specific fields use `x-<vendor>-` prefix.
+ */
+export type ThreadMessage = MessageLike &
+	ActorLike &
+	LinkLike &
+	TimestampLike &
+	VendorExtensions & {
+		id: string
+	}
+
+/** A chat thread message. Extends ChatMessageLike with VendorExtensions. */
+export type ChatThreadMessage = ChatMessageLike & VendorExtensions
+
+/** An email message in a trigger. Extends EmailMessageLike with VendorExtensions. */
+export type EmailTriggerMessage = EmailMessageLike & VendorExtensions
+
+// ============================================================
+// Trigger event base
+// ============================================================
+
+/**
+ * Every trigger event has at least these fields.
+ * `message` is a human-readable summary of what happened.
+ */
+export type TriggerEventBase = MessageLike &
+	ActorLike &
+	VendorExtensions & {
+		type: string
+		vendor: string
+	}
+
+/**
+ * Base shape for chat trigger events (Slack, Discord, MS Teams, etc.).
+ * Parameterized on the message type so each platform can narrow
+ * `triggerMessage` and `thread` to its vendor-specific message shape.
+ */
+type ChatEventBase<M extends ChatThreadMessage = ChatThreadMessage> =
+	TriggerEventBase &
+		LinkLike &
+		TimestampLike &
+		ThreadLike<M> & {
+			/** The message that fired the trigger. */
+			triggerMessage: M
+			channelId: string
+			channelName: string | null
+			threadId: string | null
+		}
+
+// ============================================================
+// Slack
+// ============================================================
+
+export type SlackChatThreadMessage = ChatThreadMessage & {
+	"x-slack-fileUrls": Array<string> | null
+	/** URLs extracted from the message text. */
+	"x-slack-urls": Array<string> | null
+}
+
+export type SlackMessageEvent = ChatEventBase<SlackChatThreadMessage> & {
+	type: "slack.message"
+	vendor: "slack"
+}
+
+export type SlackReactionAddedEvent = ChatEventBase<SlackChatThreadMessage> & {
+	type: "slack.reaction.added"
+	vendor: "slack"
+	/** The emoji name (without colons), e.g. "thumbsup". */
+	"x-slack-reaction": string | null
+}
+
+export type SlackAppMentionEvent = ChatEventBase<SlackChatThreadMessage> & {
+	type: "slack.app.mention"
+	vendor: "slack"
+}
+
+// ============================================================
+// Mail
+// ============================================================
+
+/** Base shape for all mail trigger events. */
+type MailEventBase = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		vendor: "notionmail" | "gmail" | string
+		/** The triggering email. */
+		email: EmailTriggerMessage
+		/** The email thread this message belongs to. */
+		emailThread: EmailThreadLike
+		/** The email address of the mailbox owner. */
+		userEmail: string
+	}
+
+export type MailEmailReceivedEvent = MailEventBase & {
+	type: "mail.email.received"
+}
+
+export type MailEmailSentEvent = MailEventBase & {
+	type: "mail.email.sent"
+}
+
+export type MailLabelAppliedEvent = MailEventBase & {
+	type: "mail.label.applied"
+	/** The label that was applied. */
+	appliedLabel: string
+}
+
+// ============================================================
+// Calendar
+// ============================================================
+
+/** Base shape for all calendar trigger events. */
+type CalendarEventBase = TriggerEventBase &
+	CalendarEventLike & {
+		vendor: "notion-calendar" | "google" | string
+	}
+
+export type CalendarEventCreatedEvent = CalendarEventBase & {
+	type: "calendar.event.created"
+}
+
+export type CalendarEventUpdatedEvent = CalendarEventBase & {
+	type: "calendar.event.updated"
+	/** Which fields changed. */
+	updatedFields: Array<string> | null
+}
+
+export type CalendarEventCanceledEvent = CalendarEventBase & {
+	type: "calendar.event.canceled"
+}
+
+// ============================================================
+// Discord
+// ============================================================
+
+export type DiscordChatThreadMessage = ChatThreadMessage & {
+	"x-discord-guildId": string | null
+}
+
+export type DiscordInteractionEvent =
+	ChatEventBase<DiscordChatThreadMessage> & {
+		type: "discord.interaction"
+		vendor: "discord"
+		"x-discord-guildId": string | null
+	}
+
+// ============================================================
+// Notion — Page / Database triggers
+// ============================================================
+
+/** A property edit with before/after snapshots. */
+export type NotionPageEdit = {
+	before: Record<string, unknown> | null
+	after: Record<string, unknown> | null
+	afterContent: string | null
+	contentChanged: boolean | null
+	timestamp: number
+	editedBy: Actor | null
+}
+
+export type NotionPageCreatedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.page.created"
+		vendor: "notion"
+		/** Page properties as key-value pairs. */
+		page: Record<string, unknown>
+		/** Rendered markdown content of the page. */
+		content: string
+		edits: Array<NotionPageEdit> | null
+	}
+
+export type NotionPageUpdatedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.page.updated"
+		vendor: "notion"
+		/** Chronological array of edits (accumulated during debounce). */
+		edits: Array<NotionPageEdit>
+	}
+
+export type NotionPageDeletedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.page.deleted"
+		vendor: "notion"
+		page: Record<string, unknown>
+		content: string
+	}
+
+export type NotionMeetingNoteSummaryCompletedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.meetingNote.summary.completed"
+		vendor: "notion"
+		page: Record<string, unknown>
+		content: string
+		meetingNoteBlockId: string
+	}
+
+// ============================================================
+// Notion — Discussion / Comment triggers
+// ============================================================
+
+export type NotionCommentAddedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.page.discussion.comment.added"
+		vendor: "notion"
+		/** The full discussion context. */
+		discussion: {
+			id: string
+			pageId: string
+			resolved: boolean
+			context: "inline" | "block" | "page" | "databaseProperty" | null
+			parentBlockId: string | null
+			propertyId: string | null
+			propertyName: string | null
+		}
+		/** The new comment. */
+		comment: {
+			id: string
+			text: string
+			url: string
+			timestamp: string
+			actor: Actor | null
+		}
+	}
+
+// ============================================================
+// Notion — Agent / Button triggers
+// ============================================================
+
+export type NotionAgentMentionedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.agent.mentioned"
+		vendor: "notion"
+		page: Record<string, unknown>
+		content: string
+		mentionLocation: "page_content" | "person_property"
+		mentionBlockContent: string | null
+		propertyId: string | null
+		propertyName: string | null
+	}
+
+export type NotionButtonPressedEvent = TriggerEventBase &
+	LinkLike &
+	TimestampLike & {
+		type: "notion.button.pressed"
+		vendor: "notion"
+		blockUrl: string
+	}
+
+export type NotionDatabaseAgentUpdatedEvent = TriggerEventBase &
+	TimestampLike & {
+		type: "notion.database.agent.updated"
+		vendor: "notion"
+		agentId: string
+		runtimeInstructions: string
+		shouldRunOverDatabase: boolean
+		viewId: string | null
+	}
+
+export type WebhookEvent = TriggerEventBase &
+	TimestampLike & {
+		type: "webhooks.webhook"
+		vendor: "webhooks"
+		triggerId: string
+		verificationSchema: string
+		eventType: string | null
+		deliveryId: string | null
+		payload: unknown
+	}
+
+// ============================================================
+// Google Drive OAuth — File changed (polling) trigger
+// ============================================================
+
+export type GoogleDriveOauthFilesChangedEvent = TriggerEventBase &
+	TimestampLike & {
+		type: "googleDriveOauth.filesChanged"
+		vendor: "google-drive"
+		/** The page token from before this poll. */
+		changeToken: string
+		/** The page token after this poll. */
+		newChangeToken: string
+		/** Number of changes detected. */
+		changeCount: number
+		/** The folder or drive being watched. */
+		scope:
+			| { type: "folder"; folderId: string }
+			| { type: "drive"; driveId: string }
+		/** Upper time bound for this poll window (ISO 8601). */
+		lastEventTimestamp: string
+	}
+
+// ============================================================
+// Recurrence (scheduled) trigger
+// ============================================================
+
+export type RecurrenceFrequency = "hour" | "day" | "week" | "month" | "year"
+
+export type RecurrenceEvent = TriggerEventBase &
+	TimestampLike & {
+		type: "recurrence"
+		vendor: "notion"
+		frequency: RecurrenceFrequency
+		interval: number
+		timezone: string
+	}
+
+// ============================================================
+// Derived union types
+// ============================================================
+
+/** Map from trigger type string to its event shape. Single source of truth. */
+export type TriggerEventMap = {
+	"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
+}
+
+/** All trigger type strings. Derived from TriggerEventMap. */
+export type TriggerType = keyof TriggerEventMap
+
+/** Discriminated union of all trigger events. Derived from TriggerEventMap. */
+export type TriggerEvent = TriggerEventMap[TriggerType]

package/src/types.ts

@@ -118,13 +118,7 @@ export type NumberFormat =
 /**
  * Date format types
  */
-export type DateFormat =
-	| "relative"
-	| "MM/DD/YYYY"
-	| "DD/MM/YYYY"
-	| "YYYY/MM/DD"
-	| "ll"
-	| "MMM d";
+export type DateFormat = "relative" | "MM/DD/YYYY" | "DD/MM/YYYY" | "YYYY/MM/DD" | "ll" | "MMM d";
 
 import type { NoticonName } from "./icon-names.js";
 
@@ -182,6 +176,26 @@ export interface ImageIcon {
  */
 export type Icon = EmojiIcon | NoticonIcon | ImageIcon;
 
+/**
+ * Cover image for a Notion page.
+ */
+export interface ImageCover {
+	type: "image";
+	/**
+	 * The URL of the image (must be a valid http/https URL)
+	 */
+	url: string;
+	/**
+	 * Vertical image position, from 0 (top) to 1 (bottom).
+	 */
+	position?: number;
+}
+
+/**
+ * All possible cover types
+ */
+export type Cover = ImageCover;
+
 /**
  * Person reference - represents a user in a people property
  */

package/src/worker.test.ts

@@ -141,6 +141,153 @@ describe("Worker", () => {
 		]);
 	});
 
+	it("registers a project custom block from a folder path (type defaults to project)", () => {
+		const worker = new Worker();
+
+		worker.customBlock("visualBlock", {
+			path: "./views/visual",
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "visualBlock",
+				config: {
+					source: { type: "project", path: "./views/visual" },
+					manifest: {
+						version: 1,
+						dataSources: {},
+					},
+				},
+			},
+		]);
+	});
+
+	it("carries a project's custom build command and output dir", () => {
+		const worker = new Worker();
+
+		worker.customBlock("built", {
+			path: "./app",
+			command: "npm run build-prod",
+			output: "build",
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "built",
+				config: {
+					source: {
+						type: "project",
+						path: "./app",
+						command: "npm run build-prod",
+						output: "build",
+					},
+					manifest: { version: 1, dataSources: {} },
+				},
+			},
+		]);
+	});
+
+	it("registers a static custom block served as-is", () => {
+		const worker = new Worker();
+
+		worker.customBlock("prebuilt", { type: "static", path: "./dist" });
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "prebuilt",
+				config: {
+					source: { type: "static", path: "./dist" },
+					manifest: { version: 1, dataSources: {} },
+				},
+			},
+		]);
+	});
+
+	it("carries the author-declared data-source schema verbatim into the manifest", () => {
+		const worker = new Worker();
+
+		worker.customBlock("issueBoard", {
+			path: "./views/issueBoard",
+			dataSources: {
+				issues: {
+					name: "Issues",
+					description: "The team's issues",
+					icon: { type: "emoji", emoji: "🐛" },
+					properties: {
+						title: { name: "Title", type: "title" },
+						status: {
+							name: "Status",
+							description: "Workflow state",
+							type: "status",
+						},
+					},
+				},
+			},
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "issueBoard",
+				config: {
+					source: { type: "project", path: "./views/issueBoard" },
+					manifest: {
+						version: 1,
+						dataSources: {
+							issues: {
+								name: "Issues",
+								description: "The team's issues",
+								icon: { type: "emoji", emoji: "🐛" },
+								properties: {
+									title: { name: "Title", type: "title" },
+									status: {
+										name: "Status",
+										description: "Workflow state",
+										type: "status",
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		]);
+	});
+
+	it("threads a top-level manifest version into the generated manifest", () => {
+		const worker = new Worker();
+
+		worker.customBlock("versioned", {
+			path: "./views/versioned",
+			version: 1,
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "versioned",
+				config: {
+					source: { type: "project", path: "./views/versioned" },
+					manifest: { version: 1, dataSources: {} },
+				},
+			},
+		]);
+	});
+
+	it("cannot run a custom block capability", async () => {
+		const worker = new Worker();
+		worker.customBlock("visualBlock", {
+			path: "./views/visual",
+		});
+
+		await expect(worker.run("visualBlock", {})).rejects.toThrow(
+			'Cannot run custom block capability "visualBlock"',
+		);
+	});
+
 	it("rejects duplicate keys across databases, pacers, and capabilities", () => {
 		const worker = new Worker();
 		const db = worker.database("shared-key", {