Rallly is an open-source scheduling and collaboration tool designed to make organizing events and meetings easier.
TypeScript i18nextnext-authnextjspostgresqlprismareact-emailt3-stacktailwindcsstrpcturborepotypescriptzod
import type { SpaceTier } from "@rallly/database";
import { prisma } from "@rallly/database";
import { absoluteUrl, shortUrl } from "@rallly/utils/absolute-url";
import { Scalar } from "@scalar/hono-api-reference";
import { Hono } from "hono";
import { handle } from "hono/vercel";
import {
describeRoute,
generateSpecs,
loadVendor,
resolver,
validator,
} from "hono-openapi";
import { after } from "next/server";
import { moderateContent } from "@/features/moderation/mutations";
import { MAX_POLL_OPTIONS } from "@/features/poll/constants";
import {
getPollParticipants,
getPollResults,
listPolls,
} from "@/features/poll/data";
import { closePoll, createPoll, deletePoll } from "@/features/poll/mutations";
import type { AuthorizedSpaceId } from "@/features/space/types";
import type { SlotGeneratorInput } from "@/lib/datetime/slot-generator";
import {
dedupeTimeSlots,
generateTimeSlots,
parseStartTime,
} from "@/lib/datetime/slot-generator";
import { isMaintenanceModeEnabled } from "@/lib/maintenance";
import { flushPostHog, identifyGroup, track } from "@/lib/posthog";
import { apiError } from "../../middleware/api-error";
import { spaceApiKeyAuth } from "../../middleware/api-key";
import { toOpenApiSchema } from "../../middleware/openapi";
import {
RATE_LIMIT_PER_DAY,
RATE_LIMIT_PER_MINUTE,
rateLimit,
} from "../../middleware/rate-limit";
import { wideEvent } from "../../middleware/wide-event";
import {
createPollRequestExamples,
patchPollRequestExamples,
} from "../examples";
import {
createPollInputSchema,
createPollSuccessResponseSchema,
deletePollSuccessResponseSchema,
errorResponseSchema,
getPollParticipantsSuccessResponseSchema,
getPollResultsSuccessResponseSchema,
getPollSuccessResponseSchema,
listPollsQuerySchema,
listPollsSuccessResponseSchema,
patchPollInputSchema,
patchPollSuccessResponseSchema,
} from "../schemas";
type Env = {
Variables: {
apiAuth: {
spaceId: AuthorizedSpaceId;
spaceOwnerId: string;
spaceTier: SpaceTier;
apiKeyId: string;
};
};
};
const app = new Hono<Env>().basePath("/api/private");
loadVendor("zod", { toOpenAPISchema: toOpenApiSchema });
function toPollResponseBody(poll: {
id: string;
title: string;
description: string | null;
location: string | null;
timeZone: string | null;
status: string;
createdAt: Date;
user: { name: string; image: string | null } | null;
options: { id: string; startTime: Date; duration: number }[];
}) {
return {
data: {
id: poll.id,
title: poll.title,
description: poll.description,
location: poll.location,
timezone: poll.timeZone,
status: poll.status,
createdAt: poll.createdAt.toISOString(),
user: poll.user
? {
name: poll.user.name,
image: poll.user.image,
}
: null,
options: poll.options.map((option) => ({
id: option.id,
startTime: option.startTime.toISOString(),
duration: option.duration,
})),
adminUrl: absoluteUrl(`/poll/${poll.id}`),
inviteUrl: shortUrl(`/invite/${poll.id}`),
},
};
}
app.use("*", wideEvent({ service: "api-private" }));
app.use("*", async (c, next) => {
if (isMaintenanceModeEnabled()) {
return c.json(
apiError("SERVICE_UNAVAILABLE", "The app is down for maintenance"),
503,
{ "Retry-After": "300" },
);
}
await next();
});
const spaceNotProResponse = {
description:
"The space associated with the API key does not have a Pro subscription",
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
};
const retryAfterHeader = {
"Retry-After": {
description: "Seconds to wait before retrying the request.",
schema: { type: "integer" as const },
},
};
const rateLimitExceededResponse = {
description:
"Rate limit exceeded. Includes a `Retry-After` header indicating how many seconds to wait before retrying.",
headers: retryAfterHeader,
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
};
const serviceUnavailableResponse = {
description:
"The API is temporarily unavailable, for maintenance or because the rate limit store cannot be reached. Includes a `Retry-After` header. Maintenance responses are sent before the rate limiter runs and carry no `RateLimit-*` headers.",
headers: retryAfterHeader,
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
};
async function buildOpenApiSpec() {
const spec = await generateSpecs(app, {
documentation: {
info: {
title: "Rallly Private API",
version: "0.0.1",
description: [
"## Rate limits",
"",
`All endpoints share two limits per space: **${RATE_LIMIT_PER_MINUTE} requests per minute** and **${RATE_LIMIT_PER_DAY} requests per day**. Both are fixed windows that open with the first request and reset when they expire. Both limits are per space, not per API key, so creating additional keys does not increase throughput.`,
"",
"Every response from an authenticated request includes the standard `RateLimit-*` headers. Responses sent before the limiter runs (`401`, `403`, and the maintenance `503`) do not. `RateLimit-Policy` lists both limits; `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` describe whichever limit is closest to being exhausted. When either limit is exceeded the API responds with `429 Too Many Requests`, a `RATE_LIMIT_EXCEEDED` error body, and a `Retry-After` header indicating how many seconds to wait before retrying.",
"",
"If the rate limit store cannot be reached the API fails closed and responds with `503 Service Unavailable`, a `SERVICE_UNAVAILABLE` error body, and a `Retry-After` header.",
].join("\n"),
},
components: {
securitySchemes: {
bearerAuth: {
type: "http",
scheme: "bearer",
},
},
},
},
});
// hono-openapi's validator middleware owns the request body schema and
// overwrites any content set via describeRoute, so named examples have to
// be attached to the generated spec instead.
const createPollRequestBody =
spec.paths["/api/private/polls"]?.post?.requestBody;
if (createPollRequestBody && "content" in createPollRequestBody) {
const media = createPollRequestBody.content?.["application/json"];
if (media) {
media.examples = createPollRequestExamples;
}
}
const patchPollRequestBody =
spec.paths["/api/private/polls/{pollId}"]?.patch?.requestBody;
if (patchPollRequestBody && "content" in patchPollRequestBody) {
const media = patchPollRequestBody.content?.["application/json"];
if (media) {
media.examples = patchPollRequestExamples;
}
}
return spec;
}
let openApiSpec: Awaited<ReturnType<typeof buildOpenApiSpec>> | undefined;
app.get("/openapi", async (c) => {
openApiSpec ??= await buildOpenApiSpec();
return c.json(openApiSpec);
});
app.get(
"/docs",
Scalar({
url: "/api/private/openapi",
pageTitle: "Rallly Private API Documentation",
theme: "purple",
}),
);
app.post(
"/polls",
spaceApiKeyAuth,
rateLimit,
describeRoute({
tags: ["Polls"],
summary: "Create a poll",
description: [
"Creates a new poll. Provide the poll options in one of two ways:",
"",
"- `dates` — a list of calendar dates. Each date becomes an all-day option (date poll).",
"- `slots` — time-based options that share a fixed `duration` in minutes. Each entry in `slots.times` is either an ISO datetime for an explicit slot, or a slot generator that expands into recurring slots within a time window across a date range. Generated slots start every `interval` minutes (defaults to `duration`) and must fit entirely between `startTime` and `endTime`.",
"",
"`dates` and `slots` are mutually exclusive, and a poll can have at most 100 options. See the request examples for common scenarios.",
].join("\n"),
security: [{ bearerAuth: [] }],
responses: {
200: {
description: "Successful response",
content: {
"application/json": {
schema: resolver(createPollSuccessResponseSchema),
},
},
},
400: {
description: "Invalid input or no valid options generated",
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
},
403: spaceNotProResponse,
429: rateLimitExceededResponse,
503: serviceUnavailableResponse,
},
}),
validator("json", createPollInputSchema),
async (c) => {
const input = c.req.valid("json");
const { spaceId, spaceOwnerId } = c.get("apiAuth");
// Determine the organizer userId
let organizerUserId = spaceOwnerId;
if (input.organizer) {
const spaceMember = await prisma.spaceMember.findFirst({
where: {
spaceId,
user: {
email: input.organizer.email,
},
},
include: {
user: {
select: { id: true, email: true },
},
},
});
if (!spaceMember) {
return c.json(
apiError(
"ORGANIZER_NOT_MEMBER",
"The specified organizer is not a member of this space.",
),
400,
);
}
organizerUserId = spaceMember.user.id;
}
// Same gate as the app. The strike goes to the key holder, who is the
// paying account, whichever member the poll is organized by.
const moderation = await moderateContent({
userId: spaceOwnerId,
content: {
Title: input.title,
Description: input.description ?? "",
Location: input.location ?? "",
},
});
if (moderation.verdict === "flagged") {
return c.json(
apiError(
"INAPPROPRIATE_CONTENT",
"This content was flagged by moderation and cannot be published.",
),
400,
);
}
const trackPollCreated = (poll: Awaited<ReturnType<typeof createPoll>>) => {
const kind = poll.options.some((o) => o.duration > 0) ? "time" : "date";
identifyGroup({
groupType: "poll",
groupKey: poll.id,
properties: {
name: poll.title,
status: poll.status,
kind,
created_at: poll.createdAt,
comment_count: 0,
option_count: poll.options.length,
has_location: !!poll.location,
has_description: !!poll.description,
timezone: poll.timeZone,
muted: false,
},
});
track(
{ id: organizerUserId, isGuest: false },
{
event: "poll_create",
properties: {
title: poll.title,
kind,
source: "api",
apiVersion: "private",
optionCount: poll.options.length,
hasLocation: !!poll.location,
hasDescription: !!poll.description,
timezone: poll.timeZone,
requireParticipantEmail: input.requireEmail,
hideParticipants: input.hideParticipants,
hideScores: input.hideScores,
disableComments: poll.disableComments,
allowTentativeVotes: poll.allowTentativeVotes,
isGuest: false,
},
groups: {
poll: poll.id,
space: spaceId,
},
},
);
after(() => flushPostHog());
};
// Process dates (all-day options)
if (input.dates) {
if (input.dates.length > MAX_POLL_OPTIONS) {
return c.json(
apiError(
"TOO_MANY_OPTIONS",
`Too many options (${input.dates.length}). Maximum allowed is ${MAX_POLL_OPTIONS}.`,
),
400,
);
}
const uniqueDates = [...new Set(input.dates)];
if (uniqueDates.length < input.dates.length) {
const duplicateCount = input.dates.length - uniqueDates.length;
return c.json(
apiError(
"DUPLICATE_DATES",
`Duplicate dates found. Please remove ${duplicateCount} duplicate date${duplicateCount > 1 ? "s" : ""}.`,
),
400,
);
}
const options = uniqueDates.map((date) => ({
startTime: new Date(`${date}T00:00:00.000Z`),
duration: 0,
}));
const poll = await createPoll({
userId: organizerUserId,
title: input.title,
description: input.description,
location: input.location,
requireParticipantEmail: input.requireEmail,
hideParticipants: input.hideParticipants,
hideScores: input.hideScores,
disableComments: input.disableComments,
allowTentativeVotes: input.allowTentativeVotes,
options,
spaceId,
});
trackPollCreated(poll);
return c.json(
createPollSuccessResponseSchema.parse(toPollResponseBody(poll)),
);
}
// Process slots (time-based options)
if (!input.slots) {
return c.json(
apiError("INVALID_INPUT", "Either 'dates' or 'slots' must be provided"),
400,
);
}
const slots = input.slots;
const timeZone = slots.timezone;
const duration = slots.duration;
const times = Array.isArray(slots.times) ? slots.times : [slots.times];
const timeSlots = times.flatMap((time) => {
if (typeof time === "string") {
return parseStartTime(time, timeZone, duration);
}
const slotGenerator: SlotGeneratorInput = {
startDate: time.startDate,
endDate: time.endDate,
daysOfWeek: time.days,
fromTime: time.startTime,
toTime: time.endTime,
interval: time.interval,
};
return generateTimeSlots(slotGenerator, timeZone, duration);
});
const options = dedupeTimeSlots(timeSlots);
if (!options.length) {
return c.json(
apiError(
"NO_OPTIONS_GENERATED",
"No valid options were generated. Check that your slot generators produce valid time slots.",
),
400,
);
}
if (options.length > MAX_POLL_OPTIONS) {
return c.json(
apiError(
"TOO_MANY_OPTIONS",
`Too many options generated (${options.length}). Maximum allowed is ${MAX_POLL_OPTIONS}.`,
),
400,
);
}
const poll = await createPoll({
userId: organizerUserId,
title: input.title,
description: input.description,
location: input.location,
timeZone,
requireParticipantEmail: input.requireEmail,
hideParticipants: input.hideParticipants,
hideScores: input.hideScores,
disableComments: input.disableComments,
allowTentativeVotes: input.allowTentativeVotes,
options,
spaceId,
});
trackPollCreated(poll);
return c.json(
createPollSuccessResponseSchema.parse(toPollResponseBody(poll)),
);
},
);
app.get(
"/polls",
spaceApiKeyAuth,
rateLimit,
describeRoute({
tags: ["Polls"],
summary: "List polls",
description: [
"Lists the polls in the space associated with the API key, sorted by creation date (newest first).",
"",
"Use the `status` query parameter to only return polls in a given state — for example `status=open` to sweep polls that are still collecting responses. Results are paginated with a cursor: pass the `nextCursor` value from the previous response to fetch the next page.",
].join("\n"),
security: [{ bearerAuth: [] }],
responses: {
200: {
description: "Successful response",
content: {
"application/json": {
schema: resolver(listPollsSuccessResponseSchema),
},
},
},
400: {
description: "Invalid query parameters",
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
},
403: spaceNotProResponse,
429: rateLimitExceededResponse,
503: serviceUnavailableResponse,
},
}),
validator("query", listPollsQuerySchema),
async (c) => {
const { status, cursor, limit } = c.req.valid("query");
const { spaceId } = c.get("apiAuth");
const { polls, nextCursor } = await listPolls({
spaceId,
status,
cursor,
limit,
});
return c.json(
listPollsSuccessResponseSchema.parse({
data: polls.map((poll) => ({
...toPollResponseBody(poll).data,
participantCount: poll.participantCount,
})),
nextCursor,
}),
);
},
);
app.get(
"/polls/:pollId",
spaceApiKeyAuth,
rateLimit,
describeRoute({
tags: ["Polls"],
summary: "Get a poll",
description:
"Retrieves poll metadata by ID. The poll must belong to the space associated with the API key.",
security: [{ bearerAuth: [] }],
responses: {
200: {
description: "Successful response",
content: {
"application/json": {
schema: resolver(getPollSuccessResponseSchema),
},
},
},
403: spaceNotProResponse,
429: rateLimitExceededResponse,
503: serviceUnavailableResponse,
404: {
description: "Poll not found",
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
},
},
}),
async (c) => {
const { pollId } = c.req.param();
const { spaceId } = c.get("apiAuth");
const poll = await prisma.poll.findFirst({
where: {
id: pollId,
spaceId,
deleted: false,
},
select: {
id: true,
title: true,
description: true,
location: true,
timeZone: true,
status: true,
createdAt: true,
user: {
select: {
name: true,
image: true,
},
},
options: {
select: {
id: true,
startTime: true,
duration: true,
},
orderBy: {
startTime: "asc",
},
},
},
});
if (!poll) {
return c.json(
apiError(
"POLL_NOT_FOUND",
"Poll not found or does not belong to this space.",
),
404,
);
}
return c.json(getPollSuccessResponseSchema.parse(toPollResponseBody(poll)));
},
);
app.patch(
"/polls/:pollId",
spaceApiKeyAuth,
rateLimit,
describeRoute({
tags: ["Polls"],
summary: "Update a poll",
description: [
'Updates a poll\'s status. Currently the only supported transition is closing a poll by sending `{ "status": "closed" }`.',
"",
"Close a poll once you have picked a date or the poll is no longer needed. Closing is non-destructive — the poll and its responses are preserved — but the results become final and participants can no longer vote. Consumers polling `GET /polls/:pollId/results` should remove closed polls from their queues.",
"",
"Closing is idempotent: closing an already-closed poll returns a `200` with the poll unchanged. The other statuses (`open`, `scheduled`, `canceled`) are not available via the API and return `422`.",
].join("\n"),
security: [{ bearerAuth: [] }],
responses: {
200: {
description: "Poll updated successfully",
content: {
"application/json": {
schema: resolver(patchPollSuccessResponseSchema),
},
},
},
403: spaceNotProResponse,
429: rateLimitExceededResponse,
503: serviceUnavailableResponse,
404: {
description: "Poll not found",
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
},
422: {
description: "The requested status transition is not available",
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
},
},
}),
validator("json", patchPollInputSchema),
async (c) => {
const { pollId } = c.req.param();
const { status } = c.req.valid("json");
const { spaceId } = c.get("apiAuth");
if (status !== "closed") {
return c.json(
apiError(
"TRANSITION_NOT_AVAILABLE",
`Transitioning a poll to "${status}" is not available via the API. Only "closed" is supported.`,
),
422,
);
}
const poll = await closePoll({ pollId, spaceId });
if (!poll) {
return c.json(
apiError(
"POLL_NOT_FOUND",
"Poll not found or does not belong to this space.",
),
404,
);
}
return c.json(
patchPollSuccessResponseSchema.parse(toPollResponseBody(poll)),
);
},
);
app.get(
"/polls/:pollId/results",
spaceApiKeyAuth,
rateLimit,
describeRoute({
tags: ["Polls"],
summary: "Get poll results",
description:
"Retrieves aggregated voting results for a poll. Returns vote counts per option without individual participant data.",
security: [{ bearerAuth: [] }],
responses: {
200: {
description: "Successful response",
content: {
"application/json": {
schema: resolver(getPollResultsSuccessResponseSchema),
},
},
},
403: spaceNotProResponse,
429: rateLimitExceededResponse,
503: serviceUnavailableResponse,
404: {
description: "Poll not found",
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
},
},
}),
async (c) => {
const { pollId } = c.req.param();
const { spaceId } = c.get("apiAuth");
const data = await getPollResults({ pollId, spaceId });
if (!data) {
return c.json(
apiError(
"POLL_NOT_FOUND",
"Poll not found or does not belong to this space.",
),
404,
);
}
return c.json(
getPollResultsSuccessResponseSchema.parse({
data: {
...data,
options: data.options.map((option) => ({
...option,
startTime: option.startTime.toISOString(),
// The frozen shape omits types that received no votes.
votes: option.votes.filter((vote) => vote.count > 0),
})),
},
}),
);
},
);
app.get(
"/polls/:pollId/participants",
spaceApiKeyAuth,
rateLimit,
describeRoute({
tags: ["Polls"],
summary: "Get poll participants",
description:
"Retrieves all participants and their votes for a poll. The poll must belong to the space associated with the API key.",
security: [{ bearerAuth: [] }],
responses: {
200: {
description: "Successful response",
content: {
"application/json": {
schema: resolver(getPollParticipantsSuccessResponseSchema),
},
},
},
403: spaceNotProResponse,
429: rateLimitExceededResponse,
503: serviceUnavailableResponse,
404: {
description: "Poll not found",
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
},
},
}),
async (c) => {
const { pollId } = c.req.param();
const { spaceId } = c.get("apiAuth");
const data = await getPollParticipants({ pollId, spaceId });
if (!data) {
return c.json(
apiError(
"POLL_NOT_FOUND",
"Poll not found or does not belong to this space.",
),
404,
);
}
return c.json(
getPollParticipantsSuccessResponseSchema.parse({
data: {
pollId: data.pollId,
participants: data.participants.map((participant) => ({
...participant,
createdAt: participant.createdAt.toISOString(),
})),
},
}),
);
},
);
app.delete(
"/polls/:pollId",
spaceApiKeyAuth,
rateLimit,
describeRoute({
tags: ["Polls"],
summary: "Delete a poll",
description:
"Deletes a poll by ID. The poll must belong to the space associated with the API key.",
security: [{ bearerAuth: [] }],
responses: {
200: {
description: "Poll deleted successfully",
content: {
"application/json": {
schema: resolver(deletePollSuccessResponseSchema),
},
},
},
403: spaceNotProResponse,
429: rateLimitExceededResponse,
503: serviceUnavailableResponse,
404: {
description: "Poll not found",
content: {
"application/json": {
schema: resolver(errorResponseSchema),
},
},
},
},
}),
async (c) => {
const { pollId } = c.req.param();
const { spaceId } = c.get("apiAuth");
const result = await deletePoll(pollId, spaceId);
if (!result) {
return c.json(
apiError(
"POLL_NOT_FOUND",
"Poll not found or does not belong to this space.",
),
404,
);
}
return c.json(
deletePollSuccessResponseSchema.parse({
data: {
id: result.id,
deleted: true,
},
}),
);
},
);
export { app };
export const GET = handle(app);
export const POST = handle(app);
export const PATCH = handle(app);
export const DELETE = handle(app);