@wocart/storefront 0.0.0-stage → 1.1.0

package/dist/utils/money.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Deep Money Formatter
+ *
+ * One formatter for every price a storefront shows.
+ * Handles locale-aware formatting, RTL symbol positioning, and Arabic-Indic digits.
+ *
+ * Design principle: ONE function that handles all cases. Callers curry if needed.
+ */
+export interface MoneyFormatOptions {
+    /** Currency symbol: 'دج' | 'DA' | 'DZD' */
+    symbol: string;
+    /** Locale: 'ar-DZ' | 'fr-FR' | 'en-US' */
+    locale: string;
+    /** Decimal places (default: 0) */
+    decimals?: number;
+}
+/**
+ * Format money amount with locale-aware formatting.
+ *
+ * @param amount - Amount in the platform currency's smallest whole unit (DZD)
+ * @param options - Formatting options (symbol, locale, decimals)
+ * @returns Formatted money string
+ *
+ * @example
+ * ```ts
+ * // Arabic: 5,000 دج (with Arabic-Indic digits)
+ * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ' })
+ *
+ * // French: DA 5 000,00
+ * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR' })
+ *
+ * // English: DA 5,000.00
+ * formatMoney(5000, { symbol: 'DA', locale: 'en-US' })
+ *
+ * // No decimals: 5,000 دج
+ * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ', decimals: 0 })
+ * ```
+ */
+export declare function formatMoney(amount: number, options: MoneyFormatOptions): string;

package/dist/utils/money.js

@@ -0,0 +1,43 @@
+/**
+ * Deep Money Formatter
+ *
+ * One formatter for every price a storefront shows.
+ * Handles locale-aware formatting, RTL symbol positioning, and Arabic-Indic digits.
+ *
+ * Design principle: ONE function that handles all cases. Callers curry if needed.
+ */
+/**
+ * Format money amount with locale-aware formatting.
+ *
+ * @param amount - Amount in the platform currency's smallest whole unit (DZD)
+ * @param options - Formatting options (symbol, locale, decimals)
+ * @returns Formatted money string
+ *
+ * @example
+ * ```ts
+ * // Arabic: 5,000 دج (with Arabic-Indic digits)
+ * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ' })
+ *
+ * // French: DA 5 000,00
+ * formatMoney(5000, { symbol: 'DA', locale: 'fr-FR' })
+ *
+ * // English: DA 5,000.00
+ * formatMoney(5000, { symbol: 'DA', locale: 'en-US' })
+ *
+ * // No decimals: 5,000 دج
+ * formatMoney(5000, { symbol: 'دج', locale: 'ar-DZ', decimals: 0 })
+ * ```
+ */
+export function formatMoney(amount, options) {
+    const { symbol, locale, decimals = 0 } = options;
+    // Format number with locale-aware formatting
+    const formatted = amount.toLocaleString(locale, {
+        minimumFractionDigits: decimals,
+        maximumFractionDigits: decimals,
+    });
+    // RTL-aware symbol positioning
+    // Arabic: suffix (5,000.00 دج)
+    // French/English: prefix (DA 5,000.00)
+    const isRTL = locale.startsWith("ar");
+    return isRTL ? `${formatted} ${symbol}` : `${symbol} ${formatted}`;
+}

package/dist/utils/product-image.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Which image represents a product outside its own page.
+ *
+ * `coverImage` is nullable in the read models and frequently null: a merchant
+ * uploads a gallery and never explicitly picks a cover. Reading that field
+ * alone gives a product with four photos and no thumbnail — a cart drawer and a
+ * checkout summary showing a name beside an empty grey square, on a storefront
+ * whose whole job is selling by photograph.
+ *
+ * Kept as a function rather than an inline fallback so it is one rule with one
+ * test, and so a cart, a checkout summary and a product card cannot disagree
+ * about which photo a product "is". Pair it with `getThumbnailImage` /
+ * `getCardImage` to turn the answer into a resized URL.
+ */
+/** The least an uploaded image must carry to be usable as a source. */
+export interface ProductImageSourceInput {
+    coverImage?: {
+        src?: string | null;
+    } | null;
+    images?: Array<{
+        src?: string | null;
+    }> | null;
+}
+/**
+ * The product's representative image URL, or `null` when it has none.
+ *
+ * Prefers the merchant's chosen cover, falls back to the first usable gallery
+ * image, and treats a blank `src` as no image at all — so a caller renders its
+ * placeholder exactly when the product genuinely has no photograph.
+ *
+ * @example
+ * ```ts
+ * const src = productImageSource(product); // Product | ProductList
+ * const thumbnail = src ? getThumbnailImage(src) : null;
+ * ```
+ */
+export declare function productImageSource(product: ProductImageSourceInput | null | undefined): string | null;

package/dist/utils/product-image.js

@@ -0,0 +1,38 @@
+/**
+ * Which image represents a product outside its own page.
+ *
+ * `coverImage` is nullable in the read models and frequently null: a merchant
+ * uploads a gallery and never explicitly picks a cover. Reading that field
+ * alone gives a product with four photos and no thumbnail — a cart drawer and a
+ * checkout summary showing a name beside an empty grey square, on a storefront
+ * whose whole job is selling by photograph.
+ *
+ * Kept as a function rather than an inline fallback so it is one rule with one
+ * test, and so a cart, a checkout summary and a product card cannot disagree
+ * about which photo a product "is". Pair it with `getThumbnailImage` /
+ * `getCardImage` to turn the answer into a resized URL.
+ */
+/**
+ * The product's representative image URL, or `null` when it has none.
+ *
+ * Prefers the merchant's chosen cover, falls back to the first usable gallery
+ * image, and treats a blank `src` as no image at all — so a caller renders its
+ * placeholder exactly when the product genuinely has no photograph.
+ *
+ * @example
+ * ```ts
+ * const src = productImageSource(product); // Product | ProductList
+ * const thumbnail = src ? getThumbnailImage(src) : null;
+ * ```
+ */
+export function productImageSource(product) {
+    if (!product)
+        return null;
+    const candidates = [product.coverImage, ...(product.images ?? [])];
+    for (const candidate of candidates) {
+        const src = candidate?.src;
+        if (typeof src === "string" && src.trim().length > 0)
+            return src;
+    }
+    return null;
+}

package/dist/whatsapp.d.ts

@@ -0,0 +1,55 @@
+/**
+ * WhatsApp prefill messages — the storefront's message rule.
+ *
+ * A storefront's WhatsApp launcher hands the shopper to WhatsApp with the
+ * message already written. The template belongs to the merchant (the dashboard
+ * authors it within the limits below), and the page
+ * resolves it: `{store}`, `{product}`, `{url}`, `{order}`.
+ *
+ * Three rules live here so no theme re-invents them:
+ *
+ * 1. **Ad-click parameters are stripped from `{url}`.** A shopper arriving from
+ *    a paid ad should not hand the merchant's WhatsApp a `fbclid`-laden link.
+ * 2. **The resolved message is capped at `MAX_RESOLVED_PREFILL_LENGTH`, cut at
+ *    a word boundary.** Browsers and WhatsApp both truncate silently past a
+ *    point; a cut mid-word reads as a broken store.
+ * 3. **The encoded text is appended the same way everywhere**, so a base href
+ *    that already carries a query string keeps it.
+ */
+/**
+ * The hard cap on a resolved prefill message, in characters.
+ *
+ * The same cap the dashboard's character counter enforces.
+ */
+export declare const MAX_RESOLVED_PREFILL_LENGTH = 900;
+/**
+ * The placeholders a prefill template may carry, resolved from the page the
+ * widget renders on.
+ *
+ * The same tokens the dashboard offers as insert buttons. A token the dashboard offers and the storefront does not
+ * resolve is a merchant seeing `{total}` in a sent message.
+ */
+export declare const PREFILL_TOKENS: readonly ["product", "url", "order", "store"];
+export type PrefillToken = (typeof PREFILL_TOKENS)[number];
+/** Removes ad-click parameters from a page URL so `{url}` stays clean. */
+export declare function stripTrackingParams(rawUrl: string): string;
+/** Cuts text to `maxLen`, preferring the last word boundary over a split word. */
+export declare function truncateAtWordBoundary(text: string, maxLen?: number): string;
+export interface ResolvePrefillParams {
+    template: string;
+    storeName: string;
+    productName?: string | null;
+    url?: string;
+    orderNumber?: string | null;
+}
+/**
+ * Resolves a merchant template into the message the shopper sends.
+ *
+ * `{product}` falls back to the store name (a general template rendered on a
+ * page with no product), `{order}` resolves to nothing when there is no order,
+ * and an unknown placeholder is left verbatim — the dashboard's counter, not
+ * this function, is where a typo gets reported.
+ */
+export declare function resolvePrefillText({ template, storeName, productName, url, orderNumber, }: ResolvePrefillParams): string;
+/** Appends the resolved message to a `wa.me` href, encoded and query-safe. */
+export declare function buildWhatsAppHref(baseHref: string, text: string): string;

package/dist/whatsapp.js

@@ -0,0 +1,89 @@
+/**
+ * WhatsApp prefill messages — the storefront's message rule.
+ *
+ * A storefront's WhatsApp launcher hands the shopper to WhatsApp with the
+ * message already written. The template belongs to the merchant (the dashboard
+ * authors it within the limits below), and the page
+ * resolves it: `{store}`, `{product}`, `{url}`, `{order}`.
+ *
+ * Three rules live here so no theme re-invents them:
+ *
+ * 1. **Ad-click parameters are stripped from `{url}`.** A shopper arriving from
+ *    a paid ad should not hand the merchant's WhatsApp a `fbclid`-laden link.
+ * 2. **The resolved message is capped at `MAX_RESOLVED_PREFILL_LENGTH`, cut at
+ *    a word boundary.** Browsers and WhatsApp both truncate silently past a
+ *    point; a cut mid-word reads as a broken store.
+ * 3. **The encoded text is appended the same way everywhere**, so a base href
+ *    that already carries a query string keeps it.
+ */
+/**
+ * The hard cap on a resolved prefill message, in characters.
+ *
+ * The same cap the dashboard's character counter enforces.
+ */
+export const MAX_RESOLVED_PREFILL_LENGTH = 900;
+/**
+ * The placeholders a prefill template may carry, resolved from the page the
+ * widget renders on.
+ *
+ * The same tokens the dashboard offers as insert buttons. A token the dashboard offers and the storefront does not
+ * resolve is a merchant seeing `{total}` in a sent message.
+ */
+export const PREFILL_TOKENS = ["product", "url", "order", "store"];
+/** Removes ad-click parameters from a page URL so `{url}` stays clean. */
+export function stripTrackingParams(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        const keysToDelete = [];
+        url.searchParams.forEach((_, key) => {
+            const lower = key.toLowerCase();
+            if (lower.startsWith("utm_") || lower.endsWith("clid") || lower === "fbclid") {
+                keysToDelete.push(key);
+            }
+        });
+        for (const key of keysToDelete) {
+            url.searchParams.delete(key);
+        }
+        return url.toString();
+    }
+    catch {
+        return rawUrl;
+    }
+}
+/** Cuts text to `maxLen`, preferring the last word boundary over a split word. */
+export function truncateAtWordBoundary(text, maxLen = MAX_RESOLVED_PREFILL_LENGTH) {
+    if (text.length <= maxLen)
+        return text;
+    const sliced = text.slice(0, maxLen);
+    const lastSpace = sliced.lastIndexOf(" ");
+    if (lastSpace > 0) {
+        return sliced.slice(0, lastSpace).trimEnd();
+    }
+    return sliced;
+}
+/**
+ * Resolves a merchant template into the message the shopper sends.
+ *
+ * `{product}` falls back to the store name (a general template rendered on a
+ * page with no product), `{order}` resolves to nothing when there is no order,
+ * and an unknown placeholder is left verbatim — the dashboard's counter, not
+ * this function, is where a typo gets reported.
+ */
+export function resolvePrefillText({ template, storeName, productName, url, orderNumber, }) {
+    const cleanUrl = url ? stripTrackingParams(url) : "";
+    const product = productName && productName.trim() ? productName.trim() : storeName;
+    const order = orderNumber ? orderNumber.trim() : "";
+    const resolved = template
+        .replaceAll("{store}", storeName)
+        .replaceAll("{product}", product)
+        .replaceAll("{url}", cleanUrl)
+        .replaceAll("{order}", order);
+    return truncateAtWordBoundary(resolved, MAX_RESOLVED_PREFILL_LENGTH);
+}
+/** Appends the resolved message to a `wa.me` href, encoded and query-safe. */
+export function buildWhatsAppHref(baseHref, text) {
+    if (!text)
+        return baseHref;
+    const separator = baseHref.includes("?") ? "&" : "?";
+    return `${baseHref}${separator}text=${encodeURIComponent(text)}`;
+}

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "@wocart/storefront",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
+  "keywords": [
+    "wocart",
+    "storefront",
+    "ecommerce",
+    "cash-on-delivery",
+    "cod",
+    "algeria",
+    "astro",
+    "sdk",
+    "typescript"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bighadj22/codflow.git",
+    "directory": "wocart-sdk/storefront"
+  },
+  "homepage": "https://github.com/bighadj22/codflow/tree/main/wocart-sdk/storefront#readme",
+  "bugs": "https://github.com/bighadj22/codflow/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./astro": {
+      "types": "./dist/astro.d.ts",
+      "default": "./dist/astro.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "USAGE.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "node --eval \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "build:watch": "tsc --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit && tsc --project tsconfig.test.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify:package": "npm run build && node scripts/check-package.mjs && node scripts/verify-package.mjs",
+    "verify:live": "npm run build && node scripts/verify-live.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "node scripts/check-package.mjs"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "peerDependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "fast-check": "^4.6.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0",
+    "zod": "^4.4.3"
+  }
+}