@goodtek/vibeops 0.2.0

package/dist/lib/notion-client.js

@@ -0,0 +1,459 @@
+/**
+ * Thin async wrapper around `@notionhq/client`.
+ *
+ * We lazy-import the SDK so that:
+ *   - other commands (init / status / plan / task / …) don't pay the import
+ *     cost when Notion is disabled,
+ *   - a missing or broken install of `@notionhq/client` doesn't crash the
+ *     entire CLI — only the notion subcommands.
+ *
+ * The wrapper exposes the surface VibeOps actually uses:
+ *   - `users.me()` to validate the token,                            (TASK-010)
+ *   - `databases.retrieve(id)` to verify access + schema,            (TASK-010)
+ *   - `dataSources.retrieve(id)` to read the actual schema (new API), (TASK-011 follow-up)
+ *   - `databases.query(id, filter, page_size)` to look up a row,     (TASK-011)
+ *   - `pages.create({ parent, properties })` to insert,              (TASK-011)
+ *   - `pages.update({ page_id, properties })` to upsert in place,    (TASK-011)
+ *   - `search({ filter: { value: "data_source" }})` to discover DBs. (TASK-010 UX)
+ *   - `blocks.children.list(block_id, page_size, start_cursor)` to walk
+ *     the 1-depth children of a page when we need to find inline databases
+ *     that Notion search doesn't surface.                                (TASK-010 UX)
+ *
+ * Network calls have a 5s timeout (per TASK-010 Risks).
+ *
+ * Notion API note (TASK-011 follow-up):
+ *   In the current Notion API ("2025-09-03" and later), a `database` is a
+ *   shell that can contain 0…N `data_source` children. Property schema lives
+ *   on the `data_source`, not on the `database`. VibeOps therefore exposes
+ *   `databasesRetrieve(id)` (returns `{ id, object, data_sources, ... }`)
+ *   AND `dataSourcesRetrieve(id)` (returns `{ id, object, properties, ... }`)
+ *   so the resolver (`notion-target.ts`) can fall back between them.
+ */
+const NOTION_API_TIMEOUT_MS = 5_000;
+/**
+ * Notion API version VibeOps pins on every Client construction.
+ *
+ * `"2025-09-03"` is the first version in which `database.retrieve` returns
+ * `{ object: "database", data_sources: [...] }` and the property schema
+ * (`properties`) lives on `data_source` objects rather than on the
+ * `database` shell. VibeOps' resolver (`notion-target.ts`) targets that
+ * surface. Bumping this constant later requires re-validating the resolver
+ * + schema validator against the new response shape.
+ */
+export const NOTION_API_VERSION = "2025-09-03";
+/**
+ * Defensive normaliser for the `data_sources` child array on a
+ * `databases.retrieve` response.
+ *
+ * Why this exists: Notion's official surface uses `data_sources`
+ * (snake_case), but VibeOps has seen / expects to support multiple naming
+ * shapes — `dataSources`, `child_data_sources`, `childDataSources` — as
+ * well as entries that wrap the id under `data_source.id` instead of `id`.
+ * This helper picks the first non-empty array it finds and normalises each
+ * entry to `{ id, name? }`. Returns `[]` when nothing usable is present.
+ *
+ * Tuple in the returned diagnostic: `[fieldName, items[]]` — `fieldName` is
+ * `null` when no array key was located, useful for `--debug-shape`.
+ */
+export function extractDataSourcesFromDatabaseResponse(response) {
+    if (response === null || typeof response !== "object") {
+        return { field: null, items: [] };
+    }
+    const obj = response;
+    // Order matters: prefer the canonical snake_case if both styles appear.
+    const candidates = [
+        "data_sources",
+        "dataSources",
+        "child_data_sources",
+        "childDataSources",
+    ];
+    for (const key of candidates) {
+        const raw = obj[key];
+        if (!Array.isArray(raw))
+            continue;
+        if (raw.length === 0) {
+            // remember we saw the array even if empty (so the caller can show
+            // `field=data_sources, len=0` instead of `field=null, len=0`).
+            return { field: key, items: [] };
+        }
+        const items = raw
+            .map((entry) => {
+            if (entry === null || typeof entry !== "object")
+                return null;
+            const e = entry;
+            // Accept `id` OR `data_source.id` (some payloads nest the id).
+            const directId = typeof e.id === "string" ? e.id : "";
+            const nestedRaw = e.data_source !== undefined && typeof e.data_source === "object"
+                ? e.data_source
+                : null;
+            const nestedId = nestedRaw !== null && typeof nestedRaw.id === "string"
+                ? nestedRaw.id
+                : "";
+            const id = directId.length > 0 ? directId : nestedId;
+            if (id.length === 0)
+                return null;
+            // Pick the friendliest name: e.name, e.data_source.name, e.title text.
+            let name;
+            if (typeof e.name === "string" && e.name.length > 0) {
+                name = e.name;
+            }
+            else if (nestedRaw !== null &&
+                typeof nestedRaw.name === "string" &&
+                nestedRaw.name.length > 0) {
+                name = nestedRaw.name;
+            }
+            else if (Array.isArray(e.title)) {
+                const t = e.title
+                    .map((seg) => seg.plain_text ?? "")
+                    .join("")
+                    .trim();
+                if (t.length > 0)
+                    name = t;
+            }
+            return name === undefined ? { id } : { id, name };
+        })
+            .filter((x) => x !== null);
+        return { field: key, items };
+    }
+    return { field: null, items: [] };
+}
+/**
+ * Build a token-safe {@link DatabaseShapeProbe} from a raw retrieve
+ * response. Splits out from `probeDatabaseShape` so unit tests can hit it
+ * directly without an SDK client.
+ */
+export function summariseDatabaseShape(inputId, raw) {
+    if (raw === null || typeof raw !== "object") {
+        return {
+            inputId,
+            object: "(unknown)",
+            id: inputId,
+            hasProperties: false,
+            propertiesKeysLength: 0,
+            hasDataSources: false,
+            dataSourcesLength: 0,
+            dataSources: [],
+            topLevelKeys: [],
+        };
+    }
+    const obj = raw;
+    const object = typeof obj.object === "string" ? obj.object : "(unknown)";
+    const id = typeof obj.id === "string" && obj.id.length > 0 ? obj.id : inputId;
+    let title;
+    if (Array.isArray(obj.title)) {
+        const text = obj.title
+            .map((seg) => seg.plain_text ?? "")
+            .join("")
+            .trim();
+        if (text.length > 0)
+            title = text;
+    }
+    else if (typeof obj.title === "string" && obj.title.length > 0) {
+        title = obj.title;
+    }
+    else if (typeof obj.name === "string" && obj.name.length > 0) {
+        title = obj.name;
+    }
+    const props = obj.properties;
+    const hasProperties = props !== null && props !== undefined && typeof props === "object";
+    const propertiesKeysLength = hasProperties
+        ? Object.keys(props).length
+        : 0;
+    const ds = extractDataSourcesFromDatabaseResponse(raw);
+    const topLevelKeys = Object.keys(obj).sort();
+    return {
+        inputId,
+        object,
+        id,
+        ...(title !== undefined ? { title } : {}),
+        hasProperties,
+        propertiesKeysLength,
+        hasDataSources: ds.field !== null,
+        ...(ds.field !== null ? { dataSourcesField: ds.field } : {}),
+        dataSourcesLength: ds.items.length,
+        dataSources: ds.items,
+        topLevelKeys,
+    };
+}
+export function notionApiError(err) {
+    const e = err;
+    return {
+        ok: false,
+        code: typeof e.code === "string" ? e.code : "unknown_error",
+        ...(typeof e.status === "number" ? { status: e.status } : {}),
+        message: typeof e.message === "string" ? e.message : String(err),
+    };
+}
+export async function createNotionClient(token) {
+    // Use a dynamic specifier so TS/Node import this lazily even under
+    // `--noEmitOnError`. Missing dep → caller catches and surfaces a friendly
+    // "install @notionhq/client" message.
+    const modSpecifier = "@notionhq/client";
+    const mod = await import(/* @vite-ignore */ modSpecifier);
+    const ClientCtor = mod.Client ??
+        mod.default?.Client;
+    if (typeof ClientCtor !== "function") {
+        throw new Error("Could not find `Client` export in `@notionhq/client`. Re-install the dependency: `pnpm add @notionhq/client`.");
+    }
+    // `notionVersion: "2025-09-03"` pins the Notion API version VibeOps was
+    // designed against. In this revision the schema (`properties`) lives on
+    // `data_source` objects rather than on the `database` shell, so this pin
+    // makes the response shape deterministic regardless of what default the
+    // installed `@notionhq/client` build chose.
+    //
+    // `logLevel: "error"` suppresses the SDK's WARN-level "request fail"
+    // chatter that otherwise polutes stderr on expected 4xx (e.g. when the
+    // resolver intentionally probes `dataSources.retrieve(id)` and gets a 404
+    // before falling back to `databases.retrieve(id)`). Real errors still
+    // throw; this only silences the SDK's diagnostic console.warn.
+    const client = new ClientCtor({
+        auth: token,
+        timeoutMs: NOTION_API_TIMEOUT_MS,
+        logLevel: "error",
+        notionVersion: NOTION_API_VERSION,
+    });
+    return {
+        async usersMe() {
+            const res = (await client.users.me({}));
+            return res;
+        },
+        async databasesRetrieve(databaseId) {
+            const res = (await client.databases.retrieve({
+                database_id: databaseId,
+            }));
+            return res;
+        },
+        async retrieveDatabase(databaseId) {
+            const res = (await client.databases.retrieve({
+                database_id: databaseId,
+            }));
+            return res;
+        },
+        async dataSourcesRetrieve(dataSourceId) {
+            // (A) preferred — typed SDK call when present.
+            if (client.dataSources !== undefined &&
+                typeof client.dataSources.retrieve === "function") {
+                const res = (await client.dataSources.retrieve({
+                    data_source_id: dataSourceId,
+                }));
+                return res;
+            }
+            // (B) raw HTTP fallback via SDK's public arbitrary-request helper.
+            // The SDK already attaches Authorization / Notion-Version / JSON
+            // headers, so we never touch the token from here.
+            if (typeof client.request === "function") {
+                const res = (await client.request({
+                    path: `data_sources/${dataSourceId}`,
+                    method: "GET",
+                }));
+                return res;
+            }
+            // (C) neither path available — let the resolver decide what to do.
+            return null;
+        },
+        async retrieveDataSource(dataSourceId) {
+            if (client.dataSources !== undefined &&
+                typeof client.dataSources.retrieve === "function") {
+                const res = (await client.dataSources.retrieve({
+                    data_source_id: dataSourceId,
+                }));
+                return res;
+            }
+            if (typeof client.request === "function") {
+                const res = (await client.request({
+                    path: `data_sources/${dataSourceId}`,
+                    method: "GET",
+                }));
+                return res;
+            }
+            return null;
+        },
+        async probeDatabaseShape(databaseId) {
+            const raw = (await client.databases.retrieve({
+                database_id: databaseId,
+            }));
+            return summariseDatabaseShape(databaseId, raw);
+        },
+        async databasesQuery(databaseId, options) {
+            const q = {};
+            if (options?.filter !== undefined)
+                q.filter = options.filter;
+            if (typeof options?.pageSize === "number")
+                q.page_size = options.pageSize;
+            if (typeof options?.startCursor === "string")
+                q.start_cursor = options.startCursor;
+            const res = (await (client.dataSources?.query !== undefined
+                ? client.dataSources.query({ ...q, data_source_id: databaseId })
+                : client.databases.query({ ...q, database_id: databaseId })));
+            return {
+                results: res.results ?? [],
+                hasMore: res.has_more === true,
+                nextCursor: res.next_cursor ?? null,
+            };
+        },
+        async pagesCreate({ databaseId, properties }) {
+            let res;
+            try {
+                res = (await client.pages.create({
+                    parent: { data_source_id: databaseId },
+                    properties,
+                }));
+            }
+            catch (err) {
+                const apiErr = notionApiError(err);
+                if (apiErr.code !== "validation_error" && apiErr.code !== "object_not_found") {
+                    throw err;
+                }
+                // Legacy fallback for older configs that still store database ids.
+                res = (await client.pages.create({
+                    parent: { database_id: databaseId },
+                    properties,
+                }));
+            }
+            return { id: res.id };
+        },
+        async queryDataSource(dataSourceId, options) {
+            const body = {};
+            if (options?.filter !== undefined)
+                body.filter = options.filter;
+            if (typeof options?.pageSize === "number")
+                body.page_size = options.pageSize;
+            if (typeof options?.startCursor === "string")
+                body.start_cursor = options.startCursor;
+            let raw;
+            // (A) typed SDK call when the installed build exposes `dataSources.query`.
+            if (client.dataSources !== undefined &&
+                typeof client.dataSources.query === "function") {
+                raw = (await client.dataSources.query({
+                    data_source_id: dataSourceId,
+                    ...body,
+                }));
+            }
+            else if (typeof client.request === "function") {
+                // (B) raw HTTP fallback — SDK attaches Authorization / Notion-Version /
+                // Content-Type headers itself; we never touch the token from here.
+                raw = (await client.request({
+                    path: `data_sources/${dataSourceId}/query`,
+                    method: "POST",
+                    body,
+                }));
+            }
+            else {
+                throw new Error("`@notionhq/client` does not expose `dataSources.query` nor `client.request`; cannot query data source.");
+            }
+            return {
+                results: Array.isArray(raw.results) ? raw.results : [],
+                hasMore: raw.has_more === true,
+                nextCursor: raw.next_cursor ?? null,
+            };
+        },
+        async createPageInDataSource({ dataSourceId, properties }) {
+            const body = {
+                parent: { type: "data_source_id", data_source_id: dataSourceId },
+                properties,
+            };
+            // (A) typed SDK call first — `parent` is typed as `unknown` in our cast
+            // so the new shape passes through transparently.
+            try {
+                const res = (await client.pages.create(body));
+                return { id: res.id };
+            }
+            catch (err) {
+                const apiErr = notionApiError(err);
+                // Only fall back when the SDK itself rejected the shape (validation
+                // error on the SDK side). 401/403/404/429 must propagate so the
+                // caller can show the precise reason.
+                if (apiErr.code !== "validation_error") {
+                    throw err;
+                }
+                if (typeof client.request !== "function")
+                    throw err;
+                const res = (await client.request({
+                    path: "pages",
+                    method: "POST",
+                    body,
+                }));
+                return { id: res.id };
+            }
+        },
+        async pagesUpdate({ pageId, properties }) {
+            const res = (await client.pages.update({
+                page_id: pageId,
+                properties,
+            }));
+            return { id: res.id };
+        },
+        async updatePage({ pageId, properties }) {
+            const res = (await client.pages.update({
+                page_id: pageId,
+                properties,
+            }));
+            return { id: res.id };
+        },
+        async blocksChildrenList({ blockId, pageSize, startCursor }) {
+            const q = {
+                block_id: blockId,
+            };
+            // Notion API hard-caps page_size at 100; we keep ≤ 50 for snappy UX
+            // unless a caller asks for more, but never above 100.
+            const ps = typeof pageSize === "number" ? Math.min(100, Math.max(1, pageSize)) : 50;
+            q.page_size = ps;
+            if (typeof startCursor === "string")
+                q.start_cursor = startCursor;
+            const res = (await client.blocks.children.list(q));
+            return {
+                results: Array.isArray(res.results) ? res.results : [],
+                hasMore: res.has_more === true,
+                nextCursor: res.next_cursor ?? null,
+            };
+        },
+        async listBlockChildren(blockId, options) {
+            const q = {
+                block_id: blockId,
+            };
+            q.page_size =
+                typeof options?.limit === "number"
+                    ? Math.min(100, Math.max(1, options.limit))
+                    : 50;
+            if (typeof options?.startCursor === "string") {
+                q.start_cursor = options.startCursor;
+            }
+            const res = (await client.blocks.children.list(q));
+            return {
+                results: Array.isArray(res.results) ? res.results : [],
+                hasMore: res.has_more === true,
+                nextCursor: res.next_cursor ?? null,
+            };
+        },
+        async search(options) {
+            const q = {};
+            if (typeof options?.query === "string")
+                q.query = options.query;
+            if (options?.objectFilter !== undefined)
+                q.filter = { property: "object", value: options.objectFilter };
+            q.page_size = typeof options?.pageSize === "number" ? options.pageSize : 50;
+            if (typeof options?.startCursor === "string")
+                q.start_cursor = options.startCursor;
+            const res = (await client.search(q));
+            return {
+                results: Array.isArray(res.results) ? res.results : [],
+                hasMore: res.has_more === true,
+                nextCursor: res.next_cursor ?? null,
+            };
+        },
+        async searchPages(query) {
+            const q = {
+                filter: { property: "object", value: "page" },
+                page_size: 50,
+            };
+            if (typeof query === "string" && query.length > 0)
+                q.query = query;
+            const res = (await client.search(q));
+            return {
+                results: Array.isArray(res.results) ? res.results : [],
+                hasMore: res.has_more === true,
+                nextCursor: res.next_cursor ?? null,
+            };
+        },
+    };
+}