@notionhq/custom-blocks 0.1.36 → 0.1.38

package/README.md

@@ -7,6 +7,11 @@ SDK for building Notion custom blocks.
 
 A custom block runs as a sandboxed `<iframe>` inside the Notion app that has no direct access to the internet. The only channel between your block and Notion is a local `postMessage` bridge. This library implements the sandbox side of the bridge protocol and wraps it in a framework-neutral TypeScript API (`@notionhq/custom-blocks`) and typed React hooks (`@notionhq/custom-blocks/react`).
 
+## Bundle tooling
+
+Node build tools can import `build` and `upload` from
+`@notionhq/custom-blocks/bundle`. See [deployment tooling](./docs/deployment.md#apps-sdk-integration).
+
 ## Install
 
 Create a worker project with `ntn workers new --template custom` and use the dependencies and

package/bin/notion-custom-blocks/build.d.ts

@@ -0,0 +1,23 @@
+export type BuiltBlock = {
+    key: string;
+    checksumCrc32: string;
+    bundleDir: string;
+    bundleSizeBytes: number;
+};
+export type BuildOutput = {
+    blocks: BuiltBlock[];
+};
+export type BuildArgs = {
+    out: string;
+    cwd?: string | undefined;
+    manifest?: string | undefined;
+};
+/**
+ * Build every `_tag: "custom_block"` view declared by the worker.
+ *
+ * Imports the worker bundle (`<cwd>/dist/index.js`), reads its runtime manifest,
+ * and runs the command specified (default `npm run build`)
+ */
+export declare function buildCustomBlocks(args: BuildArgs): Promise<BuildOutput>;
+/** Print the build output as the sentinel-wrapped single-line JSON contract. */
+export declare function printBuildOutput(output: BuildOutput): void;

package/bin/notion-custom-blocks/build.js

@@ -15,8 +15,10 @@ const WORKER_ENTRY = "dist/index.js";
 export async function buildCustomBlocks(args) {
     const projectRoot = args.cwd ?? process.cwd();
     const entryPath = path.resolve(projectRoot, WORKER_ENTRY);
-    const outDir = path.resolve(args.out);
-    const blocks = await readCustomBlocks(entryPath);
+    const outDir = path.resolve(projectRoot, args.out);
+    const blocks = args.manifest === undefined
+        ? await readCustomBlocks(entryPath)
+        : readAppBlocks(path.resolve(projectRoot, args.manifest));
     if (blocks.length === 0) {
         return { blocks: [] };
     }
@@ -24,8 +26,13 @@ export async function buildCustomBlocks(args) {
     for (const block of blocks) {
         const bundleDir = path.join(outDir, block.key);
         buildCustomBlock({ block, projectRoot, bundleDir });
-        const { checksumCrc32 } = packDirToTarGz(bundleDir);
-        built.push({ key: block.key, checksumCrc32, bundleDir });
+        const { checksumCrc32, tarGz } = packDirToTarGz(bundleDir);
+        built.push({
+            key: block.key,
+            checksumCrc32,
+            bundleDir,
+            bundleSizeBytes: tarGz.length,
+        });
     }
     return { blocks: built };
 }
@@ -185,3 +192,18 @@ function runCommand(key, command, cwd) {
         throw new Error(`custom_block "${key}" build command "${command}" exited with code ${String(result.status)}`);
     }
 }
+/** Read Apps SDK capabilities while retaining the worker manifest config contract. */
+function readAppBlocks(manifestPath) {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    const capabilities = readProp(manifest, "capabilities");
+    if (!Array.isArray(capabilities)) {
+        throw new Error(`manifest at ${manifestPath} has no capabilities array`);
+    }
+    return capabilities.flatMap(capability => {
+        const block = asCustomBlock({
+            ...capability,
+            _tag: readProp(capability, "type") ?? readProp(capability, "_tag"),
+        });
+        return block ? [block] : [];
+    });
+}

package/bin/notion-custom-blocks/bundle.d.ts

@@ -0,0 +1,4 @@
+export type { BuildArgs, BuildOutput, BuiltBlock } from "./build.js";
+export { buildCustomBlocks as build, printBuildOutput } from "./build.js";
+export type { UploadOutput, UploadsInput, UploadTarget } from "./upload.js";
+export { parseUploadsInput, uploadViews as upload } from "./upload.js";

package/bin/notion-custom-blocks/bundle.js

@@ -0,0 +1,2 @@
+export { buildCustomBlocks as build, printBuildOutput } from "./build.js";
+export { parseUploadsInput, uploadViews as upload } from "./upload.js";

package/bin/notion-custom-blocks/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Custom block deployment CLI invoked by Notion's worker build sandbox.
+ *
+ * It ships with the SDK so worker projects expose the executable expected by
+ * the deployment pipeline at `node_modules/.bin/notion-custom-blocks`.
+ */
+export declare function main(argv: string[]): Promise<number>;

package/bin/notion-custom-blocks/cli.js

@@ -26,7 +26,8 @@ async function runBuild(args) {
         process.stderr.write("usage: notion-custom-blocks build --out <dir>\n");
         return 1;
     }
-    const output = await buildCustomBlocks({ out });
+    const { manifest, cwd } = flags;
+    const output = await buildCustomBlocks({ out, manifest, cwd });
     printBuildOutput(output);
     return 0;
 }

package/bin/notion-custom-blocks/tar.d.ts

@@ -0,0 +1,11 @@
+type PackedTarGz = {
+    tarGz: Buffer;
+    checksumCrc32: string;
+};
+/**
+ * Pack a directory into a deterministic gzipped tarball and return both the
+ * bytes and their base64 big-endian crc32 checksum (the form
+ * `CreateCustomBlockDeploy` signs into the presigned PUT URL).
+ */
+export declare function packDirToTarGz(dir: string): PackedTarGz;
+export {};

package/bin/notion-custom-blocks/upload.d.ts

@@ -0,0 +1,14 @@
+export type UploadTarget = {
+    uploadUrl: string;
+    bundleDir: string;
+    headers?: Record<string, string>;
+};
+export type UploadsInput = Record<string, UploadTarget>;
+export type UploadOutput = {
+    uploaded: Record<string, true>;
+};
+export type UploadDeps = {
+    fetch: typeof fetch;
+};
+export declare function uploadViews(uploads: UploadsInput, deps?: UploadDeps): Promise<UploadOutput>;
+export declare function parseUploadsInput(raw: string): UploadsInput;

package/bin/notion-custom-blocks/upload.js

@@ -7,6 +7,7 @@ export async function uploadViews(uploads, deps = DEFAULT_DEPS) {
         const response = await deps.fetch(target.uploadUrl, {
             method: "PUT",
             headers: {
+                ...target.headers,
                 "Content-Type": "application/gzip",
                 "x-amz-checksum-crc32": checksumCrc32,
             },
@@ -46,10 +47,23 @@ export function parseUploadsInput(raw) {
         result[key] = {
             uploadUrl: record.uploadUrl,
             bundleDir: record.bundleDir,
+            headers: parseHeaders(record.headers, key),
         };
     }
     return result;
 }
+function parseHeaders(value, key) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.values(value).some(header => typeof header !== "string")) {
+        throw new Error(`--uploads["${key}"].headers must be an object of string values`);
+    }
+    return value;
+}
 async function safeReadText(response) {
     try {
         const text = await response.text();

package/bin/notion-custom-blocks/upload.test.d.ts

@@ -0,0 +1 @@
+export {};

package/bin/notion-custom-blocks/upload.test.js

@@ -0,0 +1,38 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import { parseUploadsInput } from "./upload.js";
+describe("parseUploadsInput", () => {
+    it("preserves signed headers and supports targets without headers", () => {
+        const targets = {
+            hello: {
+                uploadUrl: "https://example.com/bundle?signature=a%2Bb",
+                bundleDir: "/tmp/block",
+                headers: { "Content-Length": "42", "x-amz-tagging": "source=cli" },
+            },
+            legacy: {
+                uploadUrl: "https://example.com/legacy",
+                bundleDir: "/tmp/legacy",
+            },
+        };
+        expect(parseUploadsInput(JSON.stringify(targets))).toEqual(targets);
+    });
+    it.each([
+        "broken",
+        "null",
+        "[]",
+        "42",
+        '{"hello":null}',
+        '{"hello":{"bundleDir":"x"}}',
+        '{"hello":{"uploadUrl":"x"}}',
+    ])("rejects malformed target input %s", raw => {
+        expect(() => parseUploadsInput(raw)).toThrow();
+    });
+    it.each([
+        null,
+        [],
+        "bad",
+        { "Content-Length": 42 },
+    ])("rejects invalid signed headers %j", headers => {
+        expect(() => parseUploadsInput(JSON.stringify({ hello: { uploadUrl: "x", bundleDir: "x", headers } }))).toThrow("headers must be an object of string values");
+    });
+});

package/dist/version.js

@@ -4,4 +4,4 @@
  *
  * WARNING: Generated during SDK publish. Do not edit in the published package.
  */
-export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.36"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.38"

package/docs/deployment.md

@@ -19,3 +19,29 @@ At startup, the SDK fetches the page-relative `manifest` path only when the bund
 - `ManifestDataSource` — a single entry in `dataSources`.
 - `ManifestProperty` — a single property declaration inside a `ManifestDataSource`.
 - `ManifestIcon` — the icon variant accepted on a `ManifestDataSource`.
+
+## Apps SDK integration
+
+`notion-custom-blocks build --manifest dist/manifest.json --out <dir>` reads
+static Apps SDK capabilities. Paths in the manifest stay relative to the project
+root (the current directory, or `--cwd`). Without `--manifest`, the command
+continues to import the Workers SDK bundle at `dist/index.js`.
+
+Node build tools use one entrypoint:
+
+```ts
+import { build, upload } from "@notionhq/custom-blocks/bundle"
+```
+
+`build` accepts `BuildArgs` and returns `BuildOutput` containing `BuiltBlock`
+results. `upload` accepts `UploadsInput`, a map of block keys to `UploadTarget`,
+and returns `UploadOutput`. `printBuildOutput` writes the sentinel-wrapped build
+result; `parseUploadsInput` validates JSON upload arguments. The Apps CLI calls
+these functions from `build-blocks` and `upload-blocks`.
+
+Relative `--out` paths also resolve from `--cwd`. Build results include
+`bundleSizeBytes`, the exact compressed tarball length, for size-bound uploads.
+
+Upload targets may include a `headers` map containing the headers returned by
+the server presign, including `Content-Length` and object tags. The uploader
+forwards these alongside the tarball checksum and content type.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@notionhq/custom-blocks",
-	"version": "0.1.36",
+	"version": "0.1.38",
 	"license": "MIT",
 	"type": "module",
 	"publishConfig": {
@@ -25,6 +25,10 @@
 		"./vite": {
 			"import": "./vite-plugin/index.js",
 			"types": "./vite-plugin/index.d.ts"
+		},
+		"./bundle": {
+			"types": "./bin/notion-custom-blocks/bundle.d.ts",
+			"import": "./bin/notion-custom-blocks/bundle.js"
 		}
 	},
 	"bin": {