@notionhq/workers 0.3.0 → 0.5.0

package/dist/triggers.generated.js

@@ -0,0 +1,239 @@
+const triggers = {
+  /**
+   * Declare that a workflow can run on `slack.message` events.
+   *
+   * A message was posted in a subscribed Slack channel.
+   */
+  slackMessage() {
+    return {
+      type: "slack.message"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `slack.reaction.added` events.
+   *
+   * A reaction was added to a Slack message.
+   */
+  slackReactionAdded() {
+    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() {
+    return {
+      type: "slack.app.mention"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `discord.interaction` events.
+   *
+   * A Discord interaction was received.
+   */
+  discordInteraction() {
+    return {
+      type: "discord.interaction"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `mail.email.received` events.
+   *
+   * An email was received.
+   */
+  mailEmailReceived() {
+    return {
+      type: "mail.email.received"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `mail.email.sent` events.
+   *
+   * An email was sent.
+   */
+  mailEmailSent() {
+    return {
+      type: "mail.email.sent"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `mail.label.applied` events.
+   *
+   * A label was applied to an email.
+   */
+  mailLabelApplied() {
+    return {
+      type: "mail.label.applied"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `calendar.event.created` events.
+   *
+   * A calendar event was created.
+   */
+  calendarEventCreated() {
+    return {
+      type: "calendar.event.created"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `calendar.event.updated` events.
+   *
+   * A calendar event was updated.
+   */
+  calendarEventUpdated() {
+    return {
+      type: "calendar.event.updated"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `calendar.event.canceled` events.
+   *
+   * A calendar event was canceled.
+   */
+  calendarEventCanceled() {
+    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() {
+    return {
+      type: "notion.page.created"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `notion.page.updated` events.
+   *
+   * A page was updated.
+   */
+  notionPageUpdated() {
+    return {
+      type: "notion.page.updated"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `notion.page.deleted` events.
+   *
+   * A page was deleted.
+   */
+  notionPageDeleted() {
+    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() {
+    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() {
+    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() {
+    return {
+      type: "notion.agent.mentioned"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `notion.button.pressed` events.
+   *
+   * A button block was pressed.
+   */
+  notionButtonPressed() {
+    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() {
+    return {
+      type: "notion.database.agent.updated"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `webhooks.webhook` events.
+   *
+   * An incoming webhook request was received.
+   */
+  webhook() {
+    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() {
+    return {
+      type: "googleDriveOauth.filesChanged"
+    };
+  },
+  /**
+   * Declare that a workflow can run on `recurrence` events.
+   *
+   * A recurring schedule fired.
+   */
+  recurrence() {
+    return {
+      type: "recurrence"
+    };
+  }
+};
+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"
+];
+export {
+  WORKFLOW_TRIGGER_TYPES,
+  triggers
+};

package/dist/types.d.ts

@@ -122,6 +122,24 @@ export interface ImageIcon {
  * All possible icon types
  */
 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/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/worker.d.ts

@@ -6,12 +6,15 @@ import type { SyncCapability, SyncConfiguration } from "./capabilities/sync.js";
 import type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
 import type { WebhookCapability, WebhookConfiguration, WebhookEvent } from "./capabilities/webhook.js";
 import { WebhookVerificationError } from "./capabilities/webhook.js";
+import type { WorkflowCapability, WorkflowConfiguration, WorkflowEvent } from "./capabilities/workflow.js";
 import type { PacerDeclaration } from "./pacer_internal.js";
 import type { Schema } from "./schema.js";
+import type { WorkflowTrigger } from "./triggers.generated.js";
 import type { HandlerOptions, JSONValue } from "./types.js";
-export type { AutomationConfiguration, AutomationEvent, AiConnectorConfiguration, CapabilityContext, OAuthConfiguration, NotionManagedOAuthConfiguration, UserManagedOAuthConfiguration, SyncConfiguration, ToolConfiguration, WebhookConfiguration, WebhookEvent, };
+export type { AiConnectorConfiguration, AutomationConfiguration, AutomationEvent, CapabilityContext, NotionManagedOAuthConfiguration, OAuthConfiguration, SyncConfiguration, ToolConfiguration, UserManagedOAuthConfiguration, WebhookConfiguration, WebhookEvent, WorkflowConfiguration, WorkflowEvent, };
 export { WebhookVerificationError };
-type Capability = SyncCapability | AiConnectorCapability | ToolCapability<any, any> | AutomationCapability | OAuthCapability | WebhookCapability;
+type Capability = SyncCapability | AiConnectorCapability | ToolCapability<any, any> | AutomationCapability | WorkflowCapability | OAuthCapability | WebhookCapability;
+export type CapabilityType = Capability["_tag"];
 /**
  * Configuration for a database that Notion creates and manages on behalf
  * of the worker. The database is created on first deploy and its schema
@@ -298,6 +301,34 @@ export declare class Worker {
      * @returns The capability object.
      */
     automation(key: string, config: AutomationConfiguration): AutomationCapability;
+    /**
+     * Register a workflow capability.
+     *
+     * Example:
+     *
+     * ```ts
+     * import { Worker } from "@notionhq/workers";
+     * import { triggers } from "@notionhq/workers/triggers";
+     *
+     * const worker = new Worker();
+     * export default worker;
+     *
+     * worker.workflow("sendWelcomeEmail", {
+     *   title: "Send Welcome Email",
+     *   description: "Sends a welcome email when a new user is added",
+     *   triggers: [triggers.notionPageCreated()],
+     *   execute: async (event) => {
+     *     console.log(event.page);
+     *     console.log(event.content);
+     *   },
+     * })
+     * ```
+     *
+     * @param key - The unique key for this capability.
+     * @param config - The workflow configuration.
+     * @returns The capability object.
+     */
+    workflow<const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]]>(key: string, config: WorkflowConfiguration<TTriggers>): WorkflowCapability<TTriggers>;
     /**
      * Register a webhook capability.
      *

package/dist/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"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"}

package/dist/worker.js

@@ -7,6 +7,7 @@ import {
   createWebhookCapability,
   WebhookVerificationError
 } from "./capabilities/webhook.js";
+import { createWorkflowCapability } from "./capabilities/workflow.js";
 import { pacerWait } from "./pacer_internal.js";
 import { createRequire } from "node:module";
 const SDK_VERSION = (() => {
@@ -253,6 +254,39 @@ class Worker {
     this.#capabilities.set(key, capability);
     return capability;
   }
+  /**
+   * Register a workflow capability.
+   *
+   * Example:
+   *
+   * ```ts
+   * import { Worker } from "@notionhq/workers";
+   * import { triggers } from "@notionhq/workers/triggers";
+   *
+   * const worker = new Worker();
+   * export default worker;
+   *
+   * worker.workflow("sendWelcomeEmail", {
+   *   title: "Send Welcome Email",
+   *   description: "Sends a welcome email when a new user is added",
+   *   triggers: [triggers.notionPageCreated()],
+   *   execute: async (event) => {
+   *     console.log(event.page);
+   *     console.log(event.content);
+   *   },
+   * })
+   * ```
+   *
+   * @param key - The unique key for this capability.
+   * @param config - The workflow configuration.
+   * @returns The capability object.
+   */
+  workflow(key, config) {
+    this.#validateUniqueKey(key);
+    const capability = createWorkflowCapability(key, config);
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
   /**
    * Register a webhook capability.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/workers",
-	"version": "0.3.0",
+	"version": "0.5.0",
 	"description": "An SDK for building workers for the Notion Workers platform",
 	"license": "MIT",
 	"type": "module",
@@ -29,6 +29,10 @@
 			"types": "./dist/schema-builder.d.ts",
 			"default": "./dist/schema-builder.js"
 		},
+		"./triggers": {
+			"types": "./dist/triggers.generated.d.ts",
+			"default": "./dist/triggers.generated.js"
+		},
 		"./types": {
 			"types": "./dist/types.d.ts",
 			"default": "./dist/types.js"
@@ -59,6 +63,9 @@
 		"build:watch": "concurrently --group \"npm run build:watch:types\" \"npm run build:watch:js\"",
 		"build:watch:types": "tsc --watch",
 		"build:watch:js": "esbuild --watch --format=esm --outdir=dist --target=esnext --packages=external ./src/**.ts ./src/**/*.ts",
+		"generate": "tsx scripts/generate-triggers.ts",
+		"generate:check": "tsx scripts/generate-triggers.ts --check",
+		"sync:triggers": "tsx scripts/sync-triggers.ts",
 		"test": "vitest run"
 	},
 	"devDependencies": {
@@ -70,7 +77,7 @@
 		"vitest": "^4.0.8"
 	},
 	"peerDependencies": {
-		"@notionhq/client": "^2.2.15"
+		"@notionhq/client": ">=2.2.15"
 	},
 	"dependencies": {
 		"ajv": "^8.17.1",

package/src/block.ts

@@ -473,57 +473,57 @@ type Block =
 
 // Export all types
 export type {
-	RichText,
-	RichTextItem,
-	RichTextBase,
-	RichTextAnnotations,
-	TextContent,
-	EquationContent,
-	MentionContent,
-	DateMention,
-	CustomEmojiMention,
-	LinkPreviewMention,
-	LinkMention,
+	AIBlock,
 	ApiColor,
-	Icon,
+	AudioBlock,
+	Block,
+	BlockBase,
+	BookmarkBlock,
+	BreadcrumbBlock,
+	BulletedListItemBlock,
+	CalloutBlock,
+	ChildDatabaseBlock,
+	ChildPageBlock,
+	CodeBlock,
+	ColumnBlock,
+	ColumnListBlock,
+	CustomEmojiMention,
+	DateMention,
+	DividerBlock,
+	EmbedBlock,
 	EmojiIcon,
+	EquationBlock,
+	EquationContent,
+	ExternalFile,
 	ExternalIcon,
+	FileBlock,
 	FileIcon,
 	FileObject,
-	ExternalFile,
-	HostedFile,
-	BlockBase,
-	ParagraphBlock,
 	Heading1Block,
 	Heading2Block,
 	Heading3Block,
-	BulletedListItemBlock,
-	NumberedListItemBlock,
-	ToDoBlock,
-	ToggleBlock,
-	QuoteBlock,
-	CalloutBlock,
-	CodeBlock,
-	EquationBlock,
-	DividerBlock,
-	BreadcrumbBlock,
-	TableOfContentsBlock,
-	ColumnListBlock,
-	ColumnBlock,
+	HostedFile,
+	Icon,
 	ImageBlock,
-	VideoBlock,
-	AudioBlock,
-	PDFBlock,
-	FileBlock,
-	EmbedBlock,
-	BookmarkBlock,
+	LinkMention,
 	LinkPreviewBlock,
-	ChildPageBlock,
-	ChildDatabaseBlock,
-	TemplateBlock,
+	LinkPreviewMention,
+	MentionContent,
+	NumberedListItemBlock,
+	ParagraphBlock,
+	PDFBlock,
+	QuoteBlock,
+	RichText,
+	RichTextAnnotations,
+	RichTextBase,
+	RichTextItem,
 	TableBlock,
+	TableOfContentsBlock,
 	TableRowBlock,
-	AIBlock,
+	TemplateBlock,
+	TextContent,
+	ToDoBlock,
+	ToggleBlock,
 	UnsupportedBlock,
-	Block,
+	VideoBlock,
 };

package/src/builder.ts

@@ -1,5 +1,6 @@
 import type { NoticonName } from "./icon-names.js";
 import type {
+	Cover,
 	DateValue,
 	Icon,
 	NoticonColor,
@@ -310,3 +311,22 @@ export function imageIcon(url: string): Icon {
 		url,
 	};
 }
+
+/**
+ * Creates an image cover from an external URL.
+ * @param url - The URL of the image (e.g., "https://example.com/cover.png")
+ * @param position - Vertical image position, from 0 (top) to 1 (bottom). Defaults to 0.5.
+ */
+export function imageCover(url: string, position = 0.5): Cover {
+	if (!Number.isFinite(position) || position < 0 || position > 1) {
+		throw new Error(
+			`Invalid cover position: ${position}. Expected a number between 0 and 1.`,
+		);
+	}
+
+	return {
+		type: "image",
+		url,
+		position,
+	};
+}

package/src/capabilities/ai_connector.ts

@@ -154,7 +154,7 @@ export function createAiConnectorCapability<
 			runtimeContext?: StatefulRuntimeContext<State>,
 			options?: HandlerOptions,
 		) {
-			const capabilityContext = createCapabilityContext();
+			const capabilityContext = createCapabilityContext("ai_connector");
 			const state = runtimeContext?.state ?? runtimeContext?.userContext;
 
 			initPacerState(runtimeContext?.pacers, pacerDeclarations);

package/src/capabilities/automation.ts

@@ -105,7 +105,7 @@ export function createAutomationCapability(
 			options?: HandlerOptions,
 		): Promise<{ status: "success" } | undefined> {
 			try {
-				const capabilityContext = createCapabilityContext();
+				const capabilityContext = createCapabilityContext("automation");
 				await config.execute(event, capabilityContext);
 
 				if (options?.concreteOutput) {

package/src/capabilities/context.ts

@@ -1,22 +1,64 @@
 import { Client } from "@notionhq/client";
 import type { ClientOptions } from "@notionhq/client/build/src/Client.js";
+import type { CapabilityType } from "../worker.js";
 
 export type CapabilityContext = {
 	/** Notion API SDK client for this execution. */
 	notion: Client;
 };
 
-export function createCapabilityContext(): CapabilityContext {
+const FIX_STEPS =
+	"\n\nTo fix this:\n" +
+	"1. Create a connection at https://app.notion.com/developers/connections\n" +
+	"2. Give the connection access to the relevant pages/databases\n" +
+	"3. Add NOTION_API_TOKEN=<your-token> to your .env file\n" +
+	"4. For deployed workers, run: ntn workers env push";
+
+function missingTokenMessage(capabilityType: CapabilityType): string {
+	if (capabilityType === "tool") {
+		return (
+			"NOTION_API_TOKEN is not set. " +
+			"When tools are called through a Custom Agent, the platform sets NOTION_API_TOKEN automatically, " +
+			"using the permissions of the Custom Agent. " +
+			"Outside of that context (e.g. ntn workers exec), you must set it yourself." +
+			FIX_STEPS
+		);
+	}
+
+	return (
+		"NOTION_API_TOKEN is not set. " +
+		`context.notion requires an API token to make requests in ${capabilityType} capabilities to Notion.` +
+		FIX_STEPS
+	);
+}
+
+function createUnauthenticatedNotionProxy(
+	capabilityType: CapabilityType,
+): Client {
+	return new Proxy({} as Client, {
+		get(_target, prop) {
+			if (prop === "then" || typeof prop === "symbol") {
+				return undefined;
+			}
+			throw new Error(missingTokenMessage(capabilityType));
+		},
+	});
+}
+
+export function createCapabilityContext(
+	capabilityType: CapabilityType,
+): 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) {
-		options.auth = process.env.NOTION_API_TOKEN;
+	if (!process.env.NOTION_API_TOKEN) {
+		return { notion: createUnauthenticatedNotionProxy(capabilityType) };
 	}
 
+	options.auth = process.env.NOTION_API_TOKEN;
 	const notion = new Client(options);
 
 	return { notion };

package/src/capabilities/stateful-capability.ts

@@ -48,7 +48,7 @@ export function parseSchedule(schedule: Schedule): SyncSchedule {
 	}
 
 	const match = schedule.match(/^(\d+)(m|h|d)$/);
-	if (!match || !match[1] || !match[2]) {
+	if (!match?.[1] || !match[2]) {
 		throw new Error(
 			`Invalid schedule format: "${schedule}". Use "continuous" or an interval like "30m", "1h", "1d".`,
 		);