@seasonkoh/webaz 0.1.20 → 0.1.22

package/dist/money.js

@@ -0,0 +1,106 @@
+/**
+ * Money — 协议资金的【唯一】算术面(RFC-014 option A:整数最小单位)。
+ *
+ * 背景:此前金额用 JS float(SQLite REAL + number + Math.round(x*100)/100),除不尽的金额
+ *   (33.33 @ 7% 等)会在【个体钱包】留浮点尘(staked=3.3299999999983)。聚合守恒安全(残差0,
+ *   靠 residual-absorption),但接真实 USDC(整数 base-unit)对账时会变成真裂缝。诊断见
+ *   tests/test-money-precision-adversarial.ts。
+ *
+ * 表示:1 WAZ = 1,000,000 base-units(6 位小数,与 USDC base-units 对齐 → 链上对账 1:1)。
+ *   全部算术在【整数 base-units】上做(精确),只在显示层转回 2 位小数。
+ *   类型用 number 整数(安全到 ±2^53 ≈ 9.007e9 WAZ,模拟币足够);链上 USDC 边界 viem 已用 BigInt。
+ *
+ * 守恒利器:allocate() 用最大余数法把总额拆成整数桶且【精确求和 = 总额】——从源头消灭 dust,
+ *   且天然守恒(不增发/不丢)。mulRate() 单次舍入到整数单位。
+ *
+ * 用法(RFC-014 港口策略):资金热路径(engine.settle* / orders / 佣金 / dispute / skill …)
+ *   一律 toUnits 进 → 在 units 上 add/sub/mulRate/allocate → toUnits 出存库;显示层用 format。
+ *   全部港口完成后 schema 改 INTEGER(PR6),届时 toUnits/toDecimal 退化为存取边界。
+ */
+export const MONEY_SCALE = 1_000_000; // 1 WAZ = 1e6 base-units(6 dp,USDC 对齐)
+const MAX_SAFE = Number.MAX_SAFE_INTEGER; // 2^53 - 1 ≈ 9.007e15 units ≈ 9.007e9 WAZ
+function assertUnits(u, ctx) {
+    if (!Number.isFinite(u) || !Number.isInteger(u))
+        throw new Error(`money[${ctx}]: 非整数 units: ${u}`);
+    if (Math.abs(u) > MAX_SAFE)
+        throw new Error(`money[${ctx}]: units 超出安全整数范围: ${u}`);
+}
+/** 十进制 WAZ(number/string)→ 整数 base-units(四舍五入到最近 unit)。存量 REAL 价格的入口。 */
+export function toUnits(decimal) {
+    const n = typeof decimal === 'string' ? Number(decimal) : decimal;
+    if (!Number.isFinite(n))
+        throw new Error(`money.toUnits: 非有限数: ${decimal}`);
+    const u = Math.round(n * MONEY_SCALE);
+    assertUnits(u, 'toUnits');
+    return u;
+}
+/** 整数 base-units → 十进制 number(兼容/显示边界;返回 float,仅用于显示或与遗留 REAL 字段衔接)。 */
+export function toDecimal(units) {
+    assertUnits(units, 'toDecimal');
+    return units / MONEY_SCALE;
+}
+/** 整数 base-units → 定点字符串(默认 2 位,WAZ 展示)。整数运算舍入,不靠 float toFixed。 */
+export function format(units, dp = 2) {
+    assertUnits(units, 'format');
+    const neg = units < 0;
+    let abs = Math.abs(units);
+    const grain = Math.round(MONEY_SCALE / 10 ** dp); // dp=2 → 1e4 units 为一格
+    abs = Math.round(abs / grain) * grain; // 舍入到 dp 粒度(整数运算)
+    const whole = Math.floor(abs / MONEY_SCALE);
+    const fracUnits = abs - whole * MONEY_SCALE;
+    const fracStr = dp > 0 ? '.' + String(Math.floor(fracUnits / grain)).padStart(dp, '0') : '';
+    return (neg ? '-' : '') + String(whole) + fracStr;
+}
+export function add(a, b) { const r = a + b; assertUnits(r, 'add'); return r; }
+export function sub(a, b) { const r = a - b; assertUnits(r, 'sub'); return r; }
+export function sum(xs) { return xs.reduce((acc, x) => add(acc, x), 0); }
+/** 单价 × 整数数量(精确)。 */
+export function mulQty(unit, qty) {
+    if (!Number.isInteger(qty) || qty < 0)
+        throw new Error(`money.mulQty: qty 非非负整数: ${qty}`);
+    const r = unit * qty;
+    assertUnits(r, 'mulQty');
+    return r;
+}
+/** 金额 × 费率(rate 如 0.07);结果【单次】舍入到整数 base-units。守恒由 allocate 负责,勿用多次 mulRate 凑总额。 */
+export function mulRate(amount, rate) {
+    if (!Number.isFinite(rate) || rate < 0)
+        throw new Error(`money.mulRate: rate 非法: ${rate}`);
+    assertUnits(amount, 'mulRate');
+    const r = Math.round(amount * rate);
+    assertUnits(r, 'mulRate');
+    return r;
+}
+/** clamp 到 [0, cap](cap 省略=只防负)。用于"不超过余额/不超过原佣金"等上限。 */
+export function clamp(units, lo = 0, hi = MAX_SAFE) {
+    assertUnits(units, 'clamp');
+    return Math.max(lo, Math.min(hi, units));
+}
+/**
+ * 把 total 按整数权重拆成 N 桶,【精确求和 = total】(最大余数法)。
+ *   - 守恒:Σ 输出 === total,无 dust、不增发/不丢。
+ *   - 余数(floor 后差额)按小数部分从大到小逐 1 派发(确定性、稳定)。
+ *   - 全 0 权重 → 全 0 桶(调用方决定 total 的去向,通常落 reserve)。
+ * 用于佣金/罚没/分润等"一笔总额分给多方"的场景,替代逐项 round 造成的不守恒。
+ */
+export function allocate(total, weights) {
+    assertUnits(total, 'allocate');
+    if (weights.some(w => !Number.isFinite(w) || w < 0))
+        throw new Error(`money.allocate: 权重含负/非法`);
+    const W = weights.reduce((a, b) => a + b, 0);
+    if (W <= 0)
+        return weights.map(() => 0);
+    const raw = weights.map(w => (total * w) / W);
+    const floor = raw.map(Math.floor);
+    const used = floor.reduce((a, b) => a + b, 0);
+    let remainder = total - used; // 整数,0..N-1(total≥0 时)
+    const out = floor.slice();
+    const order = raw.map((r, i) => ({ i, frac: r - Math.floor(r) })).sort((a, b) => b.frac - a.frac || a.i - b.i);
+    for (let k = 0; remainder > 0 && k < order.length; k++, remainder--)
+        out[order[k].i] += 1;
+    // total 为负数的极端情况(理论上不该发生)兜底:把残余补到最后一桶,守恒优先
+    if (remainder !== 0)
+        out[out.length - 1] += remainder;
+    out.forEach((u, i) => assertUnits(u, `allocate[${i}]`));
+    return out;
+}

package/dist/pwa/acp-feed.js

@@ -0,0 +1,103 @@
+const BASE = 'https://webaz.xyz';
+// ACP availability 枚举(spec):in_stock | out_of_stock | pre_order | backorder | unknown
+function availability(stock) {
+    const n = Number(stock);
+    if (!Number.isFinite(n))
+        return 'unknown';
+    return n > 0 ? 'in_stock' : 'out_of_stock';
+}
+// 绝对化图片 URL(相对路径 → https://webaz.xyz/...);已是 http(s) 的原样返回
+function absolutizeImg(raw) {
+    if (typeof raw !== 'string' || !raw.trim())
+        return null;
+    const s = raw.trim();
+    if (/^https?:\/\//i.test(s))
+        return s;
+    return BASE + (s.startsWith('/') ? s : '/' + s);
+}
+// description 必须 plain text(spec)→ 去 HTML 标签 + 折叠空白 + 截 5000
+function plainText(raw, max) {
+    if (typeof raw !== 'string')
+        return '';
+    return raw.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+}
+export function buildAcpProductFeed(db, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 2000, 1), 5000);
+    let rows = [];
+    try {
+        rows = db.prepare(`
+      SELECT p.id, p.title, p.description, p.price, p.currency, p.stock, p.category,
+             p.images, p.brand, p.model, p.return_days, p.product_type,
+             p.seller_id, u.name AS seller_name
+      FROM products p
+      LEFT JOIN users u ON u.id = p.seller_id
+      WHERE p.status = 'active'
+      ORDER BY p.created_at DESC
+      LIMIT ?
+    `).all(limit);
+    }
+    catch {
+        rows = [];
+    }
+    const products = rows.map((p) => {
+        let imgs = [];
+        try {
+            const arr = JSON.parse(p.images || '[]');
+            if (Array.isArray(arr))
+                imgs = arr.map(absolutizeImg).filter((x) => !!x);
+        }
+        catch { /* malformed → no images */ }
+        const returnDays = Number(p.return_days);
+        const hasReturn = Number.isFinite(returnDays) && returnDays > 0;
+        const item = {
+            item_id: p.id, // 稳定商品 ID(spec: max 100)
+            title: (p.title || '').slice(0, 150), // spec: max 150
+            description: plainText(p.description, 5000), // spec: plain text, max 5000
+            url: `${BASE}/#order-product/${p.id}`, // 商品详情页(SPA hash,200)
+            // price: spec = Number + ISO 4217 code。WAZ 非 ISO 4217 → 见 feed 级 _disclosures.currency
+            price: { amount: Number(p.price), currency: p.currency || 'WAZ' },
+            availability: availability(p.stock),
+            is_digital: p.product_type === 'digital',
+            seller_name: (p.seller_name || p.seller_id).slice(0, 70),
+            seller_url: `${BASE}/#u/${p.seller_id}`,
+            // 诚实门控:可发现 ≠ 可经 ACP 购买(ACP /complete 是卡+PSP,WebAZ 未接 —— RFC-015)
+            is_eligible_search: true,
+            is_eligible_checkout: false,
+            is_eligible_ads: false,
+        };
+        if (imgs.length) {
+            item.image_url = imgs[0];
+            if (imgs.length > 1)
+                item.additional_image_urls = imgs.slice(1).join(',');
+        }
+        if (p.brand)
+            item.brand = String(p.brand).slice(0, 70);
+        if (p.model)
+            item.mpn = String(p.model).slice(0, 70);
+        if (p.category)
+            item.product_category = String(p.category);
+        if (hasReturn) {
+            item.accepts_returns = true;
+            item.return_deadline_in_days = Math.round(returnDays);
+        }
+        return item;
+    });
+    return {
+        feed_version: 1,
+        generated_at: new Date().toISOString(),
+        source: 'WebAZ',
+        spec: {
+            based_on: 'OpenAI Agentic Commerce Protocol — product feed',
+            api_version_observed: '2025-09-12',
+            reference: 'https://developers.openai.com/commerce/specs/feed',
+            rfc: `${BASE}/docs/INTEGRATOR.md`,
+        },
+        _disclosures: {
+            phase: 'pre-launch',
+            currency: "Each item's price.currency is the protocol's SIMULATED pre-launch internal unit (WAZ, or legacy 'DCP'), NOT an ISO 4217 fiat currency. No real money is involved.",
+            checkout: 'is_eligible_checkout is false for every item: ACP checkout is not yet wired. Products are DISCOVERABLE via ACP, not yet PURCHASABLE via ACP. Native WebAZ checkout + escrow + state machine govern real purchases (see RFC-015).',
+        },
+        product_count: products.length,
+        products,
+    };
+}