@zshannon/streamstore 0.22.3

package/dist/esm/endpoints.d.ts

@@ -0,0 +1,63 @@
+type Scheme = "http" | "https";
+export type EndpointTemplateInit = {
+    /**
+     * Endpoint string. May be:
+     * - `host`
+     * - `host:port`
+     * - `https://host[:port][/path]`
+     * - `http://host[:port][/path]`
+     *
+     * For basin endpoints, may include `{basin}` placeholder in hostname and/or path.
+     */
+    endpoint: string;
+};
+export declare class EndpointTemplate {
+    readonly raw: string;
+    readonly scheme: Scheme;
+    readonly hostTemplate: string;
+    readonly port: string;
+    readonly pathTemplate: string;
+    readonly hasBasinPlaceholder: boolean;
+    readonly explicitPathProvided: boolean;
+    constructor({ endpoint }: EndpointTemplateInit);
+    /**
+     * Resolve the template into a base URL string.
+     *
+     * - If `{basin}` appears in the hostname, it is substituted verbatim (basin names are validated by S2.basin()).
+     * - If `{basin}` appears in the path/query/hash, it is substituted via `encodeURIComponent`.
+     */
+    baseUrl(basin?: string): string;
+}
+export type S2EndpointsInit = {
+    /**
+     * Account endpoint (authority with optional scheme/port, optional path).
+     * If no path is present, `/v1` is used.
+     */
+    account?: string;
+    /**
+     * Basin endpoint (authority with optional scheme/port, optional path).
+     * Supports `{basin}` placeholder anywhere. If no path is present, `/v1` is used.
+     */
+    basin?: string;
+};
+/**
+ * Endpoint configuration for the S2 environment.
+ *
+ * This mirrors the Rust SDK's endpoint model, with an additional capability:
+ * the basin endpoint may include `{basin}` anywhere (hostname and/or path).
+ */
+export declare class S2Endpoints {
+    readonly account: EndpointTemplate;
+    readonly basin: EndpointTemplate;
+    /**
+     * When true, include `s2-basin: <name>` header on basin-scoped requests.
+     *
+     * Per project convention: enabled whenever a non-default basin endpoint is provided.
+     */
+    readonly includeBasinHeader: boolean;
+    constructor(init?: S2EndpointsInit);
+    accountBaseUrl(): string;
+    basinBaseUrl(basin: string): string;
+}
+export {};
+//# sourceMappingURL=endpoints.d.ts.map

package/dist/esm/endpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.d.ts","sourceRoot":"","sources":["../../src/endpoints.ts"],"names":[],"mappings":"AAAA,KAAK,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAwC/B,MAAM,MAAM,oBAAoB,GAAG;IAClC;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,gBAAgB;IAC5B,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,YAAY,EAAE,MAAM,CAAC;IACrC,SAAgB,mBAAmB,EAAE,OAAO,CAAC;IAC7C,SAAgB,oBAAoB,EAAE,OAAO,CAAC;gBAElC,EAAE,QAAQ,EAAE,EAAE,oBAAoB;IAwC9C;;;;;OAKG;IACI,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;CAYtC;AAED,MAAM,MAAM,eAAe,GAAG;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAKF;;;;;GAKG;AACH,qBAAa,WAAW;IACvB,SAAgB,OAAO,EAAE,gBAAgB,CAAC;IAC1C,SAAgB,KAAK,EAAE,gBAAgB,CAAC;IACxC;;;;OAIG;IACH,SAAgB,kBAAkB,EAAE,OAAO,CAAC;gBAEhC,IAAI,CAAC,EAAE,eAAe;IAU3B,cAAc,IAAI,MAAM;IAIxB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAG1C"}

package/dist/esm/endpoints.js

@@ -0,0 +1,115 @@
+const DEFAULT_SCHEME = "https";
+const DEFAULT_API_PATH = "/v1";
+const BASIN_PLACEHOLDER_SENTINEL = "__basin__";
+function hasScheme(input) {
+    return /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(input);
+}
+function firstDelimiterIndex(value, fromIndex) {
+    const slash = value.indexOf("/", fromIndex);
+    const query = value.indexOf("?", fromIndex);
+    const hash = value.indexOf("#", fromIndex);
+    const candidates = [slash, query, hash].filter((idx) => idx !== -1);
+    return candidates.length ? Math.min(...candidates) : -1;
+}
+function hasExplicitPath(input) {
+    const trimmed = input.trim();
+    const schemeMatch = trimmed.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):\/\//);
+    const authorityStart = schemeMatch ? schemeMatch[0].length : 0;
+    const delim = firstDelimiterIndex(trimmed, authorityStart);
+    return delim !== -1 && trimmed[delim] === "/";
+}
+function normalizeForUrlParsing(input) {
+    const trimmed = input.trim();
+    const withScheme = hasScheme(trimmed)
+        ? trimmed
+        : `${DEFAULT_SCHEME}://${trimmed}`;
+    return withScheme.replaceAll("{basin}", BASIN_PLACEHOLDER_SENTINEL);
+}
+function asScheme(protocol) {
+    const normalized = protocol.replace(":", "").toLowerCase();
+    if (normalized === "http" || normalized === "https")
+        return normalized;
+    throw new Error(`Unsupported scheme: ${protocol}`);
+}
+export class EndpointTemplate {
+    raw;
+    scheme;
+    hostTemplate;
+    port;
+    pathTemplate;
+    hasBasinPlaceholder;
+    explicitPathProvided;
+    constructor({ endpoint }) {
+        const raw = endpoint.trim();
+        if (!raw) {
+            throw new Error("Endpoint cannot be empty");
+        }
+        const explicitPathProvided = hasExplicitPath(raw);
+        const parsed = new URL(normalizeForUrlParsing(raw));
+        this.raw = raw;
+        this.scheme = asScheme(parsed.protocol);
+        this.hostTemplate = parsed.hostname.replaceAll(BASIN_PLACEHOLDER_SENTINEL, "{basin}");
+        this.port = parsed.port;
+        const parsedPath = parsed.pathname.replaceAll(BASIN_PLACEHOLDER_SENTINEL, "{basin}");
+        const parsedQuery = parsed.search.replaceAll(BASIN_PLACEHOLDER_SENTINEL, "{basin}");
+        const parsedHash = parsed.hash.replaceAll(BASIN_PLACEHOLDER_SENTINEL, "{basin}");
+        this.pathTemplate = explicitPathProvided
+            ? `${parsedPath}${parsedQuery}${parsedHash}`
+            : DEFAULT_API_PATH;
+        this.explicitPathProvided = explicitPathProvided;
+        this.hasBasinPlaceholder =
+            this.raw.includes("{basin}") ||
+                this.hostTemplate.includes("{basin}") ||
+                this.pathTemplate.includes("{basin}");
+    }
+    /**
+     * Resolve the template into a base URL string.
+     *
+     * - If `{basin}` appears in the hostname, it is substituted verbatim (basin names are validated by S2.basin()).
+     * - If `{basin}` appears in the path/query/hash, it is substituted via `encodeURIComponent`.
+     */
+    baseUrl(basin) {
+        const host = basin
+            ? this.hostTemplate.replaceAll("{basin}", basin)
+            : this.hostTemplate;
+        const path = basin
+            ? this.pathTemplate.replaceAll("{basin}", encodeURIComponent(basin))
+            : this.pathTemplate;
+        const authority = this.port ? `${host}:${this.port}` : host;
+        return `${this.scheme}://${authority}${path}`;
+    }
+}
+const DEFAULT_ACCOUNT_ENDPOINT = "aws.s2.dev";
+const DEFAULT_BASIN_ENDPOINT = "{basin}.b.aws.s2.dev";
+/**
+ * Endpoint configuration for the S2 environment.
+ *
+ * This mirrors the Rust SDK's endpoint model, with an additional capability:
+ * the basin endpoint may include `{basin}` anywhere (hostname and/or path).
+ */
+export class S2Endpoints {
+    account;
+    basin;
+    /**
+     * When true, include `s2-basin: <name>` header on basin-scoped requests.
+     *
+     * Per project convention: enabled whenever a non-default basin endpoint is provided.
+     */
+    includeBasinHeader;
+    constructor(init) {
+        this.account = new EndpointTemplate({
+            endpoint: init?.account ?? DEFAULT_ACCOUNT_ENDPOINT,
+        });
+        this.basin = new EndpointTemplate({
+            endpoint: init?.basin ?? DEFAULT_BASIN_ENDPOINT,
+        });
+        this.includeBasinHeader = init?.basin !== undefined;
+    }
+    accountBaseUrl() {
+        return this.account.baseUrl();
+    }
+    basinBaseUrl(basin) {
+        return this.basin.baseUrl(basin);
+    }
+}
+//# sourceMappingURL=endpoints.js.map

package/dist/esm/endpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoints.js","sourceRoot":"","sources":["../../src/endpoints.ts"],"names":[],"mappings":"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"}

package/dist/esm/error.d.ts

@@ -0,0 +1,119 @@
+export declare function s2Error(error: any): S2Error;
+export declare function withS2Error<T>(fn: () => Promise<T>): Promise<T>;
+/**
+ * Execute a generated client call and return its `data` on success.
+ * Throws S2Error when the response contains `error`, or when the
+ * response has no `data` and is not a 204 No Content.
+ */
+export declare function withS2Data<T>(fn: () => Promise<{
+    data?: T;
+    error?: unknown;
+    response?: {
+        status?: number;
+        statusText?: string;
+    };
+} | T>): Promise<T>;
+/**
+ * Rich error type used by the SDK to surface HTTP and protocol errors.
+ *
+ * - `code` is the service error code when available.
+ * - `status` is the HTTP status code.
+ * - `data` may include structured error details (e.g. for conditional failures).
+ */
+export declare class S2Error extends Error {
+    readonly code?: string;
+    /** HTTP status code. 0 for non-HTTP/internal errors. */
+    readonly status: number;
+    /** Optional structured error details for diagnostics. */
+    readonly data?: unknown;
+    /** Origin of the error: server (HTTP response) or sdk (local). */
+    readonly origin: "server" | "sdk";
+    constructor({ message, code, status, data, origin, }: {
+        message: string;
+        code?: string;
+        status?: number;
+        data?: unknown;
+        origin?: "server" | "sdk";
+    });
+}
+/** Helper: construct a non-retryable invariant violation error (status 0). */
+export declare function invariantViolation(message: string, details?: unknown): S2Error;
+/** Helper: construct an internal SDK error (status 0, never retried). */
+export declare function internalSdkError(message: string, details?: unknown): S2Error;
+/** Helper: construct an aborted/cancelled error (499). */
+export declare function abortedError(message?: string): S2Error;
+/**
+ * Thrown when an append operation fails due to a sequence number mismatch.
+ *
+ * This occurs when you specify a `matchSeqNum` condition in your append request,
+ * but the current tail sequence number of the stream doesn't match.
+ *
+ * The `expectedSeqNum` property contains the actual next sequence number
+ * that should be used for a successful append.
+ */
+export declare class SeqNumMismatchError extends S2Error {
+    /** The expected next sequence number for the stream. */
+    readonly expectedSeqNum: number;
+    constructor({ message, code, status, expectedSeqNum, }: {
+        message: string;
+        code?: string;
+        status?: number;
+        expectedSeqNum: number;
+    });
+}
+/**
+ * Thrown when an append operation fails due to a fencing token mismatch.
+ *
+ * This occurs when you specify a `fencingToken` condition in your append request,
+ * but the current fencing token of the stream doesn't match.
+ *
+ * The `expectedFencingToken` property contains the actual fencing token
+ * that should be used for a successful append.
+ */
+export declare class FencingTokenMismatchError extends S2Error {
+    /** The expected fencing token for the stream. */
+    readonly expectedFencingToken: string;
+    constructor({ message, code, status, expectedFencingToken, }: {
+        message: string;
+        code?: string;
+        status?: number;
+        expectedFencingToken: string;
+    });
+}
+/**
+ * Thrown when a read operation fails because the requested position is beyond the stream tail.
+ *
+ * This occurs when you specify a `startSeqNum` that is greater than the current tail
+ * of the stream (HTTP 416 Range Not Satisfiable).
+ *
+ * The `tail` property contains the current tail position of the stream.
+ *
+ * To handle this gracefully, you can set `clamp: true` in your read options to
+ * automatically start from the tail instead of throwing an error.
+ */
+export declare class RangeNotSatisfiableError extends S2Error {
+    /** The current tail position of the stream. */
+    readonly tail?: {
+        seq_num: number;
+        timestamp: number;
+    };
+    constructor({ code, status, tail, }?: {
+        code?: string;
+        status?: number;
+        tail?: {
+            seq_num: number;
+            timestamp: number;
+        };
+    });
+}
+/**
+ * Build a generic S2Error from HTTP status and optional payload.
+ * If the payload contains a structured { message, code }, those are preferred.
+ */
+export declare function makeServerError(response: {
+    status?: number;
+    statusText?: string;
+}, payload?: unknown): S2Error;
+/** Map 412 Precondition Failed append errors to rich error types. */
+export declare function makeAppendPreconditionError(status: number, json: any): S2Error;
+//# sourceMappingURL=error.d.ts.map

package/dist/esm/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/error.ts"],"names":[],"mappings":"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"}

package/dist/esm/error.js

@@ -0,0 +1,358 @@
+function getErrorCode(error) {
+    if (!(error instanceof Error))
+        return undefined;
+    const err = error;
+    if (typeof err.code === "string")
+        return err.code;
+    if (err.cause && typeof err.cause === "object") {
+        const cause = err.cause;
+        if (typeof cause.code === "string") {
+            return cause.code;
+        }
+    }
+    return undefined;
+}
+function isConnectionError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    if (error.message.includes("fetch failed")) {
+        return true;
+    }
+    const code = getErrorCode(error);
+    // Common connection error codes from Node.js net module
+    const connectionErrorCodes = [
+        "ECONNREFUSED", // Connection refused
+        "ENOTFOUND", // DNS lookup failed
+        "ETIMEDOUT", // Connection timeout
+        "ENETUNREACH", // Network unreachable
+        "EHOSTUNREACH", // Host unreachable
+        "ECONNRESET", // Connection reset by peer
+        "EPIPE", // Broken pipe
+    ];
+    return typeof code === "string" && connectionErrorCodes.includes(code);
+}
+export function s2Error(error) {
+    if (error instanceof S2Error) {
+        return error;
+    }
+    // Connection error?
+    if (isConnectionError(error)) {
+        const code = getErrorCode(error) ?? "NETWORK_ERROR";
+        // DNS failures are typically not transient - don't retry
+        if (code === "ENOTFOUND") {
+            return new S2Error({
+                message: `DNS resolution failed (ENOTFOUND)`,
+                code,
+                status: 400, // Client error - not retryable
+                origin: "sdk",
+            });
+        }
+        // Other connection errors are transient - retryable
+        return new S2Error({
+            message: `Connection failed: ${code}`,
+            code,
+            status: 502, // Bad Gateway for upstream/network issues
+            origin: "sdk",
+        });
+    }
+    // Abort error?
+    if (error instanceof Error && error.name === "AbortError") {
+        return new S2Error({
+            message: "Request cancelled",
+            status: 499, // Client Closed Request (nginx non-standard)
+            origin: "sdk",
+        });
+    }
+    // Other unknown errors
+    return new S2Error({
+        message: error instanceof Error ? error.message : "Unknown error",
+        status: 0, // Non-HTTP/internal error sentinel
+        origin: "sdk",
+    });
+}
+export async function withS2Error(fn) {
+    try {
+        const result = await fn();
+        // Support response-parsing mode (throwOnError=false):
+        // Generated client responses have shape { data, error?, response }
+        if (result &&
+            typeof result === "object" &&
+            Object.prototype.hasOwnProperty.call(result, "error")) {
+            const err = result.error;
+            if (err) {
+                const status = result.response?.status ?? 500;
+                const statusText = result.response?.statusText;
+                // If server provided structured error with message/code, use it
+                if (typeof err === "object" && "message" in err) {
+                    const structured = err;
+                    throw new S2Error({
+                        message: typeof structured.message === "string"
+                            ? structured.message
+                            : (statusText ?? "Error"),
+                        code: typeof structured.code === "string" ? structured.code : undefined,
+                        status,
+                        origin: "server",
+                    });
+                }
+                // Fallback: synthesize from HTTP response metadata
+                throw new S2Error({
+                    message: statusText ?? "Request failed",
+                    status,
+                    origin: "server",
+                });
+            }
+        }
+        return result;
+    }
+    catch (error) {
+        // Network and other thrown errors
+        throw s2Error(error);
+    }
+}
+/**
+ * Execute a generated client call and return its `data` on success.
+ * Throws S2Error when the response contains `error`, or when the
+ * response has no `data` and is not a 204 No Content.
+ */
+export async function withS2Data(fn) {
+    try {
+        const res = await fn();
+        if (res &&
+            typeof res === "object" &&
+            (Object.prototype.hasOwnProperty.call(res, "error") ||
+                Object.prototype.hasOwnProperty.call(res, "data") ||
+                Object.prototype.hasOwnProperty.call(res, "response"))) {
+            const status = res.response?.status ?? 500;
+            const statusText = res.response?.statusText;
+            if (res.error) {
+                const err = res.error;
+                if (typeof err === "object" && "message" in err) {
+                    const structured = err;
+                    throw new S2Error({
+                        message: typeof structured.message === "string"
+                            ? structured.message
+                            : (statusText ?? "Error"),
+                        code: typeof structured.code === "string" ? structured.code : undefined,
+                        status,
+                        origin: "server",
+                    });
+                }
+                throw new S2Error({
+                    message: statusText ?? "Request failed",
+                    status,
+                    origin: "server",
+                });
+            }
+            // No error
+            if (typeof res.data !== "undefined")
+                return res.data;
+            // Treat 204 as success for void endpoints
+            if (status === 204)
+                return undefined;
+            throw new S2Error({
+                message: "Empty response",
+                status,
+                origin: "server",
+            });
+        }
+        // Not a generated client response; return as-is
+        return res;
+    }
+    catch (error) {
+        throw s2Error(error);
+    }
+}
+/**
+ * Rich error type used by the SDK to surface HTTP and protocol errors.
+ *
+ * - `code` is the service error code when available.
+ * - `status` is the HTTP status code.
+ * - `data` may include structured error details (e.g. for conditional failures).
+ */
+export class S2Error extends Error {
+    code;
+    /** HTTP status code. 0 for non-HTTP/internal errors. */
+    status;
+    /** Optional structured error details for diagnostics. */
+    data;
+    /** Origin of the error: server (HTTP response) or sdk (local). */
+    origin;
+    constructor({ message, code, status, data, origin, }) {
+        super(message);
+        this.code = code;
+        // Ensure status is always a number (0 for non-HTTP/internal errors)
+        this.status = typeof status === "number" ? status : 0;
+        this.data = data;
+        this.origin = origin ?? "sdk";
+        this.name = "S2Error";
+    }
+}
+/** Helper: construct a non-retryable invariant violation error (status 0). */
+export function invariantViolation(message, details) {
+    return new S2Error({
+        message: `Invariant violation: ${message}`,
+        code: "INTERNAL_ERROR",
+        status: 0,
+        origin: "sdk",
+        data: details,
+    });
+}
+/** Helper: construct an internal SDK error (status 0, never retried). */
+export function internalSdkError(message, details) {
+    return new S2Error({
+        message: `Internal SDK error: ${message}`,
+        code: "INTERNAL_SDK_ERROR",
+        status: 0,
+        origin: "sdk",
+        data: details,
+    });
+}
+/** Helper: construct an aborted/cancelled error (499). */
+export function abortedError(message = "Request cancelled") {
+    return new S2Error({
+        message,
+        code: "ABORTED",
+        status: 499,
+        origin: "sdk",
+    });
+}
+/**
+ * Thrown when an append operation fails due to a sequence number mismatch.
+ *
+ * This occurs when you specify a `matchSeqNum` condition in your append request,
+ * but the current tail sequence number of the stream doesn't match.
+ *
+ * The `expectedSeqNum` property contains the actual next sequence number
+ * that should be used for a successful append.
+ */
+export class SeqNumMismatchError extends S2Error {
+    /** The expected next sequence number for the stream. */
+    expectedSeqNum;
+    constructor({ message, code, status, expectedSeqNum, }) {
+        super({
+            message: `${message}\nExpected sequence number: ${expectedSeqNum}`,
+            code,
+            status,
+            origin: "server",
+        });
+        this.name = "SeqNumMismatchError";
+        this.expectedSeqNum = expectedSeqNum;
+    }
+}
+/**
+ * Thrown when an append operation fails due to a fencing token mismatch.
+ *
+ * This occurs when you specify a `fencingToken` condition in your append request,
+ * but the current fencing token of the stream doesn't match.
+ *
+ * The `expectedFencingToken` property contains the actual fencing token
+ * that should be used for a successful append.
+ */
+export class FencingTokenMismatchError extends S2Error {
+    /** The expected fencing token for the stream. */
+    expectedFencingToken;
+    constructor({ message, code, status, expectedFencingToken, }) {
+        super({
+            message: `${message}\nExpected fencing token: ${expectedFencingToken}`,
+            code,
+            status,
+            origin: "server",
+        });
+        this.name = "FencingTokenMismatchError";
+        this.expectedFencingToken = expectedFencingToken;
+    }
+}
+/**
+ * Thrown when a read operation fails because the requested position is beyond the stream tail.
+ *
+ * This occurs when you specify a `startSeqNum` that is greater than the current tail
+ * of the stream (HTTP 416 Range Not Satisfiable).
+ *
+ * The `tail` property contains the current tail position of the stream.
+ *
+ * To handle this gracefully, you can set `clamp: true` in your read options to
+ * automatically start from the tail instead of throwing an error.
+ */
+export class RangeNotSatisfiableError extends S2Error {
+    /** The current tail position of the stream. */
+    tail;
+    constructor({ code, status = 416, tail, } = {}) {
+        const message = tail
+            ? `Range not satisfiable: requested position is beyond the stream tail (seq_num=${tail.seq_num}). Use 'clamp: true' to start from the tail instead.`
+            : "Range not satisfiable: requested position is beyond the stream tail. Use 'clamp: true' to start from the tail instead.";
+        super({
+            message,
+            code,
+            status,
+            origin: "server",
+        });
+        this.name = "RangeNotSatisfiableError";
+        this.tail = tail;
+    }
+}
+/**
+ * Build a generic S2Error from HTTP status and optional payload.
+ * If the payload contains a structured { message, code }, those are preferred.
+ */
+export function makeServerError(response, payload) {
+    const status = typeof response.status === "number" ? response.status : 500;
+    // Pull message/code from structured payload when present
+    if (payload && typeof payload === "object" && "message" in payload) {
+        const structured = payload;
+        return new S2Error({
+            message: typeof structured.message === "string"
+                ? structured.message
+                : (response.statusText ?? "Error"),
+            code: typeof structured.code === "string" ? structured.code : undefined,
+            status,
+            origin: "server",
+        });
+    }
+    // Fallbacks
+    let message = undefined;
+    if (typeof payload === "string" && payload.trim().length > 0) {
+        message = payload;
+    }
+    return new S2Error({
+        message: message ?? response.statusText ?? "Request failed",
+        status,
+        origin: "server",
+    });
+}
+/** Map 412 Precondition Failed append errors to rich error types. */
+export function makeAppendPreconditionError(status, json) {
+    if (json && typeof json === "object") {
+        if ("seq_num_mismatch" in json) {
+            const expected = Number(json.seq_num_mismatch);
+            return new SeqNumMismatchError({
+                message: "Append condition failed: sequence number mismatch",
+                code: "APPEND_CONDITION_FAILED",
+                status,
+                expectedSeqNum: expected,
+            });
+        }
+        if ("fencing_token_mismatch" in json) {
+            const expected = String(json.fencing_token_mismatch);
+            return new FencingTokenMismatchError({
+                message: "Append condition failed: fencing token mismatch",
+                code: "APPEND_CONDITION_FAILED",
+                status,
+                expectedFencingToken: expected,
+            });
+        }
+        if ("message" in json) {
+            return new S2Error({
+                message: json.message ?? "Append condition failed",
+                status,
+                origin: "server",
+            });
+        }
+    }
+    return new S2Error({
+        message: "Append condition failed",
+        status,
+        origin: "server",
+    });
+}
+//# sourceMappingURL=error.js.map