test: add published SDK parity E2E (#70)

Generated SDK now owns public API behavior, but runtime regressions can
still pass unit tests while diverging from latest npm release.

- compares candidate package with npm `latest` across all 16 public
operations
- validates request paths and bodies, JSON parsing, SSE streams, binary
responses, async APIs, browser sessions, embeddings, search, chat, and
responses
- keeps published SDK as test-only npm alias
- runs typed `node:test` suites directly with Node 26 strip-types
- runs mock parity in dedicated PR-safe workflow
- runs live chat contract parity in separate functional workflow with
`PPLX_API_TOKEN`
- marks both Bazel targets `manual`, keeping non-hermetic tests out of
`//...`

Author: longlho

.github/workflows/e2e.yml

@@ -0,0 +1,43 @@
+name: SDK E2E
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sdk-e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e:
+    timeout-minutes: 15
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Bazel
+        uses: bazel-contrib/setup-bazel@c5acdfb288317d0b5c0bbd7a396a3dc868bb0f86
+        with:
+          bazelisk-cache: true
+          disk-cache: ${{ github.workflow }}-e2e
+          repository-cache: true
+
+      - name: Set up Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: '26'
+
+      - name: Enable pnpm
+        run: corepack enable pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Compare candidate with published SDK
+        run: bazel test //e2e:sdk_parity

.github/workflows/functional-tests.yml

@@ -0,0 +1,50 @@
+name: Functional tests
+
+on:
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: '17 9 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: functional-tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  functional-tests:
+    if: github.ref == 'refs/heads/main'
+    timeout-minutes: 15
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Bazel
+        uses: bazel-contrib/setup-bazel@c5acdfb288317d0b5c0bbd7a396a3dc868bb0f86
+        with:
+          bazelisk-cache: true
+          disk-cache: ${{ github.workflow }}-functional-tests
+          repository-cache: true
+
+      - name: Set up Node
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: '26'
+
+      - name: Enable pnpm
+        run: corepack enable pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Refresh published SDK
+        run: pnpm update published-sdk --latest
+
+      - name: Run functional tests
+        env:
+          PPLX_API_TOKEN: ${{ secrets.PPLX_API_TOKEN }}
+        run: bazel test //e2e:live --test_env=PPLX_API_TOKEN

e2e/BUILD.bazel

@@ -0,0 +1,66 @@
+load("@aspect_rules_js//js:defs.bzl", "js_test")
+load("@aspect_rules_ts//ts:defs.bzl", "ts_project")
+load("//:ts.bzl", "ts_library")
+load("//:tsconfig.bzl", "BASE_COMPILER_OPTIONS")
+
+package(default_visibility = ["//visibility:private"])
+
+js_test(
+    name = "sdk_parity",
+    data = [
+        ":typecheck",
+        "//:node_modules/@perplexity-ai/perplexity_ai",
+        "//:node_modules/published-sdk",
+    ],
+    entry_point = "sdk-parity.ts",
+    tags = ["manual"],
+)
+
+js_test(
+    name = "live",
+    data = [
+        ":typecheck",
+        "//:node_modules/@perplexity-ai/perplexity_ai",
+        "//:node_modules/published-sdk",
+    ],
+    entry_point = "live.ts",
+    tags = ["manual"],
+)
+
+ts_project(
+    name = "typecheck",
+    srcs = [
+        "live.ts",
+        "sdk-parity.ts",
+    ],
+    no_emit = True,
+    tags = ["manual"],
+    tsc = "//:tsc",
+    tsconfig = {
+        "compilerOptions": dict(
+            BASE_COMPILER_OPTIONS,
+            module = "ESNext",
+            moduleResolution = "Bundler",
+            types = ["node"],
+        ),
+    },
+    deps = [
+        "//:node_modules/@perplexity-ai/perplexity_ai",
+        "//:node_modules/@types/node",
+        "//:node_modules/published-sdk",
+    ],
+)
+
+ts_library(
+    name = "e2e",
+    srcs = [
+        "live.ts",
+        "sdk-parity.ts",
+    ],
+    tsconfig_types = ["node"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "//:node_modules/@types/node",
+        "//:node_modules/published-sdk",
+    ],
+)

e2e/live.ts

@@ -0,0 +1,62 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+// oxlint-disable-next-line no-restricted-imports -- Verify packaged public entrypoint.
+import { Perplexity as Candidate } from '@perplexity-ai/perplexity_ai';
+import { Perplexity as Published } from 'published-sdk';
+
+interface CompletionResponse {
+  choices: Array<{
+    index: number;
+    message: {
+      content: string;
+      role: string;
+    };
+    [key: string]: unknown;
+  }>;
+  id: string;
+  model: string;
+  [key: string]: unknown;
+}
+
+function completionContract(response: unknown) {
+  assert.ok(typeof response === 'object' && response !== null);
+  const completion = response as CompletionResponse;
+
+  assert.equal(typeof completion.id, 'string');
+  assert.equal(typeof completion.model, 'string');
+  assert.ok(Array.isArray(completion.choices));
+  assert.ok(completion.choices.length > 0);
+
+  const choice = completion.choices[0];
+  assert.ok(choice);
+  assert.equal(typeof choice.index, 'number');
+  assert.equal(typeof choice.message?.content, 'string');
+  assert.equal(choice.message?.role, 'assistant');
+
+  return {
+    choiceKeys: Object.keys(choice).sort(),
+    messageKeys: Object.keys(choice.message).sort(),
+    responseKeys: Object.keys(completion).sort(),
+  };
+}
+
+const request = {
+  max_tokens: 16,
+  messages: [{ content: 'Reply with only the word pong.', role: 'user' as const }],
+  model: 'sonar',
+  temperature: 0,
+};
+
+describe('live API parity', () => {
+  it('matches published chat completion response contract', async () => {
+    const apiKey = process.env['PPLX_API_TOKEN'];
+    assert.ok(apiKey, 'PPLX_API_TOKEN must be set');
+
+    const [candidateResponse, publishedResponse] = await Promise.all([
+      new Candidate({ apiKey, maxRetries: 0 }).chat.completions.create(request),
+      new Published({ apiKey, maxRetries: 0 }).chat.completions.create(request),
+    ]);
+
+    assert.deepStrictEqual(completionContract(candidateResponse), completionContract(publishedResponse));
+  });
+});