@omelhorsite/sdk 0.15.1 → 0.17.0

package/dist/types/resources/cron.d.ts

@@ -0,0 +1,225 @@
+/**
+ * The `cron` namespace: TypeScript scripts of the signed-in person that the
+ * server runs on a schedule.
+ *
+ * A script is an ES module exporting `run(ctx)`. It runs with nothing but the
+ * API: no filesystem, no environment, no processes, and no network beyond
+ * this SDK (`ctx.oms`, authenticated as the owner with the job's scopes) and,
+ * when the job has `network` on, a `ctx.fetch` that goes through the server's
+ * guard against private addresses. What it keeps in `ctx.state` is stored
+ * when a run ends well and handed back on the next one; what it returns is
+ * the run's `result`, and `result.summary` is what the listing shows.
+ *
+ * Needs the `cron:read` scope to read and `cron:write` to change anything.
+ * A job's own token never carries either: a script cannot edit jobs.
+ */
+import { Resource, type ApiClient } from "../http";
+import type { ListParams } from "../listing";
+import type { Id, Json, Paginated, RequestOptions, Timestamp } from "../types";
+/** Scopes a job may ask for its token. Anything else answers `400`. */
+export declare const CRON_JOB_SCOPES: readonly ["profile", "news:read", "news:write", "storage:read", "storage:write", "llm", "tools:read", "tools:write", "blogs:read", "blogs:write"];
+export type CronJobScope = (typeof CRON_JOB_SCOPES)[number];
+export declare const CRON_JOB_HEALTHS: readonly ["unknown", "ok", "error"];
+export type CronJobHealth = (typeof CRON_JOB_HEALTHS)[number];
+/** Consecutive failures after which a job switches itself off. Turn `enabled` back on to revive it. */
+export declare const CRON_JOB_DISABLE_AFTER_FAILURES = 10;
+/** Code longer than this answers `400`. */
+export declare const CRON_JOB_MAX_CODE_BYTES: number;
+/** `state` and `config` ceilings. A run whose state grows past this fails and the state is not stored. */
+export declare const CRON_JOB_MAX_STATE_BYTES: number;
+export declare const CRON_JOB_MAX_CONFIG_BYTES: number;
+/** Two runs of one job must be at least this far apart. */
+export declare const CRON_JOB_MIN_INTERVAL_MINUTES = 5;
+/** `timeout_seconds` range; above 120 the account needs a trusted tier, like `network`. */
+export declare const CRON_JOB_MIN_TIMEOUT_SECONDS = 5;
+export declare const CRON_JOB_MAX_TIMEOUT_SECONDS = 1200;
+export declare const CRON_JOB_BASE_MAX_TIMEOUT_SECONDS = 120;
+export interface CronJob {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Up to 120 characters, unique per account. */
+    readonly name: string;
+    readonly description: string | null;
+    /** Five-field cron expression, read in `timezone`. */
+    readonly schedule: string;
+    /** An IANA zone such as `"Europe/Lisbon"` (the default). */
+    readonly timezone: string;
+    /** The scopes the run's token carries. */
+    readonly scopes: CronJobScope[];
+    /** Names of the stored secrets. The values never leave the server. */
+    readonly secret_keys: string[];
+    /** Whether `ctx.fetch` exists in the script. */
+    readonly network: boolean;
+    readonly timeout_seconds: number;
+    /** A folder of the owner's storage handed to the script as `ctx.job.outputDirId`. */
+    readonly output_dir_id: Id | null;
+    readonly enabled: boolean;
+    readonly next_run_at: Timestamp | null;
+    readonly last_run_at: Timestamp | null;
+    readonly last_success_at: Timestamp | null;
+    readonly health: CronJobHealth;
+    readonly consecutive_failures: number;
+    readonly notify_on_failure: boolean;
+    readonly notify_on_success: boolean;
+    /** The template the job was created from, if any. */
+    readonly template_slug: string | null;
+    /** Whether a run is queued or running right now. */
+    readonly running: boolean;
+}
+/** The types a script may give a variable it declares with `// @var key type Label | description`. */
+export declare const CRON_VAR_TYPES: readonly ["string", "text", "number", "boolean", "list", "json"];
+export type CronVarType = (typeof CRON_VAR_TYPES)[number];
+/**
+ * A variable a script declares as editable, parsed by the server from the
+ * `// @var` lines at the top of the code. Its value lives in `config[key]`.
+ */
+export interface CronVar {
+    readonly key: string;
+    readonly type: CronVarType;
+    readonly label: string;
+    readonly description: string | null;
+}
+/** `GET /cron_jobs/:id` (and every write) adds the code, the config, the state and the declared variables. */
+export interface CronJobDetail extends CronJob {
+    readonly code: string;
+    readonly config: Record<string, Json>;
+    readonly state: Record<string, Json>;
+    readonly vars: CronVar[];
+}
+export declare const CRON_JOB_FILTER_COLUMNS: readonly ["name", "enabled", "health", "template_slug"];
+export interface ListCronJobsParams extends ListParams<(typeof CRON_JOB_FILTER_COLUMNS)[number]> {
+}
+export interface CreateCronJobInput {
+    readonly name: string;
+    readonly description?: string | null;
+    /** Five fields. Two runs must be at least {@link CRON_JOB_MIN_INTERVAL_MINUTES} apart. */
+    readonly schedule: string;
+    readonly timezone?: string;
+    /** TypeScript. Checked for syntax on the server before it is stored. */
+    readonly code: string;
+    /** Defaults to every scope but `news:write` and `tools:write`. */
+    readonly scopes?: readonly CronJobScope[];
+    readonly config?: Record<string, Json>;
+    /** Stored encrypted; on update the object is MERGED, and a `null` value removes that key. */
+    readonly secrets?: Record<string, string | null>;
+    readonly state?: Record<string, Json>;
+    readonly network?: boolean;
+    readonly timeoutSeconds?: number;
+    readonly outputDirId?: Id | null;
+    readonly enabled?: boolean;
+    readonly notifyOnFailure?: boolean;
+    readonly notifyOnSuccess?: boolean;
+    readonly templateSlug?: string | null;
+}
+export type UpdateCronJobInput = Partial<Omit<CreateCronJobInput, "templateSlug">>;
+export declare const CRON_RUN_STATUSES: readonly ["queued", "running", "ok", "error", "timeout", "skipped"];
+export type CronRunStatus = (typeof CRON_RUN_STATUSES)[number];
+export declare const CRON_RUN_TRIGGERS: readonly ["schedule", "manual", "test"];
+export type CronRunTrigger = (typeof CRON_RUN_TRIGGERS)[number];
+export interface CronRun {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly cron_job_id: Id;
+    readonly status: CronRunStatus;
+    /** `test` runs never write the state back and never count as failures. */
+    readonly trigger: CronRunTrigger;
+    readonly scheduled_at: Timestamp;
+    readonly started_at: Timestamp | null;
+    readonly finished_at: Timestamp | null;
+    readonly duration_ms: number | null;
+    readonly error: string | null;
+    readonly error_name: string | null;
+    /** Model calls made with the run's token, and what they cost. */
+    readonly llm_requests: number;
+    readonly llm_cost: number;
+    /** Requests the script made, through the SDK and `ctx.fetch`. */
+    readonly http_calls: number;
+    /** `result.summary`, when the script returned one. */
+    readonly summary: string | null;
+}
+/** `GET /cron_runs/:id` adds the logs and the whole result. */
+export interface CronRunDetail extends CronRun {
+    /** What `ctx.log` and `console.log` wrote, one line per entry, capped at 64 KB. */
+    readonly logs: string | null;
+    readonly result: Json | null;
+}
+export declare const CRON_RUN_FILTER_COLUMNS: readonly ["cron_job_id", "status", "trigger"];
+export interface ListCronRunsParams extends ListParams<(typeof CRON_RUN_FILTER_COLUMNS)[number]> {
+    readonly jobId?: Id;
+    readonly status?: CronRunStatus;
+}
+/** A ready-made script: copy it into a job with {@link CronJobsNamespace.create}. */
+export interface CronTemplate {
+    readonly slug: string;
+    readonly name: string;
+    readonly description: string;
+    /** The schedule the template expects. */
+    readonly schedule: string;
+    readonly scopes: CronJobScope[];
+    readonly network: boolean;
+    /** The config the script reads, with defaults. */
+    readonly config: Record<string, Json>;
+    /** The variables the template declares as editable (`// @var`). */
+    readonly vars: CronVar[];
+    /** SHA-256 of the code, so a client can tell an edited copy from a pristine one. */
+    readonly hash: string;
+}
+export interface CronTemplateDetail extends CronTemplate {
+    readonly code: string;
+}
+/** What the syntax check answers. */
+export interface CronCheckResult {
+    readonly ok: boolean;
+    readonly error?: string;
+}
+export declare class CronJobsNamespace extends Resource {
+    list(params?: ListCronJobsParams, options?: RequestOptions): Promise<Paginated<CronJob>>;
+    get(id: Id, options?: RequestOptions): Promise<CronJobDetail>;
+    /**
+     * `POST /cron_jobs`. `201` with the full job.
+     *
+     * @throws {OmsApiError} 400 with the validation sentence: a bad or too
+     *   frequent schedule, an unknown timezone, a scope outside
+     *   {@link CRON_JOB_SCOPES}, `network` or a timeout above 120 s on an
+     *   account without a trusted tier, an `Invalid script: ...` syntax error,
+     *   or `job limit reached (N)` (the `cron_jobs` quota).
+     */
+    create(input: CreateCronJobInput, options?: RequestOptions): Promise<CronJobDetail>;
+    /** `PATCH /cron_jobs/:id`. Secrets merge; a `null` value removes a key. Changing the schedule recomputes `next_run_at`. */
+    update(id: Id, input: UpdateCronJobInput, options?: RequestOptions): Promise<CronJobDetail>;
+    /** `DELETE /cron_jobs/:id` - the job and its runs. `204`. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * `POST /cron_jobs/:id/run` - runs now, outside the schedule, as a normal
+     * run (the state is stored). `202` with the queued run.
+     *
+     * @throws {OmsApiError} 400 `this job is already running`; 429
+     *   `error: "limit"` when the day's `cron_run_seconds` are spent.
+     */
+    run(id: Id, options?: RequestOptions): Promise<CronRun>;
+    /** `POST /cron_jobs/:id/test` - runs now WITHOUT storing the state or counting a failure. `202`. */
+    test(id: Id, options?: RequestOptions): Promise<CronRun>;
+    /** `POST /cron_jobs/check` - the syntax check the server runs before storing code, on its own. */
+    check(code: string, options?: RequestOptions): Promise<CronCheckResult>;
+}
+export declare class CronRunsNamespace extends Resource {
+    /** `GET /cron_runs` - newest first. */
+    list(params?: ListCronRunsParams, options?: RequestOptions): Promise<Paginated<CronRun>>;
+    get(id: Id, options?: RequestOptions): Promise<CronRunDetail>;
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+export declare class CronTemplatesNamespace extends Resource {
+    /** `GET /cron_templates` - the built-in scripts, without their code. */
+    list(options?: RequestOptions): Promise<CronTemplate[]>;
+    /** `GET /cron_templates/:slug` - one template with its code. */
+    get(slug: string, options?: RequestOptions): Promise<CronTemplateDetail>;
+}
+/** The `cron` namespace, reachable as `oms.cron`. */
+export declare class CronNamespace extends Resource {
+    readonly jobs: CronJobsNamespace;
+    readonly runs: CronRunsNamespace;
+    readonly templates: CronTemplatesNamespace;
+    constructor(http: ApiClient);
+}

package/dist/types/resources/index.d.ts

@@ -22,6 +22,7 @@ export * from "./admin";
 export * from "./auth/index";
 export * from "./chests";
 export * from "./content";
+export * from "./cron";
 export * from "./dynamicQrs";
 export * from "./forms";
 export * from "./ipLookup";

package/dist/types/resources/llm.d.ts

@@ -41,6 +41,8 @@ export interface LlmModelChoice {
     readonly name: string;
     readonly provider_slug: string;
     readonly free: boolean;
+    /** `0` everyone, `1` trusted accounts, `2` administrators. Only models at or below the account's tier are listed. */
+    readonly tier: number;
     readonly context_window: number | null;
     readonly max_output_tokens: number | null;
     readonly input_price_per_million: number | null;
@@ -285,12 +287,81 @@ export declare class LlmChatsNamespace extends Resource {
     /** Removes the chat and every message in it. */
     delete(id: Id, options?: RequestOptions): Promise<void>;
 }
+/** The tools a completion may hand the model. Each call the model makes counts as one search or one page read. */
+export declare const LLM_COMPLETION_TOOLS: readonly ["web_search", "read_url"];
+export type LlmCompletionTool = (typeof LLM_COMPLETION_TOOLS)[number];
+/** At most this many messages in one completion. */
+export declare const LLM_COMPLETION_MAX_MESSAGES = 200;
+/** Longer contents answer `400`. */
+export declare const LLM_COMPLETION_MAX_MESSAGE_CHARS = 100000;
+/** All contents together. */
+export declare const LLM_COMPLETION_MAX_TOTAL_CHARS = 400000;
+/** `maxTokens` above this answers `400`. */
+export declare const LLM_COMPLETION_MAX_OUTPUT_TOKENS = 16000;
+/** How many tool calls one completion may make before the model is told to answer with what it has. */
+export declare const LLM_COMPLETION_MAX_TOOL_CALLS = 6;
+export type LlmCompletionRole = "system" | "user" | "assistant";
+export interface LlmCompletionMessage {
+    readonly role: LlmCompletionRole;
+    /** Plain text. Images and audio are not accepted here. */
+    readonly content: string;
+}
+export interface LlmCompletionInput {
+    /** In order. At least one `user` or `assistant` turn; `system` turns alone are a `400`. */
+    readonly messages: readonly LlmCompletionMessage[];
+    /**
+     * A model the caller may choose (an `id` or a `model_id` from {@link LlmNamespace.models}).
+     * Omitted, the server's own choice for API completions answers, with its fallbacks.
+     */
+    readonly model?: string;
+    /** Ask for a JSON object. A request, not a guarantee: parse defensively. */
+    readonly json?: boolean;
+    /** `0` to `2`. */
+    readonly temperature?: number;
+    /** `1` to {@link LLM_COMPLETION_MAX_OUTPUT_TOKENS}. */
+    readonly maxTokens?: number;
+    /** Tools the model may use while answering. Their calls come back in {@link LlmCompletion.tool_calls}. */
+    readonly tools?: readonly LlmCompletionTool[];
+    /** Language of the web searches the model runs (`"pt-PT"`, `"en"`); defaults to Portuguese. */
+    readonly language?: string;
+}
+/** One finished completion. Tokens and cost are `null` when the provider did not report them. */
+export interface LlmCompletion {
+    readonly text: string;
+    /** The provider's identifier of the model that answered (a fallback may differ from the one asked for). */
+    readonly model_id: string | null;
+    readonly input_tokens: number | null;
+    readonly output_tokens: number | null;
+    /** In the provider's currency (USD for the hosted ones). */
+    readonly cost: number | null;
+    /** What the model did with its tools, in order. Empty without `tools`. */
+    readonly tool_calls: readonly LlmToolCall[];
+    /** From the request to the answer, in milliseconds. */
+    readonly duration_ms: number;
+}
 export declare class LlmNamespace extends Resource {
     /** Conversations with the assistant. */
     readonly chats: LlmChatsNamespace;
     constructor(http: ApiClient);
     /** The models the caller may choose, with today's remaining allowance on each. */
     models(options?: RequestOptions): Promise<LlmModelChoice[]>;
+    /**
+     * `POST /llm/completions` - one answer to a list of messages, with nothing
+     * remembered between calls. For programs; people talk to the assistant
+     * through {@link chats}.
+     *
+     * Every completion counts on the account's daily ceilings (`llm_requests`
+     * and `llm_cost_microusd` in `oms.quotas.list()`) and on the chosen model's
+     * own daily limits. Needs the `llm` scope on an OAuth token.
+     *
+     * @throws {OmsApiError} 400 for malformed messages, an unknown model
+     *   (`error: "unknown_model"`) or an unknown tool; 403 `error: "model_not_allowed"`
+     *   for a model above the account's tier; 429 `error: "limit"` when a
+     *   daily ceiling is reached, or above 30 completions a minute; 502
+     *   `error: "unavailable"` when no model answered; 503 `error: "busy"`
+     *   when the provider has no free slot, worth a retry in a moment.
+     */
+    complete(input: LlmCompletionInput, options?: RequestOptions): Promise<LlmCompletion>;
     /** The caller's own usage. */
     usage(input?: LlmUsageQuery, options?: RequestOptions): Promise<LlmUsageSummary>;
 }

package/dist/types/resources/quotas.d.ts

@@ -19,8 +19,9 @@
  *   what is stored RIGHT NOW and only falls when something is deleted; waiting
  *   does not give it back.
  * - **Anonymous callers get a shorter list.** Without a credential the server
- *   answers with the daily resources only, counted per IP, because an
- *   anonymous caller has no file tree and no music library. Never index the
+ *   answers with the daily tool resources only, counted per IP, because an
+ *   anonymous caller has no file tree, no music library and no way to reach
+ *   a model or the search engines. Never index the
  *   array by position - look the resource up by name, or use
  *   {@link quotaFor}, which returns `undefined` rather than lying.
  *
@@ -44,14 +45,16 @@ import type { RequestOptions } from "../types";
  * widened to `string` on purpose, so an unknown name arrives as data rather
  * than as a type error in a client nobody has rebuilt.
  */
-export declare const QUOTA_RESOURCES: readonly ["vocal_separation_seconds", "transcription_seconds", "caption_seconds", "jumpstyle_edits", "storage_nodes", "music_storage_bytes"];
+export declare const QUOTA_RESOURCES: readonly ["vocal_separation_seconds", "transcription_seconds", "caption_seconds", "jumpstyle_edits", "storage_nodes", "music_storage_bytes", "llm_requests", "llm_cost_microusd", "search_requests"];
 /** One of {@link QUOTA_RESOURCES}. */
 export type QuotaResource = (typeof QUOTA_RESOURCES)[number];
 /**
  * What the numbers count. `"seconds"` of media, `"count"` of whole things
- * (edits, files and folders), `"bytes"` of stored media.
+ * (edits, files and folders, model calls, searches), `"bytes"` of stored
+ * media, `"microusd"` of model spend (millionths of a US dollar, so
+ * `200_000` is 0.20 USD).
  */
-export type QuotaUnit = "seconds" | "count" | "bytes";
+export type QuotaUnit = "seconds" | "count" | "bytes" | "microusd";
 /**
  * `"daily"` spends and resets at midnight, server time. `"total"` is what is
  * stored right now and only falls when something is deleted.

package/dist/types/resources/search.d.ts

@@ -103,8 +103,44 @@ export interface SearchResponse {
     /** Whether asking for `page + 1` is likely to return anything. */
     readonly has_more: boolean;
 }
+/** Longer values answer `400`. */
+export declare const SEARCH_PAGE_MAX_URL_LENGTH = 2000;
+/** `maxChars` outside this range answers `400`. */
+export declare const SEARCH_PAGE_MIN_CHARS = 200;
+export declare const SEARCH_PAGE_MAX_CHARS = 20000;
+export interface SearchPageInput {
+    /** A public `http(s)` URL. Private, loopback and link-local addresses answer `422`. */
+    readonly url: string;
+    /** How much text to return, {@link SEARCH_PAGE_MIN_CHARS} to {@link SEARCH_PAGE_MAX_CHARS}; defaults to 8000. */
+    readonly maxChars?: number;
+}
+/** The readable part of one page: scripts, navigation, footers and forms stripped. */
+export interface SearchPage {
+    /** Where the page was actually read from, after redirects. */
+    readonly url: string;
+    readonly host: string;
+    /** Plain text, at most 200 characters; empty when the page has no title. */
+    readonly title: string;
+    /** Plain text, whitespace collapsed, cut at `maxChars`. Never empty: a page with nothing readable is a `422`. */
+    readonly text: string;
+}
 /** The `search` namespace, reachable as `oms.search`. */
 export declare class SearchNamespace extends Resource {
+    /**
+     * `GET /search/page` - reads one public web page and returns its main text.
+     * The natural follow-up to {@link query}: search first, then read the hits
+     * worth reading in full.
+     *
+     * Only `http` and `https`, only public addresses, at most three redirects,
+     * and pages that are not HTML or text are refused. The server keeps the
+     * answer for ten minutes, so reading the same page twice is cheap.
+     *
+     * @throws {OmsApiError} 400 for a missing or overlong URL or a `maxChars`
+     *   out of range; 401 without a credential; 422 with `error: "unreadable"`
+     *   and a `message` saying why (private address, not HTML, unreachable,
+     *   HTTP error, nothing readable); 429 above 60 reads a minute.
+     */
+    readPage(input: SearchPageInput, options?: RequestOptions): Promise<SearchPage>;
     /**
      * `GET /search` - runs one search and returns one page of merged results.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omelhorsite/sdk",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "TypeScript SDK for the omelhorsite API. Isolate-safe: no node builtins, no environment access, no stdout.",
   "type": "module",
   "license": "UNLICENSED",

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

@@ -1,230 +0,0 @@
-/** Intel stories: the analysed, grouped, scored output. */
-import { Resource } from "../../../http";
-import type { ListParams } from "../../../listing";
-import type { Id, Paginated, RequestOptions, Timestamp } from "../../../types";
-import type { IntelArticleCategory, IntelReportKind } from "./types";
-/**
- * A story: several raw items about the same event, grouped, scored and
- * categorised by the analysis pipeline.
- *
- * This is the shape an INDEX row has. `GET /intel_articles/:id` renders
- * `:extended`, which is this plus four more keys - see
- * {@link IntelArticleDetail}. The detail is always a superset, never a
- * different record.
- */
-export interface IntelArticle {
-    readonly id: Id;
-    readonly created_at: Timestamp;
-    readonly updated_at: Timestamp;
-    /** Headline the model wrote. Nullable: the column has no `NOT NULL`. */
-    readonly title: string | null;
-    /** One-paragraph summary. Nullable for the same reason. */
-    readonly summary: string | null;
-    /**
-     * 0-10, validated `only_integer, in: 0..10`. The buckets the dashboard uses
-     * are in {@link IntelStats.by_importance} and they are NOT evenly spaced:
-     * >=9 critical, 7-8 high, 5-6 medium, 3-4 low, <3 noise.
-     */
-    readonly importance: number;
-    /** See {@link IntelArticleCategory}. `null` when unclassified. */
-    readonly category: IntelArticleCategory | null;
-    /**
-     * Free-form tags. The column defaults to `[]`, but it is nullable, so a row
-     * written before the default landed can still hand you `null`. Do not map
-     * over it without a guard.
-     */
-    readonly tags: string[] | null;
-    /**
-     * The `og:image` of one of the story's sources, stored RAW and uncompressed
-     * - it points at whatever news site published it, not at this API. Render it
-     * through {@link intelArticleImageUrl} rather than directly; that helper
-     * explains the trade it makes.
-     */
-    readonly image_url: string | null;
-    /**
-     * Whether the web-search enrichment pass has run on this story.
-     *
-     * `false` is not a failure, it is a queue position: `AnalyzeUserJob` enriches
-     * at most three stories per run, only those at or above
-     * {@link IntelConfig.enrich_min_importance}, and only while
-     * {@link IntelConfig.web_search} is on. A low-importance story stays `false`
-     * for ever, by design.
-     */
-    readonly enriched: boolean;
-    /** When the story was first built. */
-    readonly first_seen_at: Timestamp;
-    /** Touched every time a new item joins the story. This is the "recency" clock. */
-    readonly last_seen_at: Timestamp;
-    /**
-     * How many raw items back this story.
-     *
-     * Costs one COUNT query per row on the listing. A page of 500 stories is
-     * 500 extra queries. This is the reason to keep `pageSize` modest on
-     * {@link IntelArticlesNamespace.list}.
-     */
-    readonly n_sources: number;
-}
-/** One raw item cited by a story, as `:extended` inlines it. */
-export interface IntelArticleSourceRef {
-    /** Id of the {@link IntelItem}. Fetch the full row with `items.get(id)`. */
-    readonly id: Id;
-    /** Name of the {@link IntelSource} the item came from, or `null` if it was deleted. */
-    readonly source_name: string | null;
-    readonly title: string | null;
-    readonly url: string | null;
-    readonly published_at: Timestamp | null;
-}
-/**
- * A story related to this one, as `:extended` inlines it.
- *
- * "Related" is not "duplicate": duplicates are merged during dedup and never
- * become two rows. `IntelArticleLink` is an undirected edge between two
- * DISTINCT stories, which is why {@link relation} is one label describing the
- * pair rather than a direction.
- */
-export interface IntelRelatedArticleRef {
-    readonly id: Id;
-    readonly title: string | null;
-    readonly importance: number;
-    readonly category: IntelArticleCategory | null;
-    /** Free text the model wrote for the edge, e.g. a pattern name. Nullable. */
-    readonly relation: string | null;
-}
-/** A report this story appears in, as `:extended` inlines it. Newest period first. */
-export interface IntelArticleReportRef {
-    readonly id: Id;
-    readonly kind: IntelReportKind;
-    readonly title: string | null;
-    readonly period_end: Timestamp;
-}
-/**
- * `GET /intel_articles/:id` - the `:extended` view.
- *
- * Four keys the listing does not carry, and all four are joins run inline:
- * `sources` walks `intel_items`, `related` walks the link table in
- * BOTH directions, `reports` orders the report join by `period_end`. There is
- * no paging on any of them, so a story that has been running for a week can
- * inline a lot of rows.
- */
-export interface IntelArticleDetail extends IntelArticle {
-    /** The long body. `null` until the enrichment pass writes one. */
-    readonly details: string | null;
-    /** Every raw item behind the story. Length matches {@link IntelArticle.n_sources}. */
-    readonly sources: IntelArticleSourceRef[];
-    /** Stories linked to this one. `[]` when the linker found nothing. */
-    readonly related: IntelRelatedArticleRef[];
-    /** Reports that cited this story, newest period first. */
-    readonly reports: IntelArticleReportRef[];
-}
-/** Filter columns of `GET /intel_articles`, on top of {@link BASE_FILTER_COLUMNS}. */
-export declare const INTEL_ARTICLE_FILTER_COLUMNS: readonly ["title", "summary", "category", "importance", "enriched"];
-/** Filters for {@link IntelArticlesNamespace.list}. */
-export interface ListIntelArticlesParams extends ListParams<(typeof INTEL_ARTICLE_FILTER_COLUMNS)[number]> {
-    /**
-     * Free-text search over `title`, `summary` AND `details`.
-     *
-     * A TOP-LEVEL parameter, not a `search` key: the controller reads
-     * `params[:q]` itself, which is why it can reach `details` (a column that is
-     * not in `search_params` at all) and why an unknown-filter 400 cannot
-     * happen for it.
-     *
-     * Three ways it differs from {@link ListParams.search}:
-     *
-     * - it is **accent-SENSITIVE**. The controller does `LOWER(col) LIKE
-     *   LOWER(term)`, with no unaccenting, while the list DSL's `search` strips
-     *   accents on both sides. `"policia"` will not find `"polícia"` here.
-     * - `%` and `_` in your term are **not escaped**. The controller wraps the
-     *   term as `"%#{q}%"` and binds it, so a term containing `%` is a wildcard,
-     *   not a literal percent sign. Not an injection - it is a bound parameter -
-     *   but a surprise. Strip them if you are passing user input through.
-     * - it is an unanchored `LIKE` over three text columns with no index, so it
-     *   is a sequential scan of your stories. Fine for thousands, not for
-     *   millions.
-     */
-    readonly q?: string;
-    /**
-     * Keep only stories at or above this importance. Also top-level.
-     *
-     * Sent through Ruby's `String#to_i`, which does NOT raise: `"high"` becomes
-     * `0` and the filter silently matches everything. Pass a number and let the
-     * SDK stringify it.
-     */
-    readonly minImportance?: number;
-    /**
-     * `"recent"` orders by `last_seen_at` descending. Anything else - including
-     * omitting it - orders by `importance` descending, then `last_seen_at`
-     * descending. There is no third value and no ascending variant.
-     *
-     * If you ALSO pass {@link PageParams.order}, both apply and yours wins: the
-     * controller appends its ordering after the list DSL has applied
-     * `modifiers[order]`, so your column becomes the primary sort key and the
-     * controller's becomes the tie-breaker. That is the opposite of what the
-     * parameter names suggest.
-     */
-    readonly sort?: "recent" | "importance";
-}
-/**
- * `GET /intel_articles` and friends: the stories the pipeline built.
- *
- * Read-only plus a delete. There is no create and no update route -
- * `IntelArticle#creatable_by?` and `#updatable_by?` both return `false`
- * unconditionally, and the route is `only: [:index, :show, :destroy]`. Stories
- * come from `Intel::ArticleBuilder`, never from a client.
- */
-export declare class IntelArticlesNamespace extends Resource {
-    /**
-     * `GET /intel_articles` - your stories, most important first.
-     *
-     * Ordering is the controller's, not yours by default: `importance DESC,
-     * last_seen_at DESC`, or `last_seen_at DESC` alone with `sort: "recent"`.
-     * See {@link ListIntelArticlesParams.sort} for what happens when you pass
-     * `order` as well - it is not what the names imply.
-     *
-     * Filter keys this controller declares for `search` / `exactSearch`:
-     * `title`, `summary`, `category`, `importance`, `enriched`, plus the
-     * inherited `id`, `created_at`, `updated_at`. Anything else is
-     * `400 "Unknown search filter: x"` - fail-closed, never a wider result. The
-     * free-text and importance filters are top-level instead: `q` and
-     * `minImportance`.
-     *
-     * **Cost.** Every row runs its own `COUNT` for
-     * {@link IntelArticle.n_sources}. Keep `pageSize` in the tens, not at 500.
-     *
-     * The response carries an `ETag` and can answer `304` - except when
-     * `random` is set, which short-circuits `resources_stale?`.
-     *
-     * @throws {OmsAuthError} 401 when anonymous.
-     * @throws {OmsApiError} 403 `"Intel access is restricted."` for a signed-in
-     *   account outside the allowlist; 400 for an unrecognised filter key.
-     */
-    list(params?: ListIntelArticlesParams, options?: RequestOptions): Promise<Paginated<IntelArticle>>;
-    /**
-     * `GET /intel_articles/:id` - one story with its body, its sources, its
-     * related stories and the reports that cited it.
-     *
-     * The `:extended` view, so it is a strict superset of the listing row. All
-     * four extras are inlined without paging; see {@link IntelArticleDetail}.
-     *
-     * @throws {OmsApiError} 404 `"Resource not found"` when the id is not one of
-     *   yours - the lookup is `viewable_by(Current.user).find_by(id:)`, so
-     *   somebody else's story is indistinguishable from a typo, which is the
-     *   point.
-     */
-    get(id: Id, options?: RequestOptions): Promise<IntelArticleDetail>;
-    /**
-     * `DELETE /intel_articles/:id` - drops a story. `204`, empty body.
-     *
-     * The story's links to items are removed with it (`dependent: :destroy` on
-     * `intel_article_sources`), but the {@link IntelItem} rows themselves SURVIVE
-     * - they belong to the source, not to the story. They are also still marked
-     * `processed_at`, so deleting a story does not make the pipeline rebuild it.
-     * This is a hide, not an undo.
-     *
-     * @throws {OmsApiError} 404 when the story is not yours. 401
-     *   `"You are not authorized to destroy this resource"` cannot happen here -
-     *   `destroyable_by?` is `user == self.user` and the lookup already scoped it
-     *   - but note the API's habit of answering 401 rather than 403 for a failed
-     *   authorisation check, which the scripts routes DO hit.
-     */
-    delete(id: Id, options?: RequestOptions): Promise<void>;
-}