@kweaver-ai/kweaver-sdk 0.4.12 → 0.4.14

package/README.md

@@ -31,6 +31,18 @@ export KWEAVER_BASE_URL=https://your-kweaver-instance.com
 export KWEAVER_TOKEN=your-token
 ```
 
+### Business domain (platform)
+
+Set or verify **before** calling list/query APIs that scope by tenant. DIP deployments often need a UUID, not only `bd_public`.
+
+```bash
+kweaver config show
+kweaver config list-bd
+kweaver config set-bd <uuid>
+```
+
+After `kweaver auth login`, the CLI may auto-select a domain when none is saved yet. Override with `KWEAVER_BUSINESS_DOMAIN` or `-bd` / `--biz-domain` on commands. See [`../../skills/kweaver-core/references/config.md`](../../skills/kweaver-core/references/config.md).
+
 ### Simple API (recommended)
 
 ```typescript
@@ -102,6 +114,11 @@ const exact = await client.dataviews.find("orders", {
   wait: true,
 });
 const dv = await client.dataviews.get(viewId);
+const queryRows = await client.dataviews.query(viewId, {
+  sql: "SELECT id, name FROM orders LIMIT 10",
+  limit: 10,
+  needTotal: true,
+});
 
 // Dataflow automation (CSV import pipeline, etc.)
 const result = await client.dataflows.execute({
@@ -121,12 +138,15 @@ const results = await cl.search({ query: "hypertension treatment" });
 ## CLI Reference
 
 ```
-kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] [--insecure|-k] — also: status, list, use, delete, logout
+kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] [--insecure|-k]
+kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (headless login)
+kweaver auth export [url|alias] [--json]   (export command to run on a headless host)
+kweaver auth status/list/use/delete/logout
+kweaver config show / list-bd / set-bd <value>   # platform business domain — after login
 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 dataview list/find/get/query/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]
@@ -179,6 +199,23 @@ If you encounter errors like `fetch failed`, `self-signed certificate`, or `UNAB
 
 > **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.
 
+### Headless / Server Authentication
+
+For servers or CI environments without a browser, log in on any machine that has one, then transfer credentials:
+
+**Step 1 — Browser machine:** Run `kweaver auth login` as usual. The callback page displays a ready-to-copy command with `--client-id`, `--client-secret`, and `--refresh-token`. Alternatively, run `kweaver auth export` to print the same command.
+
+**Step 2 — On the machine without a browser:** Run the pasted command there (SSH server, CI, etc.):
+
+```bash
+kweaver auth login https://your-platform \
+  --client-id abc123 \
+  --client-secret def456 \
+  --refresh-token ghi789
+```
+
+The SDK exchanges the refresh token for a new access token and saves it locally. Auto-refresh works normally from that point on.
+
 ## Using with AI Agents
 
 Install the KWeaver skill for Claude Code, Cursor, or other AI coding agents:

package/README.zh.md

@@ -31,6 +31,18 @@ export KWEAVER_BASE_URL=https://your-kweaver-instance.com
 export KWEAVER_TOKEN=your-token
 ```
 
+### 业务域（平台配置）
+
+在调用依赖租户范围的接口前，应先确认业务域；DIP 环境通常使用 **UUID**，不能长期只依赖默认 `bd_public`。
+
+```bash
+kweaver config show
+kweaver config list-bd
+kweaver config set-bd <uuid>
+```
+
+`kweaver auth login` 成功后，若尚未配置，CLI 可能自动选择业务域。也可用环境变量 `KWEAVER_BUSINESS_DOMAIN` 或各命令的 `-bd` / `--biz-domain` 覆盖。详见 [`../../skills/kweaver-core/references/config.md`](../../skills/kweaver-core/references/config.md)。
+
 ### 简洁 API（推荐）
 
 ```typescript
@@ -101,6 +113,11 @@ const exact = await client.dataviews.find("orders", {
   wait: true,
 });
 const dv = await client.dataviews.get(viewId);
+const queryRows = await client.dataviews.query(viewId, {
+  sql: "SELECT id, name FROM orders LIMIT 10",
+  limit: 10,
+  needTotal: true,
+});
 
 // Context Loader（通过 MCP 对 BKN 做语义搜索）
 const cl      = client.contextLoader(mcpUrl, "bkn-id");
@@ -110,10 +127,14 @@ const results = await cl.search({ query: "高血压 治疗" });
 ## 命令速查
 
 ```
-kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] [--insecure|-k] — 另有 status、list、use、delete、logout
+kweaver auth login <url> [--alias name] [-u user] [-p pass] [--playwright] [--insecure|-k]
+kweaver auth login <url> --client-id ID --client-secret S --refresh-token T   (无浏览器登录)
+kweaver auth export [url|alias] [--json]   (导出在无浏览器机器上运行的命令)
+kweaver auth status/list/use/delete/logout
+kweaver config show / list-bd / set-bd <value>   # 平台业务域，登录后优先
 kweaver token
 kweaver ds list/get/delete/tables/connect
-kweaver dataview list/find/get/delete
+kweaver dataview list/find/get/query/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
@@ -162,6 +183,23 @@ kweaver call <path> [-X METHOD] [-d BODY] [-H header]
 
 > **安全提示：** 以上方式均会跳过 HTTPS 证书校验，仅适用于开发/内网环境。生产环境请使用受信任的 CA 签发证书。
 
+### 无浏览器 / 服务器端认证
+
+适用于 SSH 远程服务器、CI 环境等无浏览器场景：
+
+**第一步 — 有浏览器的机器：** 正常运行 `kweaver auth login`。登录成功后，回调页面会显示一条可复制的命令（含 `--client-id`、`--client-secret`、`--refresh-token`）。也可以用 `kweaver auth export` 查看。
+
+**第二步 — 在没有浏览器的那台机器上：** 在 SSH 服务器、CI 等环境中执行下面这条命令：
+
+```bash
+kweaver auth login https://your-platform \
+  --client-id abc123 \
+  --client-secret def456 \
+  --refresh-token ghi789
+```
+
+SDK 会用 refresh token 换取新的 access token 并保存到本地，之后自动续期正常工作。
+
 ## 在 AI 智能体中使用
 
 为 Claude Code、Cursor 等 AI 编程助手安装 KWeaver 技能：

package/dist/api/business-domains.d.ts

@@ -0,0 +1,20 @@
+/** One business domain entry from GET /api/business-system/v1/business-domain */
+export interface BusinessDomain {
+    id: string;
+    name?: string;
+    description?: string;
+    creator?: string;
+    products?: string[];
+    create_time?: string;
+}
+export interface ListBusinessDomainsOptions {
+    baseUrl: string;
+    accessToken: string;
+    /** When true, skip TLS verification (matches `--insecure` login). */
+    tlsInsecure?: boolean;
+}
+/**
+ * List business domains for the authenticated user. Does not send x-business-domain
+ * (the endpoint returns all domains the user can access).
+ */
+export declare function listBusinessDomains(options: ListBusinessDomainsOptions): Promise<BusinessDomain[]>;

package/dist/api/business-domains.js

@@ -0,0 +1,54 @@
+import { HttpError } from "../utils/http.js";
+async function withTlsInsecure(tlsInsecure, fn) {
+    if (!tlsInsecure) {
+        return fn();
+    }
+    const prev = process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+    process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+    try {
+        return await fn();
+    }
+    finally {
+        if (prev === undefined) {
+            delete process.env.NODE_TLS_REJECT_UNAUTHORIZED;
+        }
+        else {
+            process.env.NODE_TLS_REJECT_UNAUTHORIZED = prev;
+        }
+    }
+}
+/**
+ * List business domains for the authenticated user. Does not send x-business-domain
+ * (the endpoint returns all domains the user can access).
+ */
+export async function listBusinessDomains(options) {
+    const { baseUrl, accessToken, tlsInsecure } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/business-system/v1/business-domain`;
+    return withTlsInsecure(tlsInsecure, async () => {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                accept: "application/json, text/plain, */*",
+                authorization: `Bearer ${accessToken}`,
+                token: accessToken,
+            },
+        });
+        const body = await response.text();
+        if (!response.ok) {
+            throw new HttpError(response.status, response.statusText, body);
+        }
+        const data = JSON.parse(body);
+        if (!Array.isArray(data)) {
+            throw new Error("Business domain list response was not a JSON array.");
+        }
+        return data.map((item) => {
+            const row = item;
+            const id = row.id;
+            if (typeof id !== "string" || id.length === 0) {
+                throw new Error("Business domain entry missing string id.");
+            }
+            return item;
+        });
+    });
+}

package/dist/api/dataflow.d.ts

@@ -45,6 +45,8 @@ export interface PollDataflowOptions {
     interval?: number;
     /** Maximum time to wait in seconds. Default: 900 */
     timeout?: number;
+    /** Test injection: override sleep function. */
+    _sleep?: (ms: number) => Promise<void>;
 }
 /**
  * Poll GET /api/automation/v1/dag/{dagId}/results until the run is done.

package/dist/api/dataflow.js

@@ -69,10 +69,11 @@ export async function runDataflow(options) {
  * 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 { baseUrl, accessToken, businessDomain = "bd_public", dagId, interval = 3, timeout = 900, _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), } = options;
     const base = baseUrl.replace(/\/+$/, "");
     const url = `${base}/api/automation/v1/dag/${encodeURIComponent(dagId)}/results`;
     const deadlineMs = Date.now() + timeout * 1000;
+    let currentInterval = interval;
     while (Date.now() < deadlineMs) {
         const response = await fetch(url, {
             method: "GET",
@@ -95,9 +96,10 @@ export async function pollDataflowResults(options) {
             }
         }
         // Still running — wait before next poll
-        if (interval > 0) {
-            await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+        if (currentInterval > 0) {
+            await _sleep(currentInterval * 1000);
         }
+        currentInterval = Math.min(currentInterval * 2, 30);
     }
     throw new Error(`Dataflow polling timed out after ${timeout}s for DAG ${dagId}`);
 }

package/dist/api/dataviews.d.ts

@@ -11,7 +11,18 @@ export interface DataView {
     name: string;
     query_type: string;
     datasource_id: string;
-    fields: ViewField[];
+    /** View type, e.g. "atomic" or "custom". */
+    type?: string;
+    /** Underlying data source engine, e.g. "mysql", "postgresql". */
+    data_source_type?: string;
+    /** Human-readable data source name. */
+    data_source_name?: string;
+    /** Full SQL expression stored in the view definition (Trino catalog.schema.table). */
+    sql_str?: string;
+    /** Fully-qualified table reference (catalog."schema"."table"). */
+    meta_table_name?: string;
+    /** Field metadata. Populated by `get`; absent (`undefined`) in `list` results. */
+    fields?: ViewField[];
 }
 export declare function parseDataView(raw: Record<string, unknown>): DataView;
 export interface CreateDataViewOptions {
@@ -75,3 +86,32 @@ export interface FindDataViewOptions {
  * applies client-side `name ===` filter. Optional polling with exponential backoff.
  */
 export declare function findDataView(options: FindDataViewOptions): Promise<DataView[]>;
+/** Options for querying data view rows via mdl-uniquery (SQL / view definition). */
+export interface QueryDataViewOptions {
+    baseUrl: string;
+    accessToken: string;
+    id: string;
+    sql?: string;
+    offset?: number;
+    limit?: number;
+    needTotal?: boolean;
+    outputFields?: string[];
+    filters?: Record<string, unknown>;
+    sort?: Array<Record<string, unknown>>;
+    businessDomain?: string;
+}
+/** Query result from mdl-uniquery data-views POST (shape varies by backend). */
+export interface DataViewQueryResult {
+    columns?: Array<{
+        name: string;
+        type?: string;
+        vega_type?: string;
+    }>;
+    entries?: unknown;
+    total_count?: number;
+}
+/**
+ * Execute a query against a data view (POST /api/mdl-uniquery/v1/data-views/:id).
+ * When `sql` is omitted, the server uses the view's stored SQL definition.
+ */
+export declare function queryDataView(options: QueryDataViewOptions): Promise<DataViewQueryResult>;

package/dist/api/dataviews.js

@@ -26,8 +26,9 @@ function extractViewId(data) {
 }
 export function parseDataView(raw) {
     const fieldsRaw = raw.fields;
-    const fields = [];
-    if (Array.isArray(fieldsRaw)) {
+    let fields;
+    if (Array.isArray(fieldsRaw) && fieldsRaw.length > 0) {
+        fields = [];
         for (const f of fieldsRaw) {
             if (f && typeof f === "object") {
                 const fr = f;
@@ -40,13 +41,25 @@ export function parseDataView(raw) {
             }
         }
     }
-    return {
+    const dv = {
         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,
     };
+    if (raw.type != null)
+        dv.type = String(raw.type);
+    if (raw.data_source_type != null)
+        dv.data_source_type = String(raw.data_source_type);
+    if (raw.data_source_name != null)
+        dv.data_source_name = String(raw.data_source_name);
+    if (raw.sql_str != null)
+        dv.sql_str = String(raw.sql_str);
+    if (raw.meta_table_name != null)
+        dv.meta_table_name = String(raw.meta_table_name);
+    if (fields)
+        dv.fields = fields;
+    return dv;
 }
 function extractListPayload(data) {
     if (Array.isArray(data))
@@ -129,7 +142,7 @@ async function findDataViewByName(options) {
     return match?.id ?? null;
 }
 export async function listDataViews(options) {
-    const { baseUrl, accessToken, businessDomain = "bd_public", datasourceId, name, type, limit = -1, } = options;
+    const { baseUrl, accessToken, businessDomain = "bd_public", datasourceId, name, type, limit = 30, } = options;
     const base = baseUrl.replace(/\/+$/, "");
     const url = new URL(`${base}/api/mdl-data-model/v1/data-views`);
     url.searchParams.set("limit", String(limit));
@@ -219,3 +232,43 @@ export async function findDataView(options) {
         await sleepMs(delayMs);
     }
 }
+/**
+ * Execute a query against a data view (POST /api/mdl-uniquery/v1/data-views/:id).
+ * When `sql` is omitted, the server uses the view's stored SQL definition.
+ */
+export async function queryDataView(options) {
+    const { baseUrl, accessToken, id, sql, offset = 0, limit = 50, needTotal = false, outputFields, filters, sort, businessDomain = "bd_public", } = options;
+    const base = baseUrl.replace(/\/+$/, "");
+    const url = `${base}/api/mdl-uniquery/v1/data-views/${encodeURIComponent(id)}`;
+    const body = {
+        offset,
+        limit,
+        need_total: needTotal,
+    };
+    if (sql !== undefined && sql !== "")
+        body.sql = sql;
+    if (outputFields !== undefined)
+        body.output_fields = outputFields;
+    if (filters !== undefined)
+        body.filters = filters;
+    if (sort !== undefined)
+        body.sort = sort;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            ...buildHeaders(accessToken, businessDomain),
+            "content-type": "application/json",
+            "x-http-method-override": "GET",
+        },
+        body: JSON.stringify(body),
+    });
+    const bodyText = await response.text();
+    if (!response.ok) {
+        throw new HttpError(response.status, response.statusText, bodyText);
+    }
+    const parsed = JSON.parse(bodyText);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return {};
+}

package/dist/api/vega.js

@@ -190,7 +190,7 @@ export async function queryVegaResourceData(options) {
     return body;
 }
 export async function previewVegaResource(options) {
-    const { baseUrl, accessToken, id, limit = 10, businessDomain = "bd_public", } = options;
+    const { baseUrl, accessToken, id, limit = 50, businessDomain = "bd_public", } = options;
     const base = baseUrl.replace(/\/+$/, "");
     const url = new URL(`${base}${VEGA_BASE}/resources/${encodeURIComponent(id)}/preview`);
     url.searchParams.set("limit", String(limit));

package/dist/auth/oauth.d.ts

@@ -1,4 +1,15 @@
 import { type TokenConfig } from "../config/store.js";
+/** POSIX shell single-quote escaping for copy-paste commands. */
+export declare function shellQuoteForShell(value: string): string;
+/**
+ * Build a one-line `kweaver auth login ...` command for headless / other machines.
+ * Omits `--client-secret` when empty (PKCE-only client); headless refresh may still require a confidential client.
+ */
+export declare function buildCopyCommand(baseUrl: string, clientId: string, clientSecret: string, refreshToken: string | undefined, tlsInsecure?: boolean): string;
+/**
+ * HTML shown after successful OAuth callback with a copyable headless login command.
+ */
+export declare function buildCallbackHtml(copyCommand: string): string;
 export declare function normalizeBaseUrl(value: string): string;
 /**
  * OAuth2 Authorization Code login flow.
@@ -34,11 +45,30 @@ export declare function playwrightLogin(baseUrl: string, options?: {
     scope?: string;
     tlsInsecure?: boolean;
 }): Promise<TokenConfig>;
+/**
+ * Log in on a headless machine using OAuth2 client credentials and a refresh token (no browser).
+ * Exchanges the refresh token for a new access token and persists ~/.kweaver/ state.
+ */
+export declare function refreshTokenLogin(baseUrl: string, options: {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+    tlsInsecure?: boolean;
+}): Promise<TokenConfig>;
 /**
  * Exchange refresh_token for a new access token (OAuth2 password grant style, same as Python ConfigAuth).
  * Persists the new token to ~/.kweaver/ and returns it.
  */
 export declare function refreshAccessToken(token: TokenConfig): Promise<TokenConfig>;
+/**
+ * Resolve a usable access token for the current platform.
+ *
+ * **Default behavior** (saved `~/.kweaver/` session from OAuth2 code login): when the access
+ * token is expired or near expiry, automatically exchanges the saved **refresh_token** for a new
+ * access token (OAuth2 `refresh_token` grant) and persists it. No extra flags are required.
+ *
+ * Static env `KWEAVER_TOKEN` bypasses refresh (see implementation).
+ */
 export declare function ensureValidToken(opts?: {
     forceRefresh?: boolean;
 }): Promise<TokenConfig>;