@notionhq/apps 0.0.1

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/workflow.d.ts

@@ -0,0 +1,125 @@
+import type { CapabilityContext } from "./context.js";
+import { type RunMetadata } from "./runtime-metadata.js";
+import type { WorkflowEventMap, WorkflowTrigger } from "./triggers.generated.js";
+type HandlerOptions = {
+    /** Return the concrete result instead of writing the output envelope. */
+    concreteOutput?: true;
+};
+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]>;
+/**
+ * Configuration passed to {@link createWorkflow}.
+ */
+export type WorkflowConfiguration<TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]]> = {
+    /**
+     * A human-readable name for the workflow, shown in the UI when viewing workflows
+     */
+    name: string;
+    /**
+     * A human-readable description of what the workflow does, shown in the UI when viewing workflows
+     */
+    description: string;
+    /**
+     * An array of triggers that can invoke this workflow.
+     *
+     * Each trigger defines a specific event or condition that causes the workflow to run.
+     */
+    triggers: TTriggers;
+    handler: (event: WorkflowEventForTriggers<TTriggers>, context: WorkflowContext) => Promise<void> | void;
+};
+/**
+ * A workflow capability as returned by {@link createWorkflow}.
+ *
+ * Note that a workflow carries no key of its own — the build tool derives
+ * the capability key from the file the workflow is default-exported from.
+ */
+export type Workflow<TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]] = readonly [
+    WorkflowTrigger,
+    ...WorkflowTrigger[]
+]> = {
+    _tag: "workflow";
+    config: {
+        name: string;
+        description: string;
+        triggers: TTriggers;
+    };
+    handler: (event: WorkflowEventForTriggers<TTriggers>, options?: HandlerOptions) => Promise<{
+        status: "success";
+    } | undefined>;
+};
+/**
+ * Create a workflow capability.
+ *
+ * Default-export the result from a file directly under `src/workflows/` —
+ * the file's basename becomes the workflow's key.
+ *
+ * @example
+ * ```ts
+ * // src/workflows/onPageCreated.ts
+ * import { triggers } from "@notionhq/apps/triggers";
+ * import { createWorkflow } from "@notionhq/apps/workflow";
+ *
+ * export default createWorkflow({
+ *   name: "Send Welcome Email",
+ *   description: "Sends a welcome email when a new page is added",
+ *   triggers: [triggers.notionPageCreated()],
+ *   handler: async (event, context) => {
+ *     console.log(event.page);
+ *     await context.step("Process page", async ({ id }) => {
+ *       console.log(`Running step ${id}`);
+ *       return processPage(event.page);
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export declare function createWorkflow<const TTriggers extends readonly [WorkflowTrigger, ...WorkflowTrigger[]]>(configuration: WorkflowConfiguration<TTriggers>): Workflow<TTriggers>;
+/** Context passed to a workflow step. */
+export type StepContext = {
+    /**
+     * An identifier that is stable for this step across attempts of the workflow run.
+     * Use this to make side effects idempotent when the workflow is retried.
+     */
+    id: string;
+};
+type WorkflowStepResult<T> = T extends void ? null : T;
+/** Options for a workflow step. */
+export type WorkflowStepOptions = {
+    /**
+     * A stable key used to identify this step across attempts of a workflow run.
+     * Pass a string for a single key segment or an array of strings for a composite
+     * key. Defaults to the step name. Changing the key creates a new logical step.
+     */
+    key: string | string[];
+};
+type WorkflowStep = {
+    <T>(name: string, fn: (context: StepContext) => T | Promise<T>): Promise<WorkflowStepResult<T>>;
+    <T>(name: string, options: WorkflowStepOptions, fn: (context: StepContext) => T | Promise<T>): Promise<WorkflowStepResult<T>>;
+};
+/** Context passed to a workflow handler. */
+export type WorkflowContext = CapabilityContext & RunMetadata & {
+    /**
+     * Run an observable unit of work within the workflow.
+     *
+     * The callback may be synchronous or asynchronous, but `step` always returns
+     * a promise. Its return value must be JSON-serializable so it can be included
+     * in the success event written to stdout. A callback that returns `undefined`
+     * is normalized to `null`, which keeps first runs and saved replays consistent.
+     *
+     * The step name is used to derive its stable replay key by default. Step key
+     * inputs must be unique within a workflow invocation. Pass an explicit string
+     * or array of strings when display names are duplicated or may change.
+     *
+     * @example
+     * ```ts
+     * const page = await context.step("Fetch page", async ({ id }) => {
+     *   console.log(`Running step ${id}`);
+     *   return context.notion.pages.retrieve({ page_id: pageId });
+     * });
+     * ```
+     */
+    step: WorkflowStep;
+};
+export {};
+//# sourceMappingURL=workflow.d.ts.map

package/dist/workflow.d.ts.map

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

package/dist/workflow.js

@@ -0,0 +1,210 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createCapabilityContext } from "./context.js";
+import { ExecutionError } from "./error.js";
+import { writeOutput } from "./output.js";
+import { readRunMetadata } from "./runtime-metadata.js";
+function createWorkflow(configuration) {
+  return {
+    _tag: "workflow",
+    config: {
+      name: configuration.name,
+      description: configuration.description,
+      triggers: configuration.triggers
+    },
+    async handler(event, options) {
+      try {
+        const runMetadata = readRunMetadata();
+        const capabilityContext = {
+          ...createCapabilityContext(),
+          ...runMetadata,
+          step: createStep(runMetadata)
+        };
+        await configuration.handler(event, capabilityContext);
+        if (options?.concreteOutput) {
+          return { status: "success" };
+        }
+        writeOutput({ _tag: "success", value: { status: "success" } });
+      } catch (err) {
+        const error = new ExecutionError(err);
+        if (!options?.concreteOutput) {
+          writeOutput({
+            _tag: "error",
+            error: {
+              name: error.name,
+              message: error.message,
+              trace: error.stack
+            }
+          });
+        }
+        throw error;
+      }
+    }
+  };
+}
+const WORKFLOW_STEP_DIRECTORY_ENV_KEY = "NOTION_WORKFLOW_STEP_DIRECTORY";
+const MAX_WORKFLOW_STEP_KEY_LENGTH = 43;
+const WORKFLOW_STEP_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
+const WORKFLOW_STEP_KEY_HASH_DOMAIN = "notion-workflow-step-key";
+const WORKFLOW_STEP_KEY_HASH_VERSION = 1;
+function writeStepEvent(event, value, startedAt, emittedAt = performance.now()) {
+  const tag = `__notion_step_${event}__`;
+  process.stdout.write(
+    `
+<${tag}>${JSON.stringify({
+      ...value,
+      timestampMs: performance.timeOrigin + emittedAt,
+      durationMs: emittedAt - startedAt
+    })}</${tag}>
+`
+  );
+}
+function createStep({ runGroupId }) {
+  const stepNameByKey = /* @__PURE__ */ new Map();
+  async function step(name, optionsOrFn, maybeFn) {
+    const options = typeof optionsOrFn === "function" ? void 0 : optionsOrFn;
+    const fn = typeof optionsOrFn === "function" ? optionsOrFn : maybeFn;
+    if (!fn) {
+      throw new Error(`Workflow step "${name}" is missing its callback.`);
+    }
+    const keyInput = options?.key ?? name;
+    const key = createWorkflowStepKey(typeof keyInput === "string" ? [keyInput] : keyInput);
+    const existingStepName = stepNameByKey.get(key);
+    if (existingStepName !== void 0) {
+      throw new Error(
+        `Workflow step "${name}" has the same key as "${existingStepName}". Step names are used as keys by default; provide a unique name or an explicit key.`
+      );
+    }
+    stepNameByKey.set(key, name);
+    const context = { id: `${runGroupId}:${key}` };
+    const event = { id: context.id, name, key };
+    const startedAt = performance.now();
+    writeStepEvent("started", event, startedAt, startedAt);
+    try {
+      const checkpoint = await readWorkflowStepCheckpoint(key);
+      if (checkpoint) {
+        writeStepEvent(
+          "replayed",
+          {
+            ...event,
+            sourceRunId: checkpoint.sourceRunId,
+            sourceStepId: checkpoint.sourceStepId
+          },
+          startedAt
+        );
+        writeStepEvent(
+          "completed",
+          {
+            ...event,
+            type: "success"
+          },
+          startedAt
+        );
+        return checkpoint.value;
+      }
+      const value = normalizeWorkflowStepResult(await fn(context));
+      writeStepEvent("success", { ...event, value }, startedAt);
+      writeStepEvent(
+        "completed",
+        {
+          ...event,
+          type: "success"
+        },
+        startedAt
+      );
+      return value;
+    } catch (err) {
+      const error = new ExecutionError(err);
+      writeStepEvent(
+        "failure",
+        {
+          ...event,
+          error: {
+            name: error.name,
+            message: error.message,
+            trace: error.stack
+          }
+        },
+        startedAt
+      );
+      writeStepEvent(
+        "completed",
+        {
+          ...event,
+          type: "failure"
+        },
+        startedAt
+      );
+      throw err;
+    }
+  }
+  return step;
+}
+function createWorkflowStepKey(segments) {
+  if (segments.length === 0) {
+    throw new Error("Workflow step keys must contain at least one segment.");
+  }
+  for (const segment of segments) {
+    if (typeof segment !== "string") {
+      throw new Error("Workflow step key segments must be strings.");
+    }
+    if (segment.length === 0) {
+      throw new Error("Workflow step key segments must not be empty.");
+    }
+  }
+  const serialized = JSON.stringify([
+    WORKFLOW_STEP_KEY_HASH_DOMAIN,
+    WORKFLOW_STEP_KEY_HASH_VERSION,
+    ...segments
+  ]);
+  const key = createHash("sha256").update(serialized).digest("base64url");
+  if (key.length !== MAX_WORKFLOW_STEP_KEY_LENGTH || !WORKFLOW_STEP_KEY_PATTERN.test(key)) {
+    throw new Error(
+      `Workflow step keys must be ${MAX_WORKFLOW_STEP_KEY_LENGTH} Base64url characters after hashing.`
+    );
+  }
+  return key;
+}
+function normalizeWorkflowStepResult(value) {
+  return value === void 0 ? null : value;
+}
+async function readWorkflowStepCheckpoint(key) {
+  const directory = process.env[WORKFLOW_STEP_DIRECTORY_ENV_KEY];
+  if (!directory) {
+    return void 0;
+  }
+  const path = join(directory, `${hashWorkflowStepKey(key)}.json`);
+  let serialized;
+  try {
+    serialized = await readFile(path, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+  const parsed = JSON.parse(serialized);
+  if (!isRecord(parsed) || parsed.version !== 0 || parsed.key !== key || !Object.hasOwn(parsed, "value") || typeof parsed.sourceRunId !== "string" || typeof parsed.sourceStepId !== "string") {
+    throw new Error(`Workflow step checkpoint ${hashWorkflowStepKey(key)} is invalid.`);
+  }
+  return {
+    version: 0,
+    key,
+    value: parsed.value,
+    sourceRunId: parsed.sourceRunId,
+    sourceStepId: parsed.sourceStepId
+  };
+}
+function hashWorkflowStepKey(key) {
+  return createHash("sha256").update(key).digest("hex");
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+export {
+  createWorkflow
+};

package/dist/workflow.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=workflow.test.d.ts.map

package/dist/workflow.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.test.d.ts","sourceRoot":"","sources":["../src/workflow.test.ts"],"names":[],"mappings":""}

package/docs/BUILD.md

@@ -0,0 +1,66 @@
+# Workflow build process
+
+`notion-apps build` discovers workflow modules and produces two deployable artifacts:
+
+- `dist/worker.js`, an ESM bundle containing the app's workflow code.
+- `dist/manifest.json`, a static description of its workflows and triggers.
+
+## Project convention
+
+Each top-level TypeScript file under `src/workflows/` must default-export the result of
+`createWorkflow(...)`. The filename becomes the workflow key.
+
+```text
+my-app/
+├── src/
+│   ├── workflows/
+│   │   └── onPageCreated.ts
+│   └── lib/
+│       └── processPage.ts
+├── .notion/
+└── dist/
+    ├── worker.js
+    └── manifest.json
+```
+
+Files elsewhere under `src/` are ordinary modules and enter the bundle only when a workflow
+imports them. Directories for other capability types are not discovered.
+
+## Pipeline
+
+1. Discover top-level `src/workflows/*.ts` files.
+2. Generate `.notion/entry.ts` with static imports and a workflow dispatcher.
+3. Bundle the app's code into `dist/worker.js`, leaving npm packages external.
+4. Import the bundle once, validate every workflow export and its JSON-safe configuration, and
+   write `dist/manifest.json`.
+
+Workflow modules must therefore be importable without secrets or network access. Read required
+environment variables and make requests inside handlers or workflow steps, not at module scope.
+
+## Manifest
+
+The workflow-only manifest retains the platform's existing resource fields as empty arrays:
+
+```json
+{
+	"sdkVersion": "0.0.1",
+	"databases": [],
+	"xldbs": [],
+	"pacers": [],
+	"capabilities": [
+		{
+			"type": "workflow",
+			"key": "onPageCreated",
+			"config": {
+				"name": "Log New Pages",
+				"description": "Logs every page created in the workspace",
+				"triggers": [{ "type": "notion.page.created" }]
+			}
+		}
+	]
+}
+```
+
+The platform invokes a workflow through the generated bundle's `run("workflow", key, event)`
+dispatcher. Workflow results continue using the existing Notion output envelope, and runtime
+metadata continues using the existing `NOTION_*` environment variables and `workerId` field.