@omelhorsite/sdk 0.5.1 → 0.11.0

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

@@ -1,13 +1,14 @@
 /**
  * The `account` namespace: the signed-in user, other users' public profiles,
- * the usage report behind the quota bars, and the sessions a credential can
- * see.
+ * the usage report behind the quota bars, the sessions a credential can see,
+ * and which notifications reach the app and the mailbox.
  *
  * `GET /account` is the canonical "who am I" call and the cheapest way to check
  * that a stored credential is still alive.
  */
 import { type ApiClient, Resource } from "../http";
 import type { ListParams } from "../listing";
+import type { NotificationCategory, NotificationKind } from "./content/notifications";
 import type { BaseRecord, FileInput, Id, Paginated, RequestOptions, Timestamp } from "../types";
 /**
  * A user as the API renders them.
@@ -240,10 +241,75 @@ export declare class AccountSessionsNamespace extends Resource {
      */
     revoke(id: Id, options?: RequestOptions): Promise<void>;
 }
+/** How one notification kind reaches the user. */
+export interface NotificationPreferenceEntry {
+    readonly kind: NotificationKind;
+    readonly category: NotificationCategory;
+    /** Whether the kind shows in the inbox and counts as unread. */
+    readonly in_app: boolean;
+    /** Whether the kind is also emailed, subject to the master switch. */
+    readonly email: boolean;
+    /** `true` for the security kinds: `email` cannot be turned off, and asking is a 422. */
+    readonly email_locked: boolean;
+    /**
+     * Minutes the server waits so that several notifications of this kind
+     * become one email. `null` sends each one on its own.
+     */
+    readonly coalesce_minutes: number | null;
+}
+/** The whole notification setup of the signed-in user. */
+export interface NotificationPreferences {
+    /**
+     * The master switch. `false` stops every notification email, locked kinds
+     * included; it is what the unsubscribe link in an email flips.
+     */
+    readonly emails_enabled: boolean;
+    /** Every kind the server knows, in presentation order, defaults filled in. */
+    readonly kinds: NotificationPreferenceEntry[];
+}
+/**
+ * Changes to {@link NotificationPreferences}. Everything is optional: pass
+ * only what moves, and only the kinds that move.
+ */
+export interface UpdateNotificationPreferencesInput {
+    readonly emailsEnabled?: boolean;
+    readonly kinds?: Partial<Record<NotificationKind, {
+        readonly inApp?: boolean;
+        readonly email?: boolean;
+    }>>;
+}
+/**
+ * Notification preferences of the signed-in user, reachable as
+ * `oms.account.notificationPreferences`.
+ *
+ * A notification is always recorded; these settings decide where it goes.
+ * `in_app: false` keeps a kind out of the inbox, the unread count and the
+ * live feed. `email: true` sends it by email as well, provided the master
+ * switch is on and the account's address is verified.
+ *
+ * Needs a session.
+ */
+export declare class NotificationPreferencesNamespace extends Resource {
+    /**
+     * `GET /notification_preferences` - every kind, in presentation order,
+     * with the server's defaults where nothing was set yet.
+     */
+    get(options?: RequestOptions): Promise<NotificationPreferences>;
+    /**
+     * `PATCH /notification_preferences` - flips the master switch and/or the
+     * settings of single kinds, and answers the full set like {@link get}.
+     *
+     * @throws {OmsApiError} 422 for `email: false` on a kind whose
+     *   `email_locked` is `true`, and for a kind the server does not know.
+     */
+    update(input: UpdateNotificationPreferencesInput, options?: RequestOptions): Promise<NotificationPreferences>;
+}
 /** The `account` namespace, reachable as `oms.account`. */
 export declare class AccountNamespace extends Resource {
     /** Sessions: listing, relabelling, and ending the current one. */
     readonly sessions: AccountSessionsNamespace;
+    /** Which notification kinds reach the inbox, and which are emailed. */
+    readonly notificationPreferences: NotificationPreferencesNamespace;
     constructor(http: ApiClient);
     /**
      * `GET /account` - the user the current credential belongs to.

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

@@ -5,6 +5,7 @@ import { AdminChestsNamespace } from "./chests";
 import { AdminEventAlertsNamespace } from "./eventAlerts";
 import { LinkedIdentitiesNamespace } from "./identities";
 import { AdminJobsNamespace } from "./jobs";
+import { AdminLlmAssignmentsNamespace, AdminLlmModelsNamespace, AdminLlmProvidersNamespace, AdminLlmUsageNamespace } from "./llm";
 import { MyOauthApplicationsNamespace } from "./myOauthApplications";
 import { AdminNotepadsNamespace } from "./notepads";
 import { AdminOauthApplicationsNamespace } from "./oauthApplications";
@@ -17,6 +18,7 @@ export * from "./chests";
 export * from "./eventAlerts";
 export * from "./identities";
 export * from "./jobs";
+export * from "./llm";
 export * from "./myOauthApplications";
 export * from "./notepads";
 export * from "./oauthApplications";
@@ -77,5 +79,13 @@ export declare class AdminNamespace extends Resource {
     readonly eventAlerts: AdminEventAlertsNamespace;
     /** Any account, admin-only fields included. */
     readonly users: AdminUsersNamespace;
+    /** Language-model providers and their keys. **Administrators only.** */
+    readonly llmProviders: AdminLlmProvidersNamespace;
+    /** The models of every provider: prices, ceilings, visibility. **Administrators only.** */
+    readonly llmModels: AdminLlmModelsNamespace;
+    /** Which models answer each feature of the site, in fallback order. **Administrators only.** */
+    readonly llmAssignments: AdminLlmAssignmentsNamespace;
+    /** Everybody's language-model usage and cost. **Administrators only.** */
+    readonly llmUsage: AdminLlmUsageNamespace;
     constructor(http: ConstructorParameters<typeof Resource>[0]);
 }

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

@@ -0,0 +1,247 @@
+/**
+ * `oms.admin.llmProviders`, `oms.admin.llmModels`, `oms.admin.llmAssignments`
+ * and `oms.admin.llmUsage` - the language-model configuration. Administrators
+ * only; everything below answers `403` to anybody else.
+ *
+ * A provider is an OpenAI-compatible endpoint plus its key. A model belongs to
+ * one provider. An assignment says which models, in order, answer a named
+ * feature of the site (`"chat"`, `"translate"`, ...): the second model is the
+ * fallback of the first, and may sit on another provider. Usage is one record
+ * per call, aggregated here.
+ */
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { Id, JsonObject, Paginated, RequestOptions, Timestamp } from "../../types";
+import type { LlmCapabilities, LlmLimits, LlmUsageByUser, LlmUsageQuery, LlmUsageSummary } from "../llm";
+/**
+ * `openai_compatible` is any server speaking the OpenAI chat API (vLLM, LM
+ * Studio, Ollama's `/v1`, a self-hosted sidecar); `openrouter` and `ollama`
+ * get provider-specific error and model-list handling.
+ */
+export declare const LLM_PROVIDER_KINDS: readonly ["openai_compatible", "openrouter", "ollama"];
+export type LlmProviderKind = (typeof LLM_PROVIDER_KINDS)[number];
+/**
+ * Provider switches. `models_param` sends the ordered fallback list in one
+ * request so the provider falls back itself (at most three models per
+ * request) - what OpenRouter expects; a local server wants it off.
+ */
+export interface LlmProviderOptions {
+    readonly models_param?: boolean;
+}
+/** The key never comes back: `api_key_set` says whether one is stored. */
+export interface LlmProvider {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Lowercase letters, digits and dashes; unique. */
+    readonly slug: string;
+    readonly name: string;
+    readonly kind: LlmProviderKind | string;
+    /** Root of the OpenAI-compatible API, without a trailing slash: `/chat/completions` is appended. */
+    readonly base_url: string;
+    /** Extra request headers, sent with every call. */
+    readonly headers: Record<string, string>;
+    readonly options: LlmProviderOptions;
+    readonly enabled: boolean;
+    /** Calls allowed in flight at once on this provider; the next one answers `503`. */
+    readonly max_concurrency: number;
+    /** Seconds. */
+    readonly open_timeout: number;
+    /** Seconds, per read: a long generation is fine while tokens keep arriving. */
+    readonly read_timeout: number;
+    readonly api_key_set: boolean;
+    readonly models_count: number;
+}
+export interface CreateLlmProviderInput {
+    readonly slug: string;
+    readonly name: string;
+    readonly baseUrl: string;
+    /** Stored encrypted; never readable again through the API. */
+    readonly apiKey?: string;
+    readonly kind?: LlmProviderKind;
+    readonly headers?: Record<string, string>;
+    readonly options?: LlmProviderOptions;
+    readonly enabled?: boolean;
+    /** 1 to 64. */
+    readonly maxConcurrency?: number;
+    /** 1 to 60 seconds. */
+    readonly openTimeout?: number;
+    /** 5 to 600 seconds. */
+    readonly readTimeout?: number;
+}
+/** Omitting `apiKey`, or sending an empty string, keeps the stored key. */
+export type UpdateLlmProviderInput = Partial<CreateLlmProviderInput>;
+/** Filter columns of `GET /admin/llm_providers`. */
+export declare const ADMIN_LLM_PROVIDER_FILTER_COLUMNS: readonly ["slug", "name", "kind", "enabled"];
+export interface ListAdminLlmProvidersParams extends ListParams<(typeof ADMIN_LLM_PROVIDER_FILTER_COLUMNS)[number]> {
+}
+/**
+ * One model the provider offers, shaped like the record it would become.
+ * `free` is `null` when the provider publishes no prices; `added` says whether
+ * it is already in the list.
+ */
+export interface LlmAvailableModel {
+    readonly model_id: string;
+    readonly name: string;
+    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 free: boolean | null;
+    readonly capabilities: LlmCapabilities;
+    readonly description: string | null;
+    readonly added: boolean;
+}
+/** Always `200`: a failed probe is `ok: false` with the reason, not an error. */
+export interface LlmProviderTestResult {
+    readonly ok: boolean;
+    readonly model_id: string | null;
+    readonly reply?: string;
+    readonly latency_ms?: number;
+    readonly error?: string;
+}
+export interface TestLlmProviderInput {
+    /** A `model_id` of that provider; defaults to its first enabled model. */
+    readonly modelId?: string;
+}
+/** Prices are per million tokens, `null` when unknown. */
+export interface LlmModel {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    readonly llm_provider_id: Id;
+    readonly provider_slug: string | null;
+    /** The provider's own identifier; unique per provider. */
+    readonly model_id: string;
+    readonly name: string;
+    readonly enabled: boolean;
+    /** Whether signed-in people may pick it (see `oms.llm.models`). */
+    readonly visible_in_chat: 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 free: boolean;
+    readonly capabilities: LlmCapabilities;
+    readonly limits: LlmLimits;
+    readonly metadata: JsonObject;
+    /** Enabled, on an enabled provider. */
+    readonly usable: boolean;
+}
+export interface CreateLlmModelInput {
+    readonly llmProviderId: Id;
+    readonly modelId: string;
+    readonly name: string;
+    readonly enabled?: boolean;
+    readonly visibleInChat?: boolean;
+    readonly contextWindow?: number | null;
+    readonly maxOutputTokens?: number | null;
+    readonly inputPricePerMillion?: number | null;
+    readonly outputPricePerMillion?: number | null;
+    readonly free?: boolean;
+    readonly capabilities?: LlmCapabilities;
+    readonly limits?: LlmLimits;
+}
+/** The provider and the `model_id` are fixed after creation. */
+export type UpdateLlmModelInput = Partial<Omit<CreateLlmModelInput, "llmProviderId" | "modelId">>;
+/** Filter columns of `GET /admin/llm_models`. */
+export declare const ADMIN_LLM_MODEL_FILTER_COLUMNS: readonly ["llm_provider_id", "model_id", "name", "enabled", "visible_in_chat", "free"];
+export interface ListAdminLlmModelsParams extends ListParams<(typeof ADMIN_LLM_MODEL_FILTER_COLUMNS)[number]> {
+}
+/**
+ * Defaults a feature applies when the call does not say otherwise.
+ * `reasoning` is the request's `reasoning` object (e.g. `{ enabled: false }`:
+ * a reasoning model otherwise spends the whole token budget thinking and
+ * answers nothing). `num_ctx` goes to the provider verbatim (Ollama's context
+ * size). `prefer_free` puts the provider's free models in front of the list.
+ */
+export interface LlmAssignmentOptions {
+    readonly temperature?: number;
+    readonly max_tokens?: number;
+    readonly reasoning?: JsonObject;
+    readonly num_ctx?: number;
+    readonly prefer_free?: boolean;
+}
+export interface LlmAssignmentModelRef {
+    readonly id: Id;
+    readonly model_id: string;
+    readonly name: string;
+    readonly provider_slug: string | null;
+    readonly usable: boolean;
+    readonly free: boolean;
+}
+/** A feature of the site and the ordered models that answer it. */
+export interface LlmAssignment {
+    readonly id: Id;
+    readonly created_at: Timestamp;
+    readonly updated_at: Timestamp;
+    /** Lowercase letters, digits and underscores; unique. `"default"` answers features without one of their own. */
+    readonly feature: string;
+    /** Ordered: the second is the fallback of the first. */
+    readonly llm_model_ids: Id[];
+    readonly options: LlmAssignmentOptions;
+    /** Human description for the features the site knows; `null` for a custom one. */
+    readonly description: string | null;
+    /** `llm_model_ids` resolved, in the same order. */
+    readonly models: LlmAssignmentModelRef[];
+}
+/** One feature the site calls by name. */
+export interface LlmFeature {
+    readonly feature: string;
+    readonly description: string;
+}
+export interface CreateLlmAssignmentInput {
+    readonly feature: string;
+    readonly llmModelIds: readonly Id[];
+    readonly options?: LlmAssignmentOptions;
+}
+export interface UpdateLlmAssignmentInput {
+    readonly llmModelIds?: readonly Id[];
+    readonly options?: LlmAssignmentOptions;
+}
+/** Filter columns of `GET /admin/llm_assignments`. */
+export declare const ADMIN_LLM_ASSIGNMENT_FILTER_COLUMNS: readonly ["feature"];
+export interface ListAdminLlmAssignmentsParams extends ListParams<(typeof ADMIN_LLM_ASSIGNMENT_FILTER_COLUMNS)[number]> {
+}
+/** Everybody's usage: {@link LlmUsageSummary} plus the top twenty people by cost. */
+export interface LlmAdminUsageSummary extends LlmUsageSummary {
+    readonly by_user: LlmUsageByUser[];
+}
+export declare class AdminLlmProvidersNamespace extends Resource {
+    list(params?: ListAdminLlmProvidersParams, options?: RequestOptions): Promise<Paginated<LlmProvider>>;
+    get(id: Id, options?: RequestOptions): Promise<LlmProvider>;
+    create(input: CreateLlmProviderInput, options?: RequestOptions): Promise<LlmProvider>;
+    update(id: Id, input: UpdateLlmProviderInput, options?: RequestOptions): Promise<LlmProvider>;
+    /** Also deletes its models and drops it from every assignment. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * What the provider lists in its `/models`, without storing any of it: the
+     * model list is curated by hand and this is the menu to pick from. Cached
+     * for ten minutes; `fresh` skips the cache. `502` when the provider does
+     * not answer.
+     */
+    availableModels(id: Id, input?: {
+        fresh?: boolean;
+    }, options?: RequestOptions): Promise<LlmAvailableModel[]>;
+    /** One tiny completion, to check the key, the URL and a model. */
+    test(id: Id, input?: TestLlmProviderInput, options?: RequestOptions): Promise<LlmProviderTestResult>;
+}
+export declare class AdminLlmModelsNamespace extends Resource {
+    list(params?: ListAdminLlmModelsParams, options?: RequestOptions): Promise<Paginated<LlmModel>>;
+    get(id: Id, options?: RequestOptions): Promise<LlmModel>;
+    create(input: CreateLlmModelInput, options?: RequestOptions): Promise<LlmModel>;
+    update(id: Id, input: UpdateLlmModelInput, options?: RequestOptions): Promise<LlmModel>;
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+export declare class AdminLlmAssignmentsNamespace extends Resource {
+    list(params?: ListAdminLlmAssignmentsParams, options?: RequestOptions): Promise<Paginated<LlmAssignment>>;
+    get(id: Id, options?: RequestOptions): Promise<LlmAssignment>;
+    create(input: CreateLlmAssignmentInput, options?: RequestOptions): Promise<LlmAssignment>;
+    update(id: Id, input: UpdateLlmAssignmentInput, options?: RequestOptions): Promise<LlmAssignment>;
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /** The features the site calls by name, with a description each. Any other slug is accepted too. */
+    features(options?: RequestOptions): Promise<LlmFeature[]>;
+}
+export declare class AdminLlmUsageNamespace extends Resource {
+    summary(input?: LlmUsageQuery, options?: RequestOptions): Promise<LlmAdminUsageSummary>;
+}

package/dist/types/resources/admin/myOauthApplications.d.ts

@@ -90,8 +90,8 @@ export interface CreateOauthApplicationInput {
      * and a redirect URI pointing at something an attacker controls IS account
      * takeover - PKCE does not help, it binds the code to the client that started
      * the flow, not to where the code is delivered. The server refuses anything
-     * that is not `https`, not loopback `http`, carries userinfo, carries a
-     * wildcard host or has no host at all, and it does so with a `422`
+     * that is not `http` or `https`, carries userinfo, carries a wildcard host
+     * or has no host at all, and it does so with a `422`
      * (`validation_failed`) rather than by quietly rewriting your value.
      */
     readonly redirect_uri?: string;

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

@@ -8,19 +8,29 @@ export declare const NOTIFICATION_FILTER_COLUMNS: readonly ["user_id"];
 export type ListNotificationsParams = ListParams<(typeof NOTIFICATION_FILTER_COLUMNS)[number]>;
 /** Primary key of a notification. An INTEGER. */
 export type NotificationId = number;
+/** Every notification category, in presentation order. */
+export declare const NOTIFICATION_CATEGORIES: readonly ["security", "social", "storage", "tools", "music", "library", "forms", "tickets", "intel", "oauth", "admin"];
+/** One of {@link NOTIFICATION_CATEGORIES}. */
+export type NotificationCategory = (typeof NOTIFICATION_CATEGORIES)[number];
 /**
- * The `kind` strings the backend emits today.
+ * Every notification kind the server emits, grouped by category and in the
+ * order a preferences screen shows them (the same order
+ * {@link NotificationPreferences.kinds} comes back in).
  *
- * 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.
+ * `admin_*` kinds only ever reach administrators. The `_done` / `_failed`
+ * pairs of the media tools only reach the account that started the job.
+ */
+export declare const NOTIFICATION_KINDS: readonly ["security_new_session", "security_password_changed", "security_email_changed", "security_passkey_added", "security_app_authorized", "friendship_request", "friendship_accepted", "user_followed", "message_received", "group_chat_message", "jam_invite", "fs_grant_received", "chest_expires_soon", "vocal_separation_done", "vocal_separation_failed", "transcription_done", "transcription_failed", "upscale_done", "upscale_failed", "background_removal_done", "background_removal_failed", "caption_job_done", "caption_job_failed", "jumpstyle_job_done", "jumpstyle_job_failed", "song_import_done", "song_import_failed", "spotify_sync_done", "spotify_sync_failed", "artist_import_done", "blog_new_post", "form_submission_received", "ticket_reply", "ticket_status_changed", "intel_report_ready", "intel_source_failing", "oauth_application_approved", "oauth_application_rejected", "admin_oauth_application_submitted", "admin_ticket_created", "admin_feedback_received"];
+/**
+ * One of {@link NOTIFICATION_KINDS}.
  *
  * 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.
+ * why `context` is typed as an open record rather than a discriminated union.
+ * A server newer than this package may emit a kind that is not listed here,
+ * so keep a default branch when switching on it and never let an unknown
+ * kind break the inbox.
  */
-export type NotificationKind = "friendship_request" | "friendship_accepted" | "user_followed" | "message_received" | "fs_grant_received" | "jam_invite" | "vocal_separation_done" | "vocal_separation_failed" | (string & {});
+export type NotificationKind = (typeof NOTIFICATION_KINDS)[number];
 /**
  * One notification in a user's inbox.
  *
@@ -34,6 +44,8 @@ export interface Notification {
     readonly id: NotificationId;
     /** What happened. See {@link NotificationKind}. */
     readonly kind: NotificationKind;
+    /** The group `kind` belongs to. */
+    readonly category: NotificationCategory;
     /**
      * Free-form JSON payload, whose keys depend entirely on `kind` - these are
      * the i18n interpolation values the client renders the sentence with.
@@ -55,6 +67,12 @@ export interface Notification {
     readonly created_at: Timestamp;
     readonly updated_at: Timestamp;
 }
+/** What {@link NotificationsNamespace.unsubscribe} answers. */
+export interface NotificationUnsubscribeResult {
+    readonly ok: true;
+    /** The address that stops receiving notification emails, masked: `a***@b.pt`. */
+    readonly email: string;
+}
 /**
  * The `notifications` namespace: the per-user inbox.
  *
@@ -144,4 +162,19 @@ export declare class NotificationsNamespace extends Resource {
      * else's id is `404 "Resource not found"` rather than a 401.
      */
     dismiss(id: NotificationId, options?: RequestOptions): Promise<void>;
+    /**
+     * `POST /notifications/unsubscribe` - turns every notification email off
+     * for the account behind `token`: the one-click unsubscribe at the foot of
+     * each notification email.
+     *
+     * Needs no credential; the token is the proof, and it is good for a year
+     * from the email it came in. The inbox itself is untouched, and the emails
+     * come back by turning `emailsEnabled` on again through
+     * `oms.account.notificationPreferences`.
+     *
+     * Throttled like the other anonymous endpoints.
+     *
+     * @throws {OmsApiError} 404 for a token that is invalid or expired.
+     */
+    unsubscribe(token: string, options?: RequestOptions): Promise<NotificationUnsubscribeResult>;
 }

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

@@ -5,7 +5,7 @@ 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"];
+export declare const SERVICE_USAGE_IDS: readonly ["storage", "tools", "games", "music", "movies", "ai", "account", "tickets", "messages", "blogs", "status", "administration", "search"];
 /** One of {@link SERVICE_USAGE_IDS}. */
 export type ServiceUsageId = (typeof SERVICE_USAGE_IDS)[number];
 /**

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

@@ -28,12 +28,14 @@ export * from "./ipLookup";
 export * from "./jobs";
 export * from "./library";
 export * from "./linkTrees";
+export * from "./llm";
 export * from "./media";
 export * from "./movies";
 export * from "./music/index";
 export * from "./notepads";
 export * from "./quotas";
 export * from "./realtime";
+export * from "./search";
 export * from "./shortLinks";
 export * from "./social";
 export * from "./storage";