Skip to content

Your favorite shift management application!

4.4 KB
Raw Blame
/**
 * Shared contract of the paginated admin list endpoints (`/api/admin/users`,
 * `/api/admin/calendars`) and the hooks that call them. Pure module: safe to
 * import from route handlers and client code alike.
 */

export const ADMIN_PAGE_SIZE = 25;
export const ADMIN_MAX_PAGE_SIZE = 100;

export const SORT_ORDERS = ["asc", "desc"] as const;
export type SortOrder = (typeof SORT_ORDERS)[number];

export interface AdminListResponse<T, C> {
  items: T[];
  /** Rows matching the current search and filters */
  total: number;
  /** Instance-wide totals, independent of search and filters */
  counts: C;
  /** The page actually served; out-of-range requests get the last page */
  page: number;
  limit: number;
}

// Users

export const USER_ROLE_FILTERS = ["all", "superadmin", "admin", "user"] as const;
export const USER_STATUS_FILTERS = ["all", "active", "banned"] as const;
export const USER_SORT_FIELDS = [
  "name",
  "email",
  "role",
  "status",
  "createdAt",
  "lastActivity",
  "calendarCount",
] as const;

export type UserRoleFilter = (typeof USER_ROLE_FILTERS)[number];
export type UserStatusFilter = (typeof USER_STATUS_FILTERS)[number];
export type UserSortField = (typeof USER_SORT_FIELDS)[number];

export interface UserListParams {
  search: string;
  role: UserRoleFilter;
  status: UserStatusFilter;
  sort: UserSortField;
  order: SortOrder;
  page: number;
  limit: number;
}

export interface UserListCounts {
  total: number;
  superadmin: number;
  admin: number;
  user: number;
  banned: number;
  active: number;
}

// Calendars

export const CALENDAR_CONTENT_FILTERS = ["all", "shared", "synced"] as const;
export const CALENDAR_OWNER_FILTERS = ["all", "orphaned", "with-owner"] as const;
export const CALENDAR_SORT_FIELDS = [
  "name",
  "createdAt",
  "owner",
  "shiftsCount",
  "sharesCount",
  "externalSyncsCount",
  "guestBundle",
] as const;

export type CalendarContentFilter = (typeof CALENDAR_CONTENT_FILTERS)[number];
export type CalendarOwnerFilter = (typeof CALENDAR_OWNER_FILTERS)[number];
export type CalendarSortField = (typeof CALENDAR_SORT_FIELDS)[number];

export interface CalendarListParams {
  search: string;
  content: CalendarContentFilter;
  owner: CalendarOwnerFilter;
  sort: CalendarSortField;
  order: SortOrder;
  page: number;
  limit: number;
}

export interface CalendarListCounts {
  total: number;
  orphaned: number;
  shared: number;
  synced: number;
  shifts: number;
}

// Helpers

export function pickParam<T extends string>(
  value: string | null,
  allowed: readonly T[],
  fallback: T
): T {
  return value !== null && (allowed as readonly string[]).includes(value) ? (value as T) : fallback;
}

function positiveInt(value: string | null, fallback: number): number {
  const parsed = Number.parseInt(value ?? "", 10);
  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
}

/** Requested page (1-based) and page size, with the size capped. */
export function parsePaging(searchParams: URLSearchParams) {
  return {
    page: positiveInt(searchParams.get("page"), 1),
    limit: Math.min(positiveInt(searchParams.get("limit"), ADMIN_PAGE_SIZE), ADMIN_MAX_PAGE_SIZE),
  };
}

/** Clamps the page to the last one that has rows, so a shrinking list never shows an empty page. */
export function clampPage(page: number, limit: number, total: number) {
  const lastPage = Math.max(1, Math.ceil(total / limit));
  const served = Math.min(page, lastPage);
  return { page: served, offset: (served - 1) * limit };
}

/** Lower-cased `LIKE` pattern with `%`, `_` and `\` escaped; pair it with `ESCAPE '\'`. */
export function containsPattern(search: string): string {
  return `%${search.toLowerCase().replace(/[\\%_]/g, (char) => `\\${char}`)}%`;
}

/**
 * Filter defaults are sent explicitly rather than omitted: the endpoints accept
 * "all" as a value, and skipping it here would also swallow a free-text search
 * for the literal "all".
 */
export function toSearchParams(params: object): URLSearchParams {
  const searchParams = new URLSearchParams();
  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined && value !== "") {
      searchParams.set(key, String(value));
    }
  }
  return searchParams;
}

/** Failed admin request; hooks translate `status` into a message when they show it. */
export class AdminRequestError extends Error {
  constructor(public readonly status: number) {
    super(`Admin request failed with status ${status}`);
    this.name = "AdminRequestError";
  }
}