@notionhq/apps 0.0.16 → 0.0.18

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

@@ -17,12 +17,12 @@ 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.
 
 ## Where declarations are picked up
 
@@ -33,24 +33,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,15 +66,43 @@ 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.
+- `view({ databaseResourceId, resourceId, type, dataSourceResourceId, ... })`,
+  returning a handle with `resourceId`. This is also available as `notion.view`.
+  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
@@ -79,48 +110,43 @@ 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 views, 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.
+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 () => ({
@@ -138,11 +164,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

package/skills/workflow/SKILL.md

@@ -38,6 +38,53 @@ and Notion API calls, mutable state reads, timestamps, random values, generated
 IDs, messages, creates, and updates. Keep deterministic transforms of the event
 and completed step results outside a step.
 
+Workflow-level key-value state is available through the step closure's `state`.
+State is shared across runs of the same workflow and every operation executes
+inside that step's durability boundary:
+
+```ts
+await context.step("Update cursor", async ({ state }) => {
+	state.set("cursor", nextCursor);
+	const pendingCursor = await state.get("cursor"); // Reads the buffered write.
+	if (!(await saveCursor(pendingCursor))) {
+		throw new Error("Save failed"); // The state write is discarded.
+	}
+});
+```
+
+Use `get` and `set`; passing `undefined` to `set` deletes the key, while `null`
+is stored as a value. Mutations are buffered and committed atomically only
+after the step callback succeeds. Repeated mutations of one key are allowed,
+reads observe the latest buffered value, and only the final mutation is
+committed. If the callback throws, none of that step's state mutations are
+persisted.
+
+Use `context.wait.until(name, { after })` for a relative wait shorter than seven
+days, or `context.wait.until(name, { at })` for an absolute date within the next
+seven days. The runtime checkpoints the target time, releases the workflow's
+compute, and resumes it from the same point later:
+
+```ts
+await context.wait.until("Cooling-off period", {
+	after: { days: 1, hours: 6 },
+});
+await context.wait.until("Launch time", { at: launchAt });
+```
+
+Relative durations can combine `milliseconds`, `seconds`, `minutes`, `hours`,
+`days`, and `weeks`. Every specified value must be a positive finite integer.
+Repeated waits can keep one stable display name when each call has a unique
+composite `key`:
+
+```ts
+for (const page of pages) {
+	await context.wait.until("Rate limit delay", {
+		key: ["rate-limit", page.id],
+		after: { seconds: 1 },
+	});
+}
+```
+
 Completed steps replay saved results. Do not rely on in-memory mutations inside
 a step. Return the values required by later code. Keep calls in a stable order
 and give every step a stable display name. The name is the replay key by
@@ -67,8 +114,9 @@ Use [Notion as Code](../notion-as-code/SKILL.md) for pages and databases that
 should be created during deployment. Prefer it over equivalent manual setup
 or API calls that create the App's resources. Use runtime API calls for dynamic
 data changes, not as a substitute for supported Notion as Code setup.
-Keep declarations at module scope in
-an imported helper. For example, declare a guide page in `src/lib/resources.ts`:
+Keep declarations at module scope. A small workflow-specific resource can be
+declared inline. A larger set can live in a local module; for example, declare a
+guide page in `src/workflows/sayHello/lib/notion.ts`:
 
 ```ts
 import { page } from "@notionhq/apps";
@@ -82,10 +130,11 @@ export const guide = page({
 Import the module from `src/workflows/sayHello.ts` so the build records it:
 
 ```ts
-import "../lib/resources";
 import { workflow } from "@notionhq/apps";
 import { triggers } from "@notionhq/apps/triggers";
 
+import "./sayHello/lib/notion.js";
+
 export default workflow({
 	name: "Say Hello",
 	description: "Says hello on a recurring schedule.",

package/src/cli/build.test.ts

@@ -15,17 +15,18 @@ import { finishMetadataRecording, startMetadataRecording } from "../notion-as-co
 describe("Notion-as-Code database shorthand", () => {
 	it("keeps provisioning and sync identity equivalent to an explicit source", () => {
 		const recorder = startMetadataRecording();
-		const database = notion.database({
-			resourceId: "issues",
+		const schema = {
+			Name: { resourceId: "title", type: "title" },
+			Count: { resourceId: "count", type: "number" },
+		} as const;
+		const database = notion.database("issues", {
+			dataSourceResourceId: "issues-source",
 			name: "Issues",
-			properties: [
-				{ resourceId: "title", name: "Name", type: "title" },
-				{ resourceId: "count", name: "Count", type: "number" },
-			],
+			schema,
 		});
-		expectTypeOf(database).toExtend<
-			SingleSourceDatabaseHandle<typeof database.dataSource.schema>
-		>();
+		expectTypeOf(database).toExtend<SingleSourceDatabaseHandle<typeof schema>>();
+		expectTypeOf(database.dataSource.schema.Name.type).toEqualTypeOf<"title">();
+		expectTypeOf(database.dataSource.schema.Name.resourceId).toEqualTypeOf<"title">();
 		expectTypeOf(
 			database.dataSource.database.config.schema.Count.type,
 		).toEqualTypeOf<"number">();
@@ -33,18 +34,19 @@ describe("Notion-as-Code database shorthand", () => {
 		const shorthand = finishMetadataRecording(recorder).intents;
 
 		const explicitRecorder = startMetadataRecording();
-		const explicit = notion.database({
-			resourceId: "issues",
+		const explicit = notion.database("issues", {
 			name: "Issues",
-			dataSources: [
-				{
+			datasources: {
+				Issues: {
 					resourceId: "issues-source",
-					name: "Issues",
-					properties: database.dataSource.schema,
+					schema,
 				},
-			],
+			},
 		});
-		explicit.dataSources["issues-source"].addPage({ resourceId: "issue" });
+		expectTypeOf(explicit.datasources.Issues).toExtend<DataSourceHandle<typeof schema>>();
+		expectTypeOf(explicit.datasources.Issues.schema.Name.type).toEqualTypeOf<"title">();
+		expectTypeOf(explicit.datasources.Issues.schema.Name.resourceId).toEqualTypeOf<"title">();
+		explicit.datasources.Issues.addPage({ resourceId: "issue" });
 		// @ts-expect-error Explicit databases do not guarantee a single source.
 		void explicit.dataSource;
 		expect(shorthand).toEqual(finishMetadataRecording(explicitRecorder).intents);
@@ -56,22 +58,24 @@ describe("Notion-as-Code database shorthand", () => {
 		});
 	});
 
-	it("preserves parent binding and inferred source types through child helpers", () => {
+	it("preserves parent binding and keyed source types through child helpers", () => {
 		const recorder = startMetadataRecording();
 		const page = notion.page({ resourceId: "page" });
 		const team = notion.teamspace({ resourceId: "team", name: "Team", accessLevel: "private" });
+		const schema = {
+			Title: { resourceId: "child-title", type: "title" },
+		} as const;
 		for (const parent of [page, team]) {
-			const database = parent.addDatabase({
-				resourceId: `${parent.resourceId}-db`,
+			const database = parent.addDatabase(`${parent.resourceId}-db`, {
+				dataSourceResourceId: `${parent.resourceId}-source`,
 				name: "Child",
-				properties: [
-					{ resourceId: `${parent.resourceId}-title`, name: "Title", type: "title" },
-				],
+				schema,
 			});
-			expectTypeOf(database.dataSource).toExtend<
-				DataSourceHandle<typeof database.dataSource.schema>
-			>();
-			expectTypeOf(database.dataSource.schema[0].name).toEqualTypeOf<"Title">();
+			expectTypeOf(database.dataSource).toExtend<DataSourceHandle<typeof schema>>();
+			expectTypeOf(database.dataSource.schema.Title.type).toEqualTypeOf<"title">();
+			expectTypeOf(
+				database.dataSource.schema.Title.resourceId,
+			).toEqualTypeOf<"child-title">();
 		}
 		const intents = finishMetadataRecording(recorder).intents;
 		expect(
@@ -82,19 +86,60 @@ describe("Notion-as-Code database shorthand", () => {
 		]);
 	});
 
-	it("rejects mixed forms before recording an intent", () => {
+	it("keeps keyed child inference and rejects empty child databases", () => {
 		const recorder = startMetadataRecording();
-		const declareMixedDatabase = () => {
-			// @ts-expect-error The shorthand and explicit forms are mutually exclusive.
-			notion.database({
-				resourceId: "mixed",
-				name: "Mixed",
-				properties: [],
-				dataSources: [],
-			});
+		const page = notion.page({ resourceId: "child-page" });
+		const schema = {
+			Name: { type: "title", resourceId: "child-name" },
+			"Issue ID": { type: "text", resourceId: "child-issue-id" },
+		} as const;
+		const database = page.addDatabase("child-multi-database", {
+			datasources: {
+				Issues: {
+					resourceId: "child-issues-source",
+					schema,
+				},
+			},
+		});
+		expectTypeOf(database.datasources.Issues).toExtend<DataSourceHandle<typeof schema>>();
+		expectTypeOf(
+			database.datasources.Issues.schema.Name.resourceId,
+		).toEqualTypeOf<"child-name">();
+
+		const invalidChildDeclarations = () => {
+			// @ts-expect-error Child databases need a source or a view.
+			page.addDatabase("child-empty-datasources", { datasources: {} });
+			// @ts-expect-error Child databases need a source or a view.
+			page.addDatabase("child-empty-arguments", {});
+			// @ts-expect-error Empty child sources and views are invalid.
+			page.addDatabase("child-empty-with-views", { datasources: {}, views: [] });
 		};
-		expect(declareMixedDatabase).toThrow();
-		expect(finishMetadataRecording(recorder).intents).toEqual([]);
+		void invalidChildDeclarations;
+		expect(() =>
+			page.addDatabase("child-runtime-empty", { datasources: {}, views: [] } as never),
+		).toThrow();
+
+		const intents = finishMetadataRecording(recorder).intents;
+		expect(intents).toHaveLength(2);
+		expect(intents).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
+					type: "database",
+					resourceId: "child-multi-database",
+					parent: { type: "resourceId", resourceId: "child-page" },
+					dataSources: [
+						{
+							resourceId: "child-issues-source",
+							name: "Issues",
+							properties: [
+								{ resourceId: "child-name", name: "Name", type: "title" },
+								{ resourceId: "child-issue-id", name: "Issue ID", type: "text" },
+							],
+						},
+					],
+				}),
+			]),
+		);
 	});
 });
 
@@ -163,41 +208,49 @@ describe("buildApp", () => {
 	it("builds a sync manifest with a Notion-as-Code meetings database", async () => {
 		const { manifest } = await buildApp(example("sync"));
 
-		expect(manifest).toEqual({
-			$schema: "notion:apps-manifest:v1",
-			sdkVersion: SDK_VERSION,
-			databases: [
-				{
+		expect(manifest).toEqual(
+			expect.objectContaining({
+				$schema: "notion:apps-manifest:v1",
+				sdkVersion: SDK_VERSION,
+				xldbs: [],
+				pacers: [],
+			}),
+		);
+		expect(manifest.databases).toHaveLength(2);
+		expect(manifest.databases).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({
 					key: "issues",
-					config: {
+					config: expect.objectContaining({
 						initialTitle: "GitHub Issues",
-						schema: {
-							properties: {
+						schema: expect.objectContaining({
+							properties: expect.objectContaining({
 								Name: { type: "title" },
 								"GitHub ID": { type: "text" },
 								Closed: { type: "checkbox" },
-							},
-						},
-					},
-				},
-				{
+							}),
+						}),
+					}),
+				}),
+				expect.objectContaining({
 					key: "homebase-meetings-db-source",
-					config: {
+					config: expect.objectContaining({
 						initialTitle: "Meetings",
-						schema: {
-							properties: {
+						schema: expect.objectContaining({
+							properties: expect.objectContaining({
 								Name: { type: "title" },
 								"Meeting ID": { type: "text" },
 								"Meeting date": { type: "date" },
 								"Prep complete": { type: "checkbox" },
-							},
-						},
-					},
-				},
-			],
-			xldbs: [],
-			pacers: [],
-			capabilities: [
+							}),
+						}),
+					}),
+				}),
+			]),
+		);
+		expect(manifest.capabilities).toHaveLength(2);
+		expect(manifest.capabilities).toEqual(
+			expect.arrayContaining([
 				{
 					type: "sync",
 					key: "issues",
@@ -218,8 +271,8 @@ describe("buildApp", () => {
 						schedule: { type: "interval", intervalMs: 3_600_000 },
 					},
 				},
-			],
-		});
+			]),
+		);
 	});
 
 	it("emits a separate Notion-as-Code provisioning artifact", async () => {
@@ -285,6 +338,13 @@ describe("buildApp", () => {
 						resourceId: "__notion_apps_workspace__",
 					},
 					dataSources: [],
+					views: [
+						{
+							resourceId: "github-app-private-view",
+							type: "table",
+							dataSourceResourceId: "issues-source",
+						},
+					],
 				},
 				{
 					type: "database",