ncblock 0.0.3 → 0.0.5

package/users.ts

@@ -0,0 +1,26 @@
+import { getUser, listUsers } from "./bridge/sandboxClient"
+import type {
+	GetUserResult,
+	ListUsersInput,
+	ListUsersResult,
+	NotionUserId,
+} from "./types"
+
+/**
+ * User-related SDK APIs exposed under `sdk.users.*`.
+ */
+export const users = {
+	/**
+	 * Lists users visible in the current custom block workspace.
+	 */
+	list(input?: ListUsersInput): Promise<ListUsersResult> {
+		return listUsers(input)
+	},
+
+	/**
+	 * Fetches a user by id.
+	 */
+	get(userId: NotionUserId): Promise<GetUserResult> {
+		return getUser(userId)
+	},
+}

package/utils.ts

@@ -0,0 +1,13 @@
+/**
+ * Internal helpers shared across the SDK.
+ */
+
+/**
+ * Throws an error when an unexpected value is encountered. This is used to ensure all code paths
+ * are covered when using discriminated unions.
+ */
+export function unreachable(value: never): never {
+	throw new Error(
+		`[notion-custom-sdk] Unexpected value encountered: ${JSON.stringify(value)}`,
+	)
+}

package/vite-plugin/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Type declarations for the Vite plugin. The runtime lives in `vite.js` —
+ * see that file for behavior, options, and the reasoning for splitting `.js`
+ * + `.d.ts` instead of using a single `.ts` source.
+ */
+
+type UserConfig = { base?: string }
+
+type ResolvedConfig = { root: string; command: "serve" | "build" }
+
+type ServerLike = {
+	middlewares: { use: (handler: MiddlewareHandler) => unknown }
+}
+
+type MiddlewareHandler = (
+	req: { url?: string },
+	res: {
+		statusCode?: number
+		setHeader: (name: string, value: string) => void
+		end: (body?: string) => void
+	},
+	next: () => void,
+) => void
+
+type AssetEmitterContext = {
+	emitFile: (file: {
+		type: "asset"
+		fileName: string
+		source: string
+	}) => string
+}
+
+export type NotionCustomBlockPlugin = {
+	name: string
+	config: (userConfig: UserConfig) => { base: string }
+	configResolved: (config: ResolvedConfig) => void
+	configureServer: (server: ServerLike) => void
+	configurePreviewServer: (server: ServerLike) => void
+	buildStart: (this: AssetEmitterContext) => void
+}
+
+/**
+ * Vite plugin that serves the project's `custom_blocks.json` to the custom-block
+ * bundle in dev and emits it as a separate asset on build.
+ */
+export function notionCustomBlock(): NotionCustomBlockPlugin

package/vite-plugin/index.js

@@ -0,0 +1,115 @@
+/**
+ * Vite plugin half of `ncblock`. Exposes the project's
+ * `custom_blocks.json` manifest to the custom-block bundle so the SDK's runtime
+ * fetch can resolve.
+ *
+ * Authored as plain JS (with `index.d.ts` co-located for types) — the rest of
+ * the SDK is `.ts` consumed directly via the workspace symlink, but Vite's
+ * config loader resolves this subpath through Node's ESM resolver, which
+ * can't load `.ts` source files. Lives in its own `vite-plugin/` directory
+ * so it can grow its own tsconfig later.
+ *
+ * Usage:
+ *
+ *   import { notionCustomBlock } from "ncblock/vite"
+ *
+ *   export default defineConfig({
+ *     plugins: [react(), notionCustomBlock()],
+ *   })
+ *
+ * Requires `"type": "module"` in the consuming project's `package.json` so
+ * Vite's config loader uses Node's ESM resolver (not CommonJS `require`,
+ * which fails for ESM-only deps).
+ *
+ * - **Dev (`vite`)** — middleware serves `/custom_blocks.json` from the project root.
+ * - **Build (`vite build`)** — emits `custom_blocks.json` as an asset alongside the
+ *   built `index.html` so `vite preview` and any local file server can serve
+ *   it. In production, the custom-block CLI handles serving.
+ *
+ * Validation is intentionally not performed here — the SDK validates on
+ * receipt, and the CLI validates separately at deploy time.
+ */
+import { existsSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+
+const MANIFEST_FILENAME = "custom_blocks.json"
+const MANIFEST_URL_PATH = `/${MANIFEST_FILENAME}`
+const REQUIRED_BASE = "./"
+
+export function notionCustomBlock() {
+	let projectRoot = process.cwd()
+	let command = "serve"
+
+	function manifestPath() {
+		return resolve(projectRoot, MANIFEST_FILENAME)
+	}
+
+	function readManifest() {
+		const file = manifestPath()
+		if (!existsSync(file)) {
+			return undefined
+		}
+		return readFileSync(file, "utf8")
+	}
+
+	function middleware(req, res, next) {
+		const path = req.url?.split("?", 1)[0]
+		if (path !== MANIFEST_URL_PATH) {
+			next()
+			return
+		}
+		const contents = readManifest()
+		if (contents === undefined) {
+			res.statusCode = 404
+			res.end()
+			return
+		}
+		res.setHeader("Content-Type", "application/json")
+		res.end(contents)
+	}
+
+	return {
+		name: "ncblock:notion-manifest",
+		config(userConfig) {
+			// Custom blocks are served from a content-addressed path that
+			// has trailing slashes, eg https://dev.notion.so/custom-block-bundle/357b35e6-e67f-81fd-b425-00e7b3e2afd1/
+			// so all asset URLs in the built bundle must be relative.
+			// Force `base: "./"` and reject any other explicit value
+			//
+			// Note: once we are set up with a wildcard subdomain host, this will no longer be necessary
+			// and should be removed, since /assets will work fine.
+			if (userConfig.base !== undefined && userConfig.base !== REQUIRED_BASE) {
+				throw new Error(
+					`ncblock/vite: \`base\` must be "${REQUIRED_BASE}" (got ${JSON.stringify(userConfig.base)}). Custom blocks need relative asset paths so the bundle works under any host-served prefix.`,
+				)
+			}
+			return { base: REQUIRED_BASE }
+		},
+		configResolved(config) {
+			projectRoot = config.root
+			command = config.command
+		},
+		configureServer(server) {
+			server.middlewares.use(middleware)
+		},
+		configurePreviewServer(server) {
+			server.middlewares.use(middleware)
+		},
+		buildStart() {
+			// `emitFile` is only valid during `vite build`. In serve mode the
+			// middleware above handles `/custom_blocks.json`, so we skip emission.
+			if (command !== "build") {
+				return
+			}
+			const contents = readManifest()
+			if (contents === undefined) {
+				return
+			}
+			this.emitFile({
+				type: "asset",
+				fileName: MANIFEST_FILENAME,
+				source: contents,
+			})
+		},
+	}
+}