@srouterhq/server 0.0.0-stage → 0.9.0

package/dist/services/catalog-sync.d.ts

@@ -0,0 +1,257 @@
+import type { Db } from '../db/types.js';
+import type { Scheduler } from '../lib/scheduler.js';
+export declare const MIN_CATALOG_VERSION = "2026.06.07";
+export type SyncInterval = 'off' | 6 | 12 | 24;
+export declare function getSyncIntervalHours(): SyncInterval;
+export declare function setSyncIntervalHours(interval: SyncInterval): void;
+/**
+ * Localization payload for the client to render.
+ *
+ * Server-side notification text used to be a hardcoded Indonesian string,
+ * which meant every install saw Indonesian regardless of the chosen locale.
+ * Emitters now fill this instead: the client looks up `key` in its own
+ * dictionary and substitutes `vars`, so the bell speaks the user's language
+ * while the server stays the single source of truth for WHAT changed.
+ *
+ * The model names themselves never need translating — they are proper nouns —
+ * so they ride in `SyncNotification.message` (untruncated list, already
+ * elided by the emitter) and only the sentence around them is localized.
+ * Older notifications written before this field existed render displayName
+ * and message verbatim, exactly as they always did.
+ */
+export interface SyncNotificationPayload {
+    key: string;
+    vars?: Record<string, string | number>;
+}
+export interface SyncNotification {
+    id: string;
+    type: 'added' | 'removed' | 'updated' | 'degraded' | 'update_available';
+    modelId: string;
+    displayName: string;
+    platform: string;
+    message: string;
+    /** Structured, localizable content. Absent on notifications written by
+     *  older builds — the client then renders displayName/message verbatim. */
+    data?: SyncNotificationPayload;
+    timestamp: number;
+    read: boolean;
+}
+export declare function getNotifications(): SyncNotification[];
+export declare function addNotifications(notifs: SyncNotification[]): void;
+export declare function markNotificationsRead(): void;
+/**
+ * Settle the update-available reminder once the installed version caught up:
+ * collapse historical duplicates down to the newest row, mark it read (which
+ * un-pins it — it sinks into normal chronological order), and keep it in the
+ * list so the history still shows what happened.
+ */
+export declare function settleUpdateNotifications(): void;
+export declare function unreadNotificationCount(): number;
+/** Remove all notifications of a given type (e.g. 'update_available' after user updates). */
+export declare function removeNotificationsByType(type: SyncNotification['type']): void;
+export declare function catalogBaseUrl(): string;
+interface CatalogQuirk {
+    slug: string;
+    title: string;
+    body: string;
+    severity: 'blocker' | 'warning' | 'info';
+    targets: {
+        platform: string | null;
+        modelGlob: string | null;
+    }[];
+}
+interface CatalogModel {
+    platform: string;
+    modelId: string;
+    displayName: string;
+    intelligenceRank: number;
+    speedRank: number;
+    sizeLabel: string;
+    limits: {
+        rpm: number | null;
+        rpd: number | null;
+        tpm: number | null;
+        tpd: number | null;
+    };
+    monthlyTokenBudget: string | null;
+    contextWindow: number | null;
+    enabled: boolean;
+    supportsVision: boolean;
+    supportsTools: boolean;
+    /** 'text' (default/absent) routes to the chat `models` table; 'image'/'audio'
+     *  route to the separate `media_models` table. */
+    modality?: string;
+    /** Short display note for media models (e.g. "Keyless - up to 1024x1024"). */
+    mediaNote?: string;
+    /** Adapter request flavor for media rows, where one platform hosts more than
+     *  one deployment style (cloudflare images: absent/'json' = JSON body,
+     *  'multipart' = form-data, which the FLUX.2 family requires). Mirrors the
+     *  same field on CatalogTranscriptionModel and lands in meta_json. */
+    requestStyle?: string | null;
+}
+interface CatalogEmbedding {
+    family: string;
+    platform: string;
+    modelId: string;
+    displayName: string;
+    dimensions: number;
+    maxInputTokens: number | null;
+    priority: number;
+    enabled: boolean;
+    quotaLabel: string;
+}
+interface CatalogTranscriptionModel {
+    platform: string;
+    modelId: string;
+    displayName: string;
+    /** Failover order within the STT chain, lower first. */
+    priority: number;
+    enabled: boolean;
+    /** Subtitle formats the provider returns natively (e.g. ['vtt']). */
+    subtitleFormats?: string[];
+    /** Provider upload ceiling in bytes; absent = the route-wide 25 MB cap. */
+    maxBytes?: number | null;
+    /** Adapter request flavor where one platform hosts more than one deployment
+     *  style (cloudflare: 'json' = base64 JSON body, 'binary' = raw bytes). */
+    requestStyle?: string | null;
+    /** Short display note, mirrored into media_models.quota_label. */
+    quotaLabel?: string;
+}
+interface CatalogVideoModel {
+    platform: string;
+    modelId: string;
+    displayName: string;
+    /** Failover order within the video chain, lower first. */
+    priority: number;
+    enabled: boolean;
+    /** Short display note, mirrored into media_models.quota_label. */
+    quotaLabel?: string;
+    /** Provider-native deployment id when it differs from the public model id
+     *  (for example Hugging Face's fal.ai mapping). */
+    providerModelId?: string;
+}
+interface Catalog {
+    version: string;
+    generatedAt: string;
+    tier: 'live' | 'monthly';
+    models: CatalogModel[];
+    /** Optional for backward compatibility with catalogs published before the
+     * embedding registry joined the signed freshness feed. */
+    embeddings?: CatalogEmbedding[];
+    /** Speech-to-text registry, landing in media_models with
+     * modality='transcription'. Deliberately a NEW top-level key rather than
+     * more `models` entries: deployed binaries that predate the transcription
+     * modality would ingest unknown-modality `models` entries as CHAT models,
+     * while an unknown optional key is simply ignored by their isCatalog. */
+    transcriptionModels?: CatalogTranscriptionModel[];
+    /** Text-to-video registry. Kept out of `models` so pre-video binaries ignore
+     *  it rather than routing unknown-modality rows through chat. */
+    videoModels?: CatalogVideoModel[];
+    /** Platforms the catalog service manages even when this tier ships no rows
+     *  for them (#1348): a provider still inside its Premium window, or one the
+     *  audit deliberately keeps at zero rows. Names only, never model rows, so
+     *  the monthly snapshot can carry it without leaking Premium models. Any
+     *  platform listed here is off limits to built-in model discovery. Optional:
+     *  older catalogs omit it and older binaries ignore it. */
+    managedPlatforms?: string[];
+    quirks: CatalogQuirk[];
+}
+export interface SyncResult {
+    ok: boolean;
+    action: 'applied' | 'up_to_date' | 'skipped_older' | 'error';
+    version?: string;
+    tier?: string;
+    detail?: string;
+    counts?: {
+        updated: number;
+        inserted: number;
+        removed: number;
+        skippedUnknownPlatform: number;
+        quirks: number;
+    };
+    /** Platform → the models that changed, so the bell can name the provider
+     *  and the exact models instead of a bare "12 models added". */
+    details?: CatalogChangeDetails;
+}
+/** Per-platform model change ledger produced by applyCatalog. */
+export interface CatalogChangeDetails {
+    added: Map<string, string[]>;
+    removed: Map<string, string[]>;
+    updated: Map<string, string[]>;
+}
+/**
+ * Apply a verified catalog to the local DB inside one transaction.
+ *
+ * Rules of engagement with user data:
+ *  - metadata (name, ranks, limits, context, capabilities) tracks the catalog
+ *    unless the user has an explicit local override;
+ *  - catalog enabled=false force-disables (the model is dead upstream), but
+ *    enabled=true never re-enables a model the user turned off themselves;
+ *  - rows the user created (models.source = 'user': custom providers,
+ *    declarative config, admin adds) are never updated, never deleted, and
+ *    never adopted — on a platform:model_id collision the user row wins and
+ *    the catalog entry is skipped outright;
+ *  - catalog models the user deleted stay deleted via tombstones, while models
+ *    auto-retired from an upstream 410/end-of-life response (#634) are only
+ *    disabled — a catalog that still lists them lifts the retirement;
+ *  - models that vanished from the catalog are deleted, exactly like the
+ *    dead-model migrations do (fallback_config row first, FK order);
+ *  - rows found by built-in model discovery (models.source = 'discovered',
+ *    #1348) are a stopgap for platforms the catalog does not manage. The
+ *    catalog outranks them: a listed platform:model_id adopts the discovered
+ *    row as a catalog row, and once the catalog manages a platform at all,
+ *    every other discovered row on it is retired.
+ */
+/** models.source for rows written by built-in model discovery (#1348). */
+export declare const DISCOVERED_MODEL_SOURCE = "discovered";
+/**
+ * Platforms the catalog applied on this install manages (see catalogPlatforms),
+ * read from the cached verified document. Empty when no catalog has been
+ * applied yet. Built-in model discovery treats every platform in here as off
+ * limits, so the audited catalog, not an upstream /models list, decides what
+ * those providers serve.
+ */
+export declare function appliedCatalogPlatforms(db: Db): Set<string>;
+export declare function applyCatalog(db: Db, catalog: Catalog): NonNullable<SyncResult['counts']>;
+/** Same apply, but also returns the per-platform ledger of which models
+ *  changed — what feeds the "3 models added on Groq" bell notifications.
+ *  Counts alone cannot name a provider or a model. */
+export declare function applyCatalogDetailed(db: Db, catalog: Catalog): {
+    counts: NonNullable<SyncResult['counts']>;
+    details: CatalogChangeDetails;
+};
+export declare function syncCatalog(force?: boolean): Promise<SyncResult>;
+export interface CatalogSyncState {
+    baseUrl: string;
+    appliedVersion: string | null;
+    appliedTier: string | null;
+    lastSyncMs: number | null;
+    lastError: string | null;
+}
+export declare function getSyncState(): CatalogSyncState;
+/**
+ * Re-apply the cached (already signature-verified) catalog after boot.
+ *
+ * Migrations run on every boot and re-assert the bundled baseline — they
+ * INSERT OR IGNORE baseline models the catalog may have deleted and re-run
+ * the family-rule resets — while the boot-time network sync 304s on an
+ * unchanged version and so would NOT re-apply. Without this step every
+ * restart drifts the DB back toward the baseline until the next catalog
+ * version bump. Re-applying from the local cache is synchronous, needs no
+ * network, and keeps the catalog authoritative even offline.
+ *
+ * Legacy upgrade path: installs that applied a catalog before the cache
+ * existed have an applied-version setting but no cached document. Clearing
+ * the applied version makes the next poll fetch the full catalog (no `since`
+ * short-circuit), which re-applies it and populates the cache.
+ */
+export declare function reapplyCachedCatalog(): {
+    reapplied: boolean;
+    version?: string;
+};
+export declare function startCatalogSync(scheduler: Scheduler): void;
+export declare function stopCatalogSync(): void;
+/** Call after changing the schedule setting to restart the polling timer. */
+export declare function updateSyncSchedule(): void;
+export {};
+//# sourceMappingURL=catalog-sync.d.ts.map

package/dist/services/catalog-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-sync.d.ts","sourceRoot":"","sources":["../../src/services/catalog-sync.ts"],"names":[],"mappings":"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"}