@scryme/sdk 9.67.0 → 9.68.0

package/dist/client.d.mts

@@ -1,5 +1,5 @@
 import { AxiosInstance, AxiosResponse } from 'axios';
-import { ae as CustomerResponseDto, G as ProductResponseDto, K as ServiceCatalogResponseDto, cM as CartItemDto, b7 as CartResponseDto, dK as CustomerSessionDto, fT as RawAPI, cT as CatalogModule, ep as InventoryModule, fh as OrdersModule, cH as CRMModule, fp as POSModule, bN as AccountingModule, eR as LoyaltyModule, fa as MembersModule, cf as AdminModule, b6 as CartControllerGetCartParams, b9 as AddToCartDto, ba as RemoveFromCartDto, b8 as CartControllerClearCartParams, az as OrderResponseDto, ai as UpdateCustomerDto, aj as AddressDto, af as RegisterCustomerDto, dJ as CustomerAuthResponseDto, a0 as CreateBookingDto, gf as ServiceBookingItemDto, cs as AuthModule, s as AuthExchangeToken201 } from './base-1B2-e5i_.mjs';
+import { ai as CustomerResponseDto, G as ProductResponseDto, K as ServiceCatalogResponseDto, cQ as CartItemDto, bb as CartResponseDto, dS as CustomerSessionDto, cZ as CatalogModule, ex as InventoryModule, fp as OrdersModule, cL as CRMModule, fx as POSModule, bR as AccountingModule, eZ as LoyaltyModule, fi as MembersModule, cj as AdminModule, ba as CartControllerGetCartParams, bd as AddToCartDto, be as RemoveFromCartDto, bc as CartControllerClearCartParams, aD as OrderResponseDto, am as UpdateCustomerDto, an as AddressDto, aj as RegisterCustomerDto, dQ as CustomerAuthResponseDto, a4 as CreateBookingDto, gu as ServiceBookingItemDto, cw as AuthModule, s as AuthExchangeToken201 } from './base-CSVOv3Nr.mjs';
 
 /**
  * Defines a storage contract for persisting authentication tokens and session data.
@@ -70,6 +70,22 @@ interface SessionState<TUser = CustomerResponseDto> {
      */
     expiresAt?: number | null;
 }
+/**
+ * Standard client-side session structure matching better-auth.
+ */
+interface ClientSessionStructure<TUser = CustomerResponseDto> {
+    data: {
+        session: {
+            id: string;
+            userId: string;
+            expiresAt: Date | null;
+            token: string | null;
+        };
+        user: TUser;
+    } | null;
+    isPending: boolean;
+    error: any;
+}
 /**
  * Callback signature triggered whenever the customer authentication status changes.
  */
@@ -95,7 +111,7 @@ declare class ScrymeClientSDK<TProduct = ProductResponseDto, TService = ServiceC
     /**
      * Raw proxy API client exposing all standard endpoints auto-bound with the configured orgSlug.
      */
-    api: RawAPI;
+    private api;
     /** Catalog operations submodule (products, services, categories, bookings, staff schedules). */
     catalog: CatalogModule<TProduct, TService>;
     /** Traceability, split/merge, physical reconciliation, and partner wallet operations submodule. */
@@ -119,20 +135,72 @@ declare class ScrymeClientSDK<TProduct = ProductResponseDto, TService = ServiceC
      * Leverages internal tracking and smart delta calculations for optimized storefront shopping.
      */
     cart: {
+        /**
+         * Retrieves the active shopping cart for the current session or customer.
+         * @param params Optional cart parameters including sessionId.
+         * @returns Promise containing the axios response with the cart details.
+         */
         get<T = TCartResponse>(params?: CartControllerGetCartParams): Promise<AxiosResponse<T & Record<string, any>>>;
+        /**
+         * Adds a product variant or service to the shopping cart.
+         * Automatically resolves and appends the customer ID from the active customer session if omitted.
+         * @param dto Data transfer object containing the item details and quantity.
+         * @returns Promise containing the axios response.
+         */
         add(dto: AddToCartDto): Promise<AxiosResponse<void>>;
+        /**
+         * Removes a product variant or service from the shopping cart.
+         * Automatically resolves and appends the customer ID from the active customer session if omitted.
+         * @param dto Data transfer object specifying the item to remove.
+         * @returns Promise containing the axios response.
+         */
         remove(dto: RemoveFromCartDto): Promise<AxiosResponse<void>>;
+        /**
+         * Clears all items from the active shopping cart.
+         * @param params Optional clear parameters containing sessionId.
+         * @returns Promise containing the axios response.
+         */
         clear(params?: CartControllerClearCartParams): Promise<AxiosResponse<void>>;
+        /**
+         * Updates the quantity of a product variant or service in the shopping cart.
+         * Computes the difference and invokes add or remove operations accordingly.
+         * Automatically resolves and appends the customer ID from the active customer session if omitted.
+         * @param dto Data transfer object containing item identifiers and the target absolute quantity.
+         * @returns Promise resolving to the updated cart state or undefined.
+         */
         update<T = TCartResponse>(dto: AddToCartDto & {
             quantity: number;
         }): Promise<AxiosResponse<void> | AxiosResponse<T> | undefined>;
+        /**
+         * Retrieves the flat list of cart items currently in the cart.
+         * @param params Optional parameters.
+         * @returns Promise resolving to an array of cart items.
+         */
         getItems<T = TCartItem>(params?: CartControllerGetCartParams): Promise<T[]>;
+        /**
+         * Calculates the totals, item counts, and summary metrics of the current shopping cart.
+         * @param params Optional parameters.
+         * @returns Promise resolving to the totals object containing the itemsCount, item array, and raw cart.
+         */
         getTotals<TItem = TCartItem, TRaw = TCartResponse>(params?: CartControllerGetCartParams): Promise<{
             itemsCount: number;
             items: TItem[];
             raw: TRaw;
         }>;
+        /**
+         * Merges a guest shopping cart session into an authenticated customer's shopping cart.
+         * @param guestSessionId The guest session token to migrate items from.
+         * @param customerId The destination customer ID.
+         * @returns Promise resolving to the merged cart state.
+         */
         mergeGuestCart<T = TCartResponse>(guestSessionId: string, customerId: string): Promise<AxiosResponse<T & Record<string, any>>>;
+        /**
+         * Finalizes the shopping cart, creating a physical Sales Order for checkout.
+         * Automatically resolves and appends the customer ID from the active customer session.
+         * Clears the shopping cart state upon successful transaction creation.
+         * @param params Checkout configurations including locationId, channel, and custom notes.
+         * @returns Promise resolving to the created order response.
+         */
         checkout(params: {
             locationId: string;
             notes?: string;
@@ -144,57 +212,241 @@ declare class ScrymeClientSDK<TProduct = ProductResponseDto, TService = ServiceC
      * Manages the authenticated user's self-serve account, update workflows, and shipping/billing directories.
      */
     customer: {
+        /**
+         * Fetches the current customer profile details.
+         * @template T The expected type of the user profile.
+         * @returns Promise resolving to the user profile object.
+         */
         getProfile<T = TUser>(): Promise<T>;
+        /**
+         * Updates the profile information of the authenticated customer.
+         * @param dto Updated field attributes.
+         * @returns Promise containing the updated customer profile response.
+         */
         updateProfile<T = TUser>(dto: UpdateCustomerDto): Promise<AxiosResponse<T>>;
+        /**
+         * Retrieves all saved billing/shipping addresses for the active customer.
+         * @returns Promise resolving to the list of address records.
+         */
         getAddresses(): Promise<AxiosResponse<AddressDto[]>>;
+        /**
+         * Saves a new address record to the active customer's profile directory.
+         * @param dto The address details to persist.
+         * @returns Promise containing the response of the creation operation.
+         */
         addAddress(dto: AddressDto): Promise<AxiosResponse<void>>;
+        /**
+         * Reactive & Stateful Customer Authentication Submodule.
+         */
         auth: {
+            /**
+             * Gets the current customer session synchronously in standard format.
+             * Reflects the active customer state immediately without causing React re-renders.
+             */
+            get session(): ClientSessionStructure<TUser>;
+            /**
+             * Registers a new customer storefront profile.
+             * Automatically performs sign-in and establishes a customer session if a password is provided.
+             * @param dto The customer registration attributes (email, name, password, etc.).
+             * @returns Promise containing the created customer details.
+             */
             signUp<T = TUser>(dto: RegisterCustomerDto): Promise<AxiosResponse<T>>;
+            /**
+             * Authenticates a customer using their credentials, starting an active session.
+             * Triggers a 'SIGNED_IN' authentication state change event.
+             * @param credentials Customer login email and optional password.
+             * @returns Promise containing the session token and user profile.
+             */
             signIn<TSess = TSession, TU = TUser>(credentials: {
                 email: string;
                 password?: string;
             }): Promise<CustomerAuthResponseDto<TU, TSess>>;
+            /**
+             * Terminate the active customer session, clearing persisted tokens and session memory.
+             * Triggers a 'SIGNED_OUT' authentication state change event.
+             * @returns Promise resolving once state cleanup is done.
+             */
             signOut(): Promise<void>;
+            /**
+             * Retrieves the raw internal authentication state synchronously/asynchronously.
+             * @returns Promise containing token and user state.
+             */
             getSession<TU = TUser>(): Promise<SessionState<TU>>;
+            /**
+             * Registers a listener to reactively monitor authentication events.
+             * Triggers callback upon 'SIGNED_IN', 'SIGNED_OUT', or 'INITIAL_SESSION' events.
+             * @param callback Callback function.
+             * @returns Subscription reference containing unsubscribe cleanup method.
+             */
             onAuthStateChange<TU = TUser>(callback: AuthStateCallback<TU>): {
                 unsubscribe(): void;
             };
+            /**
+             * Lists all active concurrent sessions associated with this customer profile.
+             * @returns Promise containing the list of active session tokens and metadata.
+             */
             getSessions<TSess = TSession>(): Promise<TSess[]>;
+            /**
+             * Revokes and terminates a specific active customer session by its identifier.
+             * @param id The session identifier to destroy.
+             * @returns Promise containing the revocation response.
+             */
             revokeSession(id: string): Promise<AxiosResponse<void>>;
+            /**
+             * Revokes and terminates all other concurrent sessions for this customer.
+             * @param mode Optional mode configurations.
+             * @returns Promise containing the response.
+             */
             revokeAllSessions(mode?: string): Promise<AxiosResponse<void>>;
+            /**
+             * Retrieves the current customer user record from the backend.
+             * @returns Promise containing the active customer user details.
+             */
             getCurrentSession<TU = TUser>(): Promise<TU>;
+            /**
+             * Refreshes the active customer session, extending the validity of the customer JWT token.
+             * Triggers automatic session token updates and reactive state updates.
+             * @returns Promise resolving to the fresh customer authentication response.
+             */
             refreshSession<TSess = TSession, TU = TUser>(): Promise<CustomerAuthResponseDto<TU, TSess>>;
+            /**
+             * Stateful, reactive React Hook that fetches, manages, and updates the customer session.
+             * Subscribes to authentication state change listeners to ensure immediate UI synchronization.
+             * @returns Reactive session state containing session, user, error, pending flags, and refetch handler.
+             */
+            useSession<TSess = TSession, TU = TUser>(): {
+                data: {
+                    session: TSess;
+                    user: TU;
+                } | null;
+                isPending: boolean;
+                error: any;
+                refetch: () => Promise<void>;
+            };
         };
     };
     /**
      * Service Bookings & Appointments Submodule.
      */
     bookings: {
+        /**
+         * Creates a new booking appointment.
+         * Automatically resolves and appends the customer ID from the active customer session if omitted.
+         * @param dto The service booking reservation parameters.
+         * @returns Promise containing the booking creation response.
+         */
         create(dto: CreateBookingDto): Promise<AxiosResponse<void>>;
+        /**
+         * Retrieves the full details of a specific service booking by its identifier.
+         * @param id Service booking ID.
+         * @returns Promise containing the booking details response.
+         */
         get(id: string): Promise<AxiosResponse<ServiceBookingItemDto>>;
+        /**
+         * Lists all service bookings and reservations associated with the authenticated customer.
+         * @returns Promise containing the list of service booking records.
+         */
         list(): Promise<AxiosResponse<ServiceBookingItemDto[]>>;
+        /**
+         * Cancels an existing service booking appointment.
+         * @param id Service booking ID to cancel.
+         * @returns Promise containing the cancellation response.
+         */
         cancel(id: string): Promise<AxiosResponse<void>>;
     };
     /**
      * Authentication & Customer Session Submodule.
      */
     auth: AuthModule & {
+        /**
+         * Gets the current customer session synchronously in standard format.
+         * Reflects the active customer state immediately without causing React re-renders.
+         */
+        get session(): ClientSessionStructure<TUser>;
+        /**
+         * Registers a new customer storefront profile.
+         * Automatically performs sign-in and establishes a customer session if a password is provided.
+         * @param dto The customer registration attributes (email, name, password, etc.).
+         * @returns Promise containing the created customer details.
+         */
         signUp<T = TUser>(dto: RegisterCustomerDto): Promise<AxiosResponse<T>>;
+        /**
+         * Authenticates application or SDK client via client ID and client secret credentials.
+         * @returns Promise resolving to the token exchange response containing access token.
+         */
         authenticate(): Promise<AuthExchangeToken201>;
+        /**
+         * Authenticates a customer using their credentials, starting an active session.
+         * Triggers a 'SIGNED_IN' authentication state change event.
+         * @param credentials Customer login email and optional password.
+         * @returns Promise containing the session token and user profile.
+         */
         signIn<TSess = TSession, TU = TUser>(credentials: {
             email: string;
             password?: string;
         }): Promise<CustomerAuthResponseDto<TU, TSess>>;
+        /**
+         * Terminate the active customer session, clearing persisted tokens and session memory.
+         * Triggers a 'SIGNED_OUT' authentication state change event.
+         * @returns Promise resolving once state cleanup is done.
+         */
         signOut(): Promise<void>;
+        /**
+         * Retrieves the raw internal authentication state synchronously/asynchronously.
+         * @returns Promise containing token and user state.
+         */
         getSession<TU = TUser>(): Promise<SessionState<TU>>;
+        /**
+         * Registers a listener to reactively monitor authentication events.
+         * Triggers callback upon 'SIGNED_IN', 'SIGNED_OUT', or 'INITIAL_SESSION' events.
+         * @param callback Callback function.
+         * @returns Subscription reference containing unsubscribe cleanup method.
+         */
         onAuthStateChange<TU = TUser>(callback: AuthStateCallback<TU>): {
             unsubscribe(): void;
         };
+        /**
+         * Lists all active concurrent sessions associated with this customer profile.
+         * @returns Promise containing the list of active session tokens and metadata.
+         */
         getSessions<TSess = TSession>(): Promise<TSess[]>;
+        /**
+         * Revokes and terminates a specific active customer session by its identifier.
+         * @param id The session identifier to destroy.
+         * @returns Promise containing the revocation response.
+         */
         revokeSession(id: string): Promise<AxiosResponse<void>>;
+        /**
+         * Revokes and terminates all other concurrent sessions for this customer.
+         * @param mode Optional mode configurations.
+         * @returns Promise containing the response.
+         */
         revokeAllSessions(mode?: string): Promise<AxiosResponse<void>>;
+        /**
+         * Retrieves the current customer user record from the backend.
+         * @returns Promise containing the active customer user details.
+         */
         getCurrentSession<TU = TUser>(): Promise<TU>;
+        /**
+         * Refreshes the active customer session, extending the validity of the customer JWT token.
+         * Triggers automatic session token updates and reactive state updates.
+         * @returns Promise resolving to the fresh customer authentication response.
+         */
         refreshSession<TSess = TSession, TU = TUser>(): Promise<CustomerAuthResponseDto<TU, TSess>>;
+        /**
+         * Stateful, reactive React Hook that fetches, manages, and updates the customer session.
+         * Subscribes to authentication state change listeners to ensure immediate UI synchronization.
+         * @returns Reactive session state containing session, user, error, pending flags, and refetch handler.
+         */
+        useSession<TSess = TSession, TU = TUser>(): {
+            data: {
+                session: TSess;
+                user: TU;
+            } | null;
+            isPending: boolean;
+            error: any;
+            refetch: () => Promise<void>;
+        };
     };
     /**
      * Initializes the ScrymeClientSDK.
@@ -208,4 +460,4 @@ declare class ScrymeClientSDK<TProduct = ProductResponseDto, TService = ServiceC
  */
 declare function createClientSDK<TProduct = ProductResponseDto, TService = ServiceCatalogResponseDto, TCartItem = CartItemDto, TCartResponse = CartResponseDto, TUser = CustomerResponseDto, TSession = CustomerSessionDto>(config?: Partial<ClientSDKConfig>): ScrymeClientSDK<TProduct, TService, TCartItem, TCartResponse, TUser, TSession>;
 
-export { type AuthChangeEvent, type AuthStateCallback, type ClientSDKConfig, ScrymeClientSDK, type SessionState, type StorageProvider, createClientSDK };
+export { type AuthChangeEvent, type AuthStateCallback, type ClientSDKConfig, type ClientSessionStructure, ScrymeClientSDK, type SessionState, type StorageProvider, createClientSDK };