shop-client 3.14.1 → 3.15.0

package/README.md

@@ -699,14 +699,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 +721,38 @@ 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
 
-// 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',
 });
-// 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

@@ -1,5 +1,21 @@
-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";
+}): Promise<SystemUserPrompt>;
+declare function buildClassifyPromptForProduct(domain: string, handle: string, options?: {
+    useGfm?: boolean;
+    inputType?: "markdown" | "html";
+}): Promise<SystemUserPrompt>;
 interface EnrichedProductResult {
     bodyHtml: string;
     pageHtml: string;
@@ -26,7 +42,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 +51,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 +62,7 @@ declare function enrichProduct(domain: string, handle: string, options?: {
     inputType?: "markdown" | "html";
     model?: string;
     outputFormat?: "markdown" | "json";
+    openRouter?: OpenRouterConfig;
 }): Promise<EnrichedProductResult>;
 /**
  * Classify product content into a three-tier hierarchy using LLM.
@@ -53,6 +71,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 +85,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 +107,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

@@ -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-2W623LCW.mjs";
 import "../chunk-D5MTUWFO.mjs";
 export {
+  buildClassifyPrompt,
+  buildClassifyPromptForProduct,
+  buildEnrichPrompt,
+  buildEnrichPromptForProduct,
   classifyProduct,
   determineStoreType,
   enrichProduct,