@mangoc/dsh-sub2api-sync 0.0.0-stage → 0.1.0

package/lib/config.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The plugin's own settings section (`sub2api-sync` namespace): types and the
+ * schemastery schema the host projects into the settings page.
+ *
+ * rev.4 shape (no legacy compatibility — the project has not shipped):
+ * - `selectedKeys` lists the relay keys checked for sync (default `[]` — 全不选);
+ * - one provider route per selected key (`sub2api-<10-hex>` slug over
+ *   instance + key id — no sequential ids in route or credential names),
+ *   written by the card and by the engine's keyId persistence;
+ * - `manualGroups` (hand-declared Mode B groups) is retired — groups come
+ *   from the panel, and platform is read directly from the panel DTO;
+ * - `providerNameTemplate` renders the provider displayName (C5: must keep
+ *   the `{keyName}` or `{siteName}` placeholder);
+ * - `allowRemoteActions` is the cross-device escape hatch (§11 of the
+ *   client-UI design note).
+ *
+ * Since dsh 0.1.7 the `Config` export is auto-projected — there is no
+ * `installSection` registration any more. Every top-level field is marked
+ * `volatile`, which is what makes the entry appear as a settings form at
+ * all: the host keeps each volatile field as a live cell, so a form write
+ * updates the running plugin in place (no remount) and the entry's resolved
+ * config is the single source of truth.
+ *
+ * @module sub2api-sync/config
+ */
+import z from '@deepseek-ai/schemastery';
+import type { ModelTemplate } from './protocols.ts';
+./protocols.jsApiProtocol } from './types.ts';
+/** ./types.jskey-source options; `keyId` absent = 自动（组名建/复用）. */
+export interface Sub2apiSyncConfig {
+    /** sub2api instance address, with or without a trailing `/v1`. */
+    baseURL?: string;
+    /** Panel account email (Mode A, password/2FA channel). */
+    email?: string;
+    /** Provider displayName template; `{keyName}` and `{siteName}` placeholders. Default `{siteName}({keyName})`. */
+    providerNameTemplate?: string;
+    /** Relay keys selected for sync (panel key ids); default `[]` — 全不选. */
+    selectedKeys?: number[];
+    /** Manual model lists when `/v1/models` is unavailable for a group. */
+    modelListOverrides?: Record<string, string[]>;
+    /** Per-group wire-protocol override over the panel platform mapping. */
+    protocolOverrides?: Record<string, ApiProtocol>;
+    /** Registered route → panel key id, written by the engine so the card's
+     * per-route remove button works without a panel round trip (slugs hide
+     * the numeric id by design). */
+    routeKeyIds?: Record<string, number>;
+    /** Per-model template inherited by every synced model entry. */
+    compatTemplate?: ModelTemplate;
+    /** models.dev metadata enrichment toggle (reserved, C4). */
+    enrichModelMeta?: boolean;
+    /** Optional quota (USD) for keys the plugin creates. */
+    keyQuota?: number;
+    /** Optional expiry in days for keys the plugin creates. */
+    keyExpiresInDays?: number;
+    /** Whether removal also revokes the remote key (needs the stored keyId). */
+    deleteOrphanKeys?: boolean;
+    /** Scheduled resync interval; absent = off. */
+    syncIntervalMs?: number;
+    /** Escape hatch: allow action routes from private-network peers (§11). Default false. */
+    allowRemoteActions?: boolean;
+}
+export declare const Config: z<Sub2apiSyncConfig, any>;
+/** The default provider-name template — owned by `types.ts` (browser-safe), re-exported here. */
+export { DEFAULT_PROVIDER_NAME_TEMPLATE } from './types.ts';
+/**
+ * One resolved volatile field:./types.jsreference whose `get()` yields the
+ * current immutable snapshot. Structurally `cosmokit`'s `Volatile<T>`; kept
+ * local so this package need not depend on it.
+ */
+export interface LiveField<T> {
+    get(): T;
+}
+/**
+ * The entry config `apply` receives: every schema field resolves to a live
+ * cell the host swaps in place on each settings-form write. Keep the
+ * reference (re-reading cells per call), never cache a snapshot across a
+ * write boundary.
+ */
+export type ResolvedSub2apiSyncConfig = {
+    [K in keyof Sub2apiSyncConfig]: LiveField<Sub2apiSyncConfig[K]>;
+};
+/** Fold the live entry config into one plain snapshot for a sync run. */
+export declare function readConfig(config: ResolvedSub2apiSyncConfig): Sub2apiSyncConfig;
+/**
+ * Cross-field constraints the schema cannot express. Shape-only on purpose:
+ * reachability needs network I/O and belongs to the sync path, which fails
+ * loudly with the instance named.
+ */
+export declare function validateConfig(config: Sub2apiSyncConfig): void;

package/lib/engine.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The sync engine: diff the panel group state against the plugin's entries
+ * in the settings user layer and apply a minimal write plan to
+ * `llm-pi-ai.providers` through `settings.mutate`.
+ *
+ * rev.4 model: the panel is the single source of groups (id/name/platform),
+ * reached through the credential-backed {@link PanelGateway}. Key sources
+ * per group (three states):
+ * 1. `groups[gid].keyId` set — reuse that exact panel key (persisted by the
+ *    card's "选已有 key" or by a previous auto-creation);
+ * 2. `keyId` unset but a credential exists — pasted key, used verbatim (its
+ *    panel name is matched best-effort for the display name);
+ * 3. neither — auto: reuse the group-named key, else create one named after
+ *    the group, then persist the keyId (rename-proof idempotency).
+ *
+ * Guarantees (per the design Agent Note, carried over):
+ * - idempotent: a second sync with unchanged inputs produces zero writes;
+ * - scoped: only `sub2api-<10-hex>` (and legacy `sub2api-<digits>`) routes
+ *   are ever written or removed;
+ * - optimistic: writes carry `expectedRevision` and a `SettingsConflictError`
+ *   triggers a re-read, a recompute, and a bounded retry (3 attempts);
+ * - single flight: syncs are serialized on one queue;
+ * - loud: every per-group failure lands in the report, whole-sync failures
+ *   throw with context, and nothing writes a half state.
+ *
+ * @module sub2api-sync/engine
+ */
+import type { PanelGateway, PanelKey } from './panel.ts';./panel.jsloadModelIndex } from './enrich.ts'./enrich.jspe { Sub2apiSyncConfig } from './config.ts'./config.jstype CredentialsLike, type SettingsLike } from './types.ts';./types.jsettings namespace owned by dsh-llm-pi-ai. */
+export declare const PI_AI_NS = "llm-pi-ai";
+/** The settings namespace owned by this plugin. */
+export declare const OWN_NS = "sub2api-sync";
+/** Minimal structural view of the settings service the engine needs. */
+export type { SettingsLike, SettingsPathOp } from './types.ts';./types.jsterface SyncEngineOptions {
+    settings: SettingsLike;
+    credentials: CredentialsLike;
+    /** Credential-backed panel gateway (login tokens, single-flight refresh). */
+    gateway: PanelGateway;
+    fetchImpl?: typeof fetch;
+    /** Model-metadata index loader (C4); overridable in tests. */
+    loadModelIndex?: typeof loadModelIndex;
+    /**
+     * The instance's configured site name for the `{siteName}` template
+     * placeholder (cached probe; absent/unknown falls back to "sub2api").
+     */
+    siteName?: () => Promise<string | undefined>;
+}
+export type SyncAction = 'created' | 'updated' | 'unchanged' | 'failed';
+export interface SyncEntryOutcome {
+    groupId: number;
+    route: string;
+    /** The panel key id this entry synced (absent for stale/invalid ids). */
+    keyId?: number;
+    displayName?: string;
+    action: SyncAction;
+    models?: number;
+    error?: string;
+    /** Set when the selected id does not exist in the panel (stale selection). */
+    invalid?: true;
+}
+export interface SyncReport {
+    entries: SyncEntryOutcome[];
+    removed: string[];
+    /** Number of `set`/`unset` ops the accepted mutate carried. */
+    writes: number;
+    /** How many mutate attempts were used (1 = no conflict). */
+    attempts: number;
+    warnings: string[];
+}
+/**
+ * In-memory holder for the last accepted sync report (the status
+ * projection's `lastReport` / `lastReportAt`). The host clears it wherever
+ * the sync state is purged — logout, definitive auth loss, instance
+ * switch — because a report describing routes that no longer exist must
+ * not keep presenting itself as the current state.
+ */
+export interface SyncReportStore {
+    record(report: SyncReport): void;
+    clear(): void;
+    report(): SyncReport | undefined;
+    at(): number | undefined;
+}
+export declare function createSyncReportStore(): SyncReportStore;
+/** Whole-sync failure: bad config, not signed in, llm-pi-ai unavailable, or retries exhausted. */
+export declare class Sub2apiSyncError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve the selected relay keys against the panel's key rows. A selected id
+ * the panel no longer serves becomes an `invalid` entry (reported, not fatal).
+ */
+export declare function resolveTargets(config: Sub2apiSyncConfig, keyRows: readonly PanelKey[]): Array<{
+    key: PanelKey;
+} | {
+    invalid: number;
+    error: string;
+}>;
+export declare class Sub2apiSyncEngine {
+    private readonly settings;
+    private readonly credentials;
+    private readonly gateway;
+    private readonly fetchImpl?;
+    private readonly modelIndexLoader;
+    private readonly siteName?;
+    private queue;
+    private running;
+    constructor(options: SyncEngineOptions);
+    /** Whether a sync is currently executing (UI busy marker). */
+    isRunning(): boolean;
+    /**
+     * Run one sync. At most one runs at a time — later callers queue behind
+     * the previous one (the settings-card button, the tool, and the timer all
+     * share this queue).
+     */
+    sync(config: Sub2apiSyncConfig, keyIds?: number[]): Promise<SyncReport>;
+    private runSync;
+    private syncNow;
+    /** Protocol + models + naming for one selected key; the plaintext comes
+     * from the panel row when present, else from the stored credential. */
+    private buildKeyProfile;
+    /**
+     * Model source precedence: a non-empty `modelListOverrides` entry is the
+     * user's explicit selection from the card picker and wins outright (no
+     * fetch — the entry contains exactly the chosen ids). Otherwise discover
+     * via `/v1/models`; discovery failure falls back to the overrides loudly.
+     */
+    private discoverModels;
+    private readCurrentProviders;
+    private revisionOf;
+}

package/lib/enrich.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Model-metadata enrichment (C4): fills per-model facts the sub2api gateway
+ * never reports — context window, max output tokens, image input, and the
+ * reasoning-effort levels (`reasoning_options` → pi-ai `reasoningEfforts`) —
+ * from the models.dev catalog (https://models.dev/api.json).
+ *
+ * Source chain, in order:
+ * 1. a fresh catalog fetch (only when `enrichModelMeta` is on), cached
+ *    in-process for 24h;
+ * 2. the bundled snapshot `data/models-dev.snapshot.json` (generated by
+ *    `scripts/fetch-models-dev.mjs`, shipped with the package) — the
+ *    deterministic offline fallback;
+ * 3. nothing — the caller keeps its route-level defaults.
+ *
+ * A failed fetch degrades to the bundled snapshot (and is cached as such for
+ * the TTL, so an unreachable models.dev is not hammered on every sync).
+ * Enrichment never fails a sync.
+ *
+ * @module sub2api-sync/enrich
+ */
+/** Per-model capacity facts the enrichment can contribute. */
+export interface ModelMeta {
+    /** Display name for selectors (models.dev `name`), e.g. "Claude Opus 4.5". */
+    name?: string;
+    contextWindow?: number;
+    maxTokens?: number;
+    imageInput?: boolean;
+    reasoningModel?: boolean;
+    /**
+     * pi-ai `reasoningEfforts` map derived from the models.dev `reasoning_options`
+     * effort values: keys are pi-ai thinking levels, values the wire spelling
+     * (same-name passthrough; `none` maps to `off: null` — dispatch sends nothing).
+     * Absent for toggle/budget-only reasoning, whose wire shape is not an effort
+     * string and cannot travel through `reasoningEfforts`.
+     */
+    reasoningEfforts?: Record<string, string | null>;
+}
+/** Model id (lowercase) → metadata. */
+export type ModelMetaIndex = Map<string, ModelMeta>;
+/**
+ * pi-ai's `THINKING_LEVELS` vocabulary (dsh-llm-pi-ai: off/minimal/low/medium/
+ * high/xhigh/max) extended with models.dev's `none` spelling for `off`. models.dev
+ * effort values outside this set cannot travel through `reasoningEfforts` and are
+ * dropped. Canonical order doubles as the output order. Exported for the
+ * snapshot generator script (`scripts/fetch-models-dev.mjs`), which mirrors
+ * {@link parseCatalog}'s efforts transform.
+ */
+export declare const EFFORT_VOCABULARY: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+/**
+ * models.dev provider keys that publish the upstream's own effort surface —
+ * vendor consoles and vendor-governed cloud hosting. Aggregator entries invent
+ * richer vocabularies than the upstream accepts (claude with `xhigh`/`max`,
+ * glm-5.2 with seven levels), and a synced group forwards to the vendor
+ * upstream, so when any first-party entry exists for an id it wins outright and
+ * aggregator effort data is ignored; without one, aggregator sources intersect
+ * (a level every source claims — never more than any one of them offers).
+ * Exported for the snapshot generator script (single source of truth with
+ * {@link parseCatalog}).
+ */
+export declare const FIRST_PARTY_PROVIDERS: Set<string>;
+/**
+ * Normalize one models.dev `name` into a display name: strip the trailing
+ * " (latest)" marker (a models.dev family-latest convention, not part of the
+ * model's name) and reject empty results or names that merely repeat the id —
+ * a display name identical to the id carries no information and the UI keeps
+ * its own placeholder in that case. Exported for the snapshot generator
+ * script (single source of truth with {@link parseCatalog}).
+ */
+export declare function displayNameOf(raw: unknown, id?: string): string | undefined;
+/**
+ * Parse the bundled tuple snapshot:
+ * `{ generatedAt, source, models: { [id]: [context, output, image, reasoning, efforts?, name?] } }`
+ * — the fifth element (optional, 4-tuples predate the efforts enrichment) is the
+ * normalized effort-level array the generator script resolved, the sixth
+ * (optional) the display name.
+ */
+export declare function parseSnapshot(raw: string): ModelMetaIndex;
+/**
+ * Parse the live models.dev catalog: `{ [provider]: { models: { [id]: {
+ * name?, limit?: { context?, output? }, modalities?: { input?: string[] },
+ * attachment?: boolean, reasoning?: boolean, reasoning_options?: Array<{
+ * type: 'effort' | 'toggle' | 'budget_tokens', values?: string[] }> } } } }`.
+ * Capacity facts merge across providers with max/OR; effort levels follow the
+ * first-party preference (see {@link FIRST_PARTY_PROVIDERS}): first-party
+ * sources win outright, otherwise aggregator sources intersect. Display names
+ * also prefer first-party sources (see the tail of this function).
+ */
+export declare function parseCatalog(catalog: unknown): ModelMetaIndex;
+/** The bundled offline snapshot, read once per process. */
+export declare function bundledIndex(): ModelMetaIndex;
+/**
+ * Resolve the index for one sync run. With `enrich` on, a fresh fetch is
+ * attempted and cached for 24h (failures degrade to the bundled snapshot and
+ * are cached for the same TTL so a dead endpoint is not retried per sync);
+ * with `enrich` off, only the bundled snapshot is used — deterministic and
+ * offline.
+ */
+export declare function loadModelIndex(options: {
+    enrich: boolean;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}): Promise<ModelMetaIndex>;
+/** Test/reset hook: forget the in-process caches. */
+export declare function resetCaches(): void;

package/lib/icon.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Instance icon + site-name discovery and the icon byte proxy (host half only).
+ *
+ * The settings card shows the instance's own icon as the identity mark and
+ * its configured site name in the header once signed in. One probe of the
+ * instance root HTML serves both: parse `<link rel="icon">` (sub2api
+ * declares `/logo.svg` there) and `<title>` (sub2api's backend rewrites it
+ * to `{site_name} - AI API Gateway`, so the title carries the operator's
+ * configured site name). Undeclared icons fall back to the `/favicon.ico`
+ * convention. The bytes are proxied through a same-origin plugin route so
+ * the webview never loads cross-origin imagery (no CORS/mixed-content
+ * caveats). A per-instance cache (10 min TTL) keeps repeat polls off the
+ * instance's HTML.
+ *
+ * @module sub2api-sync/icon
+ */
+/** Icon bytes handed to the /icon route (content-type is upstream's or guessed). */
+export interface IconPayload {
+    contentType: string;
+    body: Buffer;
+}
+/**
+ * Extract the first usable icon href from an HTML document. Only the
+ * `<link>` shape is honored (the standard mechanism); `mask-icon` is skipped
+ * (Safari pinned-tab monochrome glyphs make poor avatars), everything else
+ * whose `rel` contains the `icon` word qualifies. Minimal entity decoding
+ * for the one entity HTML attribute values practically carry.
+ */
+export declare function pickIconHref(html: string): string | undefined;
+/**
+ * Extract the site name from an HTML `<title>`: decode the handful of
+ * entities title text practically carries, trim, and strip sub2api's fixed
+ * ` - AI API Gateway` suffix (case-insensitive) to surface the operator's
+ * configured site name. Absent or empty titles yield undefined.
+ */
+export declare function parseSiteTitle(html: string): string | undefined;
+/**
+ * Build the instance probe the route deps expose: `icon` proxies the icon
+ * bytes for the /icon route, `siteName` serves the parsed title for the
+ * /site route. One factory per plugin instance — the meta cache lives in
+ * the closure, so the icon and site-name consumers share one HTML read per
+ * TTL window. Errors never throw — an unavailable answer resolves to
+ * `undefined` and the client keeps its fallbacks.
+ */
+export declare function createInstanceProbe(options?: {
+    fetchImpl?: typeof fetch;
+}): {
+    icon: (instance: string) => Promise<IconPayload | undefined>;
+    siteName: (instance: string) => Promise<string | undefined>;
+};

package/lib/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * sub2api sync plugin — host half.
+ *
+ * rev.4: the panel is the single source of groups. Login channels are
+ * password(+2FA) / OAuth (OAuth routes deferred until the sub2api
+ * side lands); configuration reads/writes ride the platform settings seam
+ * (`configForms` in the browser), so the host routes carry only actions,
+ * secrets, and state projection.
+ *
+ * The settings section needs no registration since dsh 0.1.7: the `Config`
+ * export is auto-projected into the settings page, and every field arrives
+ * here as a live volatile cell (`ResolvedSub2apiSyncConfig`), so the entry's
+ * resolved config is the authoritative source — the loader swaps cell values
+ * in place on each form write and announces them via `loader/volatile-update`.
+ *
+ * @module sub2api-sync
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ResolvedSub2apiSyncConfig } from './co./config.jseclare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * Mirrors `@deepseek-ai/cordis-plugin-loader`'s declaration (not a
+         * dependency here): the loader announces an in-place volatile config
+         * commit for this plugin's entry with the changed field paths.
+         */
+        'loader/volatile-update'(paths: readonly (readonly string[])[]): void;
+    }
+}
+export { Config, validateConfig, DEFAULT_PROVIDER_NAME_TEMPLATE } from './co./config.jsxport { Sub2apiSyncEngine, Sub2apiSyncError, OWN_NS, PI_AI_NS } from './en./engine.jsxport { PanelClient, PanelGateway, PanelError } from './pa./panel.jsxport { buildProviderProfile, baseURLForProtocol, protocolForPlatform, guessPlatformFromModels, renderProviderName, SUB2API_RETRY_POLICY } from './pr./protocols.jsxport { API_PROTOCOLS, PLATFORMS, instanceKey, isOwnedRoute, routeForKey, routeKeyRef, legacyKeyRef, legacyKeyIdOfRoute, panelTokenRef, panelRefreshRef, oauthTokenRef, oauthRefreshRef, panelPasswordRef, parseGroupId, } from './ty./types.jsxport { ROUTES, trustedRequest, callbackLangOf } from './ro./routes.jsxport { OAUTH_CALLBACK_PATH, OAUTH_CLIENT_ID, OAuthAttemptStore, OAuthError, buildAuthorizeUrl, callbackPageHtml, createPkcePair, discoverOAuthEndpoints, exchangeAuthorizationCode, loopbackCallbackOrigin, oauthScopesFor, refreshAccessToken, revokeToken, type CallbackLang, } from './oa./oauth.jsxport declare const name: string;
+export declare const inject: string[];
+export declare function apply(ctx: Context, config: ResolvedSub2apiSyncConfig): void;