feat: initialize storefront kit package for public release

Author: SALAHEX

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.28.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Build
+        run: pnpm build
+
+      - name: Package smoke
+        run: npm pack --dry-run

.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.28.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+          cache: pnpm
+
+      - name: Install
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Publish
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+package-lock.json

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.
+- Added `resolveVariantSelection` and variant matching helpers.
+- Added `normalizeProductCard` and `normalizeCartSummary`.
+- Added promotion classification helpers:
+  - `classifyPromotionStatus`
+  - `promotionStatusLabel`

README.md

@@ -1,2 +1,73 @@
-# ecommaps-storefront-kit
-Framework-agnostic storefront business logic kit for Ecommaps.
+# @ecommaps/storefront-kit
+
+Framework-agnostic commerce logic primitives for Ecommaps storefront applications.
+
+![npm version](https://img.shields.io/npm/v/@ecommaps/storefront-kit)
+
+## 1. Positioning
+
+Use this package for reusable business logic that should not depend on:
+- Next.js
+- React
+- AI SDK
+
+This package is intended for server actions, API routes, workers, and backend services.
+
+## 2. Installation
+
+```bash
+pnpm add @ecommaps/storefront-kit
+```
+
+## 3. Public API
+
+### Variant resolution
+
+- `resolveVariantSelection(product, input)`
+- `variantMatchesColorAndSize(product, variant, color, size)`
+
+Behavior:
+- supports multilingual color/size synonyms
+- enforces exact size semantics (prevents wrong size fallback)
+- returns `requires_selection` when match is ambiguous
+
+### Normalizers
+
+- `normalizeProductCard(product)`
+- `normalizeCartSummary(cart)`
+
+### Promotions
+
+- `classifyPromotionStatus(promotion, context)`
+- `promotionStatusLabel(status)`
+
+## 4. Usage example
+
+```ts
+import {
+  resolveVariantSelection,
+  normalizeProductCard,
+  normalizeCartSummary,
+  classifyPromotionStatus,
+} from "@ecommaps/storefront-kit";
+
+const selection = resolveVariantSelection(product, {
+  variant_id: undefined,
+  color: "red",
+  size: "L",
+});
+
+const card = normalizeProductCard(product);
+const cart = normalizeCartSummary(rawCart);
+
+const promoState = classifyPromotionStatus(
+  { code: "DISCOUNT20", min_order_amount: 5000 },
+  { enteredCode: "DISCOUNT20", cartTotal: 7000, explicitValidationPassed: true },
+);
+```
+
+## 5. Compatibility
+
+- Runtime: Node.js 20+
+- No UI framework dependency
+- Semver-stable function contracts

package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ecommaps/storefront-kit",
+  "version": "0.1.0",
+  "description": "Reusable storefront business logic utilities for Ecommaps.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist node_modules"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/labobankcom/ecommaps-storefront-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/labobankcom/ecommaps-storefront-kit/issues"
+  },
+  "homepage": "https://github.com/labobankcom/ecommaps-storefront-kit#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "packageManager": "pnpm@10.28.0"
+}