@omelhorsite/sdk 0.5.0 → 0.11.0

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

@@ -0,0 +1,296 @@
+/**
+ * The `llm` namespace: the language models a signed-in person may pick, and
+ * what they have used.
+ *
+ * Which models exist, what they cost and who may use how much of them is
+ * administered on the server; this surface only reads. The administrator
+ * side lives under `oms.admin.llmProviders`, `oms.admin.llmModels`,
+ * `oms.admin.llmAssignments` and `oms.admin.llmUsage`.
+ */
+import { Resource, type ApiClient } from "../http";
+import type { ListParams } from "../listing";
+import type { Id, Paginated, RequestOptions, Timestamp } from "../types";
+/** What a model can do. Absent keys mean "unknown", not "no". */
+export declare const LLM_CAPABILITY_KEYS: readonly ["vision", "audio", "tools", "json", "reasoning", "streaming"];
+export type LlmCapabilityKey = (typeof LLM_CAPABILITY_KEYS)[number];
+export type LlmCapabilities = {
+    readonly [K in LlmCapabilityKey]?: boolean;
+};
+/**
+ * Per-model ceilings. `rpm` is informational; the two `*_per_day_per_user`
+ * keys are enforced per calendar day (server time) and answer `429` when hit.
+ * A missing key or `0` means no ceiling.
+ */
+export declare const LLM_LIMIT_KEYS: readonly ["rpm", "requests_per_day_per_user", "tokens_per_day_per_user"];
+export type LlmLimitKey = (typeof LLM_LIMIT_KEYS)[number];
+export type LlmLimits = {
+    readonly [K in LlmLimitKey]?: number;
+};
+/** How much of a model's daily ceilings the caller has used today. `null` remaining means no ceiling. */
+export interface LlmModelUsageToday {
+    readonly requests_today: number;
+    readonly tokens_today: number;
+    readonly requests_remaining: number | null;
+    readonly tokens_remaining: number | null;
+}
+/** One model the caller may choose. Prices are per million tokens, `null` when unknown. */
+export interface LlmModelChoice {
+    readonly id: Id;
+    /** The provider's own identifier, e.g. `"qwen/qwen3.7-flash"`. */
+    readonly model_id: string;
+    readonly name: string;
+    readonly provider_slug: string;
+    readonly free: boolean;
+    readonly context_window: number | null;
+    readonly max_output_tokens: number | null;
+    readonly input_price_per_million: number | null;
+    readonly output_price_per_million: number | null;
+    readonly capabilities: LlmCapabilities;
+    readonly limits: LlmLimits;
+    readonly usage: LlmModelUsageToday;
+}
+/** Cost is in the provider's currency (USD for the hosted ones), already summed. */
+export interface LlmUsageTotals {
+    readonly requests: number;
+    readonly tokens: number;
+    readonly cost: number;
+    readonly errors: number;
+}
+/** One day of a series. `date` is `YYYY-MM-DD`; days without calls carry zeros. */
+export interface LlmUsageDay {
+    readonly date: string;
+    readonly requests: number;
+    readonly tokens: number;
+    readonly cost: number;
+}
+export interface LlmUsageByFeature {
+    readonly feature: string;
+    readonly requests: number;
+    readonly tokens: number;
+    readonly cost: number;
+}
+export interface LlmUsageByModel {
+    /** `null` when the provider has since been deleted. */
+    readonly provider_slug: string | null;
+    readonly model_id: string;
+    readonly requests: number;
+    readonly tokens: number;
+    readonly cost: number;
+}
+/** One person's share, on the administrator summary. `null` fields belong to calls made by background work. */
+export interface LlmUsageByUser {
+    readonly user_id: Id | null;
+    readonly handle: string | null;
+    readonly name: string | null;
+    readonly requests: number;
+    readonly tokens: number;
+    readonly cost: number;
+}
+/**
+ * Usage over a window of days. `daily` has exactly `days` entries, oldest
+ * first, ending today. The breakdowns count successful calls only; `errors`
+ * in the totals counts the failed ones.
+ */
+export interface LlmUsageSummary {
+    readonly days: number;
+    readonly totals: {
+        readonly today: LlmUsageTotals;
+        readonly last_7d: LlmUsageTotals;
+        readonly last_30d: LlmUsageTotals;
+        /** The requested window. */
+        readonly window: LlmUsageTotals;
+    };
+    readonly daily: LlmUsageDay[];
+    readonly by_feature: LlmUsageByFeature[];
+    readonly by_model: LlmUsageByModel[];
+}
+/** Windows longer than this answer `400`. */
+export declare const LLM_USAGE_MAX_DAYS = 90;
+export interface LlmUsageQuery {
+    /** 1 to {@link LLM_USAGE_MAX_DAYS}; defaults to 30. */
+    readonly days?: number;
+}
+/** Filter columns of `GET /llm_chats`, on top of the base ones. */
+export declare const LLM_CHAT_FILTER_COLUMNS: readonly ["title", "pinned", "archived", "llm_model_id", "tools_enabled", "account_tools_enabled"];
+export interface ListLlmChatsParams extends ListParams<(typeof LLM_CHAT_FILTER_COLUMNS)[number]> {
+}
+export declare const LLM_CHAT_ROLES: readonly ["user", "assistant", "system", "tool"];
+export type LlmChatRole = (typeof LLM_CHAT_ROLES)[number];
+/** `streaming` while the answer is still being written, then `done` or `error`. */
+export declare const LLM_CHAT_MESSAGE_STATUSES: readonly ["streaming", "done", "error"];
+export type LlmChatMessageStatus = (typeof LLM_CHAT_MESSAGE_STATUSES)[number];
+/**
+ * The tools the assistant can use in a chat. `web_search` and `read_url` are
+ * the web tools (`tools_enabled`); `search` and `execute` are the account
+ * tools (`account_tools_enabled`): the assistant looks up the SDK's type
+ * declarations and runs TypeScript against the API as the user.
+ */
+export declare const LLM_TOOL_NAMES: readonly ["web_search", "read_url", "search", "execute"];
+export type LlmToolName = (typeof LLM_TOOL_NAMES)[number] | (string & {});
+/** `running` only ever appears in the stream; a stored call is `done` or `error`. */
+export declare const LLM_TOOL_CALL_STATUSES: readonly ["running", "done", "error"];
+export type LlmToolCallStatus = (typeof LLM_TOOL_CALL_STATUSES)[number];
+/**
+ * One use of a tool: what was asked (`args`), a one-line `summary` for people, how long it took.
+ * `args` is the tool's input: `{ query }` for `web_search` and `search`, `{ url }` for `read_url`,
+ * and for `execute` `{ code, code_chars }` - the head of the program (2,000 characters at most)
+ * and the full length it had.
+ */
+export interface LlmToolCall {
+    readonly name: LlmToolName;
+    readonly args: Readonly<Record<string, unknown>>;
+    readonly status: LlmToolCallStatus;
+    readonly summary?: string;
+    readonly ms?: number;
+    readonly error?: string;
+}
+/** One conversation with the assistant. Pinned chats list first, then by `last_message_at`. */
+export interface LlmChat {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Taken from the first question when not set by the caller. */
+    readonly title: string | null;
+    /** The chosen model; `null` means the server's default for chats. */
+    readonly llm_model_id: Id | null;
+    /** The provider's identifier of the model that answered last. */
+    readonly model_id: string | null;
+    readonly pinned: boolean;
+    /** An archived chat can be read but not written to. */
+    readonly archived: boolean;
+    /** Whether the assistant may search the web and read pages in this chat. On by default. */
+    readonly tools_enabled: boolean;
+    /**
+     * Whether the assistant may act on the user's account in this chat (the
+     * `search` and `execute` tools: it reads the SDK's declarations and runs
+     * TypeScript against the API as the user, with a short-lived token that
+     * dies with each answer). Off by default; every write it wants to make
+     * it is told to confirm first.
+     */
+    readonly account_tools_enabled: boolean;
+    readonly last_message_at: Timestamp;
+    readonly message_count: number;
+}
+export interface LlmChatMessage {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly llm_chat_id: Id;
+    readonly role: LlmChatRole;
+    readonly content: string;
+    readonly status: LlmChatMessageStatus;
+    readonly model_id: string | null;
+    readonly input_tokens: number | null;
+    readonly output_tokens: number | null;
+    readonly cost: number | null;
+    /** Why an answer ended in `error`, or `"interrupted"` on a `done` answer cut short by the reader. */
+    readonly error: string | null;
+    /** What the assistant did with its tools while writing this answer, in order. */
+    readonly tool_calls: readonly LlmToolCall[];
+    /** From the request to the model until the answer ended, in milliseconds; `null` on questions. */
+    readonly duration_ms: number | null;
+    /** From the request until the first token; `null` when nothing was generated. Tokens per second is `output_tokens / ((duration_ms - first_token_ms) / 1000)`. */
+    readonly first_token_ms: number | null;
+    /** The question this answer belongs to. */
+    readonly parent_id: Id | null;
+}
+/** `GET /llm_chats/:id`: the chat plus its messages, oldest first. */
+export interface LlmChatDetail extends LlmChat {
+    readonly messages: LlmChatMessage[];
+}
+export interface CreateLlmChatInput {
+    readonly title?: string;
+    /** Must be a model the caller may choose (see {@link LlmNamespace.models}); the server answers `400` otherwise. */
+    readonly llmModelId?: Id;
+    /** Defaults to `true`. */
+    readonly toolsEnabled?: boolean;
+    /** Defaults to `false`. See {@link LlmChat.account_tools_enabled}. */
+    readonly accountToolsEnabled?: boolean;
+}
+export interface UpdateLlmChatInput {
+    readonly title?: string | null;
+    readonly llmModelId?: Id | null;
+    readonly pinned?: boolean;
+    readonly archived?: boolean;
+    readonly toolsEnabled?: boolean;
+    readonly accountToolsEnabled?: boolean;
+}
+export interface SendLlmChatMessageInput {
+    /** At most 32,000 characters. */
+    readonly content: string;
+    /** Answer with this model and remember it on the chat. */
+    readonly llmModelId?: Id;
+}
+/**
+ * What a streamed answer yields, in order: any number of `delta` and `tool`
+ * events (a tool yields `running` first, then `done` or `error`), then
+ * exactly one `done` or `error`. A refusal before the first token (the
+ * provider is busy, the daily ceiling is reached, no model is available) is
+ * not an event but a thrown `OmsApiError` with status `503`, `429` or `502`,
+ * whose body carries `message_id` - the failed answer is kept on the chat so
+ * it can be regenerated.
+ */
+export type LlmChatStreamEvent = {
+    readonly type: "delta";
+    readonly delta: string;
+} | ({
+    readonly type: "tool";
+} & LlmToolCall) | {
+    readonly type: "done";
+    readonly messageId: Id;
+    readonly modelId: string | null;
+    readonly inputTokens: number | null;
+    readonly outputTokens: number | null;
+    readonly cost: number | null;
+    readonly durationMs: number | null;
+    readonly firstTokenMs: number | null;
+} | {
+    readonly type: "error";
+    /** `busy`, `limit`, `unavailable`, `unknown_model` or `interrupted`. */
+    readonly error: string;
+    readonly message: string;
+    readonly messageId: Id | null;
+};
+/** The messages of one chat: send, regenerate, delete. Reached through `oms.llm.chats.messages`. */
+export declare class LlmChatMessagesNamespace extends Resource {
+    /**
+     * Sends a question and streams the answer. Consume with `for await`; stop
+     * early by aborting `options.signal` - the server keeps what had arrived.
+     * The chat's title is set from the first question.
+     */
+    send(chatId: Id, input: SendLlmChatMessageInput, options?: RequestOptions): AsyncGenerator<LlmChatStreamEvent, void, undefined>;
+    /**
+     * Answers the same question again. Only the chat's last message qualifies,
+     * and it must be an answer; the old answer is discarded, the new one takes
+     * its place with the same `parent_id`.
+     */
+    regenerate(chatId: Id, messageId: Id, options?: RequestOptions): AsyncGenerator<LlmChatStreamEvent, void, undefined>;
+    /**
+     * Removes a message from the end of the chat. Deleting a question also
+     * removes the answers to it; anything earlier answers `400`.
+     */
+    delete(chatId: Id, messageId: Id, options?: RequestOptions): Promise<void>;
+    private stream;
+}
+/** The caller's conversations with the assistant. Reached through `oms.llm.chats`. */
+export declare class LlmChatsNamespace extends Resource {
+    readonly messages: LlmChatMessagesNamespace;
+    constructor(http: ApiClient);
+    /** Pinned first, then most recently active. Archived chats are included; filter with `exactSearch: { archived: false }`. */
+    list(params?: ListLlmChatsParams, options?: RequestOptions): Promise<Paginated<LlmChat>>;
+    /** The chat with all its messages, oldest first. */
+    get(id: Id, options?: RequestOptions): Promise<LlmChatDetail>;
+    create(input?: CreateLlmChatInput, options?: RequestOptions): Promise<LlmChatDetail>;
+    update(id: Id, input: UpdateLlmChatInput, options?: RequestOptions): Promise<LlmChatDetail>;
+    /** Removes the chat and every message in it. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+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[]>;
+    /** The caller's own usage. */
+    usage(input?: LlmUsageQuery, options?: RequestOptions): Promise<LlmUsageSummary>;
+}

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

@@ -0,0 +1,116 @@
+/**
+ * The `search` namespace: web search through the site's own metasearch engine.
+ *
+ * One request, one answer: results from several upstream engines merged and
+ * scored server-side, plus the query suggestions and knowledge-panel style
+ * infoboxes the engines offered. Nothing is paged in the background - a page
+ * is what you asked for, and {@link SearchResponse.has_more} says whether it
+ * is worth asking for the next one.
+ *
+ * Requires a credential. The server answers the same query from a short-lived
+ * cache, so repeating a search (or paging back) is cheap.
+ */
+import { Resource } from "../http";
+import type { RequestOptions } from "../types";
+/** The four result families. Each one changes what a {@link SearchResult} carries. */
+export declare const SEARCH_CATEGORIES: readonly ["general", "images", "news", "videos"];
+export type SearchCategory = (typeof SEARCH_CATEGORIES)[number];
+/** Restricts results to things published inside the window. */
+export declare const SEARCH_TIME_RANGES: readonly ["day", "week", "month", "year"];
+export type SearchTimeRange = (typeof SEARCH_TIME_RANGES)[number];
+/** `0` off, `1` moderate (the default), `2` strict. */
+export type SearchSafeSearch = 0 | 1 | 2;
+/** Pages beyond this answer `400`. */
+export declare const SEARCH_MAX_PAGE = 10;
+/** Longer queries answer `400`. */
+export declare const SEARCH_MAX_QUERY_LENGTH = 200;
+export interface SearchQueryInput {
+    /** What to search for. Trimmed server-side; blank is a `400`. */
+    readonly q: string;
+    /** 1-based, at most {@link SEARCH_MAX_PAGE}. Defaults to 1. */
+    readonly page?: number;
+    /** Defaults to `"general"`. */
+    readonly category?: SearchCategory;
+    readonly timeRange?: SearchTimeRange;
+    /**
+     * A language code such as `"pt"`, `"pt-PT"` or `"en"`, or `"all"` to search
+     * without a language filter. When omitted the server reads the request's
+     * `Accept-Language`, and falls back to Portuguese.
+     */
+    readonly language?: string;
+    /** Defaults to `1`. */
+    readonly safesearch?: SearchSafeSearch;
+}
+/**
+ * One hit.
+ *
+ * `image`, `resolution` and `duration` are filled only by the category that
+ * has them (images for the first two, videos for the last) and are `null`
+ * otherwise; `thumbnail` may appear in any category. `published_at` is the
+ * upstream engine's own timestamp string and is not normalised to one format.
+ */
+export interface SearchResult {
+    /** Never empty: a hit without a title carries its host instead. */
+    readonly title: string;
+    /** Always absolute `http(s)`. */
+    readonly url: string;
+    /** The hostname of `url` without a leading `www.`. */
+    readonly host: string;
+    /** Plain text, at most 600 characters. Empty when the engine gave none. */
+    readonly snippet: string;
+    /** Upstream engines that returned this hit, deduplicated. */
+    readonly engines: string[];
+    readonly thumbnail: string | null;
+    /** The full-size image, images only. */
+    readonly image: string | null;
+    /** `"1200x800"` style, images only. */
+    readonly resolution: string | null;
+    /** As the engine spells it (`"12:34"`), videos only. */
+    readonly duration: string | null;
+    readonly published_at: string | null;
+    readonly category: SearchCategory | string;
+}
+export interface SearchInfoboxLink {
+    readonly title: string;
+    readonly url: string;
+}
+/** A knowledge-panel style card an engine attached to the query. */
+export interface SearchInfobox {
+    readonly title: string;
+    /** Plain text, at most 1200 characters. */
+    readonly content: string;
+    readonly image: string | null;
+    /** At most six. */
+    readonly urls: SearchInfoboxLink[];
+}
+export interface SearchResponse {
+    /** The query as the engine understood it. */
+    readonly query: string;
+    readonly category: SearchCategory | string;
+    readonly page: number;
+    /** At most 40, in the server's ranking order. */
+    readonly results: SearchResult[];
+    /** At most eight related queries. */
+    readonly suggestions: string[];
+    readonly infoboxes: SearchInfobox[];
+    /**
+     * The engines' own estimate of the total. Often `0`: many engines do not
+     * report one, and it is never the length of anything you can page through.
+     */
+    readonly number_of_results: number;
+    /** Engines that failed to answer in time. The results are complete without them. */
+    readonly unresponsive_engines: string[];
+    /** Whether asking for `page + 1` is likely to return anything. */
+    readonly has_more: boolean;
+}
+/** The `search` namespace, reachable as `oms.search`. */
+export declare class SearchNamespace extends Resource {
+    /**
+     * `GET /search` - runs one search and returns one page of merged results.
+     *
+     * @throws {OmsApiError} 400 when the query is blank or too long, or a
+     *   parameter is out of range; 401 without a credential; 429 above 60
+     *   searches a minute; 502 while the engine behind the service is down.
+     */
+    query(input: SearchQueryInput, options?: RequestOptions): Promise<SearchResponse>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omelhorsite/sdk",
-  "version": "0.5.0",
+  "version": "0.11.0",
   "description": "TypeScript SDK for the omelhorsite API. Isolate-safe: no node builtins, no environment access, no stdout.",
   "type": "module",
   "license": "UNLICENSED",
@@ -20,7 +20,7 @@
     "typecheck": "tsc --noEmit -p . && tsc --noEmit -p tsconfig.test.json",
     "check:isolate": "bun run scripts/check-isolate.ts",
     "test": "bun run check:isolate && bun test",
-    "build": "bun build src/index.ts --target node --format esm --outdir dist --external uqr && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts --target node --format esm --outdir dist --external uqr && tsc -p tsconfig.build.json",
     "prepublishOnly": "bun run build",
     "typecheck:tests": "tsc --noEmit -p tsconfig.test.json"
   },