refactor(api): new endpoints for slackbot

apps/api/__tests__/docs-routes.test.ts

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { apiReferenceMock, generateMock } = vi.hoisted(() => ({
+  apiReferenceMock: vi.fn(() => () => new Response("openapi-ui")),
+  generateMock: vi.fn(async () => ({
+    paths: {
+      "/v1/ping": {
+        get: {},
+        post: {},
+      },
+    },
+    components: {},
+  })),
+}));
+
+vi.mock("@acme/env", () => ({
+  env: {
+    NEXT_PUBLIC_API_URL: "https://api.example.com",
+  },
+}));
+
+vi.mock("@acme/api", () => ({
+  router: {},
+}));
+
+vi.mock("@scalar/nextjs-api-reference", () => ({
+  ApiReference: apiReferenceMock,
+}));
+
+vi.mock("@orpc/openapi", () => ({
+  OpenAPIGenerator: vi.fn(() => ({
+    generate: generateMock,
+  })),
+}));
+
+vi.mock("@orpc/zod", () => ({
+  ZodToJsonSchemaConverter: vi.fn(),
+}));
+
+import { GET as getDocs } from "../src/app/docs/route";
+import { GET as getOpenApiJson } from "../src/app/docs/openapi.json/route";
+
+describe("docs routes", () => {
+  beforeEach(() => {
+    apiReferenceMock.mockClear();
+  });
+
+  it("renders the API reference page with the configured base URL", async () => {
+    const response = await getDocs();
+
+    expect(response.status).toBe(200);
+    await expect(response.text()).resolves.toBe("openapi-ui");
+    expect(apiReferenceMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: "/docs/openapi.json",
+        baseServerURL: "https://api.example.com",
+        pageTitle: "F3 Nation API Reference",
+        favicon: "/favicon.ico",
+      }),
+    );
+  });
+
+  it("returns an OpenAPI JSON document with client headers injected", async () => {
+    const response = await getOpenApiJson(
+      new Request("https://api.example.com/docs/openapi.json"),
+    );
+
+    expect(response.status).toBe(200);
+
+    const spec = (await response.json()) as {
+      components?: {
+        parameters?: Record<string, { name: string; in: string }>;
+      };
+      paths?: Record<
+        string,
+        {
+          get?: { parameters?: { $ref?: string }[] };
+          post?: { parameters?: { $ref?: string }[] };
+        }
+      >;
+    };
+
+    expect(spec.components?.parameters?.ClientHeader).toMatchObject({
+      name: "client",
+      in: "header",
+    });
+    expect(spec.paths?.["/v1/ping"]?.get?.parameters?.[0]).toMatchObject({
+      $ref: "#/components/parameters/ClientHeader",
+    });
+    expect(spec.paths?.["/v1/ping"]?.post?.parameters?.[0]).toMatchObject({
+      $ref: "#/components/parameters/ClientHeader",
+    });
+
+    const generateCalls = generateMock.mock.calls as unknown[][];
+    const generateOptions = generateCalls[0]?.[1] as
+      | { filter?: (args: { path: string[] }) => boolean }
+      | undefined;
+
+    expect(generateOptions?.filter).toBeTypeOf("function");
+    expect(generateOptions?.filter?.({ path: ["slack"] })).toBe(false);
+    expect(generateOptions?.filter?.({ path: ["ping"] })).toBe(true);
+  });
+});

apps/api/src/app/docs/openapi.json/route.ts

@@ -54,6 +54,7 @@ export async function GET(request: Request) {
   });
 
   const spec = (await generator.generate(router, {
+    filter: ({ path }) => path[0] !== "slack",
     info: {
       title: "F3 Nation API",
       version: packageJson.version,
@@ -106,6 +107,7 @@ API keys inherit the roles and permissions of their owner. Access levels include
 - **Editor**: Can view and modify data within assigned organizations
 - **Admin**: Same permissions as Editor, plus the ability to add/remove other Admins and Editors
 
+
 As of February 1, 2026, regional admins can only create read-only API keys. If you want an API Key edit access to your region, you will need to contact an F3 Nation admin. Right now, regional edit access is highly restrcited. This is because the API is still new and there are almost certainly gaps in security - meaning that a region has the potential to mess up data for other regions.
 
 ## Best Practices
@@ -119,6 +121,7 @@ As of February 1, 2026, regional admins can only create read-only API keys. If y
 - **401 Unauthorized**: Missing, invalid, revoked, or expired API key
 - **403 Forbidden**: Valid API key but insufficient permissions for the requested resource
 - **429 Too Many Requests**: Rate limit exceeded (200 requests per 60 seconds)`,
+
       contact: {
         name: "F3 Nation",
         url: "https://f3nation.com",

packages/api/src/index.ts

@@ -17,6 +17,7 @@ import { orgRouter } from "./router/org";
 import { pingRouter } from "./router/ping";
 import { positionRouter } from "./router/position";
 import { requestRouter } from "./router/request";
+import { slackRouter } from "./router/slack";
 import { userRouter } from "./router/user";
 
 // Re-export webhook event types for external use
@@ -39,5 +40,6 @@ export const router = os.prefix(API_PREFIX_V1).router({
   org: os.prefix("/org").router(orgRouter),
   position: os.prefix("/position").router(positionRouter),
   request: os.prefix("/request").router(requestRouter),
+  slack: os.prefix("/slack").router(slackRouter),
   user: os.prefix("/user").router(userRouter),
 });