@notionhq/apps 0.0.16 → 0.0.18

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

@@ -1,6 +1,6 @@
 import {
   createWorkflowConnections,
-  validateConnectionRequirements,
+  normalizeConnectionRequirements,
   validateTriggerConnections
 } from "./connections.js";
 import { createHash } from "node:crypto";
@@ -12,29 +12,39 @@ import { writeOutput } from "./output.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
 import { readRunMetadata } from "./runtime-metadata.js";
 import { createWorkflowTriggers } from "./triggers.generated.js";
-import { connections } from "./connections.js";
+import { createWorkflowStepState } from "./workflow-state.js";
+const MAX_WORKFLOW_WAIT_MS = 7 * 24 * 60 * 60 * 1e3;
+import {
+  connections
+} from "./connections.js";
 function workflow(configuration) {
+  const requirements = normalizeConnectionRequirements(configuration.connections ?? {});
+  const connectionDeclarations = configuration.connections === void 0 ? void 0 : structuredClone(configuration.connections);
   const triggers = typeof configuration.triggers === "function" ? configuration.triggers({ triggers: createWorkflowTriggers() }) : configuration.triggers;
-  validateConnectionRequirements(configuration.connections ?? []);
-  validateTriggerConnections(triggers, configuration.connections ?? []);
+  validateTriggerConnections(triggers, requirements);
   return {
     _tag: "workflow",
     config: {
       name: configuration.name,
       description: configuration.description,
       triggers,
-      ...configuration.connections === void 0 ? {} : { connections: configuration.connections }
+      ...configuration.connections === void 0 ? {} : { connections: requirements }
     },
     async handler(event, options) {
       try {
         event = await resolveRuntimeInput(event);
         const runMetadata = readRunMetadata();
         const baseContext = createCapabilityContext();
+        const step = createStep(runMetadata);
         const capabilityContext = {
           ...baseContext,
-          connections: createWorkflowConnections(baseContext.notion),
+          connections: createWorkflowConnections(
+            baseContext.notion,
+            connectionDeclarations
+          ),
           ...runMetadata,
-          step: createStep(runMetadata)
+          step,
+          wait: createWait(step)
         };
         await configuration.handler(event, capabilityContext);
         if (options?.concreteOutput) {
@@ -42,6 +52,16 @@ function workflow(configuration) {
         }
         writeOutput({ _tag: "success", value: { status: "success" } });
       } catch (err) {
+        if (err instanceof WorkflowWaitInterrupt) {
+          if (options?.concreteOutput) {
+            return err.result;
+          }
+          writeOutput({
+            _tag: "wait",
+            wait: err.result.wait
+          });
+          return;
+        }
         const error = new ExecutionError(err);
         if (!options?.concreteOutput) {
           writeOutput({
@@ -75,7 +95,8 @@ function writeStepEvent(event, value, startedAt, emittedAt = performance.now())
 `
   );
 }
-function createStep({ runGroupId }) {
+function createStep(metadata) {
+  const { runGroupId } = metadata;
   const stepNameByKey = /* @__PURE__ */ new Map();
   async function step(name, optionsOrFn, maybeFn) {
     const options = typeof optionsOrFn === "function" ? void 0 : optionsOrFn;
@@ -92,7 +113,9 @@ function createStep({ runGroupId }) {
       );
     }
     stepNameByKey.set(key, name);
-    const context = { id: `${runGroupId}:${key}` };
+    const id = `${runGroupId}:${key}`;
+    const stepState = createWorkflowStepState(metadata, id);
+    const context = { id, state: stepState.state };
     const event = { id: context.id, name, key };
     const startedAt = performance.now();
     writeStepEvent("started", event, startedAt, startedAt);
@@ -118,7 +141,7 @@ function createStep({ runGroupId }) {
         );
         return checkpoint.value;
       }
-      const value = normalizeWorkflowStepResult(await fn(context));
+      const value = normalizeWorkflowStepResult(await stepState.run(() => fn(context)));
       writeStepEvent("success", { ...event, value }, startedAt);
       writeStepEvent(
         "completed",
@@ -156,6 +179,96 @@ function createStep({ runGroupId }) {
   }
   return step;
 }
+class WorkflowWaitInterrupt extends Error {
+  constructor(result) {
+    super(`Workflow is waiting until ${new Date(result.wait.resumeAtMs).toISOString()}`);
+    this.result = result;
+    this.name = "WorkflowWaitInterrupt";
+  }
+  result;
+}
+function createWait(step) {
+  return {
+    async until(name, options) {
+      const keyInput = options.key ?? name;
+      const keySegments = [
+        "wait",
+        "until",
+        ...typeof keyInput === "string" ? [keyInput] : keyInput
+      ];
+      const resumeAtMs = await step(
+        name,
+        { key: keySegments },
+        () => resolveWaitUntilMs(options)
+      );
+      if (Date.now() >= resumeAtMs) {
+        return;
+      }
+      throw new WorkflowWaitInterrupt({
+        status: "waiting",
+        wait: {
+          type: "until",
+          name,
+          resumeAtMs
+        }
+      });
+    }
+  };
+}
+function resolveWaitUntilMs(options) {
+  const now = Date.now();
+  if ("at" in options) {
+    const resumeAtMs = options.at.getTime();
+    if (!Number.isFinite(resumeAtMs)) {
+      throw new Error("Workflow wait date must be valid.");
+    }
+    assertWaitFitsCheckpointRetention(resumeAtMs - now);
+    return resumeAtMs;
+  }
+  const durationMs = workflowWaitDurationMs(options.after);
+  assertWaitFitsCheckpointRetention(durationMs);
+  return now + durationMs;
+}
+function workflowWaitDurationMs(duration) {
+  const entries = Object.entries(duration);
+  if (entries.length === 0) {
+    throw new Error("Workflow wait duration must specify at least one unit.");
+  }
+  let durationMs = 0;
+  for (const [unit, value] of entries) {
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+      throw new Error("Workflow wait duration values must be positive finite integers.");
+    }
+    durationMs += value * waitDurationUnitMultiplier(unit);
+    if (!Number.isSafeInteger(durationMs)) {
+      throw new Error("Workflow wait duration is too large.");
+    }
+  }
+  return durationMs;
+}
+function assertWaitFitsCheckpointRetention(durationMs) {
+  if (durationMs >= MAX_WORKFLOW_WAIT_MS) {
+    throw new Error("Workflow waits must be shorter than 7 days.");
+  }
+}
+function waitDurationUnitMultiplier(unit) {
+  switch (unit) {
+    case "milliseconds":
+      return 1;
+    case "seconds":
+      return 1e3;
+    case "minutes":
+      return 6e4;
+    case "hours":
+      return 36e5;
+    case "days":
+      return 864e5;
+    case "weeks":
+      return 6048e5;
+    default:
+      throw new Error(`Unsupported workflow wait duration unit: ${unit}`);
+  }
+}
 function createWorkflowStepKey(segments) {
   if (segments.length === 0) {
     throw new Error("Workflow step keys must contain at least one segment.");

package/docs/BUILD.md

@@ -20,6 +20,7 @@ corresponding capability. The filename becomes its key:
 ```text
 my-app/
 ├── src/
+│   ├── notion.ts
 │   ├── workflows/
 │   │   └── onPageCreated.ts
 │   └── lib/
@@ -32,6 +33,10 @@ my-app/
 
 Files elsewhere under `src/` are ordinary modules and enter the build only when imported
 by a capability. Capability discovery does not recurse into subdirectories.
+Notion-as-Code declarations may be inline or in an imported helper. Use a local
+module such as `src/workflows/myWorkflow/lib/notion.ts` for resources owned by one
+capability, and `src/notion.ts` for app-wide declarations or resources without a
+natural capability owner.
 
 ## Pipeline
 
@@ -47,6 +52,97 @@ Capability modules must therefore be importable without secrets or network acces
 Read required environment variables and make requests inside handlers or workflow
 steps, not at module scope.
 
+## Declaring Notion-as-Code databases
+
+Database declarations use explicit resource IDs and keyed schemas. For a single
+data source, supply the database ID as the first argument and the distinct data
+source ID in `dataSourceResourceId`:
+
+```ts
+import { notion } from "@notionhq/apps/notion-as-code";
+
+const tasks = notion.database("tasks-db", {
+	dataSourceResourceId: "tasks-source",
+	name: "Tasks",
+	schema: {
+		Name: { type: "title", resourceId: "tasks-name" },
+		Effort: { type: "text", resourceId: "tasks-effort" },
+	},
+});
+```
+
+Here `name` is the single-source shorthand: it supplies both the database and
+data-source display names. The source handle is `tasks.dataSource`; pass it to
+`sync({ dataSource, ... })` from `@notionhq/apps`.
+
+For multiple sources, use `datasources` instead of the top-level `schema`:
+
+````ts
+const work = notion.database("work-db", {
+	name: "Work",
+	datasources: {
+		Tasks: {
+			resourceId: "work-tasks-source",
+			schema: {
+				Name: { type: "title", resourceId: "work-tasks-name" },
+				Effort: { type: "text", resourceId: "work-tasks-effort" },
+			},
+		},
+		Projects: {
+			resourceId: "work-projects-source",
+			schema: {
+				Name: { type: "title", resourceId: "work-projects-name" },
+			},
+		},
+	},
+});
+
+The keys in `datasources` are the source names, so the handles are indexed by
+those names: `work.datasources.Tasks` and `work.datasources.Projects`. Nested
+data-source configs do not accept `name`. The top-level database `name` remains
+supported and names the database; in a single-source declaration it also
+supplies the source display name. Property configs do not accept `name`; each
+schema key is always the property's name. Typed property access uses
+`work.datasources.Tasks.schema.Effort`; sync primary keys and row properties use
+the string/object key `"Effort"`.
+
+Every database, source, and property ID remains explicit and must be unique
+across the provisioning declarations. No IDs are generated from keys or names.
+Preserve explicit IDs when changing authoring keys or display names.
+
+Page and teamspace handles accept the same forms through
+`page.addDatabase("database-id", args)` and `teamspace.addDatabase("database-id", args)`.
+Top-level declarations also accept
+`parent: { type: "resourceId", resourceId: "parent-id" }`; omitting it retains the
+private Apps workspace parent. A database must declare at least one data source
+or at least one view. A linked-only declaration may omit `datasources`, or use
+`datasources: {}`, only with a nonempty `views` list. The empty forms `{}`,
+`{ datasources: {} }`, and `{ datasources: {}, views: [] }` are rejected; widened
+or dynamic maps and arrays are checked at runtime. The single-source `schema` and
+multi-source `datasources` forms cannot be combined.
+
+Here is a linked-only database whose typed table view references an explicit
+data source resource ID:
+
+```ts
+const linked = notion.database("work-linked-db", {
+	views: [
+		{
+			resourceId: "work-issues-table",
+			type: "table",
+			dataSourceResourceId: "issues-source",
+			properties: [{ property: "issue-title", visible: true }],
+		},
+	],
+});
+````
+
+The build converts these declarations to the existing serialized database
+intents: `dataSources` and `properties` remain arrays with exact resource IDs
+and names from the authoring keys. Authoring-only `schema`, `datasources`, and
+database-level `dataSourceResourceId` fields do not leak into the serialized
+database intent. The provisioning JSON envelope and server API are unchanged.
+
 ## Provisioning artifact and deployment
 
 The optional provisioning artifact uses `$schema: "notion:apps-provisioning:v1"`,

package/docs/CONNECTIONS.md

@@ -11,15 +11,15 @@ export default workflow({
 	name: "List work calendars",
 	description: "List calendars available through the work connection",
 	triggers: [triggers.notionPageCreated()],
-	connections: [connections.calendar({ key: "work" })],
+	connections: { work: connections.calendar() },
 	handler: async (_event, context) => {
-		const calendars = await context.connections.calendar("work").listCalendars({});
+		const calendars = await context.connections.work.listCalendars({});
 		console.log(calendars.accounts);
 	},
 });
 ```
 
-An omitted key defaults to the provider type, so `connections.calendar()` is accessed through `context.connections.calendar()`. Keys must be unique, begin with a letter, and contain at most 128 letters, numbers, underscores, or hyphens. A workflow can declare up to 100 requirements.
+The object property name is the connection key. Provider factories do not take a key option. Keys must begin with a letter and contain at most 128 letters, numbers, underscores, or hyphens; `constructor` and `prototype` are reserved. A workflow can declare up to 100 connections.
 
 ## Trigger a workflow from a connection
 
@@ -29,25 +29,25 @@ Use a trigger callback to check connection keys against the workflow’s declare
 export default workflow({
 	name: "Support messages",
 	description: "Run when a message arrives in the configured support channel",
-	connections: [connections.slack({ key: "support" })],
+	connections: { support: connections.slack() },
 	triggers: ({ triggers }) => [triggers.slackMessage({ connectionKey: "support" })],
 	handler: async (event, context) => {
 		console.log(event);
-		const user = await context.connections
-			.slack("support")
-			.findUserByEmail({ email: "person@example.com" });
+		const user = await context.connections.support.findUserByEmail({
+			email: "person@example.com",
+		});
 		console.log(user);
 	},
 });
 ```
 
-The callback’s `triggers.slackMessage` accepts only Slack keys declared in `connections`. In this example, `"typo"` is a type error, and a Calendar connection named `"support"` would not satisfy a Slack trigger. Keys remain literal when you save a declaration in a variable, so the same check works with `const support = connections.slack({ key: "support" })`. Omitting the declaration key defaults to the provider name.
+The callback’s `triggers.slackMessage` accepts only Slack keys declared in `connections`. In this example, `"typo"` is a type error, and a Calendar connection named `"support"` would not satisfy a Slack trigger. Keys come from the object properties, so saving `const slack = connections.slack()` and declaring `{ support: slack }` still restricts the trigger to `"support"`.
 
 The callback runs once when `workflow` is called. Its result is serialized as the ordinary trigger array, and the handler’s event type is inferred from those triggers. Returning a keyed trigger from an imported helper is checked too. Existing static trigger arrays remain supported and validate connection keys at runtime; use the callback for compile-time checking. Unbound triggers, including existing calls without `connectionKey`, keep their existing behavior.
 
 Deployment creates a disabled trigger attached to that connection. Configure the account, channel or calendar, and enable the trigger through workflow setup before publishing. Redeploying preserves its configuration. The server checks the binding at publication and execution, so a trigger on another connection cannot invoke this declaration.
 
-Calendar, Slack, Google Drive OAuth, and Discord currently have generated connection trigger helpers. Providers without registered public trigger events do not gain helpers merely by supporting actions. Existing helper calls without `connectionKey` keep their existing behavior. To bind a default connection such as `connections.calendar()`, use `triggers.calendarEventCreated({ connectionKey: "calendar" })`.
+Calendar, Slack, Google Drive OAuth, and Discord currently have generated connection trigger helpers. Providers without registered public trigger events do not gain helpers merely by supporting actions. Existing helper calls without `connectionKey` keep their existing behavior. For `connections: { calendar: connections.calendar() }`, use `triggers.calendarEventCreated({ connectionKey: "calendar" })`.
 
 Removing a declaration retains the configured trigger, but it can no longer invoke the capability unless another declaration allows it. Renaming a key creates a new connection and disabled trigger. Two keys can declare the same event type independently; repeating the same type and key is rejected.
 
@@ -56,8 +56,8 @@ Removing a declaration retains the configured trigger, but it can no longer invo
 Use the typed provider client to invoke a method:
 
 ```ts
-const calendars = await context.connections.calendar().listCalendars({});
-const user = await context.connections.slack("support").findUserByEmail({
+const calendars = await context.connections.work.listCalendars({});
+const user = await context.connections.support.findUserByEmail({
 	email: "person@example.com",
 });
 console.log(user?.displayName);
@@ -65,21 +65,32 @@ console.log(user?.displayName);
 
 Method inputs and results come from Tool Core's workflow projections. The SDK generates provider clients from those contracts, including any wire input or output transformations. Adding another registered provider generates its client from that provider's Tool Core methods.
 
-The handler context exposes only providers declared in that workflow's
-`connections` list. A Calendar-only declaration exposes `context.connections.calendar`
-but not `context.connections.slack`; omitting connections exposes no provider
-clients. Named keys still select a configured binding at runtime.
+The handler context exposes only the declared keys, each with its provider's client type. With `{ work: connections.calendar(), support: connections.slack() }`, `context.connections.work` is a Calendar client and `context.connections.support` is a Slack client. Missing keys and methods from the wrong provider are type errors. Omitting connections exposes no clients.
 
-For a separate declaration array, let TypeScript infer its type or use
-`satisfies readonly WorkflowConnection[]`. An explicit broad
-`WorkflowConnection[]` annotation erases provider information and prevents this
-narrowing. Reusable helpers can accept `WorkflowContext<typeof requirements>`.
+Two names can use the same provider:
+
+```ts
+connections: {
+	support: connections.slack(),
+	internal: connections.slack(),
+}
+```
+
+`context.connections.support` and `context.connections.internal` use separately configured workflow bindings. Reusing a declaration across workflows does not share credentials.
+
+For a separate declarations object, let TypeScript infer its type or use `satisfies WorkflowConnectionDeclarations`. A broad `WorkflowConnectionDeclarations` annotation loses the exact keys and providers. Reusable helpers can accept `WorkflowContext<typeof declarations>`.
+
+### Migrating from connection arrays
+
+Replace `connections: [connections.calendar({ key: "work" })]` with `connections: { work: connections.calendar() }`, then replace `context.connections.calendar("work")` with `context.connections.work`. For an old declaration with no explicit key, use the provider name as the object property to preserve its existing binding. Arrays and factory key options are no longer supported.
+
+The SDK serializes the object to the existing manifest array of `{ key, type }` requirements. Keeping the same key and provider preserves the server binding.
 
 ## Supported providers and setup
 
 The registry currently generates 73 methods across 12 providers: Calendar, Slack, Google Drive OAuth, Discord, Cursor, Box, Confluence, Gmail, Google Calendar, Google Drive, Outlook, and Salesforce. Only eligible Tool Core methods are generated; this does not expose every operation in those services.
 
-Each connection must be authenticated and granted access through the workflow’s setup flow before use. The server handles provider-specific authentication and checks that setup is complete. App code only declares a provider and optional binding key; declaring a connection never grants permissions.
+Each connection must be authenticated and granted access through the workflow’s setup flow before use. The server handles provider-specific authentication and checks that setup is complete. App code declares a provider under a binding key; declaring a connection never grants permissions.
 
 Providers outside the supported list are not currently available as workflow connections. Unsupported declarations receive an unavailable-provider error.
 
@@ -106,7 +117,7 @@ notion tool-core codegen-script-types --connections --path ../apps-sdk/src --che
 3. It reads the exact Tool Core definition stored on each workflow effect projection, so providers with multiple tool versions use the contract selected by their module.
 4. The existing script-type emitter renders the method's wire input and result types. It honors input field mappings and declared output projections, so the types describe the workflow endpoint contract.
 5. It also reads each provider module’s trigger definitions and emits `connection-trigger-definitions.generated.ts`. The SDK trigger generator intersects these with the public `TriggerEventMap` to generate supported `connectionKey` options, descriptions, event types, and provider-scoped trigger creators. Internal events are not exposed.
-6. It writes `<provider>.generated.ts` with types and thin client methods, plus `providers.generated.ts` with the declaration helpers and provider factories. The runtime transport stays in `connections.ts`.
+6. It writes `<provider>.generated.ts` with types and thin client methods, plus `providers.generated.ts` with keyless declaration helpers, the provider-to-client type map, and the client factory. The runtime transport stays in `connections.ts`.
 
 ### Updating the SDK after a Tool Core change
 
@@ -125,6 +136,43 @@ This does not require app developers to import server code or install Tool Core
 
 ## Runtime and rollout
 
-The runtime automatically connects each declared key to the account configured during workflow setup. For example, `context.connections.calendar("work")` uses the connection configured as `work`. App code does not manage connection IDs or credentials.
+The runtime automatically connects each declared key to the account configured during workflow setup. For example, `context.connections.work` uses the connection configured as `work`. App code does not manage connection IDs or credentials.
 
 Provider method calls currently require the server's local/development environment and `public_api_runtime_sdk_tools` and `workers_call_function` gates. A personal access token alone does not enable these endpoints. Developer portal connection setup UI wiring is a separate follow-up. Renaming a requirement key creates a new binding; removing a requirement does not revoke or delete the server's existing configured module.
+
+## Generic OAuth
+
+Use `connections.oauth()` for an OAuth 2.0 provider without a generated provider client:
+
+```ts
+export default workflow({
+	name: "Read GitHub repositories",
+	description: "Read repositories using this workflow's GitHub authorization",
+	triggers: [triggers.scheduled()],
+	connections: {
+		github: connections.oauth({
+			authorizationEndpoint: "https://github.com/login/oauth/authorize",
+			tokenEndpoint: "https://github.com/login/oauth/access_token",
+			clientId: "your-oauth-app-client-id",
+			clientSecretEnv: "GITHUB_CLIENT_SECRET",
+			scope: "repo",
+		}),
+	},
+	handler: async (_event, context) => {
+		const token = await context.connections.github.accessToken();
+		const response = await fetch("https://api.github.com/user/repos", {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		if (!response.ok) throw new Error(`GitHub returned ${response.status}`);
+		console.log(await response.json());
+	},
+});
+```
+
+Store the client secret in the app's Workers secrets under the name supplied by `clientSecretEnv`. The declaration contains the secret's name, not its value. Optional `authorizationParams` supports provider options such as `access_type: "offline"`; it cannot override state, callback, client ID, scope, or PKCE fields. Optional `accessTokenExpireMs` supplies a positive default expiry for providers that omit it.
+
+Each workflow instance requires separate authorization, even when instances share the same app and declaration. The SDK reads only the access token bound to the current run and does not fall back to app-level `worker.oauth` tokens. The server refreshes tokens before execution; `accessToken()` does not make a refresh request during a long-running handler.
+
+This SDK change requires the matching server OAuth implementation before deployment. In the workflow settings, find the declared connection in **Access**, alongside other provider connections. Choose **Connect** beside the declared key, authorize with the provider, and close the authorization window to refresh status. **Reconnect** replaces authorization for that workflow instance; If the client secret is missing, setup shows the secret name to configure. Setup requires full access to the app and workflow editor access. Store the client secret before connecting, and register the app OAuth callback URL with the provider. The SDK does not configure the provider’s OAuth app for you.
+
+Generic OAuth provides authentication for your own API calls. It does not generate provider methods or provider triggers. Unlike the generated Tool Core clients, this helper is maintained directly in the SDK.

package/package.json

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

package/skills/connections/SKILL.md

@@ -9,15 +9,15 @@ user-invocable: false
 Import `{ workflow }` from `@notionhq/apps` and
 `connections` from `@notionhq/apps/workflow`. Connections are not root exports.
 Declare requirements on the workflow, then use the corresponding typed client
-inside an awaited durable step. Access a named connection through its provider
-client, such as `context.connections.slack("support")`.
+inside an awaited durable step. Access a named connection directly through its key, such as
+`context.connections.support`.
 
 Read the installed provider declarations before choosing methods and inputs.
 The SDK handles transport, credentials, and runtime bindings. Do not construct
 raw tools API envelopes or call internal endpoints. Check the installed version
 supports the typed methods; resolve version mismatches before using them.
-Provider clients are inferred from the declared requirements. Keys default to
-the provider name; custom keys distinguish multiple connections to one provider.
+Provider clients are inferred from the declared requirements. Object property names supply the keys; factories do not accept a key option.
+Separate keys distinguish multiple connections to one provider.
 Keep keys unique and ensure connection-trigger keys match a declared provider.
 
 A declaration requests setup; it grants no access. Deploy and configure the
@@ -49,7 +49,7 @@ import { connections } from "@notionhq/apps/workflow";
 export default workflow({
 	name: "Watch support messages",
 	description: "Runs when a message arrives through the support connection.",
-	connections: [connections.slack({ key: "support" })],
+	connections: { support: connections.slack() },
 	triggers: ({ triggers }) => [triggers.slackMessage({ connectionKey: "support" })],
 	handler: async (_event, context) => {
 		await context.step("Record trigger", () => {
@@ -62,8 +62,7 @@ export default workflow({
 Use the callback's `triggers` argument to get connection-key checking.
 `connectionKey` refers to a declared key for that trigger's provider, not an
 external account ID or a durable step key. Here, a typo or a key belonging to
-a different provider's connection is a type error. Without a custom key,
-`connections.slack()` declares the key `"slack"`.
+a different provider's connection is a type error. For example, `{ slack: connections.slack() }` declares the key `"slack"`.
 
 The SDK also validates explicit bindings when constructing the workflow,
 including array-form triggers: the key must exist and its provider must match.
@@ -73,7 +72,7 @@ manifest. Event types still come from the selected triggers; narrow
 `event.type` before using provider-specific fields in mixed-trigger workflows.
 
 Unkeyed provider triggers remain supported for compatibility. Omitting
-`connectionKey` does not explicitly bind a trigger to the provider's default
+`connectionKey` does not explicitly bind a trigger to a declared
 key; supply it when the workflow should listen through a particular connection.
 SDK validation does not establish server availability or complete connection
 setup.