@omelhorsite/sdk 0.2.0 → 0.4.0

package/dist/types/resources/content/servicesStatus.d.ts

@@ -0,0 +1,194 @@
+/** The public status page: live probes and the uptime report. */
+import { Resource } from "../../http";
+import type { RequestOptions, Timestamp } from "../../types";
+/** The three services `GET /services_status` actually probes. */
+export declare const EXTERNAL_SERVICE_SLUGS: readonly ["vocal_separator", "ai", "yt_dlp"];
+/**
+ * The eight services that live inside the Rails process and are therefore
+ * "up" whenever the healthcheck job runs at all. They appear in
+ * {@link ServicesStatusNamespace.uptime} and NOT in
+ * {@link ServicesStatusNamespace.current}.
+ */
+export declare const INTERNAL_SERVICE_SLUGS: readonly ["accounts", "notifications", "storage", "socials", "short_links", "ip_lookup", "jokes", "space_invaders"];
+/** Every slug the uptime report covers. */
+export declare const ALL_SERVICE_SLUGS: readonly ["accounts", "notifications", "storage", "socials", "short_links", "ip_lookup", "jokes", "space_invaders", "vocal_separator", "ai", "yt_dlp"];
+/** A service slug. Open, because the registry is a constant somebody will extend. */
+export type ServiceSlug = (typeof ALL_SERVICE_SLUGS)[number] | (string & {});
+/** Live health of one external service. */
+export interface ServiceHealth {
+    /** `true` when the probe got a 2xx from the service's `/health`. */
+    readonly ok: boolean;
+    /**
+     * A STRING, and not the HTTP status you might expect from the name.
+     *
+     * It is `"OK"` when the probe succeeded, and otherwise the failure's
+     * identity: either a Ruby exception class (`"Errno::ECONNREFUSED"`,
+     * `"Net::OpenTimeout"`, `"SocketError"`), or `"HTTP<code>"` for a
+     * non-success response (`"HTTP503"`), or `"MissingURL"` when the service has
+     * no URL configured. Show it, do not parse it - the set is whatever Ruby
+     * happens to raise.
+     */
+    readonly status: string;
+}
+/**
+ * The live status map: one entry per external slug, and nothing else.
+ *
+ * Keyed by {@link EXTERNAL_SERVICE_SLUGS} only - the internal services do not
+ * appear, because there is nothing to ping.
+ */
+export type ServicesStatusMap = Record<string, ServiceHealth>;
+/** One day of a service's history in the uptime report. */
+export interface UptimeDay {
+    /** `YYYY-MM-DD`, in the SERVER's timezone - the bucket is `DATE(created_at)`. */
+    readonly date: string;
+    /**
+     * - `"up"` - every ping that day succeeded;
+     * - `"degraded"` - some succeeded and some did not;
+     * - `"down"` - every ping failed;
+     * - `"unknown"` - no pings at all that day (the future half of today, days
+     *   before the service existed, and any window where the healthcheck job was
+     *   not running).
+     */
+    readonly status: "up" | "degraded" | "down" | "unknown";
+    /** Successful pings that day. Roughly 1440 on a fully healthy day. */
+    readonly up: number;
+    /** Failed pings that day. */
+    readonly down: number;
+}
+/** One service's 90-day history. */
+export interface UptimeService {
+    readonly slug: ServiceSlug;
+    /**
+     * Exactly 90 entries, oldest first, with no gaps: a day with no data is
+     * present with `status: "unknown"` and zero counts rather than missing.
+     * Index 89 is today, and today is partial.
+     */
+    readonly days: UptimeDay[];
+    /**
+     * Successful pings over total pings across the whole window, as a
+     * percentage rounded to two decimals. `null` when the service has no pings
+     * at all in the window - a brand new slug, or a long outage of the
+     * healthcheck job itself. Do not render `null` as `0%`.
+     */
+    readonly uptime_pct: number | null;
+}
+/** A note appended to an incident as it progressed. */
+export interface IncidentUpdate {
+    /**
+     * Free text. Auto-opened incidents post `"investigating"` and `"resolved"`;
+     * a hand-written one can say anything.
+     */
+    readonly status: string;
+    readonly body: string | null;
+    readonly created_at: Timestamp;
+}
+/** A public incident on the status page. */
+export interface Incident {
+    /** An INTEGER. */
+    readonly id: number;
+    /** Auto-opened incidents are titled `"<slug> indisponível"`, in Portuguese. */
+    readonly title: string;
+    readonly body: string | null;
+    /** Auto-opened ones are always `"major"`. */
+    readonly severity: "minor" | "major" | "critical";
+    readonly started_at: Timestamp;
+    /** `null` while the incident is open. */
+    readonly resolved_at: Timestamp | null;
+    /** Affected slugs. Can be empty, and can name a slug not in the registry. */
+    readonly services: ServiceSlug[];
+    /** Oldest first. */
+    readonly updates: IncidentUpdate[];
+}
+/** The whole uptime report. */
+export interface UptimeReport {
+    /** First day of the window, `YYYY-MM-DD`. 89 days before `to`. */
+    readonly from: string;
+    /** Today, `YYYY-MM-DD`. */
+    readonly to: string;
+    /** One entry per slug in {@link ALL_SERVICE_SLUGS}, in registry order. */
+    readonly services: UptimeService[];
+    /** The 20 most recent PUBLIC incidents, newest first. Private ones are omitted. */
+    readonly incidents: Incident[];
+}
+/** Seconds of server-side caching on {@link ServicesStatusNamespace.uptime}. */
+export declare const UPTIME_CACHE_SECONDS = 60;
+/** Days of history the uptime report covers. */
+export declare const UPTIME_WINDOW_DAYS = 90;
+/**
+ * The `services_status` namespace: the public status page.
+ *
+ * Both routes are anonymous (`allow_unauthenticated_access` with no `only:`),
+ * and both are exempt from the visitor-logging after-action because the status
+ * widget polls from every page load and would otherwise drown the activity
+ * feed.
+ *
+ * ## The two calls have opposite cost profiles, and the names mislead
+ *
+ * {@link current} sounds cheap and is the expensive one; {@link uptime} sounds
+ * heavy and is served from a cache. Read both method docs before you put
+ * either behind a poller.
+ */
+export declare class ServicesStatusNamespace extends Resource {
+    /**
+     * `GET /services_status` - live health of the three external services.
+     *
+     * **This is the expensive endpoint in this namespace.** It performs the
+     * probes inline, on the request thread, one after another - the controller
+     * uses `index_with` with `Object#then`, so there is no concurrency - each
+     * with a 2 second connect timeout and a 5 second read timeout. A healthy
+     * call is a few tens of milliseconds; a call while all three are unreachable
+     * holds a Puma thread for up to about 21 seconds and returns
+     * `ok: false` three times.
+     *
+     * There is NO cache and NO dedicated rate limit, so it sits on the general
+     * anonymous budget of 120 requests per minute per IP. Poll it at most once
+     * every 30 seconds or so, and give it a client-side `timeoutMs` well above
+     * the SDK default if your default is short - a slow answer here is the
+     * normal answer during an outage, not a hung request.
+     *
+     * Only {@link EXTERNAL_SERVICE_SLUGS} appear in the map. The internal slugs
+     * are absent because they have nothing to probe; read them out of
+     * {@link uptime} instead.
+     */
+    current(options?: RequestOptions): Promise<ServicesStatusMap>;
+    /**
+     * `GET /services_status/uptime` - 90 days of per-day history for all eleven
+     * services, plus the 20 most recent public incidents.
+     *
+     * ## Cost and freshness, honestly
+     *
+     * This endpoint was flooded (roughly 900 requests a minute from a load
+     * generator) and the fix was not a throttle: it was one grouped query plus a
+     * cache. It still has no rack-attack bucket of its own.
+     *
+     * - **Freshness: up to 60 seconds stale.** The whole payload is memoised
+     *   under the single global cache key `"services_status/uptime"` for
+     *   {@link UPTIME_CACHE_SECONDS} seconds. The key is not per-caller and not
+     *   per-parameter (there are no parameters), so every visitor on the site
+     *   shares one entry. Polling faster than once a minute cannot produce a
+     *   newer number - it just spends your rate budget re-fetching bytes you
+     *   already have.
+     * - **Cost on a hit: sending the payload.** Eleven services times ninety
+     *   days is 990 day objects plus the incidents, so this is a
+     *   double-digit-kilobyte response every time. There is no `ETag` and no
+     *   `Last-Modified`, so it cannot answer `304` even when nothing changed.
+     * - **Cost on a miss: one grouped aggregate** over
+     *   `service_pings` - `GROUP BY slug, DATE(created_at), status` across the
+     *   window - which is on the order of a million rows, since the healthcheck
+     *   job writes one ping per slug per minute. Indexed on
+     *   `(slug, created_at)`, but it is still the single heaviest query on the
+     *   public surface, and exactly one request per minute pays it.
+     *
+     * ## Reading the numbers
+     *
+     * `up` and `down` are ping counts, not durations: a fully healthy day is
+     * about 1440 up and 0 down. The window is 90 days and ping retention is also
+     * 90 days, so the OLDEST day in every report is partially pruned and its
+     * counts read low - do not compute an SLA off day zero.
+     *
+     * The eight internal slugs are `"up"` for every minute the Rails process was
+     * running the healthcheck job, because that is literally what they measure.
+     * They report the job's liveness, not the feature's.
+     */
+    uptime(options?: RequestOptions): Promise<UptimeReport>;
+}

package/dist/types/resources/content/siteConfig.d.ts

@@ -0,0 +1,43 @@
+/** The public configuration blob. */
+import { Resource } from "../../http";
+import type { RequestOptions } from "../../types";
+/**
+ * The public configuration blob. One key today; treat it as open, since this
+ * is where any future "the browser needs to know this before signing in"
+ * value will land.
+ */
+export interface SiteConfig {
+    /**
+     * Cloudflare Turnstile site key, for rendering the widget.
+     *
+     * `null` when the credential is not configured - in development, and in any
+     * environment where the key was never set. A `null` here does NOT mean the
+     * captcha is disabled server-side: `require_captcha_if_anonymous!` still
+     * runs and still rejects an anonymous {@link FeedbacksNamespace.create}, so
+     * a client that skips the widget because this was null will see a 400 it
+     * cannot explain. Treat `null` as "anonymous submission is unavailable".
+     */
+    readonly turnstile_site_key: string | null;
+}
+/**
+ * The `config` namespace: one anonymous GET that bootstraps the client.
+ *
+ * Deliberately tiny and deliberately public - it is the only thing a client
+ * can read before it has any credential at all, and the only reason it exists
+ * is that the Turnstile widget needs a site key before the anonymous feedback
+ * form can be submitted.
+ */
+export declare class SiteConfigNamespace extends Resource {
+    /**
+     * `GET /config` - the public configuration blob.
+     *
+     * Anonymous, no side effects, reads no database. It is not cached
+     * server-side and has no `ETag`, so it is a full round trip every time -
+     * fetch it once at boot and hold it, do not call it per form.
+     *
+     * Counts against the general ceiling like everything else (120/min per IP
+     * anonymous), and - the trap this file repeats - answers `403` if you attach
+     * an OAuth access token to it, because no route here accepts one.
+     */
+    get(options?: RequestOptions): Promise<SiteConfig>;
+}

package/dist/types/resources/content/spaceInvaders.d.ts

@@ -0,0 +1,154 @@
+/** The Space Invaders leaderboard. */
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { Id, Paginated, RequestOptions, Timestamp } from "../../types";
+/** `GET /space_invaders_games` filters on {@link BASE_FILTER_COLUMNS} only; there is no player filter. */
+export declare const SPACE_INVADERS_GAME_FILTER_COLUMNS: readonly [];
+/** Filters for {@link SpaceInvadersNamespace.list}. */
+export type ListSpaceInvadersGamesParams = ListParams<(typeof SPACE_INVADERS_GAME_FILTER_COLUMNS)[number]>;
+/** Primary key of a leaderboard entry. An INTEGER. */
+export type SpaceInvadersGameId = number;
+/** Points a single kill can be worth. Mirrors `MAX_POINTS_PER_KILL`. */
+export declare const SPACE_INVADERS_MAX_POINTS_PER_KILL = 10;
+/** Kills per second the validator will believe. Mirrors `MAX_KILLS_PER_SECOND`. */
+export declare const SPACE_INVADERS_MAX_KILLS_PER_SECOND = 1;
+/** Longest session the validator accepts, in seconds. 24 hours. */
+export declare const SPACE_INVADERS_MAX_SESSION_SECONDS: number;
+/** Rows the leaderboard returns. Mirrors the `leaderboard` scope's `limit`. */
+export declare const SPACE_INVADERS_LEADERBOARD_SIZE = 100;
+/**
+ * One finished game.
+ *
+ * ## `money` and `time` are STRINGS
+ *
+ * They are `decimal` columns with no precision or scale, and Rails encodes
+ * `BigDecimal` as a JSON string on purpose - a JSON number would be parsed as
+ * a float by most clients and silently lose precision. So the wire carries
+ * `"1200.0"`, not `1200`. `kills` is an `integer` column right next to them
+ * and arrives as a real number.
+ *
+ * Anything that sorts, sums or compares these must `Number()` them first;
+ * `"9.0" > "10.0"` is `true` in JavaScript.
+ */
+export interface SpaceInvadersGame {
+    readonly id: SpaceInvadersGameId;
+    /** The player. A STRING id. */
+    readonly user_id: Id;
+    /** Score. A decimal serialised as a STRING - see the interface docs. */
+    readonly money: string;
+    /** Session length in seconds. Also a decimal serialised as a STRING. */
+    readonly time: string;
+    /** Enemies killed. An integer, and a real JSON number. */
+    readonly kills: number;
+    /**
+     * When the game ended. Stamped SERVER-side from `Time.current` in a
+     * `before_create`, and deliberately not accepted from the request body, so a
+     * client cannot back-date or future-date an entry. Sending it is ignored.
+     */
+    readonly played_at: Timestamp;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+}
+/**
+ * Arguments for {@link SpaceInvadersNamespace.submit}.
+ *
+ * All three are required and all three are validated against each other. The
+ * bounds mirror `frontend/public/spaceinvaders/config.json` and are documented
+ * in the model as what they are: not anti-cheat, just a rejection of scores
+ * that are impossible under the game's own rules. The score is
+ * client-authoritative, so anybody willing to call this endpoint by hand can
+ * post any score inside the bounds.
+ */
+export interface SubmitSpaceInvadersGameInput {
+    /**
+     * Score. Must be `>= 0` and no greater than
+     * `kills * {@link SPACE_INVADERS_MAX_POINTS_PER_KILL}`, or the call is
+     * `400 "Money is impossibly high for N kills"`.
+     */
+    readonly money: number;
+    /**
+     * Session length in seconds. Must be `>= 0` and
+     * `<= {@link SPACE_INVADERS_MAX_SESSION_SECONDS}`.
+     */
+    readonly time: number;
+    /**
+     * Enemies killed. Must be a non-negative integer and no greater than
+     * `ceil(time * {@link SPACE_INVADERS_MAX_KILLS_PER_SECOND})`, or the call is
+     * `400 "Kills are impossibly high for a Ns game"`.
+     */
+    readonly kills: number;
+}
+/**
+ * The `space_invaders_games` namespace: the leaderboard for the embedded game.
+ *
+ * The only genuinely public thing here is {@link leaderboard}. Submitting
+ * needs a session, and so - oddly - does {@link list}.
+ */
+export declare class SpaceInvadersNamespace extends Resource {
+    /**
+     * `GET /space_invaders_games/leaderboard` - the top
+     * {@link SPACE_INVADERS_LEADERBOARD_SIZE} scores, highest `money` first.
+     *
+     * Anonymous callers welcome. Not the list DSL: no paging, no filters, no
+     * ordering - `order(money: :desc).limit(100)` is the whole query, and it is
+     * backed by a descending index on `money`.
+     *
+     * One row per GAME, not per player: a player who posts three good runs
+     * occupies three slots. Deduplicate client-side if you want a per-player
+     * board.
+     *
+     * The rows carry `user_id` and nothing else about the player - no handle, no
+     * avatar - so a board with names needs a separate lookup.
+     */
+    leaderboard(options?: RequestOptions): Promise<SpaceInvadersGame[]>;
+    /**
+     * `GET /space_invaders_games` - every game ever recorded, paged.
+     *
+     * `viewable_by` is `all`, so any signed-in caller enumerates the whole
+     * table, everybody's runs included. It needs a session even though
+     * {@link leaderboard} does not, which is the wrong way round if you were
+     * expecting the listing to be the public one.
+     *
+     * **You cannot filter by player.** The controller declares only
+     * `create_params`, so the search allowlist is the three defaults - `id`,
+     * `created_at`, `updated_at`. `exact_search: { user_id: "..." }` is
+     * `400 "Unknown exact_search filter: user_id"`. To show one player's
+     * history, page and filter client-side, or use `order: "money:desc"` and
+     * stop early.
+     *
+     * No default ordering, so pass one. Sends an `ETag`.
+     */
+    list(params?: ListSpaceInvadersGamesParams, options?: RequestOptions): Promise<Paginated<SpaceInvadersGame>>;
+    /**
+     * `POST /space_invaders_games` - records a finished run. `201`.
+     *
+     * The player is taken from the session and `played_at` is stamped
+     * server-side; neither can be supplied. Any signed-in user may submit.
+     *
+     * Every submission is a new row, so a retry after a lost response posts the
+     * run twice and both appear on the leaderboard. The transport does not
+     * replay a `POST` by default, and this is an endpoint where you should not
+     * ask it to.
+     *
+     * There is no per-user rate limit beyond the general 600/min, and no
+     * de-duplication: two identical runs are two rows.
+     *
+     * @throws {OmsApiError} 400 with the validation sentence when the score
+     *   fails the plausibility bounds - see {@link SubmitSpaceInvadersGameInput};
+     *   401 without a session.
+     */
+    submit(input: SubmitSpaceInvadersGameInput, options?: RequestOptions): Promise<SpaceInvadersGame>;
+    /**
+     * `DELETE /space_invaders_games/:id` - removes an entry. `204`.
+     *
+     * The player who set it, or an admin. Anybody else gets
+     * `401 "You are not authorized to destroy this resource"` - and note it is a
+     * 401 rather than a 404, because `viewable_by` is `all` and the lookup
+     * succeeds before the authorisation check.
+     *
+     * There is no update route: the resource is declared
+     * `only: [:create, :index, :destroy]`, so a score can be deleted but never
+     * edited.
+     */
+    destroy(id: SpaceInvadersGameId, options?: RequestOptions): Promise<void>;
+}