@kweaver-ai/kweaver-sdk 0.4.12 → 0.4.13

package/README.md

@@ -102,6 +102,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 +126,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 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 +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

@@ -101,6 +101,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 +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/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 +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

@@ -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,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.

package/dist/auth/oauth.js

@@ -5,6 +5,87 @@ const TOKEN_TTL_SECONDS = 3600;
 const REFRESH_THRESHOLD_SEC = 60;
 const DEFAULT_REDIRECT_PORT = 9010;
 const DEFAULT_SCOPE = "openid offline all";
+/** POSIX shell single-quote escaping for copy-paste commands. */
+export function shellQuoteForShell(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * 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 function buildCopyCommand(baseUrl, clientId, clientSecret, refreshToken, tlsInsecure) {
+    const parts = ["kweaver", "auth", "login", shellQuoteForShell(normalizeBaseUrl(baseUrl)), "--client-id", shellQuoteForShell(clientId)];
+    if (clientSecret) {
+        parts.push("--client-secret", shellQuoteForShell(clientSecret));
+    }
+    if (refreshToken) {
+        parts.push("--refresh-token", shellQuoteForShell(refreshToken));
+    }
+    if (tlsInsecure) {
+        parts.push("--insecure");
+    }
+    return parts.join(" ");
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * HTML shown after successful OAuth callback with a copyable headless login command.
+ */
+export function buildCallbackHtml(copyCommand) {
+    const safeCmd = escapeHtml(copyCommand);
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1"/>
+  <title>Login successful</title>
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 52rem; margin: 2rem auto; padding: 0 1rem; line-height: 1.5; }
+    pre { background: #f4f4f5; padding: 1rem; border-radius: 6px; overflow-x: auto; white-space: pre-wrap; word-break: break-all; }
+    button { margin-top: 0.75rem; padding: 0.5rem 1rem; cursor: pointer; }
+    .warn { color: #b45309; margin-top: 1.5rem; font-size: 0.9rem; }
+  </style>
+</head>
+<body>
+  <h2>Login successful</h2>
+  <p>You can close this tab.</p>
+  <h3>Headless machine</h3>
+  <p>On the computer that has no browser (SSH server, CI runner, container), run:</p>
+  <pre id="kw-cmd">${safeCmd}</pre>
+  <button type="button" id="kw-copy">Copy command</button>
+  <p class="warn">Keep these credentials secure. Anyone with the refresh token and client secret can obtain new access tokens.</p>
+  <script>
+    (function () {
+      var btn = document.getElementById("kw-copy");
+      var pre = document.getElementById("kw-cmd");
+      if (btn && pre) {
+        btn.addEventListener("click", function () {
+          var text = pre.textContent || "";
+          if (navigator.clipboard && navigator.clipboard.writeText) {
+            navigator.clipboard.writeText(text.trim()).then(function () {
+              btn.textContent = "Copied";
+              setTimeout(function () { btn.textContent = "Copy command"; }, 2000);
+            });
+          } else {
+            window.prompt("Copy this command:", text.trim());
+          }
+        });
+      }
+    })();
+  </script>
+</body>
+</html>`;
+}
+function buildCallbackExchangeErrorHtml(message) {
+    return `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"/><title>Login error</title></head>
+<body><h2>Login error</h2><pre>${escapeHtml(message)}</pre></body></html>`;
+}
 export function normalizeBaseUrl(value) {
     return value.replace(/\/+$/, "");
 }
@@ -96,35 +177,62 @@ export async function oauth2Login(baseUrl, options) {
             authParams.set("code_challenge_method", "S256");
         }
         const authUrl = `${base}/oauth2/auth?${authParams.toString()}`;
-        // Step 4: Start local callback server, wait for code
-        const code = await new Promise((resolve, reject) => {
+        // Step 4: Start local callback server; exchange code inside handler, then show credentials HTML
+        const token = await new Promise((resolve, reject) => {
+            let server;
             const timeoutId = setTimeout(() => {
-                server.close();
+                server?.close();
                 reject(new Error("OAuth2 login timed out (120s). No authorization code received."));
             }, 120_000);
-            const server = createServer((req, res) => {
-                const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
-                if (url.pathname === "/callback") {
-                    const receivedState = url.searchParams.get("state");
-                    const receivedCode = url.searchParams.get("code");
-                    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-                    res.end("<html><body><h2>Login successful. You can close this tab.</h2></body></html>");
-                    clearTimeout(timeoutId);
-                    server.close();
-                    if (receivedState !== state) {
-                        reject(new Error("OAuth2 state mismatch — possible CSRF attack."));
+            server = createServer((req, res) => {
+                void (async () => {
+                    try {
+                        const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+                        if (url.pathname !== "/callback") {
+                            res.writeHead(404);
+                            res.end();
+                            return;
+                        }
+                        const receivedState = url.searchParams.get("state");
+                        const receivedCode = url.searchParams.get("code");
+                        if (receivedState !== state) {
+                            res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                            res.end(buildCallbackExchangeErrorHtml("OAuth2 state mismatch — possible CSRF attack."));
+                            clearTimeout(timeoutId);
+                            server.close();
+                            reject(new Error("OAuth2 state mismatch — possible CSRF attack."));
+                            return;
+                        }
+                        if (!receivedCode) {
+                            res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                            res.end(buildCallbackExchangeErrorHtml("No authorization code received in callback."));
+                            clearTimeout(timeoutId);
+                            server.close();
+                            reject(new Error("No authorization code received in callback."));
+                            return;
+                        }
+                        const exchanged = await exchangeCodeForToken(base, receivedCode, client.clientId, client.clientSecret, redirectUri, pkce?.verifier, options?.tlsInsecure);
+                        const copyCommand = buildCopyCommand(base, client.clientId, client.clientSecret, exchanged.refreshToken, options?.tlsInsecure);
+                        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                        res.end(buildCallbackHtml(copyCommand));
+                        clearTimeout(timeoutId);
+                        server.close();
+                        resolve(exchanged);
                     }
-                    else if (!receivedCode) {
-                        reject(new Error("No authorization code received in callback."));
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        try {
+                            res.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
+                            res.end(buildCallbackExchangeErrorHtml(message));
+                        }
+                        catch {
+                            /* response may already be sent */
+                        }
+                        clearTimeout(timeoutId);
+                        server.close();
+                        reject(err instanceof Error ? err : new Error(message));
                     }
-                    else {
-                        resolve(receivedCode);
-                    }
-                }
-                else {
-                    res.writeHead(404);
-                    res.end();
-                }
+                })();
             });
             server.listen(port, "127.0.0.1", () => {
                 // Step 5: Open browser (uses spawn with proper Windows quoting)
@@ -134,8 +242,6 @@ export async function oauth2Login(baseUrl, options) {
                 process.stderr.write(`If the wrong browser opens, copy this URL to your correct browser:\n  ${authUrl}\n`);
             });
         });
-        // Step 6: Exchange code for tokens
-        const token = await exchangeCodeForToken(base, code, client.clientId, client.clientSecret, redirectUri, pkce?.verifier, options?.tlsInsecure);
         setCurrentPlatform(base);
         return token;
     });
@@ -275,40 +381,70 @@ export async function playwrightLogin(baseUrl, options) {
             product: "adp",
         });
         const authUrl = `${base}/oauth2/auth?${authParams.toString()}`;
-        // Step 4: Start local callback server to capture the authorization code
-        const code = await new Promise((resolve, reject) => {
+        // Step 4: Start local callback server; exchange code inside handler, then show credentials HTML
+        let browser;
+        const token = await new Promise((resolve, reject) => {
             const TIMEOUT_MS = hasCredentials ? 30_000 : 120_000;
+            let server;
             const timeoutId = setTimeout(() => {
-                server.close();
+                server?.close();
                 browser?.close();
                 reject(new Error(`OAuth2 login timed out (${TIMEOUT_MS / 1000}s). No authorization code received.`));
             }, TIMEOUT_MS);
-            const server = createServer((req, res) => {
-                const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
-                if (url.pathname === "/callback") {
-                    const receivedState = url.searchParams.get("state");
-                    const receivedCode = url.searchParams.get("code");
-                    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-                    res.end("<html><body><h2>Login successful. You can close this tab.</h2></body></html>");
-                    clearTimeout(timeoutId);
-                    server.close();
-                    browser?.close();
-                    if (receivedState !== state) {
-                        reject(new Error("OAuth2 state mismatch — possible CSRF attack."));
-                    }
-                    else if (!receivedCode) {
-                        reject(new Error("No authorization code received in callback."));
+            server = createServer((req, res) => {
+                void (async () => {
+                    try {
+                        const url = new URL(req.url ?? "/", `http://127.0.0.1:${port}`);
+                        if (url.pathname !== "/callback") {
+                            res.writeHead(404);
+                            res.end();
+                            return;
+                        }
+                        const receivedState = url.searchParams.get("state");
+                        const receivedCode = url.searchParams.get("code");
+                        if (receivedState !== state) {
+                            res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                            res.end(buildCallbackExchangeErrorHtml("OAuth2 state mismatch — possible CSRF attack."));
+                            clearTimeout(timeoutId);
+                            server.close();
+                            browser?.close();
+                            reject(new Error("OAuth2 state mismatch — possible CSRF attack."));
+                            return;
+                        }
+                        if (!receivedCode) {
+                            res.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                            res.end(buildCallbackExchangeErrorHtml("No authorization code received in callback."));
+                            clearTimeout(timeoutId);
+                            server.close();
+                            browser?.close();
+                            reject(new Error("No authorization code received in callback."));
+                            return;
+                        }
+                        const exchanged = await exchangeCodeForToken(base, receivedCode, client.clientId, client.clientSecret, redirectUri, undefined, options?.tlsInsecure);
+                        const copyCommand = buildCopyCommand(base, client.clientId, client.clientSecret, exchanged.refreshToken, options?.tlsInsecure);
+                        res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                        res.end(buildCallbackHtml(copyCommand));
+                        clearTimeout(timeoutId);
+                        server.close();
+                        browser?.close();
+                        resolve(exchanged);
                     }
-                    else {
-                        resolve(receivedCode);
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        try {
+                            res.writeHead(500, { "Content-Type": "text/html; charset=utf-8" });
+                            res.end(buildCallbackExchangeErrorHtml(message));
+                        }
+                        catch {
+                            /* response may already be sent */
+                        }
+                        clearTimeout(timeoutId);
+                        server.close();
+                        browser?.close();
+                        reject(err instanceof Error ? err : new Error(message));
                     }
-                }
-                else {
-                    res.writeHead(404);
-                    res.end();
-                }
+                })();
             });
-            let browser;
             server.listen(port, "127.0.0.1", async () => {
                 try {
                     browser = await chromium.launch({ headless: hasCredentials });
@@ -334,12 +470,48 @@ export async function playwrightLogin(baseUrl, options) {
                 }
             });
         });
-        // Step 5: Exchange authorization code for tokens (includes refresh_token)
-        const token = await exchangeCodeForToken(base, code, client.clientId, client.clientSecret, redirectUri, undefined, options?.tlsInsecure);
+        if (hasCredentials) {
+            const copyCommand = buildCopyCommand(base, client.clientId, client.clientSecret, token.refreshToken, options?.tlsInsecure);
+            process.stderr.write("\nHeadless login: copy this command and run it on a machine without a browser, or use `kweaver auth export`:\n\n" +
+                copyCommand +
+                "\n\n");
+        }
         setCurrentPlatform(base);
         return token;
     });
 }
+/**
+ * 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 async function refreshTokenLogin(baseUrl, options) {
+    const base = normalizeBaseUrl(baseUrl);
+    const redirectUri = `http://127.0.0.1:${DEFAULT_REDIRECT_PORT}/callback`;
+    const client = {
+        baseUrl: base,
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        redirectUri,
+        logoutRedirectUri: redirectUri.replace("/callback", "/successful-logout"),
+        scope: DEFAULT_SCOPE,
+        lang: "zh-cn",
+        product: "adp",
+        xForwardedPrefix: "",
+    };
+    saveClientConfig(base, client);
+    const synthetic = {
+        baseUrl: base,
+        accessToken: "",
+        tokenType: "Bearer",
+        scope: "",
+        refreshToken: options.refreshToken,
+        obtainedAt: new Date().toISOString(),
+        ...(options.tlsInsecure ? { tlsInsecure: true } : {}),
+    };
+    const token = await runWithTlsInsecure(options.tlsInsecure, () => refreshAccessToken(synthetic));
+    setCurrentPlatform(base);
+    return token;
+}
 function tokenNeedsRefresh(token) {
     if (!token.expiresAt) {
         return false;