@01.software/sdk 0.46.1 → 0.49.0

package/dist/errors.d.cts

@@ -8,6 +8,8 @@ declare class SDKError extends Error {
     readonly kind?: 'commerce';
     readonly reason?: CommerceErrorCode | 'unknown_commerce_error';
     readonly rawReason?: string;
+    /** Machine-readable reason from a non-commerce API response. */
+    readonly apiReason?: string;
     readonly retryable?: boolean;
     readonly retryAfter?: number;
     constructor(code: string, message: string, status?: number, details?: unknown, userMessage?: string, suggestion?: string, requestId?: string);
@@ -15,8 +17,9 @@ declare class SDKError extends Error {
     toJSON(): {
         retryAfter?: number | undefined;
         retryable?: boolean | undefined;
+        apiReason?: string | undefined;
         rawReason?: string | undefined;
-        reason?: "currency_mismatch" | "validation_failed" | "unauthorized" | "forbidden" | "token_expired" | "origin_not_allowed" | "server_credentials_required" | "not_found" | "conflict" | "cart_revision_conflict" | "rate_limit_exceeded" | "usage_limit_exceeded" | "service_unavailable" | "idempotency_conflict" | "idempotency_in_progress" | "cart_not_active" | "cart_locked" | "cart_empty" | "cart_market_unavailable" | "cart_market_mismatch" | "checkout_not_open" | "payment_slot_held" | "reservation_expired" | "payment_session_not_cancelable" | "provider_identity_mismatch" | "provider_unavailable" | "lock_timeout" | "price_changed" | "pricing_fact_in_use" | "insufficient_stock" | "market_not_found" | "market_shipping_currency_unsupported" | "missing_market_rate" | "missing_shipping_amount" | "no_enabled_payment_provider" | "product_market_unavailable" | "unsupported_currency" | "missing_price_row" | "payment_provider_currency_unsupported" | "discount_code_not_found" | "discount_not_started" | "discount_expired" | "discount_usage_limit" | "discount_per_customer_limit" | "discount_customer_required" | "discount_first_order_only" | "discount_customer_not_eligible" | "discount_customer_excluded" | "discount_items_required" | "discount_product_not_eligible" | "discount_product_excluded" | "discount_min_order_amount" | "discount_currency_scope_required" | "discount_allocation_method_unsupported" | "unknown_commerce_error" | undefined;
+        reason?: "currency_mismatch" | "validation_failed" | "bad_request" | "unauthorized" | "forbidden" | "account_suspended" | "key_invalid" | "pat_tenant_header_forbidden" | "tenant_mismatch" | "test_tenant_expired" | "token_invalid" | "token_expired" | "origin_not_allowed" | "server_credentials_required" | "role_denied" | "scope_denied" | "feature_disabled" | "not_found" | "conflict" | "locked" | "cart_revision_conflict" | "rate_limit_exceeded" | "usage_limit_exceeded" | "service_unavailable" | "idempotency_conflict" | "idempotency_in_progress" | "idempotency_key_required" | "invalid_idempotency_key" | "cart_not_active" | "cart_locked" | "cart_empty" | "cart_market_unavailable" | "cart_market_mismatch" | "checkout_not_open" | "checkout_already_open" | "payment_slot_held" | "reservation_expired" | "payment_session_not_cancelable" | "payment_session_conflict" | "provider_identity_mismatch" | "payment_method_unavailable" | "provider_unavailable" | "lock_timeout" | "price_changed" | "pricing_fact_in_use" | "insufficient_stock" | "reservation_conflict" | "stock_lock_unavailable" | "variant_not_found" | "variant_stock_write_failed" | "stock_invariant_violation" | "payment_confirmation_in_flight" | "checkout_reservation_release_requires_transaction" | "admission_metadata_invalid" | "admission_metadata_required" | "capacity_exceeded" | "occurrence_lock_unavailable" | "occurrence_not_open" | "admission_type_capacity_exceeded" | "admission_type_occurrence_mismatch" | "admission_hold_expired" | "admission_hold_checkout_item_conflict" | "admission_hold_checkout_conflict" | "admission_hold_quantity_mismatch" | "admission_hold_unbound" | "admission_hold_missing" | "admission_hold_checkout_item_missing" | "admission_hold_expiry_failed" | "admission_hold_expiry_requires_transaction" | "admission_hold_line_item_mismatch" | "admission_materialization_failed" | "variant_inactive" | "variant_product_mismatch" | "product_not_public" | "market_not_found" | "market_shipping_currency_unsupported" | "missing_market_rate" | "missing_shipping_amount" | "no_enabled_payment_provider" | "product_market_unavailable" | "unsupported_currency" | "missing_price_row" | "payment_provider_currency_unsupported" | "discount_code_not_found" | "discount_not_started" | "discount_expired" | "discount_usage_limit" | "discount_per_customer_limit" | "discount_customer_required" | "discount_first_order_only" | "discount_customer_not_eligible" | "discount_customer_excluded" | "discount_items_required" | "discount_product_not_eligible" | "discount_product_excluded" | "discount_min_order_amount" | "discount_currency_scope_required" | "discount_allocation_method_unsupported" | "customer_token_required" | "market_required" | "server_derived" | "internal_error" | "unknown_commerce_error" | undefined;
         kind?: "commerce" | undefined;
         requestId?: string | undefined;
         name: string;
@@ -33,7 +36,7 @@ declare class SDKError extends Error {
  * intentionally does not import the private contracts package; parity is
  * enforced by a type test.
  */
-declare const COMMERCE_ERROR_CODES: readonly ["validation_failed", "unauthorized", "forbidden", "token_expired", "origin_not_allowed", "server_credentials_required", "not_found", "conflict", "cart_revision_conflict", "rate_limit_exceeded", "usage_limit_exceeded", "service_unavailable", "idempotency_conflict", "idempotency_in_progress", "cart_not_active", "cart_locked", "cart_empty", "cart_market_unavailable", "cart_market_mismatch", "checkout_not_open", "payment_slot_held", "reservation_expired", "payment_session_not_cancelable", "provider_identity_mismatch", "provider_unavailable", "lock_timeout", "price_changed", "pricing_fact_in_use", "insufficient_stock", "market_not_found", "market_shipping_currency_unsupported", "missing_market_rate", "missing_shipping_amount", "no_enabled_payment_provider", "product_market_unavailable", "unsupported_currency", "missing_price_row", "payment_provider_currency_unsupported", "discount_code_not_found", "discount_not_started", "discount_expired", "discount_usage_limit", "discount_per_customer_limit", "discount_customer_required", "discount_first_order_only", "discount_customer_not_eligible", "discount_customer_excluded", "discount_items_required", "discount_product_not_eligible", "discount_product_excluded", "discount_min_order_amount", "discount_currency_scope_required", "discount_allocation_method_unsupported", "currency_mismatch"];
+declare const COMMERCE_ERROR_CODES: readonly ["validation_failed", "bad_request", "unauthorized", "forbidden", "account_suspended", "key_invalid", "pat_tenant_header_forbidden", "tenant_mismatch", "test_tenant_expired", "token_invalid", "token_expired", "origin_not_allowed", "server_credentials_required", "role_denied", "scope_denied", "feature_disabled", "not_found", "conflict", "locked", "cart_revision_conflict", "rate_limit_exceeded", "usage_limit_exceeded", "service_unavailable", "idempotency_conflict", "idempotency_in_progress", "idempotency_key_required", "invalid_idempotency_key", "cart_not_active", "cart_locked", "cart_empty", "cart_market_unavailable", "cart_market_mismatch", "checkout_not_open", "checkout_already_open", "payment_slot_held", "reservation_expired", "payment_session_not_cancelable", "payment_session_conflict", "provider_identity_mismatch", "payment_method_unavailable", "provider_unavailable", "lock_timeout", "price_changed", "pricing_fact_in_use", "insufficient_stock", "reservation_conflict", "stock_lock_unavailable", "variant_not_found", "variant_stock_write_failed", "stock_invariant_violation", "payment_confirmation_in_flight", "checkout_reservation_release_requires_transaction", "admission_metadata_invalid", "admission_metadata_required", "capacity_exceeded", "occurrence_lock_unavailable", "occurrence_not_open", "admission_type_capacity_exceeded", "admission_type_occurrence_mismatch", "admission_hold_expired", "admission_hold_checkout_item_conflict", "admission_hold_checkout_conflict", "admission_hold_quantity_mismatch", "admission_hold_unbound", "admission_hold_missing", "admission_hold_checkout_item_missing", "admission_hold_expiry_failed", "admission_hold_expiry_requires_transaction", "admission_hold_line_item_mismatch", "admission_materialization_failed", "variant_inactive", "variant_product_mismatch", "product_not_public", "market_not_found", "market_shipping_currency_unsupported", "missing_market_rate", "missing_shipping_amount", "no_enabled_payment_provider", "product_market_unavailable", "unsupported_currency", "missing_price_row", "payment_provider_currency_unsupported", "discount_code_not_found", "discount_not_started", "discount_expired", "discount_usage_limit", "discount_per_customer_limit", "discount_customer_required", "discount_first_order_only", "discount_customer_not_eligible", "discount_customer_excluded", "discount_items_required", "discount_product_not_eligible", "discount_product_excluded", "discount_min_order_amount", "discount_currency_scope_required", "discount_allocation_method_unsupported", "currency_mismatch", "customer_token_required", "market_required", "server_derived", "internal_error"];
 type CommerceErrorCode = (typeof COMMERCE_ERROR_CODES)[number];
 type CommerceSDKErrorBase = SDKError & {
     readonly kind: 'commerce';
@@ -49,6 +52,11 @@ type CommerceSDKError = CommerceSDKErrorBase & ({
     readonly reason: 'unknown_commerce_error';
     readonly rawReason: string;
 });
+/**
+ * Read the server-provided machine reason across strict commerce and
+ * non-commerce SDK errors. Unknown commerce reasons are returned verbatim.
+ */
+declare function getSDKErrorReason(error: SDKError): string | undefined;
 declare function isCommerceSDKError(error: unknown): error is CommerceSDKError;
 declare class NetworkError extends SDKError {
     constructor(message: string, status?: number, details?: unknown, userMessage?: string, suggestion?: string);
@@ -91,8 +99,9 @@ declare class UsageLimitError extends SDKError {
         };
         retryAfter?: number | undefined;
         retryable?: boolean | undefined;
+        apiReason?: string | undefined;
         rawReason?: string | undefined;
-        reason?: "currency_mismatch" | "validation_failed" | "unauthorized" | "forbidden" | "token_expired" | "origin_not_allowed" | "server_credentials_required" | "not_found" | "conflict" | "cart_revision_conflict" | "rate_limit_exceeded" | "usage_limit_exceeded" | "service_unavailable" | "idempotency_conflict" | "idempotency_in_progress" | "cart_not_active" | "cart_locked" | "cart_empty" | "cart_market_unavailable" | "cart_market_mismatch" | "checkout_not_open" | "payment_slot_held" | "reservation_expired" | "payment_session_not_cancelable" | "provider_identity_mismatch" | "provider_unavailable" | "lock_timeout" | "price_changed" | "pricing_fact_in_use" | "insufficient_stock" | "market_not_found" | "market_shipping_currency_unsupported" | "missing_market_rate" | "missing_shipping_amount" | "no_enabled_payment_provider" | "product_market_unavailable" | "unsupported_currency" | "missing_price_row" | "payment_provider_currency_unsupported" | "discount_code_not_found" | "discount_not_started" | "discount_expired" | "discount_usage_limit" | "discount_per_customer_limit" | "discount_customer_required" | "discount_first_order_only" | "discount_customer_not_eligible" | "discount_customer_excluded" | "discount_items_required" | "discount_product_not_eligible" | "discount_product_excluded" | "discount_min_order_amount" | "discount_currency_scope_required" | "discount_allocation_method_unsupported" | "unknown_commerce_error" | undefined;
+        reason?: "currency_mismatch" | "validation_failed" | "bad_request" | "unauthorized" | "forbidden" | "account_suspended" | "key_invalid" | "pat_tenant_header_forbidden" | "tenant_mismatch" | "test_tenant_expired" | "token_invalid" | "token_expired" | "origin_not_allowed" | "server_credentials_required" | "role_denied" | "scope_denied" | "feature_disabled" | "not_found" | "conflict" | "locked" | "cart_revision_conflict" | "rate_limit_exceeded" | "usage_limit_exceeded" | "service_unavailable" | "idempotency_conflict" | "idempotency_in_progress" | "idempotency_key_required" | "invalid_idempotency_key" | "cart_not_active" | "cart_locked" | "cart_empty" | "cart_market_unavailable" | "cart_market_mismatch" | "checkout_not_open" | "checkout_already_open" | "payment_slot_held" | "reservation_expired" | "payment_session_not_cancelable" | "payment_session_conflict" | "provider_identity_mismatch" | "payment_method_unavailable" | "provider_unavailable" | "lock_timeout" | "price_changed" | "pricing_fact_in_use" | "insufficient_stock" | "reservation_conflict" | "stock_lock_unavailable" | "variant_not_found" | "variant_stock_write_failed" | "stock_invariant_violation" | "payment_confirmation_in_flight" | "checkout_reservation_release_requires_transaction" | "admission_metadata_invalid" | "admission_metadata_required" | "capacity_exceeded" | "occurrence_lock_unavailable" | "occurrence_not_open" | "admission_type_capacity_exceeded" | "admission_type_occurrence_mismatch" | "admission_hold_expired" | "admission_hold_checkout_item_conflict" | "admission_hold_checkout_conflict" | "admission_hold_quantity_mismatch" | "admission_hold_unbound" | "admission_hold_missing" | "admission_hold_checkout_item_missing" | "admission_hold_expiry_failed" | "admission_hold_expiry_requires_transaction" | "admission_hold_line_item_mismatch" | "admission_materialization_failed" | "variant_inactive" | "variant_product_mismatch" | "product_not_public" | "market_not_found" | "market_shipping_currency_unsupported" | "missing_market_rate" | "missing_shipping_amount" | "no_enabled_payment_provider" | "product_market_unavailable" | "unsupported_currency" | "missing_price_row" | "payment_provider_currency_unsupported" | "discount_code_not_found" | "discount_not_started" | "discount_expired" | "discount_usage_limit" | "discount_per_customer_limit" | "discount_customer_required" | "discount_first_order_only" | "discount_customer_not_eligible" | "discount_customer_excluded" | "discount_items_required" | "discount_product_not_eligible" | "discount_product_excluded" | "discount_min_order_amount" | "discount_currency_scope_required" | "discount_allocation_method_unsupported" | "customer_token_required" | "market_required" | "server_derived" | "internal_error" | "unknown_commerce_error" | undefined;
         kind?: "commerce" | undefined;
         requestId?: string | undefined;
         name: string;
@@ -152,4 +161,4 @@ declare const createNotFoundError: (message: string, details?: unknown, userMess
 declare const createConflictError: (message: string, details?: unknown, userMessage?: string, suggestion?: string, requestId?: string) => ConflictError;
 declare const createRateLimitError: (message: string, retryAfter?: number, details?: unknown, userMessage?: string, suggestion?: string, requestId?: string) => RateLimitError;
 
-export { ApiError, AuthError, COMMERCE_ERROR_CODES, type CommerceErrorCode, type CommerceSDKError, ConfigError, ConflictError, GoneError, NetworkError, NotFoundError, PermissionError, RateLimitError, SDKError, ServiceUnavailableError, TimeoutError, UsageLimitError, ValidationError, createApiError, createAuthError, createConfigError, createConflictError, createGoneError, createNetworkError, createNotFoundError, createPermissionError, createRateLimitError, createServiceUnavailableError, createTimeoutError, createUsageLimitError, createValidationError, isApiError, isAuthError, isCommerceSDKError, isConfigError, isConflictError, isGoneError, isNetworkError, isNotFoundError, isPermissionError, isRateLimitError, isSDKError, isServiceUnavailableError, isTimeoutError, isUsageLimitError, isValidationError };
+export { ApiError, AuthError, COMMERCE_ERROR_CODES, type CommerceErrorCode, type CommerceSDKError, ConfigError, ConflictError, GoneError, NetworkError, NotFoundError, PermissionError, RateLimitError, SDKError, ServiceUnavailableError, TimeoutError, UsageLimitError, ValidationError, createApiError, createAuthError, createConfigError, createConflictError, createGoneError, createNetworkError, createNotFoundError, createPermissionError, createRateLimitError, createServiceUnavailableError, createTimeoutError, createUsageLimitError, createValidationError, getSDKErrorReason, isApiError, isAuthError, isCommerceSDKError, isConfigError, isConflictError, isGoneError, isNetworkError, isNotFoundError, isPermissionError, isRateLimitError, isSDKError, isServiceUnavailableError, isTimeoutError, isUsageLimitError, isValidationError };

package/dist/errors.d.ts

@@ -8,6 +8,8 @@ declare class SDKError extends Error {
     readonly kind?: 'commerce';
     readonly reason?: CommerceErrorCode | 'unknown_commerce_error';
     readonly rawReason?: string;
+    /** Machine-readable reason from a non-commerce API response. */
+    readonly apiReason?: string;
     readonly retryable?: boolean;
     readonly retryAfter?: number;
     constructor(code: string, message: string, status?: number, details?: unknown, userMessage?: string, suggestion?: string, requestId?: string);
@@ -15,8 +17,9 @@ declare class SDKError extends Error {
     toJSON(): {
         retryAfter?: number | undefined;
         retryable?: boolean | undefined;
+        apiReason?: string | undefined;
         rawReason?: string | undefined;
-        reason?: "currency_mismatch" | "validation_failed" | "unauthorized" | "forbidden" | "token_expired" | "origin_not_allowed" | "server_credentials_required" | "not_found" | "conflict" | "cart_revision_conflict" | "rate_limit_exceeded" | "usage_limit_exceeded" | "service_unavailable" | "idempotency_conflict" | "idempotency_in_progress" | "cart_not_active" | "cart_locked" | "cart_empty" | "cart_market_unavailable" | "cart_market_mismatch" | "checkout_not_open" | "payment_slot_held" | "reservation_expired" | "payment_session_not_cancelable" | "provider_identity_mismatch" | "provider_unavailable" | "lock_timeout" | "price_changed" | "pricing_fact_in_use" | "insufficient_stock" | "market_not_found" | "market_shipping_currency_unsupported" | "missing_market_rate" | "missing_shipping_amount" | "no_enabled_payment_provider" | "product_market_unavailable" | "unsupported_currency" | "missing_price_row" | "payment_provider_currency_unsupported" | "discount_code_not_found" | "discount_not_started" | "discount_expired" | "discount_usage_limit" | "discount_per_customer_limit" | "discount_customer_required" | "discount_first_order_only" | "discount_customer_not_eligible" | "discount_customer_excluded" | "discount_items_required" | "discount_product_not_eligible" | "discount_product_excluded" | "discount_min_order_amount" | "discount_currency_scope_required" | "discount_allocation_method_unsupported" | "unknown_commerce_error" | undefined;
+        reason?: "currency_mismatch" | "validation_failed" | "bad_request" | "unauthorized" | "forbidden" | "account_suspended" | "key_invalid" | "pat_tenant_header_forbidden" | "tenant_mismatch" | "test_tenant_expired" | "token_invalid" | "token_expired" | "origin_not_allowed" | "server_credentials_required" | "role_denied" | "scope_denied" | "feature_disabled" | "not_found" | "conflict" | "locked" | "cart_revision_conflict" | "rate_limit_exceeded" | "usage_limit_exceeded" | "service_unavailable" | "idempotency_conflict" | "idempotency_in_progress" | "idempotency_key_required" | "invalid_idempotency_key" | "cart_not_active" | "cart_locked" | "cart_empty" | "cart_market_unavailable" | "cart_market_mismatch" | "checkout_not_open" | "checkout_already_open" | "payment_slot_held" | "reservation_expired" | "payment_session_not_cancelable" | "payment_session_conflict" | "provider_identity_mismatch" | "payment_method_unavailable" | "provider_unavailable" | "lock_timeout" | "price_changed" | "pricing_fact_in_use" | "insufficient_stock" | "reservation_conflict" | "stock_lock_unavailable" | "variant_not_found" | "variant_stock_write_failed" | "stock_invariant_violation" | "payment_confirmation_in_flight" | "checkout_reservation_release_requires_transaction" | "admission_metadata_invalid" | "admission_metadata_required" | "capacity_exceeded" | "occurrence_lock_unavailable" | "occurrence_not_open" | "admission_type_capacity_exceeded" | "admission_type_occurrence_mismatch" | "admission_hold_expired" | "admission_hold_checkout_item_conflict" | "admission_hold_checkout_conflict" | "admission_hold_quantity_mismatch" | "admission_hold_unbound" | "admission_hold_missing" | "admission_hold_checkout_item_missing" | "admission_hold_expiry_failed" | "admission_hold_expiry_requires_transaction" | "admission_hold_line_item_mismatch" | "admission_materialization_failed" | "variant_inactive" | "variant_product_mismatch" | "product_not_public" | "market_not_found" | "market_shipping_currency_unsupported" | "missing_market_rate" | "missing_shipping_amount" | "no_enabled_payment_provider" | "product_market_unavailable" | "unsupported_currency" | "missing_price_row" | "payment_provider_currency_unsupported" | "discount_code_not_found" | "discount_not_started" | "discount_expired" | "discount_usage_limit" | "discount_per_customer_limit" | "discount_customer_required" | "discount_first_order_only" | "discount_customer_not_eligible" | "discount_customer_excluded" | "discount_items_required" | "discount_product_not_eligible" | "discount_product_excluded" | "discount_min_order_amount" | "discount_currency_scope_required" | "discount_allocation_method_unsupported" | "customer_token_required" | "market_required" | "server_derived" | "internal_error" | "unknown_commerce_error" | undefined;
         kind?: "commerce" | undefined;
         requestId?: string | undefined;
         name: string;
@@ -33,7 +36,7 @@ declare class SDKError extends Error {
  * intentionally does not import the private contracts package; parity is
  * enforced by a type test.
  */
-declare const COMMERCE_ERROR_CODES: readonly ["validation_failed", "unauthorized", "forbidden", "token_expired", "origin_not_allowed", "server_credentials_required", "not_found", "conflict", "cart_revision_conflict", "rate_limit_exceeded", "usage_limit_exceeded", "service_unavailable", "idempotency_conflict", "idempotency_in_progress", "cart_not_active", "cart_locked", "cart_empty", "cart_market_unavailable", "cart_market_mismatch", "checkout_not_open", "payment_slot_held", "reservation_expired", "payment_session_not_cancelable", "provider_identity_mismatch", "provider_unavailable", "lock_timeout", "price_changed", "pricing_fact_in_use", "insufficient_stock", "market_not_found", "market_shipping_currency_unsupported", "missing_market_rate", "missing_shipping_amount", "no_enabled_payment_provider", "product_market_unavailable", "unsupported_currency", "missing_price_row", "payment_provider_currency_unsupported", "discount_code_not_found", "discount_not_started", "discount_expired", "discount_usage_limit", "discount_per_customer_limit", "discount_customer_required", "discount_first_order_only", "discount_customer_not_eligible", "discount_customer_excluded", "discount_items_required", "discount_product_not_eligible", "discount_product_excluded", "discount_min_order_amount", "discount_currency_scope_required", "discount_allocation_method_unsupported", "currency_mismatch"];
+declare const COMMERCE_ERROR_CODES: readonly ["validation_failed", "bad_request", "unauthorized", "forbidden", "account_suspended", "key_invalid", "pat_tenant_header_forbidden", "tenant_mismatch", "test_tenant_expired", "token_invalid", "token_expired", "origin_not_allowed", "server_credentials_required", "role_denied", "scope_denied", "feature_disabled", "not_found", "conflict", "locked", "cart_revision_conflict", "rate_limit_exceeded", "usage_limit_exceeded", "service_unavailable", "idempotency_conflict", "idempotency_in_progress", "idempotency_key_required", "invalid_idempotency_key", "cart_not_active", "cart_locked", "cart_empty", "cart_market_unavailable", "cart_market_mismatch", "checkout_not_open", "checkout_already_open", "payment_slot_held", "reservation_expired", "payment_session_not_cancelable", "payment_session_conflict", "provider_identity_mismatch", "payment_method_unavailable", "provider_unavailable", "lock_timeout", "price_changed", "pricing_fact_in_use", "insufficient_stock", "reservation_conflict", "stock_lock_unavailable", "variant_not_found", "variant_stock_write_failed", "stock_invariant_violation", "payment_confirmation_in_flight", "checkout_reservation_release_requires_transaction", "admission_metadata_invalid", "admission_metadata_required", "capacity_exceeded", "occurrence_lock_unavailable", "occurrence_not_open", "admission_type_capacity_exceeded", "admission_type_occurrence_mismatch", "admission_hold_expired", "admission_hold_checkout_item_conflict", "admission_hold_checkout_conflict", "admission_hold_quantity_mismatch", "admission_hold_unbound", "admission_hold_missing", "admission_hold_checkout_item_missing", "admission_hold_expiry_failed", "admission_hold_expiry_requires_transaction", "admission_hold_line_item_mismatch", "admission_materialization_failed", "variant_inactive", "variant_product_mismatch", "product_not_public", "market_not_found", "market_shipping_currency_unsupported", "missing_market_rate", "missing_shipping_amount", "no_enabled_payment_provider", "product_market_unavailable", "unsupported_currency", "missing_price_row", "payment_provider_currency_unsupported", "discount_code_not_found", "discount_not_started", "discount_expired", "discount_usage_limit", "discount_per_customer_limit", "discount_customer_required", "discount_first_order_only", "discount_customer_not_eligible", "discount_customer_excluded", "discount_items_required", "discount_product_not_eligible", "discount_product_excluded", "discount_min_order_amount", "discount_currency_scope_required", "discount_allocation_method_unsupported", "currency_mismatch", "customer_token_required", "market_required", "server_derived", "internal_error"];
 type CommerceErrorCode = (typeof COMMERCE_ERROR_CODES)[number];
 type CommerceSDKErrorBase = SDKError & {
     readonly kind: 'commerce';
@@ -49,6 +52,11 @@ type CommerceSDKError = CommerceSDKErrorBase & ({
     readonly reason: 'unknown_commerce_error';
     readonly rawReason: string;
 });
+/**
+ * Read the server-provided machine reason across strict commerce and
+ * non-commerce SDK errors. Unknown commerce reasons are returned verbatim.
+ */
+declare function getSDKErrorReason(error: SDKError): string | undefined;
 declare function isCommerceSDKError(error: unknown): error is CommerceSDKError;
 declare class NetworkError extends SDKError {
     constructor(message: string, status?: number, details?: unknown, userMessage?: string, suggestion?: string);
@@ -91,8 +99,9 @@ declare class UsageLimitError extends SDKError {
         };
         retryAfter?: number | undefined;
         retryable?: boolean | undefined;
+        apiReason?: string | undefined;
         rawReason?: string | undefined;
-        reason?: "currency_mismatch" | "validation_failed" | "unauthorized" | "forbidden" | "token_expired" | "origin_not_allowed" | "server_credentials_required" | "not_found" | "conflict" | "cart_revision_conflict" | "rate_limit_exceeded" | "usage_limit_exceeded" | "service_unavailable" | "idempotency_conflict" | "idempotency_in_progress" | "cart_not_active" | "cart_locked" | "cart_empty" | "cart_market_unavailable" | "cart_market_mismatch" | "checkout_not_open" | "payment_slot_held" | "reservation_expired" | "payment_session_not_cancelable" | "provider_identity_mismatch" | "provider_unavailable" | "lock_timeout" | "price_changed" | "pricing_fact_in_use" | "insufficient_stock" | "market_not_found" | "market_shipping_currency_unsupported" | "missing_market_rate" | "missing_shipping_amount" | "no_enabled_payment_provider" | "product_market_unavailable" | "unsupported_currency" | "missing_price_row" | "payment_provider_currency_unsupported" | "discount_code_not_found" | "discount_not_started" | "discount_expired" | "discount_usage_limit" | "discount_per_customer_limit" | "discount_customer_required" | "discount_first_order_only" | "discount_customer_not_eligible" | "discount_customer_excluded" | "discount_items_required" | "discount_product_not_eligible" | "discount_product_excluded" | "discount_min_order_amount" | "discount_currency_scope_required" | "discount_allocation_method_unsupported" | "unknown_commerce_error" | undefined;
+        reason?: "currency_mismatch" | "validation_failed" | "bad_request" | "unauthorized" | "forbidden" | "account_suspended" | "key_invalid" | "pat_tenant_header_forbidden" | "tenant_mismatch" | "test_tenant_expired" | "token_invalid" | "token_expired" | "origin_not_allowed" | "server_credentials_required" | "role_denied" | "scope_denied" | "feature_disabled" | "not_found" | "conflict" | "locked" | "cart_revision_conflict" | "rate_limit_exceeded" | "usage_limit_exceeded" | "service_unavailable" | "idempotency_conflict" | "idempotency_in_progress" | "idempotency_key_required" | "invalid_idempotency_key" | "cart_not_active" | "cart_locked" | "cart_empty" | "cart_market_unavailable" | "cart_market_mismatch" | "checkout_not_open" | "checkout_already_open" | "payment_slot_held" | "reservation_expired" | "payment_session_not_cancelable" | "payment_session_conflict" | "provider_identity_mismatch" | "payment_method_unavailable" | "provider_unavailable" | "lock_timeout" | "price_changed" | "pricing_fact_in_use" | "insufficient_stock" | "reservation_conflict" | "stock_lock_unavailable" | "variant_not_found" | "variant_stock_write_failed" | "stock_invariant_violation" | "payment_confirmation_in_flight" | "checkout_reservation_release_requires_transaction" | "admission_metadata_invalid" | "admission_metadata_required" | "capacity_exceeded" | "occurrence_lock_unavailable" | "occurrence_not_open" | "admission_type_capacity_exceeded" | "admission_type_occurrence_mismatch" | "admission_hold_expired" | "admission_hold_checkout_item_conflict" | "admission_hold_checkout_conflict" | "admission_hold_quantity_mismatch" | "admission_hold_unbound" | "admission_hold_missing" | "admission_hold_checkout_item_missing" | "admission_hold_expiry_failed" | "admission_hold_expiry_requires_transaction" | "admission_hold_line_item_mismatch" | "admission_materialization_failed" | "variant_inactive" | "variant_product_mismatch" | "product_not_public" | "market_not_found" | "market_shipping_currency_unsupported" | "missing_market_rate" | "missing_shipping_amount" | "no_enabled_payment_provider" | "product_market_unavailable" | "unsupported_currency" | "missing_price_row" | "payment_provider_currency_unsupported" | "discount_code_not_found" | "discount_not_started" | "discount_expired" | "discount_usage_limit" | "discount_per_customer_limit" | "discount_customer_required" | "discount_first_order_only" | "discount_customer_not_eligible" | "discount_customer_excluded" | "discount_items_required" | "discount_product_not_eligible" | "discount_product_excluded" | "discount_min_order_amount" | "discount_currency_scope_required" | "discount_allocation_method_unsupported" | "customer_token_required" | "market_required" | "server_derived" | "internal_error" | "unknown_commerce_error" | undefined;
         kind?: "commerce" | undefined;
         requestId?: string | undefined;
         name: string;
@@ -152,4 +161,4 @@ declare const createNotFoundError: (message: string, details?: unknown, userMess
 declare const createConflictError: (message: string, details?: unknown, userMessage?: string, suggestion?: string, requestId?: string) => ConflictError;
 declare const createRateLimitError: (message: string, retryAfter?: number, details?: unknown, userMessage?: string, suggestion?: string, requestId?: string) => RateLimitError;
 
-export { ApiError, AuthError, COMMERCE_ERROR_CODES, type CommerceErrorCode, type CommerceSDKError, ConfigError, ConflictError, GoneError, NetworkError, NotFoundError, PermissionError, RateLimitError, SDKError, ServiceUnavailableError, TimeoutError, UsageLimitError, ValidationError, createApiError, createAuthError, createConfigError, createConflictError, createGoneError, createNetworkError, createNotFoundError, createPermissionError, createRateLimitError, createServiceUnavailableError, createTimeoutError, createUsageLimitError, createValidationError, isApiError, isAuthError, isCommerceSDKError, isConfigError, isConflictError, isGoneError, isNetworkError, isNotFoundError, isPermissionError, isRateLimitError, isSDKError, isServiceUnavailableError, isTimeoutError, isUsageLimitError, isValidationError };
+export { ApiError, AuthError, COMMERCE_ERROR_CODES, type CommerceErrorCode, type CommerceSDKError, ConfigError, ConflictError, GoneError, NetworkError, NotFoundError, PermissionError, RateLimitError, SDKError, ServiceUnavailableError, TimeoutError, UsageLimitError, ValidationError, createApiError, createAuthError, createConfigError, createConflictError, createGoneError, createNetworkError, createNotFoundError, createPermissionError, createRateLimitError, createServiceUnavailableError, createTimeoutError, createUsageLimitError, createValidationError, getSDKErrorReason, isApiError, isAuthError, isCommerceSDKError, isConfigError, isConflictError, isGoneError, isNetworkError, isNotFoundError, isPermissionError, isRateLimitError, isSDKError, isServiceUnavailableError, isTimeoutError, isUsageLimitError, isValidationError };

package/dist/errors.js

@@ -1,4 +1,22 @@
 // src/core/errors.ts
+var SDK_ERROR_BRAND = /* @__PURE__ */ Symbol.for("@01.software/sdk/SDKError");
+var SDK_ERROR_TYPE_BRAND = /* @__PURE__ */ Symbol.for("@01.software/sdk/SDKError.type");
+function defineSDKErrorBrand(error) {
+  Object.defineProperty(error, SDK_ERROR_BRAND, {
+    value: true,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+}
+function defineSDKErrorType(error, type) {
+  Object.defineProperty(error, SDK_ERROR_TYPE_BRAND, {
+    value: type,
+    enumerable: false,
+    configurable: false,
+    writable: false
+  });
+}
 var SDKError = class extends Error {
   constructor(code, message, status, details, userMessage, suggestion, requestId) {
     super(message);
@@ -9,6 +27,7 @@ var SDKError = class extends Error {
     this.userMessage = userMessage;
     this.suggestion = suggestion;
     this.requestId = requestId;
+    defineSDKErrorBrand(this);
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, new.target);
     }
@@ -29,6 +48,7 @@ var SDKError = class extends Error {
       ...this.kind !== void 0 && { kind: this.kind },
       ...this.reason !== void 0 && { reason: this.reason },
       ...this.rawReason !== void 0 && { rawReason: this.rawReason },
+      ...this.apiReason !== void 0 && { apiReason: this.apiReason },
       ...this.retryable !== void 0 && { retryable: this.retryable },
       ...this.retryAfter !== void 0 && { retryAfter: this.retryAfter }
     };
@@ -36,34 +56,78 @@ var SDKError = class extends Error {
 };
 var COMMERCE_ERROR_CODES = [
   "validation_failed",
+  "bad_request",
   "unauthorized",
   "forbidden",
+  "account_suspended",
+  "key_invalid",
+  "pat_tenant_header_forbidden",
+  "tenant_mismatch",
+  "test_tenant_expired",
+  "token_invalid",
   "token_expired",
   "origin_not_allowed",
   "server_credentials_required",
+  "role_denied",
+  "scope_denied",
+  "feature_disabled",
   "not_found",
   "conflict",
+  "locked",
   "cart_revision_conflict",
   "rate_limit_exceeded",
   "usage_limit_exceeded",
   "service_unavailable",
   "idempotency_conflict",
   "idempotency_in_progress",
+  "idempotency_key_required",
+  "invalid_idempotency_key",
   "cart_not_active",
   "cart_locked",
   "cart_empty",
   "cart_market_unavailable",
   "cart_market_mismatch",
   "checkout_not_open",
+  "checkout_already_open",
   "payment_slot_held",
   "reservation_expired",
   "payment_session_not_cancelable",
+  "payment_session_conflict",
   "provider_identity_mismatch",
+  "payment_method_unavailable",
   "provider_unavailable",
   "lock_timeout",
   "price_changed",
   "pricing_fact_in_use",
   "insufficient_stock",
+  "reservation_conflict",
+  "stock_lock_unavailable",
+  "variant_not_found",
+  "variant_stock_write_failed",
+  "stock_invariant_violation",
+  "payment_confirmation_in_flight",
+  "checkout_reservation_release_requires_transaction",
+  "admission_metadata_invalid",
+  "admission_metadata_required",
+  "capacity_exceeded",
+  "occurrence_lock_unavailable",
+  "occurrence_not_open",
+  "admission_type_capacity_exceeded",
+  "admission_type_occurrence_mismatch",
+  "admission_hold_expired",
+  "admission_hold_checkout_item_conflict",
+  "admission_hold_checkout_conflict",
+  "admission_hold_quantity_mismatch",
+  "admission_hold_unbound",
+  "admission_hold_missing",
+  "admission_hold_checkout_item_missing",
+  "admission_hold_expiry_failed",
+  "admission_hold_expiry_requires_transaction",
+  "admission_hold_line_item_mismatch",
+  "admission_materialization_failed",
+  "variant_inactive",
+  "variant_product_mismatch",
+  "product_not_public",
   "market_not_found",
   "market_shipping_currency_unsupported",
   "missing_market_rate",
@@ -88,13 +152,21 @@ var COMMERCE_ERROR_CODES = [
   "discount_min_order_amount",
   "discount_currency_scope_required",
   "discount_allocation_method_unsupported",
-  "currency_mismatch"
+  "currency_mismatch",
+  "customer_token_required",
+  "market_required",
+  "server_derived",
+  "internal_error"
 ];
 var COMMERCE_ERROR_CODE_SET = new Set(
   COMMERCE_ERROR_CODES
 );
+function getSDKErrorReason(error) {
+  if (error.kind !== "commerce") return error.apiReason;
+  return error.reason === "unknown_commerce_error" ? error.rawReason : error.reason;
+}
 function isCommerceSDKError(error) {
-  if (!(error instanceof SDKError) || error.kind !== "commerce") return false;
+  if (!isSDKError(error) || error.kind !== "commerce") return false;
   if (typeof error.requestId !== "string" || typeof error.retryable !== "boolean" || error.retryAfter !== void 0 && (!Number.isSafeInteger(error.retryAfter) || error.retryAfter < 0) || typeof error.reason !== "string") {
     return false;
   }
@@ -104,12 +176,14 @@ var NetworkError = class extends SDKError {
   constructor(message, status, details, userMessage, suggestion) {
     super("NETWORK_ERROR", message, status, details, userMessage, suggestion);
     this.name = "NetworkError";
+    defineSDKErrorType(this, "NetworkError");
   }
 };
 var ValidationError = class extends SDKError {
   constructor(message, details, userMessage, suggestion, status = 400) {
     super("VALIDATION_ERROR", message, status, details, userMessage, suggestion);
     this.name = "ValidationError";
+    defineSDKErrorType(this, "ValidationError");
   }
 };
 var ApiError = class extends SDKError {
@@ -124,24 +198,28 @@ var ApiError = class extends SDKError {
       requestId
     );
     this.name = "ApiError";
+    defineSDKErrorType(this, "ApiError");
   }
 };
 var ConfigError = class extends SDKError {
   constructor(message, details, userMessage, suggestion) {
     super("CONFIG_ERROR", message, void 0, details, userMessage, suggestion);
     this.name = "ConfigError";
+    defineSDKErrorType(this, "ConfigError");
   }
 };
 var TimeoutError = class extends SDKError {
   constructor(message = "Request timed out.", details, userMessage, suggestion) {
     super("TIMEOUT_ERROR", message, 408, details, userMessage, suggestion);
     this.name = "TimeoutError";
+    defineSDKErrorType(this, "TimeoutError");
   }
 };
 var GoneError = class extends SDKError {
   constructor(message = "The requested resource is no longer available.", details, userMessage, suggestion) {
     super("GONE_ERROR", message, 410, details, userMessage, suggestion);
     this.name = "GoneError";
+    defineSDKErrorType(this, "GoneError");
   }
 };
 var ServiceUnavailableError = class extends SDKError {
@@ -156,6 +234,7 @@ var ServiceUnavailableError = class extends SDKError {
     );
     this.name = "ServiceUnavailableError";
     this.retryAfter = retryAfter;
+    defineSDKErrorType(this, "ServiceUnavailableError");
   }
 };
 var UsageLimitError = class extends SDKError {
@@ -163,6 +242,7 @@ var UsageLimitError = class extends SDKError {
     super("USAGE_LIMIT_ERROR", message, 429, details, userMessage, suggestion);
     this.name = "UsageLimitError";
     this.usage = usage;
+    defineSDKErrorType(this, "UsageLimitError");
   }
   toJSON() {
     return {
@@ -183,6 +263,7 @@ var AuthError = class extends SDKError {
       requestId
     );
     this.name = "AuthError";
+    defineSDKErrorType(this, "AuthError");
   }
 };
 var PermissionError = class extends SDKError {
@@ -197,6 +278,7 @@ var PermissionError = class extends SDKError {
       requestId
     );
     this.name = "PermissionError";
+    defineSDKErrorType(this, "PermissionError");
   }
 };
 var NotFoundError = class extends SDKError {
@@ -211,12 +293,14 @@ var NotFoundError = class extends SDKError {
       requestId
     );
     this.name = "NotFoundError";
+    defineSDKErrorType(this, "NotFoundError");
   }
 };
 var ConflictError = class extends SDKError {
   constructor(message, details, userMessage, suggestion, requestId) {
     super("conflict", message, 409, details, userMessage, suggestion, requestId);
     this.name = "ConflictError";
+    defineSDKErrorType(this, "ConflictError");
   }
 };
 var RateLimitError = class extends SDKError {
@@ -232,52 +316,63 @@ var RateLimitError = class extends SDKError {
     );
     this.name = "RateLimitError";
     this.retryAfter = retryAfter;
+    defineSDKErrorType(this, "RateLimitError");
   }
 };
+function hasBrandedSDKErrorShape(error) {
+  if (error === null || typeof error !== "object") return false;
+  const candidate = error;
+  return candidate[SDK_ERROR_BRAND] === true && typeof candidate.name === "string" && typeof candidate.code === "string" && typeof candidate.message === "string" && (candidate.status === void 0 || typeof candidate.status === "number") && (candidate.userMessage === void 0 || typeof candidate.userMessage === "string") && (candidate.suggestion === void 0 || typeof candidate.suggestion === "string") && (candidate.requestId === void 0 || typeof candidate.requestId === "string") && (candidate.kind === void 0 || candidate.kind === "commerce") && (candidate.reason === void 0 || typeof candidate.reason === "string") && (candidate.rawReason === void 0 || typeof candidate.rawReason === "string") && (candidate.apiReason === void 0 || typeof candidate.apiReason === "string") && (candidate.retryable === void 0 || typeof candidate.retryable === "boolean") && (candidate.retryAfter === void 0 || typeof candidate.retryAfter === "number") && typeof candidate.getUserMessage === "function" && typeof candidate.toJSON === "function";
+}
+function hasSDKErrorType(error, type) {
+  return hasBrandedSDKErrorShape(error) && error[SDK_ERROR_TYPE_BRAND] === type;
+}
 function isSDKError(error) {
-  return error instanceof SDKError;
+  return error instanceof SDKError || hasBrandedSDKErrorShape(error);
 }
 function isNetworkError(error) {
-  return error instanceof NetworkError;
+  return error instanceof NetworkError || hasSDKErrorType(error, "NetworkError");
 }
 function isValidationError(error) {
-  if (error instanceof ValidationError) return true;
+  if (error instanceof ValidationError || hasSDKErrorType(error, "ValidationError")) {
+    return true;
+  }
   if (error == null || typeof error !== "object") return false;
   const candidate = error;
   return candidate.name === "ValidationError" && candidate.code === "VALIDATION_ERROR" && typeof candidate.message === "string" && typeof candidate.getUserMessage === "function" && typeof candidate.toJSON === "function";
 }
 function isApiError(error) {
-  return error instanceof ApiError;
+  return error instanceof ApiError || hasSDKErrorType(error, "ApiError");
 }
 function isConfigError(error) {
-  return error instanceof ConfigError;
+  return error instanceof ConfigError || hasSDKErrorType(error, "ConfigError");
 }
 function isTimeoutError(error) {
-  return error instanceof TimeoutError;
+  return error instanceof TimeoutError || hasSDKErrorType(error, "TimeoutError");
 }
 function isGoneError(error) {
-  return error instanceof GoneError;
+  return error instanceof GoneError || hasSDKErrorType(error, "GoneError");
 }
 function isServiceUnavailableError(error) {
-  return error instanceof ServiceUnavailableError;
+  return error instanceof ServiceUnavailableError || hasSDKErrorType(error, "ServiceUnavailableError");
 }
 function isUsageLimitError(error) {
-  return error instanceof UsageLimitError;
+  return error instanceof UsageLimitError || hasSDKErrorType(error, "UsageLimitError");
 }
 function isAuthError(error) {
-  return error instanceof AuthError;
+  return error instanceof AuthError || hasSDKErrorType(error, "AuthError");
 }
 function isPermissionError(error) {
-  return error instanceof PermissionError;
+  return error instanceof PermissionError || hasSDKErrorType(error, "PermissionError");
 }
 function isNotFoundError(error) {
-  return error instanceof NotFoundError;
+  return error instanceof NotFoundError || hasSDKErrorType(error, "NotFoundError");
 }
 function isConflictError(error) {
-  return error instanceof ConflictError;
+  return error instanceof ConflictError || hasSDKErrorType(error, "ConflictError");
 }
 function isRateLimitError(error) {
-  return error instanceof RateLimitError;
+  return error instanceof RateLimitError || hasSDKErrorType(error, "RateLimitError");
 }
 var createNetworkError = (message, status, details, userMessage, suggestion) => new NetworkError(message, status, details, userMessage, suggestion);
 var createValidationError = (message, details, userMessage, suggestion, status) => new ValidationError(message, details, userMessage, suggestion, status);
@@ -334,6 +429,7 @@ export {
   createTimeoutError,
   createUsageLimitError,
   createValidationError,
+  getSDKErrorReason,
   isApiError,
   isAuthError,
   isCommerceSDKError,