@notionhq/custom-blocks 0.1.37 → 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/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/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.37"
+export const CUSTOM_BLOCKS_SDK_VERSION = "0.1.38"

package/docs/deployment.md

@@ -27,6 +27,21 @@ 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.37",
+	"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": {