@kweaver-ai/kweaver-sdk 0.4.10 → 0.4.12

package/README.md

@@ -90,6 +90,29 @@ const graph     = await client.bkn.querySubgraph("bkn-id", { /* path spec */ });
 await client.bkn.executeAction("bkn-id", "at-id", { /* params */ });
 const logs      = await client.bkn.listActionLogs("bkn-id");
 
+// Data sources & data views
+const dsList = await client.datasources.list();
+const tables = await client.datasources.listTables("ds-id");
+const viewId = await client.dataviews.create({ name: "v", datasourceId: "ds-id", table: "orders" });
+const views = await client.dataviews.list({ datasourceId: "ds-id" });
+const fuzzy = await client.dataviews.find("BOM", { wait: false });
+const exact = await client.dataviews.find("orders", {
+  datasourceId: "ds-id",
+  exact: true,
+  wait: true,
+});
+const dv = await client.dataviews.get(viewId);
+
+// Dataflow automation (CSV import pipeline, etc.)
+const result = await client.dataflows.execute({
+  title: "import", trigger_config: { operator: "manual" },
+  steps: [{ id: "s1", title: "load", operator: "csv_import", parameters: {} }],
+});
+
+// Vega observability
+const catalogs = await client.vega.listCatalogs();
+const health   = await client.vega.health();
+
 // Context Loader (semantic search over a BKN via MCP)
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
 const results = await cl.search({ query: "hypertension treatment" });
@@ -98,16 +121,24 @@ const results = await cl.search({ query: "hypertension treatment" });
 ## CLI Reference
 
 ```
-kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] — also: status, list, use, delete, logout
+kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] [--insecure|-k] — also: status, list, use, delete, logout
 kweaver token
+kweaver config show / set-bd <value>
+kweaver ds list/get/delete/tables/connect
+kweaver ds import-csv <ds_id> --files <glob> [--table-prefix <p>] [--batch-size 500]
+kweaver dataview list/find/get/delete
 kweaver bkn list/get/stats/export/create/update/delete
+kweaver bkn create-from-ds <ds_id> --name <name> [--tables t1,t2] [--build]
+kweaver bkn create-from-csv <ds_id> --files <glob> --name <name> [--build]
+kweaver bkn validate/push/pull
 kweaver bkn object-type list/get/create/update/delete/query/properties
 kweaver bkn relation-type list/get/create/update/delete
 kweaver bkn action-type list/query/execute
-kweaver bkn subgraph
+kweaver bkn subgraph / search
 kweaver bkn action-execution get
 kweaver bkn action-log list/get/cancel
-kweaver agent list/get/chat/sessions/history
+kweaver agent list/get/create/update/delete/chat/sessions/history/publish/unpublish
+kweaver vega health/stats/inspect/catalog/resource/connector-type
 kweaver context-loader config set/use/list/show
 kweaver context-loader kn-search/query-object-instance/...
 kweaver call <path> [-X METHOD] [-d BODY] [-H header]
@@ -120,6 +151,33 @@ kweaver call <path> [-X METHOD] [-d BODY] [-H header]
 | `KWEAVER_BASE_URL` | KWeaver instance URL |
 | `KWEAVER_BUSINESS_DOMAIN` | Business domain identifier |
 | `KWEAVER_TOKEN` | Access token |
+| `KWEAVER_TLS_INSECURE` | Set to `1` or `true` to skip TLS certificate verification for all HTTPS in the process (dev only; prefer `kweaver auth … --insecure` which saves per platform) |
+| `NODE_TLS_REJECT_UNAUTHORIZED` | Node.js built-in TLS switch: set to `0` to skip certificate verification for HTTPS in this process. The `kweaver` CLI sets this when `KWEAVER_TLS_INSECURE` is set or the saved token has insecure TLS (same scope as above; dev only). |
+
+### TLS Certificate Troubleshooting
+
+If you encounter errors like `fetch failed`, `self-signed certificate`, or `UNABLE_TO_GET_ISSUER_CERT`, the target server likely uses a self-signed certificate or Kubernetes Ingress default fake certificate. Try the following in order of preference:
+
+1. **Recommended (persists per platform)** — add `--insecure` during login:
+   ```bash
+   kweaver auth login https://your-host --insecure
+   # or shorthand
+   kweaver auth login https://your-host -k
+   ```
+   The flag is saved to `token.json` in `~/.kweaver/`, so all subsequent CLI commands for that platform skip TLS verification automatically.
+
+2. **Temporary (current shell)** — set an environment variable:
+   ```bash
+   export KWEAVER_TLS_INSECURE=1
+   kweaver bkn list
+   ```
+
+3. **Node.js native** — set `NODE_TLS_REJECT_UNAUTHORIZED` directly:
+   ```bash
+   NODE_TLS_REJECT_UNAUTHORIZED=0 kweaver bkn list
+   ```
+
+> **Security note:** All of the above disable HTTPS certificate verification and should only be used in development or internal network environments. Use trusted CA-signed certificates in production.
 
 ## Using with AI Agents
 

package/README.zh.md

@@ -90,6 +90,18 @@ const graph     = await client.bkn.querySubgraph("bkn-id", { /* 路径规格 */
 await client.bkn.executeAction("bkn-id", "at-id", { /* 参数 */ });
 const logs      = await client.bkn.listActionLogs("bkn-id");
 
+// 数据源与数据视图
+const dsList = await client.datasources.list();
+const viewId = await client.dataviews.create({ name: "v", datasourceId: "ds-id", table: "orders" });
+const views = await client.dataviews.list({ datasourceId: "ds-id" });
+const fuzzy = await client.dataviews.find("BOM", { wait: false });
+const exact = await client.dataviews.find("orders", {
+  datasourceId: "ds-id",
+  exact: true,
+  wait: true,
+});
+const dv = await client.dataviews.get(viewId);
+
 // Context Loader（通过 MCP 对 BKN 做语义搜索）
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
 const results = await cl.search({ query: "高血压 治疗" });
@@ -98,8 +110,10 @@ const results = await cl.search({ query: "高血压 治疗" });
 ## 命令速查
 
 ```
-kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] — 另有 status、list、use、delete、logout
+kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] [--insecure|-k] — 另有 status、list、use、delete、logout
 kweaver token
+kweaver ds list/get/delete/tables/connect
+kweaver dataview list/find/get/delete
 kweaver bkn list/get/stats/export/create/update/delete
 kweaver bkn object-type list/get/create/update/delete/query/properties
 kweaver bkn relation-type list/get/create/update/delete
@@ -120,6 +134,33 @@ kweaver call <path> [-X METHOD] [-d BODY] [-H header]
 | `KWEAVER_BASE_URL` | KWeaver 实例地址 |
 | `KWEAVER_BUSINESS_DOMAIN` | 业务域标识 |
 | `KWEAVER_TOKEN` | 访问令牌 |
+| `KWEAVER_TLS_INSECURE` | 设为 `1` 或 `true` 时跳过 TLS 证书校验（仅开发；更推荐 `kweaver auth … --insecure` 以按平台持久化） |
+| `NODE_TLS_REJECT_UNAUTHORIZED` | Node.js 内置 TLS 开关：设为 `0` 时在本进程内跳过 HTTPS 证书校验。`kweaver` 在 `KWEAVER_TLS_INSECURE` 生效或已保存 token 为不安全 TLS 时会设置此项（范围同上；仅开发）。 |
+
+### TLS 证书问题排查
+
+如果遇到 `fetch failed`、`self-signed certificate`、`UNABLE_TO_GET_ISSUER_CERT` 等 TLS 相关错误，通常是目标服务器使用了自签名证书或 Kubernetes Ingress 默认假证书。可按优先级尝试以下方案：
+
+1. **推荐（按平台持久化）** — 登录时加 `--insecure`：
+   ```bash
+   kweaver auth login https://your-host --insecure
+   # 或简写
+   kweaver auth login https://your-host -k
+   ```
+   该标记会写入 `~/.kweaver/` 的 `token.json`，后续所有 CLI 命令对该平台自动生效，无需额外操作。
+
+2. **临时生效（当前 shell）** — 设置环境变量：
+   ```bash
+   export KWEAVER_TLS_INSECURE=1
+   kweaver bkn list
+   ```
+
+3. **Node.js 原生方式** — 直接设置 `NODE_TLS_REJECT_UNAUTHORIZED`：
+   ```bash
+   NODE_TLS_REJECT_UNAUTHORIZED=0 kweaver bkn list
+   ```
+
+> **安全提示：** 以上方式均会跳过 HTTPS 证书校验，仅适用于开发/内网环境。生产环境请使用受信任的 CA 签发证书。
 
 ## 在 AI 智能体中使用
 

package/dist/api/dataflow.d.ts

@@ -0,0 +1,78 @@
+export interface DataflowStep {
+    id: string;
+    title: string;
+    operator: string;
+    parameters: Record<string, unknown>;
+}
+export interface DataflowCreateBody {
+    title: string;
+    description?: string;
+    trigger_config: {
+        operator: string;
+    };
+    steps: DataflowStep[];
+}
+export interface DataflowResult {
+    status: "success" | "completed" | "failed" | "error";
+    reason?: string;
+}
+export interface CreateDataflowOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    body: DataflowCreateBody;
+}
+/**
+ * Create a new dataflow (DAG). Returns the new DAG id.
+ */
+export declare function createDataflow(options: CreateDataflowOptions): Promise<string>;
+export interface RunDataflowOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    dagId: string;
+}
+/**
+ * Trigger a run for an existing dataflow DAG.
+ */
+export declare function runDataflow(options: RunDataflowOptions): Promise<void>;
+export interface PollDataflowOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    dagId: string;
+    /** Poll interval in seconds. Default: 3 */
+    interval?: number;
+    /** Maximum time to wait in seconds. Default: 900 */
+    timeout?: number;
+}
+/**
+ * Poll GET /api/automation/v1/dag/{dagId}/results until the run is done.
+ * Throws on "failed"/"error" status or timeout.
+ */
+export declare function pollDataflowResults(options: PollDataflowOptions): Promise<DataflowResult>;
+export interface DeleteDataflowOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    dagId: string;
+}
+/**
+ * Delete a dataflow DAG. Best-effort — does not throw on errors.
+ */
+export declare function deleteDataflow(options: DeleteDataflowOptions): Promise<void>;
+export interface ExecuteDataflowOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    body: DataflowCreateBody;
+    /** Poll interval in seconds. Default: 3 */
+    interval?: number;
+    /** Maximum polling time in seconds. Default: 900 */
+    timeout?: number;
+}
+/**
+ * Full dataflow lifecycle: create → run → poll → delete (always, even on error).
+ * Returns the final DataflowResult.
+ */
+export declare function executeDataflow(options: ExecuteDataflowOptions): Promise<DataflowResult>;

package/dist/api/dataflow.js

@@ -0,0 +1,135 @@
+import { HttpError } from "../utils/http.js";
+function buildHeaders(accessToken, businessDomain) {
+    return {
+        accept: "application/json, text/plain, */*",
+        "accept-language": "zh-cn",
+        authorization: `Bearer ${accessToken}`,
+        token: accessToken,
+        "x-business-domain": businessDomain,
+        "x-language": "zh-cn",
+    };
+}
+function debugLog(method, url, headers, body) {
+    if (!process.env["KWEAVER_DEBUG_HTTP"])
+        return;
+    const masked = { ...headers };
+    if (masked.authorization)
+        masked.authorization = masked.authorization.slice(0, 20) + "…";
+    if (masked.token)
+        masked.token = masked.token.slice(0, 20) + "…";
+    process.stderr.write(`[debug] ${method} ${url}\n`);
+    process.stderr.write(`[debug] headers: ${JSON.stringify(masked)}\n`);
+    if (body)
+        process.stderr.write(`[debug] body (first 300): ${body.slice(0, 300)}\n`);
+}
+/**
+ * Create a new dataflow (DAG). Returns the new DAG id.
+ */
+export async function createDataflow(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", body } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/automation/v1/data-flow/flow`;
+    const reqHeaders = { ...buildHeaders(accessToken, businessDomain), "content-type": "application/json" };
+    const reqBody = JSON.stringify(body);
+    debugLog("POST", url, reqHeaders, reqBody);
+    const response = await fetch(url, {
+        method: "POST",
+        headers: reqHeaders,
+        body: reqBody,
+    });
+    const responseBody = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+    const parsed = JSON.parse(responseBody);
+    return parsed.id;
+}
+/**
+ * Trigger a run for an existing dataflow DAG.
+ */
+export async function runDataflow(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", dagId } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/automation/v1/run-instance/${encodeURIComponent(dagId)}`;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+        },
+        body: "{}",
+    });
+    if (!response.ok) {
+        const responseBody = await response.text();
+        throw new HttpError(response.status, response.statusText, responseBody);
+    }
+}
+/**
+ * Poll GET /api/automation/v1/dag/{dagId}/results until the run is done.
+ * Throws on "failed"/"error" status or timeout.
+ */
+export async function pollDataflowResults(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", dagId, interval = 3, timeout = 900, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/automation/v1/dag/${encodeURIComponent(dagId)}/results`;
+    const deadlineMs = Date.now() + timeout * 1000;
+    while (Date.now() < deadlineMs) {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: buildHeaders(accessToken, businessDomain),
+        });
+        const responseBody = await response.text();
+        if (!response.ok) {
+            throw new HttpError(response.status, response.statusText, responseBody);
+        }
+        const parsed = JSON.parse(responseBody);
+        const results = parsed.results ?? [];
+        const latest = results[0];
+        if (latest) {
+            if (latest.status === "success" || latest.status === "completed") {
+                return latest;
+            }
+            if (latest.status === "failed" || latest.status === "error") {
+                const reason = latest.reason ? `: ${latest.reason}` : "";
+                throw new Error(`Dataflow run ${latest.status}${reason}`);
+            }
+        }
+        // Still running — wait before next poll
+        if (interval > 0) {
+            await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+        }
+    }
+    throw new Error(`Dataflow polling timed out after ${timeout}s for DAG ${dagId}`);
+}
+/**
+ * Delete a dataflow DAG. Best-effort — does not throw on errors.
+ */
+export async function deleteDataflow(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", dagId } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/automation/v1/data-flow/flow/${encodeURIComponent(dagId)}`;
+    try {
+        await fetch(url, {
+            method: "DELETE",
+            headers: buildHeaders(accessToken, businessDomain),
+        });
+    }
+    catch {
+        // Best-effort: swallow all errors
+    }
+}
+/**
+ * Full dataflow lifecycle: create → run → poll → delete (always, even on error).
+ * Returns the final DataflowResult.
+ */
+export async function executeDataflow(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", body, interval, timeout } = options;
+    const dagId = await createDataflow({ baseUrl, accessToken, businessDomain, body });
+    try {
+        await runDataflow({ baseUrl, accessToken, businessDomain, dagId });
+        return await pollDataflowResults({ baseUrl, accessToken, businessDomain, dagId, interval, timeout });
+    }
+    finally {
+        await deleteDataflow({ baseUrl, accessToken, businessDomain, dagId }).catch(() => { });
+    }
+}

package/dist/api/dataviews.d.ts

@@ -1,3 +1,19 @@
+/** Field metadata returned by the data-views API. */
+export interface ViewField {
+    name: string;
+    type: string;
+    display_name?: string;
+    comment?: string;
+}
+/** Normalized data view model (mdl-data-model). */
+export interface DataView {
+    id: string;
+    name: string;
+    query_type: string;
+    datasource_id: string;
+    fields: ViewField[];
+}
+export declare function parseDataView(raw: Record<string, unknown>): DataView;
 export interface CreateDataViewOptions {
     baseUrl: string;
     accessToken: string;
@@ -11,10 +27,51 @@ export interface CreateDataViewOptions {
     businessDomain?: string;
 }
 export declare function createDataView(options: CreateDataViewOptions): Promise<string>;
+export interface ListDataViewsOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    /** Filter by data source id. */
+    datasourceId?: string;
+    /** Server-side keyword filter (fuzzy). */
+    name?: string;
+    /** View type filter (e.g. atomic, custom). */
+    type?: string;
+    /** Max items; default -1 (all). */
+    limit?: number;
+}
+export declare function listDataViews(options: ListDataViewsOptions): Promise<DataView[]>;
+export interface DeleteDataViewOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    businessDomain?: string;
+}
+export declare function deleteDataView(options: DeleteDataViewOptions): Promise<void>;
 export interface GetDataViewOptions {
     baseUrl: string;
     accessToken: string;
     id: string;
     businessDomain?: string;
 }
-export declare function getDataView(options: GetDataViewOptions): Promise<string>;
+export declare function getDataView(options: GetDataViewOptions): Promise<DataView>;
+export interface FindDataViewOptions {
+    baseUrl: string;
+    accessToken: string;
+    businessDomain?: string;
+    /** View name to search for (sent as keyword to server). */
+    name: string;
+    /** Filter by data source id. */
+    datasourceId?: string;
+    /** When true, apply client-side exact name match after keyword search (default false). */
+    exact?: boolean;
+    /** When true, poll until a result appears or timeout (default false). */
+    wait?: boolean;
+    /** Total wait budget in ms (default 30000). Only used when wait is true. */
+    timeoutMs?: number;
+}
+/**
+ * Find data views by name. Uses server-side keyword filtering; when `exact` is true,
+ * applies client-side `name ===` filter. Optional polling with exponential backoff.
+ */
+export declare function findDataView(options: FindDataViewOptions): Promise<DataView[]>;

package/dist/api/dataviews.js

@@ -24,6 +24,41 @@ function extractViewId(data) {
     }
     return null;
 }
+export function parseDataView(raw) {
+    const fieldsRaw = raw.fields;
+    const fields = [];
+    if (Array.isArray(fieldsRaw)) {
+        for (const f of fieldsRaw) {
+            if (f && typeof f === "object") {
+                const fr = f;
+                fields.push({
+                    name: String(fr.name ?? ""),
+                    type: String(fr.type ?? "varchar"),
+                    display_name: fr.display_name != null ? String(fr.display_name) : undefined,
+                    comment: fr.comment != null ? String(fr.comment) : undefined,
+                });
+            }
+        }
+    }
+    return {
+        id: String(raw.id ?? ""),
+        name: String(raw.name ?? ""),
+        query_type: String(raw.query_type ?? "SQL"),
+        datasource_id: String(raw.data_source_id ?? raw.group_id ?? ""),
+        fields,
+    };
+}
+function extractListPayload(data) {
+    if (Array.isArray(data))
+        return data;
+    if (data && typeof data === "object") {
+        const obj = data;
+        const items = obj.entries ?? obj.data;
+        if (Array.isArray(items))
+            return items;
+    }
+    return [];
+}
 export async function createDataView(options) {
     const { baseUrl, accessToken, name, datasourceId, table, fields = [], businessDomain = "bd_public", } = options;
     const viewId = createHash("md5").update(`${datasourceId}:${table}`).digest("hex").slice(0, 35);
@@ -51,11 +86,90 @@ export async function createDataView(options) {
     });
     const responseBody = await response.text();
     if (!response.ok) {
+        // If DataView already exists (403 with "Existed" error code), delete and recreate
+        if (response.status === 403) {
+            try {
+                const errBody = JSON.parse(responseBody);
+                if (errBody.error_code?.includes("Existed")) {
+                    const actualId = await findDataViewByName({ baseUrl, accessToken, name, groupId: datasourceId, businessDomain });
+                    if (actualId && fields.length > 0) {
+                        // Delete the bare DataView (created by scanMetadata) and recreate with fields
+                        await deleteDataView({ baseUrl, accessToken, id: actualId, businessDomain });
+                        const retryResponse = await fetch(url, {
+                            method: "POST",
+                            headers: { ...buildHeaders(accessToken, businessDomain), "content-type": "application/json" },
+                            body,
+                        });
+                        if (retryResponse.ok) {
+                            const retryBody = await retryResponse.text();
+                            const retryId = extractViewId(JSON.parse(retryBody));
+                            return retryId ?? viewId;
+                        }
+                    }
+                    if (actualId)
+                        return actualId;
+                    return viewId;
+                }
+            }
+            catch { /* fall through to throw */ }
+        }
         throw new HttpError(response.status, response.statusText, responseBody);
     }
     const createdId = extractViewId(JSON.parse(responseBody));
     return createdId ?? viewId;
 }
+async function findDataViewByName(options) {
+    const list = await listDataViews({
+        baseUrl: options.baseUrl,
+        accessToken: options.accessToken,
+        businessDomain: options.businessDomain,
+        name: options.name,
+    });
+    const match = list.find((e) => e.name === options.name && e.datasource_id === options.groupId);
+    return match?.id ?? null;
+}
+export async function listDataViews(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", datasourceId, name, type, limit = -1, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/mdl-data-model/v1/data-views`);
+    url.searchParams.set("limit", String(limit));
+    if (datasourceId)
+        url.searchParams.set("data_source_id", datasourceId);
+    if (name)
+        url.searchParams.set("keyword", name);
+    if (type)
+        url.searchParams.set("type", type);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const bodyText = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, bodyText);
+    }
+    const parsed = JSON.parse(bodyText);
+    const items = extractListPayload(parsed);
+    const out = [];
+    for (const item of items) {
+        if (item && typeof item === "object") {
+            out.push(parseDataView(item));
+        }
+    }
+    return out;
+}
+export async function deleteDataView(options) {
+    const { baseUrl, accessToken, id, businessDomain = "bd_public" } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/mdl-data-model/v1/data-views/${encodeURIComponent(id)}`;
+    const response = await fetch(url, {
+        method: "DELETE",
+        headers: buildHeaders(accessToken, businessDomain),
+    });
+    const bodyText = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, bodyText);
+    }
+}
 export async function getDataView(options) {
     const { baseUrl, accessToken, id, businessDomain = "bd_public", } = options;
     const base = baseUrl.replace(/\/+$/, "");
@@ -68,5 +182,40 @@ export async function getDataView(options) {
     if (!response.ok) {
         throw new HttpError(response.status, response.statusText, body);
     }
-    return body;
+    let parsed = JSON.parse(body);
+    if (Array.isArray(parsed) && parsed.length > 0) {
+        parsed = parsed[0];
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new HttpError(500, "Invalid response", body);
+    }
+    return parseDataView(parsed);
+}
+function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Find data views by name. Uses server-side keyword filtering; when `exact` is true,
+ * applies client-side `name ===` filter. Optional polling with exponential backoff.
+ */
+export async function findDataView(options) {
+    const { baseUrl, accessToken, businessDomain = "bd_public", name, datasourceId, exact = false, wait = false, timeoutMs = 30_000, } = options;
+    const deadline = Date.now() + timeoutMs;
+    let attempt = 0;
+    while (true) {
+        const list = await listDataViews({
+            baseUrl,
+            accessToken,
+            businessDomain,
+            datasourceId,
+            name,
+            limit: -1,
+        });
+        const results = exact ? list.filter((v) => v.name === name) : list;
+        if (results.length > 0 || !wait || Date.now() >= deadline)
+            return results;
+        const delayMs = Math.min(5000, 1000 * 2 ** attempt);
+        attempt += 1;
+        await sleepMs(delayMs);
+    }
 }

package/dist/auth/oauth.d.ts

@@ -2,7 +2,7 @@ import { type TokenConfig } from "../config/store.js";
 export declare function normalizeBaseUrl(value: string): string;
 /**
  * OAuth2 Authorization Code login flow.
- * 1. Register client (if not already registered)
+ * 1. Register client (if not already registered), OR use a provided client ID
  * 2. Open browser to /oauth2/auth
  * 3. Receive authorization code via local HTTP callback
  * 4. Exchange code for access_token + refresh_token
@@ -11,6 +11,10 @@ export declare function normalizeBaseUrl(value: string): string;
 export declare function oauth2Login(baseUrl: string, options?: {
     port?: number;
     scope?: string;
+    clientId?: string;
+    clientSecret?: string;
+    /** Skip TLS certificate verification (self-signed / dev servers only). */
+    tlsInsecure?: boolean;
 }): Promise<TokenConfig>;
 /**
  * Playwright-automated OAuth2 login.
@@ -28,6 +32,7 @@ export declare function playwrightLogin(baseUrl: string, options?: {
     password?: string;
     port?: number;
     scope?: string;
+    tlsInsecure?: boolean;
 }): Promise<TokenConfig>;
 /**
  * Exchange refresh_token for a new access token (OAuth2 password grant style, same as Python ConfigAuth).