@notionhq/custom-blocks-host 0.0.1

package/dist/lifecycle/initializationController.js

@@ -0,0 +1,182 @@
+import { initErrorForFailureReason } from "./initErrors.js";
+import { isValidBridgeProtocolVersion } from "./protocolVersion.js";
+const DEFAULT_NO_CONNECT_TIMEOUT_MS = 5000;
+const DEFAULT_NO_INIT_RESULT_TIMEOUT_MS = 5000;
+export function createInitializationController(options) {
+    const { blockId, getState, prepareInit, post, warn, flushPendingHostStateChanges, minBridgeProtocolVersion, noConnectTimeoutMs = DEFAULT_NO_CONNECT_TIMEOUT_MS, noInitResultTimeoutMs = DEFAULT_NO_INIT_RESULT_TIMEOUT_MS, onConnect, onInitResult, onIgnoredConnect, } = options;
+    let initStatus = "waitingForConnect";
+    let noConnectTimeoutId;
+    let noInitResultTimeoutId;
+    let activeInitializationId;
+    let hasConnectedSandbox = false;
+    function clearNoConnectTimeout() {
+        if (noConnectTimeoutId !== undefined) {
+            window.clearTimeout(noConnectTimeoutId);
+            noConnectTimeoutId = undefined;
+        }
+    }
+    function clearNoInitResultTimeout() {
+        if (noInitResultTimeoutId !== undefined) {
+            window.clearTimeout(noInitResultTimeoutId);
+            noInitResultTimeoutId = undefined;
+        }
+    }
+    function sendInitError(initializationId, error) {
+        if (initStatus !== "waitingForConnect") {
+            return;
+        }
+        initStatus = "error";
+        activeInitializationId = initializationId;
+        clearNoConnectTimeout();
+        post({
+            type: "init",
+            initializationId,
+            status: "error",
+            error,
+        });
+    }
+    function sendInit(connect) {
+        if (initStatus !== "waitingForConnect") {
+            return false;
+        }
+        onConnect?.(connect);
+        const preparation = prepareInit(connect);
+        if (preparation.status === "error") {
+            sendInitError(connect.initializationId, preparation.error);
+            return false;
+        }
+        initStatus = "waitingForInitResult";
+        activeInitializationId = connect.initializationId;
+        clearNoConnectTimeout();
+        const state = getState();
+        const message = {
+            type: "init",
+            initializationId: connect.initializationId,
+            status: "success",
+            theme: state.theme,
+            contrastMode: state.contrastMode,
+            blockId,
+            parent: state.parent,
+            page: state.page,
+            manifest: preparation.manifest,
+            dataSources: preparation.dataSources,
+            currentUser: state.currentUser,
+        };
+        post(message);
+        noInitResultTimeoutId = window.setTimeout(() => {
+            if (initStatus !== "waitingForInitResult") {
+                return;
+            }
+            initStatus = "error";
+            warn({
+                message: "Sandbox did not send initResult",
+                initializationId: connect.initializationId,
+            });
+        }, noInitResultTimeoutMs);
+        return true;
+    }
+    function handleConnect(message) {
+        if (initStatus !== "waitingForConnect") {
+            // A sandbox document sends `connect` exactly once, so this connect
+            // belongs to a replacement document — or arrived after this host
+            // already gave up waiting. The host is single-initialization; the
+            // embedder must recreate it together with the iframe for the new
+            // document to initialize.
+            warn({
+                message: "Ignored connect after initialization settled; recreate the host and iframe to re-initialize",
+                initializationId: message.initializationId,
+            });
+            onIgnoredConnect?.(message);
+            return;
+        }
+        // Verify the bridge protocol version is valid.
+        if (!isValidBridgeProtocolVersion(message.bridgeProtocolVersion)) {
+            const initError = initErrorForFailureReason("invalid_protocol_version", {
+                currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+            });
+            sendInitError(message.initializationId, initError);
+            return;
+        }
+        if (message.bridgeProtocolVersion < minBridgeProtocolVersion) {
+            const initError = initErrorForFailureReason("unsupported_protocol_version", {
+                currentBridgeProtocolVersion: message.bridgeProtocolVersion,
+                minBridgeProtocolVersion,
+            });
+            sendInitError(message.initializationId, initError);
+            return;
+        }
+        // If the sandbox reported an error during `connect`, return it as an `init` error.
+        if (message.status === "error") {
+            sendInitError(message.initializationId, message.error);
+            return;
+        }
+        if (sendInit(message)) {
+            hasConnectedSandbox = true;
+        }
+    }
+    function handleInvalidConnect(initializationId) {
+        if (initStatus !== "waitingForConnect") {
+            return false;
+        }
+        sendInitError(initializationId, initErrorForFailureReason("invalid_connect_payload"));
+        return true;
+    }
+    function handleInvalidInitResult() {
+        if (initStatus !== "waitingForInitResult") {
+            return false;
+        }
+        clearNoInitResultTimeout();
+        initStatus = "error";
+        warn(initErrorForFailureReason("invalid_init_result_payload"));
+        return true;
+    }
+    function onIframeLoad() {
+        clearNoConnectTimeout();
+        if (initStatus !== "waitingForConnect") {
+            // Only set the timeout if the iframe loaded before the `connect` message was sent.
+            return;
+        }
+        noConnectTimeoutId = window.setTimeout(() => {
+            if (initStatus !== "waitingForConnect") {
+                // Only do anything if the iframe loaded before the `connect` message was sent.
+                return;
+            }
+            initStatus = "error";
+            warn(initErrorForFailureReason("no_connect"));
+        }, noConnectTimeoutMs);
+    }
+    function handleInitResult(message) {
+        if (initStatus !== "waitingForInitResult" ||
+            message.initializationId !== activeInitializationId) {
+            warn({
+                message: "Ignored stale or unexpected initResult",
+                payload: message,
+            });
+            return;
+        }
+        clearNoInitResultTimeout();
+        initStatus = message.status === "success" ? "success" : "error";
+        if (initStatus === "success") {
+            flushPendingHostStateChanges();
+        }
+        onInitResult?.(message);
+    }
+    function stop() {
+        clearNoConnectTimeout();
+        clearNoInitResultTimeout();
+    }
+    return {
+        get status() {
+            return initStatus;
+        },
+        get hasConnectedSandbox() {
+            return hasConnectedSandbox;
+        },
+        handleConnect,
+        handleInitResult,
+        handleInvalidConnect,
+        handleInvalidInitResult,
+        onIframeLoad,
+        stop,
+    };
+}

package/dist/lifecycle/protocolVersion.d.ts

@@ -0,0 +1,2 @@
+export declare function isValidBridgeProtocolVersion(version: number): boolean;
+//# sourceMappingURL=protocolVersion.d.ts.map

package/dist/lifecycle/protocolVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocolVersion.d.ts","sourceRoot":"","sources":["../../src/lifecycle/protocolVersion.ts"],"names":[],"mappings":"AAAA,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE"}

package/dist/lifecycle/protocolVersion.js

@@ -0,0 +1,3 @@
+export function isValidBridgeProtocolVersion(version) {
+    return Number.isFinite(version) && Number.isInteger(version) && version >= 1;
+}

package/dist/lifecycle/types.d.ts

@@ -0,0 +1,28 @@
+import type { NotionContrastMode } from "../protocol/contrast.js";
+import type { NotionDataSourceBindings } from "../protocol/dataSources/dataSource.js";
+import type { NotionBlockId } from "../protocol/ids.js";
+import type { CustomBlockManifest } from "../protocol/manifest.js";
+import type { ConnectMessage } from "../protocol/messages/connect.js";
+import type { CustomBlockPage } from "../protocol/pages/page.js";
+import type { NotionParent } from "../protocol/parent.js";
+import type { NotionTheme } from "../protocol/theme.js";
+import type { NotionUser } from "../protocol/users/user.js";
+export type ConnectSuccessMessage = Extract<ConnectMessage, {
+    status: "success";
+}>;
+export type InitStatus = "waitingForConnect" | "waitingForInitResult" | "success" | "error";
+export type CustomBlockHostDataSourcesPayload = {
+    bindings: NotionDataSourceBindings;
+};
+export type CustomBlockHostInitialDataSources = CustomBlockHostDataSourcesPayload | ((connect: ConnectSuccessMessage) => CustomBlockHostDataSourcesPayload);
+export type CustomBlockHostInitialState = {
+    theme: NotionTheme;
+    contrastMode?: NotionContrastMode;
+    blockId: NotionBlockId;
+    parent: NotionParent;
+    page: CustomBlockPage;
+    manifest: CustomBlockManifest;
+    dataSources: CustomBlockHostInitialDataSources;
+    currentUser: NotionUser;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/lifecycle/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lifecycle/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAA;AACtF,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4DAA4D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8CAA8C,CAAA;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sDAAsD,CAAA;AAC1F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gDAAgD,CAAA;AACrF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4CAA4C,CAAA;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAA;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gDAAgD,CAAA;AAEhF,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAC1C,cAAc,EACd;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CACrB,CAAA;AAED,MAAM,MAAM,UAAU,GACnB,mBAAmB,GACnB,sBAAsB,GACtB,SAAS,GACT,OAAO,CAAA;AAEV,MAAM,MAAM,iCAAiC,GAAG;IAC/C,QAAQ,EAAE,wBAAwB,CAAA;CAClC,CAAA;AAED,MAAM,MAAM,iCAAiC,GAC1C,iCAAiC,GACjC,CAAC,CAAC,OAAO,EAAE,qBAAqB,KAAK,iCAAiC,CAAC,CAAA;AAE1E,MAAM,MAAM,2BAA2B,GAAG;IACzC,KAAK,EAAE,WAAW,CAAA;IAElB,YAAY,CAAC,EAAE,kBAAkB,CAAA;IACjC,OAAO,EAAE,aAAa,CAAA;IACtB,MAAM,EAAE,YAAY,CAAA;IACpB,IAAI,EAAE,eAAe,CAAA;IACrB,QAAQ,EAAE,mBAAmB,CAAA;IAC7B,WAAW,EAAE,iCAAiC,CAAA;IAC9C,WAAW,EAAE,UAAU,CAAA;CACvB,CAAA"}

package/dist/lifecycle/types.js

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

package/dist/messages/invalidSandboxMessage.d.ts

@@ -0,0 +1,7 @@
+import type { InvalidSandboxMessage } from "../protocol/messages/invalidSandboxMessage.js";
+export type InvalidSandboxMessageResponse = {
+    incomingType: string | undefined;
+    nack?: InvalidSandboxMessage;
+};
+export declare function getInvalidSandboxMessageResponse(data: unknown): InvalidSandboxMessageResponse;
+//# sourceMappingURL=invalidSandboxMessage.d.ts.map

package/dist/messages/invalidSandboxMessage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalidSandboxMessage.d.ts","sourceRoot":"","sources":["../../src/messages/invalidSandboxMessage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oEAAoE,CAAA;AAE/G,MAAM,MAAM,6BAA6B,GAAG;IAC3C,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,IAAI,CAAC,EAAE,qBAAqB,CAAA;CAC5B,CAAA;AAED,wBAAgB,gCAAgC,CAC/C,IAAI,EAAE,OAAO,GACX,6BAA6B,CAe/B"}

package/dist/messages/invalidSandboxMessage.js

@@ -0,0 +1,21 @@
+import { readIncomingType } from "../protocol/incomingType.js";
+export function getInvalidSandboxMessageResponse(data) {
+    const incomingType = readIncomingType(data);
+    if (incomingType === "invalidHostMessage" ||
+        incomingType === "invalidSandboxMessage") {
+        return { incomingType };
+    }
+    return {
+        incomingType,
+        nack: {
+            type: "invalidSandboxMessage",
+            reason: nackReasonForInvalidSandboxMessage(incomingType),
+        },
+    };
+}
+function nackReasonForInvalidSandboxMessage(incomingType) {
+    if (incomingType !== undefined) {
+        return `Unsupported sandbox message of type "${incomingType}"`;
+    }
+    return "Unsupported sandbox message (no `type` field or non-object payload)";
+}

package/dist/messages/types.d.ts

@@ -0,0 +1,29 @@
+import type { BridgeMessagePayload } from "../protocol/messagePayload.js";
+import type { CreatePageMessage } from "../protocol/messages/createPage.js";
+import type { CreatePageResultMessage, CustomBlockCreatePageErrorInfo } from "../protocol/messages/createPageResult.js";
+import type { CustomBlockGetPageErrorInfo, GetPageMessage, GetPageResultMessage } from "../protocol/messages/getPage.js";
+import type { CustomBlockGetUserErrorInfo, GetUserMessage, GetUserResultMessage } from "../protocol/messages/getUser.js";
+import type { CustomBlockListUsersErrorInfo, ListUsersMessage, ListUsersResultMessage } from "../protocol/messages/listUsers.js";
+import type { QueryDataSourceMessage } from "../protocol/messages/queryDataSource.js";
+import type { ResizeMessage } from "../protocol/messages/resize.js";
+import type { UpdatePageMessage } from "../protocol/messages/updatePage.js";
+import type { CustomBlockUpdatePageErrorInfo, UpdatePageResultMessage } from "../protocol/messages/updatePageResult.js";
+import type { CustomBlockHostQueryDataSourceResult } from "../queries/types.js";
+type MaybePromise<T> = T | Promise<T>;
+export type CustomBlockHostCreatePageResult = BridgeMessagePayload<CreatePageResultMessage, CustomBlockCreatePageErrorInfo>;
+export type CustomBlockHostGetPageResult = BridgeMessagePayload<GetPageResultMessage, CustomBlockGetPageErrorInfo>;
+export type CustomBlockHostUpdatePageResult = BridgeMessagePayload<UpdatePageResultMessage, CustomBlockUpdatePageErrorInfo>;
+export type CustomBlockHostGetUserResult = BridgeMessagePayload<GetUserResultMessage, CustomBlockGetUserErrorInfo>;
+export type CustomBlockHostListUsersResult = BridgeMessagePayload<ListUsersResultMessage, CustomBlockListUsersErrorInfo>;
+export type CustomBlockHostHandlers = {
+    queryDataSource: (message: QueryDataSourceMessage) => MaybePromise<CustomBlockHostQueryDataSourceResult>;
+    createPage?: (message: CreatePageMessage) => MaybePromise<CustomBlockHostCreatePageResult>;
+    getPage?: (message: GetPageMessage) => MaybePromise<CustomBlockHostGetPageResult>;
+    getUser?: (message: GetUserMessage) => MaybePromise<CustomBlockHostGetUserResult>;
+    listUsers?: (message: ListUsersMessage) => MaybePromise<CustomBlockHostListUsersResult>;
+    updatePage?: (message: UpdatePageMessage) => MaybePromise<CustomBlockHostUpdatePageResult>;
+    resize?: (message: ResizeMessage) => void;
+};
+export type CustomBlockHostLogDirection = "in" | "out" | "warn";
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/messages/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/messages/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAA;AAC9F,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,uBAAuB,EACvB,8BAA8B,EAC9B,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,MAAM,sDAAsD,CAAA;AAC7D,OAAO,KAAK,EACX,6BAA6B,EAC7B,gBAAgB,EAChB,sBAAsB,EACtB,MAAM,wDAAwD,CAAA;AAC/D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qDAAqD,CAAA;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yDAAyD,CAAA;AAChG,OAAO,KAAK,EACX,8BAA8B,EAC9B,uBAAuB,EACvB,MAAM,+DAA+D,CAAA;AACtE,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,qBAAqB,CAAA;AAE/E,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAErC,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,CACjE,uBAAuB,EACvB,8BAA8B,CAC9B,CAAA;AAED,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,CAC9D,oBAAoB,EACpB,2BAA2B,CAC3B,CAAA;AAED,MAAM,MAAM,8BAA8B,GAAG,oBAAoB,CAChE,sBAAsB,EACtB,6BAA6B,CAC7B,CAAA;AAED,MAAM,MAAM,uBAAuB,GAAG;IACrC,eAAe,EAAE,CAChB,OAAO,EAAE,sBAAsB,KAC3B,YAAY,CAAC,oCAAoC,CAAC,CAAA;IACvD,UAAU,CAAC,EAAE,CACZ,OAAO,EAAE,iBAAiB,KACtB,YAAY,CAAC,+BAA+B,CAAC,CAAA;IAClD,OAAO,CAAC,EAAE,CACT,OAAO,EAAE,cAAc,KACnB,YAAY,CAAC,4BAA4B,CAAC,CAAA;IAC/C,OAAO,CAAC,EAAE,CACT,OAAO,EAAE,cAAc,KACnB,YAAY,CAAC,4BAA4B,CAAC,CAAA;IAC/C,SAAS,CAAC,EAAE,CACX,OAAO,EAAE,gBAAgB,KACrB,YAAY,CAAC,8BAA8B,CAAC,CAAA;IACjD,UAAU,CAAC,EAAE,CACZ,OAAO,EAAE,iBAAiB,KACtB,YAAY,CAAC,+BAA+B,CAAC,CAAA;IAClD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAA;CACzC,CAAA;AAED,MAAM,MAAM,2BAA2B,GAAG,IAAI,GAAG,KAAK,GAAG,MAAM,CAAA"}

package/dist/messages/types.js

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

package/dist/protocol/contrast.d.ts

@@ -0,0 +1,4 @@
+import * as v from "valibot";
+export declare const notionContrastModeSchema: v.PicklistSchema<["standard", "high"], undefined>;
+export type NotionContrastMode = v.InferOutput<typeof notionContrastModeSchema>;
+export declare const DEFAULT_CONTRAST_MODE: NotionContrastMode;

package/dist/protocol/contrast.js

@@ -0,0 +1,3 @@
+import * as v from "valibot";
+export const notionContrastModeSchema = v.picklist(["standard", "high"]);
+export const DEFAULT_CONTRAST_MODE = "standard";