@opengeni/sdk 0.29.0 → 0.32.1

package/dist/desktop.d.ts

@@ -0,0 +1,71 @@
+import type { DesktopStreamCapability, StreamUrlRotatedPayload } from "./types";
+/**
+ * Translate the negotiated desktop capability into the WebSocket URL the noVNC
+ * RFB client connects to. The scoped provider token is ALREADY embedded in the
+ * minted `url` (Modal tunnel host, Blaxel `bl_preview_token`, Daytona signed
+ * preview) by `session.resolveExposedPort(6080)` — we do NOT append `cap.token`
+ * as a query param (that double-auth was an adversarial-review bug: the box runs
+ * `-nopw` in v1, so the RFB password is meaningless and the real auth is the
+ * tunnel token in the host). We only normalize the scheme to `ws`/`wss` and, when
+ * the minted URL points at a `vnc.html` viewer page, rewrite it to the
+ * websockify socket path noVNC actually dials.
+ */
+export declare function desktopSocketUrl(cap: Pick<DesktopStreamCapability, "url">): string;
+/**
+ * The minimal RFB surface the React component drives. Lets tests (and 3rd
+ * parties swapping noVNC for a WebRTC client in v3) provide a fake without the
+ * DOM. Matches `@novnc/novnc`'s RFB constructor + lifecycle.
+ */
+export interface DesktopRfbLike {
+    viewOnly: boolean;
+    scaleViewport: boolean;
+    /**
+     * 1:1 viewport clipping. We always drive this FALSE: with clipping on, noVNC
+     * paints the framebuffer pixel-for-pixel and scrolls/crops to the container
+     * (the "zoomed in" look). FALSE lets `scaleViewport` shrink the 1280x800 frame
+     * to fit the panel (aspect-preserved). Declared so the hook can pin it instead
+     * of relying on noVNC's default — `scaleViewport=true` forces clip off
+     * internally, but a stale/partial state on reconnect could leave it on.
+     */
+    clipViewport: boolean;
+    addEventListener(type: "connect" | "disconnect" | "securityfailure", cb: (e?: unknown) => void): void;
+    removeEventListener?: (type: "connect" | "disconnect" | "securityfailure", cb: (e?: unknown) => void) => void;
+    disconnect(): void;
+}
+export type DesktopRfbFactory = (target: HTMLElement, url: string, opts: {
+    credentials?: {
+        password?: string | undefined;
+    } | undefined;
+}) => DesktopRfbLike;
+export type DesktopConnectionState = "idle" | "negotiating" | "connecting" | "connected" | "rotating" | "reconnecting" | "error" | "ended";
+export type DesktopStreamEvent = {
+    type: "negotiated";
+} | {
+    type: "connected";
+} | {
+    type: "disconnected";
+} | {
+    type: "rotate";
+} | {
+    type: "fail";
+} | {
+    type: "abort";
+};
+/**
+ * Pure reducer for the desktop connection lifecycle. The component owns the RFB
+ * object + DOM; this owns the transitions so they are unit-testable. Mirrors the
+ * Channel-A stream reducer discipline.
+ */
+export declare function nextDesktopState(current: DesktopConnectionState, ev: DesktopStreamEvent): DesktopConnectionState;
+export type DesktopStreamCapabilityLike = {
+    url: string | null;
+    token: string | null;
+    expiresAt: string | null;
+};
+/**
+ * Apply a `stream.url.rotated` event onto a desktop capability, fencing on
+ * leaseEpoch (split-brain). A rotation minted under an epoch the client has
+ * already advanced PAST is from a superseded owner and is dropped (returns
+ * null); otherwise the fresh url/token/expiresAt are folded in.
+ */
+export declare function applyUrlRotation<T extends DesktopStreamCapabilityLike>(cap: T, payload: StreamUrlRotatedPayload, knownEpoch: number): T | null;

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+/** Error for a non-2xx OpenGeni API response. */
+export declare class OpenGeniApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly retryable: boolean;
+    readonly correlationId: string | undefined;
+    /** True only when an uncontrolled transport failed after a mutation may have been accepted. */
+    readonly outcomeUnknown: boolean;
+    readonly body: string;
+    constructor(status: number, body: string, options?: {
+        code?: string | undefined;
+        retryable?: boolean | undefined;
+        correlationId?: string | undefined;
+        outcomeUnknown?: boolean | undefined;
+        displayMessage?: string | undefined;
+        mutation?: boolean | undefined;
+    });
+}
+/** A short-lived session-list snapshot cursor can no longer be continued. */
+export declare class OpenGeniSessionListCursorError extends OpenGeniApiError {
+}
+/** The browser bundle and API disagree about their state-changing wire contract. */
+export declare class OpenGeniApiContractMismatchError extends Error {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(expected: string, actual: string);
+}
+/** Error for an unrecoverable event-stream condition (not a transient drop). */
+export declare class OpenGeniStreamError extends Error {
+    constructor(message: string);
+}
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * Transient conditions worth a reconnect: network-level failures (`fetch`
+ * rejects with `TypeError`) and HTTP statuses that signal a temporary server
+ * or contention condition. Auth/validation failures (401/403/404/...) are
+ * permanent and surface to the caller instead.
+ */
+export declare function isRetryableStreamError(error: unknown): boolean;