@omelhorsite/sdk 0.13.0 → 0.16.0

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

@@ -1,108 +0,0 @@
-/** Intel reports: generated digests over closed time windows. */
-import { Resource } from "../../../http";
-import type { ListParams } from "../../../listing";
-import type { Id, Json, Paginated, RequestOptions, Timestamp } from "../../../types";
-import type { IntelArticleCategory, IntelReportKind } from "./types";
-/** A story as a report inlines it. Four keys, no summary and no body. */
-export interface IntelReportArticleRef {
-    readonly id: Id;
-    readonly title: string | null;
-    readonly importance: number;
-    readonly category: IntelArticleCategory | null;
-}
-/**
- * A generated report over one closed time window.
- *
- * The index shape. `GET /intel_reports/:id` adds three keys - see
- * {@link IntelReportDetail}.
- *
- * There is at most ONE report per `(user, kind, period_end)`: the migration
- * puts a unique index on that triple precisely so a re-run of
- * `GenerateReportJob` cannot mint a duplicate. Windows are the last CLOSED
- * period, computed by `IntelReport.last_window`, so a `"day"` report covers
- * yesterday and never the day in progress.
- */
-export interface IntelReport {
-    readonly id: Id;
-    readonly created_at: Timestamp;
-    readonly updated_at: Timestamp;
-    /** Which window: see {@link INTEL_REPORT_KINDS}. */
-    readonly kind: IntelReportKind;
-    /** Title the model wrote. Nullable. */
-    readonly title: string | null;
-    /** Start of the window, inclusive. */
-    readonly period_start: Timestamp;
-    /** End of the window, exclusive. Also the sort key of the listing. */
-    readonly period_end: Timestamp;
-    /** LLM that wrote it, as configured at generation time. Nullable. */
-    readonly model: string | null;
-}
-/** `GET /intel_reports/:id` - the `:extended` view. */
-export interface IntelReportDetail extends IntelReport {
-    /** The report body, usually Markdown. `null` if generation failed halfway. */
-    readonly content: string | null;
-    /**
-     * Whatever the generator chose to record about the run. A free-form JSON
-     * object with no schema on either side, defaulting to `{}` - which is why it
-     * is typed as a bag rather than as fields. Read it defensively.
-     */
-    readonly stats: Record<string, Json> | null;
-    /** The stories the report covered, most important first. */
-    readonly articles: IntelReportArticleRef[];
-}
-/** Filter columns of `GET /intel_reports`, on top of {@link BASE_FILTER_COLUMNS}. */
-export declare const INTEL_REPORT_FILTER_COLUMNS: readonly ["kind"];
-/** Filters for {@link IntelReportsNamespace.list}. */
-export interface ListIntelReportsParams extends ListParams<(typeof INTEL_REPORT_FILTER_COLUMNS)[number]> {
-    /**
-     * Narrow to one window, e.g. `"day"`. Sent as `exact_search[kind]`, so it is
-     * equality rather than a prefix match - `"6h"` will not also match `"6hx"`.
-     *
-     * Passing it through {@link ListParams.search} instead would be a
-     * partial match and would work too; `kind` is on this controller's
-     * `search_params` allowlist. Equality is what you want.
-     */
-    readonly kind?: IntelReportKind;
-}
-/**
- * `GET /intel_reports` - the generated digests.
- *
- * Read-only plus a delete, for the same reason as the stories: reports come
- * from `Intel::GenerateReportJob`. There is no way to ask for one to be
- * generated over HTTP.
- */
-export declare class IntelReportsNamespace extends Resource {
-    /**
-     * `GET /intel_reports` - your reports, newest window first.
-     *
-     * `period_end DESC` is applied by the controller; as with the stories, a
-     * `order` of your own becomes the PRIMARY key and this becomes the
-     * tie-breaker.
-     *
-     * `kind` is the only declared filter beyond the inherited three. Use
-     * {@link ListIntelReportsParams.kind}, which sends it as an exact match.
-     *
-     * @throws {OmsApiError} 403 `"Intel access is restricted."` outside the
-     *   allowlist.
-     */
-    list(params?: ListIntelReportsParams, options?: RequestOptions): Promise<Paginated<IntelReport>>;
-    /**
-     * `GET /intel_reports/:id` - the report with its body and its stories.
-     *
-     * @throws {OmsApiError} 404 when the report is not yours.
-     */
-    get(id: Id, options?: RequestOptions): Promise<IntelReportDetail>;
-    /**
-     * `DELETE /intel_reports/:id`. `204`, empty body.
-     *
-     * The stories it cited are untouched - only the join rows go.
-     *
-     * A deleted report can come back: `GenerateReportJob` is keyed by the unique
-     * `(user, kind, period_end)` index, and deleting the row frees that key, so
-     * the next dispatcher pass over the same window will regenerate it. Delete a
-     * report to re-run it, not to suppress it.
-     *
-     * @throws {OmsApiError} 404 when the report is not yours.
-     */
-    delete(id: Id, options?: RequestOptions): Promise<void>;
-}

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

@@ -1,105 +0,0 @@
-/** 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

@@ -1,86 +0,0 @@
-/** 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;