@polyester/sdk 0.0.0

package/dist/shared/connect-error-mapping.d.ts

@@ -0,0 +1,23 @@
+import { PolyesterError } from "./errors.js";
+import { ConnectError, Interceptor } from "@connectrpc/connect";
+//#region src/shared/connect-error-mapping.d.ts
+/**
+ * Maps a `ConnectError` from the Polyester backend onto the typed
+ * {@link PolyesterError} tree. The original error is preserved as `cause`.
+ */
+declare function connectErrorToPolyesterError(ce: ConnectError): PolyesterError;
+/**
+ * Converts any RPC-layer failure into its typed SDK error. Abort errors and
+ * caller-cancelled requests pass through unchanged, as do errors that are
+ * already typed (e.g. a `NetworkError` from the SDK fetch wrapper).
+ */
+declare function toPolyesterError(err: unknown): unknown;
+/**
+ * Interceptor that converts every RPC failure (unary and streaming) into the
+ * typed {@link PolyesterError} hierarchy. Installed outermost by
+ * `createTransports`, so callers of SDK services always see typed errors.
+ */
+declare function createErrorMappingInterceptor(): Interceptor;
+//#endregion
+export { connectErrorToPolyesterError, createErrorMappingInterceptor, toPolyesterError };
+//# sourceMappingURL=connect-error-mapping.d.ts.map

package/dist/shared/connect-error-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-error-mapping.d.ts","names":[],"sources":["../../src/shared/connect-error-mapping.ts"],"mappings":";;;;;;;iBA+FgB,6BAA6B,IAAI,eAAe;;;;;;iBA6HhD,iBAAiB;;;;;;iBAyBjB,iCAAiC"}

package/dist/shared/connect-error-mapping.js

@@ -0,0 +1,147 @@
+import { AuthErrorDetailSchema } from "../gen/auth/v1/auth_pb.js";
+import { ErrorDetailSchema } from "../gen/orders/v1/orders_pb.js";
+import { AlreadyExistsError, AuthenticationError, InternalServerError, MfaEnrollmentRequiredError, MfaLastFactorRequiredError, MfaVerificationError, PermissionError, PolicyInUseError, PolicyLockedError, PolicyScopeMismatchError, PolyesterError, PreconditionFailedError, RateLimitError, ResourceNotFoundError, RevisionConflictError, ServiceUnavailableError, SessionElevationRequiredError, StaleQuoteError, StepUpRequiredError, TimeoutError, TransientError, ValidationError, isAbortError, normalizeErrorMessage } from "./errors.js";
+import { Code, ConnectError } from "@connectrpc/connect";
+//#region src/shared/connect-error-mapping.ts
+function getAuthErrorDetails(err) {
+	return ConnectError.from(err).findDetails(AuthErrorDetailSchema);
+}
+function hasAuthErrorCode(err, code) {
+	return getAuthErrorDetails(err).some((detail) => detail.code === code);
+}
+function hasOrderErrorCode(err, code) {
+	return ConnectError.from(err).findDetails(ErrorDetailSchema).some((detail) => detail.code === code);
+}
+/**
+* Returns the error message without the leading "[code] " prefix that
+* `ConnectError` prepends, e.g. "[invalid_argument] Insufficient funds."
+* becomes "Insufficient funds.".
+*/
+function getNormalizedConnectMessage(err) {
+	const raw = ConnectError.from(err).message ?? "";
+	return normalizeErrorMessage(raw);
+}
+/**
+* Classifies an error as one of the MFA flows the backend can demand.
+* Classification is based only on stable structured auth error details.
+*/
+function detectMfaErrorKind(err) {
+	if (hasAuthErrorCode(err, 38)) return "session-elevation";
+	if (hasAuthErrorCode(err, 31)) return "step-up";
+	if (hasAuthErrorCode(err, 20)) return "enrollment";
+	return null;
+}
+function parseRetryAfterMs(ce) {
+	const value = ce.metadata.get("retry-after");
+	if (!value) return void 0;
+	const seconds = Number(value);
+	if (Number.isFinite(seconds)) return Math.max(0, Math.round(seconds * 1e3));
+	const date = Date.parse(value);
+	if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+}
+const MFA_ERROR_CLASSES = {
+	"session-elevation": SessionElevationRequiredError,
+	enrollment: MfaEnrollmentRequiredError,
+	"step-up": StepUpRequiredError
+};
+/**
+* Maps a `ConnectError` from the Polyester backend onto the typed
+* {@link PolyesterError} tree. The original error is preserved as `cause`.
+*/
+function connectErrorToPolyesterError(ce) {
+	const message = getNormalizedConnectMessage(ce);
+	const options = { cause: ce };
+	const withFallback = (fallback) => message || fallback;
+	if (hasAuthErrorCode(ce, 10)) return new ResourceNotFoundError(withFallback("Resource not found."), options);
+	if (hasAuthErrorCode(ce, 37)) return new RevisionConflictError(withFallback("Resource changed since it was last read."), options);
+	if (hasAuthErrorCode(ce, 34)) return new PolicyInUseError(withFallback("Policy is still in use."), options);
+	if (hasAuthErrorCode(ce, 35)) return new PolicyLockedError(withFallback("Policy is locked."), options);
+	if (hasAuthErrorCode(ce, 36)) return new PolicyScopeMismatchError(withFallback("Policy does not belong to the target account scope."), options);
+	if (hasAuthErrorCode(ce, 39)) return new MfaLastFactorRequiredError(withFallback("At least one active MFA factor must remain enrolled."), options);
+	const mfaVerificationReason = getMfaVerificationFailureReason(ce);
+	if (mfaVerificationReason) return new MfaVerificationError(withFallback("MFA verification failed."), mfaVerificationReason, options);
+	const mfaKind = detectMfaErrorKind(ce);
+	if (mfaKind) return new MFA_ERROR_CLASSES[mfaKind](withFallback("Multi-factor authentication required."), options);
+	if (hasOrderErrorCode(ce, 65)) return new StaleQuoteError(withFallback("The submitted market quote is stale."), options);
+	switch (ce.code) {
+		case Code.InvalidArgument:
+		case Code.OutOfRange: return new ValidationError(withFallback("Invalid request."), options);
+		case Code.NotFound: return new ResourceNotFoundError(withFallback("Resource not found."), options);
+		case Code.AlreadyExists: return new AlreadyExistsError(withFallback("Resource already exists."), options);
+		case Code.PermissionDenied: return new PermissionError(withFallback("Permission denied."), options);
+		case Code.Unauthenticated: return new AuthenticationError(withFallback("Authentication required."), options);
+		case Code.FailedPrecondition: return new PreconditionFailedError(withFallback("Precondition failed."), options);
+		case Code.ResourceExhausted: return new RateLimitError(withFallback("Rate limit exceeded."), {
+			...options,
+			retryAfterMs: parseRetryAfterMs(ce)
+		});
+		case Code.DeadlineExceeded: return new TimeoutError(withFallback("Request timed out."), options);
+		case Code.Unavailable: return new ServiceUnavailableError(withFallback("Service unavailable."), options);
+		case Code.Aborted: return new TransientError(withFallback("Operation aborted by the backend."), options);
+		default:
+			if (/service temporarily unavailable/i.test(message)) return new ServiceUnavailableError(withFallback("Service unavailable."), options);
+			return new InternalServerError(withFallback("Internal server error."), options);
+	}
+}
+function getMfaVerificationFailureReason(err) {
+	if (hasAuthErrorCode(err, 23)) return "challenge-invalid";
+	if (hasAuthErrorCode(err, 24)) return "challenge-locked";
+	if (hasAuthErrorCode(err, 25)) return "otp-invalid";
+	if (hasAuthErrorCode(err, 26)) return "recovery-code-invalid";
+	if (hasAuthErrorCode(err, 28) || hasAuthErrorCode(err, 29)) return "passkey-invalid";
+	return null;
+}
+function findPolyesterErrorInCauseChain(err) {
+	let current = err;
+	for (let depth = 0; depth < 5 && current instanceof Error; depth++) {
+		current = current.cause;
+		if (current instanceof PolyesterError) return current;
+	}
+	return null;
+}
+/**
+* Converts any RPC-layer failure into its typed SDK error. Abort errors and
+* caller-cancelled requests pass through unchanged, as do errors that are
+* already typed (e.g. a `NetworkError` from the SDK fetch wrapper).
+*/
+function toPolyesterError(err) {
+	if (err instanceof PolyesterError) return err;
+	if (isAbortError(err)) return err;
+	if (err instanceof ConnectError) {
+		if (err.code === Code.Canceled) return err;
+		const wrapped = findPolyesterErrorInCauseChain(err);
+		if (wrapped) return wrapped;
+		return connectErrorToPolyesterError(err);
+	}
+	return err;
+}
+async function* mapStreamErrors(source) {
+	try {
+		yield* source;
+	} catch (err) {
+		throw toPolyesterError(err);
+	}
+}
+/**
+* Interceptor that converts every RPC failure (unary and streaming) into the
+* typed {@link PolyesterError} hierarchy. Installed outermost by
+* `createTransports`, so callers of SDK services always see typed errors.
+*/
+function createErrorMappingInterceptor() {
+	return (next) => async (req) => {
+		try {
+			const res = await next(req);
+			if (res.stream) return {
+				...res,
+				message: mapStreamErrors(res.message)
+			};
+			return res;
+		} catch (err) {
+			throw toPolyesterError(err);
+		}
+	};
+}
+//#endregion
+export { connectErrorToPolyesterError, createErrorMappingInterceptor, detectMfaErrorKind, getNormalizedConnectMessage, toPolyesterError };
+
+//# sourceMappingURL=connect-error-mapping.js.map

package/dist/shared/connect-error-mapping.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect-error-mapping.js","names":["OrderErrorDetailSchema"],"sources":["../../src/shared/connect-error-mapping.ts"],"sourcesContent":["import { Code, ConnectError, type Interceptor } from \"@connectrpc/connect\";\nimport { AuthErrorCode, AuthErrorDetailSchema } from \"../gen/auth/v1/auth_pb.js\";\nimport {\n    ErrorCode as OrderErrorCode,\n    ErrorDetailSchema as OrderErrorDetailSchema,\n} from \"../gen/orders/v1/orders_pb.js\";\nimport {\n    AlreadyExistsError,\n    AuthenticationError,\n    InternalServerError,\n    isAbortError,\n    MfaEnrollmentRequiredError,\n    MfaLastFactorRequiredError,\n    MfaVerificationError,\n    type MfaVerificationFailureReason,\n    normalizeErrorMessage,\n    PermissionError,\n    PolicyInUseError,\n    PolicyLockedError,\n    PolicyScopeMismatchError,\n    PolyesterError,\n    type PolyesterErrorOptions,\n    PreconditionFailedError,\n    RateLimitError,\n    ResourceNotFoundError,\n    RevisionConflictError,\n    ServiceUnavailableError,\n    SessionElevationRequiredError,\n    StaleQuoteError,\n    StepUpRequiredError,\n    TimeoutError,\n    TransientError,\n    ValidationError,\n} from \"./errors.js\";\n\nfunction getAuthErrorDetails(err: unknown) {\n    return ConnectError.from(err).findDetails(AuthErrorDetailSchema);\n}\n\nfunction hasAuthErrorCode(err: unknown, code: AuthErrorCode): boolean {\n    return getAuthErrorDetails(err).some((detail) => detail.code === code);\n}\n\nfunction hasOrderErrorCode(err: unknown, code: OrderErrorCode): boolean {\n    return ConnectError.from(err)\n        .findDetails(OrderErrorDetailSchema)\n        .some((detail) => detail.code === code);\n}\n\n/**\n * Returns the error message without the leading \"[code] \" prefix that\n * `ConnectError` prepends, e.g. \"[invalid_argument] Insufficient funds.\"\n * becomes \"Insufficient funds.\".\n */\nexport function getNormalizedConnectMessage(err: unknown): string {\n    const ce = ConnectError.from(err);\n    const raw = ce.message ?? \"\";\n    return normalizeErrorMessage(raw);\n}\n\nexport type MfaErrorKind = \"session-elevation\" | \"enrollment\" | \"step-up\";\n\n/**\n * Classifies an error as one of the MFA flows the backend can demand.\n * Classification is based only on stable structured auth error details.\n */\nexport function detectMfaErrorKind(err: unknown): MfaErrorKind | null {\n    if (hasAuthErrorCode(err, AuthErrorCode.AUTH_MFA_ELEVATION_REQUIRED)) {\n        return \"session-elevation\";\n    }\n    if (hasAuthErrorCode(err, AuthErrorCode.AUTH_STEP_UP_REQUIRED)) return \"step-up\";\n    if (hasAuthErrorCode(err, AuthErrorCode.AUTH_MFA_NOT_ENROLLED)) return \"enrollment\";\n    return null;\n}\n\nfunction parseRetryAfterMs(ce: ConnectError): number | undefined {\n    const value = ce.metadata.get(\"retry-after\");\n    if (!value) return undefined;\n    const seconds = Number(value);\n    if (Number.isFinite(seconds)) return Math.max(0, Math.round(seconds * 1000));\n    const date = Date.parse(value);\n    if (!Number.isNaN(date)) return Math.max(0, date - Date.now());\n    return undefined;\n}\n\nconst MFA_ERROR_CLASSES = {\n    \"session-elevation\": SessionElevationRequiredError,\n    enrollment: MfaEnrollmentRequiredError,\n    \"step-up\": StepUpRequiredError,\n} as const;\n\n/**\n * Maps a `ConnectError` from the Polyester backend onto the typed\n * {@link PolyesterError} tree. The original error is preserved as `cause`.\n */\nexport function connectErrorToPolyesterError(ce: ConnectError): PolyesterError {\n    const message = getNormalizedConnectMessage(ce);\n    const options: PolyesterErrorOptions = { cause: ce };\n    const withFallback = (fallback: string) => message || fallback;\n\n    if (hasAuthErrorCode(ce, AuthErrorCode.AUTH_RESOURCE_NOT_FOUND)) {\n        return new ResourceNotFoundError(withFallback(\"Resource not found.\"), options);\n    }\n\n    if (hasAuthErrorCode(ce, AuthErrorCode.AUTH_REVISION_CONFLICT)) {\n        return new RevisionConflictError(\n            withFallback(\"Resource changed since it was last read.\"),\n            options,\n        );\n    }\n\n    if (hasAuthErrorCode(ce, AuthErrorCode.AUTH_POLICY_IN_USE)) {\n        return new PolicyInUseError(withFallback(\"Policy is still in use.\"), options);\n    }\n    if (hasAuthErrorCode(ce, AuthErrorCode.AUTH_POLICY_LOCKED)) {\n        return new PolicyLockedError(withFallback(\"Policy is locked.\"), options);\n    }\n    if (hasAuthErrorCode(ce, AuthErrorCode.AUTH_POLICY_SCOPE_MISMATCH)) {\n        return new PolicyScopeMismatchError(\n            withFallback(\"Policy does not belong to the target account scope.\"),\n            options,\n        );\n    }\n    if (hasAuthErrorCode(ce, AuthErrorCode.AUTH_MFA_LAST_FACTOR_REQUIRED)) {\n        return new MfaLastFactorRequiredError(\n            withFallback(\"At least one active MFA factor must remain enrolled.\"),\n            options,\n        );\n    }\n\n    const mfaVerificationReason = getMfaVerificationFailureReason(ce);\n    if (mfaVerificationReason) {\n        return new MfaVerificationError(\n            withFallback(\"MFA verification failed.\"),\n            mfaVerificationReason,\n            options,\n        );\n    }\n\n    const mfaKind = detectMfaErrorKind(ce);\n    if (mfaKind) {\n        return new MFA_ERROR_CLASSES[mfaKind](\n            withFallback(\"Multi-factor authentication required.\"),\n            options,\n        );\n    }\n\n    if (hasOrderErrorCode(ce, OrderErrorCode.STALE_QUOTE)) {\n        return new StaleQuoteError(withFallback(\"The submitted market quote is stale.\"), options);\n    }\n\n    switch (ce.code) {\n        case Code.InvalidArgument:\n        case Code.OutOfRange:\n            return new ValidationError(withFallback(\"Invalid request.\"), options);\n        case Code.NotFound:\n            return new ResourceNotFoundError(withFallback(\"Resource not found.\"), options);\n        case Code.AlreadyExists:\n            return new AlreadyExistsError(withFallback(\"Resource already exists.\"), options);\n        case Code.PermissionDenied:\n            return new PermissionError(withFallback(\"Permission denied.\"), options);\n        case Code.Unauthenticated:\n            return new AuthenticationError(withFallback(\"Authentication required.\"), options);\n        case Code.FailedPrecondition:\n            return new PreconditionFailedError(withFallback(\"Precondition failed.\"), options);\n        case Code.ResourceExhausted:\n            return new RateLimitError(withFallback(\"Rate limit exceeded.\"), {\n                ...options,\n                retryAfterMs: parseRetryAfterMs(ce),\n            });\n        case Code.DeadlineExceeded:\n            return new TimeoutError(withFallback(\"Request timed out.\"), options);\n        case Code.Unavailable:\n            return new ServiceUnavailableError(withFallback(\"Service unavailable.\"), options);\n        case Code.Aborted:\n            return new TransientError(withFallback(\"Operation aborted by the backend.\"), options);\n        default:\n            // Gateways sometimes surface outages as Unknown with this stock phrase.\n            if (/service temporarily unavailable/i.test(message)) {\n                return new ServiceUnavailableError(withFallback(\"Service unavailable.\"), options);\n            }\n            return new InternalServerError(withFallback(\"Internal server error.\"), options);\n    }\n}\n\nfunction getMfaVerificationFailureReason(err: unknown): MfaVerificationFailureReason | null {\n    if (hasAuthErrorCode(err, AuthErrorCode.AUTH_MFA_CHALLENGE_INVALID)) {\n        return \"challenge-invalid\";\n    }\n    if (hasAuthErrorCode(err, AuthErrorCode.AUTH_MFA_CHALLENGE_LOCKED)) {\n        return \"challenge-locked\";\n    }\n    if (hasAuthErrorCode(err, AuthErrorCode.AUTH_MFA_OTP_INVALID)) return \"otp-invalid\";\n    if (hasAuthErrorCode(err, AuthErrorCode.AUTH_MFA_RECOVERY_INVALID)) {\n        return \"recovery-code-invalid\";\n    }\n    if (\n        hasAuthErrorCode(err, AuthErrorCode.AUTH_MFA_PASSKEY_CREDENTIAL_INVALID) ||\n        hasAuthErrorCode(err, AuthErrorCode.AUTH_MFA_PASSKEY_VERIFY_FAILED)\n    ) {\n        return \"passkey-invalid\";\n    }\n\n    return null;\n}\n\nfunction findPolyesterErrorInCauseChain(err: unknown): PolyesterError | null {\n    let current: unknown = err;\n    for (let depth = 0; depth < 5 && current instanceof Error; depth++) {\n        current = current.cause;\n        if (current instanceof PolyesterError) return current;\n    }\n    return null;\n}\n\n/**\n * Converts any RPC-layer failure into its typed SDK error. Abort errors and\n * caller-cancelled requests pass through unchanged, as do errors that are\n * already typed (e.g. a `NetworkError` from the SDK fetch wrapper).\n */\nexport function toPolyesterError(err: unknown): unknown {\n    if (err instanceof PolyesterError) return err;\n    if (isAbortError(err)) return err;\n    if (err instanceof ConnectError) {\n        if (err.code === Code.Canceled) return err;\n        const wrapped = findPolyesterErrorInCauseChain(err);\n        if (wrapped) return wrapped;\n        return connectErrorToPolyesterError(err);\n    }\n    return err;\n}\n\nasync function* mapStreamErrors<T>(source: AsyncIterable<T>): AsyncIterable<T> {\n    try {\n        yield* source;\n    } catch (err) {\n        throw toPolyesterError(err);\n    }\n}\n\n/**\n * Interceptor that converts every RPC failure (unary and streaming) into the\n * typed {@link PolyesterError} hierarchy. Installed outermost by\n * `createTransports`, so callers of SDK services always see typed errors.\n */\nexport function createErrorMappingInterceptor(): Interceptor {\n    return (next) => async (req) => {\n        try {\n            const res = await next(req);\n            if (res.stream) {\n                return { ...res, message: mapStreamErrors(res.message) };\n            }\n            return res;\n        } catch (err) {\n            throw toPolyesterError(err);\n        }\n    };\n}\n"],"mappings":"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"}

package/dist/shared/decimal-surface.d.ts

@@ -0,0 +1,18 @@
+import { PairCatalogKey } from "../catalogs/types.js";
+//#region src/shared/decimal-surface.d.ts
+/**
+ * Resolves wire scales for the SDK's internal decimal conversion. Backed by
+ * the client catalog; `ready()` must be awaited before the synchronous lookups
+ * are used so the catalog can answer them.
+ */
+interface SdkScales {
+  ready(): Promise<void>;
+  price(): number;
+  baseQty(pair: PairCatalogKey): number;
+  quoteAmount(pair: PairCatalogKey): number;
+  ledgerAmount(ledgerAssetId: number): number;
+  zippedAssetAmount(zippedAssetId: number): number;
+}
+//#endregion
+export { SdkScales };
+//# sourceMappingURL=decimal-surface.d.ts.map

package/dist/shared/decimal-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimal-surface.d.ts","names":[],"sources":["../../src/shared/decimal-surface.ts"],"mappings":";;;;;;;UA6BiB;EACb,SAAS;EACT;EACA,QAAQ,MAAM;EACd,YAAY,MAAM;EAClB,aAAa;EACb,kBAAkB"}

package/dist/shared/decimal-surface.js

@@ -0,0 +1,89 @@
+import { scaledToDecimal, tryDecimalToScaled } from "../catalogs/decimal.js";
+import { CatalogConversionError } from "../catalogs/types.js";
+/**
+* Catalog-backed scale resolver. Takes a getter so it can be constructed
+* before the owning client has assigned its catalog.
+*/
+function createCatalogSdkScales(getCatalog) {
+	return {
+		ready: async () => {
+			await getCatalog().ensureReady();
+		},
+		price: () => 6,
+		baseQty: (pair) => requirePair(getCatalog(), pair).baseAsset.quantityScale,
+		quoteAmount: (pair) => requirePair(getCatalog(), pair).quoteAsset.quantityScale,
+		ledgerAmount: (ledgerAssetId) => getCatalog().ledger.requireAssetByLedgerId(ledgerAssetId).quantityScale,
+		zippedAssetAmount: (zippedAssetId) => getCatalog().zipper.requireAssetChainByZippedAssetId(zippedAssetId).asset.quantityScale
+	};
+}
+function requirePair(catalog, pair) {
+	return typeof pair === "string" || typeof pair === "object" && "symbol" in pair ? catalog.market.requirePairBySymbol(typeof pair === "string" ? pair : pair.symbol) : catalog.market.requirePairBySymbolId(typeof pair === "number" ? pair : pair.symbolId);
+}
+/** Output direction: exact scaled→decimal conversion (`1500000n`@6 → `"1.5"`). */
+function scaledToDecimalOutput(value, scale) {
+	return scaledToDecimal(value, scale);
+}
+function conversionFailureMessage(field, value, failure) {
+	return failure.reason === "precision" ? `${field} supports at most ${failure.maxDecimals} decimal places: ${value}` : `${field} must be a non-negative decimal number: ${value}`;
+}
+/**
+* Input direction: strict decimal→scaled conversion. Throws
+* CatalogConversionError for non-decimal input or excess precision.
+*/
+function decimalInputToScaled(field, value, scale) {
+	const result = tryDecimalToScaled(value.trim(), scale);
+	if (!result.ok) throw new CatalogConversionError(field, conversionFailureMessage(field, value, result.failure));
+	return result.scaled;
+}
+/** Like decimalInputToScaled, but additionally requires a value greater than zero. */
+function positiveDecimalInputToScaled(field, value, scale) {
+	const scaled = decimalInputToScaled(field, value, scale);
+	if (scaled <= 0n) throw new CatalogConversionError(field, `${field} must be greater than 0: ${value}`);
+	return scaled;
+}
+/**
+* Decimal quantity → PolyesterChain E18 ledger units.
+* Input precision is capped at the asset's quantityScale; the wire value is
+* always upscaled to E18 (trading balances / amount_e18 convention).
+*/
+function quantityInputToE18(params) {
+	const field = params.field ?? "quantity";
+	const assetScale = params.scales.ledgerAmount(params.assetId);
+	if (assetScale > 18) throw new CatalogConversionError(field, `${field} asset quantityScale ${assetScale} exceeds E18 ledger scale`);
+	return positiveDecimalInputToScaled(field, params.quantity, assetScale) * 10n ** BigInt(18 - assetScale);
+}
+/**
+* Orders event delivery behind catalog readiness. Events arriving before the
+* catalog can resolve scales are queued and flushed in arrival order once it
+* is ready; delivery errors (including post-flush ones) route to `onError`
+* instead of escaping into the transport, mirroring the realtime client's
+* consumer-handler isolation. If readiness itself fails, queued events are
+* dropped after `onError` fires — the stream cannot be decoded without scales.
+*/
+function createReadyGate(ready, onError) {
+	let state = "pending";
+	const queue = [];
+	const deliverIsolated = (deliver) => {
+		try {
+			deliver();
+		} catch (error) {
+			onError?.(error);
+		}
+	};
+	ready().then(() => {
+		state = "open";
+		for (const deliver of queue.splice(0)) deliverIsolated(deliver);
+	}, (error) => {
+		state = "failed";
+		queue.length = 0;
+		onError?.(error);
+	});
+	return { run(deliver) {
+		if (state === "open") deliverIsolated(deliver);
+		else if (state === "pending") queue.push(deliver);
+	} };
+}
+//#endregion
+export { createCatalogSdkScales, createReadyGate, decimalInputToScaled, positiveDecimalInputToScaled, quantityInputToE18, scaledToDecimalOutput };
+
+//# sourceMappingURL=decimal-surface.js.map

package/dist/shared/decimal-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decimal-surface.js","names":[],"sources":["../../src/shared/decimal-surface.ts"],"sourcesContent":["/**\n * Internal scaled⇄decimal bridge for the SDK's public decimal-string surface.\n *\n * The wire protocol carries scaled integers (price ticks, per-asset scaled\n * quantities); the public SDK surface carries plain decimal strings. Output\n * schemas convert exactly (no rounding, trailing zeros trimmed); input schemas\n * convert strictly — excess precision is an error, never rounded away. Scaled\n * integers must not escape through any service input or output.\n */\nimport {\n    scaledToDecimal,\n    tryDecimalToScaled,\n    type DecimalToScaledFailure,\n} from \"../catalogs/decimal.js\";\nimport {\n    CatalogConversionError,\n    type ClientCatalog,\n    type PairCatalogKey,\n} from \"../catalogs/types.js\";\nimport { PRICE_SCALE } from \"../catalogs/readers.js\";\n\n/** On-chain unified-asset amounts (`amountE18`) are always 18-decimal scaled. */\nexport const E18_SCALE = 18;\n\n/**\n * Resolves wire scales for the SDK's internal decimal conversion. Backed by\n * the client catalog; `ready()` must be awaited before the synchronous lookups\n * are used so the catalog can answer them.\n */\nexport interface SdkScales {\n    ready(): Promise<void>;\n    price(): number;\n    baseQty(pair: PairCatalogKey): number;\n    quoteAmount(pair: PairCatalogKey): number;\n    ledgerAmount(ledgerAssetId: number): number;\n    zippedAssetAmount(zippedAssetId: number): number;\n}\n\n/**\n * Catalog-backed scale resolver. Takes a getter so it can be constructed\n * before the owning client has assigned its catalog.\n */\nexport function createCatalogSdkScales(getCatalog: () => ClientCatalog): SdkScales {\n    return {\n        ready: async () => {\n            await getCatalog().ensureReady();\n        },\n        price: () => PRICE_SCALE,\n        baseQty: (pair) => requirePair(getCatalog(), pair).baseAsset.quantityScale,\n        quoteAmount: (pair) => requirePair(getCatalog(), pair).quoteAsset.quantityScale,\n        ledgerAmount: (ledgerAssetId) =>\n            getCatalog().ledger.requireAssetByLedgerId(ledgerAssetId).quantityScale,\n        zippedAssetAmount: (zippedAssetId) =>\n            getCatalog().zipper.requireAssetChainByZippedAssetId(zippedAssetId).asset.quantityScale,\n    };\n}\n\nfunction requirePair(catalog: ClientCatalog, pair: PairCatalogKey) {\n    return typeof pair === \"string\" || (typeof pair === \"object\" && \"symbol\" in pair)\n        ? catalog.market.requirePairBySymbol(typeof pair === \"string\" ? pair : pair.symbol)\n        : catalog.market.requirePairBySymbolId(typeof pair === \"number\" ? pair : pair.symbolId);\n}\n\n/** Output direction: exact scaled→decimal conversion (`1500000n`@6 → `\"1.5\"`). */\nexport function scaledToDecimalOutput(value: bigint, scale: number): string {\n    return scaledToDecimal(value, scale);\n}\n\nfunction conversionFailureMessage(\n    field: string,\n    value: string,\n    failure: DecimalToScaledFailure,\n): string {\n    return failure.reason === \"precision\"\n        ? `${field} supports at most ${failure.maxDecimals} decimal places: ${value}`\n        : `${field} must be a non-negative decimal number: ${value}`;\n}\n\n/**\n * Input direction: strict decimal→scaled conversion. Throws\n * CatalogConversionError for non-decimal input or excess precision.\n */\nexport function decimalInputToScaled(field: string, value: string, scale: number): bigint {\n    const result = tryDecimalToScaled(value.trim(), scale);\n    if (!result.ok) {\n        throw new CatalogConversionError(\n            field,\n            conversionFailureMessage(field, value, result.failure),\n        );\n    }\n    return result.scaled;\n}\n\n/** Like decimalInputToScaled, but additionally requires a value greater than zero. */\nexport function positiveDecimalInputToScaled(field: string, value: string, scale: number): bigint {\n    const scaled = decimalInputToScaled(field, value, scale);\n    if (scaled <= 0n) {\n        throw new CatalogConversionError(field, `${field} must be greater than 0: ${value}`);\n    }\n    return scaled;\n}\n\n/**\n * Decimal quantity → PolyesterChain E18 ledger units.\n * Input precision is capped at the asset's quantityScale; the wire value is\n * always upscaled to E18 (trading balances / amount_e18 convention).\n */\nexport function quantityInputToE18(params: {\n    scales: SdkScales;\n    assetId: number;\n    quantity: string;\n    field?: string;\n}): bigint {\n    const field = params.field ?? \"quantity\";\n    const assetScale = params.scales.ledgerAmount(params.assetId);\n    if (assetScale > E18_SCALE) {\n        throw new CatalogConversionError(\n            field,\n            `${field} asset quantityScale ${assetScale} exceeds E18 ledger scale`,\n        );\n    }\n    return (\n        positiveDecimalInputToScaled(field, params.quantity, assetScale) *\n        10n ** BigInt(E18_SCALE - assetScale)\n    );\n}\n\nexport interface ReadyGate {\n    run(deliver: () => void): void;\n}\n\n/**\n * Orders event delivery behind catalog readiness. Events arriving before the\n * catalog can resolve scales are queued and flushed in arrival order once it\n * is ready; delivery errors (including post-flush ones) route to `onError`\n * instead of escaping into the transport, mirroring the realtime client's\n * consumer-handler isolation. If readiness itself fails, queued events are\n * dropped after `onError` fires — the stream cannot be decoded without scales.\n */\nexport function createReadyGate(\n    ready: () => Promise<void>,\n    onError?: (error: unknown) => void,\n): ReadyGate {\n    let state: \"pending\" | \"open\" | \"failed\" = \"pending\";\n    const queue: Array<() => void> = [];\n\n    const deliverIsolated = (deliver: () => void) => {\n        try {\n            deliver();\n        } catch (error) {\n            onError?.(error);\n        }\n    };\n\n    ready().then(\n        () => {\n            state = \"open\";\n            for (const deliver of queue.splice(0)) deliverIsolated(deliver);\n        },\n        (error) => {\n            state = \"failed\";\n            queue.length = 0;\n            onError?.(error);\n        },\n    );\n\n    return {\n        run(deliver) {\n            if (state === \"open\") deliverIsolated(deliver);\n            else if (state === \"pending\") queue.push(deliver);\n        },\n    };\n}\n"],"mappings":";;;;;;AA0CA,SAAgB,uBAAuB,YAA4C;CAC/E,OAAO;EACH,OAAO,YAAY;GACf,MAAM,WAAW,CAAC,CAAC,YAAY;EACnC;EACA,aAAA;EACA,UAAU,SAAS,YAAY,WAAW,GAAG,IAAI,CAAC,CAAC,UAAU;EAC7D,cAAc,SAAS,YAAY,WAAW,GAAG,IAAI,CAAC,CAAC,WAAW;EAClE,eAAe,kBACX,WAAW,CAAC,CAAC,OAAO,uBAAuB,aAAa,CAAC,CAAC;EAC9D,oBAAoB,kBAChB,WAAW,CAAC,CAAC,OAAO,iCAAiC,aAAa,CAAC,CAAC,MAAM;CAClF;AACJ;AAEA,SAAS,YAAY,SAAwB,MAAsB;CAC/D,OAAO,OAAO,SAAS,YAAa,OAAO,SAAS,YAAY,YAAY,OACtE,QAAQ,OAAO,oBAAoB,OAAO,SAAS,WAAW,OAAO,KAAK,MAAM,IAChF,QAAQ,OAAO,sBAAsB,OAAO,SAAS,WAAW,OAAO,KAAK,QAAQ;AAC9F;;AAGA,SAAgB,sBAAsB,OAAe,OAAuB;CACxE,OAAO,gBAAgB,OAAO,KAAK;AACvC;AAEA,SAAS,yBACL,OACA,OACA,SACM;CACN,OAAO,QAAQ,WAAW,cACpB,GAAG,MAAM,oBAAoB,QAAQ,YAAY,mBAAmB,UACpE,GAAG,MAAM,0CAA0C;AAC7D;;;;;AAMA,SAAgB,qBAAqB,OAAe,OAAe,OAAuB;CACtF,MAAM,SAAS,mBAAmB,MAAM,KAAK,GAAG,KAAK;CACrD,IAAI,CAAC,OAAO,IACR,MAAM,IAAI,uBACN,OACA,yBAAyB,OAAO,OAAO,OAAO,OAAO,CACzD;CAEJ,OAAO,OAAO;AAClB;;AAGA,SAAgB,6BAA6B,OAAe,OAAe,OAAuB;CAC9F,MAAM,SAAS,qBAAqB,OAAO,OAAO,KAAK;CACvD,IAAI,UAAU,IACV,MAAM,IAAI,uBAAuB,OAAO,GAAG,MAAM,2BAA2B,OAAO;CAEvF,OAAO;AACX;;;;;;AAOA,SAAgB,mBAAmB,QAKxB;CACP,MAAM,QAAQ,OAAO,SAAS;CAC9B,MAAM,aAAa,OAAO,OAAO,aAAa,OAAO,OAAO;CAC5D,IAAI,aAAA,IACA,MAAM,IAAI,uBACN,OACA,GAAG,MAAM,uBAAuB,WAAW,0BAC/C;CAEJ,OACI,6BAA6B,OAAO,OAAO,UAAU,UAAU,IAC/D,OAAO,OAAA,KAAmB,UAAU;AAE5C;;;;;;;;;AAcA,SAAgB,gBACZ,OACA,SACS;CACT,IAAI,QAAuC;CAC3C,MAAM,QAA2B,CAAC;CAElC,MAAM,mBAAmB,YAAwB;EAC7C,IAAI;GACA,QAAQ;EACZ,SAAS,OAAO;GACZ,UAAU,KAAK;EACnB;CACJ;CAEA,MAAM,CAAC,CAAC,WACE;EACF,QAAQ;EACR,KAAK,MAAM,WAAW,MAAM,OAAO,CAAC,GAAG,gBAAgB,OAAO;CAClE,IACC,UAAU;EACP,QAAQ;EACR,MAAM,SAAS;EACf,UAAU,KAAK;CACnB,CACJ;CAEA,OAAO,EACH,IAAI,SAAS;EACT,IAAI,UAAU,QAAQ,gBAAgB,OAAO;OACxC,IAAI,UAAU,WAAW,MAAM,KAAK,OAAO;CACpD,EACJ;AACJ"}

package/dist/shared/errors.d.ts

@@ -0,0 +1,242 @@
+//#region src/shared/errors.d.ts
+/**
+ * Typed error hierarchy for the Polyester SDK.
+ *
+ * Every error raised by the SDK extends {@link PolyesterError}, which carries a
+ * stable machine-readable `code` and a `retryable` flag. The tree splits on
+ * retryability so callers can triage with a single `instanceof` check:
+ *
+ * ```
+ * PolyesterError                     code                        retryable
+ * ├── TransientError                 TRANSIENT_FAILURE           true
+ * │   ├── NetworkError               NETWORK_ERROR               true
+ * │   ├── TimeoutError               TIMEOUT                     true
+ * │   ├── RateLimitError             RATE_LIMITED                true
+ * │   └── ServiceUnavailableError    SERVICE_UNAVAILABLE         true
+ * ├── RequestError                   REQUEST_FAILED              false
+ * │   ├── ValidationError            VALIDATION_FAILED           false
+ * │   ├── ResourceNotFoundError      RESOURCE_NOT_FOUND          false
+ * │   ├── AlreadyExistsError         ALREADY_EXISTS              false
+ * │   ├── PermissionError            PERMISSION_DENIED           false
+ * │   ├── AuthenticationError        UNAUTHENTICATED             false
+ * │   ├── PreconditionFailedError    PRECONDITION_FAILED         false
+ * │   │   ├── RevisionConflictError      REVISION_CONFLICT
+ * │   │   ├── PolicyInUseError           POLICY_IN_USE
+ * │   │   └── PolicyLockedError          POLICY_LOCKED
+ * │   ├── PolicyScopeMismatchError   POLICY_SCOPE_MISMATCH       false
+ * │   ├── ConfigurationError         INVALID_CONFIGURATION       false
+ * │   ├── MfaRequiredError           MFA_REQUIRED                false
+ * │   │   ├── MfaEnrollmentRequiredError     MFA_ENROLLMENT_REQUIRED
+ * │   │   ├── StepUpRequiredError            STEP_UP_REQUIRED
+ * │   │   └── SessionElevationRequiredError  SESSION_ELEVATION_REQUIRED
+ * │   ├── MfaLastFactorRequiredError  MFA_LAST_FACTOR_REQUIRED       false
+ * │   └── MfaVerificationError       MFA_VERIFICATION_FAILED     false
+ * └── InternalServerError            INTERNAL_SERVER_ERROR       false
+ * ```
+ *
+ * Catalog errors (`CatalogLookupError`, `CatalogConversionError`, …) plug into
+ * the same tree under `RequestError`/`ValidationError`.
+ *
+ * Errors mapped from RPC failures keep the original `ConnectError` as `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.orders.createSpotOrder(input);
+ * } catch (err) {
+ *   if (err instanceof RateLimitError) await sleep(err.retryAfterMs ?? 1000);
+ *   else if (err instanceof TransientError) retry();
+ *   else if (err instanceof StepUpRequiredError) promptForMfa();
+ *   else throw err;
+ * }
+ * ```
+ */
+/** Stable machine-readable codes carried by built-in SDK errors. */
+type PolyesterErrorCode = "TRANSIENT_FAILURE" | "NETWORK_ERROR" | "TIMEOUT" | "RATE_LIMITED" | "SERVICE_UNAVAILABLE" | "REQUEST_FAILED" | "VALIDATION_FAILED" | "STALE_QUOTE" | "RESOURCE_NOT_FOUND" | "ALREADY_EXISTS" | "PERMISSION_DENIED" | "UNAUTHENTICATED" | "PRECONDITION_FAILED" | "REVISION_CONFLICT" | "POLICY_IN_USE" | "POLICY_LOCKED" | "POLICY_SCOPE_MISMATCH" | "INVALID_CONFIGURATION" | "MFA_REQUIRED" | "MFA_ENROLLMENT_REQUIRED" | "STEP_UP_REQUIRED" | "SESSION_ELEVATION_REQUIRED" | "MFA_LAST_FACTOR_REQUIRED" | "MFA_VERIFICATION_FAILED" | "INTERNAL_SERVER_ERROR" | "CATALOG_LOOKUP_MISS" | "CATALOG_NOT_READY" | "CATALOG_CONVERSION_INVALID" | "CATALOG_VALIDATION_FAILED";
+interface PolyesterErrorOptions {
+  /** Underlying error, typically the original `ConnectError` for RPC failures. */
+  cause?: unknown;
+}
+declare function normalizeErrorMessage(message: string): string;
+/**
+ * Base class for every error raised by the Polyester SDK.
+ *
+ * Check `retryable` (or `instanceof TransientError`) to decide whether the
+ * same call can be safely retried, and switch on `code` for exhaustive,
+ * minification-safe handling.
+ */
+declare abstract class PolyesterError extends Error {
+  /** Stable machine-readable error code, e.g. `"RATE_LIMITED"`. */
+  abstract readonly code: string;
+  /** Whether retrying the same operation may succeed. */
+  abstract readonly retryable: boolean;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/**
+ * A transient failure — the request may never have reached the backend or the
+ * backend was temporarily unable to serve it. Safe to retry (use the same
+ * `requestId`/`clientOrderId` for mutations; the backend dedupes).
+ */
+declare class TransientError extends PolyesterError {
+  readonly code: string;
+  readonly retryable = true;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The request could not be sent or the connection failed mid-flight. */
+declare class NetworkError extends TransientError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The request timed out before the backend produced a response. */
+declare class TimeoutError extends TransientError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+interface RateLimitErrorOptions extends PolyesterErrorOptions {
+  /** Suggested wait before retrying, when the backend provided one. */
+  retryAfterMs?: number;
+}
+/** The backend rejected the request due to rate limiting. */
+declare class RateLimitError extends TransientError {
+  readonly code: string;
+  /** Suggested wait before retrying, in milliseconds, when known. */
+  readonly retryAfterMs?: number;
+  constructor(message: string, options?: RateLimitErrorOptions);
+}
+/** The backend is temporarily unavailable (e.g. overloaded or restarting). */
+declare class ServiceUnavailableError extends TransientError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/**
+ * The request itself was rejected — retrying the identical call will fail the
+ * same way. Fix the input, authentication, or permissions first.
+ */
+declare class RequestError extends PolyesterError {
+  readonly code: string;
+  readonly retryable = false;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The request input failed validation (client- or server-side). */
+declare class ValidationError extends RequestError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The submitted client reference quote exceeded the market's configured drift limit. */
+declare class StaleQuoteError extends ValidationError {
+  readonly code: "STALE_QUOTE";
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The requested resource does not exist (or is not visible to the caller). */
+declare class ResourceNotFoundError extends RequestError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The resource already exists (e.g. a duplicate `clientOrderId`). */
+declare class AlreadyExistsError extends RequestError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The caller is authenticated but not allowed to perform this operation. */
+declare class PermissionError extends RequestError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The caller is not authenticated (missing, expired, or invalid credentials). */
+declare class AuthenticationError extends RequestError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The system is not in a state that allows this operation (e.g. insufficient balance). */
+declare class PreconditionFailedError extends RequestError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/**
+ * The resource changed after it was read, so the submitted expected revision
+ * is stale. Refetch and let the caller reconcile; do not blindly retry.
+ */
+declare class RevisionConflictError extends PreconditionFailedError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The policy cannot be removed while accounts or API keys still use it. */
+declare class PolicyInUseError extends PreconditionFailedError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The policy is locked against the requested mutation. */
+declare class PolicyLockedError extends PreconditionFailedError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The policy does not belong to the account scope targeted by the request. */
+declare class PolicyScopeMismatchError extends ValidationError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The SDK was configured incorrectly (bad environment, missing credentials, …). */
+declare class ConfigurationError extends RequestError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/**
+ * The operation requires additional multi-factor authentication. Catch this
+ * class to handle all MFA flows, or the subclasses to branch per flow.
+ */
+declare class MfaRequiredError extends RequestError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The user must enroll in MFA before this operation can proceed. */
+declare class MfaEnrollmentRequiredError extends MfaRequiredError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The operation requires a fresh MFA step-up proof (retry with `X-Auth-Step-Up`). */
+declare class StepUpRequiredError extends MfaRequiredError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The operation requires a recent MFA-elevated session, not a one-use step-up proof. */
+declare class SessionElevationRequiredError extends MfaRequiredError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The requested deletion would leave the account without an active MFA factor. */
+declare class MfaLastFactorRequiredError extends PreconditionFailedError {
+  readonly code: string;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/** The reason an MFA challenge could not be completed. */
+type MfaVerificationFailureReason = "challenge-invalid" | "challenge-locked" | "otp-invalid" | "recovery-code-invalid" | "passkey-invalid";
+/**
+ * An expected MFA verification rejection. Callers should select their own
+ * user-facing copy from `reason` instead of displaying the backend message.
+ */
+declare class MfaVerificationError extends RequestError {
+  readonly reason: MfaVerificationFailureReason;
+  readonly code: string;
+  constructor(message: string, reason: MfaVerificationFailureReason, options?: PolyesterErrorOptions);
+}
+/**
+ * The backend failed unexpectedly or returned a malformed response. Not
+ * automatically retryable — the failure may recur and mutations may have
+ * partially applied.
+ */
+declare class InternalServerError extends PolyesterError {
+  readonly code: string;
+  readonly retryable = false;
+  constructor(message: string, options?: PolyesterErrorOptions);
+}
+/**
+ * Checks whether an error represents an aborted request (caller-initiated via
+ * `AbortSignal`). Aborts are intentionally NOT part of the {@link PolyesterError}
+ * tree and are never retryable.
+ */
+declare function isAbortError(err: unknown): boolean;
+/** Maps a plain HTTP status code onto the SDK error tree. */
+declare function errorFromHttpStatus(status: number, message: string, options?: PolyesterErrorOptions): PolyesterError;
+//#endregion
+export { AlreadyExistsError, AuthenticationError, ConfigurationError, InternalServerError, MfaEnrollmentRequiredError, MfaLastFactorRequiredError, MfaRequiredError, MfaVerificationError, MfaVerificationFailureReason, NetworkError, PermissionError, PolicyInUseError, PolicyLockedError, PolicyScopeMismatchError, PolyesterError, PolyesterErrorCode, PolyesterErrorOptions, PreconditionFailedError, RateLimitError, RateLimitErrorOptions, RequestError, ResourceNotFoundError, RevisionConflictError, ServiceUnavailableError, SessionElevationRequiredError, StaleQuoteError, StepUpRequiredError, TimeoutError, TransientError, ValidationError, errorFromHttpStatus, isAbortError, normalizeErrorMessage };
+//# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../../src/shared/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsDY;UA+BK;;EAEb;;iBAKY,sBAAsB;;;;;;;;uBAWhB,uBAAuB;;oBAEvB;;oBAEA;EAEN,YAAA,iBAAiB,UAAU;;;;;;;cAW9B,uBAAuB;WACvB;WACA;EAEG,YAAA,iBAAiB,UAAU;;;cAO9B,qBAAqB;WACZ;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,qBAAqB;WACZ;EAEN,YAAA,iBAAiB,UAAU;;UAM1B,8BAA8B;;EAE3C;;;cAIS,uBAAuB;WACd;;WAET;EAEG,YAAA,iBAAiB,UAAU;;;cAQ9B,gCAAgC;WACvB;EAEN,YAAA,iBAAiB,UAAU;;;;;;cAU9B,qBAAqB;WACrB;WACA;EAEG,YAAA,iBAAiB,UAAU;;;cAO9B,wBAAwB;WACf;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,wBAAwB;WACf;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,8BAA8B;WACrB;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,2BAA2B;WAClB;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,wBAAwB;WACf;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,4BAA4B;WACnB;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,gCAAgC;WACvB;EAEN,YAAA,iBAAiB,UAAU;;;;;;cAU9B,8BAA8B;WACrB;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,yBAAyB;WAChB;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,0BAA0B;WACjB;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,iCAAiC;WACxB;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,2BAA2B;WAClB;EAEN,YAAA,iBAAiB,UAAU;;;;;;cAU9B,yBAAyB;WAChB;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,mCAAmC;WAC1B;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,4BAA4B;WACnB;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,sCAAsC;WAC7B;EAEN,YAAA,iBAAiB,UAAU;;;cAO9B,mCAAmC;WAC1B;EAEN,YAAA,iBAAiB,UAAU;;;KAO/B;;;;;cAWC,6BAA6B;WAKzB,QAAQ;WAJH;EAGd,YAAA,iBACS,QAAQ,8BACjB,UAAU;;;;;;;cAYL,4BAA4B;WAC5B;WACA;EAEG,YAAA,iBAAiB,UAAU;;;;;;;iBAW3B,aAAa;;iBAKb,oBACZ,gBACA,iBACA,UAAU,wBACX"}