@notionhq/apps 0.0.6 → 0.0.9

package/README.md

@@ -1,5 +1,8 @@
 # Apps SDK
 
+[![CI](https://github.com/makenotion/apps-sdk/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/makenotion/apps-sdk/actions/workflows/ci.yml?query=branch%3Amain)
+[![Publish](https://github.com/makenotion/apps-sdk/actions/workflows/publish.yml/badge.svg?branch=main)](https://github.com/makenotion/apps-sdk/actions/workflows/publish.yml?query=branch%3Amain)
+
 ## Development
 
 1. Install [mise](https://mise.jdx.dev/getting-started.html)
@@ -11,9 +14,29 @@ The SDK requires Node 26 or newer. It supports workflows and database syncs.
 
 ```ts
 import { triggers } from "@notionhq/apps/triggers";
-import { createWorkflow } from "@notionhq/apps/workflow";
+import { connections, createWorkflow } from "@notionhq/apps/workflow";
 ```
 
+Add a connection requirement to a workflow when it needs Calendar:
+
+```ts
+export default createWorkflow({
+	name: "Schedule follow-up",
+	description: "Schedules a follow-up after a page is created",
+	triggers: [triggers.notionPageCreated()],
+	connections: [connections.calendar()],
+	handler: async () => {},
+});
+```
+
+Declaring the same connection more than once causes the app build to fail.
+
+## Notion API access
+
+Use `context.notion` for Notion API calls. Deployed apps receive Notion API
+credentials automatically, so do not configure or push `NOTION_API_TOKEN`.
+Local execution needs the token in `.env` before making a Notion API request.
+
 ## Database syncs
 
 Apps declare a database schema, and users attach a real Notion database to it. Apps SDK

package/dist/context.js

@@ -1,7 +1,7 @@
 import { Client } from "@notionhq/client";
-const FIX_STEPS = "\n\nTo fix this:\n1. Create a personal access token at https://app.notion.com/developers/tokens\n2. Add NOTION_API_TOKEN=<your-token> to your .env file\n3. For deployed apps, run: ntn apps env push";
+const LOCAL_FIX_STEPS = "\n\nFor local execution:\n1. Create a personal access token at https://app.notion.com/developers/tokens\n2. Add NOTION_API_TOKEN=<your-token> to your .env file\n\nDeployed apps receive Notion API credentials automatically. Do not push NOTION_API_TOKEN.";
 function missingTokenMessage() {
-  return "NOTION_API_TOKEN is not set. context.notion requires an API token to make requests from app capabilities to Notion." + FIX_STEPS;
+  return "NOTION_API_TOKEN is not set. context.notion requires an API token when an app capability runs locally." + LOCAL_FIX_STEPS;
 }
 function createUnauthenticatedNotionProxy() {
   return new Proxy({}, {

package/dist/workflow.d.ts

@@ -8,6 +8,15 @@ type HandlerOptions = {
 export type WorkflowEvent = WorkflowEventMap[keyof WorkflowEventMap];
 export type WorkflowEventForTrigger<T extends WorkflowTrigger> = WorkflowEventMap[T["type"]];
 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 declare const connections: {
+    /** Require an authorized Calendar connection. */
+    calendar(): WorkflowConnection;
+};
 /**
  * Configuration passed to {@link createWorkflow}.
  */
@@ -26,6 +35,10 @@ export type WorkflowConfiguration<TTriggers extends readonly [WorkflowTrigger, .
      * Each trigger defines a specific event or condition that causes the workflow to run.
      */
     triggers: TTriggers;
+    /**
+     * Connections that must be set up before this workflow can run.
+     */
+    connections?: readonly WorkflowConnection[];
     handler: (event: WorkflowEventForTriggers<TTriggers>, context: WorkflowContext) => Promise<void> | void;
 };
 /**
@@ -43,6 +56,7 @@ export type Workflow<TTriggers extends readonly [WorkflowTrigger, ...WorkflowTri
         name: string;
         description: string;
         triggers: TTriggers;
+        connections?: readonly WorkflowConnection[];
     };
     handler: (event: WorkflowEventForTriggers<TTriggers>, options?: HandlerOptions) => Promise<{
         status: "success";

package/dist/workflow.d.ts.map

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

package/dist/workflow.js

@@ -6,13 +6,29 @@ import { ExecutionError } from "./error.js";
 import { writeOutput } from "./output.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
 import { readRunMetadata } from "./runtime-metadata.js";
+const connections = {
+  /** Require an authorized Calendar connection. */
+  calendar() {
+    return { type: "calendar" };
+  }
+};
 function createWorkflow(configuration) {
+  if (configuration.connections !== void 0) {
+    const connectionTypes = /* @__PURE__ */ new Set();
+    for (const connection of configuration.connections) {
+      if (connectionTypes.has(connection.type)) {
+        throw new Error(`Duplicate workflow connection: ${connection.type}`);
+      }
+      connectionTypes.add(connection.type);
+    }
+  }
   return {
     _tag: "workflow",
     config: {
       name: configuration.name,
       description: configuration.description,
-      triggers: configuration.triggers
+      triggers: configuration.triggers,
+      ...configuration.connections === void 0 ? {} : { connections: configuration.connections }
     },
     async handler(event, options) {
       try {
@@ -208,5 +224,6 @@ function isNodeError(error) {
   return error instanceof Error && "code" in error;
 }
 export {
+  connections,
   createWorkflow
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/apps",
-	"version": "0.0.6",
+	"version": "0.0.9",
 	"description": "An SDK for building workflow apps for Notion",
 	"license": "MIT",
 	"bin": {

package/src/context.ts

@@ -6,17 +6,17 @@ export type CapabilityContext = {
 	notion: Client;
 };
 
-const FIX_STEPS =
-	"\n\nTo fix this:\n" +
+const LOCAL_FIX_STEPS =
+	"\n\nFor local execution:\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";
+	"2. Add NOTION_API_TOKEN=<your-token> to your .env file\n\n" +
+	"Deployed apps receive Notion API credentials automatically. Do not push NOTION_API_TOKEN.";
 
 function missingTokenMessage(): string {
 	return (
 		"NOTION_API_TOKEN is not set. " +
-		"context.notion requires an API token to make requests from app capabilities to Notion." +
-		FIX_STEPS
+		"context.notion requires an API token when an app capability runs locally." +
+		LOCAL_FIX_STEPS
 	);
 }
 

package/src/workflow.test.ts

@@ -8,7 +8,7 @@ import { afterEach, beforeEach, describe, expect, expectTypeOf, it, vi, type Moc
 import { ExecutionError } from "./error.js";
 import type { RunMetadata } from "./runtime-metadata.js";
 import { triggers, type NotionPageCreatedEvent } from "./triggers.generated.js";
-import { createWorkflow, type StepContext, type WorkflowContext } from "./workflow.js";
+import { connections, createWorkflow, type StepContext, type WorkflowContext } from "./workflow.js";
 
 let stdoutSpy: Mock<typeof process.stdout.write>;
 let checkpointDirectory: string | undefined;
@@ -738,6 +738,30 @@ describe("createWorkflow", () => {
 		});
 	});
 
+	it("declares a Calendar connection requirement", () => {
+		const workflow = createWorkflow({
+			name: "Schedule Follow-up",
+			description: "Schedules a follow-up after a page is created",
+			triggers: [triggers.notionPageCreated()],
+			connections: [connections.calendar()],
+			handler: () => {},
+		});
+
+		expect(workflow.config.connections).toEqual([{ type: "calendar" }]);
+	});
+
+	it("rejects duplicate connection requirements", () => {
+		expect(() =>
+			createWorkflow({
+				name: "Schedule Follow-up",
+				description: "Schedules a follow-up after a page is created",
+				triggers: [triggers.notionPageCreated()],
+				connections: [connections.calendar(), connections.calendar()],
+				handler: () => {},
+			}),
+		).toThrowError("Duplicate workflow connection: calendar");
+	});
+
 	it("writes a success envelope after the handler runs", async () => {
 		const handler = vi.fn();
 		const workflow = createWorkflow({

package/src/workflow.ts

@@ -22,6 +22,19 @@ 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" };
+	},
+};
+
 /**
  * Configuration passed to {@link createWorkflow}.
  */
@@ -45,6 +58,11 @@ export type WorkflowConfiguration<
 	 */
 	triggers: TTriggers;
 
+	/**
+	 * Connections that must be set up before this workflow can run.
+	 */
+	connections?: readonly WorkflowConnection[];
+
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
 		context: WorkflowContext,
@@ -68,6 +86,7 @@ export type Workflow<
 		name: string;
 		description: string;
 		triggers: TTriggers;
+		connections?: readonly WorkflowConnection[];
 	};
 	handler: (
 		event: WorkflowEventForTriggers<TTriggers>,
@@ -104,12 +123,25 @@ export type Workflow<
 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);
+		}
+	}
+
 	return {
 		_tag: "workflow",
 		config: {
 			name: configuration.name,
 			description: configuration.description,
 			triggers: configuration.triggers,
+			...(configuration.connections === undefined
+				? {}
+				: { connections: configuration.connections }),
 		},
 		async handler(
 			event: WorkflowEventForTriggers<TTriggers>,