@notionhq/apps 0.0.29 → 0.0.31

package/docs/CONNECTIONS.md

@@ -1,213 +0,0 @@
-# Workflow connections
-
-Workflow connections declare services that a workflow needs to work properly. Connections require explicit authentication during setup before the workflow can use them. Each connection has a stable binding that links it to its configured credentials and permissions.
-
-```ts
-import { workflow } from "@notionhq/apps";
-import { connections } from "@notionhq/apps/workflow";
-import { triggers } from "@notionhq/apps/triggers";
-
-export default workflow({
-	name: "List work calendars",
-	description: "List calendars available through the work connection",
-	triggers: [triggers.notionPageCreated()],
-	connections: { work: connections.calendar() },
-	handler: async (_event, context) => {
-		const calendars = await context.connections.work.listCalendars({});
-		console.log(calendars.accounts);
-	},
-});
-```
-
-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
-
-Use a trigger callback to check connection keys against the workflow’s declared providers:
-
-```ts
-export default workflow({
-	name: "Support messages",
-	description: "Run when a message arrives in the configured support channel",
-	connections: { support: connections.slack() },
-	triggers: ({ triggers }) => [triggers.slackMessage({ connectionKey: "support" })],
-	handler: async (event, context) => {
-		console.log(event);
-		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 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, Mail, 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.
-
-## Use provider methods
-
-Use the typed provider client to invoke a method:
-
-```ts
-const calendars = await context.connections.work.listCalendars({});
-const user = await context.connections.support.findUserByEmail({
-	email: "person@example.com",
-});
-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 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.
-
-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 generates clients for Calendar, Mail, 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 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.
-
-### Mail
-
-`connections.mail()` uses the personal Mail connection and selected accounts configured in workflow setup. It is separate from the admin-enabled `connections.gmail()` and `connections.outlook()` search connectors.
-
-```ts
-import { workflow } from "@notionhq/apps";
-import { connections } from "@notionhq/apps/workflow";
-
-export default workflow({
-	name: "Read unread mail",
-	description: "Search the configured mailbox when an email arrives",
-	connections: { inbox: connections.mail() },
-	triggers: ({ triggers }) => [triggers.mailEmailReceived({ connectionKey: "inbox" })],
-	handler: async (_event, context) => {
-		await context.step("Search unread mail", async () => {
-			const result = await context.connections.inbox.searchEmails({
-				userEmailAddress: "me@example.com",
-				query: "is:unread",
-				count: 20,
-			});
-			if (result.isError) throw new Error("Mailbox search failed");
-			return result;
-		});
-	},
-});
-```
-
-Mail exposes reads such as `searchEmails`, `viewThreadContent`, `readAttachment`, and `listLabels`, plus writes such as `sendNewEmail`, draft creation, and label updates. Search accepts `pageToken` for pagination. Results preserve the Mail tool response, including `content`, optional `structuredContent`, and `isError`; inspect the provider's response before using its contents. The server enforces selected accounts and action permissions on every call.
-
-### Mail and Calendar write approval
-
-Mail and Calendar write methods are available in configured workflows, including sending email and creating, updating, or canceling calendar events. Configuring and publishing the workflow authorizes unattended execution within the connection's permissions. The server automatically approves ordinary action confirmations for the workflow's granted Mail and Calendar connections; app code does not need to approve individual calls.
-
-Account and calendar permissions still apply. Auto-approval does not grant access to an unselected mailbox, enable disallowed sending, or make a read-only calendar writable. Other confirmation requirements are not automatically approved. Direct agent calls retain their existing confirmation behavior.
-
-## Regenerate provider clients
-
-From `apps-sdk`, with a compatible sibling `notion-next` checkout and its mise toolchain installed:
-
-```sh
-pnpm exec tsx scripts/sync-connections.ts
-pnpm exec tsx scripts/sync-connections.ts --check
-```
-
-Pass a checkout path as the final argument if it is elsewhere. The script uses the server checkout’s mise toolchain because the repositories can use different Node versions. You can also run these commands directly from `notion-next`:
-
-```sh
-notion tool-core codegen-script-types --connections --path ../apps-sdk/src
-notion tool-core codegen-script-types --connections --path ../apps-sdk/src --check
-```
-
-### How generation works
-
-1. The generator reads `src/shared/workflows/connectionProviders.ts` in `notion-next`. Each entry selects a provider; the server owns its authentication and readiness checks.
-2. For each provider, it reads the corresponding workflow module's effects. It keeps effects backed by a Tool Core definition, exposed to script agents, and not excluded from the connection API. Mail and Calendar include writes because the workflow runtime can approve their action confirmations. Other providers include only read-only methods or methods without a confirmation policy. Server permission checks still apply; workflows do not yet support human confirmation steps.
-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 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
-
-Use compatible checkouts of both repositories.
-
-1. Update the operation's Tool Core contract and workflow projection in `notion-next`. Changes to input/output schemas, effect exposure, or provider registration can require regeneration.
-2. Run `pnpm exec tsx scripts/sync-connections.ts` and its `--check` variant from `apps-sdk`. This regenerates provider clients, trigger metadata, and trigger helpers together. After using the direct server command instead, run `pnpm run generate` in `apps-sdk` as well.
-3. In `apps-sdk`, run `pnpm run typecheck`, `pnpm run lint`, `pnpm test`, `pnpm run build:types`, and `pnpm run build:js`.
-4. Commit all changed generated provider files in the SDK PR, and link the corresponding server PR. Review wire compatibility and deploy server support before consumers rely on new methods.
-
-For a new provider, add its server registry entry and supported module type, and ensure its workflow module implements connection setup, permission checks, and Tool Core-backed effects. Then regenerate. Registration alone does not create authentication or port legacy operations into Tool Core. Regeneration adds the provider’s declaration helper and typed methods to the SDK.
-
-`--check` compares checked-in output with the selected local server checkout. SDK CI currently checks compilation and tests but does **not** check out `notion-next` or enforce cross-repository provider-codegen freshness. Synchronization is manual today. Generated files must not be edited by hand, and removed providers require removing their obsolete generated files as well.
-
-This does not require app developers to import server code or install Tool Core at runtime.
-
-## Runtime and rollout
-
-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/docs/workflow-inputs.md

@@ -1,28 +0,0 @@
-# Workflow input values
-
-Use `input` from `@notionhq/apps` to describe a `context.wait.forInput` form:
-
-```ts
-const response = await context.wait.forInput("Launch details", {
-	input: {
-		teams: input.multiSelect(["Design", "Engineering"]),
-		owners: input.person(),
-		window: input.date(),
-		attachments: input.files({ optional: true }),
-	},
-});
-```
-
-- `teams` is an array of the declared options, typed as `("Design" | "Engineering")[]`.
-- `owners` is a `string[]` of all selected user IDs, including when only one person
-  is selected. This replaces the previous scalar `string` response.
-- `window` is `{ start: string; end?: string; timeZone?: string }`, not a string.
-  Date-only endpoints use `YYYY-MM-DD`; timed endpoints use local `YYYY-MM-DDTHH:mm`
-  together with the selected IANA `timeZone`. Ranges retain both endpoints.
-  The type is available as `WorkflowInputDate` from `@notionhq/apps/workflow`.
-- `attachments` is a `string[]` with one URL or Notion attachment block ID per item,
-  in property order. Attachment display names are not returned as URLs.
-
-Empty required multi-select, person, and file inputs keep the request waiting. Empty optional
-inputs are omitted. Selections outside the declared options keep the request waiting
-so the respondent can correct them.