@notionhq/apps 0.0.28 → 0.0.30

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/apps",
-	"version": "0.0.28",
+	"version": "0.0.30",
 	"description": "An SDK for building workflow apps for Notion",
 	"license": "MIT",
 	"bin": {
@@ -8,10 +8,8 @@
 	},
 	"files": [
 		"skills/",
-		"AGENTS.md",
 		"dist/",
 		"src/",
-		"docs/",
 		"LICENSE.md",
 		"README.md"
 	],

package/skills/connections/SKILL.md

@@ -6,6 +6,9 @@ user-invocable: false
 
 # Workflow connections
 
+For calendar functionality, use only `connections.calendar`. Do not use another
+connection provider or connection as a calendar integration.
+
 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

package/AGENTS.md

@@ -1,40 +0,0 @@
-# Agent instructions
-
-Before creating, modifying, or troubleshooting an App capability, read the
-matching skill:
-
-- [Workflows](./skills/workflow/SKILL.md)
-- [Connections](./skills/connections/SKILL.md)
-- [Database syncs](./skills/sync/SKILL.md)
-- [Custom blocks](./skills/custom-blocks/SKILL.md)
-- [Notion as Code](./skills/notion-as-code/SKILL.md)
-
-Resolve these links relative to this package directory. Check the installed SDK
-declarations for current API details.
-
-## Pull requests for SDK changes
-
-For a change to the public SDK, show the user-facing code change in the pull
-request body. Put a short, complete example near the top:
-
-````md
-## User code
-
-### Before
-
-```ts
-// Existing app code
-```
-
-### After
-
-```ts
-// Updated app code
-```
-````
-
-Use the same small example in both sections so reviewers can compare them
-quickly. Include imports and the call that changed when they matter. Show
-normal app code, not internal types, tests, generated files, or provisioning
-output. Explain any required migration steps in plain language below the
-example.

package/docs/BUILD.md

@@ -1,268 +0,0 @@
-# App build process
-
-`notion-apps build` discovers capability modules and produces:
-
-- `dist/worker.js`, an ESM bundle containing the app's workflows and syncs.
-- `dist/manifest.json`, the static capability and resource manifest.
-- `dist/provisioning.json`, only when the app declares Notion-as-Code resources.
-
-## Project convention
-
-Each top-level TypeScript file under a capability directory must default-export the
-corresponding capability. The filename becomes its key:
-
-| Directory           | Default export     |
-| ------------------- | ------------------ |
-| `src/workflows/`    | `workflow(...)`    |
-| `src/syncs/`        | `sync(...)`        |
-| `src/customBlocks/` | `customBlock(...)` |
-
-```text
-my-app/
-├── src/
-│   ├── notion.ts
-│   ├── workflows/
-│   │   └── onPageCreated.ts
-│   └── lib/
-│       └── processPage.ts
-├── .notion/
-└── dist/
-    ├── worker.js
-    └── manifest.json
-```
-
-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
-
-1. Discover top-level files in the capability directories.
-2. Generate `.notion/entry.ts` with workflow and sync imports and a dispatcher.
-3. Bundle the app's code into `dist/worker.js`, leaving npm packages external.
-4. Evaluate custom-block declarations separately. Blocks do not enter `worker.js`.
-5. Evaluate worker and custom-block capabilities in a separate build-only metadata bundle to record
-   Notion-as-Code declarations. Validate workflow access references against those
-   declarations before writing the manifest and optional provisioning artifact.
-6. Emit `dist/manifest.json` and, when declarations exist, `dist/provisioning.json`.
-
-Capability 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.
-
-## 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"`,
-`version: 1`, and an `intents` array. These declarations are build metadata, not
-provisioning operations executed by the deployed Worker.
-
-After a successful build, the artifact reflects the current declarations. If no
-declarations remain, the build removes any previous `dist/provisioning.json`
-rather than uploading stale intents or emitting an empty artifact. This also
-works when rebuilding into a reused `dist/` directory. Removing the artifact does
-not delete previously provisioned Notion resources or reset their cloud state.
-Do not deploy the output of a failed build.
-
-Build and coordination modes use the existing CLI arguments:
-
-| Command                               | Build location                                   | Deployment coordination       |
-| ------------------------------------- | ------------------------------------------------ | ----------------------------- |
-| `ntn apps deploy`                     | Cloud sandbox, using the project's installed SDK | Server (`workersBuildWorker`) |
-| `ntn apps deploy --local-build --yes` | Local `notion-apps build`                        | CLI, as on `main`             |
-
-Cloud builds do not require the SDK or Node.js on the invoking machine. The
-uploaded project must declare its SDK dependency and a `build` script that invokes
-`notion-apps build`; the cloud runner uses the existing `npm run build` or
-`pnpm run build` command, not a separate SDK command. The CLI creates an App-linked
-Worker using `workersCreateWorker` with `createApp: true`, or updates the existing
-Worker, then uploads source and calls `workersBuildWorker` with the Worker ID.
-For App-linked Workers, the build endpoint coordinates capability registration,
-Notion-as-Code provisioning, database attachment, workflow binding resolution,
-and workflow permission reconciliation before reporting build success.
-It returns the normal build result and run ID, not provisioning state. No separate
-Apps deployment endpoint is required.
-
-For App-linked Workers, the Notion-as-Code build phase prepares a separate
-upload target, like the manifest target, for optional `dist/provisioning.json`.
-The cloud runner uploads the file only if the build emits it; an upload failure
-fails the build. The provisioning hooks read the JSON directly, not from the Worker
-bundle. Provisioning JSON is limited to 5 MiB; a missing object means there are no
-provisioning declarations, while other read errors or invalid JSON fail deployment.
-
-This upload is a retained, deployment-scoped object in the existing Workers S3
-bucket. The coordinator leaves it in storage after successful or failed deployment
-attempts. It records build declarations, not the durable installation-owned
-Notion-as-Code resource mappings and state.
-Ordinary Worker deployment APIs, responses, and storage lifecycle are unchanged.
-
-`--local-build` preserves the current CLI-coordinated setup. The CLI builds and
-uploads the Worker bundle and manifest, uses the existing Notion-as-Code apply
-flow and local state, and reconciles attachments. It reads the optional
-`dist/provisioning.json` locally and does not upload it separately or invoke
-the cloud build endpoint.
-
-Workflows with nonempty `access` require cloud deployment. The local-build path
-rejects them after the SDK build and before uploading or deploying the bundle.
-
-Custom-block default bindings are stored in `manifest.json` as resource IDs and
-resolved to live data source and property IDs during deployment. Live resource
-bindings are not stored in SDK build output. Local deployments retain a
-local state file and report `state_file`; cloud deployments keep installation-owned
-resource mappings and state on the server. Cloud builds do not import local state
-or return provisioning state to the CLI. Local and cloud state are independent:
-switching between modes may recreate resources rather than reuse existing bindings.
-
-Cloud failures never automatically retry locally. There is no rollback: code or
-resources may already have changed when a deployment fails.
-
-## Workflow access
-
-`workflow({ access: { handbook: access.view(handbook) }, ... })`
-declares access to a NaC resource and a named runtime binding. The manifest
-contains only the alias and its symbolic `{ type, resourceId, level }`
-requirement; live IDs are not build output.
-Build validation rejects references missing from the current provisioning
-declarations or having the wrong resource kind. `resourceId` is required because
-it identifies the declaration used for this validation and binding.
-
-After provisioning, cloud deployment resolves requirements against the successful
-NaC apply result. It reconciles code-managed grants through the existing
-Notion-module permissions and saves those permissions together with resolved
-bindings on the workflow's worker module, keyed by capability and alias, in one
-workflow transaction. Bindings are not authorization: the existing permissions
-authorize `context.notion` calls. Redeployment updates or removes code-managed
-grants as declarations change while preserving manually configured UI grants.
-
-Execution reads the selected workflow configuration, not the latest NaC state,
-validates the bindings against the capability requirements, and injects only that
-capability's declared bindings. The SDK exposes typed, readonly `{ type, id }`
-entries in `context.access`; UI-granted resources do not appear there. Use live
-record IDs directly in `context.notion` calls for UI-granted resources; those
-calls remain subject to the existing permissions. Missing or mismatched bindings
-fail before the handler executes.
-
-See the [workflow skill](../skills/workflow/SKILL.md#resources-created-with-the-app)
-for supported resource types, access levels, and an authoring example.
-
-## Manifest
-
-The workflow-only manifest retains the platform's existing resource fields as empty arrays:
-
-```json
-{
-	"$schema": "notion:apps-manifest:v1",
-	"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.

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.