feat(providers): add t3.chat web provider skeleton (#1909)

Registers t3-web / t3chat-alias executor, 24-model registry, WEB_COOKIE_PROVIDERS entry, i18n hints, docs row, and 19-case test suite (all passing). Endpoint URL and SSE chunk schema require a post-devtools-capture follow-up — marked with TODO(post-devtools-capture) comments throughout.
2026-07-31 04:12:10 +03:00 · 2026-05-19 10:56:54 -03:00
parent 8b8bb3da1b
commit e7eb777969
4 changed files with 403 additions and 1 deletions
--- a/docs/reference/PROVIDER_REFERENCE.md
+++ b/docs/reference/PROVIDER_REFERENCE.md
@@ -57,7 +57,7 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each
 | `kimi-coding` | `kmc`        | Kimi Coding          | OAuth | —                                                                         | —                                                                                                                                                                     |
 | `windsurf`    | `ws`         | Windsurf (Devin CLI) | OAuth | [link](https://windsurf.com)                                              | Sign in at windsurf.com to get your token. Visit windsurf.com/show-auth-token after logging in and paste it here, or use the device-code login flow.                  |

-## Web Cookie Providers (6)
+## Web Cookie Providers (7)

 | ID               | Alias      | Name                        | Tags       | Website                           | Notes                                                                                       |
 | ---------------- | ---------- | --------------------------- | ---------- | --------------------------------- | ------------------------------------------------------------------------------------------- |
@@ -67,6 +67,7 @@ Use the dashboard at `/dashboard/providers` to enable, configure, and test each
 | `grok-web`       | `gw`       | Grok Web (Subscription)     | Web cookie | [link](https://grok.com)          | Paste your sso= cookie value from grok.com                                                  |
 | `muse-spark-web` | `ms-web`   | Muse Spark Web (Meta AI)    | Web cookie | [link](https://www.meta.ai)       | Paste your abra_sess value or full cookie header from meta.ai                               |
 | `perplexity-web` | `pplx-web` | Perplexity Web (Pro/Max)    | Web cookie | [link](https://www.perplexity.ai) | Paste your \_\_Secure-next-auth.session-token cookie value from perplexity.ai               |
+| `t3-web`         | `t3chat`   | t3.chat (Pro/Free)          | Web cookie | [link](https://t3.chat)           | Pro: $8/mo, 50+ models. Free tier: limited models. Requires Cookie header + convex-session-id from DevTools. **Skeleton — endpoint URL not yet confirmed (TODO post-devtools-capture).** |

 ## API Key Providers (paid / paid-with-free-credits) (122)

--- a/open-sse/config/providerRegistry.ts
+++ b/open-sse/config/providerRegistry.ts
@@ -2286,6 +2286,54 @@ export const REGISTRY: Record<string, RegistryEntry> = {
    ],
  },

+  // TODO(post-devtools-capture): Confirm baseUrl after Step 0 DevTools capture.
+  // Current guess: "https://t3.chat/api/chat". May be a Convex deployment URL.
+  // TODO(post-devtools-capture): Trim duplicate model entries and update model IDs
+  // to match exact values seen in the DevTools request body (model field).
+  "t3-web": {
+    id: "t3-web",
+    alias: "t3chat",
+    format: "openai",
+    executor: "t3-web",
+    baseUrl: "https://t3.chat/api/chat",
+    authType: "apikey",
+    authHeader: "cookie",
+    models: [
+      // Claude
+      { id: "claude-opus-4", name: "Claude Opus 4 (via t3.chat)" },
+      { id: "claude-sonnet-4", name: "Claude Sonnet 4 (via t3.chat)" },
+      { id: "claude-haiku-4", name: "Claude Haiku 4 (via t3.chat)" },
+      { id: "claude-3.7", name: "Claude 3.7 Sonnet (via t3.chat)" },
+      // GPT / OpenAI
+      { id: "gpt-5", name: "GPT-5 (via t3.chat)" },
+      { id: "gpt-4o", name: "GPT-4o (via t3.chat)" },
+      { id: "gpt-4.1", name: "GPT-4.1 (via t3.chat)" },
+      { id: "o3", name: "o3 (via t3.chat)" },
+      { id: "o4-mini", name: "o4-mini (via t3.chat)" },
+      // Gemini
+      { id: "gemini-2.5-pro", name: "Gemini 2.5 Pro (via t3.chat)" },
+      { id: "gemini-2.5-flash", name: "Gemini 2.5 Flash (via t3.chat)" },
+      // DeepSeek
+      { id: "deepseek-r1", name: "DeepSeek R1 (via t3.chat)", supportsReasoning: true },
+      { id: "deepseek-v3", name: "DeepSeek V3 (via t3.chat)" },
+      // Grok
+      { id: "grok-3", name: "Grok 3 (via t3.chat)" },
+      { id: "grok-3-mini", name: "Grok 3 Mini (via t3.chat)" },
+      // Llama / Meta
+      { id: "llama-4-maverick", name: "Llama 4 Maverick (via t3.chat)" },
+      { id: "llama-4-scout", name: "Llama 4 Scout (via t3.chat)" },
+      { id: "llama-3.3-70b", name: "Llama 3.3 70B (via t3.chat)" },
+      // Mistral
+      { id: "devstral", name: "Devstral (via t3.chat)" },
+      { id: "mistral-large", name: "Mistral Large (via t3.chat)" },
+      // Qwen
+      { id: "qwen3-235b", name: "Qwen3 235B (via t3.chat)", supportsReasoning: true },
+      { id: "qwen3-32b", name: "Qwen3 32B (via t3.chat)", supportsReasoning: true },
+      // Kimi
+      { id: "kimi-k2", name: "Kimi K2 (via t3.chat)" },
+    ],
+  },
+
  together: {
    id: "together",
    alias: "together",
--- a/src/i18n/messages/en.json
+++ b/src/i18n/messages/en.json
@@ -3328,6 +3328,8 @@
    "bailianBaseUrlHint": "Bailian Base Url Hint",
    "blackboxWebCookieHint": "Blackbox Web Cookie Hint",
    "blackboxWebCookiePlaceholder": "Blackbox Web Cookie Placeholder",
+    "t3ChatWebCookieHint": "Open t3.chat → DevTools → Application → Local Storage → https://t3.chat, copy 'convex-session-id'. Then open DevTools → Network, copy the full Cookie header from any chat request. Paste both values in the fields below.",
+    "t3ChatWebCookiePlaceholder": "convex-session-id=abc123...",
    "blockClaudeExtraUsageDescription": "Hide extra Claude usage rows reported by some providers when they duplicate primary token accounting.",
    "blockClaudeExtraUsageLabel": "Block duplicate Claude usage rows",
    "bulkPasteAdded": "{count, plural, one {1 key added} other {# keys added}}",
--- a/tests/unit/t3-chat-web.test.ts
+++ b/tests/unit/t3-chat-web.test.ts
@@ -0,0 +1,351 @@
+// @ts-nocheck
+import test from "node:test";
+import assert from "node:assert/strict";
+
+const { T3ChatWebExecutor, T3_CHAT_BASE } = await import(
+  "../../open-sse/executors/t3-chat-web.ts"
+);
+const { getExecutor, hasSpecializedExecutor } = await import("../../open-sse/executors/index.ts");
+
+// NOTE: These tests use mocked HTTP transport. The COMPLETION_URL constant in
+// t3-chat-web.ts is a best-guess placeholder. Tests verify executor behavior
+// and OpenAI output format, not the specific endpoint URL.
+// TODO(post-devtools-capture): Update mock URL matchers once endpoint is confirmed.
+
+// ─── Registration ────────────────────────────────────────────────────────
+
+test("hasSpecializedExecutor returns true for t3-web", () => {
+  assert.ok(hasSpecializedExecutor("t3-web"));
+});
+
+test("hasSpecializedExecutor returns true for t3chat alias", () => {
+  assert.ok(hasSpecializedExecutor("t3chat"));
+});
+
+test("getExecutor returns T3ChatWebExecutor for t3-web", () => {
+  const exec = getExecutor("t3-web");
+  assert.ok(exec instanceof T3ChatWebExecutor);
+});
+
+test("getExecutor returns T3ChatWebExecutor for t3chat alias", () => {
+  const exec = getExecutor("t3chat");
+  assert.ok(exec instanceof T3ChatWebExecutor);
+});
+
+test("T3ChatWebExecutor.getProvider() returns t3-web", () => {
+  assert.equal(new T3ChatWebExecutor().getProvider(), "t3-web");
+});
+
+// ─── Credential validation ───────────────────────────────────────────────
+
+test("execute returns 400 with empty credentials", async () => {
+  const executor = new T3ChatWebExecutor();
+  const result = await executor.execute({
+    model: "gpt-4o",
+    body: { messages: [{ role: "user", content: "hi" }] },
+    stream: true,
+    credentials: {},
+    signal: AbortSignal.timeout(5000),
+  });
+  assert.equal(result.response.status, 400);
+  const body = JSON.parse(await result.response.text());
+  assert.ok(body.error?.message, "Should have error message");
+});
+
+test("execute returns 400 with cookies present but convexSessionId missing", async () => {
+  const executor = new T3ChatWebExecutor();
+  const result = await executor.execute({
+    model: "gpt-4o",
+    body: { messages: [{ role: "user", content: "hi" }] },
+    stream: true,
+    credentials: { cookies: "some-cookie=value" },
+    signal: AbortSignal.timeout(5000),
+  });
+  assert.equal(result.response.status, 400);
+  const body = JSON.parse(await result.response.text());
+  assert.ok(body.error?.message?.length > 0, "Should have error message");
+});
+
+test("execute returns 400 with convexSessionId present but cookies missing", async () => {
+  const executor = new T3ChatWebExecutor();
+  const result = await executor.execute({
+    model: "gpt-4o",
+    body: { messages: [{ role: "user", content: "hi" }] },
+    stream: true,
+    credentials: { convexSessionId: "session-abc-123" },
+    signal: AbortSignal.timeout(5000),
+  });
+  assert.equal(result.response.status, 400);
+  const body = JSON.parse(await result.response.text());
+  assert.ok(body.error?.message?.length > 0, "Should have error message");
+});
+
+test("execute returns 400 with both fields as empty strings", async () => {
+  const executor = new T3ChatWebExecutor();
+  const result = await executor.execute({
+    model: "gpt-4o",
+    body: { messages: [{ role: "user", content: "hi" }] },
+    stream: true,
+    credentials: { cookies: "", convexSessionId: "" },
+    signal: AbortSignal.timeout(5000),
+  });
+  assert.equal(result.response.status, 400);
+});
+
+// ─── testConnection ──────────────────────────────────────────────────────
+
+test("testConnection returns false with empty credentials", async () => {
+  const executor = new T3ChatWebExecutor();
+  const result = await executor.testConnection({});
+  assert.equal(result, false);
+});
+
+test("testConnection returns false when convexSessionId is missing", async () => {
+  const executor = new T3ChatWebExecutor();
+  const result = await executor.testConnection({ cookies: "some-cookie=value" });
+  assert.equal(result, false);
+});
+
+// ─── API flow helpers ─────────────────────────────────────────────────────
+
+function makeValidCreds() {
+  return {
+    cookies: "t3-auth=session-token-xyz; other=value",
+    convexSessionId: "convex-session-id-abc123",
+  };
+}
+
+function mockT3ChatSSEResponse(chunks: string[]) {
+  const original = globalThis.fetch;
+  const calls: Array<{ url: string; method: string; headers: Record<string, string>; body: unknown }> = [];
+
+  globalThis.fetch = async (url, opts) => {
+    const urlStr = typeof url === "string" ? url : url.toString();
+    calls.push({
+      url: urlStr,
+      method: opts?.method ?? "GET",
+      headers: (opts?.headers as Record<string, string>) ?? {},
+      body: opts?.body ? JSON.parse(opts.body as string) : null,
+    });
+
+    const encoder = new TextEncoder();
+    const sseData = chunks.map((c) => `data: ${c}\n\n`).join("");
+    return new Response(encoder.encode(sseData), {
+      status: 200,
+      headers: { "Content-Type": "text/event-stream" },
+    });
+  };
+
+  return {
+    calls,
+    restore: () => {
+      globalThis.fetch = original;
+    },
+  };
+}
+
+// ─── Mocked streaming flow ───────────────────────────────────────────────
+
+test("execute: POSTs to completion URL with Cookie and convex-session-id headers (streaming)", async () => {
+  // TODO(post-devtools-capture): Update URL check once endpoint is confirmed.
+  const sseChunks = [
+    JSON.stringify({ text: "Hello" }),
+    JSON.stringify({ text: " world" }),
+    JSON.stringify({ done: true }),
+  ];
+  const mock = mockT3ChatSSEResponse(sseChunks);
+
+  try {
+    const executor = new T3ChatWebExecutor();
+    const result = await executor.execute({
+      model: "gpt-4o",
+      body: { messages: [{ role: "user", content: "Say hello" }] },
+      stream: true,
+      credentials: makeValidCreds(),
+      signal: AbortSignal.timeout(10000),
+    });
+
+    assert.ok(result.response.ok, `Expected 200, got ${result.response.status}`);
+    assert.equal(mock.calls.length, 1, "Should make exactly one fetch call");
+
+    // Verify headers were sent
+    const sentHeaders = mock.calls[0].headers;
+    assert.ok(sentHeaders["Cookie"]?.length > 0, "Should send Cookie header");
+    assert.ok(
+      // convex-session-id may be header or body — check both
+      sentHeaders["convex-session-id"]?.length > 0 ||
+        (mock.calls[0].body as any)?.convexSessionId?.length > 0,
+      "Should send convex-session-id as header or body field"
+    );
+  } finally {
+    mock.restore();
+  }
+});
+
+test("execute: streaming response contains content, finish_reason stop, and [DONE]", async () => {
+  const sseChunks = [
+    JSON.stringify({ text: "Hello" }),
+    JSON.stringify({ text: " there" }),
+    "[DONE]",
+  ];
+  const mock = mockT3ChatSSEResponse(sseChunks);
+
+  try {
+    const executor = new T3ChatWebExecutor();
+    const result = await executor.execute({
+      model: "gpt-4o",
+      body: { messages: [{ role: "user", content: "hi" }] },
+      stream: true,
+      credentials: makeValidCreds(),
+      signal: AbortSignal.timeout(10000),
+    });
+
+    assert.ok(result.response.ok);
+    assert.equal(result.response.headers.get("content-type"), "text/event-stream");
+
+    const text = await result.response.text();
+    assert.ok(text.includes('"content"'), "Should contain content field");
+    assert.ok(text.includes('"finish_reason":"stop"'), "Should have finish_reason stop");
+    assert.ok(text.includes("[DONE]"), "Should end with [DONE]");
+  } finally {
+    mock.restore();
+  }
+});
+
+test("execute: non-streaming response has choices[0].message.content", async () => {
+  const sseChunks = [JSON.stringify({ text: "Hello non-stream" }), "[DONE]"];
+  const mock = mockT3ChatSSEResponse(sseChunks);
+
+  try {
+    const executor = new T3ChatWebExecutor();
+    const result = await executor.execute({
+      model: "gpt-4o",
+      body: { messages: [{ role: "user", content: "hi" }] },
+      stream: false,
+      credentials: makeValidCreds(),
+      signal: AbortSignal.timeout(10000),
+    });
+
+    assert.ok(result.response.ok);
+    const json = JSON.parse(await result.response.text());
+    assert.equal(json.object, "chat.completion");
+    assert.ok(Array.isArray(json.choices) && json.choices.length > 0, "Should have choices");
+    assert.equal(json.choices[0].message.role, "assistant");
+    assert.ok(typeof json.choices[0].message.content === "string", "Should have string content");
+  } finally {
+    mock.restore();
+  }
+});
+
+// ─── Error handling ──────────────────────────────────────────────────────
+
+test("execute: upstream 401 → returns 401 with session expired message", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => new Response("Unauthorized", { status: 401 });
+
+  try {
+    const executor = new T3ChatWebExecutor();
+    const result = await executor.execute({
+      model: "gpt-4o",
+      body: { messages: [{ role: "user", content: "hi" }] },
+      stream: true,
+      credentials: makeValidCreds(),
+      signal: AbortSignal.timeout(5000),
+    });
+    assert.equal(result.response.status, 401);
+    const body = JSON.parse(await result.response.text());
+    assert.ok(
+      body.error?.message?.toLowerCase().includes("session") ||
+        body.error?.message?.toLowerCase().includes("expired") ||
+        body.error?.message?.toLowerCase().includes("unauthorized"),
+      "Should mention session/expired/unauthorized"
+    );
+  } finally {
+    globalThis.fetch = original;
+  }
+});
+
+test("execute: upstream 403 → returns 403 with descriptive message", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => new Response("Forbidden", { status: 403 });
+
+  try {
+    const executor = new T3ChatWebExecutor();
+    const result = await executor.execute({
+      model: "gpt-4o",
+      body: { messages: [{ role: "user", content: "hi" }] },
+      stream: true,
+      credentials: makeValidCreds(),
+      signal: AbortSignal.timeout(5000),
+    });
+    assert.equal(result.response.status, 403);
+    const body = JSON.parse(await result.response.text());
+    assert.ok(body.error?.message?.length > 0, "Should have error message");
+  } finally {
+    globalThis.fetch = original;
+  }
+});
+
+test("execute: upstream 429 → returns 429", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => new Response("Too Many Requests", { status: 429 });
+
+  try {
+    const executor = new T3ChatWebExecutor();
+    const result = await executor.execute({
+      model: "gpt-4o",
+      body: { messages: [{ role: "user", content: "hi" }] },
+      stream: true,
+      credentials: makeValidCreds(),
+      signal: AbortSignal.timeout(5000),
+    });
+    assert.equal(result.response.status, 429);
+  } finally {
+    globalThis.fetch = original;
+  }
+});
+
+test("execute: AbortSignal abort → returns 499", async () => {
+  const executor = new T3ChatWebExecutor();
+  const controller = new AbortController();
+  controller.abort();
+
+  const result = await executor.execute({
+    model: "gpt-4o",
+    body: { messages: [{ role: "user", content: "hi" }] },
+    stream: true,
+    credentials: makeValidCreds(),
+    signal: controller.signal,
+  });
+
+  // AbortError before fetch is even called returns 499 or 400 from creds check;
+  // with valid creds and aborted signal the fetch throws AbortError → 499.
+  assert.ok(result.response.status >= 400, "Should indicate an error status");
+});
+
+// ─── Error sanitization ──────────────────────────────────────────────────
+
+test("execute: error responses do not include raw stack traces", async () => {
+  const original = globalThis.fetch;
+  globalThis.fetch = async () => {
+    throw new Error("Something went wrong\n    at /home/user/app/executor.ts:42:5");
+  };
+
+  try {
+    const executor = new T3ChatWebExecutor();
+    const result = await executor.execute({
+      model: "gpt-4o",
+      body: { messages: [{ role: "user", content: "hi" }] },
+      stream: true,
+      credentials: makeValidCreds(),
+      signal: AbortSignal.timeout(5000),
+    });
+
+    assert.ok(result.response.status >= 400, "Should return error status");
+    const body = JSON.parse(await result.response.text());
+    const msg = body.error?.message ?? "";
+    assert.ok(!msg.includes("at /"), "Should not expose raw stack trace paths");
+  } finally {
+    globalThis.fetch = original;
+  }
+});