@notionhq/apps 0.0.3 → 0.0.6

package/README.md

@@ -7,13 +7,58 @@
 3. Run `mise run setup`
 4. Run `mise run check && mise run test`
 
-The SDK requires Node 26 or newer and supports workflow capabilities only:
+The SDK requires Node 26 or newer. It supports workflows and database syncs.
 
 ```ts
 import { triggers } from "@notionhq/apps/triggers";
 import { createWorkflow } from "@notionhq/apps/workflow";
 ```
 
+## Database syncs
+
+Apps declare a database schema, and users attach a real Notion database to it. Apps SDK
+databases are always attached; there is no managed-database option.
+
+```ts
+import { Builder } from "@notionhq/apps/builder";
+import { createDatabase } from "@notionhq/apps/database";
+import { Schema } from "@notionhq/apps/schema";
+import { createSync } from "@notionhq/apps/sync";
+
+const issues = createDatabase("issues", {
+	schema: {
+		Name: Schema.title(),
+		"GitHub ID": Schema.richText(),
+	},
+});
+
+export default createSync({
+	database: issues,
+	primaryKey: "GitHub ID",
+	handler: async () => ({
+		changes: [
+			{
+				type: "upsert",
+				key: "123",
+				properties: { Name: Builder.title("Fix the bug") },
+			},
+		],
+	}),
+});
+```
+
+Put each default-exported sync directly in `src/syncs/`. A primary key must be a title
+or rich-text property. Do not include that property in an upsert: the SDK fills it from
+the change's `key`.
+
+### Moving from the Workers alpha SDK
+
+- Remove `type` and `primaryKey` from `createDatabase`.
+- Move the property map from `schema.properties` directly into `schema`.
+- Add `primaryKey` to each `createSync`.
+- Remove the primary-key property from each upsert's `properties` object.
+- Change imports from `@notionhq/workers/alpha/*` to `@notionhq/apps/*`.
+
 ## Publishing New Versions
 
 Publishing is initiated only from the GitHub Actions UI:
@@ -22,5 +67,5 @@ Publishing is initiated only from the GitHub Actions UI:
 2. Select **Run workflow** on the `main` branch.
 
 The workflow always increments the patch version. It builds, checks, and tests the
-SDK before committing the new version, creating an `apps-v*` GitHub release,
+SDK before committing the new version, creating a `v*` GitHub release,
 and publishing `@notionhq/apps` to npm.

package/dist/builder.d.ts

@@ -0,0 +1,29 @@
+import type { Cover, Icon, NoticonColor, PeopleValue, PlaceValue, RelationReference, TextValue } from "./types.js";
+/** Build property values returned by a sync handler. */
+export declare const Builder: {
+    richText: (content: string) => TextValue;
+    text: (content: string) => TextValue;
+    title: (content: string) => TextValue;
+    url: (url: string) => TextValue;
+    email: (email: string) => TextValue;
+    phoneNumber: (phone: string) => TextValue;
+    checkbox: (checked: boolean) => TextValue;
+    file: (url: string, name?: string) => TextValue;
+    number: (value: number) => TextValue;
+    date(value: string): TextValue;
+    dateTime(value: string, timeZone?: string): TextValue;
+    dateRange(startDate: string, endDate: string): TextValue;
+    dateTimeRange(startValue: string, endValue: string, timeZone?: string): TextValue;
+    link: (text: string, url: string) => TextValue;
+    select: (value: string) => TextValue;
+    multiSelect: (...values: string[]) => TextValue;
+    status: (value: string) => TextValue;
+    people: (...emails: string[]) => PeopleValue;
+    place(value: PlaceValue): PlaceValue;
+    relation: (primaryKey: string) => RelationReference;
+    emojiIcon: (value: string) => Icon;
+    notionIcon: (icon: string, color?: NoticonColor) => Icon;
+    imageIcon: (url: string) => Icon;
+    imageCover(url: string, position?: number): Cover;
+};
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,KAAK,EAEL,IAAI,EACJ,YAAY,EACZ,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,SAAS,EACT,MAAM,YAAY,CAAC;AAmBpB,wDAAwD;AACxD,eAAO,MAAM,OAAO;wBACC,MAAM,KAAG,SAAS;oBACtB,MAAM,KAAG,SAAS;qBACjB,MAAM,KAAG,SAAS;eACxB,MAAM,KAAG,SAAS;mBACd,MAAM,KAAG,SAAS;yBACZ,MAAM,KAAG,SAAS;wBACnB,OAAO,KAAG,SAAS;gBAC3B,MAAM,SAAS,MAAM,KAAG,SAAS;oBAC7B,MAAM,KAAG,SAAS;gBACtB,MAAM,GAAG,SAAS;oBAId,MAAM,aAAa,MAAM,GAAG,SAAS;yBAShC,MAAM,WAAW,MAAM,GAAG,SAAS;8BAK9B,MAAM,YAAY,MAAM,aAAa,MAAM,GAAG,SAAS;iBAYpE,MAAM,OAAO,MAAM,KAAG,SAAS;oBAC5B,MAAM,KAAG,SAAS;6BACT,MAAM,EAAE,KAAG,SAAS;oBAE7B,MAAM,KAAG,SAAS;wBACd,MAAM,EAAE,KAAG,WAAW;iBAC7B,UAAU,GAAG,UAAU;2BAMb,MAAM,KAAG,iBAAiB;uBAI9B,MAAM,KAAG,IAAI;uBACb,MAAM,UAAS,YAAY,KAAY,IAAI;qBAK7C,MAAM,KAAG,IAAI;oBACd,MAAM,sBAAmB,KAAK;CAM9C,CAAC"}

package/dist/builder.js

@@ -0,0 +1,86 @@
+function validateDateString(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(new Date(value).getTime())) {
+    throw new Error(`Invalid date: ${value}. Expected YYYY-MM-DD.`);
+  }
+}
+function dateToken(value) {
+  return [["\u2023", [["d", value]]]];
+}
+function parseISODateTime(value) {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(value) || Number.isNaN(new Date(value).getTime())) {
+    throw new Error(`Invalid ISO 8601 datetime: ${value}`);
+  }
+  return { date: value.slice(0, 10), time: value.slice(11, 16) };
+}
+const Builder = {
+  richText: (content) => [[content]],
+  text: (content) => [[content]],
+  title: (content) => [[content]],
+  url: (url) => [[url]],
+  email: (email) => [[email]],
+  phoneNumber: (phone) => [[phone]],
+  checkbox: (checked) => checked ? [["Yes"]] : [["No"]],
+  file: (url, name) => [[name ?? url, [["a", url]]]],
+  number: (value) => Number.isNaN(value) ? [] : [[String(value)]],
+  date(value) {
+    validateDateString(value);
+    return dateToken({ type: "date", start_date: value });
+  },
+  dateTime(value, timeZone) {
+    const parsed = parseISODateTime(value);
+    return dateToken({
+      type: "datetime",
+      start_date: parsed.date,
+      start_time: parsed.time,
+      ...timeZone === void 0 ? {} : { time_zone: timeZone }
+    });
+  },
+  dateRange(startDate, endDate) {
+    validateDateString(startDate);
+    validateDateString(endDate);
+    return dateToken({ type: "daterange", start_date: startDate, end_date: endDate });
+  },
+  dateTimeRange(startValue, endValue, timeZone) {
+    const start = parseISODateTime(startValue);
+    const end = parseISODateTime(endValue);
+    return dateToken({
+      type: "datetimerange",
+      start_date: start.date,
+      start_time: start.time,
+      end_date: end.date,
+      end_time: end.time,
+      ...timeZone === void 0 ? {} : { time_zone: timeZone }
+    });
+  },
+  link: (text, url) => [[text, [["a", url]]]],
+  select: (value) => [[value]],
+  multiSelect: (...values) => values.length === 0 ? [] : [[values.join(",")]],
+  status: (value) => [[value]],
+  people: (...emails) => emails.map((email) => ({ email })),
+  place(value) {
+    if (!Number.isFinite(value.lat) || !Number.isFinite(value.lon)) {
+      throw new Error("Place value must have numeric lat and lon coordinates");
+    }
+    return value;
+  },
+  relation: (primaryKey) => ({
+    type: "primaryKey",
+    value: primaryKey
+  }),
+  emojiIcon: (value) => ({ type: "emoji", value }),
+  notionIcon: (icon, color = "gray") => ({
+    type: "notion",
+    icon,
+    color
+  }),
+  imageIcon: (url) => ({ type: "image", url }),
+  imageCover(url, position = 0.5) {
+    if (!Number.isFinite(position) || position < 0 || position > 1) {
+      throw new Error("Cover position must be between 0 and 1");
+    }
+    return { type: "image", url, position };
+  }
+};
+export {
+  Builder
+};

package/dist/builder.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=builder.test.d.ts.map

package/dist/builder.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.test.d.ts","sourceRoot":"","sources":["../src/builder.test.ts"],"names":[],"mappings":""}

package/dist/cli/build.js

@@ -8,7 +8,7 @@ async function buildApp(projectRoot) {
   const capabilities = await discoverCapabilities(projectRoot);
   if (capabilities.length === 0) {
     throw new Error(
-      `No capabilities found in ${projectRoot}. Add a workflow file under src/workflows/<name>.ts that default-exports createWorkflow(...).`
+      `No capabilities found in ${projectRoot}. Add a workflow under src/workflows/ or a sync under src/syncs/.`
     );
   }
   const entryPath = path.join(projectRoot, ".notion", "entry.ts");

package/dist/cli/discover.d.ts

@@ -2,7 +2,7 @@ import type { CapabilityType } from "../manifest.js";
 /**
  * A capability type the build tool knows how to discover: which directory
  * under `src/` its files live in, and the `_tag` its default exports must
- * carry. This SDK intentionally registers workflows only.
+ * carry. This SDK registers workflows and syncs.
  */
 export type CapabilityTypeDefinition = {
     type: CapabilityType;
@@ -26,7 +26,7 @@ export type DiscoveredCapability = {
  * `src/<directory>/` for each registered capability type. Subdirectories are
  * not searched — they hold plain modules, not capabilities.
  *
- * Only workflow files directly under `src/workflows/` are discovered.
+ * Workflow and sync files are discovered from their matching directories.
  */
 export declare function discoverCapabilities(projectRoot: string): Promise<DiscoveredCapability[]>;
 //# sourceMappingURL=discover.d.ts.map

package/dist/cli/discover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/cli/discover.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACtC,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAAS,wBAAwB,EAE/D,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAiC/F"}
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/cli/discover.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACtC,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACZ,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAAS,wBAAwB,EAG/D,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAiC/F"}

package/dist/cli/discover.js

@@ -1,7 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 const CAPABILITY_TYPES = [
-  { type: "workflow", directory: "workflows", tag: "workflow" }
+  { type: "workflow", directory: "workflows", tag: "workflow" },
+  { type: "sync", directory: "syncs", tag: "sync" }
 ];
 async function discoverCapabilities(projectRoot) {
   const discovered = [];

package/dist/cli/emit-manifest.d.ts

@@ -1,10 +1,10 @@
 import type { AppManifest } from "../manifest.js";
 import type { DiscoveredCapability } from "./discover.js";
-/** Extract the workflow-only app manifest from a built bundle. */
+/** Extract the app manifest from a built bundle. */
 export declare function extractManifest(bundlePath: string, capabilities: readonly DiscoveredCapability[]): Promise<AppManifest>;
 /**
  * Throw if `value` contains anything `JSON.stringify` would silently drop or
- * rewrite, so invalid workflow configuration fails during the build.
+ * rewrite, so invalid manifest configuration fails during the build.
  */
 export declare function assertJsonSafe(value: unknown, path: string): void;
 //# sourceMappingURL=emit-manifest.d.ts.map

package/dist/cli/emit-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit-manifest.d.ts","sourceRoot":"","sources":["../../src/cli/emit-manifest.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAgD1D,kEAAkE;AAClE,wBAAsB,eAAe,CACpC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAC3C,OAAO,CAAC,WAAW,CAAC,CAmCtB;AAgDD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CA4CjE"}
+{"version":3,"file":"emit-manifest.d.ts","sourceRoot":"","sources":["../../src/cli/emit-manifest.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAA6C,MAAM,gBAAgB,CAAC;AAE7F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA0M1D,oDAAoD;AACpD,wBAAsB,eAAe,CACpC,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAC3C,OAAO,CAAC,WAAW,CAAC,CA6EtB;AAkCD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAoCjE"}

package/dist/cli/emit-manifest.js

@@ -1,6 +1,8 @@
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 import { Ajv } from "ajv";
+import { APPS_MANIFEST_SCHEMA } from "../manifest.js";
+import { clearRegisteredPacers, registeredPacers } from "../pacer.js";
 const SDK_VERSION = (() => {
   const require2 = createRequire(import.meta.url);
   const packageJson = require2("../../package.json");
@@ -12,16 +14,55 @@ const SDK_VERSION = (() => {
 const MANIFEST_SCHEMA = {
   type: "object",
   properties: {
+    $schema: { type: "string", enum: [APPS_MANIFEST_SCHEMA] },
     sdkVersion: { type: "string" },
-    databases: { type: "array", maxItems: 0 },
+    databases: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string" },
+          config: {
+            type: "object",
+            properties: {
+              initialTitle: { type: "string" },
+              schema: { type: "object" }
+            },
+            required: ["schema"],
+            additionalProperties: false
+          }
+        },
+        required: ["key", "config"],
+        additionalProperties: false
+      }
+    },
     xldbs: { type: "array", maxItems: 0 },
-    pacers: { type: "array", maxItems: 0 },
+    pacers: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: { type: "string" },
+          config: {
+            type: "object",
+            properties: {
+              allowedRequests: { type: "number", exclusiveMinimum: 0 },
+              intervalMs: { type: "number", exclusiveMinimum: 0 }
+            },
+            required: ["allowedRequests", "intervalMs"],
+            additionalProperties: false
+          }
+        },
+        required: ["key", "config"],
+        additionalProperties: false
+      }
+    },
     capabilities: {
       type: "array",
       items: {
         type: "object",
         properties: {
-          type: { type: "string", const: "workflow" },
+          type: { type: "string", enum: ["workflow", "sync"] },
           key: { type: "string" },
           config: {}
         },
@@ -30,29 +71,147 @@ const MANIFEST_SCHEMA = {
       }
     }
   },
-  required: ["sdkVersion", "databases", "xldbs", "pacers", "capabilities"],
+  required: ["$schema", "sdkVersion", "databases", "xldbs", "pacers", "capabilities"],
   additionalProperties: false
 };
+function asTagged(value) {
+  if (typeof value === "object" && value !== null && "_tag" in value && typeof value._tag === "string" && "config" in value && typeof value.config === "object" && value.config !== null) {
+    return value;
+  }
+  return void 0;
+}
+function asDatabase(value) {
+  const tagged = asTagged(value);
+  if (tagged?._tag === "database" && "key" in tagged && typeof tagged.key === "string") {
+    return tagged;
+  }
+  return void 0;
+}
+function schemaProperties(database) {
+  const schema = database.config.schema;
+  if (typeof schema !== "object" || schema === null || Array.isArray(schema)) {
+    throw new Error(`Database "${database.key}" must have a schema object`);
+  }
+  return schema;
+}
+function isRelationProperty(value) {
+  return typeof value === "object" && value !== null && "type" in value && value.type === "relation" && "database" in value;
+}
+class DatabaseCollector {
+  #keys = /* @__PURE__ */ new Map();
+  #byKey = /* @__PURE__ */ new Map();
+  #order = [];
+  collect(value, referencedFrom) {
+    const known = this.#keys.get(value);
+    if (known !== void 0) return known;
+    const database = asDatabase(value);
+    if (!database) {
+      throw new Error(
+        `${referencedFrom}: expected a database created with createDatabase(...)`
+      );
+    }
+    const duplicate = this.#byKey.get(database.key);
+    if (duplicate && duplicate !== database) {
+      throw new Error(`Two distinct databases use the key "${database.key}"`);
+    }
+    this.#keys.set(database, database.key);
+    this.#byKey.set(database.key, database);
+    this.#order.push(database.key);
+    for (const [propertyName, property] of Object.entries(schemaProperties(database))) {
+      if (isRelationProperty(property)) {
+        this.collect(
+          property.database,
+          `relation property "${propertyName}" of database "${database.key}"`
+        );
+      }
+    }
+    return database.key;
+  }
+  get(key) {
+    return this.#byKey.get(key);
+  }
+  entries() {
+    return this.#order.map((key) => {
+      const database = this.#byKey.get(key);
+      const properties = {};
+      for (const [propertyName, property] of Object.entries(schemaProperties(database))) {
+        if (isRelationProperty(property)) {
+          const { database: target, ...rest } = property;
+          properties[propertyName] = {
+            ...rest,
+            relatedDatabaseKey: this.#keys.get(target)
+          };
+        } else {
+          properties[propertyName] = property;
+        }
+      }
+      return {
+        key,
+        config: {
+          ...typeof database.config.initialTitle === "string" ? { initialTitle: database.config.initialTitle } : {},
+          schema: {
+            properties,
+            ...database.config.databaseIcon === void 0 ? {} : { databaseIcon: database.config.databaseIcon },
+            ...database.config.subItems === void 0 ? {} : { subItems: database.config.subItems }
+          }
+        }
+      };
+    });
+  }
+}
 async function extractManifest(bundlePath, capabilities) {
+  clearRegisteredPacers();
   const bundle = await importBundle(bundlePath);
-  const capabilityRegistry = getCapabilityRegistry(bundle);
+  const registry = getCapabilityRegistry(bundle);
+  const databases = new DatabaseCollector();
+  const primaryKeyByDatabase = /* @__PURE__ */ new Map();
   const capabilityEntries = capabilities.map((capability) => {
-    const value = capabilityRegistry.workflow?.[capability.key];
-    const workflow = asWorkflow(value);
-    if (!workflow) {
+    const tagged = asTagged(registry[capability.type]?.[capability.key]);
+    if (!tagged || tagged._tag !== capability.tag) {
       throw new Error(
-        `${capability.sourcePath}: default export is not a workflow \u2014 files under src/workflows/ must default-export createWorkflow(...)`
+        `${capability.sourcePath}: default export is not a ${capability.type} \u2014 files under this directory must default-export create${capitalize(capability.type)}(...)`
       );
     }
-    assertJsonSafe(workflow.config, `${capability.sourcePath} config`);
-    return { type: "workflow", key: capability.key, config: workflow.config };
+    let config = { ...tagged.config };
+    if (capability.type === "sync") {
+      const databaseKey = databases.collect(config.database, capability.sourcePath);
+      const database = databases.get(databaseKey);
+      const primaryKey = config.primaryKeyProperty;
+      const property = typeof primaryKey === "string" ? schemaProperties(database)[primaryKey] : void 0;
+      if (typeof primaryKey !== "string" || typeof property !== "object" || property === null || !("type" in property) || property.type !== "title" && property.type !== "text") {
+        throw new Error(
+          `${capability.sourcePath}: primaryKey "${String(primaryKey)}" must name a title or rich-text property`
+        );
+      }
+      const existingPrimaryKey = primaryKeyByDatabase.get(databaseKey);
+      if (existingPrimaryKey !== void 0 && existingPrimaryKey !== primaryKey) {
+        throw new Error(
+          `Syncs for database "${databaseKey}" disagree on its primary key: "${existingPrimaryKey}" and "${primaryKey}"`
+        );
+      }
+      primaryKeyByDatabase.set(databaseKey, primaryKey);
+      const { database: _database, ...rest } = config;
+      config = { ...rest, databaseKey };
+    }
+    assertJsonSafe(config, `${capability.sourcePath} config`);
+    return { type: capability.type, key: capability.key, config };
   });
+  const pacerEntries = registeredPacers().map((pacer) => ({
+    key: pacer.name,
+    config: pacer.config
+  }));
+  for (const pacer of pacerEntries) assertJsonSafe(pacer.config, `pacer "${pacer.key}" config`);
+  const databaseEntries = databases.entries();
+  for (const database of databaseEntries) {
+    assertJsonSafe(database.config, `database "${database.key}" config`);
+  }
   const manifest = JSON.parse(
     JSON.stringify({
+      $schema: APPS_MANIFEST_SCHEMA,
       sdkVersion: SDK_VERSION,
-      databases: [],
+      databases: databaseEntries,
       xldbs: [],
-      pacers: [],
+      pacers: pacerEntries,
       capabilities: capabilityEntries
     })
   );
@@ -68,8 +227,7 @@ async function importBundle(bundlePath) {
     return await import(`${pathToFileURL(bundlePath).href}?import=${importNonce++}`);
   } catch (error) {
     throw new Error(
-      `Failed to import built app bundle. Workflow modules must be importable without secrets or network access \u2014 check for top-level code that throws.
-Caused by: ${error instanceof Error ? error.message : String(error)}`
+      `Failed to import built app bundle. Capability modules must be importable without secrets or network access. Caused by: ${error instanceof Error ? error.message : String(error)}`
     );
   }
 }
@@ -79,11 +237,8 @@ function getCapabilityRegistry(bundle) {
   }
   return bundle.capabilities;
 }
-function asWorkflow(value) {
-  if (typeof value === "object" && value !== null && "_tag" in value && value._tag === "workflow" && "config" in value && typeof value.config === "object" && value.config !== null) {
-    return value;
-  }
-  return void 0;
+function capitalize(value) {
+  return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
 }
 function assertJsonSafe(value, path) {
   const reject = (reason) => {
@@ -91,13 +246,9 @@ function assertJsonSafe(value, path) {
   };
   switch (typeof value) {
     case "function":
-      reject("function");
-      break;
     case "symbol":
-      reject("symbol");
-      break;
     case "bigint":
-      reject("bigint");
+      reject(typeof value);
       break;
     case "number":
       if (!Number.isFinite(value)) reject(String(value));
@@ -121,8 +272,7 @@ function assertJsonSafe(value, path) {
     reject(object.constructor?.name ?? "non-plain object");
   }
   for (const [key, property] of Object.entries(object)) {
-    if (property === void 0) continue;
-    assertJsonSafe(property, `${path}.${key}`);
+    if (property !== void 0) assertJsonSafe(property, `${path}.${key}`);
   }
 }
 export {

package/dist/context.js

@@ -1,7 +1,7 @@
 import { Client } from "@notionhq/client";
 const FIX_STEPS = "\n\nTo fix this:\n1. Create a personal access token at https://app.notion.com/developers/tokens\n2. Add NOTION_API_TOKEN=<your-token> to your .env file\n3. For deployed apps, run: ntn apps env push";
 function missingTokenMessage() {
-  return "NOTION_API_TOKEN is not set. context.notion requires an API token to make requests in workflow capabilities to Notion." + FIX_STEPS;
+  return "NOTION_API_TOKEN is not set. context.notion requires an API token to make requests from app capabilities to Notion." + FIX_STEPS;
 }
 function createUnauthenticatedNotionProxy() {
   return new Proxy({}, {

package/dist/database.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseSchema, DatabaseSchemaOptions } from "./schema.js";
+export type DatabaseConfiguration<S extends DatabaseSchema = DatabaseSchema> = DatabaseSchemaOptions & {
+    initialTitle?: string;
+    schema: S;
+};
+export type Database<S extends DatabaseSchema = DatabaseSchema> = {
+    _tag: "database";
+    key: string;
+    config: DatabaseConfiguration<S>;
+};
+/** Declare a Notion database that a user will attach to this app. */
+export declare function createDatabase<const S extends DatabaseSchema>(key: string, config: DatabaseConfiguration<S>): Database<S>;
+//# sourceMappingURL=database.d.ts.map

package/dist/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzE,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAC1E,qBAAqB,GAAG;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,CAAC,CAAC;CACV,CAAC;AAEH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,IAAI;IACjE,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;CACjC,CAAC;AAEF,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,KAAK,CAAC,CAAC,SAAS,cAAc,EAC5D,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAC9B,QAAQ,CAAC,CAAC,CAAC,CAMb"}

package/dist/database.js

@@ -0,0 +1,9 @@
+function createDatabase(key, config) {
+  if (typeof key !== "string" || key.length === 0) {
+    throw new Error("Database key must be a non-empty string");
+  }
+  return { _tag: "database", key, config };
+}
+export {
+  createDatabase
+};

package/dist/error.d.ts

@@ -5,4 +5,11 @@ export declare class ExecutionError extends Error {
     readonly cause: unknown;
     constructor(cause: unknown);
 }
+/** Tell the platform that an external service asked the sync to slow down. */
+export declare class RateLimitError extends ExecutionError {
+    readonly retryAfter: number | undefined;
+    constructor(options?: {
+        retryAfter?: number;
+    });
+}
 //# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,SAAkB,KAAK,EAAE,OAAO,CAAC;gBAErB,KAAK,EAAE,OAAO;CAK1B"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,SAAkB,KAAK,EAAE,OAAO,CAAC;gBAErB,KAAK,EAAE,OAAO;CAK1B;AAED,8EAA8E;AAC9E,qBAAa,cAAe,SAAQ,cAAc;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;gBAE5B,OAAO,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;CAK7C"}

package/dist/error.js

@@ -6,6 +6,15 @@ class ExecutionError extends Error {
     this.cause = cause;
   }
 }
+class RateLimitError extends ExecutionError {
+  retryAfter;
+  constructor(options) {
+    super("Rate limited by external API");
+    this.name = "RateLimitError";
+    this.retryAfter = options?.retryAfter;
+  }
+}
 export {
-  ExecutionError
+  ExecutionError,
+  RateLimitError
 };

package/dist/manifest.d.ts

@@ -1,5 +1,29 @@
-/** The only capability type supported by this SDK. */
-export type CapabilityType = "workflow";
+import type { NormalizedSchedule } from "./types.js";
+/** Identifies the schema used to validate this manifest independently of the SDK package version. */
+export declare const APPS_MANIFEST_SCHEMA: "notion:apps-manifest:v1";
+/** Capability types supported by this SDK. */
+export type CapabilityType = "workflow" | "sync";
+export type DatabaseManifestConfig = {
+    initialTitle?: string;
+    schema: unknown;
+};
+export type DatabaseManifestEntry = {
+    key: string;
+    config: DatabaseManifestConfig;
+};
+export type PacerManifestEntry = {
+    key: string;
+    config: {
+        allowedRequests: number;
+        intervalMs: number;
+    };
+};
+export type SyncManifestConfig = {
+    databaseKey: string;
+    primaryKeyProperty: string;
+    mode?: "replace" | "incremental";
+    schedule?: NormalizedSchedule;
+};
 /**
  * One capability in the manifest: its type, its key (derived from its
  * filename), and its handler-free configuration.
@@ -15,11 +39,12 @@ export type CapabilityManifestEntry = {
  * complete, static description of the app.
  */
 export type AppManifest = {
+    $schema: typeof APPS_MANIFEST_SCHEMA;
     sdkVersion: string;
-    /** Reserved platform fields; workflow-only apps always emit empty arrays. */
-    databases: never[];
+    databases: DatabaseManifestEntry[];
+    /** Reserved platform field; the Apps SDK does not support XLDB. */
     xldbs: never[];
-    pacers: never[];
+    pacers: PacerManifestEntry[];
     capabilities: CapabilityManifestEntry[];
 };
 //# sourceMappingURL=manifest.d.ts.map