@zanii/blackbox 0.11.0 → 0.12.0

package/README.md

@@ -83,6 +83,10 @@ verifyAnswerCredential(credential, lines, bodies, packs); // { ok, problems }: t
 
 The same checks run offline as pure functions: `toolHallucinations`, `groundingFindings`, `factsIn`, `loadReferencePacks`, `answerRisk`, `detectorAccuracy`.
 
+## New in 0.12.0
+
+- Tax credit notes: `taxCreditNote` / `renderTaxCreditNote`, the document and printable copy behind gateway v0.14's `POST /v1/invoices/:number/credit-notes`.
+
 ## New in 0.11.0
 
 - Facts against the record compare currencies and units: `AED 500` in a tool result no longer grounds `USD 500` in the answer, nor `500 g` grounds `500 mg` (`currencyCodes`, `unitOf`). Dates written with an English or Arabic month (`3 March 2026`, `3 مارس 2026`) are facts too.

package/dist/billing/index.d.ts

@@ -95,5 +95,51 @@ export declare function taxInvoice(input: TaxInvoiceInput): {
 export type TaxInvoice = ReturnType<typeof taxInvoice>;
 /** spec/billing.md §5: the printable copy. */
 export declare function renderTaxInvoice(d: TaxInvoice): string;
+export interface TaxCreditNoteInput {
+    number: string;
+    issued_at: string;
+    /** The invoice it corrects, as issued. */
+    invoice: TaxInvoice;
+    reason: string;
+    /** What this note credits, before VAT. */
+    subtotal_fils: number;
+    /** What earlier notes on the invoice credited already. */
+    credited?: {
+        subtotal_fils: number;
+        vat_fils: number;
+    };
+}
+/** spec/billing.md §5a: a tax credit note. The note that credits what's left of the invoice takes
+ * the rest of its VAT exactly, so the notes never credit more VAT than was invoiced. */
+export declare function taxCreditNote(input: TaxCreditNoteInput): {
+    v: 1;
+    title: "Tax Credit Note";
+    number: string;
+    issued_at: string;
+    invoice: {
+        number: string;
+        issued_at: string;
+    };
+    reason: string;
+    supplier: {
+        name: string;
+        address: string;
+        trn: string;
+    };
+    customer: {
+        legal_name: string;
+        address: string;
+        trn: string | null;
+    };
+    currency: "AED";
+    subtotal_fils: number;
+    vat_percent: number;
+    vat_fils: number;
+    total_fils: number;
+    total_aed: string;
+};
+export type TaxCreditNote = ReturnType<typeof taxCreditNote>;
+/** spec/billing.md §5a: the printable copy. */
+export declare function renderTaxCreditNote(d: TaxCreditNote): string;
 /** spec/billing.md §6: a `Stripe-Signature` header checked against the raw body. */
 export declare function stripeSignatureOk(header: string, rawBody: Uint8Array, secret: string, nowSeconds: number, toleranceSeconds?: number): boolean;

package/dist/billing/index.js

@@ -151,6 +151,64 @@ export function renderTaxInvoice(d) {
     ];
     return out.join("\n");
 }
+/** spec/billing.md §5a: a tax credit note. The note that credits what's left of the invoice takes
+ * the rest of its VAT exactly, so the notes never credit more VAT than was invoiced. */
+export function taxCreditNote(input) {
+    const inv = input.invoice;
+    const before = input.credited ?? { subtotal_fils: 0, vat_fils: 0 };
+    const last = input.subtotal_fils === inv.subtotal_fils - before.subtotal_fils;
+    const vat = last
+        ? inv.vat_fils - before.vat_fils
+        : Math.floor((input.subtotal_fils * inv.vat_percent + 50) / 100);
+    return {
+        v: 1,
+        title: "Tax Credit Note",
+        number: input.number,
+        issued_at: input.issued_at,
+        invoice: { number: inv.number, issued_at: inv.issued_at },
+        reason: input.reason,
+        supplier: inv.supplier,
+        customer: inv.customer,
+        currency: "AED",
+        subtotal_fils: input.subtotal_fils,
+        vat_percent: inv.vat_percent,
+        vat_fils: vat,
+        total_fils: input.subtotal_fils + vat,
+        total_aed: formatAed(input.subtotal_fils + vat),
+    };
+}
+/** spec/billing.md §5a: the printable copy. */
+export function renderTaxCreditNote(d) {
+    return [
+        "# Tax Credit Note",
+        "",
+        "| Field | Value |",
+        "|---|---|",
+        `| Credit note number | ${cell(d.number)} |`,
+        `| Date of issue | ${d.issued_at} |`,
+        `| Corrects invoice | ${cell(d.invoice.number)} of ${d.invoice.issued_at} |`,
+        `| Reason | ${cell(oneLine(d.reason))} |`,
+        "",
+        "## 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"}`,
+        "",
+        "| Credited | AED |",
+        "|---|---:|",
+        `| Subtotal | ${aed(d.subtotal_fils)} |`,
+        `| VAT ${d.vat_percent}% | ${aed(d.vat_fils)} |`,
+        `| **Total credited** | **${aed(d.total_fils)}** |`,
+        "",
+    ].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) {

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { archiveParquet } from "./archive/parquet.ts";
 export { type Attestation, attest, isReadOnly, normalise, parseCommand } from "./attest/index.ts";
 export { type AuthorityFinding, authorityAt, authorityTimeline, automationSurprise, type Mode as AuthorityMode, type Span as AuthoritySpan, } from "./authority/index.ts";
 export { badgeSvg, RECORD_STATES, type RecordState, recordBadge, recordState, } from "./badge/index.ts";
-export { type Invoice, type InvoiceLine, invoice, loadPlans, type Plan, type Plans, renderTaxInvoice, stripeSignatureOk, type TaxInvoice, type TaxInvoiceInput, taxInvoice, } from "./billing/index.ts";
+export { type Invoice, type InvoiceLine, invoice, loadPlans, type Plan, type Plans, renderTaxCreditNote, renderTaxInvoice, stripeSignatureOk, type TaxCreditNote, type TaxCreditNoteInput, type TaxInvoice, type TaxInvoiceInput, taxCreditNote, taxInvoice, } from "./billing/index.ts";
 export { type AgentIdentity, checkAgent, sessionBom } from "./bom/index.ts";
 export { BlackboxApiError, type Client, type ClientOptions, client, type SessionQuery, } from "./client/index.ts";
 export { ART12_MIN_RETENTION_DAYS, type Art12Check, type Art12Report, art12Check, } from "./compliance/art12.ts";

package/dist/index.js

@@ -13,7 +13,7 @@ export { archiveParquet } from "./archive/parquet.js";
 export { attest, isReadOnly, normalise, parseCommand } from "./attest/index.js";
 export { authorityAt, authorityTimeline, automationSurprise, } from "./authority/index.js";
 export { badgeSvg, RECORD_STATES, recordBadge, recordState, } from "./badge/index.js";
-export { invoice, loadPlans, renderTaxInvoice, stripeSignatureOk, taxInvoice, } from "./billing/index.js";
+export { invoice, loadPlans, renderTaxCreditNote, renderTaxInvoice, stripeSignatureOk, taxCreditNote, taxInvoice, } from "./billing/index.js";
 export { checkAgent, sessionBom } from "./bom/index.js";
 export { BlackboxApiError, client, } from "./client/index.js";
 export { ART12_MIN_RETENTION_DAYS, art12Check, } from "./compliance/art12.js";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.11.0";
+export declare const VERSION = "0.12.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // The SDK version, on its own so the CLI can print it without loading the whole SDK.
-export const VERSION = "0.11.0";
+export const VERSION = "0.12.0";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zanii/blackbox",
   "license": "Apache-2.0",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The flight recorder for AI agents: sessions, a zero-loss spool, framework hooks, approvals, and offline verification of the gateway's hash-chained record.",
   "keywords": [
     "ai-agents",