@hilbras/omnihilbras 1.71.1 → 1.75.0

package/dist/adapters/tokenharbor-web.d.ts

@@ -0,0 +1,201 @@
+import type { ChatMessage, ChatRequest, ChatResponse, CredentialValidation, Model, ProviderAdapter, ProviderCredential, ProviderHealth, ProviderId, ProviderRequestContext } from '../types.js';
+/**
+ * Token Harbor Web — the chat application at tokenharbor.ai, driven by the Supabase session
+ * cookie a signed-in browser already holds.
+ *
+ * ## Read this before building on it
+ *
+ * Token Harbor's terms **prohibit** what this adapter does. Their product is itself a gateway,
+ * and the metered API key is its architectural guardrail; driving the web chat with a harvested
+ * session cookie routes around that guardrail. The two clauses that name it:
+ *
+ * > **Proxy Reselling:** Utilize the Service to construct a direct, white-labeled proxy
+ * > alternative to Token Harbor without adding substantive unique value or without prior written
+ * > enterprise authorization.
+ * >
+ * > ...designed to compromise the security, stability, or **architectural guardrails of the
+ * > Token Harbor gateway**.
+ *
+ * There is a legitimate path — `https://tokenharbor.ai/v1` with a Bearer key, OpenAI-compatible,
+ * documented, and free on the `:free` models — and it is the card beside this one. This adapter
+ * exists because the operator asked for the session-cookie route with that trade stated, and it
+ * carries the same warning in the dashboard catalog (`riskSeverity: 'high'`) so a user meets it
+ * before pasting a credential. It is the same shape as the Kiro notice: the vendor's terms and
+ * the gateway's behaviour are both on the card, and using it is the user's decision to make.
+ *
+ * ## What the credential is
+ *
+ * Auth is Supabase (`auth.tokenharbor.ai`), so the browser cookie is `sb-<ref>-auth-token`,
+ * where `<ref>` is the first label of the Supabase host — `auth`, giving `sb-auth-auth-token`.
+ * Above Supabase's size limit the value is split into `sb-...-auth-token.0`, `.1`, ... and the
+ * chunks are reassembled in order. It is written with `document.cookie`, so unlike ChatGPT Web's
+ * `HttpOnly` session it can be read from the Application panel or the Network tab's Cookie
+ * header — which is why the guide offers both.
+ *
+ * ## The wire format is not OpenAI's, and that is the whole adapter
+ *
+ * A turn is two requests and a decode:
+ *
+ * 1. `POST /api/direct-chat/sessions` with `{ model, temporary: true }` → `{ session: { id } }`.
+ *    `temporary` is sent so a stateless gateway does not litter the user's sidebar with a
+ *    conversation per request.
+ * 2. `POST /api/direct-chat/stream` with `{ sessionId, content, model, webSearch, tz }` → an SSE
+ *    body whose events are **named**, not OpenAI's `choices[].delta`:
+ *    `chunk` (the answer text in `delta`), `thinking` (reasoning in `delta`), `tool_use`,
+ *    `citation`, `image`, `file`, `miniapp`, and `done`. `error` carries `{ code, message }`.
+ *
+ * Only `chunk`, `thinking`, `done` and `error` are consumed. The others are attachments and
+ * citations for a UI, and inventing an OpenAI shape for them here would be guessing at a
+ * contract this adapter cannot test without the session.
+ *
+ * ## What is not claimed
+ *
+ * `capabilities.streaming` is false and no `streamChat` is implemented: the transport is SSE,
+ * but the gateway consumes the whole body and returns one completion. A streaming surface would
+ * need the chunk boundary semantics verified against a live session first.
+ *
+ * `healthCheck` reports `verified: 'credential'`. It reads `/api/me/profile`, which proves the
+ * session cookie is accepted and nothing more — the same distinction the type exists to force.
+ */
+export declare const tokenHarborWebProviderId: ProviderId;
+export declare const TOKENHARBOR_WEB: {
+    readonly origin: "https://tokenharbor.ai";
+    readonly apiBase: "https://tokenharbor.ai/api";
+    readonly profileUrl: "https://tokenharbor.ai/api/me/profile";
+    readonly sessionsUrl: "https://tokenharbor.ai/api/direct-chat/sessions";
+    readonly streamUrl: "https://tokenharbor.ai/api/direct-chat/stream";
+    readonly cookiePrefix: "sb-auth-auth-token";
+    readonly defaultModel: "th-rudder:free";
+    /** The page a user signs in on and copies the cookie from. */
+    readonly signInUrl: "https://tokenharbor.ai/login";
+};
+/**
+ * The catalog, read from `https://tokenharbor.ai/models` on 2026-10-07.
+ *
+ * A dated snapshot rather than a promise: the page is the live list and this is what it showed.
+ * Prices are per 1M tokens, which is the unit the SDK normalises to and the unit the page itself
+ * prints. The two `:free` ids are the ones that bill nothing.
+ *
+ * No context window is claimed because the page publishes none.
+ */
+export declare const TOKENHARBOR_WEB_MODELS: ReadonlyArray<{
+    id: string;
+    label: string;
+    family: string;
+    inputPer1M: number;
+    outputPer1M: number;
+}>;
+export declare function allTokenHarborWebModels(): string[];
+/**
+ * Reads the Supabase session cookie out of whatever the user pasted.
+ *
+ * Two pastes are accepted, because both are things the guide tells people to copy:
+ *
+ * - the whole `Cookie:` request header (space for the Cloudflare clearance and the other cookies
+ *   the SSR layer reads), and
+ * - just the `sb-auth-auth-token` value or the `sb-auth-auth-token=...` pair, from the
+ *   Application panel.
+ *
+ * The chunks are **joined in numeric order**, which is not the order they appear in a header:
+ * a large token is stored as `.0`, `.1`, ... and a header that happens to list `.1` before `.0`
+ * would otherwise reassemble to a garbage session that fails later as an unexplained refusal.
+ */
+export declare function parseTokenHarborCookieHeader(raw: string): string;
+/**
+ * Decodes the session cookie and reports what is wrong with it, or `undefined` when it is intact.
+ *
+ * Returns a sentence rather than a boolean because the two failures need different instructions: a
+ * value that does not decode is a **truncated paste**, and a value that decodes but carries no
+ * access token is a **shape this adapter does not recognise**. "Sign in again" is wrong for the
+ * first — the session is fine, the paste was short.
+ */
+export declare function sessionValueProblem(session: string): string | undefined;
+/** The `expires_at` epoch seconds inside the session, when it is one this adapter can read.
+ *
+ * Accepts either the bare value or a whole Cookie header, because the two callers have different
+ * shapes in hand: the parser has the value, the refusal path has the assembled header.
+ */
+export declare function sessionExpiresAt(sessionOrCookie: string): number | undefined;
+export declare function tokenHarborWebCredential(raw: string): ProviderCredential;
+export declare function tokenHarborWebCookieFromCredential(credential: ProviderCredential | undefined): string;
+export declare class TokenHarborWebAdapter implements ProviderAdapter {
+    readonly id: string;
+    readonly name = "Token Harbor Web";
+    readonly capabilities: {
+        readonly chat: true;
+        readonly models: true;
+    };
+    private readonly now;
+    private readonly fetchImpl;
+    constructor(options?: {
+        now?: () => number;
+        fetch?: typeof fetch;
+    });
+    /**
+     * The dated catalog above, not a request.
+     *
+     * Token Harbor publishes no public models JSON — the live list is rendered into the `/models`
+     * page — so there is nothing to read without a session, and an authenticated read per call
+     * would be a cost for a list that changes weekly. The snapshot is what the page showed on the
+     * date beside it, and the free-only policy narrows it the way the dialog's checkbox promises.
+     */
+    listModels(context?: ProviderRequestContext): Promise<Model[]>;
+    /**
+     * A real round trip to `/api/me/profile`, which answers `{ ok: false }` with a 401 to a session
+     * it does not recognise. That is the cheapest endpoint that proves the cookie is accepted, and
+     * it is the whole of what this establishes — see `healthCheck`.
+     */
+    validateCredential(credential: ProviderCredential | undefined, context?: ProviderRequestContext): Promise<CredentialValidation>;
+    /**
+     * `verified: 'credential'` — deliberately.
+     *
+     * Reading the profile proves the cookie is live; it says nothing about whether a model can
+     * answer. Claiming `inference` would need a real turn on every 60-second poll, which is a real
+     * request against someone else's service on a timer, and the type exists precisely so this
+     * distinction is stated rather than implied.
+     */
+    healthCheck(context?: ProviderRequestContext): Promise<ProviderHealth>;
+    chat(request: ChatRequest, context?: ProviderRequestContext): Promise<ChatResponse>;
+    private createSession;
+    private request;
+}
+/**
+ * Flattens the message list into the single `content` string the endpoint takes.
+ *
+ * Labelled rather than concatenated: a bare join of `["You are terse.", "2+2?"]` loses which was
+ * which, and the model then answers as if the instruction were part of the question.
+ */
+export declare function flattenMessages(messages: readonly ChatMessage[]): string;
+/**
+ * Reads a completed answer out of Token Harbor's named-event SSE body.
+ *
+ * The client's own parser is the source of truth for the shapes, and it is not OpenAI's:
+ *
+ * ```text
+ * event: chunk
+ * data: {"delta":"working"}
+ *
+ * event: thinking
+ * data: {"delta":"..."}
+ *
+ * event: done
+ * data: {}
+ * ```
+ *
+ * `chunk` is the answer text and `thinking` is the reasoning, split into their own events — so a
+ * model that thinks before answering does not have its reasoning read as the reply. `error`
+ * carries `{ code, message }` and is returned rather than thrown so the caller can name the code.
+ *
+ * **`done` is what makes a truncated body detectable.** A stream that closes without it was cut
+ * off, and the caller reports that instead of handing back half an answer labelled complete.
+ */
+export declare function decodeTokenHarborStream(body: string): {
+    content: string;
+    reasoning: string;
+    finished: boolean;
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+//# sourceMappingURL=tokenharbor-web.d.ts.map

package/dist/adapters/tokenharbor-web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenharbor-web.d.ts","sourceRoot":"","sources":["../../src/adapters/tokenharbor-web.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,oBAAoB,EAAgB,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,cAAc,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE9M;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAEH,eAAO,MAAM,wBAAwB,EAAE,UAA8B,CAAC;AA6BtE,eAAO,MAAM,eAAe;;;;;;;;IAQ1B,8DAA8D;;CAEtD,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAa,CAAC;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,CAuBA,CAAC;AAEF,wBAAgB,uBAAuB,IAAI,MAAM,EAAE,CAElD;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CA2EhE;AAwBD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAuBvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAW5E;AAUD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAExE;AAED,wBAAgB,kCAAkC,CAAC,UAAU,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAOrG;AA2BD,qBAAa,qBAAsB,YAAW,eAAe;IAC3D,QAAQ,CAAC,EAAE,SAA4B;IACvC,QAAQ,CAAC,IAAI,sBAAsB;IACnC,QAAQ,CAAC,YAAY;;;MAAyC;IAE9D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,GAAE;QAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;KAAO;IAKtE;;;;;;;OAOG;IACH,UAAU,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;IAalE;;;;OAIG;IACG,kBAAkB,CAAC,UAAU,EAAE,kBAAkB,GAAG,SAAS,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAQzI;;;;;;;OAOG;IACG,WAAW,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,cAAc,CAAC;IAc1E,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,YAAY,CAAC;YAkE/E,aAAa;IAgB3B,OAAO,CAAC,OAAO;CAYhB;AAsBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAYxE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAyC1J"}