@final-commerce/common 1.1.4-beta.4

package/README.md

@@ -0,0 +1,224 @@
+# @final-commerce/common
+
+Shared utilities, types, and constants for Final Commerce applications. This package provides framework-agnostic functionality that works across both frontend (React, Vue, etc.) and backend (Node.js, NestJS) environments.
+
+## Installation
+
+```bash
+npm install @final-commerce/common
+```
+
+## Imports
+
+Everything is re-exported from the package root:
+
+```typescript
+import { CurrencyCode, toMinorUnits, formatCurrency, Amount } from '@final-commerce/common';
+```
+
+Sub-path imports also work:
+
+```typescript
+import { toMinorUnits } from '@final-commerce/common/dist/utils/currency.util';
+import { CurrencyCode } from '@final-commerce/common/dist/enums';
+```
+
+---
+
+## Enums
+
+### `CurrencyCode`
+
+ISO 4217 currency codes. 41 currencies across three decimal groups:
+
+| Decimal Places        | Currencies                                                                                                                            |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| **2** (standard)      | USD, EUR, GBP, CAD, AUD, NZD, CHF, CNY, INR, MXN, BRL, ZAR, SGD, HKD, SEK, NOK, DKK, PLN, THB, MYR, PHP, IDR, AED, SAR, ILS, TRY, RUB |
+| **0** (zero-decimal)  | JPY, KRW, VND, CLP, ISK, HUF, TWD                                                                                                     |
+| **3** (three-decimal) | KWD, BHD, OMR, JOD, TND, LYD, IQD                                                                                                     |
+
+## Interfaces
+
+### `Amount`
+
+Represents a monetary value stored in the database.
+
+```typescript
+{ amount: 3122, currency: 'USD', minorUnits: 2 }  // = $31.22
+```
+
+| Field        | Type           | Description                       |
+| ------------ | -------------- | --------------------------------- |
+| `amount`     | `number`       | Value in minor units (e.g. cents) |
+| `currency`   | `CurrencyCode` | ISO 4217 code                     |
+| `minorUnits` | `number`       | Decimal places (2, 0, or 3)       |
+
+### `CurrencyConfig`
+
+| Currency | Minor Units | Symbol | Example  |
+| -------- | ----------- | ------ | -------- |
+| USD      | 2           | $      | $10.50   |
+| EUR      | 2           | €      | €10.50   |
+| GBP      | 2           | £      | £10.50   |
+| JPY      | 0           | ¥      | ¥1000    |
+| KWD      | 3           | KD     | KD10.500 |
+
+| Field            | Type                   | Description                          |
+| ---------------- | ---------------------- | ------------------------------------ |
+| `minorUnits`     | `number`               | Decimal places                       |
+| `symbol`         | `string`               | Display symbol (`$`, `€`, `¥`, etc.) |
+| `symbolPosition` | `'prefix' \| 'suffix'` | Where the symbol goes                |
+
+---
+
+## Utility Functions
+
+### Conversion
+
+| Function                                       | In                 | Out    | What it does                                                 |
+| ---------------------------------------------- | ------------------ | ------ | ------------------------------------------------------------ |
+| `toMinorUnits(amount, currency)`               | `(10.50, 'USD')`   | `1050` | Major to minor units                                         |
+| `fromMinorUnits(minorAmount, currency)`        | `(1050, 'USD')`    | `10.5` | Minor to major units                                         |
+| `stringifyMinorUnits(minorAmount, minorUnits)` | `(1050, 2)`        | `10.5` | Minor to major using decimal count directly                  |
+| `parseAmountToMinorUnits(str, currency)`       | `('10.50', 'USD')` | `1050` | Parse string input to minor units. Returns `null` on failure |
+
+### Formatting
+
+| Function                                            | In              | Out        | What it does                                                                                    |
+| --------------------------------------------------- | --------------- | ---------- | ----------------------------------------------------------------------------------------------- |
+| `formatCurrency(minorAmount, currency, options?)`   | `(1050, 'USD')` | `'$10.50'` | Display string with symbol and grouping                                                         |
+| `formatMinorUnitsToString(minorAmount, minorUnits)` | `(1050, 2)`     | `'10.5'`   | Plain decimal string (no symbol, no trailing zeros). Useful for API payloads (e.g. WooCommerce) |
+
+`formatCurrency` options:
+
+- `includeSymbol` (default: `true`) — include currency symbol
+- `useGrouping` (default: `true`) — thousands separators
+
+### Arithmetic
+
+All inputs and outputs are in minor units (integers).
+
+| Function                             | Example       | Result |
+| ------------------------------------ | ------------- | ------ |
+| `addAmounts(a, b)`                   | `(1050, 250)` | `1300` |
+| `subtractAmounts(a, b)`              | `(1050, 250)` | `800`  |
+| `multiplyAmount(amount, multiplier)` | `(1050, 2)`   | `2100` |
+| `divideAmount(amount, divisor)`      | `(1050, 2)`   | `525`  |
+| `calculatePercentage(amount, pct)`   | `(10000, 15)` | `1500` |
+
+`divideAmount` throws on division by zero. `calculatePercentage` takes percentage as a whole number (15 = 15%, not 0.15).
+
+### Config / Validation
+
+| Function                           | What it does                                                                                  |
+| ---------------------------------- | --------------------------------------------------------------------------------------------- |
+| `getCurrencyConfig(currency)`      | Returns `CurrencyConfig` for a code. Falls back to 2-decimal default for unknown currencies   |
+| `getMinorUnitMultiplier(currency)` | Returns `10^minorUnits` (100 for USD, 1 for JPY, 1000 for KWD)                                |
+| `getMinorUnits(currency)`          | Returns decimal place count for a currency                                                    |
+| `isSupportedCurrency(currency)`    | `true` if the currency has explicit config                                                    |
+| `parseCurrencyCode(value)`         | Validates a raw string is a valid `CurrencyCode`. Throws with supported codes list if invalid |
+
+### Amount Object Helpers
+
+Used in BuilderHub for converting between user input and the `Amount` storage format.
+
+| Function                        | Example                                              | Result                                             |
+| ------------------------------- | ---------------------------------------------------- | -------------------------------------------------- |
+| `createAmount(value, currency)` | `('31.22', 'USD')`                                   | `{ amount: 3122, currency: 'USD', minorUnits: 2 }` |
+| `amountToString(amount)`        | `({ amount: 3122, currency: 'USD', minorUnits: 2 })` | `'31.22'`                                          |
+
+`createAmount` accepts `string | number | null | undefined`. Returns `undefined` for null, undefined, empty string, or NaN input.
+`amountToString` returns `''` for null/undefined input.
+
+### Constants
+
+`CURRENCY_CONFIG` — a `Record<CurrencyCode | string, CurrencyConfig>` mapping all 41 currencies to their config (symbol, decimal places, symbol position).
+
+---
+
+## Local Development
+
+```bash
+npm install
+npm run build       # build with tsup (CJS + ESM + types → dist/)
+npm run dev         # watch mode — rebuilds on file changes
+npm test            # vitest in watch mode
+npm run test:run    # single test run
+npm run test:ui     # vitest UI
+npm run test:coverage
+```
+
+### Link locally to another project
+
+Use `npm link` to test changes in a consuming project without publishing:
+
+```bash
+# 1. In this package (common/) — build first so dist/ is up to date
+npm run build
+npm link
+
+# 2. In the consuming project (e.g. hub-api/) — clear node_modules to avoid stale/duplicate copies
+rm -rf node_modules/@final-commerce/common
+npm link @final-commerce/common
+
+# 3. Verify the symlink points to your local copy
+ls -la node_modules/@final-commerce/common
+# Should show a symlink → /path/to/common
+
+# 4. When done, unlink and restore the published version
+npm unlink @final-commerce/common   # in consumer
+npm install                         # reinstall published version
+npm unlink                          # in common/
+```
+
+> **If you change source files in common**, run `npm run build` again (or use `npm run dev` for watch mode). The symlink means the consumer always reads from common's `dist/`, so it picks up new builds immediately.
+
+### Quick verification with `node -p`
+
+After building, verify exports directly from the terminal:
+
+```bash
+# Check the package loads
+node -p "require('./dist/index.js')"
+
+# Test a conversion
+node -p "const c = require('./dist/index.js'); c.toMinorUnits(10.50, 'USD')"
+# → 1050
+
+# Test formatting
+node -p "const c = require('./dist/index.js'); c.formatCurrency(1050, 'USD')"
+# → $10.50
+
+# Test zero-decimal currency
+node -p "const c = require('./dist/index.js'); c.toMinorUnits(1000, 'JPY')"
+# → 1000
+
+# Test three-decimal currency
+node -p "const c = require('./dist/index.js'); c.toMinorUnits(10.5, 'KWD')"
+# → 10500
+
+# Test Amount helpers
+node -p "const c = require('./dist/index.js'); c.createAmount('31.22', 'USD')"
+# → { amount: 3122, currency: 'USD', minorUnits: 2 }
+
+node -p "const c = require('./dist/index.js'); c.amountToString({ amount: 3122, currency: 'USD', minorUnits: 2 })"
+# → 31.22
+
+# List all exported keys
+node -p "Object.keys(require('./dist/index.js'))"
+```
+
+### Verify from a linked project
+
+After `npm link`, verify the link works in the consuming project:
+
+```bash
+# In the consuming project directory
+node -p "require('@final-commerce/common')"
+node -p "const c = require('@final-commerce/common'); c.formatCurrency(2500, 'EUR')"
+# → €25.00
+```
+
+## License
+
+Private — Final Commerce internal use only.

package/bin/gate-done.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * gate-done — pre-push hook.
+ *
+ * Runs four sweeps inside a 90-second wall-clock budget:
+ *
+ *   1. npm audit — known CVE check against the installed dependency tree
+ *   2. gitleaks  — credential / secret scanning (git log + staged)
+ *   3. vitest    — full test suite with coverage threshold enforcement
+ *   4. bundle    — size-limit or custom bundle-size script (if configured)
+ *
+ * Any sweep failure exits 1, blocking the push.
+ * Budget overrun also exits 1.
+ *
+ * Install as Husky pre-push hook:
+ *   echo "npx gate-done" > .husky/pre-push
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const BUDGET_MS = 90_000;
+const t0 = Date.now();
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function remaining() {
+  return Math.max(0, BUDGET_MS - (Date.now() - t0));
+}
+
+function elapsed() {
+  return ((Date.now() - t0) / 1000).toFixed(1);
+}
+
+function checkBudget(label) {
+  if (remaining() <= 0) {
+    fail(`90s budget exhausted before "${label}" could complete. Push blocked.`);
+  }
+}
+
+/**
+ * Run a command, streaming output. Returns the spawnSync result.
+ * Passes remaining budget as the process timeout so a runaway child
+ * cannot exceed the wall-clock limit on its own.
+ */
+function run(cmd) {
+  return spawnSync(cmd, {
+    shell: true,
+    encoding: 'utf8',
+    stdio: 'inherit',
+    timeout: remaining(),
+  });
+}
+
+function capture(cmd) {
+  return spawnSync(cmd, { shell: true, encoding: 'utf8', timeout: remaining() });
+}
+
+function fail(msg) {
+  process.stderr.write(`\x1b[31m✖  [${elapsed()}s] ${msg}\x1b[0m\n`);
+  process.exit(1);
+}
+
+function warn(msg) {
+  process.stdout.write(`\x1b[33m⚠  [${elapsed()}s] ${msg}\x1b[0m\n`);
+}
+
+function info(msg) {
+  process.stdout.write(`\x1b[36mℹ  [${elapsed()}s] ${msg}\x1b[0m\n`);
+}
+
+function ok(msg) {
+  process.stdout.write(`\x1b[32m✔  [${elapsed()}s] ${msg}\x1b[0m\n`);
+}
+
+// ── 1. npm audit ─────────────────────────────────────────────────────────────
+
+info('Sweep 1/4 — npm audit (known CVEs)…');
+checkBudget('npm audit');
+
+const auditResult = run('npm audit --audit-level=high');
+if (auditResult.status !== 0) {
+  fail('npm audit found high or critical vulnerabilities. Run `npm audit` for details.');
+}
+ok('npm audit: no high/critical vulnerabilities.');
+
+// ── 2. gitleaks ───────────────────────────────────────────────────────────────
+
+info('Sweep 2/4 — gitleaks secrets scan…');
+checkBudget('gitleaks');
+
+const hasGitleaks = capture('command -v gitleaks 2>/dev/null').status === 0;
+
+if (!hasGitleaks) {
+  warn(
+    'gitleaks not found in PATH — secrets scan skipped.\n' +
+      '   Install: https://github.com/gitleaks/gitleaks#installing',
+  );
+} else {
+  // Scan the full git history visible from HEAD — correct mode for a pre-push hook.
+  // --no-git-serial scans refs in parallel for speed within the budget.
+  const glResult = run('gitleaks git --exit-code 1 .');
+  if (glResult.status !== 0) {
+    fail('gitleaks detected a potential secret. Remove it and retry the push.');
+  }
+  ok('gitleaks: no secrets detected.');
+}
+
+// ── 3. vitest coverage ────────────────────────────────────────────────────────
+
+info('Sweep 3/4 — Vitest test suite + coverage thresholds…');
+checkBudget('vitest');
+
+const vitestResult = run('npx vitest run --coverage');
+
+if (vitestResult.status !== 0) {
+  fail('Vitest coverage gate failed — fix failing tests or low-coverage areas before pushing.');
+}
+
+ok('Vitest: all tests passed, coverage thresholds met.');
+
+// ── 4. bundle size ────────────────────────────────────────────────────────────
+
+info('Sweep 4/4 — bundle size audit…');
+checkBudget('bundle audit');
+
+const pkgPath = resolve(process.cwd(), 'package.json');
+const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+
+const hasBundleSizeScript = Boolean(pkg.scripts?.['bundle-size']);
+const hasSizeLimit = Boolean(pkg.devDependencies?.['size-limit']) || Boolean(pkg.dependencies?.['size-limit']);
+const hasBundlesize = Boolean(pkg.devDependencies?.['bundlesize']) || Boolean(pkg.dependencies?.['bundlesize']);
+const hasBuildScript = Boolean(pkg.scripts?.build);
+
+if (hasBundleSizeScript) {
+  const result = run('npm run bundle-size');
+  if (result.status !== 0) fail('bundle-size script reported a violation. Push blocked.');
+  ok('Bundle size: within limits.');
+} else if (hasSizeLimit) {
+  const result = run('npx size-limit');
+  if (result.status !== 0) fail('size-limit reported a violation. Push blocked.');
+  ok('Bundle size: size-limit passed.');
+} else if (hasBundlesize) {
+  const result = run('npx bundlesize');
+  if (result.status !== 0) fail('bundlesize reported a violation. Push blocked.');
+  ok('Bundle size: bundlesize passed.');
+} else if (hasBuildScript) {
+  // No size tool configured — at minimum verify the build succeeds cleanly.
+  info('No size-limit/bundlesize configured — running build as a smoke-check.');
+  const result = run('npm run build');
+  if (result.status !== 0) fail('Build failed during gate-done. Push blocked.');
+  ok('Build: succeeded (no size budget configured).');
+} else {
+  info('No build or bundle-size script found — skipping bundle sweep.');
+}
+
+// ── done ─────────────────────────────────────────────────────────────────────
+
+ok(`gate-done completed in ${elapsed()}s (budget: 90s). Push proceeding.`);
+process.exit(0);