@zanii/blackbox 0.0.0-stage → 0.2.0

package/dist/billing/index.js

@@ -0,0 +1,174 @@
+// Invoices in integer fils with UAE VAT (spec/billing.md §3), issued tax invoices (§5) and the
+// Stripe webhook signature (§6). Mirrors sdks/python/src/zanii_blackbox/billing.py.
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { formatAed } from "../cost/index.js";
+const grouped = (n) => String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+export function invoice(plan, usage, vatPercent = 5) {
+    const lines = [
+        {
+            description: `${plan.name} plan, monthly`,
+            quantity: 1,
+            unit_fils: plan.monthly_fils,
+            amount_fils: plan.monthly_fils,
+        },
+    ];
+    if (plan.included_events !== undefined && plan.per_1000_events_fils !== undefined) {
+        const blocks = Math.ceil(Math.max(0, usage.events - plan.included_events) / 1000);
+        if (blocks > 0)
+            lines.push({
+                description: `Events over ${grouped(plan.included_events)} (per 1,000)`,
+                quantity: blocks,
+                unit_fils: plan.per_1000_events_fils,
+                amount_fils: blocks * plan.per_1000_events_fils,
+            });
+    }
+    if (plan.included_sessions !== undefined && plan.per_session_fils !== undefined) {
+        const over = Math.max(0, (usage.sessions ?? 0) - plan.included_sessions);
+        if (over > 0)
+            lines.push({
+                description: `Sessions over ${grouped(plan.included_sessions)}`,
+                quantity: over,
+                unit_fils: plan.per_session_fils,
+                amount_fils: over * plan.per_session_fils,
+            });
+    }
+    const subtotal = lines.reduce((sum, l) => sum + l.amount_fils, 0);
+    // VAT once, on the subtotal, rounded half up (integer arithmetic only).
+    const vat = Math.floor((subtotal * vatPercent + 50) / 100);
+    return {
+        lines,
+        subtotal_fils: subtotal,
+        vat_percent: vatPercent,
+        vat_fils: vat,
+        total_fils: subtotal + vat,
+    };
+}
+const PAIRS = [
+    ["included_events", "per_1000_events_fils"],
+    ["included_sessions", "per_session_fils"],
+];
+/** Parses a plans file (spec/billing.md §1); throws on anything that isn't integer fils. */
+export function loadPlans(bytes) {
+    const doc = JSON.parse(new TextDecoder().decode(bytes));
+    if (doc.currency !== "AED" || typeof doc.version !== "string" || typeof doc.plans !== "object")
+        throw new Error("not a v1 plans file (AED, integer fils)");
+    const fils = (id, k, v) => {
+        if (!Number.isSafeInteger(v) || v < 0)
+            throw new Error(`plan ${id}: ${k} must be an integer ≥ 0`);
+    };
+    for (const [id, p] of Object.entries(doc.plans)) {
+        fils(id, "monthly_fils", p.monthly_fils);
+        for (const [a, b] of PAIRS) {
+            if ((p[a] === undefined) !== (p[b] === undefined))
+                throw new Error(`plan ${id}: ${a} and ${b} go together`);
+            if (p[a] !== undefined) {
+                fils(id, a, p[a]);
+                fils(id, b, p[b]);
+            }
+        }
+    }
+    return doc;
+}
+/** The month's `[from, to)` and its last day (spec/billing.md §5). */
+function period(month) {
+    const [y, m] = month.split("-").map(Number);
+    const iso = (t) => new Date(t).toISOString().slice(0, 10);
+    const next = Date.UTC(y, m, 1); // month m (1-based) is index m-1; index m is the next month
+    return { from: `${month}-01`, to: iso(next), last: iso(next - 86_400_000) };
+}
+/** spec/billing.md §5: the tax invoice document. */
+export function taxInvoice(input) {
+    const p = period(input.month);
+    const inv = invoice(input.plan, input.usage, input.vat_percent ?? 5);
+    return {
+        v: 1,
+        title: "Tax Invoice",
+        number: input.number,
+        issued_at: input.issued_at,
+        period: { from: p.from, to: p.to },
+        date_of_supply: p.last,
+        supplier: {
+            name: input.supplier.name,
+            address: input.supplier.address,
+            trn: input.supplier.trn,
+        },
+        customer: {
+            legal_name: input.customer.legal_name,
+            address: input.customer.address,
+            trn: input.customer.trn ?? null,
+        },
+        currency: "AED",
+        plan: { id: input.plan_id, name: input.plan.name, version: input.plans_version },
+        usage: { events: input.usage.events, sessions: input.usage.sessions },
+        ...inv,
+        total_aed: formatAed(inv.total_fils),
+    };
+}
+const aed = (fils) => `${grouped(Math.floor(fils / 100))}.${String(fils % 100).padStart(2, "0")}`;
+const cell = (s) => s.replace(/\r\n|\r|\n/g, " ").replace(/\|/g, "\\|");
+const oneLine = (s) => s
+    .split(/\r\n|\r|\n/)
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .join(", ");
+/** spec/billing.md §5: the printable copy. */
+export function renderTaxInvoice(d) {
+    const out = [
+        "# Tax Invoice",
+        "",
+        "| Field | Value |",
+        "|---|---|",
+        `| Invoice number | ${cell(d.number)} |`,
+        `| Date of issue | ${d.issued_at} |`,
+        `| Date of supply | ${d.date_of_supply} (period ${d.period.from} to ${d.date_of_supply}) |`,
+        "",
+        "## Supplier",
+        "",
+        `${oneLine(d.supplier.name)}  `,
+        `${oneLine(d.supplier.address)}  `,
+        `TRN: ${d.supplier.trn}`,
+        "",
+        "## Customer",
+        "",
+        `${oneLine(d.customer.legal_name)}  `,
+        `${oneLine(d.customer.address)}  `,
+        `TRN: ${d.customer.trn ?? "not registered"}`,
+        "",
+        "## Lines",
+        "",
+        "| Description | Quantity | Unit (AED) | Amount (AED) |",
+        "|---|---:|---:|---:|",
+        ...d.lines.map((l) => `| ${cell(l.description)} | ${grouped(l.quantity)} | ${aed(l.unit_fils)} | ${aed(l.amount_fils)} |`),
+        "",
+        "| Total | AED |",
+        "|---|---:|",
+        `| Subtotal | ${aed(d.subtotal_fils)} |`,
+        `| VAT ${d.vat_percent}% | ${aed(d.vat_fils)} |`,
+        `| **Total** | **${aed(d.total_fils)}** |`,
+        "",
+        `Plan: ${oneLine(d.plan.name)} (${d.plan.id}, plans ${d.plan.version}). Usage: ${grouped(d.usage.events)} events, ${grouped(d.usage.sessions)} sessions.`,
+        "",
+    ];
+    return out.join("\n");
+}
+// ---------------------------------------------------------------- Stripe webhook signature (§6)
+/** spec/billing.md §6: a `Stripe-Signature` header checked against the raw body. */
+export function stripeSignatureOk(header, rawBody, secret, nowSeconds, toleranceSeconds = 300) {
+    let t = null;
+    const v1 = [];
+    for (const part of header.split(",")) {
+        const i = part.indexOf("=");
+        if (i < 0)
+            continue;
+        const k = part.slice(0, i).trim();
+        const v = part.slice(i + 1).trim();
+        if (k === "t" && /^\d{1,12}$/.test(v))
+            t = Number(v);
+        else if (k === "v1" && /^[0-9a-f]{64}$/.test(v))
+            v1.push(v);
+    }
+    if (t === null || v1.length === 0 || Math.abs(nowSeconds - t) > toleranceSeconds)
+        return false;
+    const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
+    return v1.some((sig) => timingSafeEqual(Buffer.from(sig, "hex"), expected));
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};