first commit

Co-authored-by: Cursor <cursoragent@cursor.com>

shared/src/types.ts

@@ -0,0 +1,109 @@
+/** Shapes returned by the API. The web app builds against these. */
+
+export type MintStatus = 'online' | 'degraded' | 'offline' | 'unknown';
+
+/** One item of `GET /api/mints`. */
+export interface MintListItem {
+  url: string;
+  host: string;
+  name: string | null;
+  icon: string | null;
+  status: MintStatus;
+  last_online: number | null;
+  review_count: number;
+  rating_avg: number | null;
+  score: number;
+  last_review_at: number | null;
+  version: string | null;
+}
+
+export interface ProbeSample {
+  ts: number;
+  ok: 0 | 1;
+  latency_ms: number | null;
+}
+
+export type RatingDistribution = Record<'1' | '2' | '3' | '4' | '5', number>;
+
+/** `GET /api/mints/:host`. */
+export interface MintDetail extends MintListItem {
+  description: string | null;
+  pubkey: string | null;
+  info: MintInfo | null;
+  nuts: string[];
+  first_seen: number;
+  last_probe: number | null;
+  updated_at: number;
+  rating_distribution: RatingDistribution;
+  /** Reviews in the last 90 days, for the verdict strip's activity cell. */
+  reviews_90d: number;
+  uptime_30d: number | null;
+  probes_recent: ProbeSample[];
+}
+
+/** `GET /api/stats`. */
+export interface Stats {
+  mints_total: number;
+  mints_online: number;
+  mints_offline: number;
+  mints_degraded: number;
+  reviews_total: number;
+  last_review_at: number | null;
+  updated_at: number;
+}
+
+/** `GET /api/health`. */
+export interface Health {
+  status: 'ok' | 'degraded';
+  uptime_s: number;
+  last_probe_at: number | null;
+  last_discovery_at: number | null;
+  mints_tracked: number;
+  updated_at: number;
+}
+
+/**
+ * A mint's `/v1/info` response (NUT-06). Every field is optional: mints in the wild
+ * omit most of it, and the site must render whatever is there.
+ */
+export interface MintInfo {
+  name?: string;
+  pubkey?: string;
+  version?: string;
+  description?: string;
+  description_long?: string;
+  contact?: MintContact[];
+  motd?: string;
+  icon_url?: string;
+  urls?: string[];
+  time?: number;
+  tos_url?: string;
+  nuts?: Record<string, unknown>;
+}
+
+export interface MintContact {
+  method?: string;
+  info?: string;
+}
+
+/** A review as rendered in the browser, parsed from a Nostr event. */
+export interface Review {
+  id: string;
+  pubkey: string;
+  created_at: number;
+  mint_url: string;
+  /** null when the event carries no parseable rating. Never defaulted to 5. */
+  rating: number | null;
+  content: string;
+}
+
+/** Resolved kind-0 metadata for a reviewer. */
+export interface Profile {
+  pubkey: string;
+  name?: string;
+  display_name?: string;
+  picture?: string;
+  nip05?: string;
+  /** false when the kind-0 lookup returned nothing, used for the provenance note. */
+  found: boolean;
+}