@notionhq/custom-blocks 0.0.79 → 0.1.0

package/bin/cli/pullManifest.js

@@ -1,158 +0,0 @@
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { resolve as resolvePath } from "node:path";
-import { NOTION_BUILTIN_PROPERTY_IDS } from "../src/bridge/dataSources/propertySchema.js";
-import { extractId, formatUuid } from "./ids.js";
-import { loginHintCommand, ntnApi } from "./ntn.js";
-import { mergeTarget, readTarget, writeTarget } from "./target.js";
-const MANIFEST_FILENAME = "custom_blocks.json";
-const BUILTIN_TYPES = new Set(NOTION_BUILTIN_PROPERTY_IDS);
-// ── Helpers ───────────────────────────────────────────────────────
-function deriveKey(name) {
-    return name
-        .toLowerCase()
-        .replace(/\s+/g, "_")
-        .replace(/[^a-z0-9_]/g, "");
-}
-function plainText(items) {
-    if (!items?.length) {
-        return "Data source";
-    }
-    return items.map(t => t.plain_text ?? "").join("") || "Data source";
-}
-function is404(error) {
-    return error instanceof Error && error.message.includes("404");
-}
-// ── Schema transform ─────────────────────────────────────────────
-function transformProperties(props) {
-    const out = {};
-    for (const prop of Object.values(props)) {
-        if (BUILTIN_TYPES.has(prop.type)) {
-            continue;
-        }
-        const key = deriveKey(prop.name);
-        if (key) {
-            out[key] = { name: prop.name, type: prop.type };
-        }
-    }
-    return out;
-}
-function fetchDataSource(dataSourceId, quiet) {
-    const id = formatUuid(dataSourceId);
-    if (!quiet) {
-        console.log(`  Fetching data source ${id}…`);
-    }
-    const ds = ntnApi(`/v1/data_sources/${id}`);
-    if (!ds.properties || Object.keys(ds.properties).length === 0) {
-        throw new Error(`Data source ${id} has no properties.`);
-    }
-    return {
-        dataSourceId: id,
-        name: plainText(ds.title),
-        properties: transformProperties(ds.properties),
-    };
-}
-/**
- * Pull schema from a database or data source ID. Tries `/v1/databases/<id>`
- * first (most common entry point); falls back to `/v1/data_sources/<id>` if
- * that 404s. ID-type classification (block / view / database / wrong-workspace)
- * happens upstream in `init.ts` — by the time we get here, the ID is expected
- * to point at a database or data source.
- */
-function fetchSchema(id, quiet) {
-    const uuid = formatUuid(id);
-    let dbError;
-    try {
-        if (!quiet) {
-            console.log(`  Fetching database ${uuid}…`);
-        }
-        const db = ntnApi(`/v1/databases/${uuid}`);
-        if (db.object === "database") {
-            if (!db.data_sources?.length) {
-                throw new Error(`Database ${uuid} has no data sources. Confirm you're logged in to the right workspace with \`${loginHintCommand()}\`.`);
-            }
-            return fetchDataSource(db.data_sources[0].id, quiet);
-        }
-    }
-    catch (error) {
-        if (!is404(error)) {
-            throw error;
-        }
-        dbError = error;
-    }
-    try {
-        return fetchDataSource(uuid, quiet);
-    }
-    catch (error) {
-        if (!is404(error)) {
-            throw error;
-        }
-    }
-    throw new Error(dbError instanceof Error
-        ? `${uuid} isn't a database or data source. Confirm you're logged in to the right workspace with \`${loginHintCommand()}\`.`
-        : `${uuid} isn't a database or data source.`);
-}
-export function pullManifest(options) {
-    const { idOrUrl, key = "default", out = MANIFEST_FILENAME, dryRun = false, quiet = false, } = options;
-    const outPath = resolvePath(process.cwd(), out);
-    const id = extractId(idOrUrl);
-    if (quiet) {
-        console.log("\nPulling data source schema…");
-    }
-    else {
-        console.log(`\nResolving ${idOrUrl}…\n`);
-    }
-    const result = fetchSchema(id, quiet);
-    const entry = {
-        name: result.name,
-        properties: result.properties,
-    };
-    // Read existing manifest or start fresh. The entry for `key` is fully
-    // replaced so stale properties are automatically removed.
-    let manifest;
-    if (existsSync(outPath)) {
-        try {
-            const existing = JSON.parse(readFileSync(outPath, "utf-8"));
-            manifest = { version: 1, dataSources: existing.dataSources ?? {} };
-        }
-        catch {
-            manifest = { version: 1, dataSources: {} };
-        }
-    }
-    else {
-        manifest = { version: 1, dataSources: {} };
-    }
-    manifest.dataSources[key] = entry;
-    const json = JSON.stringify(manifest, null, "\t") + "\n";
-    if (dryRun) {
-        console.log(json);
-        return;
-    }
-    writeFileSync(outPath, json);
-    // Stash the resolved data-source ID in .notion/target.json so `connect`
-    // can wire the block without the user re-typing it. Don't touch block_id
-    // or property_ids_by_key — init seeds block_id at scaffold time, and
-    // `connect` fills in property_ids_by_key.
-    const existingTarget = readTarget();
-    const existingEntry = existingTarget?.data_sources[key];
-    const merged = mergeTarget(existingTarget, {
-        data_sources: {
-            [key]: {
-                data_source_id: result.dataSourceId,
-                property_ids_by_key: existingEntry?.property_ids_by_key ?? {},
-            },
-        },
-    });
-    writeTarget(merged);
-    const count = Object.keys(result.properties).length;
-    if (quiet) {
-        console.log(`Found database "${result.name}" (${count} properties)`);
-        return;
-    }
-    console.log(`\n✓ Updated ${out} (key: "${key}")\n`);
-    console.log(`  → recorded data_source_id in .notion/target.json (${key})`);
-    console.log(`  ${count} properties from "${result.name}":`);
-    for (const [k, p] of Object.entries(result.properties)) {
-        console.log(`    ${k}: ${p.name} (${p.type})`);
-    }
-    console.log("");
-}

package/bin/cli/target.js

@@ -1,95 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, resolve as resolvePath } from "node:path";
-export const TARGET_PATH = ".notion/target.json";
-function defaultTarget() {
-    return { env: "production", block_id: [], data_sources: {} };
-}
-export function resolveTargetPath(cwd = process.cwd()) {
-    return resolvePath(cwd, TARGET_PATH);
-}
-export function readTarget(cwd = process.cwd()) {
-    const path = resolveTargetPath(cwd);
-    if (!existsSync(path)) {
-        return null;
-    }
-    let raw;
-    try {
-        raw = readFileSync(path, "utf-8");
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(`Error: failed to read ${TARGET_PATH}: ${message}\n  Check file permissions.`);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        throw new Error(`Error: ${TARGET_PATH} contains invalid JSON.\n  Fix the syntax or delete the file to regenerate it with 'ncblock connect'.`);
-    }
-    return normalizeTarget(parsed);
-}
-export function writeTarget(config, cwd = process.cwd()) {
-    const path = resolveTargetPath(cwd);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(config, null, "\t") + "\n");
-}
-function normalizeTarget(value) {
-    if (!isRecord(value)) {
-        throw new Error(`Error: ${TARGET_PATH} must be a JSON object.\n  Delete the file to regenerate it with 'ncblock connect'.`);
-    }
-    const env = typeof value.env === "string" ? value.env : "production";
-    const block_id = [];
-    if (Array.isArray(value.block_id)) {
-        for (const entry of value.block_id) {
-            if (typeof entry === "string" && entry.length > 0) {
-                block_id.push(entry);
-            }
-        }
-    }
-    else if (typeof value.block_id === "string" && value.block_id.length > 0) {
-        block_id.push(value.block_id);
-    }
-    const data_sources = {};
-    if (isRecord(value.data_sources)) {
-        for (const [key, ds] of Object.entries(value.data_sources)) {
-            if (!isRecord(ds) || typeof ds.data_source_id !== "string") {
-                continue;
-            }
-            const property_ids_by_key = {};
-            if (isRecord(ds.property_ids_by_key)) {
-                for (const [k, v] of Object.entries(ds.property_ids_by_key)) {
-                    if (typeof v === "string") {
-                        property_ids_by_key[k] = v;
-                    }
-                }
-            }
-            data_sources[key] = {
-                data_source_id: ds.data_source_id,
-                property_ids_by_key,
-            };
-        }
-    }
-    return { env, block_id, data_sources };
-}
-/**
- * Merge a new partial target into the existing one. Block IDs from `incoming`
- * are appended (de-duplicated). Data source bindings replace any existing
- * binding for matching keys; unrelated keys are preserved.
- */
-export function mergeTarget(existing, incoming) {
-    const base = existing ?? defaultTarget();
-    const env = incoming.env ?? base.env;
-    const blockIds = new Set(base.block_id);
-    for (const id of incoming.block_id ?? []) {
-        blockIds.add(id);
-    }
-    const data_sources = {
-        ...base.data_sources,
-        ...(incoming.data_sources ?? {}),
-    };
-    return { env, block_id: [...blockIds], data_sources };
-}
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}

package/bin/src/bridge/dataSources/propertySchema.js

@@ -1,148 +0,0 @@
-import * as v from "valibot";
-/**
- * Hex-token identifiers for Notion's named colors. Mirrors the public API's
- * `select.options[].color` enum
- * (https://developers.notion.com/reference/property-object#select).
- */
-export const notionPropertyColorSchema = v.picklist([
-    "default",
-    "gray",
-    "brown",
-    "orange",
-    "yellow",
-    "green",
-    "blue",
-    "purple",
-    "pink",
-    "red",
-    "gray_background",
-    "brown_background",
-    "orange_background",
-    "yellow_background",
-    "green_background",
-    "blue_background",
-    "purple_background",
-    "pink_background",
-    "red_background",
-    "default_background",
-]);
-export const notionPropertyOptionSchema = v.object({
-    id: v.string(),
-    name: v.string(),
-    color: v.optional(notionPropertyColorSchema),
-    description: v.optional(v.string()),
-});
-export const notionStatusGroupSchema = v.object({
-    id: v.string(),
-    name: v.string(),
-    color: v.optional(notionPropertyColorSchema),
-    option_ids: v.array(v.string()),
-});
-export const notionDualPropertySchema = v.object({
-    synced_property_id: v.string(),
-    synced_property_name: v.string(),
-});
-const baseProp = v.object({
-    name: v.string(),
-    description: v.optional(v.string()),
-});
-/**
- * Every Notion property type the bridge speaks, in a single readable list.
- * Mirrors the Notion public API
- * [property object](https://developers.notion.com/reference/property-object)
- * type field. Internal-only types (`button`, `verification`,
- * `last_visited_time`, `location`) and the four built-ins (`created_time`,
- * `last_edited_time`, `created_by`, `last_edited_by`) are included under their
- * bridge-native names.
- */
-export const NOTION_PROPERTY_TYPES = [
-    "title",
-    "rich_text",
-    "number",
-    "checkbox",
-    "url",
-    "email",
-    "phone_number",
-    "select",
-    "multi_select",
-    "status",
-    "date",
-    "people",
-    "files",
-    "unique_id",
-    "relation",
-    "place",
-    "formula",
-    "rollup",
-    "button",
-    "verification",
-    "last_visited_time",
-    "location",
-    "created_time",
-    "last_edited_time",
-    "created_by",
-    "last_edited_by",
-];
-export const notionPropertyTypeSchema = v.picklist(NOTION_PROPERTY_TYPES);
-/**
- * Per-property schema as exposed by the host over the custom-block bridge.
- * The `type` discriminator must be one of {@link NOTION_PROPERTY_TYPES}.
- */
-export const notionPropertySchemaSchema = v.variant("type", [
-    v.object({ ...baseProp.entries, type: v.literal("title") }),
-    v.object({ ...baseProp.entries, type: v.literal("rich_text") }),
-    v.object({ ...baseProp.entries, type: v.literal("number") }),
-    v.object({ ...baseProp.entries, type: v.literal("checkbox") }),
-    v.object({ ...baseProp.entries, type: v.literal("url") }),
-    v.object({ ...baseProp.entries, type: v.literal("email") }),
-    v.object({ ...baseProp.entries, type: v.literal("phone_number") }),
-    v.object({
-        ...baseProp.entries,
-        type: v.literal("select"),
-        options: v.array(notionPropertyOptionSchema),
-    }),
-    v.object({
-        ...baseProp.entries,
-        type: v.literal("multi_select"),
-        options: v.array(notionPropertyOptionSchema),
-    }),
-    v.object({
-        ...baseProp.entries,
-        type: v.literal("status"),
-        options: v.array(notionPropertyOptionSchema),
-        groups: v.array(notionStatusGroupSchema),
-    }),
-    v.object({ ...baseProp.entries, type: v.literal("date") }),
-    v.object({ ...baseProp.entries, type: v.literal("people") }),
-    v.object({ ...baseProp.entries, type: v.literal("files") }),
-    v.object({ ...baseProp.entries, type: v.literal("unique_id") }),
-    v.object({
-        ...baseProp.entries,
-        type: v.literal("relation"),
-        data_source_id: v.optional(v.string()),
-        dual_property: v.optional(notionDualPropertySchema),
-    }),
-    v.object({ ...baseProp.entries, type: v.literal("place") }),
-    v.object({ ...baseProp.entries, type: v.literal("formula") }),
-    v.object({ ...baseProp.entries, type: v.literal("rollup") }),
-    // Internal-only types passed through under their bridge-native names.
-    v.object({ ...baseProp.entries, type: v.literal("button") }),
-    v.object({ ...baseProp.entries, type: v.literal("verification") }),
-    v.object({ ...baseProp.entries, type: v.literal("last_visited_time") }),
-    v.object({ ...baseProp.entries, type: v.literal("location") }),
-    // Synthetic built-ins. The host always emits one of each per data source.
-    v.object({ ...baseProp.entries, type: v.literal("created_time") }),
-    v.object({ ...baseProp.entries, type: v.literal("last_edited_time") }),
-    v.object({ ...baseProp.entries, type: v.literal("created_by") }),
-    v.object({ ...baseProp.entries, type: v.literal("last_edited_by") }),
-]);
-/**
- * The four synthetic built-in property IDs the host always includes in every
- * data source's `propertySchemasById` and every row's `propertiesById`.
- */
-export const NOTION_BUILTIN_PROPERTY_IDS = [
-    "created_time",
-    "last_edited_time",
-    "created_by",
-    "last_edited_by",
-];

package/bin/src/bridge/manifest.js

@@ -1,40 +0,0 @@
-import * as v from "valibot";
-import { notionPropertyTypeSchema } from "./dataSources/propertySchema.js";
-/**
- * User-authored manifest declaring the data sources the custom block expects.
- * Lives at `custom_blocks.json` in the project root. The sandbox may send it in
- * `connect`, and the host returns the authoritative manifest in `init`. The
- * `notionCustomBlock` Vite plugin from
- * `@notionhq/custom-blocks/vite` wires the JSON file into the dev server and
- * the build output.
- */
-/**
- * Decorative icon attached to a manifest data source. Mirrors the
- * `emoji` / `external` icon variants the public Notion API uses, so the host
- * can render a recognizable affordance next to the slot in setup UI.
- */
-export const manifestIconSchema = v.variant("type", [
-    v.object({
-        type: v.literal("emoji"),
-        emoji: v.string(),
-    }),
-    v.object({
-        type: v.literal("external"),
-        url: v.string(),
-    }),
-]);
-export const manifestPropertySchema = v.object({
-    name: v.string(),
-    description: v.optional(v.string()),
-    type: notionPropertyTypeSchema,
-});
-export const manifestDataSourceSchema = v.object({
-    name: v.string(),
-    description: v.optional(v.string()),
-    icon: v.optional(manifestIconSchema),
-    properties: v.optional(v.record(v.string(), manifestPropertySchema), {}),
-});
-export const manifestSchema = v.object({
-    version: v.literal(1),
-    dataSources: v.record(v.string(), manifestDataSourceSchema),
-});

package/docs/manifest.md

@@ -1,42 +0,0 @@
-# Manifest
-
-A custom block declares its required data sources in `custom_blocks.json` at the project root. Notion uses the manifest to know what semantic keys the block expects, what shape each property should be, and what to show when an admin is configuring the block.
-
-```json
-{
-  "version": 1,
-  "dataSources": {
-    "tasks": {
-      "name": "Tasks",
-      "description": "The collection of tasks to render",
-      "properties": {
-        "title": { "name": "Title", "type": "title" },
-        "dueDate": { "name": "Due date", "type": "date" }
-      }
-    }
-  }
-}
-```
-
-`initCustomBlock()` fetches the manifest and forwards it with `connect`. The `notionCustomBlock()` Vite plugin from `@notionhq/custom-blocks/vite` serves it in dev and emits it into `dist/` on build. If the file is missing, the SDK omits `manifest` from `connect`. If the file is unavailable for another reason or invalid, the SDK sends `connect` with `status: "error"` and an `error` payload. The host returns its authoritative manifest in `init`. The SDK uses that manifest even when it differs from the manifest sent in `connect`.
-
-## Vite plugin
-
-```ts
-import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
-import { notionCustomBlock } from "@notionhq/custom-blocks/vite";
-
-export default defineConfig({
-  plugins: [react(), notionCustomBlock()],
-});
-```
-
-In dev, the plugin serves `custom_blocks.json` from the project root so HMR + the SDK handshake see the same file. On `vite build`, it emits `custom_blocks.json` into `dist/` as a separate asset alongside the bundled HTML and JS.
-
-## Types
-
-- `CustomBlockManifest` — the parsed shape of `custom_blocks.json`.
-- `ManifestDataSource` — a single entry in `dataSources` (name, description, properties).
-- `ManifestProperty` — a single property declaration inside a `ManifestDataSource`.
-- `ManifestIcon` — the icon variant accepted on a `ManifestDataSource`.