ci(sdk): autonomous agent-PR merge gated on tests + API-surface contract test (#3)

Two pieces that together let agent/* PRs land without a human:

- src/api-surface.test.ts: pins the public contract (exports, RektRadar
  methods, canonical api.rektradar.io REST+WS host). This is the test that
  would have caught the docs shipping `rr.stream()` (a method the SDK never
  had) and the base URL pointing at app. instead of api. Renaming or removing
  a public member now fails CI here instead of in a developer's bot.

- .github/workflows/auto-merge.yml: on green CI for an agent/* or security/*
  branch, squash-merge the PR via the built-in GITHUB_TOKEN. No org secrets,
  no Copilot pipeline (overkill for a non-deployed npm package) — the test
  suite is the gate. Publishing stays manual: npm only releases on a v* tag.

Author: mik3fly

.github/workflows/auto-merge.yml

@@ -0,0 +1,43 @@
+# Autonomous merge for agent-authored PRs.
+#
+# The SDK does not deploy and has no Copilot-review pipeline; here the test suite
+# IS the quality gate. When CI ("Build & Test" + the publish gate) passes on a
+# PR whose branch is agent/* or security/*, squash-merge it automatically. Any
+# other branch prefix is ignored, so human PRs still merge by hand.
+#
+# Uses the built-in GITHUB_TOKEN (main is unprotected) -> no org secrets needed.
+# Publishing stays manual: npm only releases on a pushed v* tag, never on merge.
+name: Auto-merge agent PRs
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'pull_request' &&
+      (startsWith(github.event.workflow_run.head_branch, 'agent/') ||
+       startsWith(github.event.workflow_run.head_branch, 'security/'))
+    runs-on: ubuntu-latest
+    steps:
+      - name: Squash-merge the green PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BRANCH: ${{ github.event.workflow_run.head_branch }}
+        run: |
+          PR=$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$BRANCH" \
+                 --state open --json number,isDraft \
+                 --jq '[.[] | select(.isDraft == false)][0].number')
+          if [ -z "$PR" ]; then
+            echo "No open non-draft PR for $BRANCH — nothing to merge."
+            exit 0
+          fi
+          echo "Auto-merging PR #$PR ($BRANCH) after green CI."
+          gh pr merge "$PR" --repo "$GITHUB_REPOSITORY" --squash --delete-branch

src/api-surface.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "vitest";
+import * as sdk from "./index.js";
+import {
+  RektRadar,
+  DEFAULT_BASE_URL,
+  connectStream,
+  streamUrl,
+  verifyWebhook,
+} from "./index.js";
+import type { FetchLike } from "./types.js";
+
+// The README, the rektradar.io/developers page and the dev.to article all
+// reference this surface by hand. When a public name is renamed or removed,
+// nothing in those hand-written examples fails until a developer copy-pastes
+// them and gets a runtime error (this is exactly how `rr.stream()` shipped in
+// the docs while the SDK only ever exposed `connectStream`). These tests pin
+// the contract so a breaking change fails CI here instead of in someone's bot.
+
+const noopFetch: FetchLike = async () => ({
+  ok: true,
+  status: 200,
+  json: async () => ({}),
+  headers: { get: () => null },
+});
+
+describe("public API surface", () => {
+  it("exports exactly the documented runtime members", () => {
+    expect(Object.keys(sdk).sort()).toEqual(
+      [
+        "DEFAULT_BASE_URL",
+        "RektRadar",
+        "RektRadarError",
+        "connectStream",
+        "streamUrl",
+        "verifyWebhook",
+      ].sort(),
+    );
+  });
+
+  it("exposes the documented RektRadar methods", () => {
+    const rr = new RektRadar({ apiKey: "rr_test", fetch: noopFetch });
+    const surface = rr as unknown as Record<string, unknown>;
+    for (const method of ["token", "tokenFull", "rugs", "recent", "topDeployers"]) {
+      expect(typeof surface[method]).toBe("function");
+    }
+  });
+
+  it("has no streaming method on the client (streaming is connectStream)", () => {
+    // The docs once wrote `rr.stream(...)`, which never existed. Streaming is a
+    // standalone `connectStream()` export. Guard against the mistake returning.
+    const rr = new RektRadar({ apiKey: "rr_test", fetch: noopFetch });
+    expect((rr as unknown as Record<string, unknown>).stream).toBeUndefined();
+    expect(typeof connectStream).toBe("function");
+    expect(typeof streamUrl).toBe("function");
+    expect(typeof verifyWebhook).toBe("function");
+  });
+
+  it("defaults to the canonical api.rektradar.io host, never app.", () => {
+    expect(DEFAULT_BASE_URL).toBe("https://api.rektradar.io");
+    expect(DEFAULT_BASE_URL).not.toContain("app.rektradar.io");
+
+    // The WebSocket origin must also be api. (the base-URL bug pointed both the
+    // REST client and the stream at app.rektradar.io). connectStream defaults to
+    // wss://api.rektradar.io when no baseUrl is passed.
+    let openedUrl = "";
+    class CaptureSocket {
+      constructor(url: string) {
+        openedUrl = url;
+      }
+      addEventListener() {}
+      removeEventListener() {}
+      close() {}
+    }
+    connectStream({
+      apiKey: "rr_test",
+      events: ["rug"],
+      onMessage: () => {},
+      WebSocket: CaptureSocket as unknown as never,
+    });
+    expect(openedUrl.startsWith("wss://api.rektradar.io")).toBe(true);
+    expect(openedUrl).not.toContain("app.rektradar.io");
+  });
+});