@undefineds.co/xpod 0.4.11 → 0.4.12

package/node_modules/@undefineds.co/ai-connections/dist/collections.d.ts

@@ -0,0 +1,119 @@
+import { credentialDescriptor } from '@undefineds.co/models';
+import type { PodCollection, RowOf } from '@undefineds.co/pod-collections';
+import type { AiConnectionsProvider, AiProviderCredentialSummary, AiProviderSummary } from './ai-connections-client';
+/**
+ * The credentials table, declared once (`docs/pod-collections.md` §6.4-2).
+ *
+ * This module is the *shape* of the table and everything that can be computed
+ * from a row without the collection layer: the row type, the projection of a row
+ * into the summary the page renders, and the enrichment carriers. Nothing here
+ * imports `@undefineds.co/pod-collections` at runtime - the row type is a type,
+ * and the two things that do need the layer (declaring the table, reading and
+ * writing its rows) live in `./collection-runtime`, which is reached through the
+ * dynamic import below. That is what keeps the engine out of the settings
+ * entry's chunk and out of any page that renders without live rows (§9-9).
+ *
+ * The one read the page does here, `useCredentialRows`, is a `useSyncExternalStore`
+ * subscription to a rows source (the controller's live snapshot of the
+ * collection). It is deliberately not `@tanstack/react-db`'s `useLiveQuery`: the
+ * page needs "all rows of one table, once its first read landed", which the
+ * collection's own change feed answers, and loading a hook lazily would force
+ * the whole panel to remount when the chunk arrived. The design doc names this
+ * exit explicitly (§7.4-4, §8.7-5: engine only, no react hook).
+ *
+ * ## What the collection can carry, and what it cannot (yet)
+ *
+ * Rows are the descriptor's projection: `id`, `service`, `provider`, `label`,
+ * `accountLabel`, `authMode`, `status`, `keyVersion`, `expiresAt`,
+ * `reauthRequired`, … The known schema drift (locked by
+ * `packages/pod-collections/test/guards.test.ts`) means `offeringId`,
+ * `metadata`, `baseUrl` and `proxyUrl` are **not** projectable, and `secret`
+ * fields are not projected however they are written. So
+ *
+ * - reading carries the undeclared attributes over from the store's own summary
+ *   of the same row (`credentialCarriers`), and
+ * - writing hands them to the store (`AiConnectionsPodStore`), which owns those
+ *   columns and the secret envelope.
+ *
+ * Both are migration-window behaviour. models 0.2.57 now declares all four, so
+ * their delete condition is formally met, but they stay until the descriptor
+ * projection work (P4) retires the carrier path as a whole - removing them one
+ * at a time would leave reads and writes disagreeing in between.
+ */
+/** A credentials-table row as the collection projects it. */
+export type CredentialRow = RowOf<typeof credentialDescriptor>;
+/** The collection's `syncState` is the page's availability signal. */
+export interface CredentialCollection {
+    readonly collection: PodCollection<CredentialRow>;
+}
+/**
+ * A live rows source: the controller's snapshot of the credentials collection.
+ *
+ * `credentialRows` is `undefined` until the collection's first read lands - and
+ * stays `undefined` while the collection layer is still loading, when the host
+ * offers no `podCollections` capability, or after a failed first read. The page
+ * keeps its store-backed rendering in every one of those states.
+ */
+export interface CredentialRowsSource {
+    subscribe(listener: () => void): () => void;
+    readonly credentialRows?: readonly CredentialRow[];
+}
+/**
+ * Live rows for the credentials table. Re-renders on sync and on optimistic
+ * writes, because the source is the collection's own change feed.
+ */
+export declare function useCredentialRows(source: CredentialRowsSource): readonly CredentialRow[] | undefined;
+/** The lazy half of this module's subject: everything that needs the engine. */
+export type CredentialCollectionRuntime = typeof import('./collection-runtime');
+/**
+ * The collection layer at the point of use, fetched once.
+ *
+ * This is the applet's only dynamic import of it: the settings entry and the
+ * applet's own chunk contain no part of the engine, and a page that never
+ * reaches the credentials list never fetches it.
+ */
+export declare function credentialCollectionRuntime(): Promise<CredentialCollectionRuntime>;
+/**
+ * The row's resource id in the shape the rest of the applet uses for
+ * credentials: `credentials.ttl#<key>`. The collection's key is only the
+ * `resourceIdPattern` slot (`#{id}` → `openai-<uuid>`), so the document segment
+ * comes from the same models builder the store writes with.
+ */
+export declare function credentialIdOfRow(row: CredentialRow): string;
+/**
+ * Which provider a row belongs to, from the row's own `provider` relation.
+ *
+ * Rows have to be attributable without the store's help: a credential another
+ * device just wrote reaches this page as a live row, before any summary read
+ * has seen it.
+ */
+export declare function providerOfCredentialRow(row: CredentialRow): AiConnectionsProvider | undefined;
+/**
+ * A row as the page's credential summary.
+ *
+ * The row wins for everything the descriptor declares; `carrier` - the store's
+ * summary of the same credential - supplies the attributes the descriptor cannot
+ * project and the secret-derived hint. A row the store has not read yet (an
+ * optimistic insert) falls back to the descriptor's own defaults.
+ */
+export declare function credentialSummaryFromRow(row: CredentialRow, provider: AiConnectionsProvider, carrier?: AiProviderCredentialSummary): AiProviderCredentialSummary;
+/** The provider's credential list, rebuilt from the live rows of one table document. */
+export declare function credentialSummariesForProvider(provider: AiConnectionsProvider, rows: readonly CredentialRow[], carrier?: readonly AiProviderCredentialSummary[]): AiProviderCredentialSummary[];
+/**
+ * The enrichment carrier per provider: the store's own summary of every
+ * credential, plus any credential a mutation of this session added and the store
+ * has not read back yet.
+ *
+ * The store's entries win where both know the same credential - it is the
+ * independent read - and the session's overlay only fills the gap, so a
+ * just-created row keeps its offering and base URL while it is still optimistic.
+ */
+export declare function credentialCarriers(storeProducts: Partial<Record<AiConnectionsProvider, AiProviderSummary>>, overlayProducts: Partial<Record<AiConnectionsProvider, AiProviderSummary>>): Partial<Record<AiConnectionsProvider, readonly AiProviderCredentialSummary[]>>;
+/**
+ * The provider products the page renders, with every credential list rebuilt
+ * from the live rows.
+ *
+ * `carriers` only enriches: which credentials exist, and every field the
+ * descriptor declares, come from the rows.
+ */
+export declare function withLiveCredentials(products: Partial<Record<AiConnectionsProvider, AiProviderSummary>>, carriers: Partial<Record<AiConnectionsProvider, readonly AiProviderCredentialSummary[]>>, rows: readonly CredentialRow[] | undefined): Partial<Record<AiConnectionsProvider, AiProviderSummary>>;

package/node_modules/@undefineds.co/ai-connections/dist/collections.js

@@ -0,0 +1,173 @@
+import { credentialResource } from '@undefineds.co/models';
+import { useSyncExternalStore } from 'react';
+import { AI_CONNECTIONS_PROVIDERS } from './ai-connections-client.js';
+import { defaultOfferingFor } from './provider-catalog.js';
+import { providerOfCredentialKey, providerResourceKey } from './credential-storage.js';
+/**
+ * Live rows for the credentials table. Re-renders on sync and on optimistic
+ * writes, because the source is the collection's own change feed.
+ */
+export function useCredentialRows(source) {
+    return useSyncExternalStore(source.subscribe, () => source.credentialRows, () => source.credentialRows);
+}
+let runtime;
+/**
+ * The collection layer at the point of use, fetched once.
+ *
+ * This is the applet's only dynamic import of it: the settings entry and the
+ * applet's own chunk contain no part of the engine, and a page that never
+ * reaches the credentials list never fetches it.
+ */
+export function credentialCollectionRuntime() {
+    runtime ?? (runtime = import('./collection-runtime.js'));
+    return runtime;
+}
+/**
+ * The row's resource id in the shape the rest of the applet uses for
+ * credentials: `credentials.ttl#<key>`. The collection's key is only the
+ * `resourceIdPattern` slot (`#{id}` → `openai-<uuid>`), so the document segment
+ * comes from the same models builder the store writes with.
+ */
+export function credentialIdOfRow(row) {
+    return credentialResource.buildId({ id: String(row.id) });
+}
+/**
+ * Which provider a row belongs to, from the row's own `provider` relation.
+ *
+ * Rows have to be attributable without the store's help: a credential another
+ * device just wrote reaches this page as a live row, before any summary read
+ * has seen it.
+ */
+export function providerOfCredentialRow(row) {
+    // `RowOf` carries an index signature (models types `fields` as
+    // `Record<string, PodModelFieldDescriptor>`), so a stale attribute name
+    // type-checks and reads back `undefined` at runtime instead of failing the
+    // build. `collections.test.ts` pins this read against a row whose id does not
+    // embed its provider, which is the only case the fallback below cannot answer.
+    const relation = typeof row.provider === 'string' ? row.provider : undefined;
+    const key = providerResourceKey(relation);
+    if (key) {
+        if (key.startsWith('custom-instance-'))
+            return 'custom';
+        const declared = AI_CONNECTIONS_PROVIDERS.find((provider) => key === provider || key.startsWith(`${provider}-`));
+        if (declared)
+            return declared;
+    }
+    // A row without a provider relation still declares one in its own key
+    // (`openai-<uuid>`); the store's reader falls back the same way.
+    return providerOfCredentialKey(String(row.id));
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function numberValue(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim()) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function isoStringValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    return stringValue(value);
+}
+function authModeValue(value) {
+    if (value === 'oauth' || value === 'deviceCode' || value === 'apiKey' || value === 'local') {
+        return value;
+    }
+    if (value === 'deviceCodeOAuth')
+        return 'deviceCode';
+    return undefined;
+}
+/**
+ * A row as the page's credential summary.
+ *
+ * The row wins for everything the descriptor declares; `carrier` - the store's
+ * summary of the same credential - supplies the attributes the descriptor cannot
+ * project and the secret-derived hint. A row the store has not read yet (an
+ * optimistic insert) falls back to the descriptor's own defaults.
+ */
+export function credentialSummaryFromRow(row, provider, carrier) {
+    const authMode = authModeValue(row.authMode) ?? carrier?.authMode ?? 'apiKey';
+    const status = stringValue(row.status);
+    // models 0.2.59 types this column as a boolean; a Pod written by an older
+    // release can still carry the literal as a string, so keep tolerating both.
+    const reauthRequired = row.reauthRequired === true || String(row.reauthRequired) === 'true';
+    return {
+        id: String(row.id),
+        provider,
+        offeringId: carrier?.offeringId ?? defaultOfferingFor(provider, authMode),
+        authMode,
+        label: stringValue(row.accountLabel) ?? stringValue(row.label) ?? carrier?.label,
+        enabled: status === undefined ? carrier?.enabled ?? true : status === 'active',
+        priority: carrier?.priority ?? 100,
+        health: reauthRequired ? 'expired' : carrier?.health ?? 'unknown',
+        maskedHint: carrier?.maskedHint,
+        baseUrl: carrier?.baseUrl,
+        proxyUrl: carrier?.proxyUrl,
+        compatibility: carrier?.compatibility,
+        expiresAt: isoStringValue(row.expiresAt) ?? carrier?.expiresAt,
+        version: numberValue(row.keyVersion) ?? carrier?.version ?? 0,
+    };
+}
+/** The provider's credential list, rebuilt from the live rows of one table document. */
+export function credentialSummariesForProvider(provider, rows, carrier = []) {
+    const byId = new Map(carrier.map((credential) => [credential.id, credential]));
+    const summaries = [];
+    for (const row of rows) {
+        if (providerOfCredentialRow(row) !== provider)
+            continue;
+        summaries.push(credentialSummaryFromRow(row, provider, byId.get(String(row.id))));
+    }
+    return summaries;
+}
+/**
+ * The enrichment carrier per provider: the store's own summary of every
+ * credential, plus any credential a mutation of this session added and the store
+ * has not read back yet.
+ *
+ * The store's entries win where both know the same credential - it is the
+ * independent read - and the session's overlay only fills the gap, so a
+ * just-created row keeps its offering and base URL while it is still optimistic.
+ */
+export function credentialCarriers(storeProducts, overlayProducts) {
+    const carriers = {};
+    for (const provider of AI_CONNECTIONS_PROVIDERS) {
+        const byId = new Map();
+        for (const credential of overlayProducts[provider]?.credentials ?? []) {
+            byId.set(credential.id, credential);
+        }
+        for (const credential of storeProducts[provider]?.credentials ?? []) {
+            byId.set(credential.id, credential);
+        }
+        carriers[provider] = [...byId.values()];
+    }
+    return carriers;
+}
+/**
+ * The provider products the page renders, with every credential list rebuilt
+ * from the live rows.
+ *
+ * `carriers` only enriches: which credentials exist, and every field the
+ * descriptor declares, come from the rows.
+ */
+export function withLiveCredentials(products, carriers, rows) {
+    if (!rows)
+        return products;
+    const live = {};
+    for (const provider of AI_CONNECTIONS_PROVIDERS) {
+        const product = products[provider];
+        if (!product)
+            continue;
+        live[provider] = {
+            ...product,
+            credentials: credentialSummariesForProvider(provider, rows, carriers[provider] ?? []),
+        };
+    }
+    // Providers outside the catalog keep whatever the store reported: the page
+    // never renders them from this table.
+    return { ...products, ...live };
+}

package/node_modules/@undefineds.co/ai-connections/dist/controller.d.ts

@@ -1,24 +1,42 @@
-import type { WebExtensionHost } from '@undefineds.co/extension-sdk/web';
-import { type AiConnectionsClient, type AiConnectionsMode, type AiConnectionsProvider, type AiProviderConnectionSummary, type AiProviderSummary } from './ai-connections-client';
+import type { SolidLiveUpdateState, WebExtensionHost } from '@undefineds.co/extension-sdk/web';
+import { type AiConnectionsClient, type AiConnectionsProvider, type AiProviderConnectionSummary, type AiProviderSummary } from './ai-connections-client';
 import type { AiClientConfigurationBridge } from './AiClientConfigurationSection';
+import { type CredentialRow } from './collections';
+import type { PodCollection } from '@undefineds.co/pod-collections';
 export interface AiProviderDefinition {
     id: AiConnectionsProvider;
     name: string;
-    browserMode: AiConnectionsMode;
-    browserLabel: string;
     description: string;
     homeUrl: string;
     apiKeyUrl?: string;
     apiKeyPlaceholder?: string;
     defaultBaseUrl?: string;
 }
+/**
+ * Provider pages explain themselves through the header's ⓘ tooltip, so each
+ * description is one line of the same shape — where the models come from and how
+ * this deployment can be authorized — instead of a restatement of the name.
+ *
+ * Connect actions are deliberately absent here: which ways in exist is offering
+ * data (`authorizationMethods`), derived by the server per offering, and a
+ * provider-level label is exactly how a page could offer a 「登录」 no offering
+ * declares.
+ */
 export declare const PROVIDERS: AiProviderDefinition[];
 export type ProviderProductState = 'loading' | 'unconfigured' | 'configured' | 'connected' | 'attention';
 export declare const AI_CONNECTIONS_PINNED_SECTIONS: readonly [{
     readonly id: "keys";
-    readonly label: "API Keys";
+    readonly label: "Xpod";
     readonly title: "API KEYS";
 }];
+/**
+ * Coalescing window for Pod change signals.
+ *
+ * A notification only says "this document changed", so a burst of writes must
+ * cost one re-read, not one per write; the first signal arms a fixed window and
+ * everything arriving inside it is absorbed.
+ */
+export declare const TABLE_CHANGE_COALESCE_MS = 75;
 export type AiConnectionsPinnedSection = typeof AI_CONNECTIONS_PINNED_SECTIONS[number]['id'];
 export type AiConnectionsWorkspaceSection = AiConnectionsPinnedSection | 'provider';
 export interface AiConnectionsController {
@@ -32,12 +50,47 @@ export interface AiConnectionsController {
     readonly providerStates: Partial<Record<AiConnectionsProvider, ProviderProductState>>;
     readonly providerSummaries: Partial<Record<AiConnectionsProvider, AiProviderSummary>>;
     readonly providerLoadError?: string;
+    /**
+     * Whether the Pod table documents this page renders are pushing changes.
+     *
+     * `unavailable` also covers a host that offers no live-update capability at
+     * all; either way the page keeps working from explicit reads.
+     */
+    readonly liveUpdates: SolidLiveUpdateState;
+    /**
+     * The live credentials table (`settings/credentials.ttl`), when the host
+     * exposes `podCollections` and the lazily loaded collection layer has landed.
+     * The page renders its rows; the controller's own live-revision refresh does
+     * not watch that document while this is present.
+     */
+    readonly credentialsCollection?: PodCollection<CredentialRow>;
+    /**
+     * The collection's rows as its own change feed reports them, or `undefined`
+     * while the layer is still loading, when the host offers no collection, or
+     * after a failed first read. This is what the credentials list renders (and
+     * what makes every credential write optimistic).
+     */
+    readonly credentialRows?: readonly CredentialRow[];
+    /**
+     * Advances once per coalesced burst of changes to those documents. Pages
+     * re-read through the loaders they already have when it changes.
+     */
+    readonly liveRevision: number;
     selectSection(section: AiConnectionsPinnedSection): void;
     selectProvider(provider: AiConnectionsProvider, credentialId?: string): void;
     selectFirstUnconfiguredProvider(): void;
     setSearchQuery(value: string): void;
     setProviderState(provider: AiConnectionsProvider, state: ProviderProductState): void;
     loadProviders(): Promise<void>;
+    /**
+     * Watches the table documents the open page renders: the credentials table
+     * plus the open provider's document.
+     *
+     * Re-entrant and idempotent, so React StrictMode's setup/cleanup/setup cycle
+     * stays harmless; releasing the last hold leaves no channel and no socket
+     * behind for this page.
+     */
+    watchPageTables(): () => void;
     cancelProviderLoads(): void;
     subscribe(listener: () => void): () => void;
 }
@@ -48,5 +101,18 @@ export declare function useSelectedCredentialId(controller: AiConnectionsControl
 export declare function useProviderSearch(controller: AiConnectionsController): string;
 export declare function useProviderStates(controller: AiConnectionsController): Partial<Record<AiConnectionsProvider, ProviderProductState>>;
 export declare function useProviderSummaries(controller: AiConnectionsController): Partial<Record<AiConnectionsProvider, AiProviderConnectionSummary>>;
+/**
+ * Providers this deployment offers, as reported by the server.
+ *
+ * Cloud answers with the operator-designated providers only (no self-hosted
+ * `custom`, no local daemon), so the settings surface cannot offer a provider the
+ * deployment does not provide. Before the first successful load this is
+ * `undefined`, which keeps every provider visible (Local behavior).
+ */
+export declare function useAvailableProviders(controller: AiConnectionsController): AiConnectionsProvider[] | undefined;
 export declare function useProviderProducts(controller: AiConnectionsController): Partial<Record<AiConnectionsProvider, AiProviderSummary>>;
 export declare function useProviderLoadError(controller: AiConnectionsController): string | undefined;
+/** Whether live Pod updates are on, for a status affordance that stays small. */
+export declare function useLiveUpdates(controller: AiConnectionsController): SolidLiveUpdateState;
+/** Advances once per coalesced burst of Pod changes; drives page re-reads. */
+export declare function useLiveRevision(controller: AiConnectionsController): number;