@notionhq/apps 0.0.39 → 0.0.41

package/dist/workflow.js

@@ -11,7 +11,7 @@ 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 { ExecutionError, FatalError, RateLimitError, RetryableError } from "./error.js";
 import { writeOutput } from "./output.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
 import { readRunMetadata } from "./runtime-metadata.js";
@@ -47,16 +47,33 @@ const input = {
   }
 };
 const MAX_WORKFLOW_WAIT_MS = 7 * 24 * 60 * 60 * 1e3;
+import { FatalError as FatalError2, RetryableError as RetryableError2 } from "./error.js";
 import { access } from "./workflow-access.js";
 import {
   connections
 } from "./connections.js";
+const MAX_WORKFLOW_RETRY_ATTEMPTS = 3;
+const MAX_WORKFLOW_DURATION_MS = 7 * 24 * 60 * 60 * 1e3;
+const WORKFLOW_STEP_RETRY_BUDGET_MS = 5 * 60 * 1e3;
+const DEFAULT_WORKFLOW_RETRY_POLICY = {
+  maxAttempts: 3,
+  initialDelayMs: 1e3,
+  maxDelayMs: 5 * 60 * 1e3,
+  backoffMultiplier: 2
+};
 function workflow(configuration) {
   const requirements = normalizeConnectionRequirements(configuration.connections ?? {});
   const accessRequirements = normalizeWorkflowAccess(configuration.access);
   const connectionDeclarations = configuration.connections === void 0 ? void 0 : structuredClone(configuration.connections);
   const triggers = typeof configuration.triggers === "function" ? configuration.triggers({ events: createWorkflowEvents() }) : configuration.triggers;
   validateTriggerConnections(triggers, requirements);
+  validateWorkflowDeadline(configuration.deadline);
+  validateWorkflowRetryPolicy(configuration.retry, "Workflow retry policy");
+  if (configuration.retry !== void 0) {
+    validateStepRetryBudget(configuration.retry, void 0, "Workflow retry policy");
+  }
+  const deadline = configuration.deadline === void 0 ? void 0 : structuredClone(configuration.deadline);
+  const retry = configuration.retry === void 0 ? void 0 : manifestRetryPolicy(configuration.retry);
   const manualTriggers = triggers.filter(
     (trigger) => trigger.type === "workflow.manual"
   );
@@ -75,9 +92,13 @@ function workflow(configuration) {
       description: configuration.description,
       triggers: manifestTriggers(triggers, configuration.verify !== void 0),
       ...configuration.connections === void 0 ? {} : { connections: requirements },
-      ...configuration.access === void 0 ? {} : { access: accessRequirements }
+      ...configuration.access === void 0 ? {} : { access: accessRequirements },
+      ...deadline === void 0 ? {} : { deadline },
+      ...retry === void 0 ? {} : { retry }
     },
     async handler(input2, options) {
+      const invocationStartedAt = Date.now();
+      const exhaustedStepErrors = /* @__PURE__ */ new WeakSet();
       try {
         input2 = await resolveRuntimeInput(input2);
         if (isVerifyInvocation(input2)) {
@@ -99,7 +120,11 @@ function workflow(configuration) {
         const event = input2;
         const runMetadata = readRunMetadata();
         const baseContext = createCapabilityContext();
-        const step = createStep(runMetadata);
+        const step = createStep(runMetadata, {
+          defaultRetry: configuration.retry,
+          exhaustedErrors: exhaustedStepErrors,
+          invocationStartedAt
+        });
         const capabilityContext = {
           ...baseContext,
           access: hydrateWorkflowAccess(accessRequirements),
@@ -137,10 +162,27 @@ function workflow(configuration) {
           return;
         }
         const error = new ExecutionError(err);
+        const terminal = err instanceof FatalError || isObject(err) && exhaustedStepErrors.has(err) || !(err instanceof RetryableError) && !isRetryableError(err, configuration.retry);
         if (!options?.concreteOutput) {
           writeOutput({
             _tag: "error",
-            error: {
+            error: !terminal && err instanceof RateLimitError ? {
+              _tag: "rate_limit",
+              name: err.name,
+              message: err.message,
+              ...err.retryAfter === void 0 ? {} : { retryAfter: err.retryAfter }
+            } : !terminal && err instanceof RetryableError ? {
+              _tag: "retryable",
+              name: err.name,
+              message: err.message,
+              trace: err.stack,
+              ...err.retryAfterMs === void 0 ? {} : { retryAfterMs: err.retryAfterMs }
+            } : terminal ? {
+              _tag: "terminal",
+              name: err instanceof Error ? err.name : error.name,
+              message: err instanceof Error ? err.message : error.message,
+              trace: err instanceof Error ? err.stack : error.stack
+            } : {
               name: error.name,
               message: error.message,
               trace: error.stack
@@ -177,16 +219,20 @@ function writeStepEvent(event, value, startedAt, emittedAt = performance.now())
 `
   );
 }
-function createStep(metadata) {
+function createStep(metadata, options) {
   const { runGroupId } = metadata;
+  const { defaultRetry, exhaustedErrors, invocationStartedAt } = options;
   const stepNameByKey = /* @__PURE__ */ new Map();
   async function step(name, optionsOrFn, maybeFn) {
-    const options = typeof optionsOrFn === "function" ? void 0 : optionsOrFn;
+    const stepOptions = 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;
+    validateWorkflowStepOptions(stepOptions);
+    const retry = stepOptions?.retry ?? defaultRetry ?? DEFAULT_WORKFLOW_RETRY_POLICY;
+    validateStepRetryBudget(retry, stepOptions?.timeoutMs, `Workflow step "${name}"`);
+    const keyInput = stepOptions?.key ?? name;
     const key = createWorkflowStepKey(typeof keyInput === "string" ? [keyInput] : keyInput);
     const existingStepName = stepNameByKey.get(key);
     if (existingStepName !== void 0) {
@@ -196,9 +242,7 @@ function createStep(metadata) {
     }
     stepNameByKey.set(key, name);
     const id = `${runGroupId}:${key}`;
-    const stepState = createWorkflowStepState(metadata, id);
-    const context = { id, state: stepState.state };
-    const event = { id: context.id, name, key };
+    const event = { id, name, key };
     const startedAt = performance.now();
     writeStepEvent("started", event, startedAt, startedAt);
     try {
@@ -223,7 +267,16 @@ function createStep(metadata) {
         );
         return checkpoint.value;
       }
-      const value = normalizeWorkflowStepResult(await stepState.run(() => fn(context)));
+      const value = normalizeWorkflowStepResult(
+        await runWorkflowStepCallback({
+          metadata,
+          id,
+          fn,
+          timeoutMs: stepOptions?.timeoutMs,
+          retry,
+          invocationStartedAt
+        })
+      );
       writeStepEvent("success", { ...event, value }, startedAt);
       writeStepEvent(
         "completed",
@@ -234,7 +287,9 @@ function createStep(metadata) {
         startedAt
       );
       return value;
-    } catch (err) {
+    } catch (caught) {
+      const deferred = caught instanceof DeferredStepRetry;
+      const err = deferred ? caught.error : caught;
       const error = new ExecutionError(err);
       writeStepEvent(
         "failure",
@@ -256,11 +311,20 @@ function createStep(metadata) {
         },
         startedAt
       );
+      if (!deferred && isObject(err)) {
+        exhaustedErrors?.add(err);
+      }
       throw err;
     }
   }
   return step;
 }
+class DeferredStepRetry {
+  constructor(error) {
+    this.error = error;
+  }
+  error;
+}
 class WorkflowWaitInterrupt extends Error {
   constructor(result) {
     super(workflowWaitMessage(result));
@@ -430,6 +494,160 @@ function waitDurationUnitMultiplier(unit) {
       throw new Error(`Unsupported workflow wait duration unit: ${unit}`);
   }
 }
+async function runWorkflowStepCallback(args) {
+  let attempt = 1;
+  while (true) {
+    const stepState = createWorkflowStepState(args.metadata, args.id);
+    const context = { id: args.id, state: stepState.state };
+    try {
+      return await stepState.run(() => runWithTimeout(args.fn(context), args.timeoutMs));
+    } catch (error) {
+      if (attempt >= args.retry.maxAttempts || !isRetryableError(error, args.retry)) {
+        throw error;
+      }
+      const delayMs = explicitRetryDelay(error) ?? calculateRetryDelay(args.retry, attempt - 1);
+      const nextAttemptBudgetMs = delayMs + (args.timeoutMs ?? 0);
+      if (Date.now() - args.invocationStartedAt + nextAttemptBudgetMs > WORKFLOW_STEP_RETRY_BUDGET_MS) {
+        throw new DeferredStepRetry(error);
+      }
+      if (delayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+      attempt += 1;
+    }
+  }
+}
+function isRetryableError(error, policy) {
+  if (error instanceof FatalError) {
+    return false;
+  }
+  if (error instanceof RetryableError || policy?.retryOn === void 0) {
+    return true;
+  }
+  const matchers = typeof policy.retryOn === "function" ? [policy.retryOn] : policy.retryOn;
+  return matchers.some(
+    (matcher) => isErrorClass(matcher) ? error instanceof matcher : matcher(error)
+  );
+}
+function isErrorClass(matcher) {
+  return matcher === Error || matcher.prototype instanceof Error;
+}
+function explicitRetryDelay(error) {
+  if (error instanceof RetryableError) {
+    return error.retryAfterMs;
+  }
+  if (error instanceof RateLimitError && error.retryAfter !== void 0) {
+    return error.retryAfter * 1e3;
+  }
+  return void 0;
+}
+async function runWithTimeout(value, timeoutMs) {
+  if (timeoutMs === void 0) {
+    return await value;
+  }
+  let timer;
+  try {
+    return await Promise.race([
+      value,
+      new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+          const error = new Error(`Workflow step timed out after ${timeoutMs}ms.`);
+          error.name = "StepTimeoutError";
+          reject(error);
+        }, timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+    }
+  }
+}
+function calculateRetryDelay(policy, retryIndex) {
+  const delayMs = maxRetryDelay(policy, retryIndex);
+  return delayMs / 2 + Math.random() * (delayMs / 2);
+}
+function maxRetryDelay(policy, retryIndex) {
+  const initialDelayMs = policy.initialDelayMs ?? DEFAULT_WORKFLOW_RETRY_POLICY.initialDelayMs;
+  const maxDelayMs = policy.maxDelayMs ?? DEFAULT_WORKFLOW_RETRY_POLICY.maxDelayMs;
+  const backoffMultiplier = policy.backoffMultiplier ?? DEFAULT_WORKFLOW_RETRY_POLICY.backoffMultiplier;
+  return Math.min(initialDelayMs * backoffMultiplier ** retryIndex, maxDelayMs);
+}
+function validateStepRetryBudget(policy, timeoutMs, label) {
+  let worstCaseMs = (timeoutMs ?? 0) * policy.maxAttempts;
+  for (let retryIndex = 0; retryIndex < policy.maxAttempts - 1; retryIndex++) {
+    worstCaseMs += maxRetryDelay(policy, retryIndex);
+  }
+  if (worstCaseMs > WORKFLOW_STEP_RETRY_BUDGET_MS) {
+    throw new Error(
+      `${label} can spend up to ${worstCaseMs}ms on retry delays and timeouts, which exceeds the ${WORKFLOW_STEP_RETRY_BUDGET_MS}ms limit for one workflow invocation. Lower maxAttempts, the retry delays, or timeoutMs, or use context.wait.until() for longer waits.`
+    );
+  }
+}
+function manifestRetryPolicy(policy) {
+  const { retryOn: _retryOn, ...rest } = policy;
+  return structuredClone(rest);
+}
+function validateWorkflowDeadline(deadline) {
+  if (deadline === void 0) {
+    return;
+  }
+  assertPositiveFiniteNumber(deadline.afterMs, "Workflow deadline afterMs");
+  assertAtMost(deadline.afterMs, MAX_WORKFLOW_DURATION_MS, "Workflow deadline afterMs");
+}
+function validateWorkflowRetryPolicy(policy, label) {
+  if (policy === void 0) {
+    return;
+  }
+  if (!Number.isInteger(policy.maxAttempts) || policy.maxAttempts < 1 || policy.maxAttempts > MAX_WORKFLOW_RETRY_ATTEMPTS) {
+    throw new Error(
+      `${label} maxAttempts must be an integer between 1 and ${MAX_WORKFLOW_RETRY_ATTEMPTS}.`
+    );
+  }
+  if (policy.initialDelayMs !== void 0) {
+    assertNonNegativeFiniteNumber(policy.initialDelayMs, `${label} initialDelayMs`);
+    assertAtMost(policy.initialDelayMs, MAX_WORKFLOW_DURATION_MS, `${label} initialDelayMs`);
+  }
+  if (policy.maxDelayMs !== void 0) {
+    assertNonNegativeFiniteNumber(policy.maxDelayMs, `${label} maxDelayMs`);
+    assertAtMost(policy.maxDelayMs, MAX_WORKFLOW_DURATION_MS, `${label} maxDelayMs`);
+  }
+  if (policy.retryOn !== void 0 && typeof policy.retryOn !== "function" && (!Array.isArray(policy.retryOn) || policy.retryOn.some((matcher) => typeof matcher !== "function"))) {
+    throw new Error(
+      `${label} retryOn must be an error class, a predicate, or an array of them.`
+    );
+  }
+  if (policy.initialDelayMs !== void 0 && policy.maxDelayMs !== void 0 && policy.maxDelayMs < policy.initialDelayMs) {
+    throw new Error(`${label} maxDelayMs must be at least initialDelayMs.`);
+  }
+  if (policy.backoffMultiplier !== void 0 && (!Number.isFinite(policy.backoffMultiplier) || policy.backoffMultiplier < 1)) {
+    throw new Error(`${label} backoffMultiplier must be at least one.`);
+  }
+}
+function validateWorkflowStepOptions(options) {
+  if (options?.timeoutMs !== void 0) {
+    assertPositiveFiniteNumber(options.timeoutMs, "Workflow step timeoutMs");
+  }
+  validateWorkflowRetryPolicy(options?.retry, "Workflow step retry policy");
+}
+function assertAtMost(value, max, label) {
+  if (value > max) {
+    throw new Error(`${label} must be at most ${max}.`);
+  }
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null || typeof value === "function";
+}
+function assertPositiveFiniteNumber(value, label) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${label} must be greater than zero.`);
+  }
+}
+function assertNonNegativeFiniteNumber(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`${label} must be zero or greater.`);
+  }
+}
 function createWorkflowStepKey(segments) {
   if (segments.length === 0) {
     throw new Error("Workflow step keys must contain at least one segment.");
@@ -495,6 +713,8 @@ function isNodeError(error) {
   return error instanceof Error && "code" in error;
 }
 export {
+  FatalError2 as FatalError,
+  RetryableError2 as RetryableError,
   access,
   connections,
   input,

package/package.json

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

package/skills/workflow/SKILL.md

@@ -99,6 +99,52 @@ await context.step("Process page", { key: ["process-page", page.id] }, async ({
 
 Keys must be stable across retries and unique within one workflow run.
 
+Configure a workflow deadline and retry policy only when the platform defaults do
+not fit the workflow:
+
+```ts
+export default workflow({
+	name: "Charge customer",
+	description: "Charges a customer when an invoice is created",
+	triggers: [events.notionPageCreated()],
+	deadline: { afterMs: 7 * 24 * 60 * 60 * 1000 },
+	retry: {
+		maxAttempts: 3,
+		initialDelayMs: 5_000,
+		maxDelayMs: 5 * 60 * 1000,
+		backoffMultiplier: 2,
+	},
+	handler: async (_event, context) => {
+		await context.step(
+			"Charge customer",
+			{ timeoutMs: 30_000, retry: { maxAttempts: 2 } },
+			chargeCustomer,
+		);
+	},
+});
+```
+
+The workflow `retry` policy is the default for every step; a step's `retry`
+replaces it rather than stacking. The run itself is retried only for failures
+outside a step. A step that fails after using its retries fails the run.
+
+`maxAttempts` includes the initial attempt and is at most 4. Without any policy,
+steps make 3 attempts with jittered backoff starting at 1 second, doubling, and
+capped at 5 minutes. A step retries ordinary errors and `RetryableError`, but
+stops immediately for `FatalError`. Set `retryOn` to an error class, a predicate,
+or an array of them to retry only matching errors, for example
+`retryOn: TimeoutError` or `retryOn: [TimeoutError, RateLimitError]`. Pass
+`retryAfterMs` to `RetryableError` when the failing service provides an explicit
+delay. Workflow deadlines include retry delays and are at most 7 days, and step
+timeouts apply to one callback attempt.
+
+Step retries wait inside one workflow invocation, which runs for at most 5
+minutes. The longest possible retry delays plus `timeoutMs` for every attempt
+must fit in 5 minutes, for step policies and for the workflow `retry` policy
+that steps inherit. Earlier work in the invocation counts against the same 5
+minutes; a retry that no longer fits is left to a run retry. Use
+`context.wait.until()` for longer waits.
+
 An external effect can succeed before its step result is saved. Pass the
 callback `id` as an idempotency key when supported; otherwise use a stable
 external ID, upsert, or duplicate check.

package/src/connections.test.ts

@@ -143,6 +143,57 @@ describe("workflow connection runtime", () => {
 		expect(Reflect.get(runtime, "toString")).toBeUndefined();
 		expect(runtime.support).toBe(runtime.support);
 	});
+
+	it("sends newly exposed Slack actions through the declared binding", async () => {
+		vi.stubEnv(
+			"NOTION_CONNECTION_BINDINGS",
+			'[{"key":"support","type":"slack","id":"support-id"}]',
+		);
+		const notion = new Client({ auth: "test" });
+		const request = vi.spyOn(notion, "request").mockResolvedValue({ result: {} });
+		const slack = createWorkflowConnections(notion, {
+			support: connections.slack(),
+		}).support;
+
+		await slack.getUser({ userId: "U123" });
+		await slack.getUserMessages({ email: "person@example.com" });
+		await slack.parseSlackUriOrUrl({
+			uriOrUrl: "https://example.slack.com/archives/C123/p123",
+		});
+		await slack.addReactionToMessage({
+			prefixedMessageUri: "slackMessage://C123/123",
+			reaction: "eyes",
+		});
+		await slack.removeReactionFromMessage({
+			prefixedMessageUri: "slackMessage://C123/123",
+			reaction: "eyes",
+		});
+
+		expect(request.mock.calls.map(([input]) => input.body)).toEqual([
+			{ connection: "support-id", action: "getUser", args: { userId: "U123" } },
+			{
+				connection: "support-id",
+				action: "getUserMessages",
+				args: { email: "person@example.com" },
+			},
+			{
+				connection: "support-id",
+				action: "parseSlackUriOrUrl",
+				args: { uriOrUrl: "https://example.slack.com/archives/C123/p123" },
+			},
+			{
+				connection: "support-id",
+				action: "addReactionToMessage",
+				args: { prefixedMessageUri: "slackMessage://C123/123", reaction: "eyes" },
+			},
+			{
+				connection: "support-id",
+				action: "removeReactionFromMessage",
+				args: { prefixedMessageUri: "slackMessage://C123/123", reaction: "eyes" },
+			},
+		]);
+	});
+
 	it("does not parse missing or malformed bindings until a declared client is used", () => {
 		vi.stubEnv("NOTION_CONNECTION_BINDINGS", "not json");
 		const runtime = createWorkflowConnections(new Client(), { support: connections.slack() });

package/src/error.ts

@@ -11,6 +11,31 @@ export class ExecutionError extends Error {
 	}
 }
 
+/** Explicitly permit another workflow or step attempt. */
+export class RetryableError extends Error {
+	readonly retryAfterMs: number | undefined;
+
+	constructor(message: string, options?: { retryAfterMs?: number }) {
+		super(message);
+		this.name = "RetryableError";
+		if (
+			options?.retryAfterMs !== undefined &&
+			(!Number.isFinite(options.retryAfterMs) || options.retryAfterMs < 0)
+		) {
+			throw new Error("RetryableError retryAfterMs must be zero or greater.");
+		}
+		this.retryAfterMs = options?.retryAfterMs;
+	}
+}
+
+/** Skip remaining workflow or step attempts. */
+export class FatalError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "FatalError";
+	}
+}
+
 /** Tell the platform that an external service asked the sync to slow down. */
 export class RateLimitError extends ExecutionError {
 	readonly retryAfter: number | undefined;