@notionhq/apps 0.0.17 → 0.0.19

package/dist/workflow.js

@@ -3,6 +3,10 @@ import {
   normalizeConnectionRequirements,
   validateTriggerConnections
 } from "./connections.js";
+import {
+  hydrateWorkflowAccess,
+  normalizeWorkflowAccess
+} from "./workflow-access.js";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -12,11 +16,14 @@ import { writeOutput } from "./output.js";
 import { resolveRuntimeInput } from "./runtime-input.js";
 import { readRunMetadata } from "./runtime-metadata.js";
 import { createWorkflowTriggers } from "./triggers.generated.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 accessRequirements = normalizeWorkflowAccess(configuration.access);
   const connectionDeclarations = configuration.connections === void 0 ? void 0 : structuredClone(configuration.connections);
   const triggers = typeof configuration.triggers === "function" ? configuration.triggers({ triggers: createWorkflowTriggers() }) : configuration.triggers;
   validateTriggerConnections(triggers, requirements);
@@ -26,21 +33,25 @@ function workflow(configuration) {
       name: configuration.name,
       description: configuration.description,
       triggers,
-      ...configuration.connections === void 0 ? {} : { connections: requirements }
+      ...configuration.connections === void 0 ? {} : { connections: requirements },
+      ...configuration.access === void 0 ? {} : { access: accessRequirements }
     },
     async handler(event, options) {
       try {
         event = await resolveRuntimeInput(event);
         const runMetadata = readRunMetadata();
         const baseContext = createCapabilityContext();
+        const step = createStep(runMetadata);
         const capabilityContext = {
           ...baseContext,
+          access: hydrateWorkflowAccess(accessRequirements),
           connections: createWorkflowConnections(
             baseContext.notion,
             connectionDeclarations
           ),
           ...runMetadata,
-          step: createStep(runMetadata)
+          step,
+          wait: createWait(step)
         };
         await configuration.handler(event, capabilityContext);
         if (options?.concreteOutput) {
@@ -48,6 +59,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({
@@ -81,7 +102,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;
@@ -98,7 +120,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);
@@ -124,7 +148,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",
@@ -162,6 +186,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,21 +33,117 @@ 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
 
 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, validate capability exports and
-   configuration, and write `dist/manifest.json`. Blocks do not enter `worker.js`.
+4. Evaluate custom-block declarations separately. 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.
+   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"`,
@@ -74,7 +171,8 @@ uploaded project must declare its SDK dependency and a `build` script that invok
 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.
+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.
 
@@ -97,6 +195,9 @@ 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.
+
 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
@@ -106,6 +207,35 @@ switching between modes may recreate resources rather than reuse existing bindin
 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: { resource: handbook, level: "view" } }, ... })`
+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:

package/package.json

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

package/skills/notion-as-code/SKILL.md

@@ -17,12 +17,20 @@ Import the resource creators you use, such as
 resources for deployment; they do not make Notion API requests when called.
 Use `context.notion` for runtime API operations instead.
 
-Put shared declarations in `src/lib/`, or capability-specific declarations in
-a directory such as `src/syncs/lib/`. Import them from a workflow or sync
-module so the build's metadata evaluation reaches them. An unimported resource
-file is not discovered automatically. Declare resources at module scope, not
-inside handlers or durable steps. Module evaluation must work without
-credentials or network access.
+Declare resources at module scope, not inside handlers or durable steps. Keep a
+small declaration inline when it belongs to one capability. For a larger set
+owned by one capability, use a local module such as
+`src/workflows/myWorkflow/lib/notion.ts`. Use `src/notion.ts` when declarations
+are shared across capabilities or do not have a natural capability owner. Module
+evaluation must work without credentials or network access.
+
+To configure a workflow's access to a declared page, database, data source, or
+custom agent, pass its handle in `access: { alias: { resource: handle, level } }`.
+The handler receives the live identity as `context.access.alias.id`; importing
+a declaration alone does not request access. See the
+[workflow skill](../workflow/SKILL.md#resources-created-with-the-app) for levels
+and examples. Nonempty workflow `access` requires cloud deployment; `--local-build`
+rejects it before upload.
 
 ## Where declarations are picked up
 
@@ -33,24 +41,27 @@ same rule. Their resource type does not determine their file location.
 
 ```text
 src/
-  lib/
-    resources.ts          Shared page/database declarations
+  notion.ts               App-wide resource declarations
   syncs/
-    issues.ts             Default-exported sync; imports ../lib/resources
-    lib/
-      issueSchema.ts      Sync-specific helper; must be imported
+    issues.ts             Default-exported sync; imports ../notion.js
   workflows/
-    notify.ts             Default-exported workflow
+    notify.ts             May declare a small related resource inline
+    myWorkflow.ts         Imports ./myWorkflow/lib/notion.js
+    myWorkflow/
+      lib/
+        notion.ts         Resources owned by myWorkflow
 ```
 
-For example, export a database handle from `src/lib/resources.ts` and import it
-in `src/syncs/issues.ts` for `sync`. A page-only declaration
-module can be loaded with a side-effect import such as
-`import "../lib/pages"` from a workflow or sync. Keep those imports at module
-scope so build evaluation runs the declarations.
+Choose the location based on ownership, not resource type. Export an app-wide
+database handle from `src/notion.ts` and import it in `src/syncs/issues.ts` when
+the sync uses it. A declaration-only module can be loaded with a side-effect
+import. Keep these imports at module scope so build evaluation runs the
+declarations.
 
-There is no automatically scanned `src/pages/`, `src/databases/`, or Notion as Code
-entrypoint. Helpers under `src/syncs/lib/` are not discovered on their own.
+Resource helper modules, including `src/notion.ts`, are not automatically scanned.
+There is no automatically scanned `src/pages/` or `src/databases/` directory
+either. Helpers under capability-specific `lib/` directories are not discovered
+on their own.
 Every direct file in a capability directory must still default-export that
 capability, so do not put a resource-only file there. Imports reached only
 through `src/customBlocks/` or browser code do not enter the Notion as Code recording
@@ -63,12 +74,14 @@ Read the installed Notion as Code types before choosing fields. The Apps
 root exports support:
 
 - `teamspace({ resourceId, name, accessLevel })`, with `addPage` and
-  `addDatabase` on the returned handle.
+  `teamspace.addDatabase(id, args)` on the returned handle.
 - `page({ resourceId, parent?, properties?, content? })`, with
-  `addPage` and `addDatabase` for children.
-- `database({ resourceId, parent?, name?, dataSources? })`, returning
-  data source handles indexed by their resource IDs. A data source's
-  `addPage` declares a row; the database handle also exposes `addView`.
+  `addPage` and `page.addDatabase(id, args)` for children.
+- `database(resourceId, { dataSourceResourceId, name, schema, parent?, views? })`,
+  returning a single source as `handle.dataSource`, or
+  `database(resourceId, { datasources: { Key: { resourceId, schema } }, views?, parent? })`,
+  returning sources as `handle.datasources.Key`. A source's `addPage` declares a row;
+  the database handle also exposes `addView`.
 - `customAgent({ resourceId, name, instructions?, sharedResources? })`.
   Shared resources are declared resource IDs; inspect the installed types
   before specifying models or triggers.
@@ -77,56 +90,71 @@ root exports support:
   Use property resource IDs in view filters, sorts, and layout options; calendar
   views require `calendarBy`, and timeline views require `timelineBy`.
 
+A database declaration must include at least one data source or at least one
+view. A linked-only database may omit `datasources`, or use `datasources: {}`,
+only when `views` is nonempty. `{}`, `{ datasources: {} }`, and
+`{ datasources: {}, views: [] }` are invalid; widened or dynamic maps and arrays
+are checked at runtime as well as by the type-level forms.
+
+```ts
+const linkedIssues = database("project-issues-linked", {
+	views: [
+		{
+			resourceId: "project-issues-table",
+			type: "table",
+			dataSourceResourceId: "issues-source",
+			properties: [{ property: "issue-title", visible: true }],
+		},
+	],
+});
+```
+
+The table view above is typed by its `type: "table"` schema and links to the
+explicit `issues-source` resource ID.
+
 Keep resource IDs stable across builds. They identify declarations, not live
 Notion UUIDs. Avoid the reserved `__notion_apps_` prefix. Explicit parents
 use `{ type: "resourceId", resourceId: parent.resourceId }`; child helpers set
 this reference for you. Pages and databases without a parent default to private
 top-level resources in the Apps workspace.
 
-Several fields, including database covers, page layouts, and custom-agent
-triggers, still have incomplete types. A field typed as `unknown` is not proof
+Several fields, including database covers and custom-agent triggers,
+still have incomplete types. A field typed as `unknown` is not proof
 that any payload is supported. Check implementation and examples before using
 it; do not assume parity with other Notion as Code packages. Database views are
 typed with `ViewSchema`; standalone declarations accept `ViewArgs`, which adds
 the owning `databaseResourceId`.
 
 The Apps SDK exposes a subset of Notion as Code. Data sources are nested inside
-`database({ dataSources: [...] })`, not declared by a separate
+`database(resourceId, { datasources: { ... } })`, not declared by a separate
 `dataSource` function. It has no `space` workspace declaration:
 Apps deployment rejects workspace creation or changes and supplies the App's
 workspace binding itself. Value helpers and types stay on their existing
 subpaths. For example, import `{ notion }` from `@notionhq/apps/notion-as-code`
 for `notion.text(...)` or `notion.file(resourceId)`. The latter creates a file
 reference, not an upload or file declaration. These helpers are not root exports.
-CLI acceptance of
-an intent envelope alone does not establish server support for its contents.
+CLI acceptance of a serialized intent envelope alone does not establish server
+support for its contents.
 
 ## Use a declared data source in a sync
 
-This example can live directly in `src/syncs/issues.ts`. Move the resource
-declaration into an imported helper when sharing it with other capabilities.
+This sync-specific example declares the resource inline in `src/syncs/issues.ts`:
 
 ```ts
 import { database, sync } from "@notionhq/apps";
 import { Builder } from "@notionhq/apps/builder";
 
-const issues = database({
-	resourceId: "issues-db",
+const issues = database("issues-db", {
+	dataSourceResourceId: "issues-source",
 	name: "Issues",
-	dataSources: [
-		{
-			resourceId: "issues-source",
-			name: "Issues",
-			properties: [
-				{ resourceId: "issue-name", name: "Name", type: "title" },
-				{ resourceId: "issue-id", name: "External ID", type: "text" },
-			],
-		},
-	],
+	schema: {
+		Name: { resourceId: "issue-name", type: "title" },
+		"External ID": { resourceId: "issue-id", type: "text" },
+	},
 });
 
 export default sync({
-	dataSource: issues.dataSources["issues-source"],
+	dataSource: issues.dataSource,
 	primaryKey: "External ID",
 	mode: "incremental",
 	handler: async () => ({
@@ -144,11 +172,23 @@ export default sync({
 
 Pass a data source handle, not the whole database handle or a UUID. The SDK
 derives the sync schema from that handle. `primaryKey` names a title or text
-property by its display name, not its resource ID. Omit that property from
-upsert values; the SDK fills it from `key`. Use Apps `Builder` for sync values.
-Follow the [sync skill](../sync/SKILL.md) for pagination and reconciliation.
-
-Notion as Code properties are an array with resource IDs and names.
+property by its schema key, which is also its serialized property name, not its
+resource ID. Omit that property from upsert values; the SDK fills it from `key`.
+Use Apps `Builder` for sync values. Follow the [sync skill](../sync/SKILL.md)
+for pagination and reconciliation.
+
+Author properties in a keyed `schema` with explicit `resourceId` and `type`.
+Both `datasources` keys and `schema` keys are names: each data-source key is
+that source's name, and each schema key is the property's name used for typed
+access, sync values, and serialized property arrays. Nested data-source configs
+and property configs do not accept `name`. The top-level database `name` remains
+supported; in the single-source shorthand it supplies both the database and
+data-source display names. In a multi-source declaration, it names the database
+while each source name comes from its key. The serialized intent retains the
+server's existing arrays. Authoring-only `schema`, `datasources`, and
+database-level `dataSourceResourceId` fields do not appear in the serialized
+database intent. The provisioning JSON envelope is unchanged.
+No IDs are generated.
 Each data source needs exactly one title property
 and unique property names and IDs. The current adapter supports title, text,
 number, select, multi-select, status, date, checkbox, URL, email, phone, and file

package/skills/sync/SKILL.md

@@ -25,26 +25,21 @@ including declaration discovery and the supported schema types.
 This example declares an Issues database and syncs into its data source:
 
 ```ts
+// src/syncs/issues.ts
 import { database, sync } from "@notionhq/apps";
 import { Builder } from "@notionhq/apps/builder";
 
-const issues = database({
-	resourceId: "issues-db",
+const issues = database("issues-db", {
+	dataSourceResourceId: "issues-source",
 	name: "Issues",
-	dataSources: [
-		{
-			resourceId: "issues-source",
-			name: "Issues",
-			properties: [
-				{ resourceId: "issue-name", name: "Name", type: "title" },
-				{ resourceId: "issue-id", name: "External ID", type: "text" },
-			],
-		},
-	],
+	schema: {
+		Name: { resourceId: "issue-name", type: "title" },
+		"External ID": { resourceId: "issue-id", type: "text" },
+	},
 });
 
 export default sync({
-	dataSource: issues.dataSources["issues-source"],
+	dataSource: issues.dataSource,
 	primaryKey: "External ID",
 	mode: "incremental",
 	handler: async () => ({
@@ -60,11 +55,19 @@ export default sync({
 });
 ```
 
-Set `primaryKey` on the sync; it names a title or text property by its display
-name. Omit it from upsert properties: the SDK supplies it from `change.key`.
-Use Apps `Builder` values for sync results. Keep resource IDs stable and reuse
-the declared data source handle. Shared declarations can live in
-`src/lib/resources.ts`, imported by the sync.
+Set `primaryKey` on the sync; it names a title or text property by its schema
+key, which is also the serialized property name. Every upsert must include at least one
+known non-primary-key schema property, while any other non-primary-key properties may be
+omitted; unknown property keys are rejected by TypeScript. Omit the primary-key property
+from upsert properties: the SDK supplies it from `change.key`. Use Apps `Builder` values for
+sync results. Keep resource IDs stable and reuse the declared data source handle. A
+sync-specific database may be declared inline or in a local helper. Shared or
+otherwise app-wide declarations often fit in `src/notion.ts`.
+Both `datasources` keys and `schema` keys are names: each data-source key is
+the source's name, and each schema key is the property's name. Nested
+data-source configs do not accept `name`. The top-level database `name` remains
+supported; in the single-source shorthand it supplies both the database and
+data-source display names.
 
 This skill covers only syncs backed by Notion as Code data sources. If the user
 asks to attach an existing database, explain that this recipe does not cover