@notionhq/apps 0.0.11 → 0.0.13

package/README.md

@@ -92,3 +92,31 @@ Publishing is initiated only from the GitHub Actions UI:
 The workflow always increments the patch version. It builds, checks, and tests the
 SDK before committing the new version, creating a `v*` GitHub release,
 and publishing `@notionhq/apps` to npm.
+
+## Custom blocks
+
+Declare browser blocks in `src/customBlocks/<key>.ts`:
+
+```ts
+import { createCustomBlock } from "@notionhq/apps/custom-block";
+
+export default createCustomBlock({
+	path: "./blocks/hello",
+	slashCommand: "hello",
+	dataSources: {},
+});
+```
+
+The filename supplies the block key. `path` is required and relative to the app
+root. Browser source belongs in the directory it names, with `index.html` and a
+Vite config. The project root supplies React, React DOM, Vite, and the React Vite
+plugin. `command` defaults to `npx vite build`, and `output` defaults to `dist`.
+Use `static: true` for an already-built directory. `slashCommand` accepts one
+optional leading `/`, then 1–64 lowercase letters, numbers, hyphens or underscores,
+starting with a letter or number. `dataSources` describes the block's schemas.
+
+`notion-apps build` reads declarations in a separate temporary bundle and emits
+`custom_block` capabilities into the manifest. Blocks never enter `worker.js`.
+
+`notion-apps build-blocks` and `notion-apps upload-blocks` are invoked by the CLI
+during `ntn apps deploy` for local builds.

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

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAUlD,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAoCxE"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/cli/build.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAUlD,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAwCxE"}

package/dist/cli/build.js

@@ -5,9 +5,9 @@ import {
   createProvisioningArtifact
 } from "../notion-as-code/provisioning.js";
 import { clearRegisteredPacers } from "../pacer.js";
-import { generateEntry, generateMetadataEntry } from "./codegen.js";
+import { generateEntry, generateMetadataEntry, generateBlocksEntry } from "./codegen.js";
 import { discoverCapabilities } from "./discover.js";
-import { extractManifest, extractProvisioning } from "./emit-manifest.js";
+import { extractManifest, extractProvisioning, extractBlockConfigs } from "./emit-manifest.js";
 async function buildApp(projectRoot) {
   const capabilities = await discoverCapabilities(projectRoot);
   if (capabilities.length === 0) {
@@ -29,11 +29,15 @@ async function buildApp(projectRoot) {
   } finally {
     await bundle.close();
   }
-  const manifest = await extractManifest(bundlePath, capabilities);
+  const blockConfigs = await buildBlockDeclarations(projectRoot, capabilities);
+  const manifest = await extractManifest(bundlePath, capabilities, blockConfigs);
   const manifestPath = path.join(projectRoot, "dist", "manifest.json");
   await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, "	")}
 `);
-  await emitProvisioningArtifact(projectRoot, capabilities);
+  await emitProvisioningArtifact(
+    projectRoot,
+    capabilities.filter((capability) => capability.runtime === "worker")
+  );
   return { manifest, bundlePath, manifestPath };
 }
 async function emitProvisioningArtifact(projectRoot, capabilities) {
@@ -73,6 +77,32 @@ async function buildMetadata(projectRoot, capabilities) {
     await fs.promises.rm(metadataBundlePath, { force: true });
   }
 }
+async function buildBlockDeclarations(projectRoot, capabilities) {
+  if (!capabilities.some((capability) => capability.runtime === "build")) return {};
+  const entryPath = path.join(projectRoot, ".notion", "blocks-entry.ts");
+  const bundlePath = path.join(projectRoot, ".notion", "blocks.js");
+  await fs.promises.writeFile(entryPath, generateBlocksEntry(capabilities));
+  try {
+    const bundle = await rolldown({
+      input: entryPath,
+      platform: "node",
+      external: (id) => !id.startsWith(".") && !path.isAbsolute(id)
+    });
+    try {
+      await bundle.write({ format: "esm", file: bundlePath, codeSplitting: false });
+    } finally {
+      await bundle.close();
+    }
+    return await extractBlockConfigs(bundlePath);
+  } catch (error) {
+    throw new Error(
+      `Failed to read custom block declarations (${capabilities.filter((c) => c.runtime === "build").map((c) => c.sourcePath).join(", ")}): ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error }
+    );
+  } finally {
+    await fs.promises.rm(bundlePath, { force: true });
+  }
+}
 export {
   buildApp
 };

package/dist/cli/codegen.d.ts

@@ -12,4 +12,6 @@ export declare function generateEntry(capabilities: readonly DiscoveredCapabilit
  * recorder starts and remain isolated from the deployed Worker entry.
  */
 export declare function generateMetadataEntry(capabilities: readonly DiscoveredCapability[]): string;
+/** Evaluate block declarations only while building, separately from the Worker. */
+export declare function generateBlocksEntry(capabilities: readonly DiscoveredCapability[]): string;
 //# sourceMappingURL=codegen.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/cli/codegen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAAG,MAAM,CAyCnF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAAG,MAAM,CAe3F"}
+{"version":3,"file":"codegen.d.ts","sourceRoot":"","sources":["../../src/cli/codegen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAE1D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAAG,MAAM,CA6CnF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAAG,MAAM,CAe3F;AAED,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,SAAS,oBAAoB,EAAE,GAAG,MAAM,CAWzF"}

package/dist/cli/codegen.js

@@ -1,9 +1,11 @@
 function generateEntry(capabilities) {
   const imports = [];
   const registryEntries = /* @__PURE__ */ new Map();
-  capabilities.forEach((capability, index) => {
+  capabilities.filter((capability) => capability.runtime !== "build").forEach((capability, index) => {
     const binding = `capability_${index}`;
-    imports.push(`import ${binding} from ${JSON.stringify(`../${capability.sourcePath}`)};`);
+    imports.push(
+      `import ${binding} from ${JSON.stringify(`../${capability.sourcePath}`)};`
+    );
     const entries = registryEntries.get(capability.type) ?? [];
     entries.push(`		${JSON.stringify(capability.key)}: ${binding},`);
     registryEntries.set(capability.type, entries);
@@ -49,7 +51,16 @@ ${imports}
 export default finishMetadataRecording(recorder);
 `;
 }
+function generateBlocksEntry(capabilities) {
+  const entries = capabilities.filter((capability) => capability.runtime === "build");
+  return entries.map(
+    (capability, index) => `import block_${index} from ${JSON.stringify(`../${capability.sourcePath}`)};`
+  ).join("\n") + `
+export const capabilities = { custom_block: {${entries.map((capability, index) => `${JSON.stringify(capability.key)}: block_${index}`).join(",")}} };
+`;
+}
 export {
+  generateBlocksEntry,
   generateEntry,
   generateMetadataEntry
 };

package/dist/cli/discover.d.ts

@@ -8,6 +8,7 @@ export type CapabilityTypeDefinition = {
     type: CapabilityType;
     directory: string;
     tag: string;
+    runtime: "worker" | "build";
 };
 export declare const CAPABILITY_TYPES: readonly CapabilityTypeDefinition[];
 /**
@@ -17,6 +18,7 @@ export declare const CAPABILITY_TYPES: readonly CapabilityTypeDefinition[];
 export type DiscoveredCapability = {
     type: CapabilityType;
     tag: string;
+    runtime: "worker" | "build";
     key: string;
     /** Path to the source file, relative to the project root. */
     sourcePath: string;

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,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"}
+{"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;IACZ,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,SAAS,wBAAwB,EAI/D,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC5B,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,CAkC/F"}

package/dist/cli/discover.js

@@ -1,8 +1,9 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 const CAPABILITY_TYPES = [
-  { type: "workflow", directory: "workflows", tag: "workflow" },
-  { type: "sync", directory: "syncs", tag: "sync" }
+  { type: "workflow", directory: "workflows", tag: "workflow", runtime: "worker" },
+  { type: "sync", directory: "syncs", tag: "sync", runtime: "worker" },
+  { type: "custom_block", directory: "customBlocks", tag: "custom_block", runtime: "build" }
 ];
 async function discoverCapabilities(projectRoot) {
   const discovered = [];
@@ -25,6 +26,7 @@ async function discoverCapabilities(projectRoot) {
       discovered.push({
         type: definition.type,
         tag: definition.tag,
+        runtime: definition.runtime,
         key: entry.name.slice(0, -".ts".length),
         sourcePath: path.join("src", definition.directory, entry.name)
       });

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

@@ -2,7 +2,7 @@ import { type RecordedProvisioning } from "../notion-as-code/provisioning.js";
 import type { AppManifest } from "../manifest.js";
 import type { DiscoveredCapability } from "./discover.js";
 /** Extract the app manifest from a built bundle. */
-export declare function extractManifest(bundlePath: string, capabilities: readonly DiscoveredCapability[]): Promise<AppManifest>;
+export declare function extractManifest(bundlePath: string, capabilities: readonly DiscoveredCapability[], blockConfigs?: Record<string, unknown>): Promise<AppManifest>;
 /** Import the metadata bundle and return the provisioning declarations it recorded. */
 export declare function extractProvisioning(bundlePath: string): Promise<RecordedProvisioning>;
 /**
@@ -10,4 +10,6 @@ export declare function extractProvisioning(bundlePath: string): Promise<Recorde
  * rewrite, so invalid manifest configuration fails during the build.
  */
 export declare function assertJsonSafe(value: unknown, path: string): void;
+/** Read the isolated declaration bundle; browser declarations never enter the Worker. */
+export declare function extractBlockConfigs(bundlePath: string): Promise<Record<string, unknown>>;
 //# 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":"AAMA,OAAO,EAEN,KAAK,oBAAoB,EACzB,MAAM,mCAAmC,CAAC;AAC3C,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;AAED,uFAAuF;AACvF,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAW3F;AAkCD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAoCjE"}
+{"version":3,"file":"emit-manifest.d.ts","sourceRoot":"","sources":["../../src/cli/emit-manifest.ts"],"names":[],"mappings":"AAMA,OAAO,EAEN,KAAK,oBAAoB,EACzB,MAAM,mCAAmC,CAAC;AAC3C,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,EAC7C,YAAY,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACxC,OAAO,CAAC,WAAW,CAAC,CAiFtB;AAED,uFAAuF;AACvF,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAW3F;AAkCD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAoCjE;AAED,yFAAyF;AACzF,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAE9F"}

package/dist/cli/emit-manifest.js

@@ -65,7 +65,7 @@ const MANIFEST_SCHEMA = {
       items: {
         type: "object",
         properties: {
-          type: { type: "string", enum: ["workflow", "sync"] },
+          type: { type: "string", enum: ["workflow", "sync", "custom_block"] },
           key: { type: "string" },
           config: {}
         },
@@ -162,17 +162,19 @@ class DatabaseCollector {
     });
   }
 }
-async function extractManifest(bundlePath, capabilities) {
+async function extractManifest(bundlePath, capabilities, blockConfigs = {}) {
   clearRegisteredPacers();
   const bundle = await importBundle(bundlePath);
   const registry = getCapabilityRegistry(bundle);
   const databases = new DatabaseCollector();
   const primaryKeyByDatabase = /* @__PURE__ */ new Map();
   const capabilityEntries = capabilities.map((capability) => {
-    const tagged = asTagged(registry[capability.type]?.[capability.key]);
+    const tagged = asTagged(
+      capability.runtime === "build" ? blockConfigs[capability.key] : registry[capability.type]?.[capability.key]
+    );
     if (!tagged || tagged._tag !== capability.tag) {
       throw new Error(
-        `${capability.sourcePath}: default export is not a ${capability.type} \u2014 files under this directory must default-export create${capitalize(capability.type)}(...)`
+        `${capability.sourcePath}: default export is not a ${capability.type} \u2014 files under this directory must default-export create${capability.type === "custom_block" ? "CustomBlock" : capitalize(capability.type)}(...)`
       );
     }
     let config = { ...tagged.config };
@@ -285,8 +287,12 @@ function assertJsonSafe(value, path) {
     if (property !== void 0) assertJsonSafe(property, `${path}.${key}`);
   }
 }
+async function extractBlockConfigs(bundlePath) {
+  return getCapabilityRegistry(await importBundle(bundlePath)).custom_block ?? {};
+}
 export {
   assertJsonSafe,
+  extractBlockConfigs,
   extractManifest,
   extractProvisioning
 };

package/dist/cli/index.js

@@ -1,10 +1,14 @@
 #!/usr/bin/env node
 import * as path from "node:path";
+import { parseArgs } from "node:util";
+import { build, upload, printBuildOutput, parseUploadsInput } from "@notionhq/custom-blocks/bundle";
 import { buildApp } from "./build.js";
 const USAGE = `Usage: notion-apps <command>
 
 Commands:
-  build    Build the app in the current directory
+  build          Build the app in the current directory
+  build-blocks   Build browser bundles (--manifest <path> --out <dir>)
+  upload-blocks  Upload browser bundles (--uploads <json>)
 `;
 async function main() {
   const command = process.argv[2];
@@ -18,6 +22,34 @@ async function main() {
       );
       break;
     }
+    case "build-blocks": {
+      const { values } = parseArgs({
+        args: process.argv.slice(3),
+        options: {
+          manifest: { type: "string" },
+          out: { type: "string" },
+          cwd: { type: "string" }
+        }
+      });
+      if (!values.out) throw new Error("build-blocks requires --out <dir>");
+      printBuildOutput(
+        await build({
+          out: values.out,
+          manifest: values.manifest ?? "dist/manifest.json",
+          cwd: values.cwd
+        })
+      );
+      break;
+    }
+    case "upload-blocks": {
+      const { values } = parseArgs({
+        args: process.argv.slice(3),
+        options: { uploads: { type: "string" } }
+      });
+      if (!values.uploads) throw new Error("upload-blocks requires --uploads <json>");
+      console.log(JSON.stringify(await upload(parseUploadsInput(values.uploads))));
+      break;
+    }
     case void 0:
     case "help":
     case "--help":

package/dist/custom-block.d.ts

@@ -0,0 +1,54 @@
+import type { ManifestDataSource } from "@notionhq/custom-blocks";
+export type CustomBlockOptions = {
+    path: string;
+    slashCommand?: string;
+    dataSources?: Record<string, ManifestDataSource>;
+} & ({
+    static: true;
+    command?: never;
+    output?: never;
+} | {
+    static?: false;
+    command?: string;
+    output?: string;
+});
+/** Declare a browser project. Its filename under src/customBlocks supplies its key. */
+export declare function createCustomBlock(options: CustomBlockOptions): {
+    _tag: "custom_block";
+    config: {
+        source: {
+            type: "static";
+            path: string;
+            command?: never;
+            output?: never;
+        } | {
+            type: "project";
+            path: string;
+            command: string;
+            output: string;
+        };
+        manifest: {
+            dataSources: Record<string, {
+                name: string;
+                description?: string | undefined;
+                icon?: {
+                    type: "emoji";
+                    emoji: string;
+                } | {
+                    type: "external";
+                    url: string;
+                } | undefined;
+                properties: {
+                    [x: string]: {
+                        name: string;
+                        description?: string | undefined;
+                        type: "number" | "date" | "url" | "title" | "rich_text" | "checkbox" | "email" | "phone_number" | "select" | "multi_select" | "status" | "people" | "files" | "unique_id" | "relation" | "place" | "formula" | "rollup" | "button" | "verification" | "last_visited_time" | "location" | "created_time" | "last_edited_time" | "created_by" | "last_edited_by";
+                    };
+                };
+            }>;
+            slashCommand?: string;
+            version: 1;
+        };
+    };
+};
+//# sourceMappingURL=custom-block.d.ts.map

package/dist/custom-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-block.d.ts","sourceRoot":"","sources":["../src/custom-block.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CACjD,GAAG,CACD;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GACjD;IAAE,MAAM,CAAC,EAAE,KAAK,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CACvD,CAAC;AAEF,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4B5D"}

package/dist/custom-block.js

@@ -0,0 +1,30 @@
+function createCustomBlock(options) {
+  if (typeof options.path !== "string" || options.path.trim() === "") {
+    throw new Error("createCustomBlock requires a non-empty path relative to the app root");
+  }
+  const slashCommand = options.slashCommand?.replace(/^\//, "");
+  if (slashCommand !== void 0 && !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(slashCommand)) {
+    throw new Error(
+      "Custom block slashCommand must be 1\u201364 lowercase letters, numbers, hyphens or underscores, starting with a letter or number"
+    );
+  }
+  return {
+    _tag: "custom_block",
+    config: {
+      source: options.static ? { type: "static", path: options.path } : {
+        type: "project",
+        path: options.path,
+        command: options.command ?? "npx vite build",
+        output: options.output ?? "dist"
+      },
+      manifest: {
+        version: 1,
+        ...slashCommand === void 0 ? {} : { slashCommand },
+        dataSources: options.dataSources ?? {}
+      }
+    }
+  };
+}
+export {
+  createCustomBlock
+};

package/dist/custom-block.test.d.ts

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

package/dist/custom-block.test.d.ts.map

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

package/dist/custom-blocks.d.ts

@@ -0,0 +1,2 @@
+export * from "@notionhq/custom-blocks";
+//# sourceMappingURL=custom-blocks.d.ts.map

package/dist/custom-blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-blocks.d.ts","sourceRoot":"","sources":["../src/custom-blocks.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/dist/custom-blocks.js

@@ -0,0 +1 @@
+export * from "@notionhq/custom-blocks";

package/dist/manifest.d.ts

@@ -2,7 +2,7 @@ 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 CapabilityType = "workflow" | "sync" | "custom_block";
 export type DatabaseManifestConfig = {
     initialTitle?: string;
     schema: unknown;

package/dist/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,qGAAqG;AACrG,eAAO,MAAM,oBAAoB,EAAG,yBAAkC,CAAC;AAEvE,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjD,MAAM,MAAM,sBAAsB,GAAG;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,OAAO,EAAE,OAAO,oBAAoB,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,mEAAmE;IACnE,KAAK,EAAE,KAAK,EAAE,CAAC;IACf,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,YAAY,EAAE,uBAAuB,EAAE,CAAC;CACxC,CAAC"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,qGAAqG;AACrG,eAAO,MAAM,oBAAoB,EAAG,yBAAkC,CAAC;AAEvE,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,cAAc,CAAC;AAElE,MAAM,MAAM,sBAAsB,GAAG;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,IAAI,CAAC,EAAE,SAAS,GAAG,aAAa,CAAC;IACjC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC9B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,OAAO,EAAE,OAAO,oBAAoB,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,mEAAmE;IACnE,KAAK,EAAE,KAAK,EAAE,CAAC;IACf,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,YAAY,EAAE,uBAAuB,EAAE,CAAC;CACxC,CAAC"}

package/dist/nds.css

@@ -0,0 +1 @@
+@import "@notionhq/custom-blocks/nds.css";

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

@@ -1,11 +1,12 @@
 import type { Database } from "../database.js";
-import type { DataSourceDefinition, NotionAsCodeIcon, NotionAsCodeProperty, Parent, ResourceId } from "./intents.js";
+import { type DataSourceDefinition, type NotionAsCodeIcon, type NotionAsCodeProperty, type Parent, type ResourceId } from "./intents.js";
 import { type ChildPageArgs, type PageHandle } from "./page.js";
 import { type AppsSchemaForProperties } from "./schema.js";
 /** Input for declaring a database and its optional data sources. */
 export type DatabaseArgs<DataSources extends readonly DataSourceDefinition[] = readonly DataSourceDefinition[]> = {
     resourceId: ResourceId;
-    parent: Parent;
+    /** Omit to create a private top-level database in the Apps workspace. */
+    parent?: Parent;
     dataSources?: DataSources;
     views?: readonly unknown[];
     icon?: NotionAsCodeIcon;
@@ -36,7 +37,7 @@ export type DatabaseHandle<DataSources extends readonly DataSourceDefinition[] =
     };
     addView: (view: unknown) => void;
 };
-/** Declare a top-level database and its data sources. */
+/** 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>;
 /** Record a database declaration and create handles for each of its data sources. */
 export declare function createDatabase(args: DatabaseArgs, parent: Parent): DatabaseHandle;

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,KAAK,EACX,oBAAoB,EAEpB,gBAAgB,EAChB,oBAAoB,EACpB,MAAM,EACN,UAAU,EACV,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,MAAM,EAAE,MAAM,CAAC;IACf,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,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,KAAK,CAAC,WAAW,SAAS,SAAS,oBAAoB,EAAE,EACjF,IAAI,EAAE,YAAY,CAAC,WAAW,CAAC,GAC7B,cAAc,CAAC,WAAW,CAAC,CAAC;AAM/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":"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"}

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

@@ -1,10 +1,19 @@
+import {
+  APPS_WORKSPACE_RESOURCE_ID
+} from "./intents.js";
 import { createPage } from "./page.js";
 import { recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
 import { createAppsDatabase } from "./schema.js";
 function database(args) {
-  assertParent(args.parent);
-  return createDatabase(args, args.parent);
+  if (args.parent) {
+    assertParent(args.parent);
+  }
+  const parent = args.parent ?? {
+    type: "resourceId",
+    resourceId: APPS_WORKSPACE_RESOURCE_ID
+  };
+  return createDatabase(args, parent);
 }
 function createDatabase(args, parent) {
   assertUserResourceId(args.resourceId);

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

@@ -92,9 +92,12 @@ export type TeamspaceIntent = TeamspaceArgs & {
     parent: Parent;
 };
 export type DatabaseIntent = DatabaseArgs & {
+    parent: Parent;
     dataSources: readonly DataSourceDefinition[];
 };
-export type PageIntent = PageArgs;
+export type PageIntent = PageArgs & {
+    parent: Parent;
+};
 export type CustomAgentIntent = CustomAgentArgs;
 export type ViewIntent = {
     databaseResourceId: ResourceId;

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

@@ -1 +1 @@
-{"version":3,"file":"intents.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/intents.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"intents.d.ts","sourceRoot":"","sources":["../../src/notion-as-code/intents.ts"],"names":[],"mappings":"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"}

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

@@ -1,9 +1,9 @@
-import type { DataSourceDefinition, NotionAsCodeIcon, Parent, ResourceId } from "./intents.js";
+import { type DataSourceDefinition, type Parent, type ResourceId } from "./intents.js";
 import { type ChildDatabaseArgs, type DatabaseHandle } from "./database.js";
 export type PageArgs = {
     resourceId: ResourceId;
-    parent: Parent;
-    icon?: NotionAsCodeIcon;
+    /** Omit to create a private top-level page in the Apps workspace. */
+    parent?: Parent;
     cover?: unknown;
     properties?: Record<string, unknown>;
     content?: string;
@@ -15,7 +15,7 @@ export type PageHandle = {
     addDatabase: <const DataSources extends readonly DataSourceDefinition[]>(args: ChildDatabaseArgs<DataSources>) => DatabaseHandle<DataSources>;
     addPage: (args: ChildPageArgs) => PageHandle;
 };
-/** Declare a top-level page. */
+/** Declare a page, defaulting to a private top-level page in the Apps workspace. */
 export declare function page(args: PageArgs): PageHandle;
 /** Record a page declaration beneath its parent resource. */
 export declare function createPage(args: ChildPageArgs | PageArgs, parent: Parent): PageHandle;

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,KAAK,EACX,oBAAoB,EACpB,gBAAgB,EAEhB,MAAM,EACN,UAAU,EACV,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,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,gBAAgB,CAAC;IAExB,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,gCAAgC;AAChC,wBAAgB,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAG/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,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"}

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

@@ -1,9 +1,18 @@
+import {
+  APPS_WORKSPACE_RESOURCE_ID
+} from "./intents.js";
 import { database } from "./database.js";
 import { recordIntent } from "./recorder.js";
 import { assertParent, assertUserResourceId } from "./resource.js";
 function page(args) {
-  assertParent(args.parent);
-  return createPage(args, args.parent);
+  if (args.parent) {
+    assertParent(args.parent);
+  }
+  const parent = args.parent ?? {
+    type: "resourceId",
+    resourceId: APPS_WORKSPACE_RESOURCE_ID
+  };
+  return createPage(args, parent);
 }
 function createPage(args, parent) {
   assertUserResourceId(args.resourceId);

package/dist/react.d.ts

@@ -0,0 +1,2 @@
+export * from "@notionhq/custom-blocks/react";
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC"}

package/dist/react.js

@@ -0,0 +1 @@
+export * from "@notionhq/custom-blocks/react";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/apps",
-	"version": "0.0.11",
+	"version": "0.0.13",
 	"description": "An SDK for building workflow apps for Notion",
 	"license": "MIT",
 	"bin": {
@@ -66,7 +66,20 @@
 		"./notion-as-code/recorder": {
 			"types": "./dist/notion-as-code/recorder.d.ts",
 			"default": "./dist/notion-as-code/recorder.js"
-		}
+		},
+		"./custom-block": {
+			"types": "./dist/custom-block.d.ts",
+			"default": "./dist/custom-block.js"
+		},
+		"./custom-blocks": {
+			"types": "./dist/custom-blocks.d.ts",
+			"default": "./dist/custom-blocks.js"
+		},
+		"./react": {
+			"types": "./dist/react.d.ts",
+			"default": "./dist/react.js"
+		},
+		"./nds.css": "./dist/nds.css"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -89,6 +102,7 @@
 		"typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.scripts.json"
 	},
 	"dependencies": {
+		"@notionhq/custom-blocks": "latest",
 		"ajv": "^8.17.1",
 		"rolldown": "^1.1.5"
 	},

package/src/cli/build.test.ts

@@ -34,6 +34,42 @@ afterEach(async () => {
 });
 
 describe("buildApp", () => {
+	it("emits workflow and block metadata without adding blocks to the Worker", async () => {
+		const root = fixture("custom-block");
+		const { manifest, bundlePath } = await buildApp(root);
+		expect(manifest.capabilities).toEqual([
+			{ type: "workflow", key: "hello", config: { name: "Hello", triggers: [] } },
+			{
+				type: "custom_block",
+				key: "hello",
+				config: {
+					source: {
+						type: "project",
+						path: "./blocks/hello",
+						command: "npx vite build",
+						output: "dist",
+					},
+					manifest: { version: 1, slashCommand: "hello", dataSources: {} },
+				},
+			},
+		]);
+		const worker = await fs.promises.readFile(bundlePath, "utf8");
+		expect(worker).not.toMatch(
+			/custom_block|createCustomBlock|react|createRoot|NotionCustomBlock/,
+		);
+		expect(fs.existsSync(path.join(root, ".notion/blocks.js"))).toBe(false);
+	});
+	it("names the block file when path is missing", async () => {
+		await expect(buildApp(fixture("custom-block-missing-path"))).rejects.toThrow(
+			/hello.ts.*non-empty path/,
+		);
+	});
+	it("rejects a block file that exports a different capability", async () => {
+		await expect(buildApp(fixture("custom-block-wrong-tag"))).rejects.toThrow(
+			/hello.ts.*createCustomBlock/,
+		);
+	});
+
 	it("builds a sync manifest with a Notion-as-Code meetings database", async () => {
 		const { manifest } = await buildApp(example("sync"));
 
@@ -142,6 +178,24 @@ describe("buildApp", () => {
 					name: "GitHub app data",
 					accessLevel: "open",
 				},
+				{
+					type: "page",
+					resourceId: "github-app-private-page",
+					parent: {
+						type: "resourceId",
+						resourceId: "__notion_apps_workspace__",
+					},
+					properties: { title: [["GitHub app home"]] },
+				},
+				{
+					type: "database",
+					resourceId: "github-app-private-database",
+					parent: {
+						type: "resourceId",
+						resourceId: "__notion_apps_workspace__",
+					},
+					dataSources: [],
+				},
 				{
 					type: "database",
 					resourceId: "issues-db",

package/src/cli/build.ts

@@ -9,9 +9,9 @@ import {
 	type RecordedProvisioning,
 } from "../notion-as-code/provisioning.js";
 import { clearRegisteredPacers } from "../pacer.js";
-import { generateEntry, generateMetadataEntry } from "./codegen.js";
+import { generateEntry, generateMetadataEntry, generateBlocksEntry } from "./codegen.js";
 import { discoverCapabilities, type DiscoveredCapability } from "./discover.js";
-import { extractManifest, extractProvisioning } from "./emit-manifest.js";
+import { extractManifest, extractProvisioning, extractBlockConfigs } from "./emit-manifest.js";
 
 export type BuildResult = {
 	manifest: AppManifest;
@@ -53,11 +53,15 @@ export async function buildApp(projectRoot: string): Promise<BuildResult> {
 		await bundle.close();
 	}
 
-	const manifest = await extractManifest(bundlePath, capabilities);
+	const blockConfigs = await buildBlockDeclarations(projectRoot, capabilities);
+	const manifest = await extractManifest(bundlePath, capabilities, blockConfigs);
 	const manifestPath = path.join(projectRoot, "dist", "manifest.json");
 	await fs.promises.writeFile(manifestPath, `${JSON.stringify(manifest, null, "\t")}\n`);
 
-	await emitProvisioningArtifact(projectRoot, capabilities);
+	await emitProvisioningArtifact(
+		projectRoot,
+		capabilities.filter((capability) => capability.runtime === "worker"),
+	);
 
 	return { manifest, bundlePath, manifestPath };
 }
@@ -110,3 +114,36 @@ async function buildMetadata(
 		await fs.promises.rm(metadataBundlePath, { force: true });
 	}
 }
+
+async function buildBlockDeclarations(
+	projectRoot: string,
+	capabilities: readonly DiscoveredCapability[],
+): Promise<Record<string, unknown>> {
+	if (!capabilities.some((capability) => capability.runtime === "build")) return {};
+	const entryPath = path.join(projectRoot, ".notion", "blocks-entry.ts");
+	const bundlePath = path.join(projectRoot, ".notion", "blocks.js");
+	await fs.promises.writeFile(entryPath, generateBlocksEntry(capabilities));
+	try {
+		const bundle = await rolldown({
+			input: entryPath,
+			platform: "node",
+			external: (id) => !id.startsWith(".") && !path.isAbsolute(id),
+		});
+		try {
+			await bundle.write({ format: "esm", file: bundlePath, codeSplitting: false });
+		} finally {
+			await bundle.close();
+		}
+		return await extractBlockConfigs(bundlePath);
+	} catch (error) {
+		throw new Error(
+			`Failed to read custom block declarations (${capabilities
+				.filter((c) => c.runtime === "build")
+				.map((c) => c.sourcePath)
+				.join(", ")}): ${error instanceof Error ? error.message : String(error)}`,
+			{ cause: error },
+		);
+	} finally {
+		await fs.promises.rm(bundlePath, { force: true });
+	}
+}

package/src/cli/codegen.test.ts

@@ -8,6 +8,7 @@ describe("generateEntry", () => {
 			{
 				type: "workflow",
 				tag: "workflow",
+				runtime: "worker",
 				key: "onPageCreated",
 				sourcePath: "src/workflows/onPageCreated.ts",
 			},
@@ -24,6 +25,7 @@ describe("generateEntry", () => {
 			{
 				type: "sync",
 				tag: "sync",
+				runtime: "worker",
 				key: "issues",
 				sourcePath: "src/syncs/issues.ts",
 			},

package/src/cli/codegen.ts

@@ -11,14 +11,18 @@ export function generateEntry(capabilities: readonly DiscoveredCapability[]): st
 	const imports: string[] = [];
 	const registryEntries = new Map<string, string[]>();
 
-	capabilities.forEach((capability, index) => {
-		const binding = `capability_${index}`;
-		imports.push(`import ${binding} from ${JSON.stringify(`../${capability.sourcePath}`)};`);
+	capabilities
+		.filter((capability) => capability.runtime !== "build")
+		.forEach((capability, index) => {
+			const binding = `capability_${index}`;
+			imports.push(
+				`import ${binding} from ${JSON.stringify(`../${capability.sourcePath}`)};`,
+			);
 
-		const entries = registryEntries.get(capability.type) ?? [];
-		entries.push(`\t\t${JSON.stringify(capability.key)}: ${binding},`);
-		registryEntries.set(capability.type, entries);
-	});
+			const entries = registryEntries.get(capability.type) ?? [];
+			entries.push(`\t\t${JSON.stringify(capability.key)}: ${binding},`);
+			registryEntries.set(capability.type, entries);
+		});
 
 	const registry = Array.from(registryEntries.entries())
 		.map(([type, entries]) => `\t${JSON.stringify(type)}: {\n${entries.join("\n")}\n\t},`)
@@ -70,3 +74,17 @@ ${imports}
 export default finishMetadataRecording(recorder);
 `;
 }
+
+/** Evaluate block declarations only while building, separately from the Worker. */
+export function generateBlocksEntry(capabilities: readonly DiscoveredCapability[]): string {
+	const entries = capabilities.filter((capability) => capability.runtime === "build");
+	return (
+		entries
+			.map(
+				(capability, index) =>
+					`import block_${index} from ${JSON.stringify(`../${capability.sourcePath}`)};`,
+			)
+			.join("\n") +
+		`\nexport const capabilities = { custom_block: {${entries.map((capability, index) => `${JSON.stringify(capability.key)}: block_${index}`).join(",")}} };\n`
+	);
+}

package/src/cli/discover.test.ts

@@ -9,11 +9,21 @@ const EXAMPLES = fileURLToPath(new URL("../../examples/", import.meta.url));
 const FIXTURES = fileURLToPath(new URL("../../test/fixtures/", import.meta.url));
 
 describe("discoverCapabilities", () => {
+	it("discovers custom block declaration files as build-only capabilities", async () => {
+		expect(await discoverCapabilities(path.join(FIXTURES, "custom-block"))).toContainEqual({
+			type: "custom_block",
+			tag: "custom_block",
+			runtime: "build",
+			key: "hello",
+			sourcePath: path.join("src", "customBlocks", "hello.ts"),
+		});
+	});
 	it("discovers workflow files", async () => {
 		await expect(discoverCapabilities(path.join(EXAMPLES, "workflow"))).resolves.toEqual([
 			{
 				type: "workflow",
 				tag: "workflow",
+				runtime: "worker",
 				key: "onPageCreated",
 				sourcePath: path.join("src", "workflows", "onPageCreated.ts"),
 			},
@@ -25,12 +35,14 @@ describe("discoverCapabilities", () => {
 			{
 				type: "sync",
 				tag: "sync",
+				runtime: "worker",
 				key: "issues",
 				sourcePath: path.join("src", "syncs", "issues.ts"),
 			},
 			{
 				type: "sync",
 				tag: "sync",
+				runtime: "worker",
 				key: "notionAsCodeIssues",
 				sourcePath: path.join("src", "syncs", "notionAsCodeIssues.ts"),
 			},

package/src/cli/discover.ts

@@ -12,11 +12,13 @@ export type CapabilityTypeDefinition = {
 	type: CapabilityType;
 	directory: string;
 	tag: string;
+	runtime: "worker" | "build";
 };
 
 export const CAPABILITY_TYPES: readonly CapabilityTypeDefinition[] = [
-	{ type: "workflow", directory: "workflows", tag: "workflow" },
-	{ type: "sync", directory: "syncs", tag: "sync" },
+	{ type: "workflow", directory: "workflows", tag: "workflow", runtime: "worker" },
+	{ type: "sync", directory: "syncs", tag: "sync", runtime: "worker" },
+	{ type: "custom_block", directory: "customBlocks", tag: "custom_block", runtime: "build" },
 ];
 
 /**
@@ -26,6 +28,7 @@ export const CAPABILITY_TYPES: readonly CapabilityTypeDefinition[] = [
 export type DiscoveredCapability = {
 	type: CapabilityType;
 	tag: string;
+	runtime: "worker" | "build";
 	key: string;
 	/** Path to the source file, relative to the project root. */
 	sourcePath: string;
@@ -64,6 +67,7 @@ export async function discoverCapabilities(projectRoot: string): Promise<Discove
 			discovered.push({
 				type: definition.type,
 				tag: definition.tag,
+				runtime: definition.runtime,
 				key: entry.name.slice(0, -".ts".length),
 				sourcePath: path.join("src", definition.directory, entry.name),
 			});

package/src/cli/emit-manifest.ts

@@ -77,7 +77,7 @@ const MANIFEST_SCHEMA = {
 			items: {
 				type: "object",
 				properties: {
-					type: { type: "string", enum: ["workflow", "sync"] },
+					type: { type: "string", enum: ["workflow", "sync", "custom_block"] },
 					key: { type: "string" },
 					config: {},
 				},
@@ -216,6 +216,7 @@ class DatabaseCollector {
 export async function extractManifest(
 	bundlePath: string,
 	capabilities: readonly DiscoveredCapability[],
+	blockConfigs: Record<string, unknown> = {},
 ): Promise<AppManifest> {
 	clearRegisteredPacers();
 	const bundle = await importBundle(bundlePath);
@@ -224,11 +225,15 @@ export async function extractManifest(
 	const primaryKeyByDatabase = new Map<string, string>();
 
 	const capabilityEntries = capabilities.map((capability) => {
-		const tagged = asTagged(registry[capability.type]?.[capability.key]);
+		const tagged = asTagged(
+			capability.runtime === "build"
+				? blockConfigs[capability.key]
+				: registry[capability.type]?.[capability.key],
+		);
 		if (!tagged || tagged._tag !== capability.tag) {
 			throw new Error(
 				`${capability.sourcePath}: default export is not a ${capability.type} — ` +
-					`files under this directory must default-export create${capitalize(capability.type)}(...)`,
+					`files under this directory must default-export create${capability.type === "custom_block" ? "CustomBlock" : capitalize(capability.type)}(...)`,
 			);
 		}
 
@@ -382,3 +387,8 @@ export function assertJsonSafe(value: unknown, path: string): void {
 		if (property !== undefined) assertJsonSafe(property, `${path}.${key}`);
 	}
 }
+
+/** Read the isolated declaration bundle; browser declarations never enter the Worker. */
+export async function extractBlockConfigs(bundlePath: string): Promise<Record<string, unknown>> {
+	return getCapabilityRegistry(await importBundle(bundlePath)).custom_block ?? {};
+}

package/src/cli/index.ts

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import * as path from "node:path";
+import { parseArgs } from "node:util";
+import { build, upload, printBuildOutput, parseUploadsInput } from "@notionhq/custom-blocks/bundle";
 
 import { buildApp } from "./build.js";
 
 const USAGE = `Usage: notion-apps <command>
 
 Commands:
-  build    Build the app in the current directory
+  build          Build the app in the current directory
+  build-blocks   Build browser bundles (--manifest <path> --out <dir>)
+  upload-blocks  Upload browser bundles (--uploads <json>)
 `;
 
 async function main(): Promise<void> {
@@ -24,6 +28,34 @@ async function main(): Promise<void> {
 			);
 			break;
 		}
+		case "build-blocks": {
+			const { values } = parseArgs({
+				args: process.argv.slice(3),
+				options: {
+					manifest: { type: "string" },
+					out: { type: "string" },
+					cwd: { type: "string" },
+				},
+			});
+			if (!values.out) throw new Error("build-blocks requires --out <dir>");
+			printBuildOutput(
+				await build({
+					out: values.out,
+					manifest: values.manifest ?? "dist/manifest.json",
+					cwd: values.cwd,
+				}),
+			);
+			break;
+		}
+		case "upload-blocks": {
+			const { values } = parseArgs({
+				args: process.argv.slice(3),
+				options: { uploads: { type: "string" } },
+			});
+			if (!values.uploads) throw new Error("upload-blocks requires --uploads <json>");
+			console.log(JSON.stringify(await upload(parseUploadsInput(values.uploads))));
+			break;
+		}
 		case undefined:
 		case "help":
 		case "--help":

package/src/custom-block.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { createCustomBlock } from "./custom-block.js";
+
+describe("createCustomBlock", () => {
+	it("supports static assets without a build command", () => {
+		expect(createCustomBlock({ path: "assets", static: true }).config.source).toEqual({
+			type: "static",
+			path: "assets",
+		});
+	});
+	it.each(["//hello", "Hello", "-hello", "", "a".repeat(65)])(
+		"rejects invalid slash command %s",
+		(slashCommand) => {
+			expect(() => createCustomBlock({ path: "blocks/hello", slashCommand })).toThrow(
+				/slashCommand/,
+			);
+		},
+	);
+});

package/src/custom-block.ts

@@ -0,0 +1,41 @@
+import type { ManifestDataSource } from "@notionhq/custom-blocks";
+
+export type CustomBlockOptions = {
+	path: string;
+	slashCommand?: string;
+	dataSources?: Record<string, ManifestDataSource>;
+} & (
+	| { static: true; command?: never; output?: never }
+	| { static?: false; command?: string; output?: string }
+);
+
+/** Declare a browser project. Its filename under src/customBlocks supplies its key. */
+export function createCustomBlock(options: CustomBlockOptions) {
+	if (typeof options.path !== "string" || options.path.trim() === "") {
+		throw new Error("createCustomBlock requires a non-empty path relative to the app root");
+	}
+	const slashCommand = options.slashCommand?.replace(/^\//, "");
+	if (slashCommand !== undefined && !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(slashCommand)) {
+		throw new Error(
+			"Custom block slashCommand must be 1–64 lowercase letters, numbers, hyphens or underscores, starting with a letter or number",
+		);
+	}
+	return {
+		_tag: "custom_block" as const,
+		config: {
+			source: options.static
+				? { type: "static" as const, path: options.path }
+				: {
+						type: "project" as const,
+						path: options.path,
+						command: options.command ?? "npx vite build",
+						output: options.output ?? "dist",
+					},
+			manifest: {
+				version: 1 as const,
+				...(slashCommand === undefined ? {} : { slashCommand }),
+				dataSources: options.dataSources ?? {},
+			},
+		},
+	};
+}

package/src/custom-blocks.ts

@@ -0,0 +1 @@
+export * from "@notionhq/custom-blocks";

package/src/manifest.ts

@@ -4,7 +4,7 @@ import type { NormalizedSchedule } from "./types.js";
 export const APPS_MANIFEST_SCHEMA = "notion:apps-manifest:v1" as const;
 
 /** Capability types supported by this SDK. */
-export type CapabilityType = "workflow" | "sync";
+export type CapabilityType = "workflow" | "sync" | "custom_block";
 
 export type DatabaseManifestConfig = {
 	initialTitle?: string;

package/src/nds.css

@@ -0,0 +1 @@
+@import "@notionhq/custom-blocks/nds.css";

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

@@ -1,11 +1,12 @@
 import type { Database } from "../database.js";
-import type {
-	DataSourceDefinition,
-	DatabaseIntent,
-	NotionAsCodeIcon,
-	NotionAsCodeProperty,
-	Parent,
-	ResourceId,
+import {
+	APPS_WORKSPACE_RESOURCE_ID,
+	type DataSourceDefinition,
+	type DatabaseIntent,
+	type NotionAsCodeIcon,
+	type NotionAsCodeProperty,
+	type Parent,
+	type ResourceId,
 } from "./intents.js";
 import { createPage, type ChildPageArgs, type PageHandle } from "./page.js";
 import { recordIntent } from "./recorder.js";
@@ -17,7 +18,8 @@ export type DatabaseArgs<
 	DataSources extends readonly DataSourceDefinition[] = readonly DataSourceDefinition[],
 > = {
 	resourceId: ResourceId;
-	parent: Parent;
+	/** Omit to create a private top-level database in the Apps workspace. */
+	parent?: Parent;
 	dataSources?: DataSources;
 	// TODO: Port view types.
 	views?: readonly unknown[];
@@ -69,13 +71,19 @@ export type DatabaseHandle<
 	addView: (view: unknown) => void;
 };
 
-/** Declare a top-level database and its data sources. */
+/** Declare a database, defaulting to a private top-level database in the Apps workspace. */
 export function database<const DataSources extends readonly DataSourceDefinition[]>(
 	args: DatabaseArgs<DataSources>,
 ): DatabaseHandle<DataSources>;
 export function database(args: DatabaseArgs): DatabaseHandle {
-	assertParent(args.parent);
-	return createDatabase(args, args.parent);
+	if (args.parent) {
+		assertParent(args.parent);
+	}
+	const parent = args.parent ?? {
+		type: "resourceId",
+		resourceId: APPS_WORKSPACE_RESOURCE_ID,
+	};
+	return createDatabase(args, parent);
 }
 
 /** Record a database declaration and create handles for each of its data sources. */

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

@@ -107,10 +107,11 @@ export type TeamspaceIntent = TeamspaceArgs & {
 };
 
 export type DatabaseIntent = DatabaseArgs & {
+	parent: Parent;
 	dataSources: readonly DataSourceDefinition[];
 };
 
-export type PageIntent = PageArgs;
+export type PageIntent = PageArgs & { parent: Parent };
 export type CustomAgentIntent = CustomAgentArgs;
 
 export type ViewIntent = {

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

@@ -1,9 +1,9 @@
-import type {
-	DataSourceDefinition,
-	NotionAsCodeIcon,
-	PageIntent,
-	Parent,
-	ResourceId,
+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 { recordIntent } from "./recorder.js";
@@ -11,8 +11,8 @@ import { assertParent, assertUserResourceId } from "./resource.js";
 
 export type PageArgs = {
 	resourceId: ResourceId;
-	parent: Parent;
-	icon?: NotionAsCodeIcon;
+	/** Omit to create a private top-level page in the Apps workspace. */
+	parent?: Parent;
 	// TODO: Port cover types.
 	cover?: unknown;
 	// TODO: Port page property types.
@@ -31,10 +31,16 @@ export type PageHandle = {
 	addPage: (args: ChildPageArgs) => PageHandle;
 };
 
-/** Declare a top-level page. */
+/** Declare a page, defaulting to a private top-level page in the Apps workspace. */
 export function page(args: PageArgs): PageHandle {
-	assertParent(args.parent);
-	return createPage(args, args.parent);
+	if (args.parent) {
+		assertParent(args.parent);
+	}
+	const parent = args.parent ?? {
+		type: "resourceId",
+		resourceId: APPS_WORKSPACE_RESOURCE_ID,
+	};
+	return createPage(args, parent);
 }
 
 /** Record a page declaration beneath its parent resource. */

package/src/react.ts

@@ -0,0 +1 @@
+export * from "@notionhq/custom-blocks/react";