From cdb8ee85695eca3efecd7ba303803747fc2600b4 Mon Sep 17 00:00:00 2001 From: Sidney Swift <158200036+sidneyswift@users.noreply.github.com> Date: Wed, 21 Oct 2026 18:01:54 -0400 Subject: [PATCH] test: bind published Slack author contracts to admin routes --- lib/contracts/README.md | 11 + .../publishedAdminCodingSlack.test.ts | 223 +++++++++ lib/contracts/fixtures/published-docs.json | 428 +++++++++++++++++- 3 files changed, 661 insertions(+), 1 deletion(-) create mode 100644 lib/contracts/__tests__/publishedAdminCodingSlack.test.ts diff --git a/lib/contracts/README.md b/lib/contracts/README.md index d10469b21..60dcec10c 100644 --- a/lib/contracts/README.md +++ b/lib/contracts/README.md @@ -156,3 +156,14 @@ error through the real HTTP adapter. Authentication and processSiteOperation are mocked: no lifecycle implementation, workspace/subscription lookup, production workflow, provider, publish, unpublish or delete operation runs. Static source accounting and schema examples do not prove paid eligibility or hosted behavior. + +`publishedAdminCodingSlack.test.ts` compares the documented author filter and +distinct-author options response with the actual admin GET exports, query and +authentication code. The fixture producer freezes both operations' request +declarations, examples and resolved response schemas. Slack collection and +credential/admin lookup leaves are mocked, with unexpected network/database +calls fenced off. Checks cover filtered totals, trimmed/unknown/omitted IDs, +first-profile deduplication, empty options, both 401 envelopes, 403, query 400 +and masked collection 500 responses. This does not run a real Slack collector, +verify admin access, establish history completeness/latency/quotas or introduce +an automatic caller, UI, poller, scheduled action or Slack send. diff --git a/lib/contracts/__tests__/publishedAdminCodingSlack.test.ts b/lib/contracts/__tests__/publishedAdminCodingSlack.test.ts new file mode 100644 index 000000000..7c25fc52c --- /dev/null +++ b/lib/contracts/__tests__/publishedAdminCodingSlack.test.ts @@ -0,0 +1,223 @@ +import Ajv from "ajv"; +import { NextRequest, NextResponse } from "next/server"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { GET as getMentions } from "@/app/api/admins/coding/slack/route"; +import { GET as getOptions } from "@/app/api/admins/coding-agent/slack-tags/route"; +import { getSlackTagsQuerySchema } from "@/lib/admins/slack/validateGetSlackTagsQuery"; +import fixture from "../fixtures/published-docs.json"; + +const mocks = vi.hoisted(() => ({ + key: vi.fn(), + bearer: vi.fn(), + admin: vi.fn(), + collect: vi.fn(), +})); +vi.mock("@/lib/auth/getApiKeyAccountId", () => ({ getApiKeyAccountId: mocks.key })); +vi.mock("@/lib/auth/getAuthenticatedAccountId", () => ({ + getAuthenticatedAccountId: mocks.bearer, +})); +vi.mock("@/lib/admins/checkIsAdmin", () => ({ checkIsAdmin: mocks.admin })); +vi.mock("@/lib/admins/slack/fetchSlackMentions", () => ({ fetchSlackMentions: mocks.collect })); +vi.mock("@/lib/supabase/serverClient", () => ({ + default: { + from: () => { + throw new Error("Unexpected database call in the synthetic Slack contract"); + }, + }, +})); + +interface OperationContract { + path: string; + security: unknown[]; + parameters: Array<{ name: string; schema: Record }>; + schemas: Record>; + examples: Record; +} +const contract = ( + fixture as unknown as { + adminCodingSlack?: { + mentions: OperationContract; + options: OperationContract; + queryExample: { tag: string; period: string }; + }; + } +).adminCodingSlack; +const mentions = [ + { + user_id: "U2", + user_name: "Bob", + user_avatar: null, + prompt: "newer", + timestamp: "2026-10-20T00:00:00Z", + channel_id: "C1", + channel_name: "coding", + pull_requests: ["https://example.invalid/pr/1"], + }, + { + user_id: "U1", + user_name: "Alice", + user_avatar: null, + prompt: "other", + timestamp: "2026-10-19T00:00:00Z", + channel_id: "C1", + channel_name: "coding", + pull_requests: [], + }, + { + user_id: "U2", + user_name: "Older Bob", + user_avatar: "https://example.invalid/older.png", + prompt: "older", + timestamp: "2026-10-18T00:00:00Z", + channel_id: "C1", + channel_name: "coding", + pull_requests: [], + }, +]; +const request = (path: string, headers: Record = { "x-api-key": "fixture" }) => + new NextRequest(`https://example.invalid${path}`, { headers }); + +function matches(operation: OperationContract, status: number, body: unknown) { + const validate = new Ajv({ strict: false, allErrors: true, validateFormats: false }).compile( + operation.schemas[String(status)], + ); + expect(validate(body), JSON.stringify(validate.errors)).toBe(true); +} + +beforeEach(() => { + vi.resetAllMocks(); + vi.stubGlobal( + "fetch", + vi.fn(() => { + throw new Error("Unexpected network call in Slack contract"); + }), + ); + mocks.key.mockResolvedValue("fixture-admin"); + mocks.bearer.mockResolvedValue("fixture-admin"); + mocks.admin.mockResolvedValue(true); + mocks.collect.mockResolvedValue(mentions); +}); + +afterEach(() => vi.unstubAllGlobals()); + +describe("published coding Slack author contracts", () => { + it("declares the filter and separate admin options operation", () => { + expect(contract).toBeDefined(); + expect(contract!.mentions.path).toBe("/api/admins/coding/slack"); + expect(contract!.options.path).toBe("/api/admins/coding-agent/slack-tags"); + for (const operation of [contract!.mentions, contract!.options]) { + expect(operation.security).toEqual([{ apiKeyAuth: [] }, { bearerAuth: [] }]); + } + expect(contract!.options.parameters).toEqual([]); + const tag = contract!.mentions.parameters.find(p => p.name === "tag")!; + const validate = new Ajv({ strict: false }).compile(tag.schema); + expect(validate(contract!.queryExample.tag)).toBe(true); + for (const invalid of ["", " "]) { + expect(validate(invalid)).toBe(false); + expect(getSlackTagsQuerySchema.safeParse({ tag: invalid }).success).toBe(false); + } + }); + + it.each([{ "x-api-key": "fixture" }, { authorization: "Bearer fixture" }])( + "runs the copied filter with %s and recomputes totals", + async headers => { + expect(contract).toBeDefined(); + const query = new URLSearchParams(contract!.queryExample).toString(); + const response = await getMentions(request(`${contract!.mentions.path}?${query}`, headers)); + const body = await response.json(); + expect(response.status).toBe(200); + expect(body).toMatchObject({ + total: 2, + total_pull_requests: 1, + tags_with_pull_requests: 1, + tags: [mentions[0], mentions[2]], + }); + matches(contract!.mentions, 200, body); + expect(mocks.collect).toHaveBeenCalledExactlyOnceWith(contract!.queryExample.period); + }, + ); + + it("retains omitted filtering and trims exact case-sensitive IDs after collection", async () => { + expect(contract).toBeDefined(); + const all = await getMentions(request(contract!.mentions.path)); + expect((await all.json()).total).toBe(3); + for (const [tag, total] of [ + [" U2 ", 2], + ["u2", 0], + ["UNKNOWN", 0], + ] as const) { + const response = await getMentions( + request(`${contract!.mentions.path}?tag=${encodeURIComponent(tag)}`), + ); + const body = await response.json(); + expect(body.total).toBe(total); + matches(contract!.mentions, 200, body); + } + expect(mocks.collect).toHaveBeenCalledTimes(4); + }); + + it("returns the published distinct first-profile options and empty example", async () => { + expect(contract).toBeDefined(); + const response = await getOptions(request(contract!.options.path)); + const body = await response.json(); + expect(body).toEqual(contract!.options.examples.collectedAuthors); + matches(contract!.options, 200, body); + expect(mocks.collect).toHaveBeenCalledExactlyOnceWith("all"); + mocks.collect.mockResolvedValueOnce([]); + const empty = await getOptions(request(contract!.options.path)); + const emptyBody = await empty.json(); + expect(emptyBody).toEqual(contract!.options.examples.noAuthors); + matches(contract!.options, 200, emptyBody); + const schema = contract!.options.schemas["200"] as { + properties: { tags: { items: { required: string[] } } }; + }; + expect(schema.properties.tags.items.required).toEqual(["id", "name", "avatar"]); + }); + + it.each(["tag=", "tag=%20%20", "period=yearly"])( + "declares invalid query %s before collection", + async query => { + expect(contract).toBeDefined(); + const response = await getMentions(request(`${contract!.mentions.path}?${query}`)); + expect(response.status).toBe(400); + matches(contract!.mentions, 400, await response.json()); + expect(mocks.collect).not.toHaveBeenCalled(); + }, + ); + + it.each([getMentions, getOptions])( + "preserves both 401 envelopes and 403 before collection", + async handler => { + expect(contract).toBeDefined(); + const operation = handler === getMentions ? contract!.mentions : contract!.options; + const missing = await handler(request(operation.path, {})); + expect(missing.status).toBe(401); + matches(operation, 401, await missing.json()); + mocks.key.mockResolvedValueOnce( + NextResponse.json({ status: "error", message: "Unauthorized" }, { status: 401 }), + ); + const invalid = await handler(request(operation.path)); + expect(invalid.status).toBe(401); + matches(operation, 401, await invalid.json()); + mocks.admin.mockResolvedValueOnce(false); + const forbidden = await handler(request(operation.path)); + expect(forbidden.status).toBe(403); + matches(operation, 403, await forbidden.json()); + expect(mocks.collect).not.toHaveBeenCalled(); + }, + ); + + it.each([getMentions, getOptions])( + "declares thrown collection failures without exposing internal detail", + async handler => { + expect(contract).toBeDefined(); + const operation = handler === getMentions ? contract!.mentions : contract!.options; + mocks.collect.mockRejectedValueOnce(new Error("synthetic-private-canary")); + const response = await handler(request(operation.path)); + const body = await response.json(); + expect(response.status).toBe(500); + matches(operation, 500, body); + expect(JSON.stringify(body)).not.toContain("synthetic-private-canary"); + }, + ); +}); diff --git a/lib/contracts/fixtures/published-docs.json b/lib/contracts/fixtures/published-docs.json index 9f169d8a4..c069eb936 100644 --- a/lib/contracts/fixtures/published-docs.json +++ b/lib/contracts/fixtures/published-docs.json @@ -345,7 +345,7 @@ } ], "sourceHashes": { - "content/docs/source/api-reference/openapi/accounts.json": "2d107a6832ac1732233580675b67a24af7d914bb2417dbaa9377e26677695341", + "content/docs/source/api-reference/openapi/accounts.json": "2dd43f5daf898995fe2072a720474b4a8d898dd2fcf35a92a6e3cb3b0cffefb0", "content/docs/source/api-reference/openapi/content.json": "c109fc9eb3b5557c6585f32fb4771d3ebe6103ac9532c6a7a3b8f929a2603511", "content/docs/source/api-reference/openapi/research.json": "ba0ebf1af7bb7cb1441d47830581c318cca770164ab7362c010e03f5fa381b20", "content/docs/source/api-reference/openapi/releases.json": "5823be0a303d9d4e106405aa4f7bafde9847c7bb559d0c3a4782700c1098e457", @@ -1676,6 +1676,432 @@ ], "preflightExcluded": true }, + "adminCodingSlack": { + "mentions": { + "path": "/api/admins/coding/slack", + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ], + "parameters": [ + { + "name": "period", + "in": "query", + "description": "Time period to filter tags. One of: all (no date filter), daily (last 24 hours), weekly (last 7 days), monthly (last 30 days). Defaults to all.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "all", + "daily", + "weekly", + "monthly" + ], + "default": "all" + } + }, + { + "name": "tag", + "in": "query", + "description": "Optional exact, case-sensitive Slack author ID. Leading/trailing whitespace is trimmed; blank values are rejected. This filters already collected mentions before the totals are computed and does not change access or collection work.", + "required": false, + "schema": { + "type": "string", + "minLength": 1, + "pattern": "\\S" + }, + "example": "U2" + } + ], + "schemas": { + "200": { + "type": "object", + "required": [ + "status", + "total", + "total_pull_requests", + "tags_with_pull_requests", + "tags" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "success" + ], + "description": "Status of the request" + }, + "total": { + "type": "integer", + "description": "Number of collected Coding Agent mentions after the requested period and optional author filter.", + "example": 134 + }, + "total_pull_requests": { + "type": "integer", + "description": "Number of pull request links across the filtered collected mentions.", + "example": 121 + }, + "tags_with_pull_requests": { + "type": "integer", + "description": "Number of filtered collected mentions with at least one pull request link.", + "example": 84 + }, + "tags": { + "type": "array", + "description": "List of Slack tag events", + "items": { + "type": "object", + "required": [ + "user_id", + "user_name", + "prompt", + "timestamp", + "channel_id", + "channel_name" + ], + "properties": { + "user_id": { + "type": "string", + "description": "Slack ID of the person who tagged the agent", + "example": "U012AB3CD" + }, + "user_name": { + "type": "string", + "description": "Display name of the person who tagged the agent", + "example": "Jane Smith" + }, + "user_avatar": { + "type": [ + "string", + "null" + ], + "description": "URL of the Slack avatar", + "example": "https://avatars.slack-edge.com/..." + }, + "prompt": { + "type": "string", + "description": "The text of the message sent to the agent", + "example": "add dark mode support to the settings page" + }, + "timestamp": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of the tag event", + "example": "2024-01-15T10:30:00.000Z" + }, + "channel_id": { + "type": "string", + "description": "Slack channel ID where the tag occurred", + "example": "C012AB3CD" + }, + "channel_name": { + "type": "string", + "description": "Human-readable name of the Slack channel", + "example": "dev-team" + }, + "pull_requests": { + "type": "array", + "description": "GitHub pull request URLs opened by the Coding Agent in response to this prompt, parsed from bot replies in the Slack thread", + "items": { + "type": "string", + "format": "uri", + "example": "https://github.com/recoupable/api/pull/42" + }, + "example": [ + "https://github.com/recoupable/api/pull/42" + ] + } + } + } + } + } + }, + "401": { + "description": "Missing or simultaneous authentication mechanisms return status/error. An invalid API key or Bearer credential returns status/message. Supply exactly one mechanism and authenticate a Recoup admin account.", + "oneOf": [ + { + "type": "object", + "required": [ + "status", + "error" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "string", + "description": "The first invalid query field or authentication-mechanism error." + } + } + }, + { + "type": "object", + "required": [ + "status", + "message" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Status of the request" + }, + "message": { + "type": "string", + "description": "Error message describing what went wrong" + } + } + } + ] + }, + "403": { + "type": "object", + "required": [ + "status", + "message" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Status of the request" + }, + "message": { + "type": "string", + "description": "Error message describing what went wrong" + } + } + }, + "500": { + "type": "object", + "required": [ + "status", + "message" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Status of the request" + }, + "message": { + "type": "string", + "description": "Error message describing what went wrong" + } + } + }, + "400": { + "type": "object", + "required": [ + "status", + "error" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "string", + "description": "The first invalid query field or authentication-mechanism error." + } + } + } + }, + "examples": {} + }, + "options": { + "path": "/api/admins/coding-agent/slack-tags", + "security": [ + { + "apiKeyAuth": [] + }, + { + "bearerAuth": [] + } + ], + "parameters": [], + "schemas": { + "200": { + "type": "object", + "required": [ + "status", + "total", + "tags" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "success" + ] + }, + "total": { + "type": "integer", + "minimum": 0, + "description": "Number of distinct author IDs in the collected data." + }, + "tags": { + "type": "array", + "description": "Distinct authors, deduplicated by ID and sorted by display name with the server localeCompare order. The first collected profile is retained; equal names do not merge distinct IDs.", + "items": { + "type": "object", + "required": [ + "id", + "name", + "avatar" + ], + "properties": { + "id": { + "type": "string", + "description": "Slack author ID; use it as the analytics tag filter." + }, + "name": { + "type": "string", + "description": "Display name from the first collected profile." + }, + "avatar": { + "type": [ + "string", + "null" + ], + "description": "Avatar URL from the first collected profile, or null." + } + } + } + } + } + }, + "401": { + "description": "Missing or simultaneous authentication mechanisms return status/error. An invalid API key or Bearer credential returns status/message. Supply exactly one mechanism and authenticate a Recoup admin account.", + "oneOf": [ + { + "type": "object", + "required": [ + "status", + "error" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ] + }, + "error": { + "type": "string", + "description": "The first invalid query field or authentication-mechanism error." + } + } + }, + { + "type": "object", + "required": [ + "status", + "message" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Status of the request" + }, + "message": { + "type": "string", + "description": "Error message describing what went wrong" + } + } + } + ] + }, + "403": { + "type": "object", + "required": [ + "status", + "message" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Status of the request" + }, + "message": { + "type": "string", + "description": "Error message describing what went wrong" + } + } + }, + "500": { + "type": "object", + "required": [ + "status", + "message" + ], + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ], + "description": "Status of the request" + }, + "message": { + "type": "string", + "description": "Error message describing what went wrong" + } + } + } + }, + "examples": { + "collectedAuthors": { + "status": "success", + "total": 2, + "tags": [ + { + "id": "U1", + "name": "Alice", + "avatar": null + }, + { + "id": "U2", + "name": "Bob", + "avatar": null + } + ] + }, + "noAuthors": { + "status": "success", + "total": 0, + "tags": [] + } + } + }, + "queryExample": { + "period": "all", + "tag": "U2" + } + }, "headlessChat": { "requestSchema": { "type": "object",