ncblock 0.0.1

package/dist/pages.d.ts

@@ -0,0 +1,23 @@
+import type { CreatePageInput, CreatePageResult, GetPageResult, NotionPageId, UpdatePageInput, UpdatePageResult } from "./types";
+/**
+ * Page-related SDK APIs exposed under `sdk.pages.*`.
+ */
+export declare const pages: {
+    /**
+     * Creates a new Notion page.
+     */
+    create(input: CreatePageInput): Promise<CreatePageResult>;
+    /**
+     * Fetches a page by id.
+     */
+    get(pageId: NotionPageId): Promise<GetPageResult>;
+    /**
+     * Updates an existing page.
+     */
+    update(input: UpdatePageInput): Promise<UpdatePageResult>;
+    /**
+     * Soft-delete a page by archiving it.
+     */
+    delete(pageId: NotionPageId): Promise<UpdatePageResult>;
+};
+//# sourceMappingURL=pages.d.ts.map

package/dist/pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../pages.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,MAAM,SAAS,CAAA;AAEhB;;GAEG;AACH,eAAO,MAAM,KAAK;IACjB;;OAEG;kBACW,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIzD;;OAEG;gBACS,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAIjD;;OAEG;kBACW,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIzD;;OAEG;mBACY,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAGvD,CAAA"}

package/dist/pages.js

@@ -0,0 +1,30 @@
+import { createPage, getPage, updatePage } from "./notion";
+/**
+ * Page-related SDK APIs exposed under `sdk.pages.*`.
+ */
+export const pages = {
+    /**
+     * Creates a new Notion page.
+     */
+    create(input) {
+        return createPage(input);
+    },
+    /**
+     * Fetches a page by id.
+     */
+    get(pageId) {
+        return getPage(pageId);
+    },
+    /**
+     * Updates an existing page.
+     */
+    update(input) {
+        return updatePage(input);
+    },
+    /**
+     * Soft-delete a page by archiving it.
+     */
+    delete(pageId) {
+        return updatePage({ pageId, archived: true });
+    },
+};

package/dist/react.d.ts

@@ -0,0 +1,171 @@
+import { type ReactNode } from "react";
+import type { NotionCustomBlockContext } from "./bridge/context";
+import type { NotionDataSource } from "./bridge/dataSources/dataSource";
+import type { NotionTheme } from "./bridge/theme";
+import { type CustomBlockInitial, type InitCustomBlockOptions } from "./notion";
+import type { UseDataSourceResult } from "./types";
+/**
+ * Discriminated state returned by {@link useCustomBlockInit}.
+ *
+ * Branch on `isLoaded`/`error`:
+ * - `{ isLoaded: false, error: undefined }` — handshake in progress.
+ * - `{ isLoaded: false, error: Error }` — handshake failed (most commonly a
+ *   `TimeoutError` because the host never sent `init`).
+ * - `{ isLoaded: true, initial }` — handshake complete; safe to render
+ *   children that call `useTheme`, `useCustomBlockContext`, etc.
+ */
+export type UseCustomBlockInitResult = {
+    isLoaded: false;
+    error: undefined;
+} | {
+    isLoaded: false;
+    error: Error;
+} | {
+    isLoaded: true;
+    error: undefined;
+    initial: CustomBlockInitial;
+};
+/**
+ * React wrapper around {@link initCustomBlock}. Kicks off the SDK ↔ host
+ * handshake on mount and returns a discriminated state object so the rest of
+ * the tree can render inside the `isLoaded === true` branch (where every
+ * other SDK hook is guaranteed to return a populated value).
+ *
+ * Idempotent — multiple components can call this; they share the same
+ * underlying handshake promise.
+ *
+ * @example
+ * function Root() {
+ *   const init = useCustomBlockInit()
+ *   if (init.error) return <p role="alert">Init failed: {init.error.message}</p>
+ *   if (!init.isLoaded) return null
+ *   return <App />
+ * }
+ */
+export declare function useCustomBlockInit(opts?: InitCustomBlockOptions): UseCustomBlockInitResult;
+/**
+ * Props accepted by {@link NotionCustomBlock}.
+ */
+export type NotionCustomBlockProps = InitCustomBlockOptions & {
+    children: ReactNode;
+    /**
+     * Rendered while the SDK ↔ host handshake is in progress. Defaults to
+     * `null` (nothing).
+     */
+    fallback?: ReactNode;
+    /**
+     * Rendered when the handshake fails. Either a node, or a function that
+     * receives the `Error`. When omitted, a small inline `<p role="alert">` is
+     * rendered with the error message — replace it for production templates.
+     */
+    errorFallback?: ReactNode | ((error: Error) => ReactNode);
+    /**
+     * Whether the provider should automatically post resize messages so the
+     * host iframe matches the content height of `#root`. Defaults to `true`.
+     * Pass `false` when you want to use the default block size and are ok
+     * with scrollbars within the Notion client.
+     *
+     * @default true
+     */
+    autoResize?: boolean;
+};
+/**
+ * Top-level wrapper that runs the SDK ↔ host handshake and gates `children`
+ * until it resolves. Passes `timeoutMs` straight through to
+ * {@link initCustomBlock}.
+ *
+ * Templates that prefer not to write a `Root` gating component (or top-level
+ * `await`) can mount their app entirely inside this provider:
+ *
+ * ```tsx
+ * ReactDOM.createRoot(root).render(
+ *   <NotionCustomBlock>
+ *     <App />
+ *   </NotionCustomBlock>,
+ * )
+ * ```
+ *
+ * Inside `children`, every SDK hook is guaranteed to return a populated
+ * value. Outside the provider (or during the loading window), they throw.
+ */
+export declare function NotionCustomBlock({ children, timeoutMs, fallback, errorFallback, autoResize, }: NotionCustomBlockProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Returns the block's location in the document tree. Re-renders when the host sends
+ * `contextChanged` (e.g. the block moves into a different container or its enclosing
+ * page changes).
+ *
+ * Throws if called before `initCustomBlock` has resolved — `await` it before mounting.
+ *
+ * @example
+ * const ctx = useCustomBlockContext()
+ * console.log(ctx.customBlockId, ctx.parent.type)
+ */
+export declare function useCustomBlockContext(): NotionCustomBlockContext;
+/**
+ * Returns the host's current theme. Re-renders on every `themeChanged` message from the host.
+ *
+ * Throws if called before `initCustomBlock` has resolved — `await` it before mounting.
+ *
+ * @example
+ * const theme = useTheme()
+ */
+export declare function useTheme(): NotionTheme;
+/**
+ * Returns the raw data-source definitions — semantic keys plus optional `collectionPointer`,
+ * `collectionSchema`, `propertyIdsByKey`, and derived `propertySchemasById`. Most templates should use
+ * `useDataSource(key)` instead — this hook is for views that render the configuration
+ * itself (debug panels, schema-driven UIs).
+ *
+ * Throws if called before `initCustomBlock` has resolved.
+ */
+export declare function useDataSourceDefinitions(): NotionDataSource[];
+/**
+ * Reads from the data source mapped to the given semantic `key`.
+ *
+ * The first render kicks off a query for the first `initialLimit` items. Calling
+ * `fetchMore()` re-requests a larger prefix (the bridge does not expose cursors yet);
+ * page growth tracks `initialLimit`. The hook automatically resets to `initialLimit`
+ * when the underlying data source definition changes.
+ *
+ * @param key - The semantic data-source key the block is wired to (e.g. `"people"`).
+ * @param initialLimit - Page size for the first query, and the increment used by
+ *   `fetchMore`. Defaults to 20.
+ *
+ * @example
+ * const { items, isLoading, hasMore, fetchMore, error } = useDataSource("default")
+ */
+export declare function useDataSource(key: string, initialLimit?: number): UseDataSourceResult;
+/**
+ * Measures the sandbox's `#root` element and posts `resize` messages so the host iframe
+ * matches the block's content height. Uses `Math.ceil(scrollHeight)` and dedupes
+ * unchanged values.
+ *
+ * `<NotionCustomBlock>` calls this hook for you by default — only reach for it directly
+ * when you need to drive `enabled` yourself (e.g. behind a debug toggle). In that case,
+ * pass `autoResize={false}` to the provider to avoid running it twice. For full-bleed
+ * views that should fill their slot, pass `autoResize={false}` and skip the hook.
+ *
+ * @param args.enabled - When `false`, suspends measurement. Useful for conditional
+ *   measurement (e.g. while a debug toggle is off). Defaults to `true`.
+ *
+ * @example
+ * <NotionCustomBlock autoResize={false}>
+ *   <App />
+ * </NotionCustomBlock>
+ *
+ * function App() {
+ *   const [enabled, setEnabled] = useState(true)
+ *   useCustomBlockAutoResize({ enabled })
+ *   return <div>…</div>
+ * }
+ */
+export declare function useCustomBlockAutoResize(args?: {
+    /**
+     * Whether or not the hook is enabled. To disable this behavior, pass `false`. This is
+     * provided as an argument to allow for conditional disabling of the hook.
+     *
+     * @default true
+     */
+    enabled?: boolean;
+}): void;
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../react.tsx"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,SAAS,EAKd,MAAM,OAAO,CAAA;AACd,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAA;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAEN,KAAK,kBAAkB,EAGvB,KAAK,sBAAsB,EAO3B,MAAM,UAAU,CAAA;AACjB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAA;AAsBlD;;;;;;;;;GASG;AACH,MAAM,MAAM,wBAAwB,GACjC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GACrC;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACjC;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,CAAA;AAEpE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CACjC,IAAI,CAAC,EAAE,sBAAsB,GAC3B,wBAAwB,CA8B1B;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,sBAAsB,GAAG;IAC7D,QAAQ,EAAE,SAAS,CAAA;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,CAAA;IACzD;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,EACjC,QAAQ,EACR,SAAS,EACT,QAAe,EACf,aAAa,EACb,UAAiB,GACjB,EAAE,sBAAsB,2CAyDxB;AAYD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,IAAI,wBAAwB,CAIhE;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,IAAI,WAAW,CAItC;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,gBAAgB,EAAE,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,MAAM,EACX,YAAY,GAAE,MAAwC,GACpD,mBAAmB,CAiDrB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,wBAAwB,CACvC,IAAI,GAAE;IACL;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CACZ,GACJ,IAAI,CAmCN"}

package/dist/react.js

@@ -0,0 +1,284 @@
+import { jsxs as _jsxs, Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useState, useSyncExternalStore, } from "react";
+import { getCustomBlockHostState, getDataSourceQueryView, initCustomBlock, NotInIframeError, postCustomBlockResize, queryCustomBlockDataSource, setMockCustomBlockState, subscribeToCustomBlockHost, } from "./notion";
+const DEFAULT_DATA_SOURCE_QUERY_LIMIT = 20;
+function useCustomBlockHost() {
+    return useSyncExternalStore(subscribeToCustomBlockHost, getCustomBlockHostState);
+}
+function assertInitialized(host, hookName) {
+    if (host.status !== "initialized") {
+        throw new Error(`${hookName} called before \`initCustomBlock\` resolved. Await it before mounting your tree.`);
+    }
+}
+/**
+ * React wrapper around {@link initCustomBlock}. Kicks off the SDK ↔ host
+ * handshake on mount and returns a discriminated state object so the rest of
+ * the tree can render inside the `isLoaded === true` branch (where every
+ * other SDK hook is guaranteed to return a populated value).
+ *
+ * Idempotent — multiple components can call this; they share the same
+ * underlying handshake promise.
+ *
+ * @example
+ * function Root() {
+ *   const init = useCustomBlockInit()
+ *   if (init.error) return <p role="alert">Init failed: {init.error.message}</p>
+ *   if (!init.isLoaded) return null
+ *   return <App />
+ * }
+ */
+export function useCustomBlockInit(opts) {
+    const [state, setState] = useState({
+        isLoaded: false,
+        error: undefined,
+    });
+    useEffect(() => {
+        let cancelled = false;
+        initCustomBlock(opts).then(initial => {
+            if (!cancelled) {
+                setState({ isLoaded: true, error: undefined, initial });
+            }
+        }, err => {
+            if (!cancelled) {
+                setState({
+                    isLoaded: false,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                });
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+        // `initCustomBlock` caches its result, so options after the first call
+        // are ignored — re-running on opts changes would be misleading.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    return state;
+}
+/**
+ * Top-level wrapper that runs the SDK ↔ host handshake and gates `children`
+ * until it resolves. Passes `timeoutMs` straight through to
+ * {@link initCustomBlock}.
+ *
+ * Templates that prefer not to write a `Root` gating component (or top-level
+ * `await`) can mount their app entirely inside this provider:
+ *
+ * ```tsx
+ * ReactDOM.createRoot(root).render(
+ *   <NotionCustomBlock>
+ *     <App />
+ *   </NotionCustomBlock>,
+ * )
+ * ```
+ *
+ * Inside `children`, every SDK hook is guaranteed to return a populated
+ * value. Outside the provider (or during the loading window), they throw.
+ */
+export function NotionCustomBlock({ children, timeoutMs, fallback = null, errorFallback, autoResize = true, }) {
+    const init = useCustomBlockInit({ timeoutMs });
+    useCustomBlockAutoResize({ enabled: autoResize });
+    const isStandalone = init.error instanceof NotInIframeError;
+    const host = useCustomBlockHost();
+    useEffect(() => {
+        if (!isStandalone) {
+            return;
+        }
+        console.warn(`[notion-custom-sdk] ${init.error?.message}`);
+        setMockCustomBlockState({
+            type: "init",
+            theme: "light",
+            context: {
+                customBlockId: "",
+                parent: { id: "", type: "" },
+                page: { id: "" },
+            },
+            dataSources: { bindings: {} },
+        });
+    }, [isStandalone, init.error]);
+    if (init.error && !isStandalone) {
+        if (errorFallback === undefined) {
+            return (_jsxs("p", { role: "alert", children: ["Notion custom view init failed: ", init.error.message] }));
+        }
+        return (_jsx(_Fragment, { children: typeof errorFallback === "function"
+                ? errorFallback(init.error)
+                : errorFallback }));
+    }
+    if (isStandalone) {
+        // Wait for the effect to seed placeholder host state; otherwise hooks
+        // in `children` would throw.
+        if (host.status !== "initialized") {
+            return _jsx(_Fragment, { children: fallback });
+        }
+        return (_jsxs(_Fragment, { children: [_jsx("div", { role: "status", style: STANDALONE_BANNER_STYLE, children: "Notion host not detected \u2014 running in standalone preview. SDK hooks return placeholder values until embedded in Notion." }), children] }));
+    }
+    if (!init.isLoaded) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    return _jsx(_Fragment, { children: children });
+}
+const STANDALONE_BANNER_STYLE = {
+    padding: "8px 12px",
+    background: "#fff8e1",
+    color: "#5d4200",
+    borderBottom: "1px solid #f0d77b",
+    fontSize: 13,
+    fontFamily: "system-ui, sans-serif",
+    lineHeight: 1.4,
+};
+/**
+ * Returns the block's location in the document tree. Re-renders when the host sends
+ * `contextChanged` (e.g. the block moves into a different container or its enclosing
+ * page changes).
+ *
+ * Throws if called before `initCustomBlock` has resolved — `await` it before mounting.
+ *
+ * @example
+ * const ctx = useCustomBlockContext()
+ * console.log(ctx.customBlockId, ctx.parent.type)
+ */
+export function useCustomBlockContext() {
+    const host = useCustomBlockHost();
+    assertInitialized(host, "useCustomBlockContext");
+    return host.context;
+}
+/**
+ * Returns the host's current theme. Re-renders on every `themeChanged` message from the host.
+ *
+ * Throws if called before `initCustomBlock` has resolved — `await` it before mounting.
+ *
+ * @example
+ * const theme = useTheme()
+ */
+export function useTheme() {
+    const host = useCustomBlockHost();
+    assertInitialized(host, "useTheme");
+    return host.theme;
+}
+/**
+ * Returns the raw data-source definitions — semantic keys plus optional `collectionPointer`,
+ * `collectionSchema`, `propertyIdsByKey`, and derived `propertySchemasById`. Most templates should use
+ * `useDataSource(key)` instead — this hook is for views that render the configuration
+ * itself (debug panels, schema-driven UIs).
+ *
+ * Throws if called before `initCustomBlock` has resolved.
+ */
+export function useDataSourceDefinitions() {
+    const host = useCustomBlockHost();
+    assertInitialized(host, "useDataSourceDefinitions");
+    return host.dataSources;
+}
+/**
+ * Reads from the data source mapped to the given semantic `key`.
+ *
+ * The first render kicks off a query for the first `initialLimit` items. Calling
+ * `fetchMore()` re-requests a larger prefix (the bridge does not expose cursors yet);
+ * page growth tracks `initialLimit`. The hook automatically resets to `initialLimit`
+ * when the underlying data source definition changes.
+ *
+ * @param key - The semantic data-source key the block is wired to (e.g. `"people"`).
+ * @param initialLimit - Page size for the first query, and the increment used by
+ *   `fetchMore`. Defaults to 20.
+ *
+ * @example
+ * const { items, isLoading, hasMore, fetchMore, error } = useDataSource("default")
+ */
+export function useDataSource(key, initialLimit = DEFAULT_DATA_SOURCE_QUERY_LIMIT) {
+    const host = useCustomBlockHost();
+    const [limit, setLimit] = useState(initialLimit);
+    const matchingDataSource = host.status === "initialized"
+        ? host.dataSources.find(dataSource => dataSource.key === key)
+        : undefined;
+    // Serialize to avoid re-querying when `dataSourcesChanged` rebuilds the array with equal entries.
+    const matchingSignature = matchingDataSource
+        ? JSON.stringify(matchingDataSource)
+        : null;
+    useEffect(() => {
+        // A new key or source definition means we should restart from the initial page size.
+        setLimit(initialLimit);
+    }, [matchingSignature, key, initialLimit]);
+    const isInitialized = host.status === "initialized";
+    useEffect(() => {
+        if (!isInitialized) {
+            return;
+        }
+        queryCustomBlockDataSource(key, limit);
+    }, [matchingSignature, isInitialized, key, limit]);
+    const view = getDataSourceQueryView(host, key);
+    const fetchMore = useCallback(() => {
+        if (!view.hasMore || view.isLoading) {
+            return;
+        }
+        // The bridge does not expose cursors yet, so "fetch more" means re-requesting a
+        // larger prefix of items and letting the host return the expanded result set.
+        // Page growth tracks the caller-provided `initialLimit` so templates can opt
+        // into larger batches.
+        setLimit(currentLimit => currentLimit + initialLimit);
+    }, [view.hasMore, view.isLoading, initialLimit]);
+    return {
+        items: view.items,
+        collectionSchema: view.collectionSchema,
+        propertySchemasById: view.propertySchemasById,
+        propertySchemasByKey: view.propertySchemasByKey,
+        isLoading: view.isLoading,
+        hasMore: view.hasMore,
+        fetchMore,
+        error: view.error,
+    };
+}
+/**
+ * Measures the sandbox's `#root` element and posts `resize` messages so the host iframe
+ * matches the block's content height. Uses `Math.ceil(scrollHeight)` and dedupes
+ * unchanged values.
+ *
+ * `<NotionCustomBlock>` calls this hook for you by default — only reach for it directly
+ * when you need to drive `enabled` yourself (e.g. behind a debug toggle). In that case,
+ * pass `autoResize={false}` to the provider to avoid running it twice. For full-bleed
+ * views that should fill their slot, pass `autoResize={false}` and skip the hook.
+ *
+ * @param args.enabled - When `false`, suspends measurement. Useful for conditional
+ *   measurement (e.g. while a debug toggle is off). Defaults to `true`.
+ *
+ * @example
+ * <NotionCustomBlock autoResize={false}>
+ *   <App />
+ * </NotionCustomBlock>
+ *
+ * function App() {
+ *   const [enabled, setEnabled] = useState(true)
+ *   useCustomBlockAutoResize({ enabled })
+ *   return <div>…</div>
+ * }
+ */
+export function useCustomBlockAutoResize(args = {}) {
+    const { enabled = true } = args;
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        if (typeof window === "undefined") {
+            return;
+        }
+        const target = document.getElementById("root");
+        if (!(target instanceof HTMLElement)) {
+            return;
+        }
+        let lastHeight = -1;
+        const post = () => {
+            const next = Math.ceil(target.scrollHeight);
+            if (next === lastHeight) {
+                return;
+            }
+            lastHeight = next;
+            postCustomBlockResize(next);
+        };
+        post();
+        if (typeof ResizeObserver === "undefined") {
+            return;
+        }
+        const observer = new ResizeObserver(post);
+        observer.observe(target);
+        return () => {
+            observer.disconnect();
+        };
+    }, [enabled]);
+}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+import type { NotionCollectionSchema } from "./bridge/dataSources/dataSource";
+import type { NotionDataSourcePage, NotionDataSourcePageUpdateInput, NotionDataSourcePageUpdateResult } from "./bridge/dataSources/dataSourcePage";
+import type { NotionPropertySchema } from "./bridge/dataSources/propertySchema";
+import type { NotionDataSourceId } from "./bridge/ids";
+import type { NotionCreatePagePosition } from "./bridge/messages/createPage";
+import type { NotionPage, NotionPageCover, NotionPageIcon, NotionPageId, NotionPagePropertyInputMap, NotionPagePropertyWriteMap } from "./bridge/pages/page";
+export type { NotionDataSourceId, NotionSpaceId } from "./bridge/ids";
+export type { NotionPageId } from "./bridge/pages/page";
+export type { NotionDataSourcePageUpdateInput, NotionDataSourcePageUpdateResult, };
+/**
+ * Return shape of `useDataSource`.
+ *
+ * - `items` — the rows the host has returned so far. Empty until the first response arrives.
+ * - `isLoading` — `true` while a query is in flight.
+ * - `hasMore` — `true` if the host indicated more rows are available beyond the current page.
+ * - `fetchMore` — re-requests a larger prefix of items (no-op while loading or when
+ *   `hasMore` is `false`). The page grows by `initialLimit` per call.
+ * - `error` — a human-readable error string if the most recent query failed.
+ */
+export type UseDataSourceResult = {
+    items: NotionDataSourcePage[];
+    /**
+     * Collection/data-source schema for the bound Notion data source, including raw property
+     * schemas. Undefined when the semantic data-source key has not been bound.
+     */
+    collectionSchema?: NotionCollectionSchema;
+    /**
+     * Per-property schemas keyed by raw property ID, including the four synthetic built-ins
+     * (`created_time`, `last_edited_time`, `created_by`, `last_edited_by`).
+     */
+    propertySchemasById: {
+        [propertyId: string]: NotionPropertySchema;
+    };
+    /**
+     * Per-property schemas keyed by user-defined keys from the data source's `propertyIdsByKey`.
+     * Built-ins are NOT included here. Keys mapped to `undefined` indicate a declared-but-unbound
+     * slot.
+     */
+    propertySchemasByKey: {
+        [key: string]: NotionPropertySchema | undefined;
+    };
+    isLoading: boolean;
+    hasMore: boolean;
+    fetchMore: () => void;
+    error?: string;
+};
+/**
+ * Parent reference accepted by `sdk.pages.create`. Mirrors Notion's public `POST /v1/pages`
+ * parent shape; see https://developers.notion.com/reference/data-source.
+ *
+ * - `page_id`: Create a child page under the given Notion page.
+ * - `data_source_id`: Create a row inside the given Notion data source (aka the internal
+ *   collection). The public API's `data_source_id` is the same UUID as the `collectionPointer.id`
+ *   exposed in `dataSources`, so either value works here.
+ * - `data_source_key`: Create a row inside the data source that the custom block was configured with
+ *   under this semantic key. The SDK resolves the key to a `data_source_id` locally before
+ *   sending the request to the host.
+ */
+export type CreatePageParent = {
+    type: "page_id";
+    page_id: NotionPageId;
+} | {
+    type: "data_source_id";
+    data_source_id: NotionDataSourceId;
+} | {
+    type: "data_source_key";
+    key: string;
+};
+/**
+ * Input accepted by `sdk.pages.create`. Mirrors the Notion public API `POST /v1/pages` API.
+ */
+export type CreatePageInput = {
+    parent: CreatePageParent;
+    properties: NotionPagePropertyInputMap;
+    icon?: NotionPageIcon;
+    cover?: NotionPageCover;
+    position?: NotionCreatePagePosition;
+};
+/**
+ * The result of a `sdk.pages.create` API call.
+ */
+export type CreatePageResult = {
+    status: "success";
+    /** The newly created page. */
+    page: NotionPage;
+} | {
+    status: "error";
+    error: string;
+};
+/**
+ * Input accepted by `sdk.pages.update`.
+ *
+ * `properties` is keyed by raw Notion property ID. To update a row with configured
+ * custom-block property keys, use the `update` helper on pages returned from
+ * `useDataSource`.
+ */
+export type UpdatePageInput = {
+    pageId: NotionPageId;
+    properties?: NotionPagePropertyWriteMap;
+    icon?: NotionPageIcon;
+    cover?: NotionPageCover;
+    archived?: boolean;
+};
+/**
+ * Result of `sdk.pages.get`.
+ */
+export type GetPageResult = {
+    status: "success";
+    page: NotionPage;
+} | {
+    status: "error";
+    error: string;
+};
+/**
+ * Result of `sdk.pages.update` / `sdk.pages.delete`.
+ */
+export type UpdatePageResult = {
+    status: "success";
+    page: NotionPage;
+} | {
+    status: "error";
+    error: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

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

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function unreachable(value: never): never;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAI/C"}

package/dist/utils.js

@@ -0,0 +1,10 @@
+/**
+ * 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) {
+    throw new Error(`[notion-custom-sdk] Unexpected value encountered: ${JSON.stringify(value)}`);
+}