@hue-run/sdk 0.3.2 → 0.4.1

package/dist/setup/backend.d.ts

@@ -0,0 +1,229 @@
+import type { TraceReceipt } from "../types.js";
+import { type SetupFileChange } from "./configure.js";
+import { type SetupCommandRunner } from "./application.js";
+import type { SetupProjectDetection } from "./types.js";
+import { FileSetupInstallationStore, type SetupInstallationRecord, type SetupStoredCredential } from "./installation.js";
+/** Read-only public setup availability and fixed anonymous bounds. */
+export interface SetupPreflightStatus {
+    /** Frozen HTTP protocol version, independent of public event version. */
+    protocolVersion: 1;
+    /** Whether anonymous provisioning is currently enabled. */
+    state: "available" | "inactive";
+    /** Server-enforced metadata projection for all setup keys. */
+    capturePolicy: "metadata-only-v1";
+    /** Lifetime anonymous storage bounds. */
+    limits: {
+        /** Maximum stored traces. */
+        traces: 100;
+        /** Maximum stored spans. */
+        spans: 1000;
+        /** Maximum sanitized stored bytes. */
+        bytes: 2097152;
+    };
+    /** Fixed anonymous write and retention windows. */
+    lifetime: {
+        /** Ingestion expires one day after provisioning. */
+        expiresAfterSeconds: 86400;
+        /** Unclaimed data is purged eight days after provisioning. */
+        purgeAfterSeconds: 691200;
+    };
+    /** Published disclosure, not an executable acceptance gate. */
+    privacyNotice: {
+        /** Canonical public privacy page. */
+        url: "https://hue.run/privacy";
+        /** Published notice effective date. */
+        effectiveDate: "2026-08-24";
+    };
+    /** Canonical public security information. */
+    securityUrl: "https://trust.hue.run/";
+}
+/** Non-secret descriptor for the current one-time browser handoff. */
+export interface SetupClaimHandoff {
+    /** Persisted lowercase UUIDv4; not the bearer capability. */
+    id: string;
+    /** One-time handoff lifecycle state. */
+    state: "pending" | "consumed" | "expired" | "revoked";
+    /** Original fixed handoff deadline. */
+    expiresAt: string;
+    /** Distinct browser session deadline after successful exchange. */
+    sessionExpiresAt: string | null;
+}
+/** Strictly validated Setup HTTP protocol v1 installation status. */
+export interface SetupInstallationStatus {
+    /** Setup protocol version. */
+    protocolVersion: 1;
+    /** Project/origin-scoped lowercase UUIDv4. */
+    installationId: string;
+    /** Server lifecycle state; expired and purged are terminal. */
+    state: "active" | "claimed" | "expired" | "purged";
+    /** Isolated trial project, or null only when the protocol permits no project. */
+    project: {
+        /** Project identifier retained across account claim. */
+        id: string;
+        /** Organization currently owning the project. */
+        organizationId: string;
+    } | null;
+    /** Current anonymous or post-claim credential generation. */
+    credentialVersion: 0 | 1;
+    /** Server-enforced setup telemetry policy. */
+    capturePolicy: "metadata-only-v1";
+    /** Trial expiry timestamp, or null after claim. */
+    expiresAt: string | null;
+    /** Fixed anonymous lifetime limits. */
+    limits: {
+        /** Maximum anonymous traces. */
+        traces: 100;
+        /** Maximum anonymous spans. */
+        spans: 1000;
+        /** Maximum anonymous canonical stored bytes. */
+        bytes: 2097152;
+    };
+    /** Anonymous lifetime usage counters. */
+    usage: {
+        /** Accepted trace count. */
+        traces: number;
+        /** Accepted span count. */
+        spans: number;
+        /** Accepted canonical stored bytes. */
+        bytes: number;
+    };
+    /** Non-secret current one-time browser handoff descriptor. */
+    claimHandoff: SetupClaimHandoff | null;
+    /** Same-origin telemetry and receipt routes fixed by protocol v1. */
+    endpoints: {
+        /** Relative OTLP/HTTP traces route. */
+        otlp: "/api/v1/otlp/v1/traces";
+        /** Relative exact-receipt route template. */
+        receipt: "/api/v1/setup/traces/{traceId}/receipt";
+    };
+}
+/** Installation status plus one idempotently recovered telemetry credential. */
+export interface SetupCredentialResult extends SetupInstallationStatus {
+    /** Telemetry-only credential for the requested generation. */
+    credential: SetupStoredCredential & {
+        /** Closed capability set enforced for setup-issued keys. */
+        capabilities: ["setup_telemetry_write"];
+    };
+}
+/** Exact receipt evidence for one real metadata-only setup probe. */
+export interface SetupProbeEvidence {
+    /** External trace identifier sent by the probe. */
+    traceId: string;
+    /** External span identifier required in the receipt. */
+    spanId: string;
+    /** Validated positive receipt containing the exact identifiers. */
+    receipt: TraceReceipt;
+}
+/** Exact receipt evidence from a request through the repository's existing application. */
+export interface SetupApplicationEvidence extends SetupProbeEvidence {
+    /** Closed evidence source; synthetic setup probes can never satisfy application verification. */
+    source: "existing-application-request";
+}
+/** @deprecated Use SetupInstallationStatus. Retained as an exported compatibility name. */
+export type SetupBackendTrial = SetupInstallationStatus;
+/** @deprecated Use SetupProbeEvidence. Retained as an exported compatibility name. */
+export type SetupBackendReceipt = SetupProbeEvidence;
+/** Non-secret account-claim state; bearer handoffs are never part of public adapter results. */
+export type SetupBackendClaim = {
+    /** Browser owner action is still required. */
+    status: "required";
+    /** Installation identity associated with the claim. */
+    claimId: string;
+    /** Capability-free indication that the browser handoff is stored owner-only. */
+    handoff: "owner-local";
+} | {
+    /** Browser claim and local reconciliation completed. */
+    status: "completed";
+    /** Installation identity associated with the claim. */
+    claimId: string;
+};
+/** Sanitized setup failure with a stable local or protocol code. */
+export declare class SetupBackendError extends Error {
+    /** Stable local code or exact `SETUP_*` server code. */
+    readonly code: "invalid_origin" | "transport" | "invalid_response" | "unverified" | `SETUP_${string}`;
+    /** Validated HTTP status when the failure came from the server. */
+    readonly status?: number | undefined;
+    /** Bounded server-requested retry delay, when provided. */
+    readonly retryAfterMillis?: number | undefined;
+    constructor(
+    /** Stable local code or exact `SETUP_*` server code. */
+    code: "invalid_origin" | "transport" | "invalid_response" | "unverified" | `SETUP_${string}`, message: string, 
+    /** Validated HTTP status when the failure came from the server. */
+    status?: number | undefined, 
+    /** Bounded server-requested retry delay, when provided. */
+    retryAfterMillis?: number | undefined, options?: ErrorOptions);
+}
+/** Construction options for the real Setup HTTP protocol v1 adapter. */
+export interface SetupBackendAdapterOptions {
+    /** Project directory that owns the installation identity and managed configuration. */
+    projectRoot: string;
+    /** HTTPS Hue origin, or an explicit loopback HTTP origin for isolated tests. */
+    origin?: string;
+    /** Injectable Fetch implementation used by synthetic loopback tests. */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request deadline in milliseconds. */
+    requestTimeoutMillis?: number;
+    /** Total receipt polling deadline in milliseconds. */
+    receiptTimeoutMillis?: number;
+    /** Injectable owner-browser opener used only by isolated tests. */
+    openBrowser?: (localHandoffUrl: string) => Promise<void>;
+    /** Injectable fixed-argv package-manager runner used only by isolated tests. */
+    commandRunner?: SetupCommandRunner;
+}
+/** Real implementation of the frozen Setup HTTP protocol v1. */
+export declare class SetupBackendAdapter {
+    /** Exact normalized Hue origin used by every request. */
+    readonly origin: string;
+    /** Project/origin-scoped owner-only installation store. */
+    readonly store: FileSetupInstallationStore;
+    private readonly fetcher;
+    private readonly requestTimeoutMillis;
+    private readonly receiptTimeoutMillis;
+    private readonly browserOpener;
+    private readonly commandRunner?;
+    private installation?;
+    private applicationPlan?;
+    private installationStatus?;
+    /** Discards cached facts after the command-wide lock has been acquired. */
+    resetLocalCache(): void;
+    constructor(options: SetupBackendAdapterOptions);
+    /** Persists installation UUID and proof before returning control to any network operation. */
+    prepare(): Promise<SetupInstallationRecord>;
+    /** Reads local state without creating files or contacting Hue. */
+    localInstallation(): Promise<SetupInstallationRecord | undefined>;
+    private readJson;
+    private publicPreflightRequest;
+    private request;
+    /** Creates once or recovers the same installation. At most two provision writes occur per invocation. */
+    provision(signal?: AbortSignal): Promise<SetupInstallationStatus>;
+    /** Reads and validates the current installation status without provisioning. */
+    status(signal?: AbortSignal): Promise<SetupInstallationStatus>;
+    /** Requests or recovers one proof-bound handoff and opens only its owner-local file URL. */
+    prepareClaimHandoff(status: SetupInstallationStatus, openBrowser: boolean, restart?: boolean, signal?: AbortSignal): Promise<{
+        /** Whether the owner-local handoff file was opened without echoing its URL. */
+        opened: boolean;
+        /** Last observed non-secret handoff state. */
+        state: SetupClaimHandoff["state"];
+        /** Whether explicit owner restart is necessary rather than browser-session resume. */
+        restartRequired: boolean;
+    }>;
+    /** Retrieves an idempotent generation and persists it before it can be used by project config. */
+    credentials(credentialVersion: 0 | 1, signal?: AbortSignal): Promise<SetupCredentialResult>;
+    /** Installs the exact Hue runtime through the one unambiguous project package manager. */
+    installRuntime(project: SetupProjectDetection): Promise<boolean>;
+    /** Writes secret-free config and an owned middleware block into the recognized application. */
+    configure(project: SetupProjectDetection): Promise<SetupFileChange[]>;
+    /** Fails before mutation on unsafe project state, then reads public technical availability. */
+    preflight(project: SetupProjectDetection, signal?: AbortSignal, checkAvailability?: boolean): Promise<SetupPreflightStatus | undefined>;
+    /** Runs one request through the recognized existing app and privately checkpoints its IDs. */
+    exerciseApplication(project: SetupProjectDetection, signal?: AbortSignal): Promise<void>;
+    private verifyStoredApplication;
+    /** Verifies only IDs emitted by the existing application request; it never creates a probe. */
+    verifyApplication(signal?: AbortSignal): Promise<SetupApplicationEvidence | undefined>;
+    private validateReceiptProject;
+    private verifyStoredProbe;
+    /** Exports one real metadata-only span, awaits flush, and verifies its exact stored IDs. */
+    verifyProbe(signal?: AbortSignal): Promise<SetupProbeEvidence | undefined>;
+    /** Confirms a superseded telemetry key cannot read the newly verified receipt. */
+    verifyRevokedCredential(oldApiKey: string, evidence: SetupProbeEvidence, signal?: AbortSignal): Promise<void>;
+}