@notionhq/apps 0.0.15 → 0.0.16

package/AGENTS.md

@@ -0,0 +1,13 @@
+# 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.

package/README.md

@@ -63,6 +63,16 @@ uses explicit exports and does not re-export utility types or the custom-block b
 keep using `@notionhq/apps/custom-blocks` and `@notionhq/apps/react`; the root includes
 Node-only workflow code. Styles stay in `@notionhq/apps/nds.css`.
 
+## Agent skills
+
+The package includes skills for [workflows](./skills/workflow/SKILL.md),
+[connections](./skills/connections/SKILL.md),
+[database syncs](./skills/sync/SKILL.md),
+[custom blocks](./skills/custom-blocks/SKILL.md), and
+[Notion as Code](./skills/notion-as-code/SKILL.md). Read the matching skill
+before creating, modifying, or troubleshooting an App capability. Shipping the
+skills with the SDK keeps their instructions up to date with the installed API.
+
 ## Development
 
 1. Install [mise](https://mise.jdx.dev/getting-started.html)
@@ -139,6 +149,38 @@ Put each default-exported sync directly in `src/syncs/`. A primary key must be a
 or text property. Do not include that property in an upsert: the SDK fills it from
 the change's `key`.
 
+## Notion-as-Code databases
+
+Use `properties` to declare a database with one data source:
+
+```ts
+import { notion } from "@notionhq/apps/notion-as-code";
+
+const issues = notion.database({
+	resourceId: "branch-check-issues",
+	name: "Issues",
+	properties: [
+		{ resourceId: "issue-title", name: "Name", type: "title" },
+		{ resourceId: "issue-id", name: "ID", type: "text" },
+	],
+});
+```
+
+Pass `issues.dataSource` as the `dataSource` argument to `sync` from `@notionhq/apps`, or use
+`issues.dataSource.addPage(...)` to declare a page in the source. The database still exposes
+`dataSources` and `addView`.
+
+For explicit sources, keep using `notion.database({ resourceId, dataSources: [...] })`
+and access each source through `handle.dataSources[sourceResourceId]`.
+`properties` and `dataSources` are mutually exclusive. Both forms also work with
+page and teamspace `addDatabase` helpers.
+
+The shorthand emits the existing database intent with one source named after the
+database and identified by `${resourceId}-source`. That ID must be globally unique.
+When converting an existing explicit declaration, use the shorthand only if its
+source already has that ID; changing the source ID creates a different resource.
+No top-level `properties` field is added to the database intent.
+
 ## Custom blocks
 
 Declare browser blocks in `src/customBlocks/<key>.ts`:

package/dist/notion-as-code/database.d.ts

@@ -18,6 +18,13 @@ export type DatabaseArgs<DataSources extends readonly DataSourceDefinition[] = r
 };
 /** Input for adding a database beneath an existing resource. */
 export type ChildDatabaseArgs<DataSources extends readonly DataSourceDefinition[] = readonly DataSourceDefinition[]> = Omit<DatabaseArgs<DataSources>, "parent">;
+/** Single-source shorthand; the source ID is `${resourceId}-source`. */
+export type SingleSourceDatabaseArgs<Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[]> = Omit<DatabaseArgs, "dataSources" | "name"> & {
+    name: string;
+    properties: Properties;
+    dataSources?: never;
+};
+export type ChildSingleSourceDatabaseArgs<Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[]> = Omit<SingleSourceDatabaseArgs<Properties>, "parent">;
 /** Resolves one data source ID to the properties declared for it. */
 type DataSourcePropertiesForResourceId<DataSources extends readonly DataSourceDefinition[], ResourceId extends DataSources[number]["resourceId"]> = Extract<DataSources[number], {
     resourceId: ResourceId;
@@ -37,8 +44,23 @@ export type DatabaseHandle<DataSources extends readonly DataSourceDefinition[] =
     };
     addView: (view: unknown) => void;
 };
+/** A database whose sole data source is available without an ID lookup. */
+export type SingleSourceDatabaseHandle<Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[]> = DatabaseHandle<readonly DataSourceDefinition<Properties>[]> & {
+    readonly dataSource: DataSourceHandle<Properties>;
+};
+export type ChildDatabaseFactory = {
+    <const Properties extends readonly NotionAsCodeProperty[]>(args: ChildSingleSourceDatabaseArgs<Properties>): SingleSourceDatabaseHandle<Properties>;
+    <const DataSources extends readonly DataSourceDefinition[]>(args: ChildDatabaseArgs<DataSources> & {
+        properties?: never;
+    }): DatabaseHandle<DataSources>;
+};
 /** Declare a database, defaulting to a private top-level database in the Apps workspace. */
-export declare function database<const DataSources extends readonly DataSourceDefinition[]>(args: DatabaseArgs<DataSources>): DatabaseHandle<DataSources>;
+export declare function database<const Properties extends readonly NotionAsCodeProperty[]>(args: SingleSourceDatabaseArgs<Properties>): SingleSourceDatabaseHandle<Properties>;
+export declare function database<const DataSources extends readonly DataSourceDefinition[]>(args: DatabaseArgs<DataSources> & {
+    properties?: never;
+}): DatabaseHandle<DataSources>;
+/** Bind both database declaration forms to an existing parent. */
+export declare function createChildDatabase(parent: Parent): ChildDatabaseFactory;
 /** Record a database declaration and create handles for each of its data sources. */
 export declare function createDatabase(args: DatabaseArgs, parent: Parent): DatabaseHandle;
 export {};

package/dist/notion-as-code/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAEN,KAAK,oBAAoB,EAEzB,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAc,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAG5E,OAAO,EAAsB,KAAK,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAE/E,oEAAoE;AACpE,MAAM,MAAM,YAAY,CACvB,WAAW,SAAS,SAAS,oBAAoB,EAAE,GAAG,SAAS,oBAAoB,EAAE,IAClF;IACH,UAAU,EAAE,UAAU,CAAC;IACvB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B,KAAK,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B,IAAI,CAAC,EAAE,gBAAgB,CAAC;IAExB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,iBAAiB,CAC5B,WAAW,SAAS,SAAS,oBAAoB,EAAE,GAAG,SAAS,oBAAoB,EAAE,IAClF,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;AAE9C,qEAAqE;AACrE,KAAK,iCAAiC,CACrC,WAAW,SAAS,SAAS,oBAAoB,EAAE,EACnD,UAAU,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,IAEpD,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE;IAAE,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC,SAAS,oBAAoB,CACpF,MAAM,UAAU,CAChB,GACE,UAAU,GACV,KAAK,CAAC;AAEV,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,CAC3B,UAAU,SAAS,SAAS,oBAAoB,EAAE,GAAG,SAAS,oBAAoB,EAAE,IACjF;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,uBAAuB,CAAC,UAAU,CAAC,CAAC,CAAC;IACjE,OAAO,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,UAAU,CAAC;CAC7C,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,cAAc,CACzB,WAAW,SAAS,SAAS,oBAAoB,EAAE,GAAG,SAAS,oBAAoB,EAAE,IAClF;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE;QACrB,QAAQ,EAAE,UAAU,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,GAAG,gBAAgB,CAC3E,iCAAiC,CAAC,WAAW,EAAE,UAAU,CAAC,CAC1D;KACD,CAAC;IACF,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CACjC,CAAC;AAEF,4FAA4F;AAC5F,wBAAgB,QAAQ,CAAC,KAAK,CAAC,WAAW,SAAS,SAAS,oBAAoB,EAAE,EACjF,IAAI,EAAE,YAAY,CAAC,WAAW,CAAC,GAC7B,cAAc,CAAC,WAAW,CAAC,CAAC;AAY/B,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,CA+BjF"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/database.ts"],"names":[],"mappings":"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"}

package/dist/notion-as-code/database.js

@@ -13,8 +13,34 @@ function database(args) {
     type: "resourceId",
     resourceId: APPS_WORKSPACE_RESOURCE_ID
   };
+  if ("properties" in args) {
+    if (args.dataSources !== void 0) {
+      throw new Error("Specify either properties or dataSources, not both");
+    }
+    const { properties, ...databaseArgs } = args;
+    const source = {
+      resourceId: `${args.resourceId}-source`,
+      name: args.name,
+      properties
+    };
+    const handle = createDatabase({ ...databaseArgs, dataSources: [source] }, parent);
+    const dataSource = handle.dataSources[source.resourceId];
+    if (!dataSource) {
+      throw new Error(`Missing data source "${source.resourceId}"`);
+    }
+    return { ...handle, dataSource };
+  }
   return createDatabase(args, parent);
 }
+function createChildDatabase(parent) {
+  function addDatabase(args) {
+    if ("properties" in args) {
+      return database({ ...args, parent });
+    }
+    return database({ ...args, parent });
+  }
+  return addDatabase;
+}
 function createDatabase(args, parent) {
   assertUserResourceId(args.resourceId);
   const dataSources = args.dataSources ?? [];
@@ -72,6 +98,7 @@ function createDataSourceHandle(dataSource) {
   };
 }
 export {
+  createChildDatabase,
   createDatabase,
   database
 };

package/dist/notion-as-code/index.d.ts

@@ -1,7 +1,7 @@
 export { APPS_RESERVED_RESOURCE_ID_PREFIX, APPS_WORKSPACE_RESOURCE_ID } from "./intents.js";
 export type { DataSourceDefinition, NotionAsCodeProperty, Parent } from "./intents.js";
 export type { CustomAgentArgs, CustomAgentHandle } from "./custom-agent.js";
-export type { ChildDatabaseArgs, DataSourceHandle, DatabaseArgs, DatabaseHandle, } from "./database.js";
+export type { ChildDatabaseArgs, ChildDatabaseFactory, ChildSingleSourceDatabaseArgs, DataSourceHandle, DatabaseArgs, DatabaseHandle, SingleSourceDatabaseArgs, SingleSourceDatabaseHandle, } from "./database.js";
 export type { ChildPageArgs, PageArgs, PageHandle } from "./page.js";
 export type { TeamspaceArgs, TeamspaceHandle } from "./teamspace.js";
 /** Experimental Notion-as-Code facade for Apps SDK project metadata. */

package/dist/notion-as-code/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gCAAgC,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC5F,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACvF,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EACX,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,cAAc,GACd,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACrE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAErE,wEAAwE;AACxE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;CAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gCAAgC,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAC5F,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACvF,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC5E,YAAY,EACX,iBAAiB,EACjB,oBAAoB,EACpB,6BAA6B,EAC7B,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,wBAAwB,EACxB,0BAA0B,GAC1B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACrE,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAErE,wEAAwE;AACxE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;CAAiB,CAAC"}

package/dist/notion-as-code/page.d.ts

@@ -1,5 +1,5 @@
-import { type DataSourceDefinition, type Parent, type ResourceId } from "./intents.js";
-import { type ChildDatabaseArgs, type DatabaseHandle } from "./database.js";
+import { type Parent, type ResourceId } from "./intents.js";
+import { type ChildDatabaseFactory } from "./database.js";
 export type PageArgs = {
     resourceId: ResourceId;
     /** Omit to create a private top-level page in the Apps workspace. */
@@ -12,7 +12,7 @@ export type PageArgs = {
 export type ChildPageArgs = Omit<PageArgs, "parent">;
 export type PageHandle = {
     readonly resourceId: string;
-    addDatabase: <const DataSources extends readonly DataSourceDefinition[]>(args: ChildDatabaseArgs<DataSources>) => DatabaseHandle<DataSources>;
+    addDatabase: ChildDatabaseFactory;
     addPage: (args: ChildPageArgs) => PageHandle;
 };
 /** Declare a page, defaulting to a private top-level page in the Apps workspace. */

package/dist/notion-as-code/page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/page.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,oBAAoB,EAEzB,KAAK,MAAM,EACX,KAAK,UAAU,EACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAY,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAItF,MAAM,MAAM,QAAQ,GAAG;IACtB,UAAU,EAAE,UAAU,CAAC;IACvB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,CAAC,KAAK,CAAC,WAAW,SAAS,SAAS,oBAAoB,EAAE,EACtE,IAAI,EAAE,iBAAiB,CAAC,WAAW,CAAC,KAChC,cAAc,CAAC,WAAW,CAAC,CAAC;IACjC,OAAO,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,UAAU,CAAC;CAC7C,CAAC;AAEF,oFAAoF;AACpF,wBAAgB,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAS/C;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAoBrF"}
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/page.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,MAAM,EACX,KAAK,UAAU,EACf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAI/E,MAAM,MAAM,QAAQ,GAAG;IACtB,UAAU,EAAE,UAAU,CAAC;IACvB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,UAAU,CAAC;CAC7C,CAAC;AAEF,oFAAoF;AACpF,wBAAgB,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAS/C;AAED,6DAA6D;AAC7D,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAerF"}

package/dist/notion-as-code/page.js

@@ -1,7 +1,7 @@
 import {
   APPS_WORKSPACE_RESOURCE_ID
 } from "./intents.js";
-import { database } from "./database.js";
+import { createChildDatabase } from "./database.js";
 import { recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
 function page(args) {
@@ -23,12 +23,7 @@ function createPage(args, parent) {
   });
   return {
     resourceId: args.resourceId,
-    addDatabase(databaseArgs) {
-      return database({
-        ...databaseArgs,
-        parent: { type: "resourceId", resourceId: args.resourceId }
-      });
-    },
+    addDatabase: createChildDatabase({ type: "resourceId", resourceId: args.resourceId }),
     addPage(pageArgs) {
       return createPage(pageArgs, { type: "resourceId", resourceId: args.resourceId });
     }

package/dist/notion-as-code/teamspace.d.ts

@@ -1,5 +1,5 @@
-import { type DataSourceDefinition, type NotionAsCodeIcon, type ResourceId } from "./intents.js";
-import { type ChildDatabaseArgs, type DatabaseHandle } from "./database.js";
+import { type NotionAsCodeIcon, type ResourceId } from "./intents.js";
+import { type ChildDatabaseFactory } from "./database.js";
 import { type ChildPageArgs, type PageHandle } from "./page.js";
 export type TeamspaceArgs = {
     resourceId: ResourceId;
@@ -10,7 +10,7 @@ export type TeamspaceArgs = {
 };
 export type TeamspaceHandle = {
     readonly resourceId: string;
-    addDatabase: <const DataSources extends readonly DataSourceDefinition[]>(args: ChildDatabaseArgs<DataSources>) => DatabaseHandle<DataSources>;
+    addDatabase: ChildDatabaseFactory;
     addPage: (args: ChildPageArgs) => PageHandle;
 };
 /** Declare a teamspace that Apps automatically creates in its workspace. */

package/dist/notion-as-code/teamspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"teamspace.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/teamspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAY,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAc,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAI5E,MAAM,MAAM,aAAa,GAAG;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvD,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,CAAC,KAAK,CAAC,WAAW,SAAS,SAAS,oBAAoB,EAAE,EACtE,IAAI,EAAE,iBAAiB,CAAC,WAAW,CAAC,KAChC,cAAc,CAAC,WAAW,CAAC,CAAC;IACjC,OAAO,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,UAAU,CAAC;CAC7C,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CAoB9D"}
+{"version":3,"file":"teamspace.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/teamspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAEN,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAEf,MAAM,cAAc,CAAC;AACtB,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAc,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAI5E,MAAM,MAAM,aAAa,GAAG;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACvD,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,oBAAoB,CAAC;IAClC,OAAO,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,UAAU,CAAC;CAC7C,CAAC;AAEF,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,CAe9D"}

package/dist/notion-as-code/teamspace.js

@@ -1,7 +1,7 @@
 import {
   APPS_WORKSPACE_RESOURCE_ID
 } from "./intents.js";
-import { database } from "./database.js";
+import { createChildDatabase } from "./database.js";
 import { createPage } from "./page.js";
 import { recordIntent } from "./recorder.js";
 import { assertUserResourceId } from "./resource.js";
@@ -14,12 +14,7 @@ function teamspace(args) {
   });
   return {
     resourceId: args.resourceId,
-    addDatabase(databaseArgs) {
-      return database({
-        ...databaseArgs,
-        parent: { type: "resourceId", resourceId: args.resourceId }
-      });
-    },
+    addDatabase: createChildDatabase({ type: "resourceId", resourceId: args.resourceId }),
     addPage(pageArgs) {
       return createPage(pageArgs, { type: "resourceId", resourceId: args.resourceId });
     }

package/package.json

@@ -1,12 +1,14 @@
 {
 	"name": "@notionhq/apps",
-	"version": "0.0.15",
+	"version": "0.0.16",
 	"description": "An SDK for building workflow apps for Notion",
 	"license": "MIT",
 	"bin": {
 		"notion-apps": "./dist/cli/index.js"
 	},
 	"files": [
+		"skills/",
+		"AGENTS.md",
 		"dist/",
 		"src/",
 		"docs/",

package/skills/connections/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: connections
+description: Configure and use typed provider connections and connection-bound triggers in Notion App workflows.
+user-invocable: false
+---
+
+# Workflow connections
+
+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
+inside an awaited durable step. Access a named connection through its provider
+client, such as `context.connections.slack("support")`.
+
+Read the installed provider declarations before choosing methods and inputs.
+The SDK handles transport, credentials, and runtime bindings. Do not construct
+raw tools API envelopes or call internal endpoints. Check the installed version
+supports the typed methods; resolve version mismatches before using them.
+Provider clients are inferred from the declared requirements. Keys default to
+the provider name; custom keys distinguish multiple connections to one provider.
+Keep keys unique and ensure connection-trigger keys match a declared provider.
+
+A declaration requests setup; it grants no access. Deploy and configure the
+requirement before execution. The runtime resolves bindings and credentials.
+Do not manufacture connection IDs, set runtime binding metadata to bypass setup,
+or copy Worker auth interceptors into an App.
+
+Availability and permissions are decided by the server. If a provider is
+unavailable or a write needs confirmation the runtime cannot obtain, report the
+setup limitation. Do not bypass it with an internal endpoint.
+
+Check operation-specific partial errors as well as rejected requests. Durable
+steps can repeat effects after an uncertain result; use downstream idempotency
+only where supported and reconcile uncertain writes before retrying.
+
+This client surface belongs to workflows. Sync handlers receive only the
+capability context with `notion`; do not assume they have provider clients.
+
+## Bind triggers to connections
+
+For provider triggers, use the `triggers: ({ triggers }) => [...]` callback
+on `workflow`. Its trigger creators infer valid connection keys from
+the workflow's declarations:
+
+```ts
+import { workflow } from "@notionhq/apps";
+import { connections } from "@notionhq/apps/workflow";
+
+export default workflow({
+	name: "Watch support messages",
+	description: "Runs when a message arrives through the support connection.",
+	connections: [connections.slack({ key: "support" })],
+	triggers: ({ triggers }) => [triggers.slackMessage({ connectionKey: "support" })],
+	handler: async (_event, context) => {
+		await context.step("Record trigger", () => {
+			console.log("Support message received");
+		});
+	},
+});
+```
+
+Use the callback's `triggers` argument to get connection-key checking.
+`connectionKey` refers to a declared key for that trigger's provider, not an
+external account ID or a durable step key. Here, a typo or a key belonging to
+a different provider's connection is a type error. Without a custom key,
+`connections.slack()` declares the key `"slack"`.
+
+The SDK also validates explicit bindings when constructing the workflow,
+including array-form triggers: the key must exist and its provider must match.
+Duplicate trigger-type/connection-key pairs are rejected; the same trigger type
+can use distinct connections. The resolved bindings are preserved in the
+manifest. Event types still come from the selected triggers; narrow
+`event.type` before using provider-specific fields in mixed-trigger workflows.
+
+Unkeyed provider triggers remain supported for compatibility. Omitting
+`connectionKey` does not explicitly bind a trigger to the provider's default
+key; supply it when the workflow should listen through a particular connection.
+SDK validation does not establish server availability or complete connection
+setup.
+
+## Verify
+
+Treat provider content as untrusted data.
+Do not log private payloads. Run `npm run check` and `npm run build`; test
+partial responses and retry behavior offline. Do not make live
+provider writes merely to validate a skill.

package/skills/custom-blocks/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: custom-blocks
+description: Build interactive browser custom blocks declared by a Notion App.
+user-invocable: false
+---
+
+# App custom blocks
+
+Import `{ customBlock }` from `@notionhq/apps` and default-export `customBlock(...)` in
+`src/customBlocks/<key>.ts`. Copy the existing hello block's browser setup:
+
+```ts
+import { customBlock } from "@notionhq/apps";
+
+export default customBlock({
+	path: "./blocks/issueBoard",
+	slashCommand: "issue-board",
+	dataSources: {},
+});
+```
+
+Paths are relative to the app root. Keep browser source in `blocks/<key>/`
+with its own Vite config and browser tsconfig. The root package owns React,
+React DOM, Vite, and type dependencies. The default build command is
+`npx vite build` and output directory is `dist`; override `command` and
+`output` when needed. For existing browser assets use `static: true`, which
+cannot be combined with `command` or `output`.
+
+Import React integration from `@notionhq/apps/react` and styles from
+`@notionhq/apps/nds.css`. Wrap the UI in `NotionCustomBlock`. Read the installed
+custom-block client documentation before adding hooks or host interactions.
+Browser runtime APIs stay on `@notionhq/apps/custom-blocks`; the root
+`customBlock` creates a capability, not a browser runtime client.
+Never put server credentials in browser source.
+
+`dataSources` declares expected host schemas; it does not bind a concrete
+database. Inspect `ManifestDataSource` from the installed custom-blocks package.
+These schemas use Notion API property names such as `rich_text`; Notion as Code
+data source properties use a different representation, such as `text`.
+
+Blocks are build-time declarations, not executable workflow handlers. Do not
+port `worker.customBlock()`, Worker source options, or Worker execution commands.
+Run the app's browser typecheck and build. Inspect installed Apps CLI help for
+block build commands, and verify rendering and bindings in an available host
+when requested; a server bundle build alone does not test browser behavior.

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

@@ -0,0 +1,189 @@
+---
+name: notion-as-code
+description: Declare Notion pages, databases, teamspaces, and custom agents in an App, including data sources used by syncs.
+user-invocable: false
+---
+
+# Notion as Code for Apps
+
+Prefer Notion as Code whenever it supports the requested resource setup. Use declarations
+for pages, databases, teamspaces, and custom agents instead of equivalent
+manual setup or runtime creation calls. Respect explicit user choices and
+existing resource attachments; use other methods for unsupported operations
+or runtime data changes.
+
+Import the resource creators you use, such as
+`import { database, page } from "@notionhq/apps"`. These functions declare
+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.
+
+## Where declarations are picked up
+
+The Apps build discovers direct `.ts` children of `src/workflows/` and
+`src/syncs/`, then evaluates their imports with the Notion as Code recorder active.
+Pages, databases, data sources, teamspaces, and custom agents all follow this
+same rule. Their resource type does not determine their file location.
+
+```text
+src/
+  lib/
+    resources.ts          Shared page/database declarations
+  syncs/
+    issues.ts             Default-exported sync; imports ../lib/resources
+    lib/
+      issueSchema.ts      Sync-specific helper; must be imported
+  workflows/
+    notify.ts             Default-exported workflow
+```
+
+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.
+
+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.
+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
+phase. An App containing only unimported resource declarations is not a
+standalone Notion as Code project and has no discovered capabilities.
+
+## Declare resources
+
+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.
+- `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`.
+- `customAgent({ resourceId, name, instructions?, sharedResources? })`.
+  Shared resources are declared resource IDs; inspect the installed types
+  before specifying models or triggers.
+
+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 views, covers, page layouts, 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.
+
+The Apps SDK exposes a subset of Notion as Code. Data sources are nested inside
+`database({ 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.
+
+## 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.
+
+```ts
+import { database, sync } from "@notionhq/apps";
+import { Builder } from "@notionhq/apps/builder";
+
+const issues = database({
+	resourceId: "issues-db",
+	name: "Issues",
+	dataSources: [
+		{
+			resourceId: "issues-source",
+			name: "Issues",
+			properties: [
+				{ resourceId: "issue-name", name: "Name", type: "title" },
+				{ resourceId: "issue-id", name: "External ID", type: "text" },
+			],
+		},
+	],
+});
+
+export default sync({
+	dataSource: issues.dataSources["issues-source"],
+	primaryKey: "External ID",
+	mode: "incremental",
+	handler: async () => ({
+		changes: [
+			{
+				type: "upsert",
+				key: "example-123",
+				properties: { Name: Builder.title("Example issue") },
+			},
+		],
+		hasMore: false,
+	}),
+});
+```
+
+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.
+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
+properties. It rejects other kinds, including relation, formula, rollup, and
+person, even though some appear in the declaration type. Status options use
+`todo`, `inProgress`, and `complete` arrays. Read the installed adapter before
+extending a schema.
+
+## Build and deployment
+
+Run the app's check and build commands, then inspect `dist/provisioning.json`
+alongside the manifest. The provisioning artifact contains recorded resource
+declarations. Building it does not create live resources. Do not hand-edit
+generated artifacts or deploy output from a failed build.
+
+Deployment applies provisioning and connects resources to the app. Cloud
+deployment stores resource mappings on the server; local-build deployment
+uses local state. Switching modes can recreate resources because their state
+is independent. A failed deployment can leave partial changes; there is no
+automatic rollback. Report the result before attempting recovery.
+
+Use `ntn apps deploy` for the App workflow. The default path uploads source
+for a cloud build and server-side provisioning. With `--local-build`, the
+CLI builds the App, reads `dist/provisioning.json` and `dist/manifest.json`,
+deploys code, applies Notion as Code intents, and reconciles sync attachments. It matches
+each sync's manifest `databaseKey` to a declared data source's `resourceId`,
+then resolves the resulting live data source from provisioning state.
+`sync` supplies this matching key from the handle. An existing
+binding to a different database causes an error instead of silent rebinding.
+
+The standalone command `ntn notion-as-code apply <dir>` is a different
+project flow: it builds that directory and reads `dist/intents.json`.
+Do not use it as a substitute for Apps deployment or rename the Apps artifact
+to fit it. It does not perform the App's sync attachment reconciliation.
+
+Local deployment defaults to state named `apps-<worker-id>` in the CLI's
+environment/workspace-scoped config store. The
+`--notion-as-code-state-name` option requires `--local-build`. Preserve that
+state when updating; local and cloud mappings are not interchangeable.
+
+Removing all declarations removes the build artifact, but does not delete
+previously provisioned resources. Keep local deployment state out of Git.
+Validate declarations and sync transforms offline; perform deployment only
+as part of a requested live task.

package/skills/sync/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: sync
+description: Build, debug, or review Notion App database syncs with stable keys and resumable pagination.
+user-invocable: false
+---
+
+# App database syncs
+
+Read the installed `@notionhq/apps/sync`, `notion-as-code`, and `builder`
+declarations before adapting a Worker sync. Default-export one sync directly in
+`src/syncs/<key>.ts`. Apps use standalone declarations, not `worker.sync()`.
+Put sync-specific helpers in `src/syncs/lib/` and shared helpers in `src/lib/`.
+
+## Choose the database source
+
+Prefer Notion as Code for the sync's database when Apps Notion as Code supports the required schema.
+Do not choose manual database setup or a separate attached-database declaration
+when Notion as Code can provide the same resource.
+
+For a database the App creates, declare and provision it with
+`database(...)` and `sync({ dataSource, ... })`.
+Read the [Notion as Code skill](../notion-as-code/SKILL.md) for that path,
+including declaration discovery and the supported schema types.
+
+This example declares an Issues database and syncs into its data source:
+
+```ts
+import { database, sync } from "@notionhq/apps";
+import { Builder } from "@notionhq/apps/builder";
+
+const issues = database({
+	resourceId: "issues-db",
+	name: "Issues",
+	dataSources: [
+		{
+			resourceId: "issues-source",
+			name: "Issues",
+			properties: [
+				{ resourceId: "issue-name", name: "Name", type: "title" },
+				{ resourceId: "issue-id", name: "External ID", type: "text" },
+			],
+		},
+	],
+});
+
+export default sync({
+	dataSource: issues.dataSources["issues-source"],
+	primaryKey: "External ID",
+	mode: "incremental",
+	handler: async () => ({
+		changes: [
+			{
+				type: "upsert",
+				key: "example-123",
+				properties: { Name: Builder.title("Example issue") },
+			},
+		],
+		hasMore: false,
+	}),
+});
+```
+
+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.
+
+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
+that setup and clarify the next step. Do not silently create a replacement
+database.
+
+## Pagination and reconciliation
+
+The handler receives `(state, context)` and returns `changes`, `hasMore`, and
+`nextState`. State can be undefined initially. Persist a serializable cursor
+and advance it only after successfully processing the corresponding page.
+Return `hasMore: true` while pages remain; an empty filtered page is not proof
+that the upstream listing ended. Keep record keys deterministic across pages
+and runs. Throw on failed requests instead of emitting a false empty success.
+
+Choose and document replace versus incremental behavior explicitly. Replace
+requires a complete snapshot; incremental requires explicit deletion handling
+when upstream records disappear. Test multiple pages, empty pages with a next
+cursor, retrying the same cursor, and deletion handling offline.
+
+The context supplies `notion`, not workflow steps or connection clients.
+Configure required external credentials separately using names and safe
+placeholders in `.env.example`; do not copy Worker auth registration.
+
+## Review and verify
+
+Check stable keys, schema/value compatibility, cursor progress and exhaustion,
+partial failures, and whether the documented mode matches the emitted changes.
+Report findings with file, line, impact, and fix. Run the app's offline tests,
+`npm run check`, and `npm run build`. Live execution can change database rows;
+use it only as part of the requested live task.

package/skills/workflow/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: workflow
+description: Build or review Notion App workflows for typed triggers, durable replay-safe steps, and idempotent effects.
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Workflow
+
+Use this skill to add or review a workflow in this template.
+
+## Build or change a workflow
+
+1. Read `AGENTS.md` and the existing files in `src/workflows/`.
+2. Inspect the installed workflow and trigger declarations.
+3. Choose the trigger, outcome, step boundaries, and required configuration.
+4. Create one camelCase file directly in `src/workflows/`.
+5. Default-export `workflow(...)` and use typed trigger creators.
+6. Put all non-deterministic work in awaited `context.step(...)` calls.
+7. Give each step a stable display name. For repeated steps, keep the name
+   constant and pass a stable, unique composite `key`, such as
+   `{ key: ["process-page", page.id] }`.
+8. Return JSON-safe values needed by later steps.
+9. Use the step `id` as an idempotency key when supported.
+10. Run `npm run check` and `npm run build`.
+
+Each direct `src/workflows/*.ts` file must default-export `workflow(...)`.
+The camelCase file name becomes its workflow key.
+Keep workflow-specific helpers in `src/workflows/lib/` and shared helpers in
+`src/lib/`; direct children of `src/workflows/` are discovered as workflows.
+
+For provider triggers, follow [trigger connection binding](../connections/SKILL.md#bind-triggers-to-connections).
+Use the typed trigger callback to check `connectionKey` against the declared
+provider connections.
+
+Use a step for every value that can change and every external effect: network
+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.
+
+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
+default. For a repeated step, do not interpolate an item ID or loop index into
+the name; pass a stable composite key instead:
+
+```ts
+await context.step("Process page", { key: ["process-page", page.id] }, async ({ id }) =>
+	processPage(page, { idempotencyKey: id }),
+);
+```
+
+Keys must be stable across retries and unique within one workflow run.
+
+An external effect can succeed before its step result is saved. Pass the
+callback `id` as an idempotency key when supported; otherwise use a stable
+external ID, upsert, or duplicate check.
+
+Do not write credentials. Add only environment variable names and safe
+placeholders to `.env.example` when configuration is required. Return only
+JSON-serializable step values, throw on failed requests and missing required
+configuration, and do not log secrets or private payloads.
+
+## Resources created with the App
+
+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`:
+
+```ts
+import { page } from "@notionhq/apps";
+
+export const guide = page({
+	resourceId: "workflow-guide",
+	content: "# Workflow guide\nThis App runs a scheduled workflow.",
+});
+```
+
+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";
+
+export default workflow({
+	name: "Say Hello",
+	description: "Says hello on a recurring schedule.",
+	triggers: [triggers.scheduled()],
+	handler: async (_event, context) => {
+		await context.step("Say hello", () => {
+			console.log("Hello from your workflow!");
+		});
+	},
+});
+```
+
+The page is provisioned during deployment, not on every workflow run.
+Database declarations follow the same import pattern; see the
+[sync example](../sync/SKILL.md#choose-the-database-source) for using a Notion as Code
+data source in a sync. Notion as Code resource IDs are declaration identities, not live
+Notion UUIDs to pass to `context.notion`. Runtime API calls still belong in
+durable steps and need actual resolved Notion IDs.
+
+## Review a workflow
+
+Review every file in `src/workflows/` and the modules it calls. Report each
+finding with its file, line, impact, and fix. Treat these as errors:
+
+1. A workflow is not a direct file or does not default-export `workflow`.
+2. Trigger-specific event fields are used without type narrowing.
+3. Non-deterministic work occurs outside an awaited step.
+4. Step order or names can change between retries.
+5. A step result is not JSON-serializable, or later code needs an in-memory mutation.
+6. A retry-sensitive write lacks an idempotency key or duplicate guard.
+7. External failures are ignored, or credentials are hard-coded or logged.
+8. An explicit trigger connection key is undeclared, belongs to the wrong
+   provider, or repeats the same trigger-type/key pair.
+
+Run `npm run check` and `npm run build` when dependencies are installed.

package/src/cli/build.test.ts

@@ -2,9 +2,101 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { afterEach, describe, expect, it } from "vitest";
+import { afterEach, describe, expect, expectTypeOf, it } from "vitest";
 
 import { buildApp } from "./build.js";
+import {
+	notion,
+	type DataSourceHandle,
+	type SingleSourceDatabaseHandle,
+} from "../notion-as-code/index.js";
+import { finishMetadataRecording, startMetadataRecording } from "../notion-as-code/recorder.js";
+
+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",
+			name: "Issues",
+			properties: [
+				{ resourceId: "title", name: "Name", type: "title" },
+				{ resourceId: "count", name: "Count", type: "number" },
+			],
+		});
+		expectTypeOf(database).toExtend<
+			SingleSourceDatabaseHandle<typeof database.dataSource.schema>
+		>();
+		expectTypeOf(
+			database.dataSource.database.config.schema.Count.type,
+		).toEqualTypeOf<"number">();
+		database.dataSource.addPage({ resourceId: "issue" });
+		const shorthand = finishMetadataRecording(recorder).intents;
+
+		const explicitRecorder = startMetadataRecording();
+		const explicit = notion.database({
+			resourceId: "issues",
+			name: "Issues",
+			dataSources: [
+				{
+					resourceId: "issues-source",
+					name: "Issues",
+					properties: database.dataSource.schema,
+				},
+			],
+		});
+		explicit.dataSources["issues-source"].addPage({ resourceId: "issue" });
+		// @ts-expect-error Explicit databases do not guarantee a single source.
+		void explicit.dataSource;
+		expect(shorthand).toEqual(finishMetadataRecording(explicitRecorder).intents);
+		expect(database.dataSource.database.key).toBe("issues-source");
+		expect(shorthand[1]).toEqual({
+			type: "page",
+			resourceId: "issue",
+			parent: { type: "resourceId", resourceId: "issues-source" },
+		});
+	});
+
+	it("preserves parent binding and inferred source types through child helpers", () => {
+		const recorder = startMetadataRecording();
+		const page = notion.page({ resourceId: "page" });
+		const team = notion.teamspace({ resourceId: "team", name: "Team", accessLevel: "private" });
+		for (const parent of [page, team]) {
+			const database = parent.addDatabase({
+				resourceId: `${parent.resourceId}-db`,
+				name: "Child",
+				properties: [
+					{ resourceId: `${parent.resourceId}-title`, name: "Title", type: "title" },
+				],
+			});
+			expectTypeOf(database.dataSource).toExtend<
+				DataSourceHandle<typeof database.dataSource.schema>
+			>();
+			expectTypeOf(database.dataSource.schema[0].name).toEqualTypeOf<"Title">();
+		}
+		const intents = finishMetadataRecording(recorder).intents;
+		expect(
+			intents.filter((intent) => intent.type === "database").map((intent) => intent.parent),
+		).toEqual([
+			{ type: "resourceId", resourceId: "page" },
+			{ type: "resourceId", resourceId: "team" },
+		]);
+	});
+
+	it("rejects mixed forms before recording an intent", () => {
+		const recorder = startMetadataRecording();
+		const declareMixedDatabase = () => {
+			// @ts-expect-error The shorthand and explicit forms are mutually exclusive.
+			notion.database({
+				resourceId: "mixed",
+				name: "Mixed",
+				properties: [],
+				dataSources: [],
+			});
+		};
+		expect(declareMixedDatabase).toThrow();
+		expect(finishMetadataRecording(recorder).intents).toEqual([]);
+	});
+});
 
 const FIXTURES = fileURLToPath(new URL("../../test/fixtures/", import.meta.url));
 const EXAMPLES = fileURLToPath(new URL("../../examples/", import.meta.url));
@@ -89,7 +181,7 @@ describe("buildApp", () => {
 					},
 				},
 				{
-					key: "homebase-meetings-source",
+					key: "homebase-meetings-db-source",
 					config: {
 						initialTitle: "Meetings",
 						schema: {
@@ -120,7 +212,7 @@ describe("buildApp", () => {
 					type: "sync",
 					key: "notionAsCodeIssues",
 					config: {
-						databaseKey: "homebase-meetings-source",
+						databaseKey: "homebase-meetings-db-source",
 						primaryKeyProperty: "Meeting ID",
 						mode: "incremental",
 						schedule: { type: "interval", intervalMs: 3_600_000 },

package/src/notion-as-code/database.ts

@@ -37,6 +37,19 @@ export type ChildDatabaseArgs<
 	DataSources extends readonly DataSourceDefinition[] = readonly DataSourceDefinition[],
 > = Omit<DatabaseArgs<DataSources>, "parent">;
 
+/** Single-source shorthand; the source ID is `${resourceId}-source`. */
+export type SingleSourceDatabaseArgs<
+	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
+> = Omit<DatabaseArgs, "dataSources" | "name"> & {
+	name: string;
+	properties: Properties;
+	dataSources?: never;
+};
+
+export type ChildSingleSourceDatabaseArgs<
+	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
+> = Omit<SingleSourceDatabaseArgs<Properties>, "parent">;
+
 /** Resolves one data source ID to the properties declared for it. */
 type DataSourcePropertiesForResourceId<
 	DataSources extends readonly DataSourceDefinition[],
@@ -71,11 +84,32 @@ export type DatabaseHandle<
 	addView: (view: unknown) => void;
 };
 
+/** A database whose sole data source is available without an ID lookup. */
+export type SingleSourceDatabaseHandle<
+	Properties extends readonly NotionAsCodeProperty[] = readonly NotionAsCodeProperty[],
+> = DatabaseHandle<readonly DataSourceDefinition<Properties>[]> & {
+	readonly dataSource: DataSourceHandle<Properties>;
+};
+
+export type ChildDatabaseFactory = {
+	<const Properties extends readonly NotionAsCodeProperty[]>(
+		args: ChildSingleSourceDatabaseArgs<Properties>,
+	): SingleSourceDatabaseHandle<Properties>;
+	<const DataSources extends readonly DataSourceDefinition[]>(
+		args: ChildDatabaseArgs<DataSources> & { properties?: never },
+	): DatabaseHandle<DataSources>;
+};
+
 /** Declare a database, defaulting to a private top-level database in the Apps workspace. */
+export function database<const Properties extends readonly NotionAsCodeProperty[]>(
+	args: SingleSourceDatabaseArgs<Properties>,
+): SingleSourceDatabaseHandle<Properties>;
 export function database<const DataSources extends readonly DataSourceDefinition[]>(
-	args: DatabaseArgs<DataSources>,
+	args: DatabaseArgs<DataSources> & { properties?: never },
 ): DatabaseHandle<DataSources>;
-export function database(args: DatabaseArgs): DatabaseHandle {
+export function database(
+	args: DatabaseArgs | SingleSourceDatabaseArgs,
+): DatabaseHandle | SingleSourceDatabaseHandle {
 	if (args.parent) {
 		assertParent(args.parent);
 	}
@@ -83,9 +117,45 @@ export function database(args: DatabaseArgs): DatabaseHandle {
 		type: "resourceId",
 		resourceId: APPS_WORKSPACE_RESOURCE_ID,
 	};
+	if ("properties" in args) {
+		if (args.dataSources !== undefined) {
+			throw new Error("Specify either properties or dataSources, not both");
+		}
+		const { properties, ...databaseArgs } = args;
+		const source: DataSourceDefinition = {
+			resourceId: `${args.resourceId}-source`,
+			name: args.name,
+			properties,
+		};
+		const handle = createDatabase({ ...databaseArgs, dataSources: [source] }, parent);
+		const dataSource = handle.dataSources[source.resourceId];
+		if (!dataSource) {
+			throw new Error(`Missing data source "${source.resourceId}"`);
+		}
+		return { ...handle, dataSource };
+	}
 	return createDatabase(args, parent);
 }
 
+/** Bind both database declaration forms to an existing parent. */
+export function createChildDatabase(parent: Parent): ChildDatabaseFactory {
+	function addDatabase<const Properties extends readonly NotionAsCodeProperty[]>(
+		args: ChildSingleSourceDatabaseArgs<Properties>,
+	): SingleSourceDatabaseHandle<Properties>;
+	function addDatabase<const DataSources extends readonly DataSourceDefinition[]>(
+		args: ChildDatabaseArgs<DataSources> & { properties?: never },
+	): DatabaseHandle<DataSources>;
+	function addDatabase(
+		args: ChildDatabaseArgs | ChildSingleSourceDatabaseArgs,
+	): DatabaseHandle | SingleSourceDatabaseHandle {
+		if ("properties" in args) {
+			return database({ ...args, parent });
+		}
+		return database({ ...args, parent });
+	}
+	return addDatabase;
+}
+
 /** Record a database declaration and create handles for each of its data sources. */
 export function createDatabase(args: DatabaseArgs, parent: Parent): DatabaseHandle {
 	assertUserResourceId(args.resourceId);

package/src/notion-as-code/index.ts

@@ -5,9 +5,13 @@ export type { DataSourceDefinition, NotionAsCodeProperty, Parent } from "./inten
 export type { CustomAgentArgs, CustomAgentHandle } from "./custom-agent.js";
 export type {
 	ChildDatabaseArgs,
+	ChildDatabaseFactory,
+	ChildSingleSourceDatabaseArgs,
 	DataSourceHandle,
 	DatabaseArgs,
 	DatabaseHandle,
+	SingleSourceDatabaseArgs,
+	SingleSourceDatabaseHandle,
 } from "./database.js";
 export type { ChildPageArgs, PageArgs, PageHandle } from "./page.js";
 export type { TeamspaceArgs, TeamspaceHandle } from "./teamspace.js";

package/src/notion-as-code/page.ts

@@ -1,11 +1,10 @@
 import {
 	APPS_WORKSPACE_RESOURCE_ID,
-	type DataSourceDefinition,
 	type PageIntent,
 	type Parent,
 	type ResourceId,
 } from "./intents.js";
-import { database, type ChildDatabaseArgs, type DatabaseHandle } from "./database.js";
+import { createChildDatabase, type ChildDatabaseFactory } from "./database.js";
 import { recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
 
@@ -25,9 +24,7 @@ export type ChildPageArgs = Omit<PageArgs, "parent">;
 
 export type PageHandle = {
 	readonly resourceId: string;
-	addDatabase: <const DataSources extends readonly DataSourceDefinition[]>(
-		args: ChildDatabaseArgs<DataSources>,
-	) => DatabaseHandle<DataSources>;
+	addDatabase: ChildDatabaseFactory;
 	addPage: (args: ChildPageArgs) => PageHandle;
 };
 
@@ -54,12 +51,7 @@ export function createPage(args: ChildPageArgs | PageArgs, parent: Parent): Page
 
 	return {
 		resourceId: args.resourceId,
-		addDatabase(databaseArgs) {
-			return database({
-				...databaseArgs,
-				parent: { type: "resourceId", resourceId: args.resourceId },
-			});
-		},
+		addDatabase: createChildDatabase({ type: "resourceId", resourceId: args.resourceId }),
 		addPage(pageArgs) {
 			return createPage(pageArgs, { type: "resourceId", resourceId: args.resourceId });
 		},

package/src/notion-as-code/teamspace.ts

@@ -1,11 +1,10 @@
 import {
 	APPS_WORKSPACE_RESOURCE_ID,
-	type DataSourceDefinition,
 	type NotionAsCodeIcon,
 	type ResourceId,
 	type TeamspaceIntent,
 } from "./intents.js";
-import { database, type ChildDatabaseArgs, type DatabaseHandle } from "./database.js";
+import { createChildDatabase, type ChildDatabaseFactory } from "./database.js";
 import { createPage, type ChildPageArgs, type PageHandle } from "./page.js";
 import { recordIntent } from "./recorder.js";
 import { assertUserResourceId } from "./resource.js";
@@ -20,9 +19,7 @@ export type TeamspaceArgs = {
 
 export type TeamspaceHandle = {
 	readonly resourceId: string;
-	addDatabase: <const DataSources extends readonly DataSourceDefinition[]>(
-		args: ChildDatabaseArgs<DataSources>,
-	) => DatabaseHandle<DataSources>;
+	addDatabase: ChildDatabaseFactory;
 	addPage: (args: ChildPageArgs) => PageHandle;
 };
 
@@ -37,12 +34,7 @@ export function teamspace(args: TeamspaceArgs): TeamspaceHandle {
 
 	return {
 		resourceId: args.resourceId,
-		addDatabase(databaseArgs) {
-			return database({
-				...databaseArgs,
-				parent: { type: "resourceId", resourceId: args.resourceId },
-			});
-		},
+		addDatabase: createChildDatabase({ type: "resourceId", resourceId: args.resourceId }),
 		addPage(pageArgs) {
 			return createPage(pageArgs, { type: "resourceId", resourceId: args.resourceId });
 		},