@linxin666/dsh-usage 0.4.9 → 0.4.11

package/lib/types/client/settings-form.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Form model behind the plugin settings card. Every control applies itself:
+ * a pick (a segment, a select option, a reset) writes the moment it is made,
+ * and typed text writes once typing pauses or the reader leaves the field.
+ * Between the edit and the write the edit is held here as a draft, so what is
+ * on screen is exactly what the write will store; a write the Host refuses
+ * puts a pick back to the stored value and keeps typed text for correcting.
+ * Family-shared slice inlined into each plugin's client bundle.
+ */
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+/** The write one field's draft text performs when it is applied. */
+export type FieldWrite = {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'clear';
+};
+/** How one field converts between its stored value and its draft text. */
+export interface FieldSpec {
+    /** Field name inside the namespace section. */
+    field: string;
+    /**
+     * How the reader enters a value, which decides when it is written: a `pick`
+     * is a whole value at once and applies immediately; `type` is text arriving
+     * a keystroke at a time and applies once typing pauses or the field is left.
+     */
+    entry: 'pick' | 'type';
+    /**
+     * Whether the Host treats this field as a secret and redacts its value from
+     * the read-back (role('secret') in the section schema). Redacted secrets are
+     * never compared against the draft on save: the Host strips them from every
+     * wire view layer, so the settled snapshot carries nothing to read back. A
+     * staged secret set is judged by the mutation settling; the rest of its
+     * batch, when one exists, is still judged by read-back, and the atomic
+     * mutation lands every write or none.
+     */
+    secret?: boolean;
+    /** Render a stored value as draft text; the empty string when the section carries none. */
+    format: (value: unknown) => string;
+    /**
+     * The write this draft text performs, or undefined when the text is not a
+     * value this field accepts — which holds the draft unwritten rather than
+     * discarding it.
+     */
+    parse: (text: string) => FieldWrite | undefined;
+}
+/** One field as the card renders it. */
+export interface FieldState {
+    /** Draft text the control renders. */
+    text: string;
+    /** Whether the field leaves (or will leave) a user-layer entry. */
+    overridden: boolean;
+    /** Whether the draft is not a value this field accepts, which holds it unwritten. */
+    invalid: boolean;
+}
+/** Form state every plugin settings card shares. */
+export interface CardShell {
+    /** False while the namespace is still loading; the card renders nothing. */
+    available: boolean;
+    /**
+     * Whether the namespace is actually served to this client. False when the
+     * Host deployment does not expose it (e.g. the owning plugin's settings
+     * domain is not mounted): the card renders an explanation
+     * instead of its form, so a missing namespace never looks like a missing
+     * plugin.
+     */
+    exposed: boolean;
+    /** Whether the Host document accepts writes. */
+    writable: boolean;
+    /** Whether the form holds drafts not yet written (typed text waiting for its pause). */
+    dirty: boolean;
+    /** Whether any draft is invalid, which holds it unwritten. */
+    invalid: boolean;
+    /** Whether a write is crossing the wire. */
+    saving: boolean;
+    /** Whether the last write did not land; cleared by the next edit or write. */
+    failed: boolean;
+    /**
+     * The rejection code/message the Host returned for the last failed save,
+     * surfaced next to the generic failure text. Undefined while no save has
+     * failed (or the failure carried no server reason).
+     */
+    failedReason?: string;
+}
+/** The write actions the card's slot entry injects. */
+export interface CardActions {
+    /** Take draft text for one field; a pick writes at once, typed text after a pause. */
+    edit: (field: string, text: string) => void;
+    /** Clear one field at once, so it re-inherits the composition layer. */
+    resetField: (field: string) => void;
+    /** Write every pending draft now (a text field's Enter or blur), then re-seed from what the Host accepted. */
+    save: () => void;
+    /** Drop every pending draft, putting each control back to the stored value (a text field's Escape). */
+    discard: () => void;
+}
+/** How long typed text rests before it is written. */
+export declare const TYPE_PAUSE_MS = 600;
+/** One durable write inside the save's atomic form mutation. */
+export interface BatchedWrite {
+    /** Field this entry writes. */
+    field: string;
+    /** set stores a value; unset drops the leaf. */
+    op: 'set' | 'unset';
+    /** Value for op set (absent for unset). */
+    value?: unknown;
+}
+/** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
+export interface NumberConstraints {
+    /** The accepted value must be a whole number. */
+    integer?: boolean;
+    /** The accepted value must be at least this. */
+    min?: number;
+}
+/** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints stays unwritten. */
+export declare function numberField(field: string, constraints?: NumberConstraints): FieldSpec;
+/**
+ * A free-text field. An empty draft clears the field. `entry` is `pick` when
+ * the text arrives whole from a picker (a preset or a reasoning level).
+ */
+export declare function textField(field: string, entry?: FieldSpec['entry']): FieldSpec;
+/**
+ * A free-text field the Host treats as a secret and redacts from the read-back
+ * (role('secret') in the section schema). The card still edits it like text,
+ * but a save never compares the redacted value back: the staged set is judged
+ * by the mutation settling (see {@link FieldSpec.secret}).
+ */
+export declare function secretField(field: string): FieldSpec;
+/** A boolean field, edited through true/false draft text. */
+export declare function booleanField(field: string): FieldSpec;
+/** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
+export declare function choiceField(field: string, choices: readonly string[]): FieldSpec;
+/**
+ * Applies one card's edits to one settings namespace as the reader makes them.
+ *
+ * The Host is the only authority on whether a value was accepted — its
+ * validators own the constraints no schema can express — so the outcome is
+ * read back from the section rather than predicted here. A write that did not
+ * land puts each pick back to the stored value, the way a switch that could not
+ * flip springs back, and keeps typed text so the reader can correct it instead
+ * of retyping.
+ */
+export declare class CardForm<T> {
+    private readonly scope;
+    private readonly specs;
+    private readonly staged;
+    private readonly listeners;
+    /** The form subscription installed in the constructor; released by dispose(). */
+    private readonly disposeForm;
+    private disposed;
+    /** The pending write of typed text, waiting for typing to pause. */
+    private typePause;
+    private saving;
+    /** A save asked for while one was in flight; it runs once the first settles (#1754). */
+    private saveQueued;
+    private failed;
+    private failedReason;
+    /** @param scope - the bound configuration form for this card's namespace. */
+    constructor(scope: ConfigForm<T>, specs: FieldSpec[]);
+    /**
+     * Release the form subscription and every bound store listener. The card
+     * must call this on teardown; later calls are no-ops.
+     */
+    dispose(): void;
+    /** Publish a projection of this form, rebuilt whenever the form or a draft changes. */
+    bind<S>(project: () => S): SnapshotStore<S>;
+    /** Read the card-level state: what the Host serves, and what is still waiting to be written. */
+    shell(): CardShell;
+    /** Read one field's state from the effective section and its staged draft. */
+    field(field: string): FieldState;
+    /** The actions the card's slot registration injects. */
+    actions(): CardActions;
+    /**
+     * Run one write, and re-run it once if another was asked for while this one
+     * was still in flight.
+     *
+     * A write is a Host round trip that also drives the profile reconcile, and
+     * the Host runs it inside one exclusive transaction. Answering an edit that
+     * arrives mid-flight by returning immediately dropped it with no explanation
+     * (#1754). Serializing instead means an edit made while another write is
+     * still settling is written against the settled state.
+     * @returns settlement after the mutation and the read-back.
+     */
+    requestSave(): Promise<void>;
+    /**
+     * Write every valid draft in one atomic form mutation, then re-seed from
+     * what the Host accepted. A draft the field does not accept stays on screen,
+     * unwritten, without holding the others back.
+     *
+     * The batch rides one mutate, so cross-field validate hooks (baseURL+model)
+     * judge it as a unit: the Host either applies every write or refuses the
+     * batch. The form contract answers a refusal or a skipped write with `false`
+     * (it recovers with a fresh Host view instead of throwing), so the outcome is
+     * judged twice: the answer itself, and then the settled snapshot read back
+     * one planned write at a time. One missed write fails the whole batch. A
+     * transport that rejects instead (the dsh-web bridge controller on a dead
+     * connection) reports through the same failure path with its rejection
+     * message. A batch that did not land puts its picks and clears back to the
+     * stored value and keeps its typed text, so the reader can correct it.
+     * @returns settlement after the mutation and the read-back.
+     */
+    save(): Promise<void>;
+    /**
+     * Every staged edit a write would carry. An entry whose draft is not a value
+     * its field accepts carries no write: the form is still dirty, and the draft
+     * stays on screen rather than being dropped. A staged edit that matches the
+     * effective section is not a write at all.
+     * @returns the planned writes, in the order the fields were staged.
+     */
+    private plan;
+    /**
+     * Read-back judgment for a planned set: the user layer must hold the
+     * intended value once the mutation has settled.
+     */
+    private landedSet;
+    /**
+     * Read-back judgment for a planned unset: the field must be gone from the
+     * user layer once the mutation has settled.
+     */
+    private landedUnset;
+    /**
+     * Take one edit and schedule its write: a pick or a clear is written now,
+     * typed text once typing has rested for TYPE_PAUSE_MS.
+     */
+    private stage;
+    /** Write every pending draft now, taking the place of a waiting pause. */
+    private applyNow;
+    private specOf;
+    private snapshotOf;
+    private sectionValue;
+    private baseValue;
+    private userLayer;
+    private stored;
+    private publish;
+}

package/lib/types/client/usage-settings-card.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The usage page's settings card: the plugin switch and the three display
+ * rows, written through the family card form so a pick lands at once and a
+ * typed value after a pause, exactly as the other Web Extensions pages do.
+ * @module @linxin666/dsh-usage/client/usage-settings-card
+ */
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import { type CardActions, type CardShell, type FieldState } from './settings-form.ts';
+/** The settings fields this page edits (the namespace's own schema). */
+export interface UsageSettings {
+    enabled?: boolean;
+    pollIntervalSec?: number;
+    /** Currency the spend figures are displayed in; the ledger stays CNY. */
+    spendCurrency?: 'CNY' | 'USD';
+    /** CNY per USD, consulted only while the display currency is USD. */
+    cnyPerUsd?: number;
+}
+/** The display currencies the spend figures offer. */
+export declare const SPEND_CURRENCIES: readonly ["CNY", "USD"];
+/** Bounds of the poll interval, mirroring the host schema; the slider walks them in steps of 10 s. */
+export declare const POLL_INTERVAL_RANGE: {
+    min: number;
+    max: number;
+    step: number;
+};
+/** What the settings card renders. */
+export interface UsageSettingsCardState extends CardShell {
+    enabled: FieldState;
+    pollIntervalSec: FieldState;
+    spendCurrency: FieldState;
+    cnyPerUsd: FieldState;
+}
+/** The card's snapshot and its form actions, as the section receives them. */
+export interface UsageSettingsCardFace extends CardActions {
+    store: SnapshotStore<UsageSettingsCardState>;
+}
+/** Bridges the usage namespace onto the family card form for the plugin's lifetime. */
+export declare class UsageSettingsCardController {
+    private readonly form;
+    private readonly store;
+    /** @param scope - the bound configuration form of the usage namespace. */
+    constructor(scope: ConfigForm<UsageSettings>);
+    /** The face the section's slot entry injects. */
+    inject(): UsageSettingsCardFace;
+    /** Release the form subscription; the plugin disposer calls this on teardown. */
+    dispose(): void;
+}

package/lib/types/client/web-extension-page.d.ts

@@ -0,0 +1,50 @@
+/**
+ * One settings page's seat in either the Web Extensions parent or the legacy
+ * first-level settings navigation.
+ *
+ * The parent supplies the page contract; a child does not know which slot the
+ * parent uses internally. While `webUiExtensions` is live the page is handed
+ * to its service, which owns keyed mounting and disposal. Without the parent,
+ * the same component registers as its original first-level settings section,
+ * so a standalone install keeps a working entry.
+ */
+/** The parent service face this helper consumes. */
+export interface WebExtensionPageService {
+    readonly sectionId: string;
+    registerPage(page: WebExtensionPageSeat): () => void;
+}
+/** Seat-independent page contribution. */
+export interface WebExtensionPageSeat {
+    key: string;
+    order: number;
+    locale: string;
+    label(): string;
+    inject(): object;
+    component: unknown;
+    children?: Record<string, {
+        kind: 'keyed' | 'list';
+        scope: 'root';
+    }>;
+}
+/** The slot-registry slice used for the standalone fallback. */
+export interface WebExtensionPageSlots {
+    register(options: never, component: never): unknown;
+    spec?(key: string): unknown;
+    entries?(key: string): readonly {
+        component?: unknown;
+        options: Record<string, unknown>;
+    }[];
+}
+/** The context slice needed by the migration. */
+export interface WebExtensionPageContext {
+    slots: WebExtensionPageSlots;
+    get?(name: string): unknown;
+    on?(event: string, listener: () => void): unknown;
+}
+/**
+ * Keep exactly one reachable page contribution while the parent loads or
+ * unloads. The parent service owns integrated mounting; only the fallback uses
+ * this plugin's own slot registry. Slot disposal is synchronous, so the latch
+ * prevents a move from recursively registering a duplicate.
+ */
+export declare function installWebExtensionPage(ctx: WebExtensionPageContext, page: WebExtensionPageSeat): () => void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-usage",
   "description": "Usage statistics plugin for the dsh web GUI: per-provider balance and coding-plan quota detection plus a live token usage ledger, with a compact price glance card above the sidebar's Settings row",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "icon": "icon.svg",
   "type": "module",
   "engines": {