cbrowser 19.6.0 → 20.0.1

package/dist/help-client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * help-client.ts — ask the CBrowser knowledge base a question.
+ *
+ * One client for `cbrowser ask` and the `question_answer` MCP tool. Before
+ * 20.0.0 the tool always posted to CMS_URL or localhost:3200, which exists only
+ * on the hosted servers, so on a user's machine it could never answer.
+ *
+ * Where a question goes:
+ *  - CMS_URL set: only there, with the caller's key hash (an operator's own CMS).
+ *  - Hosted mode: the local CMS first, with the key hash, so the account is
+ *    known; the public endpoint only if the local CMS cannot be reached.
+ *  - Otherwise: the public endpoint (CBROWSER_HELP_URL overrides it), anonymously.
+ *
+ * The key hash goes only to a CMS the operator runs, never to the public
+ * endpoint. A target is skipped only when it cannot be reached; an HTTP error
+ * (429, 500) is the answer, because asking a second server would double-spend.
+ */
+export declare const PUBLIC_HELP_URL = "https://cbrowser.ai/cms/api/ai/question";
+export interface HelpAnswer {
+    question: string;
+    answer: string;
+    sources: string[];
+    /** Which endpoint answered (no credentials in it). */
+    answeredBy: string;
+}
+export interface AskOptions {
+    context?: string;
+    /** sha256 of the caller's cbk_ key, as the hosted tier gate holds it. */
+    keyHash?: string | null;
+    /** True on the hosted MCP servers (startRemoteMcpServer). */
+    hosted?: boolean;
+    timeoutMs?: number;
+    /** Tests only: the CMS a hosted server asks first (default localhost:3200). */
+    localCmsUrl?: string;
+}
+/** A help request that failed, with a message a person can act on. */
+export declare class HelpError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+interface Target {
+    url: string;
+    keyHash?: string;
+}
+export declare function helpTargets(opts?: AskOptions): Target[];
+export declare function askCbrowser(question: string, opts?: AskOptions): Promise<HelpAnswer>;
+export {};
+//# sourceMappingURL=help-client.d.ts.map

package/dist/help-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-client.d.ts","sourceRoot":"","sources":["../src/help-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,eAAO,MAAM,eAAe,4CAA4C,CAAC;AAKzE,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,sEAAsE;AACtE,qBAAa,SAAU,SAAQ,KAAK;IACL,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;gBAAzC,OAAO,EAAE,MAAM,EAAW,MAAM,CAAC,EAAE,MAAM,YAAA;CAItD;AAED,UAAU,MAAM;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE;AAElD,wBAAgB,WAAW,CAAC,IAAI,GAAE,UAAe,GAAG,MAAM,EAAE,CAY3D;AAED,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CA+C9F"}

package/dist/help-client.js

@@ -0,0 +1,96 @@
+/**
+ * help-client.ts — ask the CBrowser knowledge base a question.
+ *
+ * One client for `cbrowser ask` and the `question_answer` MCP tool. Before
+ * 20.0.0 the tool always posted to CMS_URL or localhost:3200, which exists only
+ * on the hosted servers, so on a user's machine it could never answer.
+ *
+ * Where a question goes:
+ *  - CMS_URL set: only there, with the caller's key hash (an operator's own CMS).
+ *  - Hosted mode: the local CMS first, with the key hash, so the account is
+ *    known; the public endpoint only if the local CMS cannot be reached.
+ *  - Otherwise: the public endpoint (CBROWSER_HELP_URL overrides it), anonymously.
+ *
+ * The key hash goes only to a CMS the operator runs, never to the public
+ * endpoint. A target is skipped only when it cannot be reached; an HTTP error
+ * (429, 500) is the answer, because asking a second server would double-spend.
+ */
+export const PUBLIC_HELP_URL = "https://cbrowser.ai/cms/api/ai/question";
+const LOCAL_CMS_URL = "http://localhost:3200";
+const QUESTION_PATH = "/api/ai/question";
+const DEFAULT_TIMEOUT_MS = 30_000;
+/** A help request that failed, with a message a person can act on. */
+export class HelpError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "HelpError";
+    }
+}
+export function helpTargets(opts = {}) {
+    const explicit = process.env.CMS_URL;
+    const key = opts.keyHash || undefined;
+    if (explicit)
+        return [{ url: explicit.replace(/\/$/, "") + QUESTION_PATH, keyHash: key }];
+    const publicUrl = process.env.CBROWSER_HELP_URL || PUBLIC_HELP_URL;
+    if (opts.hosted) {
+        return [
+            { url: (opts.localCmsUrl ?? LOCAL_CMS_URL) + QUESTION_PATH, keyHash: key },
+            { url: publicUrl },
+        ];
+    }
+    return [{ url: publicUrl }];
+}
+export async function askCbrowser(question, opts = {}) {
+    if (!question.trim())
+        throw new HelpError("Ask a question, e.g. cbrowser ask \"How do I test on an iPhone?\"");
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const body = JSON.stringify({ question, ...(opts.context ? { context: opts.context } : {}) });
+    let lastNetworkError;
+    for (const target of helpTargets(opts)) {
+        let res;
+        try {
+            res = await fetch(target.url, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    ...(target.keyHash ? { Authorization: `Bearer ${target.keyHash}` } : {}),
+                },
+                body,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch (e) {
+            if (e.name === "TimeoutError") {
+                throw new HelpError(`The help service did not answer within ${Math.round(timeoutMs / 1000)}s. Try again, or read https://cbrowser.ai/docs`);
+            }
+            lastNetworkError = e;
+            continue;
+        }
+        const where = new URL(target.url).host;
+        if (res.status === 429) {
+            const retry = res.headers.get("Retry-After");
+            throw new HelpError(`The help service is rate-limited${retry ? `; try again in ${retry}s` : ""}. The docs are at https://cbrowser.ai/docs`, 429);
+        }
+        if (!res.ok) {
+            let detail = "";
+            try {
+                detail = (await res.json()).error ?? "";
+            }
+            catch { /* not JSON */ }
+            throw new HelpError(`The help service answered ${res.status}${detail ? `: ${detail}` : ""}`, res.status);
+        }
+        const data = (await res.json());
+        if (typeof data.answer !== "string")
+            throw new HelpError("The help service sent no answer");
+        return {
+            question,
+            answer: data.answer,
+            sources: Array.isArray(data.sources) ? data.sources.filter((s) => typeof s === "string") : [],
+            answeredBy: where,
+        };
+    }
+    throw new HelpError(`Could not reach the help service (${lastNetworkError?.message ?? "no route"}). The docs are at https://cbrowser.ai/docs`);
+}
+//# sourceMappingURL=help-client.js.map

package/dist/help-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-client.js","sourceRoot":"","sources":["../src/help-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,yCAAyC,CAAC;AACzE,MAAM,aAAa,GAAG,uBAAuB,CAAC;AAC9C,MAAM,aAAa,GAAG,kBAAkB,CAAC;AACzC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAqBlC,sEAAsE;AACtE,MAAM,OAAO,SAAU,SAAQ,KAAK;IACI;IAAtC,YAAY,OAAe,EAAW,MAAe;QACnD,KAAK,CAAC,OAAO,CAAC,CAAC;QADqB,WAAM,GAAN,MAAM,CAAS;QAEnD,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAID,MAAM,UAAU,WAAW,CAAC,OAAmB,EAAE;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,IAAI,SAAS,CAAC;IACtC,IAAI,QAAQ;QAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,aAAa,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1F,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,eAAe,CAAC;IACnE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,OAAO;YACL,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,WAAW,IAAI,aAAa,CAAC,GAAG,aAAa,EAAE,OAAO,EAAE,GAAG,EAAE;YAC1E,EAAE,GAAG,EAAE,SAAS,EAAE;SACnB,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAgB,EAAE,OAAmB,EAAE;IACvE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,SAAS,CAAC,mEAAmE,CAAC,CAAC;IAC/G,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC9F,IAAI,gBAAyB,CAAC;IAE9B,KAAK,MAAM,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE;gBAC5B,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,kBAAkB;oBAClC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACzE;gBACD,IAAI;gBACJ,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;aACvC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAK,CAAW,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;gBACzC,MAAM,IAAI,SAAS,CAAC,0CAA0C,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,gDAAgD,CAAC,CAAC;YAC9I,CAAC;YACD,gBAAgB,GAAG,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;QACvC,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;YAC7C,MAAM,IAAI,SAAS,CAAC,mCAAmC,KAAK,CAAC,CAAC,CAAC,kBAAkB,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,4CAA4C,EAAE,GAAG,CAAC,CAAC;QACnJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC;gBAAC,MAAM,GAAI,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAwB,CAAC,KAAK,IAAI,EAAE,CAAC;YAAC,CAAC;YAAC,MAAM,CAAC,CAAC,cAAc,CAAC,CAAC;YACjG,MAAM,IAAI,SAAS,CAAC,6BAA6B,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3G,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA4C,CAAC;QAC3E,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ;YAAE,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;QAC5F,OAAO;YACL,QAAQ;YACR,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;YAC1G,UAAU,EAAE,KAAK;SAClB,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,SAAS,CAAC,qCAAsC,gBAA0B,EAAE,OAAO,IAAI,UAAU,6CAA6C,CAAC,CAAC;AAC5J,CAAC"}

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA6zGpE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,SAAS,CAAC,CAE1D;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvE;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAWpD"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiwBpE;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,SAAS,CAAC,CAE1D;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvE;AAED,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAWpD"}