@domino-sdk/relay 1.0.0-next.8 → 1.0.0

package/dist/request-error-DWduJCGV.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The request-error core every Domino client error extends: the participant `RelayError` and the
+ * management client's error share these fields, so one handler serves both.
+ *
+ * `kind` says what happened:
+ *
+ * - `http`: the server answered with an error status.
+ * - `network`: the transport failed, including a response body cut off after its headers.
+ * - `timeout`: the client's deadline passed.
+ * - `aborted`: the caller cancelled the request.
+ * - `invalid-response`: a 2xx answer that is not JSON, or not the shape this SDK version expects.
+ * - `client`: the client refused the call without sending it, such as for invalid input.
+ */
+type RequestErrorKind = "http" | "network" | "timeout" | "aborted" | "invalid-response" | "client";
+/**
+ * What to do when `uncertain` is true. `replay`: sending the call again with the same
+ * `operationId` is safe, because the server applies it at most once. `reconcile`: read the state
+ * first, since repeating the call could apply it twice.
+ */
+type RequestRecovery = "replay" | "reconcile";
+type RequestErrorDetails = {
+    kind: RequestErrorKind;
+    /** True only when a write may have been applied. Reads are never uncertain. */
+    uncertain?: boolean;
+    /** The HTTP status, whenever response headers arrived. Never invented. */
+    status?: number;
+    /** A machine-readable code: open, so a newer server's codes are kept. */
+    code?: string;
+    /** The call's idempotency or action ID, to replay it with. */
+    operationId?: string;
+    /** Whether repeating this operation is safe. An ID alone may have no durable receipt. */
+    replaySafe?: boolean;
+    /** Milliseconds the server asked to wait before trying again (its `Retry-After`). */
+    retryAfter?: number;
+    cause?: unknown;
+};
+declare const requestErrorBrand: unique symbol;
+/**
+ * Whether `value` is a `RequestError` from any copy of the SDK. Prefer it to `instanceof`, which
+ * fails when an app bundles two copies of the package.
+ */
+declare function isRequestError(value: unknown): value is RequestError;
+declare class RequestError extends Error {
+    readonly name: string;
+    readonly [requestErrorBrand] = true;
+    readonly kind: RequestErrorKind;
+    readonly uncertain: boolean;
+    readonly status: number | undefined;
+    readonly code: string | undefined;
+    readonly operationId: string | undefined;
+    /** `replay` for a replay-safe operation ID, else `reconcile`; only when `uncertain`. */
+    readonly recovery: RequestRecovery | undefined;
+    /**
+     * Milliseconds the server asked the client to wait before trying again, from the `Retry-After`
+     * header of an error answer such as a 429 or 503. The client's own retries never wait past the
+     * call's deadline, so a longer wait is left to the caller.
+     */
+    readonly retryAfter: number | undefined;
+    constructor(message: string, details: RequestErrorDetails);
+}
+
+export { RequestError as R, type RequestErrorDetails as a, type RequestErrorKind as b, type RequestRecovery as c, isRequestError as i };