Ecom Service

Description

The EcomService is a centralized class designed to handle various backend operations for an e-commerce platform, covering branches, products, stock, locality, authentication, customer preferences, and general utilities.

Static Token Configuration

• accessTokenExpiryBuffer: Seconds before actual expiry to consider token as "about to expire".
• accessTokenPollInterval: Polling interval for token refresh.
• newTokenGeneratedAt: Timestamp of last token generation.

Branch Related Methods

• fetchAllBranches()
  • Description: Fetches all offline Toolstation (TS) branches.
  • Returns: { data: Branch[] }
  • Error Handling: Uses $customClientErrorHandler with context metadata.

• fetchBranchById(branchId: string, debug = false)
  • Description: Retrieves a single branch’s details by its ID.
  • Returns: { data: Branch }
  • Error Handling: Logs branchId and relevant metadata.

• fetchNearestBranches(request: NearestBranchRequest)
  • Description: Returns nearby branches based on latitude/longitude or postcode.
  • Returns: { data: Branch[] }
  • Error Handling: Uses high-severity error handler.

Product Related Methods

• fetchAllProducts(request: { products: string[] })
  • Static Method
  • Description: Gets details for multiple product IDs.
  • Concurrency Control: Uses isProductListFetching with polling.
  • Error Handling: Captures product request and logs via $customClientErrorHandler.

• fetchStockProduct(request: ProductStockRequest)
  • Static Method
  • Description: Returns product stock info across sites/branches.
  • Returns: { data: ProductStockResponse[] }
  • Error Handling: ncludes stockRequest metadata in error logs.

Locality & Location Services

• fetchEcomLocalityDetails(input: string, woosmapPrivateApiKey: string, countries = ["nl"])
  • Static Method
  • Description: Gets locality/postal code suggestions using backend-integrated Woosmap API.
  • Returns: Location suggestion results.
  • Country Filtering: Uses Google-style components string.

Newsletter

• subscribeToNewsletter(options: { email_address: string; ip?: string })
  • Static Method
  • Description: Subscribes a user to newsletter using email (and optional IP).
  • Endpoints: Location suggestion results.

Contact & Feedback Services

• postContactFormData(options: { email, name, feedback, feedback_type, order_number })
  • Static Method
  • Description: Posts contact/feedback form data to backend.
  • Error Handling: Logs request payload and error context.

Categories & Sitemap Services

• getCategoriesData(cache = false)
  • Static Method
  • Description: Fetches top-level category taxonomy.
  • Error Handling: Logs cache flag and error context.

• getCategoryDetailsById(taxonomyId: string)
  • Static Method
  • Description: Gets taxonomy data by ID.
  • Returns: Single category structure.
  • Error Handling: taxonomyId.

• getCategorySitemap()
  • Static Method
  • Description: Retrieves full category sitemap hierarchy.
  • Returns: { data: CategorySiteMapStructure[] }
  • Error Handling: taxonomyId.

Token & Auth

• getAccessToken()
  • Static Method
  • Description: Returns cached ecomApiAccessToken from cookies or refreshes it if invalid.
  • Logic:
    • Checks token validity with buffer.
    • Falls back to refreshToken() if missing/expired.

• refreshToken()
  • Static Method
  • Description: Poll-safe method to fetch and set new access token using /api/ecom/access-token.
  • Token Structure Includes: accessToken, expiresIn, applicationName, etc.
  • Cookie Updated: ecomApiAccessToken
  • Concurrency Controlled: Uses isTokenFetching with polling loop.

Preferences & Language

• getPreferredLanguage(customerId: string)
  • Static Method
  • Description: Fetches preferred language for a customer.
  • Header: Includes 'app-type': "Toolstation Web"

• setPreferredLanguage(customerId: string, data: object)
  • Static Method
  • Description: Sets preferred language for a customer.
  • Body: JSON stringified.

Redis Integration

• getRedisDataByKey(redis, key)
  • Static Method
  • Description: Fetches a value from Redis using a given key.

Error handling Overview

• Approach: All methods use $customClientErrorHandler.
• Severity Levels: Mostly 'high'.
• Error Context: Each call logs specific metadata (e.g., productRequest, branchId, taxonomyId).