@kweaver-ai/kweaver-sdk 0.4.10 → 0.4.11

package/README.md

@@ -98,7 +98,7 @@ 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 bkn list/get/stats/export/create/update/delete
 kweaver bkn object-type list/get/create/update/delete/query/properties
@@ -120,6 +120,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

@@ -98,7 +98,7 @@ 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 bkn list/get/stats/export/create/update/delete
 kweaver bkn object-type list/get/create/update/delete/query/properties
@@ -120,6 +120,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.js

@@ -51,11 +51,60 @@ 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 base = options.baseUrl.replace(/\/+$/, "");
+    const url = new URL(`${base}/api/mdl-data-model/v1/data-views`);
+    url.searchParams.set("keyword", options.name);
+    const response = await fetch(url.toString(), {
+        method: "GET",
+        headers: buildHeaders(options.accessToken, options.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;
+}
+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, {
+        method: "DELETE",
+        headers: buildHeaders(options.accessToken, options.businessDomain),
+    });
+}
 export async function getDataView(options) {
     const { baseUrl, accessToken, id, businessDomain = "bd_public", } = options;
     const base = baseUrl.replace(/\/+$/, "");

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).