shop-client 3.8.2 → 3.9.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 ShopSearch
+Copyright (c) 2025 ShopClient
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -6,6 +6,18 @@
 
 `shop-client` is a powerful, type-safe TypeScript library for fetching and transforming product data from Shopify stores. Perfect for building e-commerce applications, product catalogs, price comparison tools, and automated store analysis.
 
+## Contents
+
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Store Info Caching & Concurrency](#store-info-caching--concurrency)
+- [Browser Usage](#browser-usage)
+- [Server/Edge Usage](#serveredge-usage)
+- [Deep Imports & Tree-Shaking](#deep-imports--tree-shaking)
+- [Rate Limiting](#rate-limiting)
+- [Migration: Barrel → Subpath Imports](#migration-barrel--subpath-imports)
+ - [API Docs](#api-docs)
+
 ## 🚀 Features
 
 - **Complete Store Data Access**: Fetch products, collections, and store information
@@ -17,6 +29,66 @@
 - **Zero Dependencies**: Lightweight with minimal external dependencies
 - **Store Type Classification**: Infers audience and verticals from showcased products (body_html-only)
 
+## 🧠 Store Info Caching & Concurrency
+
+`getInfo()` uses time-based caching and in-flight request deduping to avoid redundant network calls:
+
+- Cache window: `5 minutes` (`cacheExpiry`). Fresh cached results return immediately.
+  - You can configure this TTL via the `ShopClient` constructor option `cacheTTL` (milliseconds).
+- Cached fields: `infoCacheValue` (last `StoreInfo`) and `infoCacheTimestamp` (last fetch time).
+- In-flight deduping: concurrent calls share a single request via an internal promise; result is cached and returned to all callers.
+- Failure handling: the in-flight marker clears in a `finally` block so subsequent calls can retry.
+
+Behavior:
+- Cached and fresh → returns cached `StoreInfo`.
+- Stale/missing and request in-flight → awaits shared promise.
+- Stale/missing and no in-flight → performs fetch, caches, returns.
+
+Example: configure cache TTL
+
+```ts
+import { ShopClient } from "shop-client";
+
+// Set store info + validation cache TTL to 10 seconds
+const shop = new ShopClient("https://exampleshop.com", { cacheTTL: 10_000 });
+const info = await shop.getInfo();
+```
+
+Manual invalidation
+
+```ts
+import { ShopClient } from "shop-client";
+
+const shop = new ShopClient("https://exampleshop.com", { cacheTTL: 60_000 });
+
+// Fetch and cache
+await shop.getInfo();
+
+// Invalidate cache proactively (e.g., after a content update)
+shop.clearInfoCache();
+
+// Next call refetches and repopulates cache
+await shop.getInfo();
+```
+
+Force refetch
+
+```ts
+import { ShopClient } from "shop-client";
+
+const shop = new ShopClient("https://exampleshop.com", { cacheTTL: 60_000 });
+
+// First call caches within TTL
+await shop.getInfo();
+
+// Force a fresh network fetch even if the cache is still fresh
+const fresh = await shop.getInfo({ force: true });
+```
+
+See also:
+- Architecture: [Caching Strategy](./ARCHITECTURE.md#caching-strategy)
+- API Reference (LLM): [ShopClientOptions, getInfo(force), clearInfoCache](./.llm/api-reference.md#constructor)
+
 ## 📦 Installation
 
 ```bash
@@ -133,6 +205,21 @@ Notes:
 
 ### Migration: Barrel → Subpath Imports
 
+#### Package Rename: `shop-search` → `shop-client` (v3.8.2)
+- Install: `npm i shop-client` (replaces `shop-search`)
+- Update imports to `shop-client` (API unchanged)
+
+TypeScript:
+```ts
+// Before (pre-rename: shop-search)
+import { Store } from 'shop-search';
+const store = new Store("your-store.myshopify.com");
+
+// After (post-rename: shop-client v3.8.2+)
+import { ShopClient } from 'shop-client';
+const client = new ShopClient("your-store.myshopify.com");
+```
+
 You can keep using the root entry (`shop-client`), but for smaller bundles switch to deep imports. The API remains the same—only the import paths change.
 
 Examples:
@@ -165,7 +252,12 @@ Notes:
 - No bundler changes required; deep imports are exposed via `exports`.
 - The root entry continues to work; prefer deep imports for production apps.
 
-## ��️ Rate Limiting
+## API Docs
+
+- TypeDoc builds automatically on pushes to `main` and publishes to GitHub Pages.
+- Visit: `https://peppyhop.github.io/shop-client/` (after the first successful workflow run).
+
+## Rate Limiting
 
 `shop-client` ships with an opt-in, global rate limiter that transparently throttles all internal HTTP requests (products, collections, store info, enrichment). This helps avoid `429 Too Many Requests` responses and keeps crawling stable.
 
@@ -530,6 +622,45 @@ Notes:
 - npm publishes use OIDC with provenance; no `NPM_TOKEN` secret is required.
 - Ensure your npm package settings add this GitHub repo as a trusted publisher and set the environment name to `npm-publish`.
 
+### Additional Utilities
+
+```typescript
+import {
+  calculateDiscount,
+  extractDomainWithoutSuffix,
+  generateStoreSlug,
+  genProductSlug,
+  detectShopCountry,
+} from 'shop-client';
+
+// Discount calculation (percentage, rounded to nearest integer)
+calculateDiscount(8000, 10000); // 20
+
+// Extract base domain without public suffix
+extractDomainWithoutSuffix('www.example.co.uk'); // 'example'
+
+// Create an SEO-friendly store slug
+generateStoreSlug('https://shop.example.com'); // 'shop-example-com'
+
+// Create a product slug from product data
+genProductSlug({
+  title: 'Summer Dress',
+  handle: 'summer-dress',
+  vendor: 'Acme',
+}); // 'acme-summer-dress'
+
+// Detect Shopify store country with confidence score
+const result = await detectShopCountry('anuki.in');
+// result.country → 'IN', result.confidence → 0.9
+```
+
+Notes:
+- `calculateDiscount` expects prices in the same unit (e.g., cents) and returns an integer percentage.
+- `extractDomainWithoutSuffix` removes known TLDs/suffixes, leaving the registrable label.
+- `generateStoreSlug` preserves domain components and replaces separators with hyphens.
+- `genProductSlug` builds a stable, vendor-prefixed slug using product fields.
+- `detectShopCountry` combines multiple signals to infer store country and confidence.
+
 ### Store Type Classification
 
 Determine the store’s primary verticals and target audiences using showcased products. Classification uses only each product’s `body_html` content and aggregates per-product results, optionally pruned by store-level signals.
@@ -565,6 +696,32 @@ Details:
 - If `OPENROUTER_API_KEY` is absent or `OPENROUTER_OFFLINE=1`, uses offline regex heuristics.
 - Applies store-level pruning based on title/description to improve consistency.
 
+### AI Enrichment
+
+```typescript
+import { classifyProduct, generateSEOContent } from 'shop-client';
+
+// Classify a single product (offline or via OpenRouter when configured)
+const classification = await classifyProduct({
+  title: 'Organic Cotton T-Shirt',
+  bodyHtml: '<p>Soft, breathable cotton tee</p>',
+  tags: ['organic', 'cotton', 'unisex'],
+});
+// classification → { adult_unisex: { clothing: ['t-shirts'] } }
+
+// Generate basic SEO content for a product
+const seo = await generateSEOContent({
+  title: 'Organic Cotton T-Shirt',
+  description: 'Soft, breathable tee for everyday wear',
+  tags: ['organic', 'cotton', 'unisex'],
+});
+// seo.metaTitle, seo.metaDescription, seo.keywords
+```
+
+Notes:
+- `classifyProduct` mirrors the store-level classification logic but operates on a single product.
+- `generateSEOContent` produces lightweight, deterministic metadata suitable for catalogs and PDPs.
+
 ## 🏗️ Type Definitions
 
 ### StoreInfo

package/dist/ai/enrich.d.ts

@@ -0,0 +1,93 @@
+import { k as ProductClassification, l as SEOContent, a as ShopifySingleProduct } from '../types-luPg5O08.js';
+
+interface EnrichedProductResult {
+    bodyHtml: string;
+    pageHtml: string;
+    extractedMainHtml: string;
+    mergedMarkdown: string;
+}
+/**
+ * Fetch Shopify Product AJAX API
+ * /products/{handle}.js
+ */
+declare function fetchAjaxProduct(domain: string, handle: string): Promise<ShopifySingleProduct>;
+/**
+ * Fetch full product page HTML
+ */
+declare function fetchProductPage(domain: string, handle: string): Promise<string>;
+/**
+ * Extract the main Shopify product section WITHOUT cheerio
+ * Uses regex + indexing (fast & reliable)
+ */
+declare function extractMainSection(html: string): string | null;
+/**
+ * Convert HTML → Clean Markdown using Turndown
+ * Includes Shopify cleanup rules + GFM support
+ */
+declare function htmlToMarkdown(html: string | null, options?: {
+    useGfm?: boolean;
+}): string;
+/**
+ * Merge the two markdown sources using OpenAI GPT
+ */
+declare function mergeWithLLM(bodyInput: string, pageInput: string, options?: {
+    apiKey?: string;
+    inputType?: "markdown" | "html";
+    model?: string;
+    outputFormat?: "markdown" | "json";
+}): Promise<string>;
+/**
+ * MAIN WORKFLOW
+ */
+declare function enrichProduct(domain: string, handle: string, options?: {
+    apiKey?: string;
+    useGfm?: boolean;
+    inputType?: "markdown" | "html";
+    model?: string;
+    outputFormat?: "markdown" | "json";
+}): Promise<EnrichedProductResult>;
+/**
+ * Classify product content into a three-tier hierarchy using LLM.
+ * Returns strictly validated JSON with audience, vertical, and optional category/subCategory.
+ */
+declare function classifyProduct(productContent: string, options?: {
+    apiKey?: string;
+    model?: string;
+}): Promise<ProductClassification>;
+/**
+ * Generate SEO and marketing content for a product. Returns strictly validated JSON.
+ */
+declare function generateSEOContent(product: {
+    title: string;
+    description?: string;
+    vendor?: string;
+    price?: number;
+    tags?: string[];
+}, options?: {
+    apiKey?: string;
+    model?: string;
+}): Promise<SEOContent>;
+/**
+ * Determine store type (primary vertical and audience) from store information.
+ * Accepts flexible input for showcase products/collections (titles or handles) and returns
+ * strictly validated `vertical` and `audience` values.
+ */
+declare function determineStoreType(storeInfo: {
+    title: string;
+    description?: string | null;
+    showcase: {
+        products: Array<{
+            title: string;
+            productType?: string | null;
+        }> | string[];
+        collections: Array<{
+            title: string;
+        }> | string[];
+    };
+}, options?: {
+    apiKey?: string;
+    model?: string;
+}): Promise<Partial<Record<ProductClassification["audience"], Partial<Record<ProductClassification["vertical"], string[]>>>>>;
+declare function pruneBreakdownForSignals(breakdown: Partial<Record<ProductClassification["audience"], Partial<Record<ProductClassification["vertical"], string[]>>>>, text: string): Partial<Record<ProductClassification["audience"], Partial<Record<ProductClassification["vertical"], string[]>>>>;
+
+export { type EnrichedProductResult, classifyProduct, determineStoreType, enrichProduct, extractMainSection, fetchAjaxProduct, fetchProductPage, generateSEOContent, htmlToMarkdown, mergeWithLLM, pruneBreakdownForSignals };

package/dist/ai/enrich.js

@@ -0,0 +1,25 @@
+import {
+  classifyProduct,
+  determineStoreType,
+  enrichProduct,
+  extractMainSection,
+  fetchAjaxProduct,
+  fetchProductPage,
+  generateSEOContent,
+  htmlToMarkdown,
+  mergeWithLLM,
+  pruneBreakdownForSignals
+} from "../chunk-VPPCOJC3.js";
+import "../chunk-2MF53V33.js";
+export {
+  classifyProduct,
+  determineStoreType,
+  enrichProduct,
+  extractMainSection,
+  fetchAjaxProduct,
+  fetchProductPage,
+  generateSEOContent,
+  htmlToMarkdown,
+  mergeWithLLM,
+  pruneBreakdownForSignals
+};

package/dist/checkout.js

@@ -1,115 +1,6 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/checkout.ts
-var checkout_exports = {};
-__export(checkout_exports, {
-  createCheckoutOperations: () => createCheckoutOperations
-});
-module.exports = __toCommonJS(checkout_exports);
-function createCheckoutOperations(baseUrl) {
-  return {
-    /**
-     * Creates a Shopify checkout URL with pre-filled customer information and cart items.
-     *
-     * @param params - Checkout parameters
-     * @param params.email - Customer's email address (must be valid email format)
-     * @param params.items - Array of products to add to cart
-     * @param params.items[].productVariantId - Shopify product variant ID
-     * @param params.items[].quantity - Quantity as string (must be positive number)
-     * @param params.address - Customer's shipping address
-     * @param params.address.firstName - Customer's first name
-     * @param params.address.lastName - Customer's last name
-     * @param params.address.address1 - Street address
-     * @param params.address.city - City name
-     * @param params.address.zip - Postal/ZIP code
-     * @param params.address.country - Country name
-     * @param params.address.province - State/Province name
-     * @param params.address.phone - Phone number
-     *
-     * @returns {string} Complete Shopify checkout URL with pre-filled information
-     *
-     * @throws {Error} When email is invalid, items array is empty, or required address fields are missing
-     *
-     * @example
-     * ```typescript
-     * const shop = new ShopClient('https://exampleshop.com');
-     * const checkoutUrl = await shop.checkout.create([
-     *   { variantId: '123', quantity: 2 },
-     *   { variantId: '456', quantity: 1 }
-     * ]);
-     * console.log(checkoutUrl);
-     * ```
-     */
-    createUrl: ({
-      email,
-      items,
-      address
-    }) => {
-      if (!email || !email.includes("@")) {
-        throw new Error("Invalid email address");
-      }
-      if (!items || items.length === 0) {
-        throw new Error("Items array cannot be empty");
-      }
-      for (const item of items) {
-        if (!item.productVariantId || !item.quantity) {
-          throw new Error("Each item must have productVariantId and quantity");
-        }
-        const qty = Number.parseInt(item.quantity, 10);
-        if (Number.isNaN(qty) || qty <= 0) {
-          throw new Error("Quantity must be a positive number");
-        }
-      }
-      const requiredFields = [
-        "firstName",
-        "lastName",
-        "address1",
-        "city",
-        "zip",
-        "country"
-      ];
-      for (const field of requiredFields) {
-        if (!address[field]) {
-          throw new Error(`Address field '${field}' is required`);
-        }
-      }
-      const cartPath = items.map(
-        (item) => `${encodeURIComponent(item.productVariantId)}:${encodeURIComponent(item.quantity)}`
-      ).join(",");
-      const params = new URLSearchParams({
-        "checkout[email]": email,
-        "checkout[shipping_address][first_name]": address.firstName,
-        "checkout[shipping_address][last_name]": address.lastName,
-        "checkout[shipping_address][address1]": address.address1,
-        "checkout[shipping_address][city]": address.city,
-        "checkout[shipping_address][zip]": address.zip,
-        "checkout[shipping_address][country]": address.country,
-        "checkout[shipping_address][province]": address.province,
-        "checkout[shipping_address][phone]": address.phone
-      });
-      return `${baseUrl}cart/${cartPath}?${params.toString()}`;
-    }
-  };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
+import {
   createCheckoutOperations
-});
-//# sourceMappingURL=checkout.js.map
+} from "./chunk-RR6YTQWP.js";
+export {
+  createCheckoutOperations
+};

package/dist/{chunk-2KBOKOAD.mjs → chunk-2MF53V33.js}

@@ -17,12 +17,6 @@ var RateLimiter = class {
       this.refillTimer.unref();
     }
   }
-  stopRefill() {
-    if (this.refillTimer) {
-      clearInterval(this.refillTimer);
-      this.refillTimer = null;
-    }
-  }
   ensureRefillStarted() {
     if (!this.refillTimer) {
       this.startRefill();
@@ -151,16 +145,42 @@ function configureRateLimit(options) {
     }
   }
 }
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function rateLimitedFetch(input, init) {
-  var _a;
-  if (!enabled) {
-    return fetch(input, init);
-  }
+  var _a, _b, _c, _d, _e, _f, _g;
   const klass = init == null ? void 0 : init.rateLimitClass;
   const byClass = klass ? classLimiters.get(klass) : void 0;
   const byHost = getHostLimiter(getHost(input));
-  const eff = (_a = byClass != null ? byClass : byHost) != null ? _a : limiter;
-  return eff.schedule(() => fetch(input, init));
+  const eff = enabled ? (_a = byClass != null ? byClass : byHost) != null ? _a : limiter : void 0;
+  const maxRetries = Math.max(0, (_c = (_b = init == null ? void 0 : init.retry) == null ? void 0 : _b.maxRetries) != null ? _c : 2);
+  const baseDelayMs = Math.max(0, (_e = (_d = init == null ? void 0 : init.retry) == null ? void 0 : _d.baseDelayMs) != null ? _e : 200);
+  const retryOnStatuses = (_g = (_f = init == null ? void 0 : init.retry) == null ? void 0 : _f.retryOnStatuses) != null ? _g : [429, 503];
+  let attempt = 0;
+  let lastError = null;
+  let response = null;
+  while (attempt <= maxRetries) {
+    try {
+      if (eff) {
+        response = await eff.schedule(() => fetch(input, init));
+      } else {
+        response = await fetch(input, init);
+      }
+      if (!response || response.ok || !retryOnStatuses.includes(response.status)) {
+        return response;
+      }
+    } catch (err) {
+      lastError = err;
+    }
+    attempt += 1;
+    if (attempt > maxRetries) break;
+    const jitter = Math.floor(Math.random() * 100);
+    const delay = baseDelayMs * 2 ** (attempt - 1) + jitter;
+    await sleep(delay);
+  }
+  if (response) return response;
+  throw lastError != null ? lastError : new Error("rateLimitedFetch failed without response");
 }
 function getRateLimitStatus() {
   return {
@@ -174,4 +194,3 @@ export {
   rateLimitedFetch,
   getRateLimitStatus
 };
-//# sourceMappingURL=chunk-2KBOKOAD.mjs.map

package/dist/{chunk-BWKBRM2Z.mjs → chunk-CN7L3BHG.js}

@@ -110,6 +110,17 @@ function buildVariantOptionsMap(optionNames, variants) {
   }
   return map;
 }
+function buildVariantKey(obj) {
+  const parts = [];
+  for (const [name, value] of Object.entries(obj)) {
+    if (value) {
+      parts.push(`${normalizeKey(name)}#${normalizeKey(value)}`);
+    }
+  }
+  if (parts.length === 0) return "";
+  parts.sort((a, b) => a.localeCompare(b));
+  return parts.join("##");
+}
 function formatPrice(amountInCents, currency) {
   try {
     return new Intl.NumberFormat(void 0, {
@@ -131,6 +142,6 @@ export {
   safeParseDate,
   normalizeKey,
   buildVariantOptionsMap,
+  buildVariantKey,
   formatPrice
 };
-//# sourceMappingURL=chunk-BWKBRM2Z.mjs.map