Skip to content

Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.

98.3 KB
Raw Blame
import { beforeEach, describe, expect, it, onTestFinished, vi } from "vitest";

// Mock server-only before any imports that might need it
vi.mock("server-only", () => ({}));

const mockDeletePoll = vi.fn();
const mockCreatePoll = vi.fn();
const mockGetPollResults = vi.fn();
const mockGetPollParticipants = vi.fn();
const mockGetPollParticipant = vi.fn();
const mockListPolls = vi.fn();
const mockGetPollWithOptions = vi.fn();
const mockGetSpaceMemberByEmail = vi.fn();
const mockTrack = vi.fn();
const mockIdentifyGroup = vi.fn();

const mockGetAvailableConferencingProviders = vi.fn(() => [] as string[]);
const mockGetConnectedConferencingProviders = vi.fn(
  async (_userId: string) => [] as string[],
);

vi.mock("@/features/conferencing/constants", () => ({
  isConferencingEnabled: false,
  getAvailableConferencingProviders: () =>
    mockGetAvailableConferencingProviders(),
}));

vi.mock("@/features/conferencing/data", () => ({
  getConnectedConferencingProviders: (userId: string) =>
    mockGetConnectedConferencingProviders(userId),
  parsePollConferencing: (value: unknown) => value,
}));

vi.mock("@/features/moderation/mutations", () => ({
  moderateContent: vi.fn().mockResolvedValue({ verdict: "safe", reason: "" }),
}));

vi.mock("@/features/poll/mutations", () => ({
  deletePoll: (...args: unknown[]) => mockDeletePoll(...args),
  createPoll: (...args: unknown[]) => mockCreatePoll(...args),
}));

vi.mock("@/features/poll/data", () => ({
  getPollResults: (...args: unknown[]) => mockGetPollResults(...args),
  getPollParticipants: (...args: unknown[]) => mockGetPollParticipants(...args),
  getPollParticipant: (...args: unknown[]) => mockGetPollParticipant(...args),
  listPolls: (...args: unknown[]) => mockListPolls(...args),
  getPollWithOptions: (...args: unknown[]) => mockGetPollWithOptions(...args),
}));

vi.mock("@/features/space/member/data", () => ({
  getSpaceMemberByEmail: (...args: unknown[]) =>
    mockGetSpaceMemberByEmail(...args),
}));

// Hoisted so the tests can drive the api-key middleware's lookups without
// importing @rallly/database, which the DAL lint bans outside data/mutations.
const prisma = vi.hoisted(() => ({
  spaceApiKey: {
    findUnique: vi.fn(),
    findMany: vi.fn(),
    update: vi.fn(),
  },
  user: {
    findUnique: vi.fn(),
  },
}));

vi.mock("@rallly/database", () => ({ prisma }));

vi.mock("@rallly/utils/absolute-url", () => ({
  absoluteUrl: (path = "") => `https://example.com${path}`,
  shortUrl: (path: string) => `https://example.com${path}`,
}));

vi.mock("@rallly/utils/nanoid", () => ({
  nanoid: () => "test-poll-id",
}));

vi.mock("next/server", () => ({
  after: vi.fn(),
}));

vi.mock("@/lib/feature-flags/server", () => ({
  isFeatureEnabled: () => false,
}));

vi.mock("@/lib/kv", async () => ({
  redis: (await import("../../middleware/fake-redis")).createFakeRedis(),
}));

vi.mock("@/lib/posthog", () => ({
  track: (...args: unknown[]) => mockTrack(...args),
  identifyGroup: (...args: unknown[]) => mockIdentifyGroup(...args),
  flushPostHog: vi.fn(),
}));

import { logger } from "@rallly/logger";
import { after } from "next/server";
import { hashApiKey, verifyApiKey } from "@/features/api-keys/utils";
import { moderateContent } from "@/features/moderation/mutations";
import { MAX_POLL_TITLE_LENGTH } from "@/features/poll/schema";
import { MAX_SLOT_GENERATION_DAYS } from "@/lib/datetime/slot-generator";
import { redis } from "@/lib/kv";
import type { FakeRedis } from "../../middleware/fake-redis";
import { RATE_LIMIT_PER_MINUTE } from "../../middleware/rate-limit";
import { createPollRequestExamples } from "../examples";
import {
  createPollInputSchema,
  deletePollSuccessResponseSchema,
  errorResponseSchema,
  getPollParticipantSuccessResponseSchema,
  getPollParticipantsSuccessResponseSchema,
  getPollResultsSuccessResponseSchema,
  listPollsSuccessResponseSchema,
  pollResponseSchema,
} from "../schemas";
import { app, GET, POST } from "./route";

const expectMatchesContract = (
  schema: {
    safeParse: (data: unknown) => { success: boolean; error?: unknown };
  },
  body: unknown,
) => {
  const result = schema.safeParse(body);
  expect(result.error).toBeUndefined();
  expect(result.success).toBe(true);
};

// Every failure must be the documented `{ error: { code, message } }` JSON
// envelope, whichever layer produced it (bearer auth, validator, handler,
// notFound, onError).
const expectErrorEnvelope = async (
  res: Response,
  { status, code }: { status: number; code: string },
) => {
  expect(res.status).toBe(status);
  expect(res.headers.get("content-type")).toMatch(/^application\/json/);
  const json = await res.json();
  expectMatchesContract(errorResponseSchema, json);
  expect(json.error.code).toBe(code);
  expect(typeof json.error.message).toBe("string");
  return json as { error: { code: string; message: string } };
};

// Pre-generated test API key fixture. The stored hash deliberately uses the
// deprecated scrypt format so every test in this file exercises the legacy
// verification path that existing production keys depend on.
const testApiKey = "sk_eXzkd84Y_bN24KFwZ_UyiQ0b6zckpNfL2pSdng3r3";
const mockApiKey = {
  id: "api-key-id",
  name: "Test API Key",
  prefix: "eXzkd84Y",
  spaceId: "test-space-id",
  hashedKey:
    "scrypt$16384$8$1$AvCRsm3--6zUOTmMdmM5Jg$4fe1f6de88b70ed9f78aa89752e632cc6ff628194dd42bd34a8cf8e71b23e19ba23ceb9c6371f6eed9129a8afee81bdad8b5b31351162178e2a8b68381102940",
  lastUsedAt: null,
  expiresAt: null,
  revokedAt: null,
  createdAt: new Date("2025-01-01"),
  updatedAt: new Date("2025-01-01"),
  space: {
    ownerId: "test-user-id",
    tier: "pro",
    owner: { banned: false },
  },
};

describe("API v1 - /polls", () => {
  beforeEach(() => {
    vi.clearAllMocks();
    (redis as unknown as FakeRedis).reset();

    // Mock findMany for the timing-safe lookup
    vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([mockApiKey]);
    vi.mocked(prisma.spaceApiKey.findUnique).mockResolvedValue(mockApiKey);
    vi.mocked(prisma.spaceApiKey.update).mockResolvedValue({} as never);
    vi.mocked(prisma.user.findUnique).mockResolvedValue({
      id: "test-user-id",
    } as never);
    mockGetSpaceMemberByEmail.mockResolvedValue(null);

    // Mock createPoll mutation
    mockCreatePoll.mockResolvedValue({
      id: "test-poll-id",
      title: "Test Poll",
      description: null,
      location: null,
      conferencing: null,
      timeZone: null,
      status: "open",
      kind: "date",
      createdAt: new Date("2025-01-10T12:00:00Z"),
      updatedAt: new Date("2025-01-10T12:00:00Z"),
      requireParticipantEmail: false,
      hideParticipants: false,
      hideScores: false,
      disableComments: true,
      allowTentativeVotes: true,
      participantCount: 0,
      user: {
        id: "test-user-id",
        name: "Test User",
        email: "[email protected]",
        image: null,
      },
      options: [],
      adminUrl: "https://example.com/poll/test-poll-id",
      inviteUrl: "https://example.com/invite/test-poll-id",
    });
  });

  describe("Authentication", () => {
    it("should return 401 without authorization header", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      await expectErrorEnvelope(res, { status: 401, code: "UNAUTHORIZED" });
      expect(res.headers.get("WWW-Authenticate")).not.toBeNull();
    });

    it("should return 401 with invalid API key", async () => {
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([]);

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: "Bearer invalid_key",
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      await expectErrorEnvelope(res, { status: 401, code: "UNAUTHORIZED" });
      expect(res.headers.get("WWW-Authenticate")).not.toBeNull();
    });

    it("should return 401 with revoked API key", async () => {
      // Revoked keys are filtered out by the database query
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([]);

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      await expectErrorEnvelope(res, { status: 401, code: "UNAUTHORIZED" });
      expect(res.headers.get("WWW-Authenticate")).not.toBeNull();
    });

    it("should return 401 with expired API key", async () => {
      // Expired keys are filtered out by the database query
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([]);

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      await expectErrorEnvelope(res, { status: 401, code: "UNAUTHORIZED" });
      expect(res.headers.get("WWW-Authenticate")).not.toBeNull();
    });
  });

  describe("Pro tier enforcement", () => {
    it("should return 403 with SPACE_NOT_PRO when the space is not pro", async () => {
      const hobbyApiKey = {
        ...mockApiKey,
        space: { ...mockApiKey.space, tier: "hobby" },
      };
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([hobbyApiKey]);

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(403);
      const json = await res.json();
      expect(json.error.code).toBe("SPACE_NOT_PRO");
    });

    it("should not schedule a lastUsedAt write when the space is not pro", async () => {
      const hobbyApiKey = {
        ...mockApiKey,
        hashedKey: hashApiKey(testApiKey),
        lastUsedAt: null,
        space: { ...mockApiKey.space, tier: "hobby" },
      };
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([hobbyApiKey]);

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(403);
      expect(after).not.toHaveBeenCalled();
    });

    it("should return 200 with a valid key when the space is pro", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(201);
    });
  });

  describe("content moderation", () => {
    it("rejects a flagged poll with INAPPROPRIATE_CONTENT", async () => {
      vi.mocked(moderateContent).mockResolvedValueOnce({
        verdict: "flagged",
        reason: "phishing",
      });

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          title: "Verify your account",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      await expectErrorEnvelope(res, {
        status: 400,
        code: "INAPPROPRIATE_CONTENT",
      });
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });
  });

  describe("banned owner", () => {
    it("rejects a valid key when the space owner is banned", async () => {
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([
        {
          ...mockApiKey,
          hashedKey: hashApiKey(testApiKey),
          space: { ...mockApiKey.space, owner: { banned: true } },
        },
      ]);

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      await expectErrorEnvelope(res, { status: 401, code: "UNAUTHORIZED" });
      expect(after).not.toHaveBeenCalled();
    });
  });

  describe("lastUsedAt throttling", () => {
    it("should not schedule a write when lastUsedAt is recent", async () => {
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([
        {
          ...mockApiKey,
          hashedKey: hashApiKey(testApiKey),
          lastUsedAt: new Date(Date.now() - 30_000),
        },
      ]);

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).not.toBe(401);
      expect(after).not.toHaveBeenCalled();
    });

    it("should schedule a write when lastUsedAt is stale", async () => {
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([
        {
          ...mockApiKey,
          hashedKey: hashApiKey(testApiKey),
          lastUsedAt: new Date(Date.now() - 120_000),
        },
      ]);

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).not.toBe(401);
      expect(after).toHaveBeenCalledTimes(1);
    });

    it("should schedule a write when lastUsedAt is null", async () => {
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([
        {
          ...mockApiKey,
          hashedKey: hashApiKey(testApiKey),
          lastUsedAt: null,
        },
      ]);

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).not.toBe(401);
      expect(after).toHaveBeenCalledTimes(1);
    });

    it("should still re-hash a legacy key when lastUsedAt is recent", async () => {
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([
        {
          ...mockApiKey,
          lastUsedAt: new Date(Date.now() - 30_000),
        },
      ]);

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).not.toBe(401);
      expect(after).toHaveBeenCalledTimes(1);
    });
  });

  describe("Hash migration (scrypt -> sha256)", () => {
    // The lastUsedAt/re-hash update runs in an after() callback; invoke the
    // captured callbacks to simulate the post-response phase
    const flushAfterCallbacks = async () => {
      for (const [callback] of vi.mocked(after).mock.calls) {
        await (callback as () => Promise<unknown>)();
      }
    };

    it("should authenticate a legacy scrypt-hashed key and re-hash it to sha256", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(201);
      await flushAfterCallbacks();

      expect(prisma.spaceApiKey.update).toHaveBeenCalledWith({
        where: { id: mockApiKey.id },
        data: expect.objectContaining({
          hashedKey: expect.stringMatching(/^sha256\$/),
        }),
      });

      // The re-hashed value must still verify the original key
      const updateCall = vi.mocked(prisma.spaceApiKey.update).mock.calls[0];
      const newHash = updateCall?.[0]?.data?.hashedKey as string;
      expect(await verifyApiKey(testApiKey, newHash)).toBe(true);
    });

    it("should authenticate a sha256-hashed key without re-hashing", async () => {
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([
        { ...mockApiKey, hashedKey: hashApiKey(testApiKey) },
      ]);

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(201);
      await flushAfterCallbacks();

      expect(prisma.spaceApiKey.update).toHaveBeenCalledWith({
        where: { id: mockApiKey.id },
        data: { lastUsedAt: expect.any(Date) },
      });
    });
  });

  describe("Create poll with dates", () => {
    it("should create a poll with date options", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team offsite",
          kind: "date",
          options: [
            { date: "2025-01-15" },
            { date: "2025-01-16" },
            { date: "2025-01-17" },
          ],
        }),
      });

      expect(res.status).toBe(201);
      const json = await res.json();
      expectMatchesContract(pollResponseSchema, json);
      expect(json.data.id).toBe("test-poll-id");
      expect(json.data.adminUrl).toBe("https://example.com/poll/test-poll-id");
      expect(json.data.inviteUrl).toBe(
        "https://example.com/invite/test-poll-id",
      );

      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          title: "Team offsite",
          options: [
            {
              startTime: new Date("2025-01-15T00:00:00.000Z"),
              duration: 0,
            },
            {
              startTime: new Date("2025-01-16T00:00:00.000Z"),
              duration: 0,
            },
            {
              startTime: new Date("2025-01-17T00:00:00.000Z"),
              duration: 0,
            },
          ],
        }),
      );
    });

    it("should respond 201 with the settings, organizer and participantCount round-tripped", async () => {
      mockCreatePoll.mockResolvedValueOnce({
        id: "test-poll-id",
        title: "Team offsite",
        description: null,
        location: null,
        timeZone: null,
        status: "open",
        kind: "date",
        createdAt: new Date("2025-01-10T12:00:00Z"),
        updatedAt: new Date("2025-01-10T12:00:00Z"),
        requireParticipantEmail: true,
        hideParticipants: true,
        hideScores: true,
        disableComments: false,
        allowTentativeVotes: true,
        participantCount: 0,
        user: {
          id: "test-user-id",
          name: "Test User",
          email: "[email protected]",
          image: null,
        },
        options: [],
      });

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team offsite",
          kind: "date",
          options: [{ date: "2025-01-15" }],
          requireEmail: true,
          hideParticipants: true,
          hideScores: true,
          disableComments: false,
        }),
      });

      expect(res.status).toBe(201);
      const json = await res.json();
      expectMatchesContract(pollResponseSchema, json);
      expect(json.data).toMatchObject({
        requireEmail: true,
        hideParticipants: true,
        hideScores: true,
        disableComments: false,
        allowTentativeVotes: true,
        participantCount: 0,
        updatedAt: "2025-01-10T12:00:00.000Z",
        organizer: {
          id: "test-user-id",
          name: "Test User",
          email: "[email protected]",
          image: null,
        },
      });
      expect(json).not.toHaveProperty("data.user");

      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          requireParticipantEmail: true,
          hideParticipants: true,
          hideScores: true,
          disableComments: false,
        }),
      );
    });

    it("should create a yes/no poll when tentative votes are turned off", async () => {
      mockCreatePoll.mockResolvedValueOnce({
        id: "test-poll-id",
        title: "Team offsite",
        description: null,
        location: null,
        timeZone: null,
        status: "open",
        kind: "date",
        createdAt: new Date("2025-01-10T12:00:00Z"),
        updatedAt: new Date("2025-01-10T12:00:00Z"),
        requireParticipantEmail: false,
        hideParticipants: false,
        hideScores: false,
        disableComments: true,
        allowTentativeVotes: false,
        participantCount: 0,
        user: {
          id: "test-user-id",
          name: "Test User",
          email: "[email protected]",
          image: null,
        },
        options: [],
      });

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team offsite",
          kind: "date",
          options: [{ date: "2025-01-15" }],
          allowTentativeVotes: false,
        }),
      });

      expect(res.status).toBe(201);
      const json = await res.json();
      expectMatchesContract(pollResponseSchema, json);
      expect(json.data.allowTentativeVotes).toBe(false);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({ allowTentativeVotes: false }),
      );
    });

    it("should track poll creation with source api and kind date", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team offsite",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockTrack).toHaveBeenCalledWith(
        { id: "test-user-id", isGuest: false },
        expect.objectContaining({
          event: "poll_create",
          properties: expect.objectContaining({
            kind: "date",
            source: "api",
            apiVersion: "v1",
          }),
          groups: { poll: "test-poll-id", space: "test-space-id" },
        }),
      );
      expect(mockIdentifyGroup).toHaveBeenCalledWith(
        expect.objectContaining({
          groupType: "poll",
          groupKey: "test-poll-id",
          properties: expect.objectContaining({ kind: "date" }),
        }),
      );
    });

    it("should save location when provided", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team offsite",
          location: "Conference Room A",
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          title: "Team offsite",
          location: "Conference Room A",
        }),
      );
    });

    it("stores a custom video call and echoes it back", async () => {
      mockCreatePoll.mockImplementationOnce(async (input) => ({
        id: "test-poll-id",
        title: input.title,
        description: null,
        location: null,
        conferencing: input.conferencing,
        timeZone: null,
        status: "open",
        kind: "date",
        createdAt: new Date("2025-01-10T12:00:00Z"),
        updatedAt: new Date("2025-01-10T12:00:00Z"),
        requireParticipantEmail: false,
        hideParticipants: false,
        hideScores: false,
        disableComments: true,
        allowTentativeVotes: true,
        participantCount: 0,
        user: null,
        options: [],
      }));
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          conferencing: {
            provider: "custom",
            label: "Microsoft Teams",
            uri: "https://teams.microsoft.com/l/meetup-join/abc",
          },
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          conferencing: {
            provider: "custom",
            label: "Microsoft Teams",
            uri: "https://teams.microsoft.com/l/meetup-join/abc",
          },
        }),
      );
      const body = await res.json();
      expect(body.data.conferencing).toEqual({
        provider: "custom",
        label: "Microsoft Teams",
        uri: "https://teams.microsoft.com/l/meetup-join/abc",
      });
    });

    it("rejects a non-http custom link", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          conferencing: {
            provider: "custom",
            label: "Call",
            uri: "javascript:alert(1)",
          },
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(400);
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it("rejects a provider the instance does not offer", async () => {
      mockGetAvailableConferencingProviders.mockReturnValueOnce([]);
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          conferencing: { provider: "zoom" },
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(400);
      expect((await res.json()).error.code).toBe("CONFERENCING_UNAVAILABLE");
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it("rejects a provider the organizer has not connected", async () => {
      mockGetAvailableConferencingProviders.mockReturnValueOnce(["zoom"]);
      mockGetConnectedConferencingProviders.mockResolvedValueOnce([]);
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          conferencing: { provider: "zoom" },
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(400);
      expect((await res.json()).error.code).toBe("CONFERENCING_NOT_CONNECTED");
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it("stores a connected provider", async () => {
      mockGetAvailableConferencingProviders.mockReturnValueOnce(["zoom"]);
      mockGetConnectedConferencingProviders.mockResolvedValueOnce(["zoom"]);
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          conferencing: { provider: "zoom" },
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({ conferencing: { provider: "zoom" } }),
      );
    });

    it("should return error when too many date options", async () => {
      const dates = Array.from({ length: 101 }, (_, i) => {
        const date = new Date(2025, 0, 1 + i);
        return date.toISOString().split("T")[0];
      });

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: dates.map((date) => ({ date })),
        }),
      });

      expect(res.status).toBe(400);
      const json = await res.json();
      expect(json.error.code).toBe("TOO_MANY_OPTIONS");
    });

    it("should remove duplicate dates instead of rejecting them", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [
            { date: "2025-01-15" },
            { date: "2025-01-16" },
            { date: "2025-01-15" },
            { date: "2025-01-17" },
          ],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          options: [
            { startTime: new Date("2025-01-15T00:00:00.000Z"), duration: 0 },
            { startTime: new Date("2025-01-16T00:00:00.000Z"), duration: 0 },
            { startTime: new Date("2025-01-17T00:00:00.000Z"), duration: 0 },
          ],
        }),
      );
    });
  });

  describe("Create poll with time options", () => {
    it("should create a poll with time slot options", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          kind: "time",
          duration: 30,
          timeZone: "Europe/London",
          options: [
            { startTime: "2025-01-15T09:00:00Z" },
            { startTime: "2025-01-15T10:00:00Z" },
          ],
        }),
      });

      expect(res.status).toBe(201);
      const json = await res.json();
      expectMatchesContract(pollResponseSchema, json);
      expect(json.data.id).toBe("test-poll-id");

      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          title: "Team sync",
          timeZone: "Europe/London",
        }),
      );
    });

    it("should track poll creation with source api and kind time", async () => {
      mockCreatePoll.mockResolvedValueOnce({
        id: "test-poll-id",
        title: "Team sync",
        description: null,
        location: null,
        timeZone: "Europe/London",
        status: "open",
        kind: "time",
        createdAt: new Date("2025-01-10T12:00:00Z"),
        updatedAt: new Date("2025-01-10T12:00:00Z"),
        requireParticipantEmail: false,
        hideParticipants: false,
        hideScores: false,
        disableComments: true,
        allowTentativeVotes: true,
        participantCount: 0,
        user: {
          id: "test-user-id",
          name: "Test User",
          email: "[email protected]",
          image: null,
        },
        options: [
          {
            id: "opt-1",
            startTime: new Date("2025-01-15T09:00:00Z"),
            duration: 30,
          },
        ],
      });

      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          kind: "time",
          duration: 30,
          timeZone: "Europe/London",
          options: [{ startTime: "2025-01-15T09:00:00Z" }],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockTrack).toHaveBeenCalledWith(
        { id: "test-user-id", isGuest: false },
        expect.objectContaining({
          event: "poll_create",
          properties: expect.objectContaining({
            kind: "time",
            source: "api",
            apiVersion: "v1",
          }),
        }),
      );
      expect(mockIdentifyGroup).toHaveBeenCalledWith(
        expect.objectContaining({
          properties: expect.objectContaining({ kind: "time" }),
        }),
      );
    });

    it("should create poll without timezone when not provided in request", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          kind: "time",
          duration: 30,
          options: [{ startTime: "2025-01-15T09:00:00Z" }],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          timeZone: undefined,
        }),
      );
    });

    it("should return error for invalid timezone", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          kind: "time",
          duration: 30,
          timeZone: "Invalid/Timezone",
          options: [{ startTime: "2025-01-15T09:00:00Z" }],
        }),
      });

      expect(res.status).toBe(400);
    });

    it("should create poll with slot generator", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Weekly standup",
          kind: "time",
          duration: 30,
          timeZone: "Europe/London",
          generators: [
            {
              startDate: "2025-01-20",
              endDate: "2025-01-22",
              days: ["mon", "tue", "wed"],
              from: "09:00",
              to: "10:00",
            },
          ],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalled();
    });

    it("should reject a slot generator range longer than the supported limit", async () => {
      // A 516-day range, one Sunday slot each week (~74 slots). Deliberately
      // under MAX_POLL_OPTIONS so TOO_MANY_OPTIONS can't mask it: only the
      // range check rejects this. The old code silently truncated to ~52 slots
      // and returned them as a successful poll.
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Way too long",
          kind: "time",
          duration: 30,
          timeZone: "Europe/London",
          generators: [
            {
              startDate: "2025-01-01",
              endDate: "2026-06-01",
              days: ["sun"],
              from: "09:00",
              to: "09:30",
            },
          ],
        }),
      });

      // Rejected up front by validation, not silently truncated into a poll.
      // Assert the error targets endDate + names the limit so an unrelated 400
      // (e.g. TOO_MANY_OPTIONS) can't mask a regression.
      expect(res.status).toBe(400);
      expect(mockCreatePoll).not.toHaveBeenCalled();
      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain("endDate");
      expect(json.error.message).toContain(String(MAX_SLOT_GENERATION_DAYS));
    });

    it("should reject a slot generator range where endDate precedes startDate", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Reversed range",
          kind: "time",
          duration: 30,
          timeZone: "Europe/London",
          generators: [
            {
              startDate: "2025-06-01",
              endDate: "2025-01-01",
              days: ["mon"],
              from: "09:00",
              to: "10:00",
            },
          ],
        }),
      });

      expect(res.status).toBe(400);
      expect(mockCreatePoll).not.toHaveBeenCalled();
      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain("endDate");
    });

    it("should reject a range spanning exactly MAX_SLOT_GENERATION_DAYS", async () => {
      // The generator processes days inclusively, so a span equal to the cap is
      // one day too many — the boundary must reject, not truncate.
      const start = new Date(Date.UTC(2025, 0, 1));
      const end = new Date(start);
      end.setUTCDate(end.getUTCDate() + MAX_SLOT_GENERATION_DAYS);
      const toIsoDate = (d: Date) => d.toISOString().slice(0, 10);
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Boundary range",
          kind: "time",
          duration: 30,
          timeZone: "Europe/London",
          generators: [
            {
              startDate: toIsoDate(start),
              endDate: toIsoDate(end),
              days: ["sun"],
              from: "09:00",
              to: "09:30",
            },
          ],
        }),
      });

      expect(res.status).toBe(400);
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });
    it("should let a slot override the poll duration", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          kind: "time",
          duration: 30,
          options: [
            { startTime: "2025-01-15T09:00:00Z" },
            { startTime: "2025-01-15T10:00:00Z", duration: 45 },
          ],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          options: [
            { startTime: new Date("2025-01-15T09:00:00Z"), duration: 30 },
            { startTime: new Date("2025-01-15T10:00:00Z"), duration: 45 },
          ],
        }),
      );
    });

    it("should accept slots that each carry a duration when the poll has no default", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          kind: "time",
          options: [{ startTime: "2025-01-15T09:00:00Z", duration: 45 }],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          options: [
            { startTime: new Date("2025-01-15T09:00:00Z"), duration: 45 },
          ],
        }),
      );
    });

    it("should name the slot that has no duration when the poll has no default", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          kind: "time",
          options: [
            { startTime: "2025-01-15T09:00:00Z", duration: 45 },
            { startTime: "2025-01-15T10:00:00Z" },
          ],
        }),
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain("options.1.duration");
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it("should require a poll duration when generators are used", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Weekly standup",
          kind: "time",
          generators: [
            {
              startDate: "2025-01-20",
              endDate: "2025-01-22",
              from: "09:00",
              to: "10:00",
            },
          ],
        }),
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain("duration");
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it("should require options or generators on a time poll", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Team sync",
          kind: "time",
          duration: 30,
        }),
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain("options");
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it("should default a generator to every day of the week", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Any day",
          kind: "time",
          duration: 30,
          timeZone: "Europe/London",
          generators: [
            {
              // Saturday to Sunday
              startDate: "2025-01-18",
              endDate: "2025-01-19",
              from: "09:00",
              to: "09:30",
            },
          ],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          options: [
            { startTime: new Date("2025-01-18T09:00:00Z"), duration: 30 },
            { startTime: new Date("2025-01-19T09:00:00Z"), duration: 30 },
          ],
        }),
      );
    });

    it("should append generated slots to explicit ones and drop duplicates", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Mixed",
          kind: "time",
          duration: 30,
          timeZone: "Europe/London",
          options: [{ startTime: "2025-01-20T09:00:00" }],
          generators: [
            {
              startDate: "2025-01-20",
              endDate: "2025-01-20",
              days: ["mon"],
              from: "09:00",
              to: "10:00",
            },
          ],
        }),
      });

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          options: [
            { startTime: new Date("2025-01-20T09:00:00Z"), duration: 30 },
            { startTime: new Date("2025-01-20T09:30:00Z"), duration: 30 },
          ],
        }),
      );
    });

    it.each([
      {
        reason: "the window ends before it starts",
        generator: { from: "12:00", to: "09:00" },
        path: "generators.0.to",
      },
      {
        reason: "the window is shorter than the duration",
        generator: { from: "09:00", to: "09:15" },
        path: "generators.0.to",
      },
      {
        reason: "the range contains none of the listed days",
        // 2025-01-20 to 2025-01-22 is Monday to Wednesday
        generator: { from: "09:00", to: "10:00", days: ["sat", "sun"] },
        path: "generators.0.days",
      },
    ])("should reject a generator at validation when $reason", async ({
      generator,
      path,
    }) => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Bad generator",
          kind: "time",
          duration: 30,
          timeZone: "Europe/London",
          generators: [
            { startDate: "2025-01-20", endDate: "2025-01-22", ...generator },
          ],
        }),
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain(path);
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });
  });

  describe("Validation", () => {
    it("should return error when options are missing", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
        }),
      });

      expect(res.status).toBe(400);
    });

    it("should return error when a date poll carries time fields", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
          timeZone: "Europe/London",
          duration: 30,
        }),
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain("timeZone");
      expect(json.error.message).toContain("duration");
    });

    it("should return error when title is missing", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(400);
    });

    it("should reject unknown fields such as spaceId instead of ignoring them", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
          spaceId: "some-other-space",
        }),
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain("spaceId");
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it.each([
      {
        level: "organizer",
        body: {
          title: "Test Poll",
          kind: "date",
          options: [{ date: "2025-01-15" }],
          organizer: { email: "[email protected]", name: "Ann" },
        },
        message: 'organizer: Unrecognized key: "name"',
      },
      {
        level: "time poll",
        body: {
          title: "Test Poll",
          kind: "time",
          duration: 30,
          options: [{ startTime: "2025-01-15T09:00:00Z" }],
          timezone: "Europe/London",
        },
        message: 'Unrecognized key: "timezone"',
      },
      {
        level: "slot generator",
        body: {
          title: "Test Poll",
          kind: "time",
          duration: 30,
          generators: [
            {
              startDate: "2025-01-13",
              endDate: "2025-01-17",
              days: ["mon"],
              from: "09:00",
              to: "12:00",
              step: 60,
            },
          ],
        },
        message: 'generators.0: Unrecognized key: "step"',
      },
    ])("should reject unknown fields nested in the $level object", async ({
      body,
      message,
    }) => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify(body),
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain(message);
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it("should reject a title longer than the maximum length", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "x".repeat(MAX_POLL_TITLE_LENGTH + 1),
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toMatch(/^title: /);
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it("should accept a title at the maximum length", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "x".repeat(MAX_POLL_TITLE_LENGTH),
          kind: "date",
          options: [{ date: "2025-01-15" }],
        }),
      });

      expect(res.status).toBe(201);
    });

    it("should return error when dates array is empty", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${testApiKey}`,
        },
        body: JSON.stringify({
          title: "Test Poll",
          kind: "date",
          options: [],
        }),
      });

      expect(res.status).toBe(400);
    });
  });

  describe("Route handler path prefix", () => {
    it("should serve /v1 as delivered by the API host rewrite", async () => {
      const res = await GET(new Request("https://api.example.com/v1/openapi"));

      expect(res.status).toBe(200);
      expect((await res.json()).info.title).toBe("Rallly API");
    });

    it("should serve /api/v1 on the app host by stripping the prefix", async () => {
      const res = await GET(new Request("https://example.com/api/v1/openapi"));

      expect(res.status).toBe(200);
      expect((await res.json()).info.title).toBe("Rallly API");
    });

    it("should keep the method and body when stripping the prefix", async () => {
      const res = await POST(
        new Request("https://example.com/api/v1/polls", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${testApiKey}`,
          },
          body: JSON.stringify({
            title: "Forwarded through the prefix handler",
            kind: "date",
            options: [{ date: "2027-03-01" }],
          }),
        }),
      );

      expect(res.status).toBe(201);
      expect(mockCreatePoll).toHaveBeenCalledWith(
        expect.objectContaining({
          title: "Forwarded through the prefix handler",
        }),
      );
    });
  });

  describe("OpenAPI endpoints", () => {
    it("should return OpenAPI spec", async () => {
      const res = await app.request("/v1/openapi");

      expect(res.status).toBe(200);
      const json = await res.json();
      expect(json.info.title).toBe("Rallly API");
      expect(json.info.version).toBe("1.0.0");
    });

    it("should state the versioning policy and point the playground at this origin's /api prefix when there is no API host", async () => {
      const res = await app.request("/v1/openapi");

      expect(res.status).toBe(200);
      const json = await res.json();
      expect(json.info.description).toContain("## Versioning");
      expect(json.info.description).toContain("new version prefix");
      expect(json.servers).toEqual([{ url: "https://example.com/api" }]);
    });

    it("should include create poll request examples that match the input schema", async () => {
      const res = await app.request("/v1/openapi");

      expect(res.status).toBe(200);
      const json = await res.json();
      const media =
        json.paths["/v1/polls"].post.requestBody.content["application/json"];
      expect(Object.keys(media.examples)).toEqual(
        Object.keys(createPollRequestExamples),
      );

      for (const example of Object.values(createPollRequestExamples)) {
        const result = createPollInputSchema.safeParse(example.value);
        expect(result.error).toBeUndefined();
        expect(result.success).toBe(true);
      }
    });

    it("should emit schema descriptions, examples and named components", async () => {
      const res = await app.request("/v1/openapi");

      expect(res.status).toBe(200);
      const json = await res.json();
      const schemas = json.components.schemas;

      expect(Object.keys(schemas)).toEqual(
        expect.arrayContaining([
          "CreatePollInput",
          "CreateDatePollInput",
          "CreateTimePollInput",
          "DateOptionInput",
          "TimeOptionInput",
          "SlotGenerator",
          "Poll",
          "PollStatus",
          "PollResponse",
          "OptionResult",
          "ErrorResponse",
        ]),
      );
      // Option shapes are unions keyed by the poll kind; both variants are
      // named components and the score description states it is opaque.
      expect(schemas.OptionResult.anyOf).toEqual([
        { $ref: "#/components/schemas/DateOptionResult" },
        { $ref: "#/components/schemas/TimeOptionResult" },
      ]);
      expect(schemas.TimeOptionResult.properties.score.description).toContain(
        "Opaque ranking value",
      );
      expect(schemas.DateOptionResult.properties.date.format).toBe("date");
      expect(schemas.Poll.properties.title.example).toBe("Team sync");
      expect(
        json.paths["/v1/polls"].post.requestBody.content["application/json"]
          .schema,
      ).toEqual({ $ref: "#/components/schemas/CreatePollInput" });
      // The request body is a union keyed by kind, and each variant's
      // options mirror the response option shapes.
      expect(schemas.CreatePollInput).toMatchObject({
        oneOf: [
          { $ref: "#/components/schemas/CreateDatePollInput" },
          { $ref: "#/components/schemas/CreateTimePollInput" },
        ],
        discriminator: { propertyName: "kind" },
      });
      expect(schemas.CreateDatePollInput.properties.options.items).toEqual({
        $ref: "#/components/schemas/DateOptionInput",
      });
      expect(schemas.CreateTimePollInput.properties.options.items).toEqual({
        $ref: "#/components/schemas/TimeOptionInput",
      });
      expect(schemas.CreateTimePollInput.properties.generators.items).toEqual({
        $ref: "#/components/schemas/SlotGenerator",
      });
      expect(schemas.SlotGenerator.properties.days.default).toEqual([
        "mon",
        "tue",
        "wed",
        "thu",
        "fri",
        "sat",
        "sun",
      ]);

      // Contextual .meta() clones keep pointing at the shared component.
      const pollStatusRef = "#/components/schemas/PollStatus";
      expect(
        schemas.GetPollResultsResponse.properties.data.properties.status,
      ).toMatchObject({
        $ref: pollStatusRef,
        description: expect.stringContaining("close automatically"),
      });
      expect(json.paths["/v1/polls"].get.parameters).toContainEqual(
        expect.objectContaining({
          name: "status",
          schema: expect.objectContaining({ $ref: pollStatusRef }),
        }),
      );

      // Every $ref must resolve, and zod's intermediate keys must not leak.
      const refs = new Set<string>();
      const leaked: string[] = [];
      JSON.stringify(json, (key, value) => {
        if (key === "$ref") refs.add(value);
        if (key === "$defs" || key === "$schema") leaked.push(key);
        if (key === "id" && typeof value === "string") leaked.push(key);
        return value;
      });
      expect(leaked).toEqual([]);
      for (const ref of refs) {
        expect(ref).toMatch(/^#\/components\/schemas\//);
        expect(schemas[ref.split("/").pop() as string]).toBeDefined();
      }
    });

    it("should document 201 for create, strict inputs and realistic ID examples", async () => {
      const res = await app.request("/v1/openapi");

      expect(res.status).toBe(200);
      const json = await res.json();
      const schemas = json.components.schemas;
      const createResponses = json.paths["/v1/polls"].post.responses;

      expect(createResponses["201"]).toBeDefined();
      expect(createResponses["200"]).toBeUndefined();

      for (const variant of [
        schemas.CreateDatePollInput,
        schemas.CreateTimePollInput,
      ]) {
        expect(variant.additionalProperties).toBe(false);
        expect(variant.properties.spaceId).toBeUndefined();
        expect(variant.properties.title.maxLength).toBe(MAX_POLL_TITLE_LENGTH);

        // Input and output use the same setting names and organizer field.
        for (const key of [
          "requireEmail",
          "hideParticipants",
          "hideScores",
          "disableComments",
          "allowTentativeVotes",
        ]) {
          expect(variant.properties[key]).toBeDefined();
          expect(schemas.Poll.properties[key]).toBeDefined();
        }
      }
      expect(schemas.Poll.properties.user).toBeUndefined();
      expect(schemas.Poll.properties.organizer).toMatchObject({
        anyOf: expect.arrayContaining([
          { $ref: "#/components/schemas/PollOrganizer" },
        ]),
      });
      expect(schemas.PollOrganizer.properties.email).toBeDefined();
      expect(schemas.Poll.properties.participantCount).toBeDefined();
      expect(schemas.Poll.properties.updatedAt.format).toBe("date-time");
      expect(schemas.ListPollItem).toBeUndefined();
      expect(schemas.ListPollsResponse.properties.data.items).toEqual({
        $ref: "#/components/schemas/Poll",
      });

      // Real IDs carry no prefix: polls are 12-char nanoids, everything else a cuid.
      const nanoidExample = /^[0-9A-Za-z]{12}$/;
      const cuidExample = /^c[a-z0-9]{24}$/;
      expect(schemas.Poll.properties.id.example).toMatch(nanoidExample);
      expect(
        schemas.DeletePollResponse.properties.data.properties.id.example,
      ).toMatch(nanoidExample);
      expect(schemas.TimeOption.properties.id.example).toMatch(cuidExample);
      expect(schemas.DateOption.properties.id.example).toMatch(cuidExample);
      expect(schemas.Participant.properties.id.example).toMatch(cuidExample);
      expect(JSON.stringify(json)).not.toMatch(
        /p_123abc|opt_abc123|participant_abc123|space_abc123/,
      );
    });

    it("should serve the spec without a no-store header", async () => {
      const res = await app.request("/v1/openapi");

      expect(res.status).toBe(200);
      expect(res.headers.get("Cache-Control")).toBeNull();
    });

    it("should not serve a docs page (the reference lives in the docs site)", async () => {
      const res = await app.request("/v1/docs");

      expect(res.status).toBe(404);
    });
  });

  describe("Delete poll", () => {
    it("should delete a poll", async () => {
      mockDeletePoll.mockResolvedValue({ id: "test-poll-id" });

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "DELETE",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(deletePollSuccessResponseSchema, json);
      expect(json.data.id).toBe("test-poll-id");
      expect(json.data.deleted).toBe(true);

      expect(mockDeletePoll).toHaveBeenCalledWith(
        "test-poll-id",
        "test-space-id",
      );
    });

    it("should return 404 when poll not found", async () => {
      mockDeletePoll.mockResolvedValue(null);

      const res = await app.request("/v1/polls/nonexistent-poll", {
        method: "DELETE",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(404);
      const json = await res.json();
      expect(json.error.code).toBe("POLL_NOT_FOUND");
    });

    it("should return 404 when poll belongs to different space", async () => {
      mockDeletePoll.mockResolvedValue(null);

      const res = await app.request("/v1/polls/other-space-poll", {
        method: "DELETE",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(404);
      const json = await res.json();
      expect(json.error.code).toBe("POLL_NOT_FOUND");
    });

    it("should return 401 without authorization", async () => {
      const res = await app.request("/v1/polls/test-poll-id", {
        method: "DELETE",
      });

      expect(res.status).toBe(401);
    });

    it("should return 404 when poll is already deleted", async () => {
      mockDeletePoll.mockResolvedValue(null);

      const res = await app.request("/v1/polls/deleted-poll-id", {
        method: "DELETE",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(404);
      const json = await res.json();
      expect(json.error.code).toBe("POLL_NOT_FOUND");
    });
  });

  describe("Get poll", () => {
    const mockPoll = {
      id: "test-poll-id",
      title: "Team sync",
      description: "Weekly team meeting",
      location: "Zoom",
      timeZone: "Europe/London",
      status: "open",
      kind: "time",
      createdAt: new Date("2025-01-10T12:00:00Z"),
      updatedAt: new Date("2025-01-12T08:30:00Z"),
      requireParticipantEmail: true,
      hideParticipants: false,
      hideScores: true,
      disableComments: false,
      allowTentativeVotes: true,
      participantCount: 5,
      user: {
        id: "user-1",
        name: "John Doe",
        email: "[email protected]",
        image: "https://example.com/avatar.jpg",
      },
      options: [
        {
          id: "opt-1",
          startTime: new Date("2025-01-15T09:00:00Z"),
          duration: 30,
        },
        {
          id: "opt-2",
          startTime: new Date("2025-01-15T10:00:00Z"),
          duration: 30,
        },
      ],
    };

    it("should return poll data", async () => {
      mockGetPollWithOptions.mockResolvedValue(mockPoll);

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(pollResponseSchema, json);
      expect(json.data.id).toBe("test-poll-id");
      expect(json.data.title).toBe("Team sync");
      expect(json.data.description).toBe("Weekly team meeting");
      expect(json.data.location).toBe("Zoom");
      expect(json.data.timeZone).toBe("Europe/London");
      expect(json.data.status).toBe("open");
      expect(json.data.kind).toBe("time");
      expect(json.data.createdAt).toBe("2025-01-10T12:00:00.000Z");
      expect(json.data.updatedAt).toBe("2025-01-12T08:30:00.000Z");
      expect(json.data.organizer).toEqual({
        id: "user-1",
        name: "John Doe",
        email: "[email protected]",
        image: "https://example.com/avatar.jpg",
      });
      expect(json).not.toHaveProperty("data.user");
      expect(json.data.participantCount).toBe(5);
      expect(json.data.requireEmail).toBe(true);
      expect(json.data.hideParticipants).toBe(false);
      expect(json.data.hideScores).toBe(true);
      expect(json.data.disableComments).toBe(false);
      expect(json.data.options).toHaveLength(2);
      expect(json.data.options[0]).toEqual({
        id: "opt-1",
        startTime: "2025-01-15T09:00:00.000Z",
        duration: 30,
      });
      expect(json.data.adminUrl).toBe("https://example.com/poll/test-poll-id");
      expect(json.data.inviteUrl).toBe(
        "https://example.com/invite/test-poll-id",
      );

      expect(mockGetPollWithOptions).toHaveBeenCalledWith({
        pollId: "test-poll-id",
        spaceId: "test-space-id",
      });
    });

    it("should return calendar dates instead of datetimes for date polls", async () => {
      mockGetPollWithOptions.mockResolvedValue({
        ...mockPoll,
        timeZone: null,
        kind: "date",
        options: [
          {
            id: "opt-1",
            startTime: new Date("2025-01-15T00:00:00.000Z"),
            duration: 0,
          },
          {
            id: "opt-2",
            startTime: new Date("2025-01-16T00:00:00.000Z"),
            duration: 0,
          },
        ],
      });

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(pollResponseSchema, json);
      expect(json.data.kind).toBe("date");
      expect(json.data.options).toEqual([
        { id: "opt-1", date: "2025-01-15" },
        { id: "opt-2", date: "2025-01-16" },
      ]);
    });

    it("should return a null organizer when the organizer account is gone", async () => {
      mockGetPollWithOptions.mockResolvedValue({
        ...mockPoll,
        user: null,
      });

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expect(json.data.organizer).toBeNull();
    });

    it("should return 404 when poll not found", async () => {
      mockGetPollWithOptions.mockResolvedValue(null);

      const res = await app.request("/v1/polls/nonexistent-poll", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(404);
      const json = await res.json();
      expect(json.error.code).toBe("POLL_NOT_FOUND");
    });

    it("should return 404 when poll belongs to different space", async () => {
      mockGetPollWithOptions.mockResolvedValue(null);

      const res = await app.request("/v1/polls/other-space-poll", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(404);
      const json = await res.json();
      expect(json.error.code).toBe("POLL_NOT_FOUND");
    });

    it("should return 401 without authorization", async () => {
      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
      });

      expect(res.status).toBe(401);
    });
  });

  describe("List polls", () => {
    const mockListedPoll = {
      id: "test-poll-id",
      title: "Team sync",
      description: "Weekly team meeting",
      location: "Zoom",
      timeZone: "Europe/London",
      status: "open",
      kind: "time",
      createdAt: new Date("2025-01-10T12:00:00Z"),
      updatedAt: new Date("2025-01-10T12:00:00Z"),
      requireParticipantEmail: false,
      hideParticipants: false,
      hideScores: false,
      disableComments: true,
      allowTentativeVotes: true,
      user: {
        id: "user-1",
        name: "John Doe",
        email: "[email protected]",
        image: null,
      },
      options: [
        {
          id: "opt-1",
          startTime: new Date("2025-01-15T09:00:00Z"),
          duration: 30,
        },
      ],
      participantCount: 3,
    };

    it("should return a list of polls", async () => {
      mockListPolls.mockResolvedValue({
        polls: [mockListedPoll],
        nextCursor: null,
      });

      const res = await app.request("/v1/polls", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(listPollsSuccessResponseSchema, json);

      expect(json.data).toHaveLength(1);
      expect(json.data[0].id).toBe("test-poll-id");
      expect(json.data[0].title).toBe("Team sync");
      expect(json.data[0].status).toBe("open");
      expect(json.data[0].participantCount).toBe(3);
      expect(json.data[0].updatedAt).toBe("2025-01-10T12:00:00.000Z");
      expect(json.data[0].organizer.email).toBe("[email protected]");
      expect(json.data[0].kind).toBe("time");
      expect(json.data[0].createdAt).toBe("2025-01-10T12:00:00.000Z");
      expect(json.data[0].options).toEqual([
        {
          id: "opt-1",
          startTime: "2025-01-15T09:00:00.000Z",
          duration: 30,
        },
      ]);
      expect(json.data[0].adminUrl).toBe(
        "https://example.com/poll/test-poll-id",
      );
      expect(json.data[0].inviteUrl).toBe(
        "https://example.com/invite/test-poll-id",
      );
      expect(json.nextCursor).toBeNull();

      expect(mockListPolls).toHaveBeenCalledWith({
        spaceId: "test-space-id",
        status: undefined,
        cursor: undefined,
        limit: 20,
      });
    });

    it("should return calendar dates for date polls in the list", async () => {
      mockListPolls.mockResolvedValue({
        polls: [
          {
            ...mockListedPoll,
            timeZone: null,
            kind: "date",
            options: [
              {
                id: "opt-1",
                startTime: new Date("2025-01-15T00:00:00.000Z"),
                duration: 0,
              },
            ],
          },
        ],
        nextCursor: null,
      });

      const res = await app.request("/v1/polls", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(listPollsSuccessResponseSchema, json);
      expect(json.data[0].kind).toBe("date");
      expect(json.data[0].options).toEqual([
        { id: "opt-1", date: "2025-01-15" },
      ]);
    });

    it("should return an empty list when the space has no polls", async () => {
      mockListPolls.mockResolvedValue({
        polls: [],
        nextCursor: null,
      });

      const res = await app.request("/v1/polls", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(listPollsSuccessResponseSchema, json);
      expect(json.data).toEqual([]);
      expect(json.nextCursor).toBeNull();
    });

    it("should pass the status filter to the query", async () => {
      mockListPolls.mockResolvedValue({
        polls: [],
        nextCursor: null,
      });

      const res = await app.request("/v1/polls?status=open", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      expect(mockListPolls).toHaveBeenCalledWith(
        expect.objectContaining({
          spaceId: "test-space-id",
          status: "open",
        }),
      );
    });

    it("should return 400 for an invalid status", async () => {
      const res = await app.request("/v1/polls?status=finalized", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(400);
      expect(mockListPolls).not.toHaveBeenCalled();
    });

    it("should pass cursor and limit to the query and return nextCursor", async () => {
      mockListPolls.mockResolvedValue({
        polls: [mockListedPoll],
        nextCursor: "test-poll-id",
      });

      const res = await app.request("/v1/polls?cursor=prev-poll-id&limit=1", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(listPollsSuccessResponseSchema, json);
      expect(json.nextCursor).toBe("test-poll-id");

      expect(mockListPolls).toHaveBeenCalledWith(
        expect.objectContaining({
          cursor: "prev-poll-id",
          limit: 1,
        }),
      );
    });

    it("should return 400 when limit exceeds the maximum", async () => {
      const res = await app.request("/v1/polls?limit=101", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(400);
      expect(mockListPolls).not.toHaveBeenCalled();
    });

    it("should return 401 without authorization", async () => {
      const res = await app.request("/v1/polls", {
        method: "GET",
      });

      expect(res.status).toBe(401);
    });
  });

  describe("Get poll results", () => {
    it("should return aggregated vote results", async () => {
      mockGetPollResults.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "time",
        status: "open",
        participantCount: 5,
        highScore: 4003,
        options: [
          {
            id: "opt-1",
            startTime: new Date("2025-01-15T09:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 3 },
              { type: "ifNeedBe", count: 1 },
              { type: "no", count: 1 },
            ],
            score: 4003,
            isTopChoice: true,
          },
          {
            id: "opt-2",
            startTime: new Date("2025-01-15T10:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 1 },
              { type: "ifNeedBe", count: 0 },
              { type: "no", count: 2 },
            ],
            score: 1001,
            isTopChoice: false,
          },
          {
            id: "opt-3",
            startTime: new Date("2025-01-15T11:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 0 },
              { type: "ifNeedBe", count: 0 },
              { type: "no", count: 0 },
            ],
            score: 0,
            isTopChoice: false,
          },
        ],
      });

      const res = await app.request("/v1/polls/test-poll-id/results", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(getPollResultsSuccessResponseSchema, json);

      expect(json.data.pollId).toBe("test-poll-id");
      expect(json.data.status).toBe("open");
      expect(json.data.participantCount).toBe(5);
      expect(json.data.highScore).toBe(4003);
      expect(json.data.kind).toBe("time");
      expect(json.data.options).toHaveLength(3);
      expect(json.data.options[0]).toEqual({
        id: "opt-1",
        startTime: "2025-01-15T09:00:00.000Z",
        duration: 30,
        votes: [
          { type: "yes", count: 3 },
          { type: "ifNeedBe", count: 1 },
          { type: "no", count: 1 },
        ],
        score: 4003,
        isTopChoice: true,
      });
      // Every vote type is present even when nobody chose it.
      expect(json.data.options[2].votes).toEqual([
        { type: "yes", count: 0 },
        { type: "ifNeedBe", count: 0 },
        { type: "no", count: 0 },
      ]);

      expect(mockGetPollResults).toHaveBeenCalledWith({
        pollId: "test-poll-id",
        spaceId: "test-space-id",
      });
    });

    it("should return calendar dates for date poll results", async () => {
      mockGetPollResults.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "date",
        status: "open",
        participantCount: 2,
        highScore: 2002,
        options: [
          {
            id: "opt-1",
            startTime: new Date("2025-01-15T00:00:00.000Z"),
            duration: 0,
            votes: [
              { type: "yes", count: 2 },
              { type: "ifNeedBe", count: 0 },
              { type: "no", count: 0 },
            ],
            score: 2002,
            isTopChoice: true,
          },
        ],
      });

      const res = await app.request("/v1/polls/test-poll-id/results", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(getPollResultsSuccessResponseSchema, json);
      expect(json.data.kind).toBe("date");
      expect(json.data.options[0]).toEqual({
        id: "opt-1",
        date: "2025-01-15",
        votes: [
          { type: "yes", count: 2 },
          { type: "ifNeedBe", count: 0 },
          { type: "no", count: 0 },
        ],
        score: 2002,
        isTopChoice: true,
      });
    });

    it("should return the poll status for closed polls", async () => {
      mockGetPollResults.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "time",
        status: "closed",
        participantCount: 1,
        highScore: 1001,
        options: [
          {
            id: "opt-1",
            startTime: new Date("2025-01-15T09:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 1 },
              { type: "ifNeedBe", count: 0 },
              { type: "no", count: 0 },
            ],
            score: 1001,
            isTopChoice: true,
          },
        ],
      });

      const res = await app.request("/v1/polls/test-poll-id/results", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(getPollResultsSuccessResponseSchema, json);
      expect(json.data.status).toBe("closed");
    });

    it("should handle ties for top choice", async () => {
      mockGetPollResults.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "time",
        status: "open",
        participantCount: 2,
        highScore: 2002,
        options: [
          {
            id: "opt-1",
            startTime: new Date("2025-01-15T09:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 2 },
              { type: "ifNeedBe", count: 0 },
              { type: "no", count: 0 },
            ],
            score: 2002,
            isTopChoice: true,
          },
          {
            id: "opt-2",
            startTime: new Date("2025-01-15T10:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 2 },
              { type: "ifNeedBe", count: 0 },
              { type: "no", count: 0 },
            ],
            score: 2002,
            isTopChoice: true,
          },
        ],
      });

      const res = await app.request("/v1/polls/test-poll-id/results", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();

      // Both options have score 2002, both should be top choice
      expect(json.data.options[0].isTopChoice).toBe(true);
      expect(json.data.options[1].isTopChoice).toBe(true);
      expect(json.data.highScore).toBe(2002);
    });

    it("should prioritize total availability over yes votes", async () => {
      mockGetPollResults.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "time",
        status: "open",
        participantCount: 5,
        highScore: 5003,
        options: [
          {
            id: "opt-1",
            startTime: new Date("2025-01-15T09:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 4 },
              { type: "ifNeedBe", count: 0 },
              { type: "no", count: 0 },
            ],
            score: 4004,
            isTopChoice: false,
          },
          {
            id: "opt-2",
            startTime: new Date("2025-01-15T10:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 3 },
              { type: "ifNeedBe", count: 2 },
              { type: "no", count: 0 },
            ],
            score: 5003,
            isTopChoice: true,
          },
        ],
      });

      const res = await app.request("/v1/polls/test-poll-id/results", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();

      // 5 available (5003) beats 4 available (4004) even though opt-1 has more yes votes
      expect(json.data.options[0].score).toBe(4004);
      expect(json.data.options[0].isTopChoice).toBe(false);
      expect(json.data.options[1].score).toBe(5003);
      expect(json.data.options[1].isTopChoice).toBe(true);
    });

    it("should use yes votes as tiebreaker when availability is equal", async () => {
      mockGetPollResults.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "time",
        status: "open",
        participantCount: 4,
        highScore: 4004,
        options: [
          {
            id: "opt-1",
            startTime: new Date("2025-01-15T09:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 3 },
              { type: "ifNeedBe", count: 1 },
              { type: "no", count: 0 },
            ],
            score: 4003,
            isTopChoice: false,
          },
          {
            id: "opt-2",
            startTime: new Date("2025-01-15T10:00:00Z"),
            duration: 30,
            votes: [
              { type: "yes", count: 4 },
              { type: "ifNeedBe", count: 0 },
              { type: "no", count: 0 },
            ],
            score: 4004,
            isTopChoice: true,
          },
        ],
      });

      const res = await app.request("/v1/polls/test-poll-id/results", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();

      // Same availability (4), but opt-2 has more yes votes
      expect(json.data.options[0].score).toBe(4003);
      expect(json.data.options[0].isTopChoice).toBe(false);
      expect(json.data.options[1].score).toBe(4004);
      expect(json.data.options[1].isTopChoice).toBe(true);
    });

    it("should return 404 when poll not found", async () => {
      mockGetPollResults.mockResolvedValue(null);

      const res = await app.request("/v1/polls/nonexistent-poll/results", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(404);
      const json = await res.json();
      expect(json.error.code).toBe("POLL_NOT_FOUND");
    });

    it("should return 401 without authorization", async () => {
      const res = await app.request("/v1/polls/test-poll-id/results", {
        method: "GET",
      });

      expect(res.status).toBe(401);
    });
  });

  describe("Rate limiting", () => {
    // The rate limiter is keyed per space. Use a dedicated space id here so
    // the requests below don't count against (or get counted by) other tests.
    const rateLimitSpaceId = "rate-limit-space-id";

    beforeEach(() => {
      vi.mocked(prisma.spaceApiKey.findMany).mockResolvedValue([
        {
          ...mockApiKey,
          hashedKey: hashApiKey(testApiKey),
          spaceId: rateLimitSpaceId,
          lastUsedAt: new Date(),
        },
      ]);
    });

    it("should include standard RateLimit headers on successful responses", async () => {
      mockGetPollWithOptions.mockResolvedValue(null);

      const res = await app.request("/v1/polls/some-poll", {
        method: "GET",
        headers: { Authorization: `Bearer ${testApiKey}` },
      });

      expect(res.headers.get("RateLimit-Limit")).toBe(
        String(RATE_LIMIT_PER_MINUTE),
      );
      expect(res.headers.get("RateLimit-Remaining")).not.toBeNull();
    });

    it("should return 429 with RATE_LIMIT_EXCEEDED once the per-space limit is exceeded", async () => {
      mockGetPollWithOptions.mockResolvedValue(null);

      const request = () =>
        app.request("/v1/polls/some-poll", {
          method: "GET",
          headers: { Authorization: `Bearer ${testApiKey}` },
        });

      // The limit is RATE_LIMIT_PER_MINUTE requests/minute per space; one more trips it.
      let limited: Response | undefined;
      for (let i = 0; i < RATE_LIMIT_PER_MINUTE + 1; i++) {
        const res = await request();
        if (res.status === 429) {
          limited = res;
          break;
        }
      }

      expect(limited).toBeDefined();
      expect(limited?.status).toBe(429);
      expect(limited?.headers.get("Retry-After")).not.toBeNull();

      const json = await limited?.json();
      expect(json.error.code).toBe("RATE_LIMIT_EXCEEDED");
    });
  });

  describe("Caching", () => {
    it("should mark every key-scoped response no-store", async () => {
      mockGetPollParticipants.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "time",
        participants: [],
      });
      mockListPolls.mockResolvedValue({ polls: [], nextCursor: null });

      const responses = await Promise.all([
        app.request("/v1/polls/test-poll-id/participants", {
          headers: { Authorization: `Bearer ${testApiKey}` },
        }),
        app.request("/v1/polls", {
          headers: { Authorization: `Bearer ${testApiKey}` },
        }),
        app.request("/v1/polls/test-poll-id"),
      ]);

      for (const res of responses) {
        expect(res.headers.get("Cache-Control")).toBe("no-store");
      }
    });
  });

  describe("List poll participants", () => {
    const participants = [
      {
        id: "participant-1",
        name: "Alice",
        email: "[email protected]",
        createdAt: new Date("2025-01-10T10:00:00Z"),
        votes: [
          {
            type: "yes",
            option: {
              startTime: new Date("2025-01-15T09:00:00Z"),
              duration: 30,
            },
          },
          {
            type: "ifNeedBe",
            option: {
              startTime: new Date("2025-01-16T09:00:00Z"),
              duration: 30,
            },
          },
          {
            type: "no",
            option: {
              startTime: new Date("2025-01-17T09:00:00Z"),
              duration: 30,
            },
          },
        ],
      },
      {
        id: "participant-2",
        name: "Bob",
        email: null,
        createdAt: new Date("2025-01-10T11:00:00Z"),
        votes: [],
      },
    ];
    const aliceAvailability = [
      {
        start: "2025-01-15T09:00:00.000Z",
        end: "2025-01-15T09:30:00.000Z",
        allDay: false,
        modifiers: [],
      },
      {
        start: "2025-01-16T09:00:00.000Z",
        end: "2025-01-16T09:30:00.000Z",
        allDay: false,
        modifiers: ["ifNeedBe"],
      },
    ];

    it("should return participants in the list shape", async () => {
      mockGetPollParticipants.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "time",
        participants,
      });

      const res = await app.request("/v1/polls/test-poll-id/participants", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(getPollParticipantsSuccessResponseSchema, json);

      expect(json.data).toHaveLength(2);
      expect(json.data[0]).toEqual({
        id: "participant-1",
        name: "Alice",
        email: "[email protected]",
        createdAt: "2025-01-10T10:00:00.000Z",
        availability: aliceAvailability,
      });
      expect(json.data[1].availability).toEqual([]);
      expect(json.data[1].email).toBeNull();
      expect(json).not.toHaveProperty("nextCursor");

      expect(mockGetPollParticipants).toHaveBeenCalledWith({
        pollId: "test-poll-id",
        spaceId: "test-space-id",
      });
    });

    it("should return every participant and ignore pagination query parameters", async () => {
      mockGetPollParticipants.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "time",
        participants,
      });

      const res = await app.request(
        "/v1/polls/test-poll-id/participants?cursor=participant-1&limit=1",
        {
          method: "GET",
          headers: {
            Authorization: `Bearer ${testApiKey}`,
          },
        },
      );

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(getPollParticipantsSuccessResponseSchema, json);
      expect(json.data.map((p: { id: string }) => p.id)).toEqual([
        "participant-1",
        "participant-2",
      ]);

      expect(mockGetPollParticipants).toHaveBeenCalledWith({
        pollId: "test-poll-id",
        spaceId: "test-space-id",
      });
    });

    it("should return empty array when no participants", async () => {
      mockGetPollParticipants.mockResolvedValue({
        pollId: "test-poll-id",
        kind: "time",
        participants: [],
      });

      const res = await app.request("/v1/polls/test-poll-id/participants", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(200);
      const json = await res.json();

      expect(json.data).toEqual([]);
    });

    it("should return 404 when poll not found", async () => {
      mockGetPollParticipants.mockResolvedValue(null);

      const res = await app.request("/v1/polls/nonexistent-poll/participants", {
        method: "GET",
        headers: {
          Authorization: `Bearer ${testApiKey}`,
        },
      });

      expect(res.status).toBe(404);
      const json = await res.json();
      expect(json.error.code).toBe("POLL_NOT_FOUND");
    });

    it("should return 401 without authorization", async () => {
      const res = await app.request("/v1/polls/test-poll-id/participants", {
        method: "GET",
      });

      expect(res.status).toBe(401);
    });
  });

  describe("Get poll participant", () => {
    const participant = {
      id: "participant-1",
      name: "Alice",
      email: "[email protected]",
      createdAt: new Date("2025-01-10T10:00:00Z"),
      votes: [
        {
          type: "yes",
          option: { startTime: new Date("2025-01-15T00:00:00Z"), duration: 0 },
        },
      ],
    };
    const authed = { Authorization: `Bearer ${testApiKey}` };

    it("should return the participant with their availability", async () => {
      mockGetPollParticipant.mockResolvedValue({
        poll: { id: "test-poll-id", kind: "date" },
        participant,
      });

      const res = await app.request(
        "/v1/polls/test-poll-id/participants/participant-1",
        { method: "GET", headers: authed },
      );

      expect(res.status).toBe(200);
      const json = await res.json();
      expectMatchesContract(getPollParticipantSuccessResponseSchema, json);
      expect(json.data).toEqual({
        id: "participant-1",
        name: "Alice",
        email: "[email protected]",
        createdAt: "2025-01-10T10:00:00.000Z",
        availability: [
          {
            start: "2025-01-15T00:00:00.000Z",
            end: "2025-01-16T00:00:00.000Z",
            allDay: true,
            modifiers: [],
          },
        ],
      });
      expect(mockGetPollParticipant).toHaveBeenCalledWith({
        pollId: "test-poll-id",
        participantId: "participant-1",
        spaceId: "test-space-id",
      });
    });

    it("should return POLL_NOT_FOUND when the poll is missing", async () => {
      mockGetPollParticipant.mockResolvedValue({
        poll: null,
        participant: null,
      });

      const res = await app.request(
        "/v1/polls/nonexistent-poll/participants/participant-1",
        { method: "GET", headers: authed },
      );

      expect(res.status).toBe(404);
      expect((await res.json()).error.code).toBe("POLL_NOT_FOUND");
    });

    it("should return PARTICIPANT_NOT_FOUND when the poll exists but the participant does not", async () => {
      mockGetPollParticipant.mockResolvedValue({
        poll: { id: "test-poll-id", kind: "time" },
        participant: null,
      });

      const res = await app.request(
        "/v1/polls/test-poll-id/participants/nonexistent",
        { method: "GET", headers: authed },
      );

      expect(res.status).toBe(404);
      expect((await res.json()).error.code).toBe("PARTICIPANT_NOT_FOUND");
    });

    it("should return 401 without authorization", async () => {
      const res = await app.request(
        "/v1/polls/test-poll-id/participants/participant-1",
        { method: "GET" },
      );

      expect(res.status).toBe(401);
    });
  });

  describe("Error envelope", () => {
    const authed = { Authorization: `Bearer ${testApiKey}` };

    it("should return 400 INVALID_AUTHORIZATION_HEADER as JSON for a malformed Authorization header", async () => {
      const res = await app.request("/v1/polls", {
        method: "GET",
        headers: { Authorization: "Basic not-a-bearer-token" },
      });

      await expectErrorEnvelope(res, {
        status: 400,
        code: "INVALID_AUTHORIZATION_HEADER",
      });
      expect(res.headers.get("WWW-Authenticate")).toContain("invalid_request");
    });

    it("should return 400 VALIDATION_ERROR naming the fields, without echoing the body, for an invalid JSON body", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: { ...authed, "Content-Type": "application/json" },
        body: JSON.stringify({
          kind: "date",
          options: [{ date: "not-a-date" }],
          secret: "do-not-echo",
        }),
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toContain("title:");
      expect(json.error.message).toContain("options.0.date:");
      expect(Object.keys(json.error).sort()).toEqual(["code", "message"]);
      expect(JSON.stringify(json)).not.toContain("do-not-echo");
      expect(json).not.toHaveProperty("success");
      expect(json).not.toHaveProperty("data");
      expect(mockCreatePoll).not.toHaveBeenCalled();
    });

    it("should return 400 VALIDATION_ERROR as JSON for an invalid query string", async () => {
      const res = await app.request("/v1/polls?limit=9999", {
        method: "GET",
        headers: authed,
      });

      const json = await expectErrorEnvelope(res, {
        status: 400,
        code: "VALIDATION_ERROR",
      });
      expect(json.error.message).toMatch(/^limit: /);
      expect(mockListPolls).not.toHaveBeenCalled();
    });

    it("should return 400 VALIDATION_ERROR as JSON for a malformed JSON body", async () => {
      const res = await app.request("/v1/polls", {
        method: "POST",
        headers: { ...authed, "Content-Type": "application/json" },
        body: "{not json",
      });

      await expectErrorEnvelope(res, { status: 400, code: "VALIDATION_ERROR" });
    });

    it("should return 404 NOT_FOUND as JSON for an unknown route", async () => {
      const res = await app.request("/v1/nope", {
        method: "GET",
        headers: authed,
      });

      await expectErrorEnvelope(res, { status: 404, code: "NOT_FOUND" });
    });

    it("should return 404 NOT_FOUND as JSON for an unsupported method on a known route", async () => {
      const res = await app.request("/v1/polls", {
        method: "PUT",
        headers: authed,
      });

      await expectErrorEnvelope(res, { status: 404, code: "NOT_FOUND" });
    });

    it("should return 500 INTERNAL_ERROR as JSON and log the error when a handler behind the rate limiter throws", async () => {
      const errorSpy = vi.spyOn(logger, "error").mockImplementation(() => {});
      onTestFinished(() => errorSpy.mockRestore());
      mockGetPollWithOptions.mockRejectedValue(new TypeError("db exploded"));

      const res = await app.request("/v1/polls/test-poll-id", {
        method: "GET",
        headers: authed,
      });

      const json = await expectErrorEnvelope(res, {
        status: 500,
        code: "INTERNAL_ERROR",
      });
      // Never leak the underlying error message to the client.
      expect(json.error.message).not.toContain("db exploded");
      // The request was counted by the limiter before the handler threw.
      expect(res.headers.get("RateLimit-Limit")).not.toBeNull();

      expect(errorSpy).toHaveBeenCalledTimes(1);
      expect(errorSpy.mock.calls[0][0]).toMatchObject({
        service: "api-v1",
        statusCode: 500,
        errorType: "TypeError",
        errorMessage: "db exploded",
        spaceId: "test-space-id",
      });
    });

    it("should document the full error code list in the spec", async () => {
      const res = await app.request("/v1/openapi");
      const json = await res.json();

      for (const code of [
        "VALIDATION_ERROR",
        "UNAUTHORIZED",
        "INVALID_AUTHORIZATION_HEADER",
        "SPACE_NOT_PRO",
        "RATE_LIMIT_EXCEEDED",
        "NOT_FOUND",
        "POLL_NOT_FOUND",
        "ORGANIZER_NOT_MEMBER",
        "TOO_MANY_OPTIONS",
        "SERVICE_UNAVAILABLE",
        "INTERNAL_ERROR",
      ]) {
        expect(json.info.description).toContain(`\`${code}\``);
      }
    });
  });
});