@skaile/forge-settings 0.0.0-stage → 1.0.0

package/dist/runtime/vue/useProvidersPanel.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Shared brain for `components-nuxt-ui/ForgeProvidersPanel.vue` — the settings
+ * modal's Providers tab.
+ *
+ * It drives the registry editor: loading, the add/edit form, the delete confirmation,
+ * the "detected in environment" one-click adds, the per-row credential picker,
+ * the enabled toggle and every request live here.
+ *
+ * The panel writes one registry document — the scope's own `layer` — through
+ * `PUT|DELETE ${providersWriteUrl}/:id`. An entry a lower layer defines can be
+ * patched at workspace scope (`credential` / `enabled` only) and reset by
+ * deleting the patch. A key typed into the panel goes to the scope's `.env`
+ * route only; the provider route receives an `env:NAME` reference, never a
+ * value.
+ */
+import { type ComputedRef, type Ref, type WritableComputedRef } from "vue";
+import { type EnvLayerId, type EnvSettingsDocument } from "../shared/env-vars.js";
+import { type AIProviderCredentialKind, type AIProviderKind, type AIProviderSurface } from "../shared/provider-registry.js";
+/** Registry document a provider entry is defined in. */
+export type ProvidersPanelLayer = "instance" | "workspace";
+/** Props both `ForgeProvidersPanel` variants declare. */
+export interface ProvidersPanelProps {
+    /** `GET` merged view for this scope (`/api/providers` | `/api/workspaces/:id/providers`). */
+    providersUrl: string;
+    /** `PUT|DELETE ${providersWriteUrl}/:id`; `GET ${providersWriteUrl}/detected`. */
+    providersWriteUrl: string;
+    /** Catalog preset summaries. Default `/api/providers/presets`. */
+    presetsUrl?: string;
+    /**
+     * The scope's `.env` route. `GET` on load and after every write; keys typed
+     * into the panel write through it. Omitted, no key can be entered.
+     */
+    environmentUrl?: string;
+    /** The scope's own registry document. */
+    layer: ProvidersPanelLayer;
+    /** Disables every write (non-admin at instance scope; provider lock). */
+    readOnly?: boolean;
+}
+/** Emits both variants declare. */
+export type ProvidersPanelEmit = (event: "changed") => void;
+/** One entry of `GET ${providersUrl}?all=1`. */
+export interface ProvidersPanelEntry {
+    id: string;
+    /** The entry's label, else its id. */
+    name: string;
+    kind: AIProviderKind;
+    /** Whether the credential reference resolved on the server. */
+    configured: boolean;
+    /** Why it did not resolve. Secret-free. */
+    error?: string;
+    credentialRef?: string;
+    credentialKind?: AIProviderCredentialKind;
+    hasEnvKey: boolean;
+    envKeyName?: string;
+    baseUrl?: string;
+    preset?: string;
+    surface?: AIProviderSurface;
+    enabled: boolean;
+    locked: boolean;
+    /** Registry documents holding the id, lowest first: `["instance"]`, `["workspace"]` or both. */
+    layers: ProvidersPanelLayer[];
+    /** The scope's own document's values for the editable fields the dialog does not show. */
+    layerFields?: Record<string, unknown>;
+}
+/** One catalog preset, as `GET /api/providers/presets` and `.../detected` list it. */
+export interface ProvidersPanelPreset {
+    id: string;
+    label: string;
+    kind: AIProviderKind;
+    surface?: AIProviderSurface;
+    base_url?: string;
+    base_url_env?: string;
+    credential: {
+        kind: AIProviderCredentialKind;
+        env?: string;
+    };
+}
+/** Where a row's entry lives relative to the scope's own document. */
+export type ProvidersPanelRowState = "own" | "inherited" | "patched";
+/** One entry of a row's credential select. */
+export interface ProvidersPanelCredentialOption {
+    /** An env var NAME, a literal non-env ref, {@link CREDENTIAL_ENTER_KEY} or {@link CREDENTIAL_OTHER_REF}. */
+    value: string;
+    /** `NAME ••••hint` | `NAME (not set)` | the literal ref | `Enter a key…` | `Other reference…`. */
+    label: string;
+    defined?: boolean;
+    hint?: string;
+    source?: EnvLayerId;
+    action?: "enter-key" | "other-ref";
+}
+/** A table row: the entry plus what the panel derives for it. */
+export interface ProvidersPanelRow extends ProvidersPanelEntry {
+    /** Own entry, an inherited one, or an inherited one this scope patched. */
+    state: ProvidersPanelRowState;
+    /** `instance` | `workspace` | `instance · overridden here`. */
+    badge: string;
+    /** Set on inherited rows. */
+    inheritedNote?: string;
+    /** Edit/Delete offered: the scope's document defines it and the panel is writable. */
+    editable: boolean;
+    /** Reset offered: a patched row of a writable panel. */
+    canReset: boolean;
+    /** The enabled switch is live. */
+    canToggle: boolean;
+    /** The entry takes a credential (its kind is not `none`). */
+    needsCredential: boolean;
+    /** The credential picker is live. */
+    canEditCredential: boolean;
+    /** The select's model: the env var NAME of an `env:` ref, else the literal ref, else `""`. */
+    credentialValue: string;
+    credentialOptions: ProvidersPanelCredentialOption[];
+    /** The preset it inherits, else its surface, else its kind. */
+    origin: string;
+    /** `configured · <source>`, `missing <VAR>`, the resolver's reason, or `No credential needed.`. */
+    status: string;
+    /** Which other layer defines or overrides the credential; see the panel contract. */
+    overrideNotices: string[];
+}
+/** The add/edit dialog's fields. */
+export interface ProvidersPanelForm {
+    /** A preset id, or {@link CUSTOM_PRESET}. */
+    preset: string;
+    id: string;
+    /** Custom entries only. */
+    surface: string;
+    /** Empty: the preset's endpoint. */
+    baseUrl: string;
+    /** Adding only: the `env:` variable the credential references. */
+    envName: string;
+    /** Adding only, "Set value now": written to the scope's `.env`, never to the provider route. */
+    secret: string;
+}
+/** The preset select's value for an entry that names no preset. */
+export declare const CUSTOM_PRESET = "__custom__";
+/** Credential select value: open the inline key editor. */
+export declare const CREDENTIAL_ENTER_KEY = "__enter_key__";
+/** Credential select value: open the inline reference editor. */
+export declare const CREDENTIAL_OTHER_REF = "__other_ref__";
+/** What both `ForgeProvidersPanel` variants bind to. */
+export interface ProvidersPanelState {
+    /** The scope's entries, disabled ones included, in registry order. */
+    rows: ComputedRef<ProvidersPanelRow[]>;
+    loading: Ref<boolean>;
+    loadError: Ref<string | null>;
+    /** Re-read the entries, the detected presets and the environment document. */
+    refresh: () => Promise<void>;
+    dialogVisible: Ref<boolean>;
+    dialogTitle: ComputedRef<string>;
+    /** The row being edited; `null` while adding. */
+    editing: Ref<ProvidersPanelEntry | null>;
+    form: ProvidersPanelForm;
+    /** A refusal from the form check or either request, shown in the dialog. */
+    dialogError: Ref<string | null>;
+    saving: Ref<boolean>;
+    /** Catalog presets plus "Custom" ({@link CUSTOM_PRESET}). */
+    presetOptions: ComputedRef<Array<{
+        label: string;
+        value: string;
+    }>>;
+    surfaceOptions: Array<{
+        label: string;
+        value: AIProviderSurface;
+    }>;
+    isCustom: ComputedRef<boolean>;
+    /** The surface select is shown: a custom `llm`/`embed` entry. */
+    showSurface: ComputedRef<boolean>;
+    baseUrlPlaceholder: ComputedRef<string>;
+    /** "Set value now" is offered: the scope has an `.env` route. */
+    canSetValue: ComputedRef<boolean>;
+    /** The dialog shows the env name and secret fields: adding, not editing. */
+    showCredentialFields: ComputedRef<boolean>;
+    idError: ComputedRef<string | null>;
+    openAdd: (presetId?: string) => void;
+    openEdit: (row: ProvidersPanelEntry) => void;
+    selectPreset: (value: string) => void;
+    saveProvider: () => Promise<void>;
+    deleteTarget: Ref<ProvidersPanelEntry | null>;
+    /** The confirmation dialog's `v-model`; closing it cancels. */
+    deleteOpen: WritableComputedRef<boolean>;
+    deleteError: Ref<string | null>;
+    deleting: Ref<boolean>;
+    requestDelete: (row: ProvidersPanelEntry) => void;
+    confirmDelete: () => Promise<void>;
+    /** Presets whose key is set in the scope's env and that no entry names. */
+    detected: Ref<ProvidersPanelPreset[]>;
+    /** Preset id whose one-click add is in flight. */
+    detectedBusy: Ref<string | null>;
+    detectedError: Ref<string | null>;
+    addDetected: (preset: ProvidersPanelPreset) => Promise<void>;
+    /** The credential select's `@update`: a NAME writes, the two actions open an editor. */
+    onCredentialSelect: (row: ProvidersPanelRow, value: string) => void;
+    setCredentialEnv: (row: ProvidersPanelRow, name: string) => Promise<void>;
+    setEnabled: (row: ProvidersPanelRow, enabled: boolean) => Promise<void>;
+    /** Delete the workspace patch of an inherited entry. */
+    resetPatch: (row: ProvidersPanelRow) => Promise<void>;
+    /** Row id with a write in flight. */
+    rowBusy: Ref<string | null>;
+    rowError: Ref<{
+        id: string;
+        message: string;
+    } | null>;
+    /** "Enter a key…" is offered: the scope has an editable `.env` route. */
+    canEnterKey: ComputedRef<boolean>;
+    /** Row id whose key editor is open. */
+    keyEditing: Ref<string | null>;
+    keyForm: {
+        name: string;
+        value: string;
+    };
+    keyError: Ref<string | null>;
+    openKeyEditor: (row: ProvidersPanelRow) => void;
+    cancelKeyEditor: () => void;
+    saveKeyEditor: () => Promise<void>;
+    /** Row id whose reference editor is open. */
+    refEditing: Ref<string | null>;
+    refForm: {
+        ref: string;
+    };
+    refError: Ref<string | null>;
+    openRefEditor: (row: ProvidersPanelRow) => void;
+    cancelRefEditor: () => void;
+    saveRefEditor: () => Promise<void>;
+    envDocument: Ref<EnvSettingsDocument | null>;
+    /** The environment document says the caller may write its layer. */
+    envEditable: ComputedRef<boolean>;
+    /** Draft new values per variable name. */
+    envValues: Record<string, string>;
+    envError: Ref<string | null>;
+    envBusy: Ref<boolean>;
+    setEnvValue: (name: string) => Promise<void>;
+}
+export declare function useProvidersPanel(props: ProvidersPanelProps, emit: ProvidersPanelEmit): ProvidersPanelState;