npm - shop-client - Versions diffs - 3.14.1 → 3.16.0 - Mend

shop-client 3.14.1 → 3.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md +48 -22
package/dist/ai/enrich.d.ts +27 -3
package/dist/ai/enrich.mjs +9 -1
package/dist/{chunk-7IMI76JZ.mjs → chunk-OA76XD32.mjs} +15 -2
package/dist/{chunk-554O5ED6.mjs → chunk-QCB3U4AO.mjs} +12 -1
package/dist/{chunk-ZF4M6GMB.mjs → chunk-THCO3JT4.mjs} +94 -29
package/dist/{chunk-GNIBTUEK.mjs → chunk-ZX4IG4TY.mjs} +390 -206
package/dist/collections.d.ts +1 -1
package/dist/collections.mjs +1 -1
package/dist/index.d.ts +5 -3
package/dist/index.mjs +10 -6
package/dist/products.d.ts +30 -3
package/dist/products.mjs +1 -1
package/dist/store.d.ts +1 -1
package/dist/store.mjs +1 -1
package/dist/{types-luPg5O08.d.ts → types-BRXamZMS.d.ts} +14 -1
package/dist/utils/detect-country.d.ts +1 -1
package/dist/utils/func.d.ts +1 -1
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -409,6 +409,24 @@ const showcasedProducts = await shop.products.showcased();
 **Returns:** `Product[]` - Array of featured products
+#### `products.infoHtml(productHandle, content?)`
+Fetches the extracted HTML content from the product page. This is useful for getting the main product description and content directly from the page HTML.
+```typescript
+// Fetch from store
+const html = await shop.products.infoHtml("product-handle");
+// Use provided HTML
+const htmlFromContent = await shop.products.infoHtml("product-handle", "<html>...</html>");
+```
+**Parameters:**
+- `productHandle` (string): The product handle
+- `content` (string, optional): HTML content to extract from. If provided, skips fetching the product page.
+**Returns:** `Promise<string | null>` - Extracted HTML content or null if not found
 #### `products.filter()`
 Creates a map of variant options and their distinct values from all products in the store. This is useful for building filter interfaces, search facets, and product option selectors.
@@ -699,14 +717,11 @@ Determine the store’s primary verticals and target audiences using showcased p
 ```typescript
 import { ShopClient } from 'shop-client';
-const shop = new ShopClient('your-store-domain.com');
+const shop = new ShopClient('your-store-domain.com', {
+  openRouter: { apiKey: 'YOUR_OPENROUTER_API_KEY', model: 'openai/gpt-4o-mini' },
+});
 const breakdown = await shop.determineStoreType({
-  // Optional: provide an OpenRouter API key for online classification
-  // Offline mode falls back to regex heuristics if no key is set
-  apiKey: process.env.OPENROUTER_API_KEY,
-  // Optional: model name when using online classification
-  model: 'openai/gpt-4o-mini',
   // Optional: limit the number of showcased products sampled (default 10, max 50)
   maxShowcaseProducts: 12,
   // Note: showcased collections are not used for classification
@@ -724,34 +739,45 @@ Details:
 - Uses only `product.bodyHtml` for classification (no images or external text).
 - Samples up to `maxShowcaseProducts` from `getInfo().showcase.products`.
 - Aggregates per-product audience/vertical into a multi-audience breakdown.
-- If `OPENROUTER_API_KEY` is absent or `OPENROUTER_OFFLINE=1`, uses offline regex heuristics.
+- If `openRouter.offline` is `true`, uses offline regex heuristics. Otherwise, an OpenRouter API key is required (via `ShopClient` options or `determineStoreType({ apiKey })`).
 - Applies store-level pruning based on title/description to improve consistency.
 ### AI Enrichment
 ```typescript
-import { classifyProduct, generateSEOContent } from 'shop-client';
+import { ShopClient } from 'shop-client';
+const shop = new ShopClient('your-store-domain.com', {
+  openRouter: { apiKey: 'YOUR_OPENROUTER_API_KEY', model: 'openai/gpt-4o-mini' },
+});
+// Merge API (Ajax) + product page content into a clean description
+const enrichedMarkdown = await shop.products.enriched('some-product-handle', {
+  outputFormat: 'markdown',
+});
+// enrichedMarkdown?.enriched_content → markdown
+// Use provided content instead of fetching product page
+const enrichedFromContent = await shop.products.enriched('some-product-handle', {
+  outputFormat: 'markdown',
+  content: '<html>...</html>',
+});
-// 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'],
+const enrichedJson = await shop.products.enriched('some-product-handle', {
+  outputFormat: 'json',
 });
-// classification → { adult_unisex: { clothing: ['t-shirts'] } }
+// enrichedJson?.enriched_content → JSON string (validated)
-// 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'],
+// Build prompts without calling the LLM (useful for debugging)
+const { system, user } = await shop.products.enrichedPrompts('some-product-handle', {
+  outputFormat: 'markdown',
+  content: '<html>...</html>', // Optional content
 });
-// 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.
+- `enriched()` returns `enriched_content` as either markdown or a validated JSON string (based on `outputFormat`).
+- `enrichedPrompts()` and `classifyPrompts()` return the prompt pair without making network calls.
 ## 🏗️ Type Definitions

package/dist/ai/enrich.d.ts CHANGED Viewed

@@ -1,5 +1,23 @@
-import { k as ProductClassification, l as SEOContent, a as ShopifySingleProduct } from '../types-luPg5O08.js';
+import { O as OpenRouterConfig, k as ProductClassification, l as SEOContent, m as SystemUserPrompt, a as ShopifySingleProduct } from '../types-BRXamZMS.js';
+declare function buildEnrichPrompt(args: {
+    bodyInput: string;
+    pageInput: string;
+    inputType: "markdown" | "html";
+    outputFormat: "markdown" | "json";
+}): SystemUserPrompt;
+declare function buildClassifyPrompt(productContent: string): SystemUserPrompt;
+declare function buildEnrichPromptForProduct(domain: string, handle: string, options?: {
+    useGfm?: boolean;
+    inputType?: "markdown" | "html";
+    outputFormat?: "markdown" | "json";
+    htmlContent?: string;
+}): Promise<SystemUserPrompt>;
+declare function buildClassifyPromptForProduct(domain: string, handle: string, options?: {
+    useGfm?: boolean;
+    inputType?: "markdown" | "html";
+    htmlContent?: string;
+}): Promise<SystemUserPrompt>;
 interface EnrichedProductResult {
     bodyHtml: string;
     pageHtml: string;
@@ -26,7 +44,7 @@ declare function extractMainSection(html: string): string | null;
  */
 declare function htmlToMarkdown(html: string | null, options?: {
     useGfm?: boolean;
-}): string;
+}): Promise<string>;
 /**
  * Merge the two markdown sources using OpenAI GPT
  */
@@ -35,6 +53,7 @@ declare function mergeWithLLM(bodyInput: string, pageInput: string, options?: {
     inputType?: "markdown" | "html";
     model?: string;
     outputFormat?: "markdown" | "json";
+    openRouter?: OpenRouterConfig;
 }): Promise<string>;
 /**
  * MAIN WORKFLOW
@@ -45,6 +64,8 @@ declare function enrichProduct(domain: string, handle: string, options?: {
     inputType?: "markdown" | "html";
     model?: string;
     outputFormat?: "markdown" | "json";
+    openRouter?: OpenRouterConfig;
+    htmlContent?: string;
 }): Promise<EnrichedProductResult>;
 /**
  * Classify product content into a three-tier hierarchy using LLM.
@@ -53,6 +74,7 @@ declare function enrichProduct(domain: string, handle: string, options?: {
 declare function classifyProduct(productContent: string, options?: {
     apiKey?: string;
     model?: string;
+    openRouter?: OpenRouterConfig;
 }): Promise<ProductClassification>;
 /**
  * Generate SEO and marketing content for a product. Returns strictly validated JSON.
@@ -66,6 +88,7 @@ declare function generateSEOContent(product: {
 }, options?: {
     apiKey?: string;
     model?: string;
+    openRouter?: OpenRouterConfig;
 }): Promise<SEOContent>;
 /**
  * Determine store type (primary vertical and audience) from store information.
@@ -87,7 +110,8 @@ declare function determineStoreType(storeInfo: {
 }, options?: {
     apiKey?: string;
     model?: string;
+    openRouter?: OpenRouterConfig;
 }): 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 };
+export { type EnrichedProductResult, buildClassifyPrompt, buildClassifyPromptForProduct, buildEnrichPrompt, buildEnrichPromptForProduct, classifyProduct, determineStoreType, enrichProduct, extractMainSection, fetchAjaxProduct, fetchProductPage, generateSEOContent, htmlToMarkdown, mergeWithLLM, pruneBreakdownForSignals };

package/dist/ai/enrich.mjs CHANGED Viewed

@@ -1,4 +1,8 @@
 import {
+  buildClassifyPrompt,
+  buildClassifyPromptForProduct,
+  buildEnrichPrompt,
+  buildEnrichPromptForProduct,
   classifyProduct,
   determineStoreType,
   enrichProduct,
@@ -9,9 +13,13 @@ import {
   htmlToMarkdown,
   mergeWithLLM,
   pruneBreakdownForSignals
-} from "../chunk-GNIBTUEK.mjs";
+} from "../chunk-ZX4IG4TY.mjs";
 import "../chunk-D5MTUWFO.mjs";
 export {
+  buildClassifyPrompt,
+  buildClassifyPromptForProduct,
+  buildEnrichPrompt,
+  buildEnrichPromptForProduct,
   classifyProduct,
   determineStoreType,
   enrichProduct,

package/dist/{chunk-7IMI76JZ.mjs → chunk-OA76XD32.mjs} RENAMED Viewed

@@ -171,6 +171,19 @@ async function getInfoForShop(args, options) {
       (handle) => Boolean(handle)
     );
   }
+  const dedupeByNormalized = (arr) => {
+    var _a2;
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const h of arr) {
+      const base = (_a2 = h == null ? void 0 : h.split("?")[0]) == null ? void 0 : _a2.replace(/^\/|\/$/g, "");
+      if (!base) continue;
+      if (seen.has(base)) continue;
+      seen.add(base);
+      out.push(base);
+    }
+    return out;
+  };
   const info = {
     name: name || slug,
     domain: sanitizeDomain(baseUrl),
@@ -182,8 +195,8 @@ async function getInfoForShop(args, options) {
     contactLinks,
     headerLinks,
     showcase: {
-      products: unique(homePageProductLinks != null ? homePageProductLinks : []),
-      collections: unique(homePageCollectionLinks != null ? homePageCollectionLinks : [])
+      products: dedupeByNormalized(homePageProductLinks != null ? homePageProductLinks : []),
+      collections: dedupeByNormalized(homePageCollectionLinks != null ? homePageCollectionLinks : [])
     },
     jsonLdData: ((_p = (_o = html.match(
       /<script[^>]*type="application\/ld\+json"[^>]*>([^<]+)<\/script>/g

package/dist/{chunk-554O5ED6.mjs → chunk-QCB3U4AO.mjs} RENAMED Viewed

@@ -230,8 +230,19 @@ function createCollectionOperations(baseUrl, storeDomain, fetchCollections, coll
      */
     showcased: async () => {
       const storeInfo = await getStoreInfo();
+      const normalizedHandles = storeInfo.showcase.collections.map((h) => {
+        var _a;
+        return (_a = h.split("?")[0]) == null ? void 0 : _a.replace(/^\/|\/$/g, "");
+      }).filter((base) => Boolean(base));
+      const seen = /* @__PURE__ */ new Set();
+      const uniqueHandles = [];
+      for (const base of normalizedHandles) {
+        if (seen.has(base)) continue;
+        seen.add(base);
+        uniqueHandles.push(base);
+      }
       const collections = await Promise.all(
-        storeInfo.showcase.collections.map(
+        uniqueHandles.map(
           (collectionHandle) => findCollection(collectionHandle)
         )
       );

package/dist/{chunk-ZF4M6GMB.mjs → chunk-THCO3JT4.mjs} RENAMED Viewed

@@ -7,7 +7,7 @@ import {
 // src/products.ts
 import { filter, isNonNullish } from "remeda";
-function createProductOperations(baseUrl, storeDomain, fetchProducts, productsDto, productDto, getStoreInfo, findProduct) {
+function createProductOperations(baseUrl, storeDomain, fetchProducts, productsDto, productDto, getStoreInfo, findProduct, ai) {
   const cacheExpiryMs = 5 * 60 * 1e3;
   const findCache = /* @__PURE__ */ new Map();
   const getCached = (key) => {
@@ -242,12 +242,6 @@ function createProductOperations(baseUrl, storeDomain, fetchProducts, productsDt
       if (!productHandle || typeof productHandle !== "string") {
         throw new Error("Product handle is required and must be a string");
       }
-      const apiKey = (options == null ? void 0 : options.apiKey) || process.env.OPENROUTER_API_KEY;
-      if (!apiKey) {
-        throw new Error(
-          "Missing OpenRouter API key. Pass options.apiKey or set OPENROUTER_API_KEY."
-        );
-      }
       const baseProduct = await operations.find(productHandle);
       if (!baseProduct) {
         return null;
@@ -255,32 +249,46 @@ function createProductOperations(baseUrl, storeDomain, fetchProducts, productsDt
       const handle = baseProduct.handle;
       const { enrichProduct } = await import("./ai/enrich.mjs");
       const enriched = await enrichProduct(storeDomain, handle, {
-        apiKey,
+        apiKey: options == null ? void 0 : options.apiKey,
+        openRouter: ai == null ? void 0 : ai.openRouter,
         useGfm: options == null ? void 0 : options.useGfm,
         inputType: options == null ? void 0 : options.inputType,
         model: options == null ? void 0 : options.model,
-        outputFormat: options == null ? void 0 : options.outputFormat
+        outputFormat: options == null ? void 0 : options.outputFormat,
+        htmlContent: options == null ? void 0 : options.content
       });
       return {
         ...baseProduct,
         enriched_content: enriched.mergedMarkdown
       };
     },
-    classify: async (productHandle, options) => {
+    enrichedPrompts: async (productHandle, options) => {
       if (!productHandle || typeof productHandle !== "string") {
         throw new Error("Product handle is required and must be a string");
       }
-      const apiKey = (options == null ? void 0 : options.apiKey) || process.env.OPENROUTER_API_KEY;
-      if (!apiKey) {
-        throw new Error(
-          "Missing OpenRouter API key. Pass options.apiKey or set OPENROUTER_API_KEY."
-        );
+      const baseProduct = await operations.find(productHandle);
+      if (!baseProduct) {
+        throw new Error("Product not found");
+      }
+      const handle = baseProduct.handle;
+      const { buildEnrichPromptForProduct } = await import("./ai/enrich.mjs");
+      return buildEnrichPromptForProduct(storeDomain, handle, {
+        useGfm: options == null ? void 0 : options.useGfm,
+        inputType: options == null ? void 0 : options.inputType,
+        outputFormat: options == null ? void 0 : options.outputFormat,
+        htmlContent: options == null ? void 0 : options.content
+      });
+    },
+    classify: async (productHandle, options) => {
+      if (!productHandle || typeof productHandle !== "string") {
+        throw new Error("Product handle is required and must be a string");
       }
       const enrichedProduct = await operations.enriched(productHandle, {
-        apiKey,
+        apiKey: options == null ? void 0 : options.apiKey,
         inputType: "html",
         model: options == null ? void 0 : options.model,
-        outputFormat: "json"
+        outputFormat: "json",
+        content: options == null ? void 0 : options.content
       });
       if (!enrichedProduct || !enrichedProduct.enriched_content) return null;
       let productContent = enrichedProduct.enriched_content;
@@ -304,20 +312,31 @@ function createProductOperations(baseUrl, storeDomain, fetchProducts, productsDt
       }
       const { classifyProduct } = await import("./ai/enrich.mjs");
       const classification = await classifyProduct(productContent, {
-        apiKey,
+        apiKey: options == null ? void 0 : options.apiKey,
+        openRouter: ai == null ? void 0 : ai.openRouter,
         model: options == null ? void 0 : options.model
       });
       return classification;
     },
-    generateSEOContent: async (productHandle, options) => {
+    classifyPrompts: async (productHandle, options) => {
       if (!productHandle || typeof productHandle !== "string") {
         throw new Error("Product handle is required and must be a string");
       }
-      const apiKey = (options == null ? void 0 : options.apiKey) || process.env.OPENROUTER_API_KEY;
-      if (!apiKey) {
-        throw new Error(
-          "Missing OpenRouter API key. Pass options.apiKey or set OPENROUTER_API_KEY."
-        );
+      const baseProduct = await operations.find(productHandle);
+      if (!baseProduct) {
+        throw new Error("Product not found");
+      }
+      const handle = baseProduct.handle;
+      const { buildClassifyPromptForProduct } = await import("./ai/enrich.mjs");
+      return buildClassifyPromptForProduct(storeDomain, handle, {
+        useGfm: options == null ? void 0 : options.useGfm,
+        inputType: options == null ? void 0 : options.inputType,
+        htmlContent: options == null ? void 0 : options.content
+      });
+    },
+    generateSEOContent: async (productHandle, options) => {
+      if (!productHandle || typeof productHandle !== "string") {
+        throw new Error("Product handle is required and must be a string");
       }
       const baseProduct = await operations.find(productHandle);
       if (!baseProduct) return null;
@@ -328,13 +347,50 @@ function createProductOperations(baseUrl, storeDomain, fetchProducts, productsDt
         price: baseProduct.price,
         tags: baseProduct.tags
       };
-      const { generateSEOContent: generateSEOContentLLM } = await import("./ai/enrich.mjs");
+      const {
+        extractMainSection,
+        fetchAjaxProduct,
+        fetchProductPage,
+        generateSEOContent: generateSEOContentLLM,
+        mergeWithLLM
+      } = await import("./ai/enrich.mjs");
       const seo = await generateSEOContentLLM(payload, {
-        apiKey,
+        apiKey: options == null ? void 0 : options.apiKey,
+        openRouter: ai == null ? void 0 : ai.openRouter,
         model: options == null ? void 0 : options.model
       });
       return seo;
     },
+    /**
+     * Fetches the extracted HTML content from the product page.
+     * This is useful for getting the main product description and content directly from the page HTML.
+     *
+     * @param productHandle - The handle of the product
+     * @param content - Optional HTML content to extract from. If provided, skips fetching the product page.
+     * @returns {Promise<string | null>} The extracted HTML content or null if not found
+     *
+     * @example
+     * ```typescript
+     * // Fetch from store
+     * const html = await shop.products.infoHtml("product-handle");
+     *
+     * // Use provided HTML
+     * const htmlFromContent = await shop.products.infoHtml("product-handle", "<html>...</html>");
+     * ```
+     */
+    infoHtml: async (productHandle, content) => {
+      if (!productHandle || typeof productHandle !== "string") {
+        throw new Error("Product handle is required and must be a string");
+      }
+      const { extractMainSection, fetchProductPage } = await import("./ai/enrich.mjs");
+      if (content) {
+        return extractMainSection(content);
+      }
+      const baseProduct = await operations.find(productHandle);
+      if (!baseProduct) return null;
+      const pageHtml = await fetchProductPage(storeDomain, baseProduct.handle);
+      return extractMainSection(pageHtml);
+    },
     /**
      * Fetches products that are showcased/featured on the store's homepage.
      *
@@ -355,10 +411,19 @@ function createProductOperations(baseUrl, storeDomain, fetchProducts, productsDt
      */
     showcased: async () => {
       const storeInfo = await getStoreInfo();
+      const normalizedHandles = storeInfo.showcase.products.map((h) => {
+        var _a;
+        return (_a = h.split("?")[0]) == null ? void 0 : _a.replace(/^\/|\/$/g, "");
+      }).filter((base) => Boolean(base));
+      const seen = /* @__PURE__ */ new Set();
+      const uniqueHandles = [];
+      for (const base of normalizedHandles) {
+        if (seen.has(base)) continue;
+        seen.add(base);
+        uniqueHandles.push(base);
+      }
       const products = await Promise.all(
-        storeInfo.showcase.products.map(
-          (productHandle) => findProduct(productHandle)
-        )
+        uniqueHandles.map((productHandle) => findProduct(productHandle))
       );
       return filter(products, isNonNullish);
     },