@notionhq/custom-blocks 0.1.7 → 0.1.8

package/src/bridge/dataSources/errors.ts

@@ -1,14 +0,0 @@
-import * as v from "valibot"
-import type { CustomBlockErrorInfo } from "../errors.js"
-
-// The schema accepts any string code. The type lists known codes for
-// autocomplete, with an open string fallback for newer senders.
-export const customBlockDataSourceResolutionErrorCodeSchema = v.string()
-
-export type CustomBlockDataSourceResolutionErrorCode =
-	| "unknown_data_source_key"
-	| "unmapped_data_source"
-	| (string & {})
-
-export type CustomBlockDataSourceResolutionErrorInfo =
-	CustomBlockErrorInfo<CustomBlockDataSourceResolutionErrorCode>

package/src/bridge/dataSources/propertySchema.ts

@@ -1,186 +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 type NotionPropertyColor = v.InferOutput<
-	typeof notionPropertyColorSchema
->
-
-export const notionPropertyOptionSchema = v.object({
-	id: v.string(),
-	name: v.string(),
-	color: v.optional(notionPropertyColorSchema),
-	description: v.optional(v.string()),
-})
-
-export type NotionPropertyOption = v.InferOutput<
-	typeof notionPropertyOptionSchema
->
-
-export const notionStatusGroupSchema = v.object({
-	id: v.string(),
-	name: v.string(),
-	color: v.optional(notionPropertyColorSchema),
-	option_ids: v.array(v.string()),
-})
-
-export type NotionStatusGroup = v.InferOutput<typeof notionStatusGroupSchema>
-
-export const notionDualPropertySchema = v.object({
-	synced_property_id: v.string(),
-	synced_property_name: v.string(),
-})
-
-export type NotionDualProperty = v.InferOutput<typeof notionDualPropertySchema>
-
-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",
-] as const
-
-export const notionPropertyTypeSchema = v.picklist(NOTION_PROPERTY_TYPES)
-
-/**
- * String literal union of every supported Notion property type. Same set as
- * the discriminator in `NotionPropertySchema` — split out so the manifest
- * can declare expected property types without dragging in the per-type
- * payload shapes.
- */
-export type NotionPropertyType = v.InferOutput<typeof notionPropertyTypeSchema>
-
-/**
- * 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") }),
-])
-
-export type NotionPropertySchema = v.InferOutput<
-	typeof notionPropertySchemaSchema
->
-
-/**
- * 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",
-] as const
-
-export type NotionBuiltinPropertyId =
-	(typeof NOTION_BUILTIN_PROPERTY_IDS)[number]

package/src/bridge/dataSources/recordPointer.ts

@@ -1,13 +0,0 @@
-import * as v from "valibot"
-
-/**
- * A pointer to a record in a database.
- */
-export const notionRecordPointerSchema = v.object({
-	id: v.string(),
-	table: v.string(),
-})
-
-export type NotionRecordPointer = v.InferOutput<
-	typeof notionRecordPointerSchema
->

package/src/bridge/errors.ts

@@ -1,21 +0,0 @@
-import * as v from "valibot"
-
-export type CustomBlockErrorCode<KnownCode extends string> =
-	// Accept a list of known codes for auto-completion.
-	| KnownCode
-	// Hosts send this for any errors that are not covered by an error code known by that host.
-	| "unknown_error"
-	// Hosts may introduce new codes in the future, so allow any string as a catch-all.
-	| (string & {})
-
-export type CustomBlockErrorInfo<TCode extends string = string> = {
-	code: TCode
-	message: string
-	isRetryable: boolean
-}
-
-export const customBlockErrorInfoSchema = v.object({
-	code: v.string(),
-	message: v.string(),
-	isRetryable: v.boolean(),
-})

package/src/bridge/ids.ts

@@ -1,72 +0,0 @@
-import * as v from "valibot"
-
-declare const notionDataSourceIdBrand: unique symbol
-declare const notionBlockIdBrand: unique symbol
-declare const notionPageIdBrand: unique symbol
-declare const notionAgentIdBrand: unique symbol
-declare const notionSpaceIdBrand: unique symbol
-
-/**
- * Branded Notion block ID. Host payloads and SDK APIs use plain strings at runtime,
- * but the brand keeps block IDs from being accidentally mixed with other IDs in TypeScript.
- */
-export type NotionBlockId = string & {
-	readonly [notionBlockIdBrand]: "NotionBlockId"
-}
-
-export const notionBlockIdSchema = v.custom<NotionBlockId>(
-	value => typeof value === "string",
-	"Expected a Notion block ID",
-)
-
-/**
- * Branded Notion data source ID. Host payloads and SDK APIs use plain strings at runtime,
- * but the brand keeps data source IDs from being accidentally mixed with other IDs in TypeScript.
- */
-export type NotionDataSourceId = string & {
-	readonly [notionDataSourceIdBrand]: "NotionDataSourceId"
-}
-
-export const notionDataSourceIdSchema = v.custom<NotionDataSourceId>(
-	value => typeof value === "string",
-	"Expected a Notion data source ID",
-)
-
-/**
- * Branded Notion page ID. Host payloads and SDK APIs use plain strings at runtime,
- * but the brand keeps page IDs from being accidentally mixed with other IDs in TypeScript.
- */
-export type NotionPageId = string & {
-	readonly [notionPageIdBrand]: "NotionPageId"
-}
-
-export const notionPageIdSchema = v.custom<NotionPageId>(
-	value => typeof value === "string",
-	"Expected a Notion page ID",
-)
-
-/**
- * Branded Notion agent ID. Agent parents identify the workflow that owns an
- * instruction page or one of its blocks.
- */
-export type NotionAgentId = string & {
-	readonly [notionAgentIdBrand]: "NotionAgentId"
-}
-
-export const notionAgentIdSchema = v.custom<NotionAgentId>(
-	value => typeof value === "string",
-	"Expected a Notion agent ID",
-)
-
-/**
- * Branded Notion workspace/space ID. Host payloads and SDK APIs use plain strings at runtime,
- * but the brand keeps space IDs from being accidentally mixed with other IDs in TypeScript.
- */
-export type NotionSpaceId = string & {
-	readonly [notionSpaceIdBrand]: "NotionSpaceId"
-}
-
-export const notionSpaceIdSchema = v.custom<NotionSpaceId>(
-	value => typeof value === "string",
-	"Expected a Notion space ID",
-)

package/src/bridge/incomingType.ts

@@ -1,19 +0,0 @@
-/**
- * Reads the `type` field off an inbound bridge message, if any.
- *
- * Used by both sides of the bridge after the canonical message schema rejects a payload. We still
- * want to know what type the sender claimed to be sending so we can (a) avoid NACK loops on
- * `invalidHostMessage` / `invalidSandboxMessage` and (b) include the type in the failure reason
- * for debugging.
- */
-export function readIncomingType(data: unknown): string | undefined {
-	if (
-		typeof data === "object" &&
-		data !== null &&
-		"type" in data &&
-		typeof data.type === "string"
-	) {
-		return data.type
-	}
-	return undefined
-}

package/src/bridge/manifest.ts

@@ -1,47 +0,0 @@
-import * as v from "valibot"
-import { notionPropertyTypeSchema } from "./dataSources/propertySchema.js"
-
-/**
- * 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 type ManifestIcon = v.InferOutput<typeof manifestIconSchema>
-
-export const manifestPropertySchema = v.object({
-	name: v.string(),
-	description: v.optional(v.string()),
-	type: notionPropertyTypeSchema,
-})
-
-export type ManifestProperty = v.InferOutput<typeof manifestPropertySchema>
-
-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 type ManifestDataSource = v.InferOutput<typeof manifestDataSourceSchema>
-
-export const manifestSchema = v.object({
-	version: v.literal(1),
-	dataSources: v.record(v.string(), manifestDataSourceSchema),
-})
-
-/**
- * Manifest declaring the data sources required by a custom block.
- */
-export type CustomBlockManifest = v.InferOutput<typeof manifestSchema>

package/src/bridge/messages/connect.ts

@@ -1,42 +0,0 @@
-import * as v from "valibot"
-import { customBlockErrorInfoSchema } from "../errors.js"
-import { manifestSchema } from "../manifest.js"
-
-const connectMessageCommonEntries = {
-	type: v.literal("connect"),
-	initializationId: v.string(),
-	/**
-	 * Used to ensure that the host and client are using the same version of the bridge protocol. A
-	 * single host needs to support multiple custom blocks built with different versions of the bridge
-	 * protocol. Increment this number any time a breaking change is made to the bridge protocol.
-	 */
-	bridgeProtocolVersion: v.number(),
-	/**
-	 * Semver version of the SDK package that sent this connect message. Should only be used for
-	 * analytics purposes. Business logic should compare against `bridgeProtocolVersion` instead.
-	 */
-	sdkVersion: v.string(),
-}
-
-/**
- * First message the sandbox sends after mount. It identifies the sandbox and starts the bridge
- * initialization exchange. The host echoes `initializationId` in its `init` response.
- */
-export const connectMessageSchema = v.variant("status", [
-	v.object({
-		status: v.literal("success"),
-		/**
-		 * The data sources and settings the custom block expects. Hosts may omit
-		 * this when they already have an authoritative manifest.
-		 */
-		manifest: v.optional(manifestSchema),
-		...connectMessageCommonEntries,
-	}),
-	v.object({
-		status: v.literal("error"),
-		error: customBlockErrorInfoSchema,
-		...connectMessageCommonEntries,
-	}),
-])
-
-export type ConnectMessage = v.InferOutput<typeof connectMessageSchema>

package/src/bridge/messages/contrastModeChanged.ts

@@ -1,12 +0,0 @@
-import * as v from "valibot"
-import { notionContrastModeSchema } from "../contrast.js"
-
-/** Message sent by the host when contrast changes after initialization. */
-export const contrastModeChangedMessageSchema = v.object({
-	type: v.literal("contrastModeChanged"),
-	contrastMode: notionContrastModeSchema,
-})
-
-export type ContrastModeChangedMessage = v.InferOutput<
-	typeof contrastModeChangedMessageSchema
->

package/src/bridge/messages/createPage.ts

@@ -1,62 +0,0 @@
-import * as v from "valibot"
-import {
-	notionBlockIdSchema,
-	notionDataSourceIdSchema,
-	notionPageIdSchema,
-} from "../ids.js"
-import { notionPagePropertyWriteMapSchema } from "../pages/page.js"
-
-/**
- * Describes where the newly created page should be inserted.
- * - `start` / `end` (default): prepend / append to the request's `parent`
- *   page's children.
- * - `before` / `after`: insert as a sibling of the anchor block identified by
- *   `blockId`, using the anchor's own structural parent. The anchor can be
- *   nested anywhere below the page (inside a toggle, column, callout, etc.).
- */
-export const notionCreatePagePositionSchema = v.variant("type", [
-	v.object({ type: v.literal("start") }),
-	v.object({ type: v.literal("end") }),
-	v.object({ type: v.literal("before"), blockId: notionBlockIdSchema }),
-	v.object({ type: v.literal("after"), blockId: notionBlockIdSchema }),
-])
-
-export type NotionCreatePagePosition = v.InferOutput<
-	typeof notionCreatePagePositionSchema
->
-
-/**
- * Parent accepted by the outbound `createPage` bridge message.
- *
- * Mirrors Notion's public API `POST /v1/pages` parent shape: `page_id` for a page-parented child,
- * `data_source_id` for a database row. `data_source_id` is the internal collection ID.
- *
- * The SDK additionally accepts a higher-level `data_source_key` variant that resolves to
- * `data_source_id` locally, using the `dataSources` mapping.
- */
-export const createPageParentSchema = v.variant("type", [
-	v.object({ type: v.literal("page_id"), page_id: notionPageIdSchema }),
-	v.object({
-		type: v.literal("data_source_id"),
-		data_source_id: notionDataSourceIdSchema,
-	}),
-])
-
-export type CreatePageMessageParent = v.InferOutput<
-	typeof createPageParentSchema
->
-
-/**
- * Message sent by the sandbox to ask the host to create a new page on its behalf.
- * The payload mirrors Notion's public `POST /v1/pages` API.
- */
-export const createPageMessageSchema = v.object({
-	type: v.literal("createPage"),
-	requestId: v.string(),
-	parent: createPageParentSchema,
-	properties: notionPagePropertyWriteMapSchema,
-	// TODO(custom-blocks): Add icon and cover once the Notion host supports them for page creation.
-	position: v.optional(notionCreatePagePositionSchema),
-})
-
-export type CreatePageMessage = v.InferOutput<typeof createPageMessageSchema>

package/src/bridge/messages/createPageResult.ts

@@ -1,52 +0,0 @@
-import * as v from "valibot"
-import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
-import { notionPageSchema } from "../pages/page.js"
-
-// The schema accepts any string code. The type lists known codes for
-// autocomplete, with an open string fallback for newer senders.
-export const customBlockCreatePageErrorCodeSchema = v.string()
-
-export type CustomBlockCreatePageErrorCode = CustomBlockErrorCode<
-	| "create_page_failed"
-	| "invalid_page_parent"
-	| "page_access_failed"
-	| "collection_access_failed"
-	| "unknown_data_source_key"
-	| "unmapped_data_source"
-	| "unmapped_property"
-	| "property_id_mismatch"
-	| "duplicate_property"
-	| "invalid_property_value"
->
-
-export type CustomBlockCreatePageErrorInfo =
-	CustomBlockErrorInfo<CustomBlockCreatePageErrorCode>
-
-export const customBlockCreatePageErrorInfoSchema = v.object({
-	code: customBlockCreatePageErrorCodeSchema,
-	message: v.string(),
-	isRetryable: v.boolean(),
-})
-
-/**
- * Message sent by the host in response to a sandbox `createPage` request.
- */
-export const createPageResultMessageSchema = v.variant("status", [
-	v.object({
-		type: v.literal("createPageResult"),
-		requestId: v.string(),
-		status: v.literal("success"),
-		/** The newly created page. */
-		page: notionPageSchema,
-	}),
-	v.object({
-		type: v.literal("createPageResult"),
-		requestId: v.string(),
-		status: v.literal("error"),
-		error: customBlockCreatePageErrorInfoSchema,
-	}),
-])
-
-export type CreatePageResultMessage = v.InferOutput<
-	typeof createPageResultMessageSchema
->

package/src/bridge/messages/currentUserChanged.ts

@@ -1,14 +0,0 @@
-import * as v from "valibot"
-import { notionUserSchema } from "../users/user.js"
-
-/**
- * Sent by the host when the viewing user's profile changes while the block is mounted.
- */
-export const currentUserChangedMessageSchema = v.object({
-	type: v.literal("currentUserChanged"),
-	currentUser: notionUserSchema,
-})
-
-export type CurrentUserChangedMessage = v.InferOutput<
-	typeof currentUserChangedMessageSchema
->

package/src/bridge/messages/dataSourcesChanged.ts

@@ -1,18 +0,0 @@
-import * as v from "valibot"
-import { notionDataSourceBindingsSchema } from "../dataSources/dataSource.js"
-
-/**
- * Message sent by the host whenever the custom block's data-source mapping changes (e.g. a key is
- * added, removed, or remapped). The SDK replaces its list of configured data sources but keeps any
- * in-flight `useDataSource` query state for keys that still exist.
- */
-export const dataSourcesChangedMessageSchema = v.object({
-	type: v.literal("dataSourcesChanged"),
-	dataSources: v.object({
-		bindings: notionDataSourceBindingsSchema,
-	}),
-})
-
-export type DataSourcesChangedMessage = v.InferOutput<
-	typeof dataSourcesChangedMessageSchema
->

package/src/bridge/messages/getPage.ts

@@ -1,51 +0,0 @@
-import * as v from "valibot"
-import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
-import { notionPageIdSchema } from "../ids.js"
-import { notionPageSchema } from "../pages/page.js"
-
-// The schema accepts any string code. The type lists known codes for
-// autocomplete, with an open string fallback for newer senders.
-export const customBlockGetPageErrorCodeSchema = v.string()
-
-export type CustomBlockGetPageErrorCode = CustomBlockErrorCode<
-	"get_page_failed" | "page_access_failed"
->
-
-export type CustomBlockGetPageErrorInfo =
-	CustomBlockErrorInfo<CustomBlockGetPageErrorCode>
-
-export const customBlockGetPageErrorInfoSchema = v.object({
-	code: customBlockGetPageErrorCodeSchema,
-	message: v.string(),
-	isRetryable: v.boolean(),
-})
-
-/**
- * Sandbox -> host: fetch a page by ID.
- */
-export const getPageMessageSchema = v.object({
-	type: v.literal("getPage"),
-	requestId: v.string(),
-	pageId: notionPageIdSchema,
-})
-
-export type GetPageMessage = v.InferOutput<typeof getPageMessageSchema>
-
-export const getPageResultMessageSchema = v.variant("status", [
-	v.object({
-		type: v.literal("getPageResult"),
-		requestId: v.string(),
-		status: v.literal("success"),
-		page: notionPageSchema,
-	}),
-	v.object({
-		type: v.literal("getPageResult"),
-		requestId: v.string(),
-		status: v.literal("error"),
-		error: customBlockGetPageErrorInfoSchema,
-	}),
-])
-
-export type GetPageResultMessage = v.InferOutput<
-	typeof getPageResultMessageSchema
->

package/src/bridge/messages/getUser.ts

@@ -1,49 +0,0 @@
-import * as v from "valibot"
-import type { CustomBlockErrorCode, CustomBlockErrorInfo } from "../errors.js"
-import { notionUserSchema } from "../users/user.js"
-
-// The schema accepts any string code. The type lists known codes for
-// autocomplete, with an open string fallback for newer senders.
-export const customBlockGetUserErrorCodeSchema = v.string()
-
-export type CustomBlockGetUserErrorCode =
-	CustomBlockErrorCode<"get_user_failed">
-
-export type CustomBlockGetUserErrorInfo =
-	CustomBlockErrorInfo<CustomBlockGetUserErrorCode>
-
-export const customBlockGetUserErrorInfoSchema = v.object({
-	code: customBlockGetUserErrorCodeSchema,
-	message: v.string(),
-	isRetryable: v.boolean(),
-})
-
-/**
- * Sandbox -> host: fetch a user by ID.
- */
-export const getUserMessageSchema = v.object({
-	type: v.literal("getUser"),
-	requestId: v.string(),
-	userId: v.string(),
-})
-
-export type GetUserMessage = v.InferOutput<typeof getUserMessageSchema>
-
-export const getUserResultMessageSchema = v.variant("status", [
-	v.object({
-		type: v.literal("getUserResult"),
-		requestId: v.string(),
-		status: v.literal("success"),
-		user: notionUserSchema,
-	}),
-	v.object({
-		type: v.literal("getUserResult"),
-		requestId: v.string(),
-		status: v.literal("error"),
-		error: customBlockGetUserErrorInfoSchema,
-	}),
-])
-
-export type GetUserResultMessage = v.InferOutput<
-	typeof getUserResultMessageSchema
->