@notionhq/workers 0.7.0 → 0.8.0

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

@@ -0,0 +1,124 @@
+/**
+ * Icon for a custom block data source. Mirrors the server/client
+ * `CustomBlockManifestIcon` (`@notionhq/shared/customViews/customBlockManifestTypes`).
+ */
+export type CustomBlockManifestIcon = {
+    type: "emoji";
+    emoji: string;
+} | {
+    type: "external";
+    url: string;
+};
+/**
+ * Public-API-shaped property type names usable in a custom block manifest.
+ */
+export type CustomBlockManifestPropertyType = "title" | "rich_text" | "number" | "select" | "multi_select" | "status" | "date" | "people" | "files" | "checkbox" | "url" | "email" | "phone_number" | "formula" | "relation" | "rollup" | "created_time" | "created_by" | "last_edited_time" | "last_edited_by" | "last_visited_time" | "button" | "unique_id" | "location" | "verification" | "place";
+/**
+ * Describes a single property exposed by a custom block data source.
+ */
+export type CustomBlockManifestProperty = {
+    name: string;
+    description?: string;
+    type: CustomBlockManifestPropertyType;
+};
+/**
+ * Rich schema describing one of a custom block's data sources.
+ */
+export type CustomBlockManifestDataSource = {
+    /** Display name for the data source. */
+    name: string;
+    /** Optional human-readable description of the data source. */
+    description?: string;
+    /** Optional icon for the data source. */
+    icon?: CustomBlockManifestIcon;
+    /** Optional property schema keyed by property key. */
+    properties?: Record<string, CustomBlockManifestProperty>;
+};
+export type CustomBlockManifest = {
+    version: 1;
+    /**
+     * The block's datasources schema, mapping keys you name to {@link CustomBlockManifestDataSource}
+     *
+     * @example
+     *
+     * {
+     *   "myDataSource": {
+     *     "name": "My Data Source",
+     *     "description": "A description of my data source",
+     *     "icon": "icon.png",
+     *     "properties": {
+     *       "property1": {
+     *         "name": "Property 1",
+     *         "type": "string"
+     *       }
+     *     }
+     *   }
+     * }
+     */
+    dataSources: Record<string, CustomBlockManifestDataSource>;
+};
+/**
+ * A custom block is a front-end web app served in an iframe in the client with live data access.
+ *
+ * Available `type`s are `project` (a buildable project dir) and `static` (an already-built dir served as-is).
+ */
+export type CustomBlockConfiguration = ({
+    /** Buildable project dir (the default). */
+    type?: "project";
+    /** Path to the project dir, relative to the worker root (e.g. `"./blocks/foo"`). */
+    path: string;
+    /** Build command run in `path`. Defaults to `npm run build`. */
+    command?: string;
+    /** Built-output dir relative to `path`. Defaults to `dist`. */
+    output?: string;
+} | {
+    /** An already-built browser-bundle dir; served as-is, no build step. */
+    type: "static";
+    /** Path to the prebuilt dir, relative to the worker root. */
+    path: string;
+    command?: never;
+    output?: never;
+}) & Partial<CustomBlockManifest>;
+/**
+ * The build source of a custom block, mirroring the server's
+ * `BlockSourceDeclaration`. `project` is a buildable dir (`command` defaults to
+ * `npm run build`, `output` to `dist`); `static` is an already-built dir served
+ * as-is.
+ */
+export type BlockSourceDeclaration = {
+    type: "project";
+    path: string;
+    command?: string;
+    output?: string;
+} | {
+    type: "static";
+    path: string;
+};
+/**
+ * Config payload carried in the runtime manifest for a `_tag: "custom_block"`
+ * capability entry. The server parses this (see `RawBlockCapabilityConfig` in
+ * `capabilities-service.ts`): `source` is the build entry and `manifest` is the
+ * author-declared {@link CustomBlockManifest} describing the block's data-source
+ * schema. Data-source *bindings* are instance-level and are not carried here.
+ */
+export type CustomBlockCapabilityConfig = {
+    source: BlockSourceDeclaration;
+    manifest: CustomBlockManifest;
+};
+/**
+ * A custom-block capability entry. Unlike other capabilities it has no runtime
+ * handler — it is a build-time/deploy-time declaration only, carried through
+ * the manifest so the server can build and bind the block on deploy.
+ */
+export type CustomBlockCapability = {
+    readonly _tag: "custom_block";
+    readonly key: string;
+    readonly config: CustomBlockCapabilityConfig;
+};
+/**
+ * Builds a custom-block capability entry from its authoring configuration. The
+ * author-declared `dataSources` schema is carried verbatim into the block
+ * {@link CustomBlockManifest}; no bindings are emitted.
+ */
+export declare function createCustomBlockCapability(key: string, config: CustomBlockConfiguration): CustomBlockCapability;
+//# sourceMappingURL=custom-block.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"custom-block.d.ts","sourceRoot":"","sources":["../../src/capabilities/custom-block.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAChC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;GAEG;AACH,MAAM,MAAM,+BAA+B,GACxC,OAAO,GACP,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,cAAc,GACd,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,OAAO,GACP,UAAU,GACV,KAAK,GACL,OAAO,GACP,cAAc,GACd,SAAS,GACT,UAAU,GACV,QAAQ,GACR,cAAc,GACd,YAAY,GACZ,kBAAkB,GAClB,gBAAgB,GAChB,mBAAmB,GACnB,QAAQ,GACR,WAAW,GACX,UAAU,GACV,cAAc,GACd,OAAO,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,+BAA+B,CAAC;CACtC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,6BAA6B,GAAG;IAC3C,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,IAAI,CAAC,EAAE,uBAAuB,CAAC;IAC/B,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;CACzD,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IACjC,OAAO,EAAE,CAAC,CAAC;IACX;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,6BAA6B,CAAC,CAAC;CAC3D,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACpC;IACA,2CAA2C;IAC3C,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,oFAAoF;IACpF,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACf,GACD;IACA,wEAAwE;IACxE,IAAI,EAAE,QAAQ,CAAC;IACf,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,KAAK,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,CAAC;CACd,CACH,GACA,OAAO,CAAC,mBAAmB,CAAC,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAC/B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,MAAM,2BAA2B,GAAG;IACzC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,EAAE,mBAAmB,CAAC;CAC9B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;CAC7C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,2BAA2B,CAC1C,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,wBAAwB,GAC9B,qBAAqB,CAsBvB"}

package/dist/capabilities/custom-block.js

@@ -0,0 +1,22 @@
+function createCustomBlockCapability(key, config) {
+  const source = config.type === "static" ? { type: "static", path: config.path } : {
+    type: "project",
+    path: config.path,
+    ...config.command !== void 0 ? { command: config.command } : {},
+    ...config.output !== void 0 ? { output: config.output } : {}
+  };
+  return {
+    _tag: "custom_block",
+    key,
+    config: {
+      source,
+      manifest: {
+        version: config.version ?? 1,
+        dataSources: config.dataSources ?? {}
+      }
+    }
+  };
+}
+export {
+  createCustomBlockCapability
+};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export type { CustomBlockCapability, CustomBlockCapabilityConfig, CustomBlockConfiguration, CustomBlockManifest, CustomBlockManifestDataSource, } from "./capabilities/custom-block.js";
 export { emojiIcon, imageCover, imageIcon, notionIcon, place } from "./builder.js";
 export type { AiConnectorArchetype, AiConnectorCapability, AiConnectorChange, AiConnectorChangeUpsert, AiConnectorChatAuthor, AiConnectorChatChannel, AiConnectorChatMessage, AiConnectorChatRecord, AiConnectorConfiguration, AiConnectorExecutionResult, AiConnectorMode, AiConnectorProjectBlock, AiConnectorProjectRecord, AiConnectorRecordByArchetype, } from "./capabilities/ai_connector.js";
 export type { AutomationCapability, AutomationConfiguration, AutomationEvent, PageObjectResponse, } from "./capabilities/automation.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACnF,YAAY,EACX,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,eAAe,EACf,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,GAC5B,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACX,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,YAAY,EACX,+BAA+B,EAC/B,eAAe,EACf,kBAAkB,EAClB,6BAA6B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,QAAQ,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAC3F,YAAY,EACX,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,GACZ,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EACX,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,EACb,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACX,KAAK,EACL,IAAI,EACJ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AACpB,YAAY,EACX,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,cAAc,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACX,qBAAqB,EACrB,2BAA2B,EAC3B,wBAAwB,EACxB,mBAAmB,EACnB,6BAA6B,GAC7B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACnF,YAAY,EACX,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC1B,eAAe,EACf,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,GAC5B,MAAM,gCAAgC,CAAC;AACxC,YAAY,EACX,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,EACf,kBAAkB,GAClB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,YAAY,EACX,+BAA+B,EAC/B,eAAe,EACf,kBAAkB,EAClB,6BAA6B,GAC7B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,QAAQ,GACR,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAC3F,YAAY,EACX,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,GACZ,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,YAAY,EACX,kBAAkB,EAClB,qBAAqB,EACrB,aAAa,EACb,uBAAuB,EACvB,wBAAwB,GACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAClE,YAAY,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACX,KAAK,EACL,IAAI,EACJ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,GACR,MAAM,YAAY,CAAC;AACpB,YAAY,EACX,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,cAAc,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/worker.d.ts

@@ -1,6 +1,7 @@
 import type { AiConnectorArchetype, AiConnectorCapability, AiConnectorConfiguration } from "./capabilities/ai_connector.js";
 import type { AutomationCapability, AutomationConfiguration, AutomationEvent } from "./capabilities/automation.js";
 import type { CapabilityContext } from "./capabilities/context.js";
+import type { CustomBlockCapability, CustomBlockConfiguration } from "./capabilities/custom-block.js";
 import type { NotionManagedOAuthConfiguration, OAuthCapability, OAuthConfiguration, UserManagedOAuthConfiguration } from "./capabilities/oauth.js";
 import type { SyncCapability, SyncConfiguration } from "./capabilities/sync.js";
 import type { ToolCapability, ToolConfiguration } from "./capabilities/tool.js";
@@ -13,7 +14,7 @@ import type { WorkflowTrigger } from "./triggers.generated.js";
 import type { HandlerOptions, JSONValue } from "./types.js";
 export type { AiConnectorConfiguration, AutomationConfiguration, AutomationEvent, CapabilityContext, NotionManagedOAuthConfiguration, OAuthConfiguration, SyncConfiguration, ToolConfiguration, UserManagedOAuthConfiguration, WebhookConfiguration, WebhookEvent, WorkflowConfiguration, WorkflowEvent, };
 export { WebhookVerificationError };
-type Capability = SyncCapability | AiConnectorCapability | ToolCapability<any, any> | AutomationCapability | WorkflowCapability | OAuthCapability | WebhookCapability;
+type Capability = SyncCapability | AiConnectorCapability | ToolCapability<any, any> | AutomationCapability | WorkflowCapability | OAuthCapability | WebhookCapability | CustomBlockCapability;
 export type CapabilityType = Capability["_tag"];
 /**
  * Configuration for a database that Notion creates and manages on behalf
@@ -400,6 +401,45 @@ export declare class Worker {
      * @returns The registered OAuth capability.
      */
     oauth(key: string, config: OAuthConfiguration): OAuthCapability;
+    /**
+     * Register a custom block capability.
+     *
+     * A custom block is a front-end view that the deploy pipeline builds from
+     * the source entry into a deployable bundle. It can optionally declare a
+     * data-source *schema* (`name`, and optional `description`, `icon`, and
+     * `properties`) that the block reads.
+     *
+     * Example:
+     *
+     * ```ts
+     * const worker = new Worker();
+     * export default worker;
+     *
+     * worker.customBlock("issueBoard", {
+     *   version: 1,
+     *   path: "./views/issueBoard",
+     *   dataSources: {
+     *     issues: {
+     *       name: "Issues",
+     *       properties: {
+     *         title: { name: "Title", type: "title" },
+     *         status: { name: "Status", type: "status" },
+     *       },
+     *     },
+     *   },
+     * });
+     * ```
+     *
+     * The manifest keys (`version`, `dataSources`) are top-level on the config;
+     * the SDK assembles the deploy-wire `CustomBlockManifest` from them. Binding
+     * each declared data source to a concrete managed database is instance-level
+     * and handled at deploy time — the worker does not emit bindings.
+     *
+     * @param key - The unique key for this block (the block declaration key).
+     * @param config - The custom block configuration (a `project`/`static` source folder + optional `version`/`dataSources` schema).
+     * @returns The custom block capability.
+     */
+    customBlock(key: string, config: CustomBlockConfiguration): CustomBlockCapability;
     /**
      * Get all registered capabilities (for discovery) without their handlers.
      */

package/dist/worker.d.ts.map

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

package/dist/worker.js

@@ -1,5 +1,6 @@
 import { createAiConnectorCapability } from "./capabilities/ai_connector.js";
 import { createAutomationCapability } from "./capabilities/automation.js";
+import { createCustomBlockCapability } from "./capabilities/custom-block.js";
 import { createOAuthCapability } from "./capabilities/oauth.js";
 import { createSyncCapability } from "./capabilities/sync.js";
 import { createToolCapability } from "./capabilities/tool.js";
@@ -365,6 +366,50 @@ class Worker {
     this.#capabilities.set(key, capability);
     return capability;
   }
+  /**
+   * Register a custom block capability.
+   *
+   * A custom block is a front-end view that the deploy pipeline builds from
+   * the source entry into a deployable bundle. It can optionally declare a
+   * data-source *schema* (`name`, and optional `description`, `icon`, and
+   * `properties`) that the block reads.
+   *
+   * Example:
+   *
+   * ```ts
+   * const worker = new Worker();
+   * export default worker;
+   *
+   * worker.customBlock("issueBoard", {
+   *   version: 1,
+   *   path: "./views/issueBoard",
+   *   dataSources: {
+   *     issues: {
+   *       name: "Issues",
+   *       properties: {
+   *         title: { name: "Title", type: "title" },
+   *         status: { name: "Status", type: "status" },
+   *       },
+   *     },
+   *   },
+   * });
+   * ```
+   *
+   * The manifest keys (`version`, `dataSources`) are top-level on the config;
+   * the SDK assembles the deploy-wire `CustomBlockManifest` from them. Binding
+   * each declared data source to a concrete managed database is instance-level
+   * and handled at deploy time — the worker does not emit bindings.
+   *
+   * @param key - The unique key for this block (the block declaration key).
+   * @param config - The custom block configuration (a `project`/`static` source folder + optional `version`/`dataSources` schema).
+   * @returns The custom block capability.
+   */
+  customBlock(key, config) {
+    this.#validateUniqueKey(key);
+    const capability = createCustomBlockCapability(key, config);
+    this.#capabilities.set(key, capability);
+    return capability;
+  }
   /**
    * Get all registered capabilities (for discovery) without their handlers.
    */
@@ -401,6 +446,11 @@ class Worker {
         `Cannot run OAuth capability "${key}" - OAuth capabilities only provide configuration`
       );
     }
+    if (capability._tag === "custom_block") {
+      throw new Error(
+        `Cannot run custom block capability "${key}" - custom blocks only provide configuration`
+      );
+    }
     if (!capability.handler) {
       throw new Error(`Capability "${key}" cannot be executed`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/workers",
-	"version": "0.7.0",
+	"version": "0.8.0",
 	"description": "An SDK for building workers for the Notion Workers platform",
 	"license": "MIT",
 	"bin": {

package/src/capabilities/custom-block.ts

@@ -0,0 +1,181 @@
+// ============================================================================
+// Custom Block Authoring API
+// ============================================================================
+
+/**
+ * Icon for a custom block data source. Mirrors the server/client
+ * `CustomBlockManifestIcon` (`@notionhq/shared/customViews/customBlockManifestTypes`).
+ */
+export type CustomBlockManifestIcon =
+	| { type: "emoji"; emoji: string }
+	| { type: "external"; url: string };
+
+/**
+ * Public-API-shaped property type names usable in a custom block manifest.
+ */
+export type CustomBlockManifestPropertyType =
+	| "title"
+	| "rich_text"
+	| "number"
+	| "select"
+	| "multi_select"
+	| "status"
+	| "date"
+	| "people"
+	| "files"
+	| "checkbox"
+	| "url"
+	| "email"
+	| "phone_number"
+	| "formula"
+	| "relation"
+	| "rollup"
+	| "created_time"
+	| "created_by"
+	| "last_edited_time"
+	| "last_edited_by"
+	| "last_visited_time"
+	| "button"
+	| "unique_id"
+	| "location"
+	| "verification"
+	| "place";
+
+/**
+ * Describes a single property exposed by a custom block data source.
+ */
+export type CustomBlockManifestProperty = {
+	name: string;
+	description?: string;
+	type: CustomBlockManifestPropertyType;
+};
+
+/**
+ * Rich schema describing one of a custom block's data sources.
+ */
+export type CustomBlockManifestDataSource = {
+	/** Display name for the data source. */
+	name: string;
+	/** Optional human-readable description of the data source. */
+	description?: string;
+	/** Optional icon for the data source. */
+	icon?: CustomBlockManifestIcon;
+	/** Optional property schema keyed by property key. */
+	properties?: Record<string, CustomBlockManifestProperty>;
+};
+
+export type CustomBlockManifest = {
+	version: 1;
+	/**
+	 * The block's datasources schema, mapping keys you name to {@link CustomBlockManifestDataSource}
+	 *
+	 * @example
+	 *
+	 * {
+	 *   "myDataSource": {
+	 *     "name": "My Data Source",
+	 *     "description": "A description of my data source",
+	 *     "icon": "icon.png",
+	 *     "properties": {
+	 *       "property1": {
+	 *         "name": "Property 1",
+	 *         "type": "string"
+	 *       }
+	 *     }
+	 *   }
+	 * }
+	 */
+	dataSources: Record<string, CustomBlockManifestDataSource>;
+};
+
+/**
+ * A custom block is a front-end web app served in an iframe in the client with live data access.
+ *
+ * Available `type`s are `project` (a buildable project dir) and `static` (an already-built dir served as-is).
+ */
+export type CustomBlockConfiguration = (
+	| {
+			/** Buildable project dir (the default). */
+			type?: "project";
+			/** Path to the project dir, relative to the worker root (e.g. `"./blocks/foo"`). */
+			path: string;
+			/** Build command run in `path`. Defaults to `npm run build`. */
+			command?: string;
+			/** Built-output dir relative to `path`. Defaults to `dist`. */
+			output?: string;
+	  }
+	| {
+			/** An already-built browser-bundle dir; served as-is, no build step. */
+			type: "static";
+			/** Path to the prebuilt dir, relative to the worker root. */
+			path: string;
+			command?: never;
+			output?: never;
+	  }
+) &
+	Partial<CustomBlockManifest>;
+
+/**
+ * The build source of a custom block, mirroring the server's
+ * `BlockSourceDeclaration`. `project` is a buildable dir (`command` defaults to
+ * `npm run build`, `output` to `dist`); `static` is an already-built dir served
+ * as-is.
+ */
+export type BlockSourceDeclaration =
+	| { type: "project"; path: string; command?: string; output?: string }
+	| { type: "static"; path: string };
+
+/**
+ * Config payload carried in the runtime manifest for a `_tag: "custom_block"`
+ * capability entry. The server parses this (see `RawBlockCapabilityConfig` in
+ * `capabilities-service.ts`): `source` is the build entry and `manifest` is the
+ * author-declared {@link CustomBlockManifest} describing the block's data-source
+ * schema. Data-source *bindings* are instance-level and are not carried here.
+ */
+export type CustomBlockCapabilityConfig = {
+	source: BlockSourceDeclaration;
+	manifest: CustomBlockManifest;
+};
+
+/**
+ * A custom-block capability entry. Unlike other capabilities it has no runtime
+ * handler — it is a build-time/deploy-time declaration only, carried through
+ * the manifest so the server can build and bind the block on deploy.
+ */
+export type CustomBlockCapability = {
+	readonly _tag: "custom_block";
+	readonly key: string;
+	readonly config: CustomBlockCapabilityConfig;
+};
+
+/**
+ * Builds a custom-block capability entry from its authoring configuration. The
+ * author-declared `dataSources` schema is carried verbatim into the block
+ * {@link CustomBlockManifest}; no bindings are emitted.
+ */
+export function createCustomBlockCapability(
+	key: string,
+	config: CustomBlockConfiguration,
+): CustomBlockCapability {
+	const source: BlockSourceDeclaration =
+		config.type === "static"
+			? { type: "static", path: config.path }
+			: {
+					type: "project",
+					path: config.path,
+					...(config.command !== undefined ? { command: config.command } : {}),
+					...(config.output !== undefined ? { output: config.output } : {}),
+				};
+
+	return {
+		_tag: "custom_block",
+		key,
+		config: {
+			source,
+			manifest: {
+				version: config.version ?? 1,
+				dataSources: config.dataSources ?? {},
+			},
+		},
+	};
+}

package/src/index.ts

@@ -1,3 +1,10 @@
+export type {
+	CustomBlockCapability,
+	CustomBlockCapabilityConfig,
+	CustomBlockConfiguration,
+	CustomBlockManifest,
+	CustomBlockManifestDataSource,
+} from "./capabilities/custom-block.js";
 export { emojiIcon, imageCover, imageIcon, notionIcon, place } from "./builder.js";
 export type {
 	AiConnectorArchetype,

package/src/worker.test.ts

@@ -141,6 +141,153 @@ describe("Worker", () => {
 		]);
 	});
 
+	it("registers a project custom block from a folder path (type defaults to project)", () => {
+		const worker = new Worker();
+
+		worker.customBlock("visualBlock", {
+			path: "./views/visual",
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "visualBlock",
+				config: {
+					source: { type: "project", path: "./views/visual" },
+					manifest: {
+						version: 1,
+						dataSources: {},
+					},
+				},
+			},
+		]);
+	});
+
+	it("carries a project's custom build command and output dir", () => {
+		const worker = new Worker();
+
+		worker.customBlock("built", {
+			path: "./app",
+			command: "npm run build-prod",
+			output: "build",
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "built",
+				config: {
+					source: {
+						type: "project",
+						path: "./app",
+						command: "npm run build-prod",
+						output: "build",
+					},
+					manifest: { version: 1, dataSources: {} },
+				},
+			},
+		]);
+	});
+
+	it("registers a static custom block served as-is", () => {
+		const worker = new Worker();
+
+		worker.customBlock("prebuilt", { type: "static", path: "./dist" });
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "prebuilt",
+				config: {
+					source: { type: "static", path: "./dist" },
+					manifest: { version: 1, dataSources: {} },
+				},
+			},
+		]);
+	});
+
+	it("carries the author-declared data-source schema verbatim into the manifest", () => {
+		const worker = new Worker();
+
+		worker.customBlock("issueBoard", {
+			path: "./views/issueBoard",
+			dataSources: {
+				issues: {
+					name: "Issues",
+					description: "The team's issues",
+					icon: { type: "emoji", emoji: "🐛" },
+					properties: {
+						title: { name: "Title", type: "title" },
+						status: {
+							name: "Status",
+							description: "Workflow state",
+							type: "status",
+						},
+					},
+				},
+			},
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "issueBoard",
+				config: {
+					source: { type: "project", path: "./views/issueBoard" },
+					manifest: {
+						version: 1,
+						dataSources: {
+							issues: {
+								name: "Issues",
+								description: "The team's issues",
+								icon: { type: "emoji", emoji: "🐛" },
+								properties: {
+									title: { name: "Title", type: "title" },
+									status: {
+										name: "Status",
+										description: "Workflow state",
+										type: "status",
+									},
+								},
+							},
+						},
+					},
+				},
+			},
+		]);
+	});
+
+	it("threads a top-level manifest version into the generated manifest", () => {
+		const worker = new Worker();
+
+		worker.customBlock("versioned", {
+			path: "./views/versioned",
+			version: 1,
+		});
+
+		expect(worker.manifest.capabilities).toEqual([
+			{
+				_tag: "custom_block",
+				key: "versioned",
+				config: {
+					source: { type: "project", path: "./views/versioned" },
+					manifest: { version: 1, dataSources: {} },
+				},
+			},
+		]);
+	});
+
+	it("cannot run a custom block capability", async () => {
+		const worker = new Worker();
+		worker.customBlock("visualBlock", {
+			path: "./views/visual",
+		});
+
+		await expect(worker.run("visualBlock", {})).rejects.toThrow(
+			'Cannot run custom block capability "visualBlock"',
+		);
+	});
+
 	it("rejects duplicate keys across databases, pacers, and capabilities", () => {
 		const worker = new Worker();
 		const db = worker.database("shared-key", {