@notionhq/apps 0.0.13 → 0.0.14

package/docs/BUILD.md

@@ -1,14 +1,21 @@
-# Workflow build process
+# App build process
 
-`notion-apps build` discovers workflow modules and produces two deployable artifacts:
+`notion-apps build` discovers capability modules and produces:
 
-- `dist/worker.js`, an ESM bundle containing the app's workflow code.
-- `dist/manifest.json`, a static description of its workflows and triggers.
+- `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 `src/workflows/` must default-export the result of
-`createWorkflow(...)`. The filename becomes the workflow key.
+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/`    | `createWorkflow(...)`    |
+| `src/syncs/`        | `createSync(...)`        |
+| `src/customBlocks/` | `createCustomBlock(...)` |
 
 ```text
 my-app/
@@ -23,19 +30,81 @@ my-app/
     └── manifest.json
 ```
 
-Files elsewhere under `src/` are ordinary modules and enter the bundle only when a workflow
-imports them. Directories for other capability types are not discovered.
+Files elsewhere under `src/` are ordinary modules and enter the build only when imported
+by a capability. Capability discovery does not recurse into subdirectories.
 
 ## Pipeline
 
-1. Discover top-level `src/workflows/*.ts` files.
-2. Generate `.notion/entry.ts` with static imports and a workflow dispatcher.
+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. Import the bundle once, validate every workflow export and its JSON-safe configuration, and
-   write `dist/manifest.json`.
+4. Evaluate custom-block declarations separately, validate capability exports and
+   configuration, and write `dist/manifest.json`. Blocks do not enter `worker.js`.
+5. Evaluate worker capabilities in a separate build-only metadata bundle to record
+   Notion-as-Code declarations, then emit `dist/provisioning.json` if there are any.
+
+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.
+
+## 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, and database attachment 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.
+
+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.
 
-Workflow modules must therefore be importable without secrets or network access. Read required
-environment variables and make requests inside handlers or workflow steps, not at module scope.
+Cloud failures never automatically retry locally. There is no rollback: code or
+resources may already have changed when a deployment fails.
 
 ## Manifest
 

package/docs/CONNECTIONS.md

@@ -0,0 +1,129 @@
+# 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 { connections, createWorkflow } from "@notionhq/apps/workflow";
+import { triggers } from "@notionhq/apps/triggers";
+
+export default createWorkflow({
+	name: "List work calendars",
+	description: "List calendars available through the work connection",
+	triggers: [triggers.notionPageCreated()],
+	connections: [connections.calendar({ key: "work" })],
+	handler: async (_event, context) => {
+		const calendars = await context.connections.calendar("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.
+
+## Trigger a workflow from a connection
+
+Use a trigger callback to check connection keys against the workflow’s declared providers:
+
+```ts
+export default createWorkflow({
+	name: "Support messages",
+	description: "Run when a message arrives in the configured support channel",
+	connections: [connections.slack({ key: "support" })],
+	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" });
+		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 runs once when `createWorkflow` 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" })`.
+
+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.calendar().listCalendars({});
+const user = await context.connections.slack("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 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.
+
+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>`.
+
+## 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.
+
+Providers outside the supported list are not currently available as workflow connections. Unsupported declarations receive an unavailable-provider error.
+
+## 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, not excluded from the connection API, and without an explicit confirmation requirement. 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 the declaration helpers and provider factories. 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.calendar("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.

package/package.json

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

package/src/box.generated.ts

@@ -0,0 +1,187 @@
+// Generated by notion tool-core codegen-script-types --connections. Do not edit.
+import type { ConnectionActionInvoker } from "./connection-actions.js"
+/**
+ * Script input for the "Find shared Box item" effect (`box.findSharedItem`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Resolve a Box shared link to an item ID and type.
+ */
+export type FindSharedItemScriptInput = {
+	/**
+	 * The full Box shared link URL.
+	 */
+	sharedLink: string
+}
+
+/**
+ * Canonical Tool Core output for the "Find shared Box item" effect (`box.findSharedItem`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type FindSharedItemScriptOutput = {
+	itemId: string
+	/**
+	 * One of: `file`, `folder`
+	 */
+	itemType: "file" | "folder"
+	name: string
+	size: number
+	modifiedAt: string
+	owner: string
+}
+
+/**
+ * Script input for the "Load Box file" effect (`box.loadFile`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Load a Box file by its file ID.
+ */
+export type LoadFileScriptInput = {
+	/**
+	 * The Box file ID.
+	 */
+	fileId: string
+}
+
+/**
+ * Canonical Tool Core output for the "Load Box file" effect (`box.loadFile`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type LoadFileScriptOutput = {
+	/**
+	 * Always `box-file`
+	 */
+	type: "box-file"
+	title: string
+	blocks: Array<string>
+	fileId: string
+}
+
+/**
+ * Script input for the "List Box folder" effect (`box.lsFolder`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * List files and subfolders in a Box folder.
+ */
+export type LsFolderScriptInput = {
+	/**
+	 * The Box folder ID to list contents of.
+	 */
+	folderId: string
+}
+
+/**
+ * Canonical Tool Core output for the "List Box folder" effect (`box.lsFolder`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type LsFolderScriptOutput = {
+	items: Array<{
+		id: string
+		/**
+		 * One of: `file`, `folder`
+		 */
+		type: "file" | "folder"
+		name: string
+		size: number
+		modifiedAt: string
+	}>
+}
+
+/**
+ * Script input for the "Search Box" effect (`box.search`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Search Box via the configured connector.
+ */
+export type SearchScriptInput = {
+	/**
+	 * A single, focused question to search for.
+	 */
+	question: string
+	/**
+	 * Brief keywords capturing the core entities.
+	 */
+	keywords?: string
+	/**
+	 * Optional time window. Use only "default", "all_time", a duration matching /^\d+[dwmy]$/ (for example, "7d", "2w", "3m", or "1y"), or a date in "YYYY-MM-DD" format. Do not use natural-language durations or combine units.
+	 */
+	lookback?: string
+	/**
+	 * Optional list of Box folder IDs to scope the search to. Use findSharedItem or searchFolders to get folder IDs.
+	 */
+	folderIds?: Array<string>
+}
+
+/**
+ * Canonical Tool Core output for the "Search Box" effect (`box.search`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type SearchScriptOutput = {
+	results: Array<{
+		id: string
+		title: string
+		path: string
+		text: string
+		lastEdited: string
+		isPrivate: boolean
+		pageId: string
+		fileType: string
+		fileId: string
+	}>
+}
+
+/**
+ * Script input for the "Search Box folders" effect (`box.searchFolders`),
+ * derived from its Tool Core definition's call_function input projection.
+ *
+ * Search Box folders by name.
+ */
+export type SearchFoldersScriptInput = {
+	/**
+	 * The search query for finding folders.
+	 */
+	question: string
+	/**
+	 * Optional additional keywords to refine the folder search.
+	 */
+	keywords?: string
+}
+
+/**
+ * Canonical Tool Core output for the "Search Box folders" effect (`box.searchFolders`).
+ * This is the definition's output schema; the effect's script surface may
+ * re-encode it before returning.
+ */
+export type SearchFoldersScriptOutput = {
+	results: Array<{
+		id: string
+		name: string
+		folderId: string
+	}>
+}
+
+export class BoxConnectionClient {
+	constructor(private readonly invoke: ConnectionActionInvoker) {}
+	findSharedItem(
+		args: FindSharedItemScriptInput,
+	): Promise<FindSharedItemScriptOutput> {
+		return this.invoke<FindSharedItemScriptOutput>("findSharedItem", args)
+	}
+	loadFile(args: LoadFileScriptInput): Promise<LoadFileScriptOutput> {
+		return this.invoke<LoadFileScriptOutput>("loadFile", args)
+	}
+	lsFolder(args: LsFolderScriptInput): Promise<LsFolderScriptOutput> {
+		return this.invoke<LsFolderScriptOutput>("lsFolder", args)
+	}
+	search(args: SearchScriptInput): Promise<SearchScriptOutput> {
+		return this.invoke<SearchScriptOutput>("search", args)
+	}
+	searchFolders(
+		args: SearchFoldersScriptInput,
+	): Promise<SearchFoldersScriptOutput> {
+		return this.invoke<SearchFoldersScriptOutput>("searchFolders", args)
+	}
+}