@shardflux/sdk 0.5.0

package/dist/errors.d.ts

@@ -0,0 +1,57 @@
+import type { components as AppComponents } from './generated/app-api.js';
+import type { components as CellComponents } from './generated/cell-api.js';
+export type AppErrorBody = AppComponents['schemas']['ErrorBody'];
+export type AppErrorCode = AppErrorBody['error']['code'];
+export type CellErrorCode = CellComponents['schemas']['ErrorCode'];
+/** Closed error codes of the application API and the cell gateway (both published in OpenAPI). */
+export type ErrorCode = AppErrorCode | CellErrorCode;
+export interface ErrorBodyLike {
+    error: {
+        code: string;
+        message: string;
+        request_id: string;
+        retryable: boolean;
+        operation_id?: string;
+        details?: Record<string, unknown>;
+    };
+}
+export declare function isErrorBody(v: unknown): v is ErrorBodyLike;
+/** A structured error from the application API or a cell gateway (contracts §3). */
+export declare class ShardfluxApiError extends Error {
+    readonly status: number;
+    readonly code: ErrorCode;
+    readonly requestId: string;
+    readonly retryable: boolean;
+    readonly details: Record<string, unknown> | undefined;
+    readonly operationId: string | undefined;
+    readonly source: 'api' | 'cell';
+    readonly retryAfterSeconds: number | undefined;
+    constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number);
+}
+/** The response was not the documented shape (e.g. a proxy error page). */
+export declare class ShardfluxProtocolError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+type Operation = AppComponents['schemas']['Operation'];
+/**
+ * Waiting for an operation ran out of time. The operation keeps running server side:
+ * resume with `cloud.workspaces.waitForOperation(err.operationId)` or call open() again
+ * (it returns the same operation while it is active).
+ */
+export declare class OperationTimeoutError extends Error {
+    readonly operationId: string;
+    readonly workspaceId: string | null;
+    readonly lastState: Operation['state'];
+    readonly lastReason: string | null;
+    readonly waitedMs: number;
+    constructor(op: Operation, waitedMs: number);
+}
+/** The operation reached `failed` or `canceled`. */
+export declare class OperationFailedError extends Error {
+    readonly operation: Operation;
+    readonly operationId: string;
+    readonly errorCode: string | null;
+    constructor(op: Operation);
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,73 @@
+export function isErrorBody(v) {
+    if (typeof v !== 'object' || v === null || !('error' in v))
+        return false;
+    const e = v.error;
+    return typeof e === 'object' && e !== null && typeof e.code === 'string' && typeof e.message === 'string';
+}
+/** A structured error from the application API or a cell gateway (contracts §3). */
+export class ShardfluxApiError extends Error {
+    status;
+    code;
+    requestId;
+    retryable;
+    details;
+    operationId;
+    source;
+    retryAfterSeconds;
+    constructor(status, body, source, retryAfterSeconds) {
+        super(body.error.message);
+        this.name = 'ShardfluxApiError';
+        this.status = status;
+        this.code = body.error.code;
+        this.requestId = body.error.request_id;
+        this.retryable = body.error.retryable;
+        this.details = body.error.details;
+        this.operationId = body.error.operation_id;
+        this.source = source;
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+/** The response was not the documented shape (e.g. a proxy error page). */
+export class ShardfluxProtocolError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'ShardfluxProtocolError';
+        this.status = status;
+    }
+}
+/**
+ * Waiting for an operation ran out of time. The operation keeps running server side:
+ * resume with `cloud.workspaces.waitForOperation(err.operationId)` or call open() again
+ * (it returns the same operation while it is active).
+ */
+export class OperationTimeoutError extends Error {
+    operationId;
+    workspaceId;
+    lastState;
+    lastReason;
+    waitedMs;
+    constructor(op, waitedMs) {
+        super(`Operation ${op.id} (${op.kind}) is still ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''} after ${Math.round(waitedMs)} ms; it continues server side.`);
+        this.name = 'OperationTimeoutError';
+        this.operationId = op.id;
+        this.workspaceId = op.workspace_id;
+        this.lastState = op.state;
+        this.lastReason = op.state_reason ?? null;
+        this.waitedMs = waitedMs;
+    }
+}
+/** The operation reached `failed` or `canceled`. */
+export class OperationFailedError extends Error {
+    operation;
+    operationId;
+    errorCode;
+    constructor(op) {
+        const code = typeof op.error?.code === 'string' ? op.error.code : null;
+        super(`Operation ${op.id} (${op.kind}) ${op.state}${code ? `: ${code}` : ''}`);
+        this.name = 'OperationFailedError';
+        this.operation = op;
+        this.operationId = op.id;
+        this.errorCode = code;
+    }
+}