@cimplify/sdk 0.3.3 → 0.3.5

package/dist/index.d.mts

@@ -1,3 +1,95 @@
+/**
+ * Observability hooks for monitoring SDK behavior.
+ *
+ * These hooks allow you to plug in your own logging, metrics, and tracing
+ * without the SDK depending on any specific observability library.
+ *
+ * @example
+ * ```typescript
+ * const client = createCimplifyClient({
+ *   hooks: {
+ *     onRequestStart: ({ method, path }) => {
+ *       console.log(`[SDK] ${method} ${path}`);
+ *     },
+ *     onRequestSuccess: ({ method, path, durationMs }) => {
+ *       metrics.histogram('sdk.request.duration', durationMs, { method, path });
+ *     },
+ *     onRequestError: ({ method, path, error, retryCount }) => {
+ *       Sentry.captureException(error, { extra: { method, path, retryCount } });
+ *     },
+ *   },
+ * });
+ * ```
+ */
+/** Context passed to request lifecycle hooks */
+interface RequestContext {
+    /** HTTP method */
+    method: "GET" | "POST" | "DELETE";
+    /** Request path (e.g., "/api/q", "/api/m") */
+    path: string;
+    /** Full URL */
+    url: string;
+    /** Request body (for POST requests) */
+    body?: unknown;
+    /** Timestamp when request started */
+    startTime: number;
+}
+/** Passed when a request starts */
+interface RequestStartEvent extends RequestContext {
+}
+/** Passed when a request succeeds */
+interface RequestSuccessEvent extends RequestContext {
+    /** HTTP status code */
+    status: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
+/** Passed when a request fails */
+interface RequestErrorEvent extends RequestContext {
+    /** The error that occurred */
+    error: Error;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Number of retries attempted before giving up */
+    retryCount: number;
+    /** Whether the error is retryable */
+    retryable: boolean;
+}
+/** Passed when a retry is about to happen */
+interface RetryEvent extends RequestContext {
+    /** Which retry attempt (1, 2, 3...) */
+    attempt: number;
+    /** Delay before retry in milliseconds */
+    delayMs: number;
+    /** The error that triggered the retry */
+    error: Error;
+}
+/** Passed when session token changes */
+interface SessionChangeEvent {
+    /** Previous token (null if none) */
+    previousToken: string | null;
+    /** New token (null if cleared) */
+    newToken: string | null;
+    /** Source of the change */
+    source: "response" | "manual" | "clear";
+}
+/**
+ * Observability hooks configuration.
+ * All hooks are optional - only implement what you need.
+ */
+interface ObservabilityHooks {
+    /** Called when a request is about to be sent */
+    onRequestStart?: (event: RequestStartEvent) => void;
+    /** Called when a request completes successfully */
+    onRequestSuccess?: (event: RequestSuccessEvent) => void;
+    /** Called when a request fails (after all retries exhausted) */
+    onRequestError?: (event: RequestErrorEvent) => void;
+    /** Called before each retry attempt */
+    onRetry?: (event: RetryEvent) => void;
+    /** Called when session token changes */
+    onSessionChange?: (event: SessionChangeEvent) => void;
+}
+
 /** Decimal value represented as string for precision */
 type Money = string;
 /** Supported currencies */
@@ -2839,6 +2931,8 @@ interface CimplifyConfig {
     maxRetries?: number;
     /** Base delay between retries in milliseconds (default: 1000) */
     retryDelay?: number;
+    /** Observability hooks for logging, metrics, and tracing */
+    hooks?: ObservabilityHooks;
 }
 declare class CimplifyClient {
     private baseUrl;
@@ -2849,6 +2943,9 @@ declare class CimplifyClient {
     private timeout;
     private maxRetries;
     private retryDelay;
+    private hooks;
+    /** In-flight request deduplication map */
+    private inflightRequests;
     private _catalogue?;
     private _cart?;
     private _checkout?;
@@ -2868,11 +2965,29 @@ declare class CimplifyClient {
     private getHeaders;
     private updateSessionFromResponse;
     /**
-     * Resilient fetch with timeout and automatic retries for network errors.
+     * Resilient fetch with timeout, automatic retries, and observability hooks.
      * Uses exponential backoff: 1s, 2s, 4s between retries.
      */
     private resilientFetch;
+    /**
+     * Generate a deduplication key for a request.
+     * Same query + variables = same key = deduplicated.
+     */
+    private getDedupeKey;
+    /**
+     * Execute a request with deduplication.
+     * If an identical request is already in-flight, return the same promise.
+     * This prevents redundant network calls when multiple components request the same data.
+     */
+    private deduplicatedRequest;
+    /**
+     * Execute a query with deduplication.
+     * Multiple identical queries made simultaneously will share a single network request.
+     */
     query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * Execute a mutation. NOT deduplicated - mutations have side effects.
+     */
     call<T = unknown>(method: string, args?: unknown): Promise<T>;
     get<T = unknown>(path: string): Promise<T>;
     post<T = unknown>(path: string, body?: unknown): Promise<T>;
@@ -3415,4 +3530,4 @@ interface ApiResponse<T> {
     metadata?: ResponseMetadata;
 }
 
-export { AUTHORIZATION_TYPE, AUTH_MUTATION, type AddOn, type AddOnDetails, type AddOnGroupDetails, type AddOnOption, type AddOnOptionDetails, type AddOnOptionPrice, type AddOnWithOptions, type AddToCartInput, type AddressData, type AdjustmentType, type AmountToPay, type ApiError, type ApiResponse, type AppliedDiscount, type AuthResponse, AuthService, type AuthStatus, type AuthorizationType, type AvailabilityCheck, type AvailabilityResult, type AvailableSlot, type BenefitType, type Booking, type BookingRequirementOverride, type BookingStatus, type BookingWithDetails, type BufferTimes, type Bundle, type BundleComponentData, type BundleComponentInfo, type BundlePriceType, type BundleProduct, type BundleSelectionData, type BundleSelectionInput, type BundleStoredSelection, type BundleSummary, type BundleWithDetails, type Business, type BusinessHours, type BusinessPreferences, BusinessService, type BusinessSettings, type BusinessType, type BusinessWithLocations, CHECKOUT_MODE, CHECKOUT_MUTATION, CHECKOUT_STEP, CURRENCY_SYMBOLS, type CancelBookingInput, type CancelOrderInput, type CancellationPolicy, type Cart, type CartAddOn, type CartChannel, type CartItem, type CartItemDetails, CartOperations, type CartStatus, type CartSummary, type CartTotals, CatalogueQueries, type Category, type CategoryInfo, type CategorySummary, type ChangePasswordInput, type CheckSlotAvailabilityInput, type CheckoutAddressInfo, type CheckoutCustomerInfo, type CheckoutFormData, type CheckoutInput, type CheckoutMode, CheckoutService as CheckoutOperations, type CheckoutOrderType, type CheckoutPaymentMethod, type CheckoutResult, CheckoutService, type CheckoutStep, type ChosenPrice, CimplifyClient, type CimplifyConfig, CimplifyError, type Collection, type CollectionProduct, type CollectionSummary, type ComponentGroup, type ComponentGroupWithComponents, type ComponentPriceBreakdown, type ComponentSelectionInput, type ComponentSourceType, type Composite, type CompositeComponent, type CompositePriceBreakdown, type CompositePriceResult, type CompositePricingMode, type CompositeSelectionData, type ComponentSelectionInput as CompositeSelectionInput, type CompositeStoredSelection, type CompositeWithDetails, type ContactType, type CreateAddressInput, type CreateMobileMoneyInput, type Currency, type Customer, type CustomerAddress, type CustomerLinkPreferences, type CustomerMobileMoney, type CustomerServicePreferences, DEFAULT_COUNTRY, DEFAULT_CURRENCY, type DayAvailability, type DepositResult, type DepositType, type DeviceType, type DigitalProductType, type DiscountBreakdown, type DiscountDetails, type DisplayAddOn, type DisplayAddOnOption, type DisplayCart, type DisplayCartItem, type EnrollAndLinkOrderInput, type EnrollAndLinkOrderResult, type EnrollmentData, type Err, ErrorCode, type ErrorCodeType, type FeeBearerType, type FormatCompactOptions, type FormatPriceOptions, type FulfillmentLink, type FulfillmentStatus, type FulfillmentType, type GetAvailableSlotsInput, type GetOrdersOptions, type GetProductsOptions, type GroupPricingBehavior, type InitializePaymentResult, InventoryService, type InventorySummary, type InventoryType, type KitchenOrderItem, type KitchenOrderResult, LINK_MUTATION, LINK_QUERY, type LineConfiguration, type LineItem, type LineType, type LinkData, type LinkEnrollResult, LinkService, type LinkSession, type LinkStatusResult, type LiteBootstrap, LiteService, type Location, type LocationAppointment, type LocationProductPrice, type LocationStock, type LocationTaxBehavior, type LocationTaxOverrides, type LocationTimeProfile, type LocationWithDetails, MOBILE_MONEY_PROVIDER, MOBILE_MONEY_PROVIDERS, type MobileMoneyData, type MobileMoneyDetails, type MobileMoneyProvider, type Money, type MutationRequest, ORDER_MUTATION, ORDER_TYPE, type Ok, type Order, type OrderChannel, type OrderFilter, type OrderFulfillmentSummary, type OrderGroup, type OrderGroupDetails, type OrderGroupPayment, type OrderGroupPaymentState, type OrderGroupPaymentSummary, type OrderHistory, type OrderLineState, type OrderLineStatus, type OrderPaymentEvent, OrderQueries, type OrderSplitDetail, type OrderStatus, type OtpResult, PAYMENT_METHOD, PAYMENT_MUTATION, PAYMENT_STATE, PICKUP_TIME_TYPE, type Pagination, type PaginationParams, type ParsedPrice, type Payment, type PaymentErrorDetails, type PaymentMethod, type PaymentMethodType, type PaymentProcessingState, type PaymentProvider, type PaymentResponse, type PaymentState, type PaymentStatus, type PaymentStatusResponse, type PickupTime, type PickupTimeType, type Price, type PriceAdjustment, type PriceDecisionPath, type PriceEntryType, type PriceInfo, type PricePathTaxInfo, type PriceSource, type PricingOverrides, type Product, type ProductAddOn, type ProductAvailability, type ProductStock, type ProductTimeProfile, type ProductType, type ProductVariant, type ProductVariantValue, type ProductWithDetails, type ProductWithPrice, QueryBuilder, type QueryRequest, type RefundOrderInput, type ReminderMethod, type ReminderSettings, type RequestOtpInput, type RescheduleBookingInput, type ResourceAssignment, type ResourceAvailabilityException, type ResourceAvailabilityRule, type ResourceType, type ResponseMetadata, type Result, type RevokeAllSessionsResult, type RevokeSessionResult, type Room, type SalesChannel, type SchedulingMetadata, type SchedulingResult, SchedulingService, type SearchOptions, type SelectedAddOnOption, type Service, type ServiceAvailabilityException, type ServiceAvailabilityParams, type ServiceAvailabilityResult, type ServiceAvailabilityRule, type ServiceCharge, type ServiceNotes, type ServiceScheduleRequest, type ServiceStaffRequirement, type ServiceStatus, type ServiceWithStaff, type Staff, type StaffAssignment, type StaffAvailabilityException, type StaffAvailabilityRule, type StaffBookingProfile, type StaffRole, type StaffScheduleItem, type Stock, type StockLevel, type StockOwnershipType, type StockStatus, type StorefrontBootstrap, type SubmitAuthorizationInput, type Table, type TableInfo, type TaxComponent, type TaxInfo, type TaxPathComponent, type TimeRange, type TimeRanges, type TimeSlot, type UICart, type UICartBusiness, type UICartCustomer, type UICartLocation, type UICartPricing, type UpdateAddressInput, type UpdateCartItemInput, type UpdateOrderStatusInput, type UpdateProfileInput, type VariantAxis, type VariantAxisSelection, type VariantAxisValue, type VariantAxisWithValues, type VariantDetails, type VariantDetailsDTO, type VariantDisplayAttribute, type VariantLocationAvailability, type VariantStock, type VariantStrategy, type VerifyOtpInput, categorizePaymentError, combine, combineObject, createCimplifyClient, detectMobileMoneyProvider, err, extractPriceInfo, flatMap, formatMoney, formatNumberCompact, formatPrice, formatPriceAdjustment, formatPriceCompact, formatProductPrice, fromPromise, generateIdempotencyKey, getBasePrice, getCurrencySymbol, getDiscountPercentage, getDisplayPrice, getMarkupPercentage, getOrElse, getProductCurrency, isCimplifyError, isErr, isOk, isOnSale, isRetryableError, mapError, mapResult, normalizePaymentResponse, normalizeStatusResponse, ok, parsePrice, parsePricePath, parsedPriceToPriceInfo, query, toNullable, tryCatch, unwrap };
+export { AUTHORIZATION_TYPE, AUTH_MUTATION, type AddOn, type AddOnDetails, type AddOnGroupDetails, type AddOnOption, type AddOnOptionDetails, type AddOnOptionPrice, type AddOnWithOptions, type AddToCartInput, type AddressData, type AdjustmentType, type AmountToPay, type ApiError, type ApiResponse, type AppliedDiscount, type AuthResponse, AuthService, type AuthStatus, type AuthorizationType, type AvailabilityCheck, type AvailabilityResult, type AvailableSlot, type BenefitType, type Booking, type BookingRequirementOverride, type BookingStatus, type BookingWithDetails, type BufferTimes, type Bundle, type BundleComponentData, type BundleComponentInfo, type BundlePriceType, type BundleProduct, type BundleSelectionData, type BundleSelectionInput, type BundleStoredSelection, type BundleSummary, type BundleWithDetails, type Business, type BusinessHours, type BusinessPreferences, BusinessService, type BusinessSettings, type BusinessType, type BusinessWithLocations, CHECKOUT_MODE, CHECKOUT_MUTATION, CHECKOUT_STEP, CURRENCY_SYMBOLS, type CancelBookingInput, type CancelOrderInput, type CancellationPolicy, type Cart, type CartAddOn, type CartChannel, type CartItem, type CartItemDetails, CartOperations, type CartStatus, type CartSummary, type CartTotals, CatalogueQueries, type Category, type CategoryInfo, type CategorySummary, type ChangePasswordInput, type CheckSlotAvailabilityInput, type CheckoutAddressInfo, type CheckoutCustomerInfo, type CheckoutFormData, type CheckoutInput, type CheckoutMode, CheckoutService as CheckoutOperations, type CheckoutOrderType, type CheckoutPaymentMethod, type CheckoutResult, CheckoutService, type CheckoutStep, type ChosenPrice, CimplifyClient, type CimplifyConfig, CimplifyError, type Collection, type CollectionProduct, type CollectionSummary, type ComponentGroup, type ComponentGroupWithComponents, type ComponentPriceBreakdown, type ComponentSelectionInput, type ComponentSourceType, type Composite, type CompositeComponent, type CompositePriceBreakdown, type CompositePriceResult, type CompositePricingMode, type CompositeSelectionData, type ComponentSelectionInput as CompositeSelectionInput, type CompositeStoredSelection, type CompositeWithDetails, type ContactType, type CreateAddressInput, type CreateMobileMoneyInput, type Currency, type Customer, type CustomerAddress, type CustomerLinkPreferences, type CustomerMobileMoney, type CustomerServicePreferences, DEFAULT_COUNTRY, DEFAULT_CURRENCY, type DayAvailability, type DepositResult, type DepositType, type DeviceType, type DigitalProductType, type DiscountBreakdown, type DiscountDetails, type DisplayAddOn, type DisplayAddOnOption, type DisplayCart, type DisplayCartItem, type EnrollAndLinkOrderInput, type EnrollAndLinkOrderResult, type EnrollmentData, type Err, ErrorCode, type ErrorCodeType, type FeeBearerType, type FormatCompactOptions, type FormatPriceOptions, type FulfillmentLink, type FulfillmentStatus, type FulfillmentType, type GetAvailableSlotsInput, type GetOrdersOptions, type GetProductsOptions, type GroupPricingBehavior, type InitializePaymentResult, InventoryService, type InventorySummary, type InventoryType, type KitchenOrderItem, type KitchenOrderResult, LINK_MUTATION, LINK_QUERY, type LineConfiguration, type LineItem, type LineType, type LinkData, type LinkEnrollResult, LinkService, type LinkSession, type LinkStatusResult, type LiteBootstrap, LiteService, type Location, type LocationAppointment, type LocationProductPrice, type LocationStock, type LocationTaxBehavior, type LocationTaxOverrides, type LocationTimeProfile, type LocationWithDetails, MOBILE_MONEY_PROVIDER, MOBILE_MONEY_PROVIDERS, type MobileMoneyData, type MobileMoneyDetails, type MobileMoneyProvider, type Money, type MutationRequest, ORDER_MUTATION, ORDER_TYPE, type ObservabilityHooks, type Ok, type Order, type OrderChannel, type OrderFilter, type OrderFulfillmentSummary, type OrderGroup, type OrderGroupDetails, type OrderGroupPayment, type OrderGroupPaymentState, type OrderGroupPaymentSummary, type OrderHistory, type OrderLineState, type OrderLineStatus, type OrderPaymentEvent, OrderQueries, type OrderSplitDetail, type OrderStatus, type OtpResult, PAYMENT_METHOD, PAYMENT_MUTATION, PAYMENT_STATE, PICKUP_TIME_TYPE, type Pagination, type PaginationParams, type ParsedPrice, type Payment, type PaymentErrorDetails, type PaymentMethod, type PaymentMethodType, type PaymentProcessingState, type PaymentProvider, type PaymentResponse, type PaymentState, type PaymentStatus, type PaymentStatusResponse, type PickupTime, type PickupTimeType, type Price, type PriceAdjustment, type PriceDecisionPath, type PriceEntryType, type PriceInfo, type PricePathTaxInfo, type PriceSource, type PricingOverrides, type Product, type ProductAddOn, type ProductAvailability, type ProductStock, type ProductTimeProfile, type ProductType, type ProductVariant, type ProductVariantValue, type ProductWithDetails, type ProductWithPrice, QueryBuilder, type QueryRequest, type RefundOrderInput, type ReminderMethod, type ReminderSettings, type RequestContext, type RequestErrorEvent, type RequestOtpInput, type RequestStartEvent, type RequestSuccessEvent, type RescheduleBookingInput, type ResourceAssignment, type ResourceAvailabilityException, type ResourceAvailabilityRule, type ResourceType, type ResponseMetadata, type Result, type RetryEvent, type RevokeAllSessionsResult, type RevokeSessionResult, type Room, type SalesChannel, type SchedulingMetadata, type SchedulingResult, SchedulingService, type SearchOptions, type SelectedAddOnOption, type Service, type ServiceAvailabilityException, type ServiceAvailabilityParams, type ServiceAvailabilityResult, type ServiceAvailabilityRule, type ServiceCharge, type ServiceNotes, type ServiceScheduleRequest, type ServiceStaffRequirement, type ServiceStatus, type ServiceWithStaff, type SessionChangeEvent, type Staff, type StaffAssignment, type StaffAvailabilityException, type StaffAvailabilityRule, type StaffBookingProfile, type StaffRole, type StaffScheduleItem, type Stock, type StockLevel, type StockOwnershipType, type StockStatus, type StorefrontBootstrap, type SubmitAuthorizationInput, type Table, type TableInfo, type TaxComponent, type TaxInfo, type TaxPathComponent, type TimeRange, type TimeRanges, type TimeSlot, type UICart, type UICartBusiness, type UICartCustomer, type UICartLocation, type UICartPricing, type UpdateAddressInput, type UpdateCartItemInput, type UpdateOrderStatusInput, type UpdateProfileInput, type VariantAxis, type VariantAxisSelection, type VariantAxisValue, type VariantAxisWithValues, type VariantDetails, type VariantDetailsDTO, type VariantDisplayAttribute, type VariantLocationAvailability, type VariantStock, type VariantStrategy, type VerifyOtpInput, categorizePaymentError, combine, combineObject, createCimplifyClient, detectMobileMoneyProvider, err, extractPriceInfo, flatMap, formatMoney, formatNumberCompact, formatPrice, formatPriceAdjustment, formatPriceCompact, formatProductPrice, fromPromise, generateIdempotencyKey, getBasePrice, getCurrencySymbol, getDiscountPercentage, getDisplayPrice, getMarkupPercentage, getOrElse, getProductCurrency, isCimplifyError, isErr, isOk, isOnSale, isRetryableError, mapError, mapResult, normalizePaymentResponse, normalizeStatusResponse, ok, parsePrice, parsePricePath, parsedPriceToPriceInfo, query, toNullable, tryCatch, unwrap };

package/dist/index.d.ts

@@ -1,3 +1,95 @@
+/**
+ * Observability hooks for monitoring SDK behavior.
+ *
+ * These hooks allow you to plug in your own logging, metrics, and tracing
+ * without the SDK depending on any specific observability library.
+ *
+ * @example
+ * ```typescript
+ * const client = createCimplifyClient({
+ *   hooks: {
+ *     onRequestStart: ({ method, path }) => {
+ *       console.log(`[SDK] ${method} ${path}`);
+ *     },
+ *     onRequestSuccess: ({ method, path, durationMs }) => {
+ *       metrics.histogram('sdk.request.duration', durationMs, { method, path });
+ *     },
+ *     onRequestError: ({ method, path, error, retryCount }) => {
+ *       Sentry.captureException(error, { extra: { method, path, retryCount } });
+ *     },
+ *   },
+ * });
+ * ```
+ */
+/** Context passed to request lifecycle hooks */
+interface RequestContext {
+    /** HTTP method */
+    method: "GET" | "POST" | "DELETE";
+    /** Request path (e.g., "/api/q", "/api/m") */
+    path: string;
+    /** Full URL */
+    url: string;
+    /** Request body (for POST requests) */
+    body?: unknown;
+    /** Timestamp when request started */
+    startTime: number;
+}
+/** Passed when a request starts */
+interface RequestStartEvent extends RequestContext {
+}
+/** Passed when a request succeeds */
+interface RequestSuccessEvent extends RequestContext {
+    /** HTTP status code */
+    status: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
+/** Passed when a request fails */
+interface RequestErrorEvent extends RequestContext {
+    /** The error that occurred */
+    error: Error;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Number of retries attempted before giving up */
+    retryCount: number;
+    /** Whether the error is retryable */
+    retryable: boolean;
+}
+/** Passed when a retry is about to happen */
+interface RetryEvent extends RequestContext {
+    /** Which retry attempt (1, 2, 3...) */
+    attempt: number;
+    /** Delay before retry in milliseconds */
+    delayMs: number;
+    /** The error that triggered the retry */
+    error: Error;
+}
+/** Passed when session token changes */
+interface SessionChangeEvent {
+    /** Previous token (null if none) */
+    previousToken: string | null;
+    /** New token (null if cleared) */
+    newToken: string | null;
+    /** Source of the change */
+    source: "response" | "manual" | "clear";
+}
+/**
+ * Observability hooks configuration.
+ * All hooks are optional - only implement what you need.
+ */
+interface ObservabilityHooks {
+    /** Called when a request is about to be sent */
+    onRequestStart?: (event: RequestStartEvent) => void;
+    /** Called when a request completes successfully */
+    onRequestSuccess?: (event: RequestSuccessEvent) => void;
+    /** Called when a request fails (after all retries exhausted) */
+    onRequestError?: (event: RequestErrorEvent) => void;
+    /** Called before each retry attempt */
+    onRetry?: (event: RetryEvent) => void;
+    /** Called when session token changes */
+    onSessionChange?: (event: SessionChangeEvent) => void;
+}
+
 /** Decimal value represented as string for precision */
 type Money = string;
 /** Supported currencies */
@@ -2839,6 +2931,8 @@ interface CimplifyConfig {
     maxRetries?: number;
     /** Base delay between retries in milliseconds (default: 1000) */
     retryDelay?: number;
+    /** Observability hooks for logging, metrics, and tracing */
+    hooks?: ObservabilityHooks;
 }
 declare class CimplifyClient {
     private baseUrl;
@@ -2849,6 +2943,9 @@ declare class CimplifyClient {
     private timeout;
     private maxRetries;
     private retryDelay;
+    private hooks;
+    /** In-flight request deduplication map */
+    private inflightRequests;
     private _catalogue?;
     private _cart?;
     private _checkout?;
@@ -2868,11 +2965,29 @@ declare class CimplifyClient {
     private getHeaders;
     private updateSessionFromResponse;
     /**
-     * Resilient fetch with timeout and automatic retries for network errors.
+     * Resilient fetch with timeout, automatic retries, and observability hooks.
      * Uses exponential backoff: 1s, 2s, 4s between retries.
      */
     private resilientFetch;
+    /**
+     * Generate a deduplication key for a request.
+     * Same query + variables = same key = deduplicated.
+     */
+    private getDedupeKey;
+    /**
+     * Execute a request with deduplication.
+     * If an identical request is already in-flight, return the same promise.
+     * This prevents redundant network calls when multiple components request the same data.
+     */
+    private deduplicatedRequest;
+    /**
+     * Execute a query with deduplication.
+     * Multiple identical queries made simultaneously will share a single network request.
+     */
     query<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * Execute a mutation. NOT deduplicated - mutations have side effects.
+     */
     call<T = unknown>(method: string, args?: unknown): Promise<T>;
     get<T = unknown>(path: string): Promise<T>;
     post<T = unknown>(path: string, body?: unknown): Promise<T>;
@@ -3415,4 +3530,4 @@ interface ApiResponse<T> {
     metadata?: ResponseMetadata;
 }
 
-export { AUTHORIZATION_TYPE, AUTH_MUTATION, type AddOn, type AddOnDetails, type AddOnGroupDetails, type AddOnOption, type AddOnOptionDetails, type AddOnOptionPrice, type AddOnWithOptions, type AddToCartInput, type AddressData, type AdjustmentType, type AmountToPay, type ApiError, type ApiResponse, type AppliedDiscount, type AuthResponse, AuthService, type AuthStatus, type AuthorizationType, type AvailabilityCheck, type AvailabilityResult, type AvailableSlot, type BenefitType, type Booking, type BookingRequirementOverride, type BookingStatus, type BookingWithDetails, type BufferTimes, type Bundle, type BundleComponentData, type BundleComponentInfo, type BundlePriceType, type BundleProduct, type BundleSelectionData, type BundleSelectionInput, type BundleStoredSelection, type BundleSummary, type BundleWithDetails, type Business, type BusinessHours, type BusinessPreferences, BusinessService, type BusinessSettings, type BusinessType, type BusinessWithLocations, CHECKOUT_MODE, CHECKOUT_MUTATION, CHECKOUT_STEP, CURRENCY_SYMBOLS, type CancelBookingInput, type CancelOrderInput, type CancellationPolicy, type Cart, type CartAddOn, type CartChannel, type CartItem, type CartItemDetails, CartOperations, type CartStatus, type CartSummary, type CartTotals, CatalogueQueries, type Category, type CategoryInfo, type CategorySummary, type ChangePasswordInput, type CheckSlotAvailabilityInput, type CheckoutAddressInfo, type CheckoutCustomerInfo, type CheckoutFormData, type CheckoutInput, type CheckoutMode, CheckoutService as CheckoutOperations, type CheckoutOrderType, type CheckoutPaymentMethod, type CheckoutResult, CheckoutService, type CheckoutStep, type ChosenPrice, CimplifyClient, type CimplifyConfig, CimplifyError, type Collection, type CollectionProduct, type CollectionSummary, type ComponentGroup, type ComponentGroupWithComponents, type ComponentPriceBreakdown, type ComponentSelectionInput, type ComponentSourceType, type Composite, type CompositeComponent, type CompositePriceBreakdown, type CompositePriceResult, type CompositePricingMode, type CompositeSelectionData, type ComponentSelectionInput as CompositeSelectionInput, type CompositeStoredSelection, type CompositeWithDetails, type ContactType, type CreateAddressInput, type CreateMobileMoneyInput, type Currency, type Customer, type CustomerAddress, type CustomerLinkPreferences, type CustomerMobileMoney, type CustomerServicePreferences, DEFAULT_COUNTRY, DEFAULT_CURRENCY, type DayAvailability, type DepositResult, type DepositType, type DeviceType, type DigitalProductType, type DiscountBreakdown, type DiscountDetails, type DisplayAddOn, type DisplayAddOnOption, type DisplayCart, type DisplayCartItem, type EnrollAndLinkOrderInput, type EnrollAndLinkOrderResult, type EnrollmentData, type Err, ErrorCode, type ErrorCodeType, type FeeBearerType, type FormatCompactOptions, type FormatPriceOptions, type FulfillmentLink, type FulfillmentStatus, type FulfillmentType, type GetAvailableSlotsInput, type GetOrdersOptions, type GetProductsOptions, type GroupPricingBehavior, type InitializePaymentResult, InventoryService, type InventorySummary, type InventoryType, type KitchenOrderItem, type KitchenOrderResult, LINK_MUTATION, LINK_QUERY, type LineConfiguration, type LineItem, type LineType, type LinkData, type LinkEnrollResult, LinkService, type LinkSession, type LinkStatusResult, type LiteBootstrap, LiteService, type Location, type LocationAppointment, type LocationProductPrice, type LocationStock, type LocationTaxBehavior, type LocationTaxOverrides, type LocationTimeProfile, type LocationWithDetails, MOBILE_MONEY_PROVIDER, MOBILE_MONEY_PROVIDERS, type MobileMoneyData, type MobileMoneyDetails, type MobileMoneyProvider, type Money, type MutationRequest, ORDER_MUTATION, ORDER_TYPE, type Ok, type Order, type OrderChannel, type OrderFilter, type OrderFulfillmentSummary, type OrderGroup, type OrderGroupDetails, type OrderGroupPayment, type OrderGroupPaymentState, type OrderGroupPaymentSummary, type OrderHistory, type OrderLineState, type OrderLineStatus, type OrderPaymentEvent, OrderQueries, type OrderSplitDetail, type OrderStatus, type OtpResult, PAYMENT_METHOD, PAYMENT_MUTATION, PAYMENT_STATE, PICKUP_TIME_TYPE, type Pagination, type PaginationParams, type ParsedPrice, type Payment, type PaymentErrorDetails, type PaymentMethod, type PaymentMethodType, type PaymentProcessingState, type PaymentProvider, type PaymentResponse, type PaymentState, type PaymentStatus, type PaymentStatusResponse, type PickupTime, type PickupTimeType, type Price, type PriceAdjustment, type PriceDecisionPath, type PriceEntryType, type PriceInfo, type PricePathTaxInfo, type PriceSource, type PricingOverrides, type Product, type ProductAddOn, type ProductAvailability, type ProductStock, type ProductTimeProfile, type ProductType, type ProductVariant, type ProductVariantValue, type ProductWithDetails, type ProductWithPrice, QueryBuilder, type QueryRequest, type RefundOrderInput, type ReminderMethod, type ReminderSettings, type RequestOtpInput, type RescheduleBookingInput, type ResourceAssignment, type ResourceAvailabilityException, type ResourceAvailabilityRule, type ResourceType, type ResponseMetadata, type Result, type RevokeAllSessionsResult, type RevokeSessionResult, type Room, type SalesChannel, type SchedulingMetadata, type SchedulingResult, SchedulingService, type SearchOptions, type SelectedAddOnOption, type Service, type ServiceAvailabilityException, type ServiceAvailabilityParams, type ServiceAvailabilityResult, type ServiceAvailabilityRule, type ServiceCharge, type ServiceNotes, type ServiceScheduleRequest, type ServiceStaffRequirement, type ServiceStatus, type ServiceWithStaff, type Staff, type StaffAssignment, type StaffAvailabilityException, type StaffAvailabilityRule, type StaffBookingProfile, type StaffRole, type StaffScheduleItem, type Stock, type StockLevel, type StockOwnershipType, type StockStatus, type StorefrontBootstrap, type SubmitAuthorizationInput, type Table, type TableInfo, type TaxComponent, type TaxInfo, type TaxPathComponent, type TimeRange, type TimeRanges, type TimeSlot, type UICart, type UICartBusiness, type UICartCustomer, type UICartLocation, type UICartPricing, type UpdateAddressInput, type UpdateCartItemInput, type UpdateOrderStatusInput, type UpdateProfileInput, type VariantAxis, type VariantAxisSelection, type VariantAxisValue, type VariantAxisWithValues, type VariantDetails, type VariantDetailsDTO, type VariantDisplayAttribute, type VariantLocationAvailability, type VariantStock, type VariantStrategy, type VerifyOtpInput, categorizePaymentError, combine, combineObject, createCimplifyClient, detectMobileMoneyProvider, err, extractPriceInfo, flatMap, formatMoney, formatNumberCompact, formatPrice, formatPriceAdjustment, formatPriceCompact, formatProductPrice, fromPromise, generateIdempotencyKey, getBasePrice, getCurrencySymbol, getDiscountPercentage, getDisplayPrice, getMarkupPercentage, getOrElse, getProductCurrency, isCimplifyError, isErr, isOk, isOnSale, isRetryableError, mapError, mapResult, normalizePaymentResponse, normalizeStatusResponse, ok, parsePrice, parsePricePath, parsedPriceToPriceInfo, query, toNullable, tryCatch, unwrap };
+export { AUTHORIZATION_TYPE, AUTH_MUTATION, type AddOn, type AddOnDetails, type AddOnGroupDetails, type AddOnOption, type AddOnOptionDetails, type AddOnOptionPrice, type AddOnWithOptions, type AddToCartInput, type AddressData, type AdjustmentType, type AmountToPay, type ApiError, type ApiResponse, type AppliedDiscount, type AuthResponse, AuthService, type AuthStatus, type AuthorizationType, type AvailabilityCheck, type AvailabilityResult, type AvailableSlot, type BenefitType, type Booking, type BookingRequirementOverride, type BookingStatus, type BookingWithDetails, type BufferTimes, type Bundle, type BundleComponentData, type BundleComponentInfo, type BundlePriceType, type BundleProduct, type BundleSelectionData, type BundleSelectionInput, type BundleStoredSelection, type BundleSummary, type BundleWithDetails, type Business, type BusinessHours, type BusinessPreferences, BusinessService, type BusinessSettings, type BusinessType, type BusinessWithLocations, CHECKOUT_MODE, CHECKOUT_MUTATION, CHECKOUT_STEP, CURRENCY_SYMBOLS, type CancelBookingInput, type CancelOrderInput, type CancellationPolicy, type Cart, type CartAddOn, type CartChannel, type CartItem, type CartItemDetails, CartOperations, type CartStatus, type CartSummary, type CartTotals, CatalogueQueries, type Category, type CategoryInfo, type CategorySummary, type ChangePasswordInput, type CheckSlotAvailabilityInput, type CheckoutAddressInfo, type CheckoutCustomerInfo, type CheckoutFormData, type CheckoutInput, type CheckoutMode, CheckoutService as CheckoutOperations, type CheckoutOrderType, type CheckoutPaymentMethod, type CheckoutResult, CheckoutService, type CheckoutStep, type ChosenPrice, CimplifyClient, type CimplifyConfig, CimplifyError, type Collection, type CollectionProduct, type CollectionSummary, type ComponentGroup, type ComponentGroupWithComponents, type ComponentPriceBreakdown, type ComponentSelectionInput, type ComponentSourceType, type Composite, type CompositeComponent, type CompositePriceBreakdown, type CompositePriceResult, type CompositePricingMode, type CompositeSelectionData, type ComponentSelectionInput as CompositeSelectionInput, type CompositeStoredSelection, type CompositeWithDetails, type ContactType, type CreateAddressInput, type CreateMobileMoneyInput, type Currency, type Customer, type CustomerAddress, type CustomerLinkPreferences, type CustomerMobileMoney, type CustomerServicePreferences, DEFAULT_COUNTRY, DEFAULT_CURRENCY, type DayAvailability, type DepositResult, type DepositType, type DeviceType, type DigitalProductType, type DiscountBreakdown, type DiscountDetails, type DisplayAddOn, type DisplayAddOnOption, type DisplayCart, type DisplayCartItem, type EnrollAndLinkOrderInput, type EnrollAndLinkOrderResult, type EnrollmentData, type Err, ErrorCode, type ErrorCodeType, type FeeBearerType, type FormatCompactOptions, type FormatPriceOptions, type FulfillmentLink, type FulfillmentStatus, type FulfillmentType, type GetAvailableSlotsInput, type GetOrdersOptions, type GetProductsOptions, type GroupPricingBehavior, type InitializePaymentResult, InventoryService, type InventorySummary, type InventoryType, type KitchenOrderItem, type KitchenOrderResult, LINK_MUTATION, LINK_QUERY, type LineConfiguration, type LineItem, type LineType, type LinkData, type LinkEnrollResult, LinkService, type LinkSession, type LinkStatusResult, type LiteBootstrap, LiteService, type Location, type LocationAppointment, type LocationProductPrice, type LocationStock, type LocationTaxBehavior, type LocationTaxOverrides, type LocationTimeProfile, type LocationWithDetails, MOBILE_MONEY_PROVIDER, MOBILE_MONEY_PROVIDERS, type MobileMoneyData, type MobileMoneyDetails, type MobileMoneyProvider, type Money, type MutationRequest, ORDER_MUTATION, ORDER_TYPE, type ObservabilityHooks, type Ok, type Order, type OrderChannel, type OrderFilter, type OrderFulfillmentSummary, type OrderGroup, type OrderGroupDetails, type OrderGroupPayment, type OrderGroupPaymentState, type OrderGroupPaymentSummary, type OrderHistory, type OrderLineState, type OrderLineStatus, type OrderPaymentEvent, OrderQueries, type OrderSplitDetail, type OrderStatus, type OtpResult, PAYMENT_METHOD, PAYMENT_MUTATION, PAYMENT_STATE, PICKUP_TIME_TYPE, type Pagination, type PaginationParams, type ParsedPrice, type Payment, type PaymentErrorDetails, type PaymentMethod, type PaymentMethodType, type PaymentProcessingState, type PaymentProvider, type PaymentResponse, type PaymentState, type PaymentStatus, type PaymentStatusResponse, type PickupTime, type PickupTimeType, type Price, type PriceAdjustment, type PriceDecisionPath, type PriceEntryType, type PriceInfo, type PricePathTaxInfo, type PriceSource, type PricingOverrides, type Product, type ProductAddOn, type ProductAvailability, type ProductStock, type ProductTimeProfile, type ProductType, type ProductVariant, type ProductVariantValue, type ProductWithDetails, type ProductWithPrice, QueryBuilder, type QueryRequest, type RefundOrderInput, type ReminderMethod, type ReminderSettings, type RequestContext, type RequestErrorEvent, type RequestOtpInput, type RequestStartEvent, type RequestSuccessEvent, type RescheduleBookingInput, type ResourceAssignment, type ResourceAvailabilityException, type ResourceAvailabilityRule, type ResourceType, type ResponseMetadata, type Result, type RetryEvent, type RevokeAllSessionsResult, type RevokeSessionResult, type Room, type SalesChannel, type SchedulingMetadata, type SchedulingResult, SchedulingService, type SearchOptions, type SelectedAddOnOption, type Service, type ServiceAvailabilityException, type ServiceAvailabilityParams, type ServiceAvailabilityResult, type ServiceAvailabilityRule, type ServiceCharge, type ServiceNotes, type ServiceScheduleRequest, type ServiceStaffRequirement, type ServiceStatus, type ServiceWithStaff, type SessionChangeEvent, type Staff, type StaffAssignment, type StaffAvailabilityException, type StaffAvailabilityRule, type StaffBookingProfile, type StaffRole, type StaffScheduleItem, type Stock, type StockLevel, type StockOwnershipType, type StockStatus, type StorefrontBootstrap, type SubmitAuthorizationInput, type Table, type TableInfo, type TaxComponent, type TaxInfo, type TaxPathComponent, type TimeRange, type TimeRanges, type TimeSlot, type UICart, type UICartBusiness, type UICartCustomer, type UICartLocation, type UICartPricing, type UpdateAddressInput, type UpdateCartItemInput, type UpdateOrderStatusInput, type UpdateProfileInput, type VariantAxis, type VariantAxisSelection, type VariantAxisValue, type VariantAxisWithValues, type VariantDetails, type VariantDetailsDTO, type VariantDisplayAttribute, type VariantLocationAvailability, type VariantStock, type VariantStrategy, type VerifyOtpInput, categorizePaymentError, combine, combineObject, createCimplifyClient, detectMobileMoneyProvider, err, extractPriceInfo, flatMap, formatMoney, formatNumberCompact, formatPrice, formatPriceAdjustment, formatPriceCompact, formatProductPrice, fromPromise, generateIdempotencyKey, getBasePrice, getCurrencySymbol, getDiscountPercentage, getDisplayPrice, getMarkupPercentage, getOrElse, getProductCurrency, isCimplifyError, isErr, isOk, isOnSale, isRetryableError, mapError, mapResult, normalizePaymentResponse, normalizeStatusResponse, ok, parsePrice, parsePricePath, parsedPriceToPriceInfo, query, toNullable, tryCatch, unwrap };

package/dist/index.js

@@ -1469,6 +1469,8 @@ function deriveUrls() {
 var CimplifyClient = class {
   constructor(config = {}) {
     this.sessionToken = null;
+    /** In-flight request deduplication map */
+    this.inflightRequests = /* @__PURE__ */ new Map();
     this.publicKey = config.publicKey || "";
     const urls = deriveUrls();
     this.baseUrl = urls.baseUrl;
@@ -1477,18 +1479,31 @@ var CimplifyClient = class {
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT_MS;
     this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.retryDelay = config.retryDelay ?? DEFAULT_RETRY_DELAY_MS;
+    this.hooks = config.hooks ?? {};
     this.sessionToken = this.loadSessionToken();
   }
   getSessionToken() {
     return this.sessionToken;
   }
   setSessionToken(token) {
+    const previous = this.sessionToken;
     this.sessionToken = token;
     this.saveSessionToken(token);
+    this.hooks.onSessionChange?.({
+      previousToken: previous,
+      newToken: token,
+      source: "manual"
+    });
   }
   clearSession() {
+    const previous = this.sessionToken;
     this.sessionToken = null;
     this.saveSessionToken(null);
+    this.hooks.onSessionChange?.({
+      previousToken: previous,
+      newToken: null,
+      source: "clear"
+    });
   }
   loadSessionToken() {
     if (typeof window !== "undefined" && window.localStorage) {
@@ -1518,15 +1533,33 @@ var CimplifyClient = class {
   updateSessionFromResponse(response) {
     const newToken = response.headers.get(SESSION_TOKEN_HEADER);
     if (newToken && newToken !== this.sessionToken) {
+      const previous = this.sessionToken;
       this.sessionToken = newToken;
       this.saveSessionToken(newToken);
+      this.hooks.onSessionChange?.({
+        previousToken: previous,
+        newToken,
+        source: "response"
+      });
     }
   }
   /**
-   * Resilient fetch with timeout and automatic retries for network errors.
+   * Resilient fetch with timeout, automatic retries, and observability hooks.
    * Uses exponential backoff: 1s, 2s, 4s between retries.
    */
   async resilientFetch(url, options) {
+    const method = options.method || "GET";
+    const path = url.replace(this.baseUrl, "").replace(this.linkApiUrl, "");
+    const startTime = Date.now();
+    let retryCount = 0;
+    const context = {
+      method,
+      path,
+      url,
+      body: options.body ? JSON.parse(options.body) : void 0,
+      startTime
+    };
+    this.hooks.onRequestStart?.(context);
     let lastError;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       try {
@@ -1538,39 +1571,113 @@ var CimplifyClient = class {
         });
         clearTimeout(timeoutId);
         if (response.ok || response.status >= 400 && response.status < 500) {
+          this.hooks.onRequestSuccess?.({
+            ...context,
+            status: response.status,
+            durationMs: Date.now() - startTime
+          });
           return response;
         }
         if (response.status >= 500 && attempt < this.maxRetries) {
+          retryCount++;
           const delay = this.retryDelay * Math.pow(2, attempt);
+          this.hooks.onRetry?.({
+            ...context,
+            attempt: retryCount,
+            delayMs: delay,
+            error: new Error(`Server error: ${response.status}`)
+          });
           await sleep(delay);
           continue;
         }
+        this.hooks.onRequestSuccess?.({
+          ...context,
+          status: response.status,
+          durationMs: Date.now() - startTime
+        });
         return response;
       } catch (error) {
         lastError = error;
-        if (!isRetryable(error) || attempt >= this.maxRetries) {
-          throw toNetworkError(error);
+        const networkError = toNetworkError(error);
+        const errorRetryable = isRetryable(error);
+        if (!errorRetryable || attempt >= this.maxRetries) {
+          this.hooks.onRequestError?.({
+            ...context,
+            error: networkError,
+            durationMs: Date.now() - startTime,
+            retryCount,
+            retryable: errorRetryable
+          });
+          throw networkError;
         }
+        retryCount++;
         const delay = this.retryDelay * Math.pow(2, attempt);
+        this.hooks.onRetry?.({
+          ...context,
+          attempt: retryCount,
+          delayMs: delay,
+          error: networkError
+        });
         await sleep(delay);
       }
     }
-    throw toNetworkError(lastError);
+    const finalError = toNetworkError(lastError);
+    this.hooks.onRequestError?.({
+      ...context,
+      error: finalError,
+      durationMs: Date.now() - startTime,
+      retryCount,
+      retryable: false
+    });
+    throw finalError;
   }
+  /**
+   * Generate a deduplication key for a request.
+   * Same query + variables = same key = deduplicated.
+   */
+  getDedupeKey(type, payload) {
+    return `${type}:${JSON.stringify(payload)}`;
+  }
+  /**
+   * Execute a request with deduplication.
+   * If an identical request is already in-flight, return the same promise.
+   * This prevents redundant network calls when multiple components request the same data.
+   */
+  async deduplicatedRequest(key, requestFn) {
+    const existing = this.inflightRequests.get(key);
+    if (existing) {
+      return existing;
+    }
+    const request = requestFn().finally(() => {
+      this.inflightRequests.delete(key);
+    });
+    this.inflightRequests.set(key, request);
+    return request;
+  }
+  /**
+   * Execute a query with deduplication.
+   * Multiple identical queries made simultaneously will share a single network request.
+   */
   async query(query2, variables) {
     const body = { query: query2 };
     if (variables) {
       body.variables = variables;
     }
-    const response = await this.resilientFetch(`${this.baseUrl}/api/q`, {
-      method: "POST",
-      credentials: this.credentials,
-      headers: this.getHeaders(),
-      body: JSON.stringify(body)
+    const key = this.getDedupeKey("query", body);
+    return this.deduplicatedRequest(key, async () => {
+      const response = await this.resilientFetch(`${this.baseUrl}/api/q`, {
+        method: "POST",
+        credentials: this.credentials,
+        headers: this.getHeaders(),
+        body: JSON.stringify(body)
+      });
+      this.updateSessionFromResponse(response);
+      return this.handleResponse(response);
     });
-    this.updateSessionFromResponse(response);
-    return this.handleResponse(response);
   }
+  /**
+   * Execute a mutation. NOT deduplicated - mutations have side effects.
+   */
   async call(method, args) {
     const body = {
       method,
@@ -1586,13 +1693,16 @@ var CimplifyClient = class {
     return this.handleResponse(response);
   }
   async get(path) {
-    const response = await this.resilientFetch(`${this.baseUrl}${path}`, {
-      method: "GET",
-      credentials: this.credentials,
-      headers: this.getHeaders()
+    const key = this.getDedupeKey("get", path);
+    return this.deduplicatedRequest(key, async () => {
+      const response = await this.resilientFetch(`${this.baseUrl}${path}`, {
+        method: "GET",
+        credentials: this.credentials,
+        headers: this.getHeaders()
+      });
+      this.updateSessionFromResponse(response);
+      return this.handleRestResponse(response);
     });
-    this.updateSessionFromResponse(response);
-    return this.handleRestResponse(response);
   }
   async post(path, body) {
     const response = await this.resilientFetch(`${this.baseUrl}${path}`, {
@@ -1614,13 +1724,16 @@ var CimplifyClient = class {
     return this.handleRestResponse(response);
   }
   async linkGet(path) {
-    const response = await this.resilientFetch(`${this.linkApiUrl}${path}`, {
-      method: "GET",
-      credentials: this.credentials,
-      headers: this.getHeaders()
+    const key = this.getDedupeKey("linkGet", path);
+    return this.deduplicatedRequest(key, async () => {
+      const response = await this.resilientFetch(`${this.linkApiUrl}${path}`, {
+        method: "GET",
+        credentials: this.credentials,
+        headers: this.getHeaders()
+      });
+      this.updateSessionFromResponse(response);
+      return this.handleRestResponse(response);
     });
-    this.updateSessionFromResponse(response);
-    return this.handleRestResponse(response);
   }
   async linkPost(path, body) {
     const response = await this.resilientFetch(`${this.linkApiUrl}${path}`, {

package/dist/index.mjs

@@ -1467,6 +1467,8 @@ function deriveUrls() {
 var CimplifyClient = class {
   constructor(config = {}) {
     this.sessionToken = null;
+    /** In-flight request deduplication map */
+    this.inflightRequests = /* @__PURE__ */ new Map();
     this.publicKey = config.publicKey || "";
     const urls = deriveUrls();
     this.baseUrl = urls.baseUrl;
@@ -1475,18 +1477,31 @@ var CimplifyClient = class {
     this.timeout = config.timeout ?? DEFAULT_TIMEOUT_MS;
     this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
     this.retryDelay = config.retryDelay ?? DEFAULT_RETRY_DELAY_MS;
+    this.hooks = config.hooks ?? {};
     this.sessionToken = this.loadSessionToken();
   }
   getSessionToken() {
     return this.sessionToken;
   }
   setSessionToken(token) {
+    const previous = this.sessionToken;
     this.sessionToken = token;
     this.saveSessionToken(token);
+    this.hooks.onSessionChange?.({
+      previousToken: previous,
+      newToken: token,
+      source: "manual"
+    });
   }
   clearSession() {
+    const previous = this.sessionToken;
     this.sessionToken = null;
     this.saveSessionToken(null);
+    this.hooks.onSessionChange?.({
+      previousToken: previous,
+      newToken: null,
+      source: "clear"
+    });
   }
   loadSessionToken() {
     if (typeof window !== "undefined" && window.localStorage) {
@@ -1516,15 +1531,33 @@ var CimplifyClient = class {
   updateSessionFromResponse(response) {
     const newToken = response.headers.get(SESSION_TOKEN_HEADER);
     if (newToken && newToken !== this.sessionToken) {
+      const previous = this.sessionToken;
       this.sessionToken = newToken;
       this.saveSessionToken(newToken);
+      this.hooks.onSessionChange?.({
+        previousToken: previous,
+        newToken,
+        source: "response"
+      });
     }
   }
   /**
-   * Resilient fetch with timeout and automatic retries for network errors.
+   * Resilient fetch with timeout, automatic retries, and observability hooks.
    * Uses exponential backoff: 1s, 2s, 4s between retries.
    */
   async resilientFetch(url, options) {
+    const method = options.method || "GET";
+    const path = url.replace(this.baseUrl, "").replace(this.linkApiUrl, "");
+    const startTime = Date.now();
+    let retryCount = 0;
+    const context = {
+      method,
+      path,
+      url,
+      body: options.body ? JSON.parse(options.body) : void 0,
+      startTime
+    };
+    this.hooks.onRequestStart?.(context);
     let lastError;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       try {
@@ -1536,39 +1569,113 @@ var CimplifyClient = class {
         });
         clearTimeout(timeoutId);
         if (response.ok || response.status >= 400 && response.status < 500) {
+          this.hooks.onRequestSuccess?.({
+            ...context,
+            status: response.status,
+            durationMs: Date.now() - startTime
+          });
           return response;
         }
         if (response.status >= 500 && attempt < this.maxRetries) {
+          retryCount++;
           const delay = this.retryDelay * Math.pow(2, attempt);
+          this.hooks.onRetry?.({
+            ...context,
+            attempt: retryCount,
+            delayMs: delay,
+            error: new Error(`Server error: ${response.status}`)
+          });
           await sleep(delay);
           continue;
         }
+        this.hooks.onRequestSuccess?.({
+          ...context,
+          status: response.status,
+          durationMs: Date.now() - startTime
+        });
         return response;
       } catch (error) {
         lastError = error;
-        if (!isRetryable(error) || attempt >= this.maxRetries) {
-          throw toNetworkError(error);
+        const networkError = toNetworkError(error);
+        const errorRetryable = isRetryable(error);
+        if (!errorRetryable || attempt >= this.maxRetries) {
+          this.hooks.onRequestError?.({
+            ...context,
+            error: networkError,
+            durationMs: Date.now() - startTime,
+            retryCount,
+            retryable: errorRetryable
+          });
+          throw networkError;
         }
+        retryCount++;
         const delay = this.retryDelay * Math.pow(2, attempt);
+        this.hooks.onRetry?.({
+          ...context,
+          attempt: retryCount,
+          delayMs: delay,
+          error: networkError
+        });
         await sleep(delay);
       }
     }
-    throw toNetworkError(lastError);
+    const finalError = toNetworkError(lastError);
+    this.hooks.onRequestError?.({
+      ...context,
+      error: finalError,
+      durationMs: Date.now() - startTime,
+      retryCount,
+      retryable: false
+    });
+    throw finalError;
   }
+  /**
+   * Generate a deduplication key for a request.
+   * Same query + variables = same key = deduplicated.
+   */
+  getDedupeKey(type, payload) {
+    return `${type}:${JSON.stringify(payload)}`;
+  }
+  /**
+   * Execute a request with deduplication.
+   * If an identical request is already in-flight, return the same promise.
+   * This prevents redundant network calls when multiple components request the same data.
+   */
+  async deduplicatedRequest(key, requestFn) {
+    const existing = this.inflightRequests.get(key);
+    if (existing) {
+      return existing;
+    }
+    const request = requestFn().finally(() => {
+      this.inflightRequests.delete(key);
+    });
+    this.inflightRequests.set(key, request);
+    return request;
+  }
+  /**
+   * Execute a query with deduplication.
+   * Multiple identical queries made simultaneously will share a single network request.
+   */
   async query(query2, variables) {
     const body = { query: query2 };
     if (variables) {
       body.variables = variables;
     }
-    const response = await this.resilientFetch(`${this.baseUrl}/api/q`, {
-      method: "POST",
-      credentials: this.credentials,
-      headers: this.getHeaders(),
-      body: JSON.stringify(body)
+    const key = this.getDedupeKey("query", body);
+    return this.deduplicatedRequest(key, async () => {
+      const response = await this.resilientFetch(`${this.baseUrl}/api/q`, {
+        method: "POST",
+        credentials: this.credentials,
+        headers: this.getHeaders(),
+        body: JSON.stringify(body)
+      });
+      this.updateSessionFromResponse(response);
+      return this.handleResponse(response);
     });
-    this.updateSessionFromResponse(response);
-    return this.handleResponse(response);
   }
+  /**
+   * Execute a mutation. NOT deduplicated - mutations have side effects.
+   */
   async call(method, args) {
     const body = {
       method,
@@ -1584,13 +1691,16 @@ var CimplifyClient = class {
     return this.handleResponse(response);
   }
   async get(path) {
-    const response = await this.resilientFetch(`${this.baseUrl}${path}`, {
-      method: "GET",
-      credentials: this.credentials,
-      headers: this.getHeaders()
+    const key = this.getDedupeKey("get", path);
+    return this.deduplicatedRequest(key, async () => {
+      const response = await this.resilientFetch(`${this.baseUrl}${path}`, {
+        method: "GET",
+        credentials: this.credentials,
+        headers: this.getHeaders()
+      });
+      this.updateSessionFromResponse(response);
+      return this.handleRestResponse(response);
     });
-    this.updateSessionFromResponse(response);
-    return this.handleRestResponse(response);
   }
   async post(path, body) {
     const response = await this.resilientFetch(`${this.baseUrl}${path}`, {
@@ -1612,13 +1722,16 @@ var CimplifyClient = class {
     return this.handleRestResponse(response);
   }
   async linkGet(path) {
-    const response = await this.resilientFetch(`${this.linkApiUrl}${path}`, {
-      method: "GET",
-      credentials: this.credentials,
-      headers: this.getHeaders()
+    const key = this.getDedupeKey("linkGet", path);
+    return this.deduplicatedRequest(key, async () => {
+      const response = await this.resilientFetch(`${this.linkApiUrl}${path}`, {
+        method: "GET",
+        credentials: this.credentials,
+        headers: this.getHeaders()
+      });
+      this.updateSessionFromResponse(response);
+      return this.handleRestResponse(response);
     });
-    this.updateSessionFromResponse(response);
-    return this.handleRestResponse(response);
   }
   async linkPost(path, body) {
     const response = await this.resilientFetch(`${this.linkApiUrl}${path}`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cimplify/sdk",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Cimplify Commerce SDK for storefronts",
   "keywords": [
     "cimplify",