@omelhorsite/sdk 0.3.0 → 0.4.0

package/dist/types/resources/content/intel/stats.d.ts

@@ -0,0 +1,105 @@
+/** Intel stats: the dashboard counters. */
+import { Resource } from "../../../http";
+import type { RequestOptions } from "../../../types";
+/** One category bucket of {@link IntelStats}. */
+export interface IntelCategoryCount {
+    readonly category: string;
+    /** Named `c`, not `count`. */
+    readonly c: number;
+}
+/** One day of the {@link IntelStats} histogram. */
+export interface IntelDayCount {
+    /** `YYYY-MM-DD`, from Postgres `DATE(last_seen_at)`. Not a full timestamp. */
+    readonly day: string;
+    readonly c: number;
+}
+/**
+ * The importance histogram, with the backend's own Portuguese bucket names.
+ *
+ * The boundaries are hard-coded server-side and are not
+ * configurable: `critico` >=9, `alta` 7-8, `media` 5-6, `baixa` 3-4, `ruido`
+ * <3. Note they are NOT the same thresholds as
+ * {@link IntelConfig.report_min_importance} or
+ * {@link IntelConfig.enrich_min_importance} - those are yours, these are the
+ * dashboard's.
+ */
+export interface IntelImportanceBuckets {
+    readonly critico: number;
+    readonly alta: number;
+    readonly media: number;
+    readonly baixa: number;
+    readonly ruido: number;
+}
+/** Row counts on the {@link IntelStats} answer. */
+export interface IntelStatsTotals {
+    /** Stories you own. */
+    readonly articles: number;
+    /**
+     * **Not the number of feeds you have configured.** This counts the
+     * story-to-item POINTER rows, so this is "how many citations exist across
+     * all my stories" and it grows without bound as
+     * stories accumulate. If you want the number of configured sources, read the
+     * length of {@link IntelSourcesNamespace.list}. The name is the backend's and
+     * the SDK does not rename it, but do not put it under a "Sources" label.
+     */
+    readonly sources: number;
+    readonly reports: number;
+    /** Raw items you own, processed or not. */
+    readonly items: number;
+    /**
+     * Items the analysis pipeline has not consumed yet (`processed_at IS NULL`).
+     *
+     * The one number worth watching: a figure that climbs and never falls means
+     * the pipeline is not running - most often because `Intel::LlmClient` is
+     * disabled for want of an API key, in which case `AnalysisDispatcherJob`
+     * returns immediately and silently.
+     */
+    readonly pending_items: number;
+}
+/**
+ * `GET /intel_stats` - counters for the intel dashboard.
+ *
+ * Not a record: it has no `id`, no timestamps and no `:extended` view.
+ */
+export interface IntelStats {
+    readonly totals: IntelStatsTotals;
+    /**
+     * Categories by story count, descending. Stories with a `null` category are
+     * EXCLUDED, so these do not sum to `totals.articles`.
+     */
+    readonly by_category: IntelCategoryCount[];
+    /**
+     * The last 30 days by `last_seen_at`, ascending.
+     *
+     * Sparse: a day with no activity is simply ABSENT, not present with zero.
+     * Fill the gaps before plotting or the line will lie about its own x-axis.
+     */
+    readonly by_day: IntelDayCount[];
+    readonly by_importance: IntelImportanceBuckets;
+    /** Stories touched in the last 24 hours. */
+    readonly last24h: number;
+}
+/** `/intel_stats` - the dashboard counters. One route, one verb. */
+export declare class IntelStatsNamespace extends Resource {
+    /**
+     * `GET /intel_stats` - every counter the intel dashboard shows, in one call.
+     *
+     * Also a Rails singular resource, so the path is `/intel_stats` with no id
+     * despite the plural spelling.
+     *
+     * **Cost, and the reason not to poll this.** The controller does
+     * `articles.pluck(:importance)` - it loads the importance of EVERY story you
+     * own into Ruby memory to build {@link IntelStats.by_importance} - and then
+     * runs five more aggregate queries beside it. There is no cache, no `ETag`
+     * (the hand-written action never calls `stale?`, unlike every list in this
+     * file) and therefore no `304`. Cost grows linearly with your story count for
+     * ever. Fetch it on a dashboard open, not on a timer.
+     *
+     * Read {@link IntelStatsTotals.sources} before you label it: it does not
+     * count your feeds.
+     *
+     * @throws {OmsApiError} 403 `"Intel access is restricted."` outside the
+     *   allowlist.
+     */
+    get(options?: RequestOptions): Promise<IntelStats>;
+}

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

@@ -0,0 +1,86 @@
+/** Vocabulary shared across the intel families. */
+/**
+ * ## Access: this is effectively a one-user feature
+ *
+ * Every intel route is gated by a fixed allowlist of one handle plus admins.
+ * So: anonymous is `401`, any other signed-in account is
+ * `403 "Intel access is restricted."`, and no amount of correct request
+ * shaping changes that. Do not build a shared feature on it, and do not
+ * treat a 403 here as a bug in the caller.
+ *
+ * An OAuth access token is `403 {"error":"insufficient_scope"}` on every
+ * route below. Session credential only.
+ *
+ * ## Ids are STRINGS here
+ *
+ * Articles, reports, sources, scripts, items and the config row all carry
+ * opaque string ids, unlike blogs, notifications, jokes and Space Invaders
+ * games, whose ids are integers. Nothing in intel is ever a number you can
+ * compare or sort by.
+ *
+ * ## Ceilings
+ *
+ * None of their own. Every route rides the general bucket: 600 requests per
+ * minute for an authenticated caller. Two of them are still expensive and are
+ * documented as such - {@link IntelStatsNamespace.get} and
+ * {@link IntelSourcesNamespace.run}.
+ */
+/** Categories a story can carry. `null` when the classifier declined to pick one. */
+export declare const INTEL_ARTICLE_CATEGORIES: readonly ["incidente", "politica", "comunidade", "sociedade", "internacional", "economia", "outro"];
+/**
+ * A story's category.
+ *
+ * Widened with `string & {}` deliberately: the list is a Ruby constant that a
+ * migration can extend without the SDK noticing, and a `switch` that fails to
+ * compile on a new category is worse than one that falls through to a default.
+ * The backend DOES validate inclusion, so a value outside the list can only
+ * mean the constant moved.
+ */
+export type IntelArticleCategory = (typeof INTEL_ARTICLE_CATEGORIES)[number] | (string & {});
+/** Report windows a report can cover. */
+export declare const INTEL_REPORT_KINDS: readonly ["6h", "day", "week", "month"];
+/** Which window a report covers. */
+export type IntelReportKind = (typeof INTEL_REPORT_KINDS)[number] | (string & {});
+/**
+ * Base of the third-party image proxy {@link intelArticleImageUrl} builds on.
+ *
+ * `wsrv.nl` is a free public image CDN. It is NOT this API and NOT our
+ * infrastructure.
+ */
+export declare const INTEL_IMAGE_PROXY_BASE_URL = "https://wsrv.nl/";
+/** Knobs for {@link intelArticleImageUrl}. */
+export interface IntelImageOptions {
+    /** Target width in pixels. Default 480. Height follows the aspect ratio. */
+    readonly width?: number;
+    /** Quality, 1-100. Default 45 - low on purpose; these are thumbnails. */
+    readonly quality?: number;
+}
+/**
+ * Builds a resized, re-compressed URL for {@link IntelArticle.image_url}.
+ *
+ * Pure string building, no request, isolate-safe. Returns `""` for a story with
+ * no image so it can be dropped straight into an `<img src>` without a
+ * conditional - though a real client should test the field and render nothing.
+ *
+ * ## What this actually does, and why you might not want it
+ *
+ * `image_url` is the raw `og:image` of a news site: full size, arbitrary
+ * format, arbitrary weight, and served from that site's own host. Nothing in
+ * this API resizes it. This helper routes it through `wsrv.nl`, a free public
+ * image CDN, which fetches the origin image and hands back a width-limited
+ * WebP.
+ *
+ * The trade is explicit and it is not the SDK's to make silently:
+ *
+ * - the ORIGIN URL is sent to a third party in a query string, so wsrv.nl
+ *   learns which article your user is looking at, and so does anyone reading
+ *   the request. There is no credential involved - the images are public - but
+ *   it is still a referrer-shaped leak;
+ * - availability is theirs, not ours. A wsrv.nl outage is a page of broken
+ *   images, and there is no fallback in the URL;
+ * - `&we` asks it not to enlarge images smaller than `width`.
+ *
+ * If neither trade suits you, use {@link IntelArticle.image_url} directly and
+ * size it in CSS.
+ */
+export declare function intelArticleImageUrl(imageUrl: string | null | undefined, options?: IntelImageOptions): string;

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

@@ -0,0 +1,93 @@
+/** The joke table behind the loading screens. */
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { Paginated, RequestOptions, Timestamp } from "../../types";
+/** `GET /jokes` filters on {@link BASE_FILTER_COLUMNS} only. */
+export declare const JOKE_FILTER_COLUMNS: readonly [];
+/** Filters for {@link JokesNamespace.list}. */
+export type ListJokesParams = ListParams<(typeof JOKE_FILTER_COLUMNS)[number]>;
+/** Primary key of a joke. An INTEGER. */
+export type JokeId = number;
+/**
+ * A joke.
+ *
+ * Unlike the blog records this one really does carry all three base fields.
+ */
+export interface Joke {
+    readonly id: JokeId;
+    /**
+     * Language tag, as whoever typed it wrote it. Free text with a presence
+     * validation and NOTHING else - no inclusion list, no normalisation - so the
+     * table can and does hold `"pt"` next to `"PT"` next to `"pt-PT"`. Compare
+     * case-insensitively, and see {@link JokesNamespace.list} for why you cannot
+     * make the server do the filtering.
+     */
+    readonly lang: string;
+    /**
+     * The joke. A `varchar` with no database limit and no model validation; the
+     * web composer caps input at 255 characters as a house rule, which nothing
+     * server-side enforces.
+     */
+    readonly content: string;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+}
+/** Arguments for {@link JokesNamespace.create}. Both fields are required by the model. */
+export interface JokeInput {
+    readonly lang: string;
+    readonly content: string;
+}
+/**
+ * The `jokes` namespace: the joke table behind the site's loading screens.
+ *
+ * Reading is fully public; writing is admin-only. `Joke.viewable_by` is `all`,
+ * so every joke is visible to every caller including anonymous ones, and
+ * `creatable_by?`/`updatable_by?`/`destroyable_by?` all reduce to
+ * `user.admin?`.
+ */
+export declare class JokesNamespace extends Resource {
+    /**
+     * `GET /jokes` - the joke table, paged. Anonymous callers welcome.
+     *
+     * **You cannot filter by language.** The allowlist is only the three
+     * defaults - `id`, `created_at`, `updated_at` - and `lang` is not on it.
+     * `search: { lang: "pt" }`
+     * is `400 "Unknown search filter: lang"`, not a wider result: the DSL fails
+     * closed. Pull a page and filter client-side, which is what every caller
+     * ends up doing.
+     *
+     * For "give me a joke", `random: true` with `pageSize: 1` is the whole
+     * recipe: the server applies `ORDER BY RANDOM()` and the pagination is
+     * applied after it. Note that a random listing carries no `ETag` and can
+     * never answer `304`, which is exactly what you want here and exactly what
+     * you do not want on a normal page.
+     *
+     * `modifiers[order]` also accepts a third segment for an explicit value
+     * ordering (`"lang:asc:pt,en"` puts those languages first), which the rest
+     * of the SDK does not advertise because almost nothing needs it.
+     */
+    list(params?: ListJokesParams, options?: RequestOptions): Promise<Paginated<Joke>>;
+    /**
+     * `POST /jokes` - adds a joke. `201`. **Admin only.**
+     *
+     * A signed-in non-admin gets `401 "You are not authorized to create this
+     * resource"`; an anonymous caller gets `401 "Session required to access
+     * this resource."` from the authentication filter first.
+     */
+    create(input: JokeInput, options?: RequestOptions): Promise<Joke>;
+    /**
+     * `PATCH /jokes/:id` - edits a joke. **Admin only.**
+     *
+     * Both fields are permitted and both are optional; the model requires each
+     * to be present, so sending `content: ""` is `400`, not a clear.
+     */
+    update(id: JokeId, input: Partial<JokeInput>, options?: RequestOptions): Promise<Joke>;
+    /**
+     * `DELETE /jokes/:id` - removes a joke. `204`. **Admin only.**
+     *
+     * There is no `GET /jokes/:id`: the resource is declared
+     * `only: [:create, :index, :update, :destroy]`, so a single fetch by id is a
+     * routing 404.
+     */
+    destroy(id: JokeId, options?: RequestOptions): Promise<void>;
+}

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

@@ -0,0 +1,147 @@
+/** The per-user notification inbox. */
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { Id, Paginated, RequestOptions, Timestamp } from "../../types";
+/** Filter columns of `GET /notifications`, on top of {@link BASE_FILTER_COLUMNS}. `read` and `kind` are not filterable. */
+export declare const NOTIFICATION_FILTER_COLUMNS: readonly ["user_id"];
+/** Filters for {@link NotificationsNamespace.list}. */
+export type ListNotificationsParams = ListParams<(typeof NOTIFICATION_FILTER_COLUMNS)[number]>;
+/** Primary key of a notification. An INTEGER. */
+export type NotificationId = number;
+/**
+ * The `kind` strings the backend emits today.
+ *
+ * NOT a closed set and not validated anywhere - `Notification` only requires
+ * `kind` to be present, so a new feature can add one without a migration. The
+ * union is here so the kinds you handle autocomplete; keep a default branch
+ * for the ones you do not, and never let an unknown kind break the inbox.
+ *
+ * Each kind implies a different {@link Notification.context} shape, which is
+ * why `context` is typed as an open record rather than a discriminated union:
+ * the backend guarantees a JSON object and nothing about its keys.
+ */
+export type NotificationKind = "friendship_request" | "friendship_accepted" | "user_followed" | "message_received" | "fs_grant_received" | "jam_invite" | "vocal_separation_done" | "vocal_separation_failed" | (string & {});
+/**
+ * One notification in a user's inbox.
+ *
+ * Unlike most of this file it IS a full record, so it carries `id`,
+ * `created_at` and `updated_at`. The `:extended` view adds
+ * nothing, so a notification arriving over the cable and one arriving over
+ * HTTP have the same fields.
+ */
+export interface Notification {
+    /** An integer, and a JSON number, not a string. */
+    readonly id: NotificationId;
+    /** What happened. See {@link NotificationKind}. */
+    readonly kind: NotificationKind;
+    /**
+     * Free-form JSON payload, whose keys depend entirely on `kind` - these are
+     * the i18n interpolation values the client renders the sentence with.
+     *
+     * Never `null` (the column is `NOT NULL DEFAULT '{}'`), and never large: the
+     * emitter runs user-supplied text through a 120-character preview before
+     * storing it, so a message-received notification carries a truncated
+     * snippet, not the message.
+     *
+     * One shape is documented outside the code and worth having here:
+     * `jam_invite` carries `{ jam_id, host_id, host_handle, inviter_id,
+     * inviter_handle }`. The rest you learn by reading a row.
+     */
+    readonly context: Record<string, unknown>;
+    /** Whether it has been marked read. See {@link NotificationsNamespace.markAllRead}. */
+    readonly read: boolean;
+    /** Owner. Always the caller: the scope is `user.notifications`. A STRING. */
+    readonly user_id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+}
+/**
+ * The `notifications` namespace: the per-user inbox.
+ *
+ * ## This covers the HTTP half only
+ *
+ * Notifications are pushed in real time over ActionCable, on the per-user
+ * `NotificationsChannel` stream, and that is where a live inbox gets its
+ * updates from: the channel transmits `{type: "unread_count", unread_count}`
+ * on subscribe, `{type: "created", notification, unread_count}` when one
+ * arrives, and `{type: "unread_count", unread_count}` again whenever the read
+ * state or the row count changes. The SDK does not open that socket and does
+ * not wrap it - it has no cable client - so these methods are the polling
+ * fallback and the write path, not the way to keep a badge live. A host with a
+ * socket should subscribe and use {@link unreadCount} only for the first
+ * paint.
+ *
+ * ## You cannot mark ONE notification read
+ *
+ * `PATCH /notifications/:id` is routed, and it cannot succeed for anybody: it
+ * answers `401 "You are not authorized to update this resource"` on every
+ * call - for the owner, for an admin, for everyone. The SDK therefore exposes
+ * no `markRead(id)`: there is nothing honest to put behind it. Mark the whole
+ * inbox with {@link markAllRead}, or remove the row with {@link dismiss}.
+ *
+ * There is also no `GET /notifications/:id`: the resource is declared
+ * `only: [:index, :update, :destroy]`, so a single fetch by id is a routing
+ * 404. Read one out of {@link list}.
+ *
+ * Everything here needs a session and rides the general 600/min ceiling.
+ */
+export declare class NotificationsNamespace extends Resource {
+    /**
+     * `GET /notifications` - the caller's inbox, one page at a time.
+     *
+     * Scoped to the caller by `viewable_by` (`user.notifications`), so there is
+     * no way to read anybody else's and the `user_id` filter below is redundant.
+     *
+     * **The filterable columns are almost none.** The controller declares
+     * `search_params :user_id`, which the DSL merges with the three defaults, so
+     * the complete allowlist is `id`, `created_at`, `updated_at` and `user_id`.
+     * `read` and `kind` are NOT on it, and filters fail closed: asking for
+     * `exact_search: { read: false }` - the obvious way to fetch the unread ones -
+     * is `400 "Unknown exact_search filter: read"`, not an unfiltered list.
+     * Fetch a page and filter client-side, or read {@link unreadCount} for the
+     * badge.
+     *
+     * No default ordering is declared, so rows come back in whatever order
+     * Postgres chooses. Pass `order: "created_at:desc"` for an inbox; there is
+     * an index on `(user_id, created_at)` behind it.
+     *
+     * Sends an `ETag`, so an unchanged page answers `304` and costs nothing -
+     * except with `random: true`, which disables the check.
+     */
+    list(params?: ListNotificationsParams, options?: RequestOptions): Promise<Paginated<Notification>>;
+    /**
+     * `GET /notifications/unread_count` - how many unread notifications the
+     * caller has. Unwraps the `{"count": n}` the server sends.
+     *
+     * One indexed `COUNT` behind a partial index (`WHERE read = false`), so it is
+     * cheap - but it is still a request per call, and the cable already pushes
+     * this number on subscribe and on every change. Poll it only where there is
+     * no socket.
+     */
+    unreadCount(options?: RequestOptions): Promise<number>;
+    /**
+     * `POST /notifications/read_all` - marks every unread notification read.
+     *
+     * Returns how many rows changed, which is the unread count from an instant
+     * ago; calling it twice returns `0` the second time. `200`, not `201` - it
+     * creates nothing.
+     *
+     * Runs as a single `update_all`, so no model callback fires and the per-row
+     * broadcast is skipped; the controller pushes the new count over the cable
+     * by hand afterwards, which is why every device still updates.
+     *
+     * Idempotent, so a retry is harmless. It is not enabled by default (the
+     * transport does not replay a `POST`); pass `retry: {}` if you want one.
+     */
+    markAllRead(options?: RequestOptions): Promise<number>;
+    /**
+     * `DELETE /notifications/:id` - removes one notification. `204`, no body.
+     *
+     * This is the closest thing to "mark as read" the API has: the row is gone,
+     * so the unread count drops and the new count is pushed over the cable.
+     *
+     * Owner only - `viewable_by` scopes the lookup to the caller, so somebody
+     * else's id is `404 "Resource not found"` rather than a 401.
+     */
+    dismiss(id: NotificationId, options?: RequestOptions): Promise<void>;
+}

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

@@ -0,0 +1,73 @@
+/** Per-user service visit counters. */
+import { Resource } from "../../http";
+import type { RequestOptions } from "../../types";
+/**
+ * The twelve service ids the counter accepts. A closed set: anything else is
+ * `400 "Unknown service_id"`.
+ */
+export declare const SERVICE_USAGE_IDS: readonly ["storage", "tools", "games", "music", "movies", "ai", "account", "tickets", "messages", "blogs", "status", "administration"];
+/** One of {@link SERVICE_USAGE_IDS}. */
+export type ServiceUsageId = (typeof SERVICE_USAGE_IDS)[number];
+/**
+ * A per-user visit counter.
+ *
+ * Note what is NOT here: no `id`, no `user_id`, no timestamps. Both routes
+ * answer a bare `{ service_id, count }`, so this is one of the very few
+ * payloads in the API that is not a record.
+ */
+export interface ServiceUsage {
+    readonly service_id: ServiceUsageId;
+    /** Lifetime visit count for this user and service. Monotonic, never reset. */
+    readonly count: number;
+}
+/**
+ * The `service_usages` namespace: which parts of the site a user opens, so the
+ * home screen can put their favourites first.
+ *
+ * Both routes need a session - there is no `allow_unauthenticated_access` on
+ * this controller - and both are pure bookkeeping. The music app calls
+ * {@link record} with `"music"` on launch, fire and forget.
+ */
+export declare class ServiceUsagesNamespace extends Resource {
+    /**
+     * `POST /service_usages` - increments the caller's counter for one service.
+     *
+     * Answers **`200`, not `201`**, even on the very first call that creates the
+     * row: the controller uses `ok!` rather than `created!`, so this is one of
+     * the handful of creates in the API that breaks the 201 convention. The body
+     * is the updated `{ service_id, count }`.
+     *
+     * ## Not idempotent, and it can page somebody
+     *
+     * Every call does `count += 1` and stamps `last_visited_at`, so a retry
+     * inflates the number. That is why the transport's default of never
+     * replaying a `POST` is the right default here: do not pass `retry: {}`.
+     *
+     * It can also fire a Discord `service_opened` alert - on the first ever
+     * visit, and again whenever more than an hour has passed since the last one.
+     * A client that calls this on every route change inside an app is fine (the
+     * hour gap suppresses the alert), but a client that calls it from a
+     * background poller is a pager, not telemetry.
+     *
+     * Fire and forget: nothing in a UI should wait on this, and nothing should
+     * fail because it failed.
+     *
+     * @throws {OmsApiError} 400 `"Unknown service_id"` for anything outside
+     *   {@link SERVICE_USAGE_IDS}; 401 without a session.
+     */
+    record(serviceId: ServiceUsageId, options?: RequestOptions): Promise<ServiceUsage>;
+    /**
+     * `GET /service_usages/top` - the caller's most-used services, busiest
+     * first, tie-broken by most recently visited.
+     *
+     * Not the list DSL: `limit` is the only parameter, it is clamped to
+     * `1..10` (silently - asking for 50 returns 10), and it defaults to 3. There
+     * is no paging and no way to read the full set.
+     *
+     * Only services the caller has actually opened appear, so a fresh account
+     * gets an empty array rather than every id with a zero.
+     */
+    top(input?: {
+        readonly limit?: number;
+    }, options?: RequestOptions): Promise<ServiceUsage[]>;
+}