Open-source package · @armalo/receipt-schema
Verify a receipt without trusting Armalo's code.
A Proof-of-Outcome receipt asserts one thing: a real payment-provider event confirmed that a piece of work produced economic value, of a given amount and currency, observed at a given time. Nothing more. This package is a standalone, versioned schema and validator for that public format, no dependency on any Armalo-internal type or package, so you can check a receipt you were handed against a stable, versioned shape.
Availability
Not yet published to the npm registry: the package is built, tested, and reviewed against its packed form; this guide's code is copied from that check. There is no install command yet because there is nothing on the registry to install.
Validate a receipt
import {
isProofOfOutcomeReceiptPublicV0_1,
parseProofOfOutcomeReceiptPublicV0_1,
proofOfOutcomeReceiptPublicV0_1JsonSchema,
} from "@armalo/receipt-schema";
// Non-throwing check.
if (isProofOfOutcomeReceiptPublicV0_1(receiptFromSomewhere)) {
// receiptFromSomewhere is now typed.
}
// Throws on an invalid value.
const receipt = parseProofOfOutcomeReceiptPublicV0_1(receiptFromSomewhere);
// Plain JSON Schema: for a verifier that wants to validate without a zod
// dependency, e.g. with ajv, or in a non-JS toolchain.
const jsonSchema = proofOfOutcomeReceiptPublicV0_1JsonSchema();Fields, v0.1
Strict: an unrecognized extra field fails validation.
| Field | Type | What it means |
|---|---|---|
| schemaVersion | "0.1.0" (literal) | The format version being validated against. |
| amountMinorUnits | non-negative integer | The economic value, in minor currency units (e.g. cents). |
| currency | 3-letter uppercase ISO 4217 | Required to interpret amountMinorUnits. |
| attestedBy | "payment_provider" (literal) | The class of evidence backing the receipt, a real payment-provider event, never self-reported. |
| observedAt | ISO 8601 datetime | When the underlying event was recorded. |
Versioning
v0.1 validation is strict and version-exact: a receipt is checked against the schema version it declares in schemaVersion, and an unrecognized field fails validation, the same rule the Fields section states. The 0.1.x line evolves additively: a future field is always optional, and it ships as a new published minor schema version alongside this one, never as a silent change to v0.1's own schema. A verifier written against 0.1.0 rejects a receipt whose declared version it doesn't recognize, rather than guessing at fields it doesn't fully understand. A breaking change, a field removed, or an existing field's meaning changed, ships as a new major format published alongside this one.
License
Apache-2.0. Back to open-source packages.