@kweaver-ai/kweaver-sdk 0.4.11 → 0.4.13

package/README.md

@@ -90,6 +90,34 @@ 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);
+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({
+  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 +126,27 @@ 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 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/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]
+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]
@@ -148,6 +187,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

@@ -90,6 +90,23 @@ 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);
+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");
 const results = await cl.search({ query: "高血压 治疗" });
@@ -98,8 +115,13 @@ 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 token
+kweaver ds list/get/delete/tables/connect
+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
@@ -148,6 +170,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/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

@@ -1,3 +1,30 @@
+/** 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;
+    /** 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 {
     baseUrl: string;
     accessToken: string;
@@ -11,10 +38,80 @@ 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[]>;
+/** 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

@@ -24,6 +24,54 @@ function extractViewId(data) {
     }
     return null;
 }
+export function parseDataView(raw) {
+    const fieldsRaw = raw.fields;
+    let fields;
+    if (Array.isArray(fieldsRaw) && fieldsRaw.length > 0) {
+        fields = [];
+        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,
+                });
+            }
+        }
+    }
+    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 ?? ""),
+    };
+    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))
+        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);
@@ -84,26 +132,56 @@ export async function createDataView(options) {
     return createdId ?? viewId;
 }
 async function findDataViewByName(options) {
-    const base = options.baseUrl.replace(/\/+$/, "");
+    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 = 30, } = options;
+    const base = baseUrl.replace(/\/+$/, "");
     const url = new URL(`${base}/api/mdl-data-model/v1/data-views`);
-    url.searchParams.set("keyword", options.name);
+    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(options.accessToken, options.businessDomain),
+        headers: buildHeaders(accessToken, businessDomain),
     });
-    if (!response.ok)
-        return null;
-    const body = JSON.parse(await response.text());
-    const match = body.entries?.find((e) => e.name === options.name && e.group_id === options.groupId);
-    return match?.id ?? null;
+    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;
 }
-async function deleteDataView(options) {
-    const base = options.baseUrl.replace(/\/+$/, "");
-    const url = `${base}/api/mdl-data-model/v1/data-views/${encodeURIComponent(options.id)}`;
-    await fetch(url, {
+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(options.accessToken, options.businessDomain),
+        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;
@@ -117,5 +195,80 @@ 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);
+    }
+}
+/**
+ * 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,6 +45,16 @@ 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.