@zackbart/connecta 0.34.1 → 0.36.0

package/dist/operator-ui/view.d.ts

@@ -1,401 +0,0 @@
-import type { OperatorRole, OperatorUiContractV2 } from "./contract.js";
-import type { CatalogDriftReport } from "../types.js";
-import type { CredentialManagementCapability, UiConnector, UiData, UiProblem } from "./model.js";
-import type { FixPromptKind } from "./fix-prompts.js";
-import type { AgentSlot } from "./agents.js";
-export declare function registrationPathLabel(path: NonNullable<UiConnector["registrationPath"]>): string;
-export type OperatorPage = "overview" | "endpoints" | "settings" | "connector" | "tokens" | "connections" | "activity";
-/** Pages the nav lists, in dashboard order. */
-export declare const OPERATOR_PAGES: readonly OperatorPage[];
-export declare const PAGE_META: Readonly<Record<OperatorPage, {
-    path: string;
-    label: string;
-}>>;
-/** Legacy links remain valid, with the browser replacing their URL. */
-export declare function canonicalOperatorPath(path: string): string;
-/**
- * What each page is for, in one line under its heading — on the gate as well
- * as once signed in, so the page an operator lands on reads the same before
- * and after the session is checked.
- */
-export declare function pageDescription(page: OperatorPage, productDescription: string): string;
-/**
- * Signed in, but neither a maintainer nor a member of any endpoint: who to
- * ask, and that this is not an error to retry.
- */
-export declare function noAccessCopy(kind: string, productName: string): string;
-/** What the gate says while the session is checked, page by page. */
-export declare function checkingCopy(): string;
-export declare function pageForPath(path: string): OperatorPage;
-export interface UiActivityActor {
-    kind?: string;
-    id?: string;
-    namespace?: string;
-    label?: string;
-}
-export interface UiActivityEvent {
-    kind?: "catalog_drift";
-    drift?: import("../activity.js").ActivityCatalogChange;
-    id?: string;
-    requestId?: string;
-    classification?: "read" | "write";
-    resultBytes?: number;
-    occurredAt: string;
-    actor?: UiActivityActor;
-    connectorId: string;
-    toolName: string;
-    address: string;
-    source: string;
-    outcome: string;
-    durationMs: number;
-    attempts: number;
-    errorCode?: string;
-    friction?: string;
-    approval?: string;
-    packageVersion?: string;
-    clientName?: string;
-    clientVersion?: string;
-}
-/**
- * Which fix prompt a failure offers. A kind and a configured connector id —
- * the message beside it never travels with it.
- */
-export interface NoticeFix {
-    kind: FixPromptKind;
-    connectorId: string;
-}
-/** A message with the tone that decides its live region: status or alert. */
-export interface Notice {
-    message: string;
-    tone: "info" | "error";
-    fix?: NoticeFix;
-}
-export declare function info(message: string): Notice;
-export declare function failure(message: string, fix?: NoticeFix): Notice;
-/**
- * Why a request the page made did not land, as the store classifies it. Only
- * this kind, a status code, and a closed `problem` enum ever reach a notice;
- * the route's `error` text never does.
- *
- * - `session` — no usable session, or the route answered 401.
- * - `forbidden` — the route answered 403: this identity may not do that. On a
- *   mutation that is a permission, not an expired session, so it stays inline.
- * - `network` — the browser could not reach the deployment at all.
- * - `refused` — the route answered, and said no.
- * - `stale` — never sent: what the action was checked against changed before
- *   dispatch (a refreshed slot list or member contract).
- */
-export type RequestFailureKind = "session" | "forbidden" | "network" | "refused" | "stale";
-export interface RequestFailureFacts {
-    kind: RequestFailureKind;
-    status?: number | undefined;
-    problem?: unknown;
-    /** A refusal's machine `code` from a closed set, such as `slot_changed`; checked, never shown. */
-    code?: unknown;
-}
-/**
- * What the notices for an OAuth action and a credential Test say. Each of
- * those actions reaches a downstream, and a downstream's refusal can quote the
- * secret it was sent — so these notices are fixed sentences chosen by outcome,
- * and no text the server sent back is ever one of them. The route logs the
- * downstream's words on the host; the fix prompt beside a failure is keyed off
- * the same outcome.
- */
-export type DownstreamAction = "oauth_disconnect" | "oauth_reconnect" | "credential_test";
-/** Every action a connector row can start, downstream or not. */
-export type RowAction = DownstreamAction | "credential_save" | "credential_remove";
-/**
- * The route's answer to a finished OAuth action. Its state picks the sentence;
- * `opened` says whether the authorization page is already in a new tab.
- */
-export declare function oauthDoneNotice(action: "oauth_disconnect" | "oauth_reconnect", answer: {
-    state?: unknown;
-    code?: unknown;
-} | null, opened?: boolean): Notice;
-/** A credential Test's result. `ok` is the only part of the answer it reads. */
-export declare function credentialTestNotice(connectorId: string, answer: {
-    ok?: unknown;
-} | null): Notice;
-/**
- * A route that refused one of these actions. A credential Test that found
- * nothing usable to test names the problem, which picks the same copy and fix
- * prompt the Connections page uses for it; every other refusal gets the
- * action's one sentence. `problem` is whatever the response carried, so it is
- * checked, not trusted.
- */
-export declare function refusedNotice(action: DownstreamAction, connectorId: string, problem?: unknown): Notice;
-/** An action whose permission or target changed before it was sent. */
-export declare const STALE_COPY = "This changed before sending, so nothing was sent. Try again.";
-/**
- * Every row action's failure, in one voice. The page's own failures — a
- * lapsed session, a denied identity, a dropped connection — read the same for
- * every action; a route's refusal picks the action's fixed sentence.
- */
-export declare function actionFailedNotice(action: RowAction, connectorId: string, facts: RequestFailureFacts, productName: string): Notice;
-/**
- * Why one connector's details did not load, when the reason is on this side
- * of the deployment rather than the downstream's. A downstream failure is the
- * server's `connector_unavailable` and keeps its own copy and fix prompt;
- * these two have nothing for a coding agent to fix.
- */
-export type ConnectorLoadFailure = "session" | "network" | "unavailable";
-export declare function connectorLoadFailureCopy(failure: ConnectorLoadFailure, productName: string): string;
-/** The signed-in page's answer when `/ui/data` could not be read. */
-export declare function loadFailureCopy(failure: "server" | "network", productName: string): {
-    title: string;
-    body: string;
-};
-/** A collection page's load failure: fixed words, whatever the route said. */
-export declare function collectionFailureCopy(_collection: "activity", facts: RequestFailureFacts, productName: string): string;
-/** A destructive or disruptive row action waiting for a second, in-page click. */
-export interface PendingConfirm {
-    connectorId: string;
-    action: "oauth_disconnect" | "oauth_restart" | "credential_remove";
-}
-/** The confirm's question, naming the connector by its title. */
-export declare function confirmCopy(action: PendingConfirm["action"], name: string): {
-    question: string;
-    confirm: string;
-};
-/**
- * A remote collection's four states, named once so every page spells them the
- * same way. `idle` is "nobody has asked yet" and is what makes a re-entered
- * page fetch again after an identity change.
- */
-type LoadPhase = "idle" | "loading" | "ready" | "error";
-export declare function accessTokenUnavailableCopy(capability?: string): string;
-export interface OperatorState {
-    tokenPhase: LoadPhase;
-    tokenNotice: Notice | null;
-    /** One slot per declared agent, from `/ui/access-tokens`. */
-    tokens: AgentSlot[];
-    /** A just-issued secret, shown once in its dialog and dropped when that closes. */
-    createdToken: string | null;
-    /** The agent `createdToken` belongs to. */
-    createdTokenFor: string | null;
-    /** A rotation or revocation waiting on its in-row confirmation. */
-    tokenConfirm: {
-        name: string;
-        action: "rotate" | "revoke";
-    } | null;
-    /**
-     * Agents whose last token operation ended with an unknown outcome (503,
-     * 499, or a dropped connection). Their actions stay off until a slot list
-     * read that started after the failure succeeds.
-     */
-    unresolvedSlots: string[];
-    tokenBusy: boolean;
-    page: OperatorPage;
-    /**
-     * Bumped by every identity change. Async work captures it before awaiting and
-     * throws its result away if the operator is no longer the one who asked —
-     * the fence that keeps one identity's data off another identity's screen.
-     */
-    generation: number;
-    /**
-     * `loading` until `/ui/api/config` answers (and, for a maintainer,
-     * `/ui/data` too). `denied` is signed in as someone who is neither a
-     * maintainer nor a pool member.
-     */
-    session: "loading" | "gated" | "ready" | "denied";
-    gate: Notice | null;
-    /** True while a signed-in operator's /ui/data is in flight. */
-    refreshing: boolean;
-    /** A bounded admission recovery is pending; Retry can supersede it. */
-    recoveryPending: boolean;
-    /**
-     * Why the last /ui/data read failed when the session itself was not the
-     * reason: the page stays signed in, with its chrome, and offers a retry.
-     * Only a 401 or 403 on that read returns to the gate.
-     */
-    loadFailure: "server" | "network" | null;
-    /**
-     * Element id the next render should focus. A rebuilt page has no stable node
-     * to hand focus to from an event handler, so the request travels through
-     * state and the shell spends it once the new markup exists.
-     */
-    pendingFocus: string | null;
-    /**
-     * Like `pendingFocus`, but spent only when focus has nowhere to be — the
-     * control that had it is gone. An action that lands next to its own control
-     * announces through its live region and leaves focus where the operator is.
-     */
-    focusIfLost: string | null;
-    data: UiData | null;
-    /** Operator contract v2, for either role; null until `/ui/api/config` answers. */
-    contract: OperatorUiContractV2 | null;
-    /**
-     * The role the last good contract confirmed. It outlives a failed refresh
-     * that clears `contract`, so the next answer with a different role is
-     * still recognized as a different viewer. Only an identity reset clears it.
-     */
-    role: OperatorRole | null;
-    contractPhase: LoadPhase;
-    health: "loading" | "ok" | "unavailable";
-    connectorFilter: string;
-    oauthNotice: Notice | null;
-    /** The connector row `oauthNotice` answers, which is where it renders. */
-    oauthNoticeFor: string | null;
-    /** Connector id whose OAuth mutation is in flight. */
-    oauthBusy: string | null;
-    /**
-     * Connector id whose authorization started while the browser refused the
-     * new tab: its row offers the link instead of the button.
-     */
-    oauthBlocked: string | null;
-    /**
-     * The authorization link the route returned for `oauthBlocked`. A member has
-     * no `/ui/data` connector to keep it on, so it is held here.
-     */
-    oauthBlockedUrl: string | null;
-    /** A row action waiting for its in-page confirmation. */
-    confirming: PendingConfirm | null;
-    /** Connectors whose details failed on this side of the deployment. */
-    connectorFailures: Readonly<Record<string, ConnectorLoadFailure>>;
-    credentialNotice: Notice | null;
-    /** The connector row `credentialNotice` answers. */
-    credentialNoticeFor: string | null;
-    /** Connector id whose credential form is open. */
-    credentialEditing: string | null;
-    /** Connector id whose credential mutation is in flight. */
-    credentialBusy: string | null;
-    activityPhase: LoadPhase;
-    activityNotice: Notice | null;
-    activityEvents: UiActivityEvent[];
-    activityCursor: string | null;
-    activitySearch: string;
-}
-/** Who the contract says this viewer is, or null before it loads. */
-export declare function operatorRole(state: Pick<OperatorState, "contract">): OperatorRole | null;
-/**
- * The role pages and navigation render for. The contract's, or, while a
- * refresh that failed has left no contract on screen, maintainer when the
- * last good contract confirmed one and that maintainer's data is still here:
- * their page stays mounted on its own retry state instead of being torn down
- * mid-recovery. Never a request's permission; the store sends maintainer
- * reads only while the contract itself says maintainer.
- */
-export declare function displayRole(state: Pick<OperatorState, "contract" | "role" | "data">): OperatorRole | null;
-/**
- * A confirmed maintainer's page is mounted without a contract behind it: a
- * refresh failed, or its read ran past the deadline. The shell shows one
- * recovery banner with Retry above whichever page is open, and that page is
- * stale until a contract confirms the role again.
- */
-export declare function contractRecovering(state: Pick<OperatorState, "contract" | "role" | "data">): boolean;
-/**
- * Whether Activity is open to this viewer: maintainers only, on a deployment
- * that records history. Members always read "forbidden".
- */
-export declare function activityReadable(state: Pick<OperatorState, "contract" | "data">): boolean;
-/** The contract's half of `activityReadable`: a maintainer, on a deployment that records. */
-export declare function activityAllowed(state: Pick<OperatorState, "contract">): boolean;
-export declare function initialState(page: OperatorPage): OperatorState;
-/**
- * Drop to the gate and forget the previous operator. Bumping the generation is
- * what makes the drop stick: work already in flight for the old identity
- * resolves into a state that no longer accepts it.
- */
-export declare function resetIdentity(state: OperatorState, gate?: Notice | null): OperatorState;
-/**
- * Leaving a page closes what should not survive it: a one-time secret, a half
- * typed credential, and the notices that answered the page just left.
- */
-export declare function withPage(state: OperatorState, page: OperatorPage): OperatorState;
-export declare function credentialUnavailableCopy(capability?: CredentialManagementCapability): string;
-/**
- * The status badge. An auth-needed connector is named by what it needs, so a
- * row whose fix is "Add credential" does not say "Authorization needed".
- */
-export declare function connectorStatusLabel(status: string, problem?: UiProblem): string;
-/** The tone a status carries wherever it is rendered as a badge or a tile. */
-export type Tone = "ok" | "warn" | "danger" | "neutral" | "accent";
-export declare function connectorStatusTone(status: string): Tone;
-export declare function problemCopy(problem: UiProblem | undefined): string | null;
-/**
- * A problem someone can fix by authorizing is a warning, matching the amber
- * "Authorization needed" badge above it; one where something broke is an
- * error. The two used to share the red box, so the row contradicted itself.
- */
-export declare function problemTone(problem: UiProblem): "warn" | "danger";
-/** What the page knows about a connector beyond its live status: a failed detail read. */
-export interface ConnectorSignals {
-    failed?: boolean;
-}
-/** One connector's health everywhere it is shown: badge tone, status word, and the one action beside it. */
-export interface ConnectorVerdict {
-    tone: "ok" | "warn" | "danger" | "neutral";
-    label: string;
-    /** The link to the Connection tab, or null when the connector is fine. */
-    action: "Connect" | "Replace key" | "Inspect" | null;
-}
-/**
- * The verdict the Connectors list, the Overview, Endpoints and a connector's
- * page all show. The server's problem code comes first, then a failed detail
- * read on this page, then a non-ok status. Catalog drift is informational. A problem
- * outranks the status, so a connector whose catalog failed is never
- * "Connected". A failed read marks its connector `connector_unavailable` in
- * the store, so that one code beside a failed read is the page's own and
- * reads "Couldn't load" instead of blaming the downstream.
- */
-export declare function connectorVerdict(live: {
-    status: string;
-    problem?: UiProblem;
-}, signals?: ConnectorSignals): ConnectorVerdict;
-/**
- * Hosted-provider catalog drift, as an operator reads it
- * ([#343](https://github.com/zackbart/connecta/issues/343)).
- *
- * - `unavailable` — no refresh has been observed in this runtime, so there is
- *   nothing to report. Deliberately not `clean`: "we have not looked" and "we
- *   looked and it matches" are different answers, and only one of them is a
- *   reason to stop worrying.
- * - `clean` — a refresh happened and every category counted zero.
- * - `warning` — a refresh happened and at least one category did not.
- */
-export type DriftState = "clean" | "warning" | "unavailable";
-export declare function driftState(drift?: CatalogDriftReport): DriftState;
-/** Every category with its count, so a clean report still shows its zeros. */
-export declare function driftCounts(drift?: CatalogDriftReport): Array<{
-    key: string;
-    label: string;
-    count: number;
-}>;
-/** One line naming the state and when it was observed. Never what drifted. */
-export declare function driftSummary(drift?: CatalogDriftReport): string;
-/**
- * Only http/https may become a clickable href — the browser half of the gate
- * `src/ui.ts` applies before an authorizationUrl is ever serialized. A hostile
- * downstream that gets a `javascript:` URL past one of them still meets the
- * other, and the caller renders inert text instead of a link.
- */
-export declare function safeHttpHref(url: string | undefined): string | null;
-/** Locale timestamp, or "" for anything that is not a readable date. */
-export declare function formatDate(value?: string): string;
-/** Who made a call: their name when there is one, and how they signed in. */
-export declare function actorLabel(actor?: UiActivityActor): string;
-/**
- * The stable id behind a friendly label, shown only when a label or namespace
- * could otherwise make two different people look like one.
- */
-export declare function actorStableId(actor?: UiActivityActor): string | null;
-export declare function filterActivity(events: UiActivityEvent[], query: string): UiActivityEvent[];
-/** Counts only. What the deployment ran, never what it sent or received. */
-export declare function activitySummary(events: UiActivityEvent[]): string;
-export declare function activityOutcomeClass(outcome: string): string;
-export declare function activityOutcomeBadge(outcome: string): {
-    label: string;
-    tone: Tone;
-};
-/** Why a call stalled or failed, in words; "" when nothing was recorded. */
-export declare function activityReason(event: UiActivityEvent): string;
-/** The one-line detail under an address: where it ran, retries, and why it stalled. */
-export declare function activityDetail(event: UiActivityEvent): string;
-/**
- * A stored credential that cannot be used, by cause. The payload's `error`
- * beside it is not shown: it can carry a vault's own words.
- */
-export declare function credentialProblemCopy(problem: string | undefined): string;
-/** Gate copy for each browser-auth shape, so the sign-in state is never a blank page. */
-export declare function gateCopy(kind: string, signedIn: boolean): string;
-export {};