@tuppence/node 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,373 @@
+import type { components, paths } from "./generated/api.js";
+/** Types generated from the API's OpenAPI document — never hand-written, so they cannot drift. */
+type S = components["schemas"];
+export type { components, paths };
+export type Account = S["AccountModel"];
+/** Every price the account pays now — the list's, or one agreed with Tuppence (61-12). */
+export type AccountPricing = S["AccountPricingModel"];
+export type Payment = S["PaymentModel"];
+export type Refund = S["RefundModel"];
+export type Customer = S["CustomerModel"];
+export type CustomerPreference = S["CustomerPreferenceModel"];
+export type CustomerPreferenceList = S["CustomerPreferenceList"];
+export type PaymentLink = S["PaymentLinkModel"];
+export type Plan = S["PlanModel"];
+export type Subscription = S["SubscriptionModel"];
+/** A discount on subscriptions (17-10). */
+export type Coupon = S["CouponModel"];
+/** A code a customer types for a coupon (17-10). */
+export type PromoCode = S["PromoCodeModel"];
+/** What a subscription charge was for (17-13). */
+export type Invoice = S["InvoiceModel"];
+/** A one-hour link into the customer portal (17-11). */
+export type PortalSession = S["PortalSessionModel"];
+/** What changing plan would cost, before it is charged. */
+export type ProrationPreview = S["ProrationPreviewModel"];
+export type Event = S["EventModel"];
+/**
+ * Any of the store's webhook events (94-06), discriminated by `type`: after
+ * `if (event.type === "order.created")`, `event.data.object` is an `Order`.
+ */
+export type StoreEvent = S["StoreEvent"];
+/** One store event by its type: `StoreEventOf<"store.site_published">`. */
+export type StoreEventOf<T extends StoreEvent["type"]> = Extract<StoreEvent, {
+    type: T;
+}>;
+/**
+ * Any of Tuppence Events' webhook events (114-12), discriminated by `type`: after
+ * `if (event.type === "ticket_order.paid")`, `event.data.object` is the ticket order.
+ */
+export type TicketingEvent = S["TicketingEvent"];
+/** One Tuppence Events event by its type: `TicketingEventOf<"ticket.issued">`. */
+export type TicketingEventOf<T extends TicketingEvent["type"]> = Extract<TicketingEvent, {
+    type: T;
+}>;
+export type WebhookEndpoint = S["WebhookEndpointModel"];
+/** A domain your own checkout runs on, registered so Apple Pay and Google Pay show there (09-13). */
+export type PaymentMethodDomain = S["PaymentMethodDomainModel"];
+export type Balance = S["BalanceModel"];
+export type Payout = S["PayoutModel"];
+/** What a payout covered, from the books: the balance before, its activity, the balance after. */
+export type PayoutReconciliation = S["PayoutReconciliationModel"];
+/**
+ * What an instant move would cost before it is made (57-03): to the bank (the default) or the
+ * card balance, when it arrives, and — when it can't be made — the `reason`, `message`, `fix_url`
+ * and `available_from`.
+ */
+export type InstantPayoutQuote = S["InstantPayoutQuoteModel"];
+/** Where an instant move can go: `bank`, or `card_balance` (UK only). */
+export type InstantPayoutDestination = InstantPayoutQuote["destination"];
+/** The schedule, the bank, the limits — and `instant_payouts`, with each destination's answer. */
+export type PayoutSettings = S["PayoutSettingsModel"];
+/** Next-day payouts (UK, 61-06): whether they can be switched on now, and what is on. */
+export type NextDayPayouts = S["NextDayModel"];
+export type Dispute = S["DisputeModel"];
+export type Meter = S["MeterModel"];
+export type CreditBalance = S["CreditBalanceModel"];
+/** A balance as listed: who holds it, and the totals topped up and used. */
+export type CreditHolder = S["CreditHolderModel"];
+export type CreditTopup = S["CreditTopupModel"];
+export type UsageEvent = S["UsageEventModel"];
+export type UsageSummary = S["UsageSummaryModel"];
+/** Cards for agents (M14). */
+export type Agent = S["AgentModel"];
+/** What's normal for an agent's spending, and its latest unusual purchases (19-07). */
+export type AgentProfile = S["AgentProfileModel"];
+export type Cardholder = S["CardholderModel"];
+export type Card = S["CardModel"];
+export type SpendPolicy = S["SpendPolicyModel"];
+export type Approval = S["ApprovalModel"];
+export type CardAuthorization = S["CardAuthorizationModel"];
+export type CardTransaction = S["CardTransactionModel"];
+/** A virtual card's number, CVC and expiry (14-22). Never keep it. */
+export type CardDetails = S["CardDetailsModel"];
+/** A dispute of a card purchase (53-05): a draft until submitted. */
+export type CardDispute = S["CardDisputeModel"];
+/** A dispute as filed or submitted — with `other_recent_purchases` to dispute too. */
+export type CardDisputeFiled = S["CardDisputeFiledModel"];
+/** Issuing's limits for the account's trust tier (53-03). */
+export type IssuingLimits = S["IssuingLimitsModel"];
+/** What the cards can spend now (`spendable`), and where it lives (`spends_from`). */
+export type IssuingBalance = S["IssuingBalanceModel"];
+/** Money on its way to the card balance: what it waits on (`delay`), and when it lands. */
+export type IssuingTopup = S["IssuingTopupModel"];
+/** A hosted top-up page (54-18): `url` is shown only when it is made. */
+export type IssuingTopupLink = S["IssuingTopupLinkModel"];
+/** One way to top up the card balance: open or not (and why), its fee, total and timing (54-07). */
+export type IssuingTopupOption = S["IssuingTopupOptionModel"];
+/** Every way to top up the card balance, for an amount (or rates and timings without one). */
+export type IssuingTopupOptions = S["IssuingTopupOptionsList"];
+/** The auto top-up rule (54-15): below `threshold`, top up by `amount`; paused after a failure. */
+export type IssuingAutoTopup = S["IssuingAutoTopupModel"];
+/** The business's own card, saved for top-ups and charged with nobody there (54-15). */
+export type IssuingTopupPaymentMethod = S["IssuingTopupPaymentMethodModel"];
+/** What a person lets an agent top the cards up with, without asking each time (54-15, E13). */
+export type AgentFundingMandate = S["AgentFundingMandateModel"];
+/** The card balance's own bank details, by region. */
+export type FundingInstructions = S["FundingInstructionsModel"];
+/** Where the business is with Bacs Direct Debit, and what to do next (59-11). */
+export type DirectDebit = S["DirectDebitModel"];
+/** An application for Bacs Direct Debit, and what Tuppence decided (59-11). */
+export type DirectDebitApplication = S["DirectDebitApplicationModel"];
+/** Bookings (M23): where, what, who — and when a client could come. */
+export type Location = S["LocationModel"];
+/** Whether a mobile location covers a client's postcode or coordinates. */
+export type Coverage = S["CoverageModel"];
+/** A country pack (plan 31-19): what differs between countries at the till, as data. */
+export type CountryPack = S["CountryPackModel"];
+export type ServiceCategory = S["ServiceCategoryModel"];
+export type Service = S["ServiceModel"];
+export type ServiceVariant = S["ServiceVariantModel"];
+export type ServiceAddon = S["ServiceAddonModel"];
+/** What one service would take and cost, as chosen. */
+export type ServiceQuote = S["ServiceQuoteModel"];
+export type StaffMember = S["StaffMemberModel"];
+export type Schedule = S["ScheduleModel"];
+export type ScheduleException = S["ScheduleExceptionModel"];
+export type WorkingHours = S["WorkingHoursModel"];
+export type Resource = S["ResourceModel"];
+export type ResourceCheck = S["ResourceCheckModel"];
+export type BookingPolicy = S["BookingPolicyModel"];
+/** The policy's client-facing words, rendered. */
+export type PolicyRender = S["PolicyRenderModel"];
+export type BookingPage = S["BookingPageModel"];
+export type BookingPagePreviewToken = S["BookingPagePreviewTokenModel"];
+/** The starts a client could book, and each one's people and resources. */
+export type Availability = S["AvailabilityModel"];
+export type AvailabilitySlot = S["AvailabilitySlotModel"];
+export type Booking = S["BookingModel"];
+export type ClassSession = S["ClassSessionModel"];
+export type BookingSeries = S["BookingSeriesModel"];
+export type WaitlistEntry = S["BookingWaitlistEntryModel"];
+/** A customer's review of a booking or an order (M91). */
+export type Review = S["ReviewModel"];
+export type ReviewSummary = S["ReviewSummaryModel"];
+/** One change an assistant or a person made to the store, with its undo (92-01). */
+export type ChangeSet = S["ChangeSetModel"];
+/** A store's move from another platform (93-01). */
+export type StoreImport = S["StoreImportModel"];
+export type StockMirror = S["StockMirrorModel"];
+export type StoreImportSavings = S["StoreImportSavingsModel"];
+/** One of the store's operator jobs (M92). */
+export type AssistantJob = S["AssistantJobModel"];
+export type AssistantJobRun = S["AssistantJobRunModel"];
+export type AssistantJobBrief = S["AssistantJobBriefModel"];
+export type AssistantJobExample = S["AssistantJobExampleModel"];
+/** Lists answered whole, with no cursor (no `has_more`). */
+export type AssistantJobList = S["AssistantJobList"];
+export type AssistantJobBriefList = S["AssistantJobBriefList"];
+export type AssistantJobExampleList = S["AssistantJobExampleList"];
+/** The store's daily brief (M92). */
+export type StoreBrief = S["StoreBriefModel"];
+export type ChannelReport = S["ChannelReportModel"];
+/** The business's one store site (85-02): its brand, navigation, address and settings. */
+export type Site = S["SiteModel"];
+export type SiteDomain = S["SiteDomainModel"];
+/** A store's domain moving from its old platform (93-07). */
+export type DomainSwitch = S["DomainSwitchModel"];
+export type SiteFonts = S["SiteFontsModel"];
+export type SitePage = S["SitePageModel"];
+/** A published (or scheduled) version of the site, which a revert brings back. */
+export type SiteVersion = S["SiteVersionModel"];
+export type SitePreviewToken = S["SitePreviewTokenModel"];
+export type SiteRedirect = S["SiteRedirectModel"];
+export type SiteNotFoundList = S["SiteNotFoundList"];
+export type SiteTranslationList = S["SiteTranslationList"];
+export type SiteTranslationResult = S["SiteTranslationResult"];
+export type SiteRenderContext = S["SiteRenderContextModel"];
+/** What stands between the store and going live, each with its fix. */
+export type SiteReadiness = S["SiteReadinessModel"];
+export type SellingAbroad = S["SellingAbroadModel"];
+export type StoreChecklist = S["StoreChecklistModel"];
+export type ReturnPolicy = S["ReturnPolicyModel"];
+/** A design agent run (95-05): what it made, its checks, its cost and its change set. */
+export type DesignRun = S["DesignRunModel"];
+/** A custom section in the site's library (M95), with its versions and the pages using it. */
+export type SiteSection = S["SiteSectionModel"];
+export type SiteSectionWrite = S["SiteSectionWriteModel"];
+export type SiteSectionVersion = S["SiteSectionVersionModel"];
+export type SiteSectionList = S["SiteSectionList"];
+/** A code section: a document in a sealed frame, with a fallback section (S25). */
+export type SiteCodeSection = S["SiteCodeSectionModel"];
+export type SiteCodeSectionList = S["SiteCodeSectionList"];
+export type SectionCheck = S["SectionCheckModel"];
+/** The site's design as a file: the look, the sections' source and the draft pages' layouts. */
+export type SiteDesignFile = S["SiteDesignFileModel"];
+export type SiteDesignImport = S["SiteDesignImportModel"];
+/** A change to the store proposed from a sentence, as a change set awaiting approval (86). */
+export type StoreChange = S["StoreChangeModel"];
+/** The store builder's proposal (86-01): stages, cost and its items in review order. */
+export type StoreProposal = S["StoreProposalModel"];
+export type StoreProposalList = S["StoreProposalListModel"];
+export type ProposalItem = S["ProposalItemModel"];
+export type ProposalPreview = S["ProposalPreviewModel"];
+export type ProposalAcceptAll = S["AcceptAllModel"];
+export type ProposalPublish = S["PublishModel"];
+/** A product from a photo (86-11): its steps, cost, and once ready its draft and guesses. */
+export type StoreSnap = S["StoreSnapModel"];
+export type StoreSettings = S["StoreSettingsModel"];
+/** A parcel's way to the shopper (M87): picked, packed, labelled, shipped, or collected. */
+export type Fulfilment = S["FulfilmentModel"];
+export type LabelBatch = S["LabelBatchModel"];
+export type LabelRate = S["LabelRateModel"];
+export type PackingSlip = S["PackingSlipModel"];
+/** A return or exchange (87-09), from the request to the refund. */
+export type Return = S["ReturnModel"];
+export type ReturnScan = S["ReturnScanModel"];
+export type WayBackOptionList = S["WayBackOptionList"];
+/** The day's parcels handed to a carrier, with its manifest (87-10). */
+export type ShippingManifest = S["ShippingManifestModel"];
+export type CloseDay = S["CloseDayModel"];
+export type CarrierPickup = S["CarrierPickupModel"];
+/** Postage owed for labels bought from the balance, and the credit limit (87-03). */
+export type Postage = S["PostageModel"];
+/** Your own carrier account for labels (87-03b), with the carriers and fields it can take. */
+export type CarrierAccount = S["CarrierAccountModel"];
+export type CarrierAccountList = S["CarrierAccountListModel"];
+/** What delivery costs where (87-01): zones, each with its rates, for a set of products. */
+export type ShippingProfile = S["ShippingProfileModel"];
+export type ShippingDeleted = S["ShippingDeletedModel"];
+export type EstimatedWeight = S["EstimatedWeightModel"];
+export type DeliveryPreview = S["DeliveryPreviewModel"];
+export type ShippingPackage = S["ShippingPackageModel"];
+export type ShippingService = S["ShippingServiceModel"];
+/** A photo, video or document in the media library (85-04). */
+export type MediaAsset = S["MediaAssetModel"];
+export type MediaUpload = S["MediaUploadModel"];
+/** A file a digital product delivers (88-12). */
+export type DigitalAsset = S["DigitalAssetModel"];
+export type ImageStudio = S["ImageStudioModel"];
+export type ImageEdit = S["ImageEditModel"];
+/** A store collection (85-05): chosen products, or rules that pick them. */
+export type Collection = S["CollectionModel"];
+/** A product the till and the store sell, with its web fields. */
+export type Product = S["ProductModel"];
+export type ProductVariant = S["ProductVariantModel"];
+export type ProductLookup = S["ProductLookupModel"];
+export type ProductBulkUpdate = S["ProductBulkUpdateModel"];
+/** What the product still needs to go online, each with its fix (85-03). */
+export type OnlineChecklist = S["OnlineChecklistModel"];
+export type LicenceKeyPool = S["LicenceKeyPoolModel"];
+export type ReturnInsightList = S["ReturnInsightList"];
+/** An order: one list for the till, the store and every channel, with its `source`. */
+export type Order = S["OrderModel"];
+export type OrderEvent = S["OrderEventModel"];
+export type OrderSync = S["OrderSyncModel"];
+export type Tender = S["TenderModel"];
+export type OrderTender = S["OrderTenderModel"];
+export type OrderReturn = S["OrderReturnModel"];
+export type ReturnPreview = S["ReturnPreviewModel"];
+/** The order's lines, totals, fulfilment, payments and contact details. */
+export type OrderDetails = S["OrderDetailsModel"];
+export type OrderAddressChanged = S["OrderAddressChangedModel"];
+export type OrderConfirmationSent = S["OrderConfirmationSentModel"];
+export type OrderEReceipt = S["OrderEReceiptModel"];
+export type OrderReceipt = S["OrderReceiptModel"];
+/** The store's policy pages (88-02): terms, privacy, returns, delivery, each versioned. */
+export type SitePolicy = S["SitePolicyModel"];
+export type SitePolicyList = S["SitePolicyList"];
+export type SitePolicyVersion = S["SitePolicyVersionModel"];
+export type SitePolicyVersionList = S["SitePolicyVersionList"];
+/** A shopper's request to see or erase their data (88-05). */
+export type StorePrivacyRequest = S["StorePrivacyRequestModel"];
+/** The business's own say over a product's or collection's recommendations (91-03). */
+export type RecommendationRule = S["RecommendationRuleModel"];
+/** Subscribe and save on a product (91-08). */
+export type SubscriptionOffer = S["SubscriptionOfferModel"];
+/** A store campaign, its preview and its results (91-09b). */
+export type StoreCampaign = S["StoreCampaignModel"];
+export type StoreCampaignPreview = S["StoreCampaignPreviewModel"];
+export type StoreCampaignResults = S["StoreCampaignResultsModel"];
+/** A store flow: on or off, its words, paused or not, and its last 30 days (91-17). */
+export type StoreFlow = S["StoreFlowModel"];
+/** A connection to another place the store sells: a marketplace, a social shop, a feed (M90). */
+export type SalesChannel = S["SalesChannelModel"];
+/** A variant's place on a sales channel (M90). */
+export type Listing = S["ListingModel"];
+/** A store inbox conversation, with its messages on retrieve (91-10). */
+export type StoreThread = S["StoreThreadModel"];
+export type StoreThreadTemplates = S["StoreThreadTemplates"];
+/** A store's own sending domain and the records to add (91-13). */
+export type MerchantSendingDomain = S["MerchantSendingDomainModel"];
+export type MerchantSendingDomainSuggestion = S["MerchantSendingDomainSuggestion"];
+/** A limited release with a fair queue (85-12). */
+export type Drop = S["DropModel"];
+export type DropQueue = S["DropQueueModel"];
+/** Everything that moved a balance — a platform's Connect balance with `balance: "connect"`. */
+export type BalanceTransaction = S["BalanceTransactionModel"];
+/**
+ * Tuppence Connect (M40–M43): a platform's connected accounts, onboarding them, and the money
+ * between them. A connected account is a full Tuppence account: act as one with
+ * `{ tuppenceAccount }` on any request, or `tuppence.as("acct_…")`.
+ */
+export type ConnectedAccount = S["ConnectAccountModel"];
+export type ConnectedAccountDeleted = S["ConnectAccountDeletedModel"];
+export type ConnectedAccountStore = S["ConnectStoreModel"];
+/** One of the people behind a connected account: names and roles, never the details given. */
+export type Person = S["PersonModel"];
+export type PersonDeleted = S["PersonDeletedModel"];
+/** A person's identity check: the Stripe Identity session to send them to. */
+export type PersonIdentityCheck = S["PersonIdentityCheckModel"];
+/** A connected account's bank account, for its payouts. */
+export type ExternalAccount = S["ExternalAccountModel"];
+export type ExternalAccountDeleted = S["ExternalAccountDeletedModel"];
+export type Capability = S["CapabilityModel"];
+/** A URL, good once and for five minutes, onto the hosted onboarding in your branding. */
+export type AccountLink = S["AccountLinkModel"];
+/** A file uploaded for a connected account's verification (the `file` object). */
+export type FileUpload = S["FileModel"];
+export type ApplicationFee = S["ApplicationFeeModel"];
+export type FeeRefund = S["FeeRefundModel"];
+export type Transfer = S["TransferModel"];
+export type TransferReversal = S["TransferReversalModel"];
+export type TicketedEvent = S["TicketedEventModel"];
+export type TicketType = S["TicketTypeModel"];
+export type TicketOrder = S["TicketOrderModel"];
+/** A refund of a ticket order: the order, every ticket (refunded ones `void`) and the refund. */
+export type TicketOrderRefund = S["TicketOrderRefundModel"];
+export type Ticket = S["TicketModel"];
+export type TicketPromoCode = S["TicketPromoCodeModel"];
+/** Ticket money held until after a date, and when it is released. */
+export type TicketFundsHold = S["TicketFundsHoldModel"];
+export type TicketSalesReport = S["TicketSalesReportModel"];
+export type TicketSettlement = S["TicketSettlementModel"];
+/** A scan at the door: `admitted` the first time, `duplicate` after (117). */
+export type CheckIn = S["CheckInModel"];
+export type CheckInManifest = S["CheckInManifestModel"];
+export type CheckInSync = S["CheckInSyncModel"];
+/** An event a door can check guests in for: one with a date not yet over (116-05). */
+export type CheckInEvent = S["CheckInEventModel"];
+/** An event's door, live: tickets in by gate and by type (116-07). */
+export type CheckInCounts = S["CheckInCountsModel"];
+/** A ticket given or resold to someone else (117-06, 117-08). */
+export type TicketTransfer = S["TicketTransferModel"];
+export type TicketTransferResult = S["TicketTransferResultModel"];
+/** A place on a sold-out ticket type's waitlist (117-07). */
+export type EventWaitlistEntry = S["EventWaitlistEntryModel"];
+/** A partner's commission on an order made with an affiliate code (118-03). */
+export type TicketCommission = S["TicketCommissionModel"];
+/** A message to an event's attendees, by email, text or WhatsApp (118-04). */
+export type EventMessage = S["EventMessageModel"];
+/** The account's settings for every event: its ad pixels (118-06). */
+export type TicketingSettings = S["TicketingSettingsModel"];
+/** A page of a list: `data`, and whether there is more after it. */
+export type List<T> = {
+    object: "list";
+    data: T[];
+    has_more: boolean;
+};
+/** Cursor paging, the same on every list. */
+export type ListParams = {
+    limit?: number;
+    starting_after?: string;
+    ending_before?: string;
+};
+type JsonBody<O> = O extends {
+    requestBody?: infer R;
+} ? NonNullable<R> extends {
+    content: {
+        "application/json": infer B;
+    };
+} ? B : never : never;
+/** The JSON body an operation takes — e.g. `Body<"/v1/payments", "post">`. */
+export type Body<P extends keyof paths, M extends keyof paths[P]> = JsonBody<paths[P][M]>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/webhooks.d.ts

@@ -0,0 +1,25 @@
+import type { Event } from "./types.js";
+export declare const SIGNATURE_HEADER = "Tuppence-Signature";
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Checks a webhook really came from Tuppence, then parses it.
+ *
+ *   const event = tuppence.webhooks.constructEvent(rawBody, req.headers["tuppence-signature"], secret);
+ *
+ * `payload` must be the RAW body exactly as received (a Buffer or string) — re-serialised JSON
+ * will not match. `Tuppence-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]`: v1 is HMAC-SHA256
+ * over `"<t>.<body>"`; during a secret rotation there are two v1s and either may match.
+ *
+ * An endpoint for the store's events can say so, and `type` narrows `data.object` (94-06):
+ *
+ *   const event = constructEvent<StoreEvent>(rawBody, header, secret);
+ *   if (event.type === "order.created") ship(event.data.object.lines);
+ */
+export declare function constructEvent<E extends {
+    type: string;
+} = Event>(payload: string | Buffer, header: string | string[] | undefined | null, secret: string, options?: {
+    toleranceSeconds?: number;
+    nowSeconds?: number;
+}): E;
+/** Signs a payload the way Tuppence does — for testing your own webhook handler. */
+export declare function generateTestHeader(payload: string, secret: string, timestamp?: number): string;

package/dist/webhooks.js

@@ -0,0 +1,56 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { SignatureVerificationError } from "./errors.js";
+export const SIGNATURE_HEADER = "Tuppence-Signature";
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+const hmac = (secret, timestamp, payload) => createHmac("sha256", secret).update(`${timestamp}.${payload}`, "utf8").digest("hex");
+/**
+ * Checks a webhook really came from Tuppence, then parses it.
+ *
+ *   const event = tuppence.webhooks.constructEvent(rawBody, req.headers["tuppence-signature"], secret);
+ *
+ * `payload` must be the RAW body exactly as received (a Buffer or string) — re-serialised JSON
+ * will not match. `Tuppence-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]`: v1 is HMAC-SHA256
+ * over `"<t>.<body>"`; during a secret rotation there are two v1s and either may match.
+ *
+ * An endpoint for the store's events can say so, and `type` narrows `data.object` (94-06):
+ *
+ *   const event = constructEvent<StoreEvent>(rawBody, header, secret);
+ *   if (event.type === "order.created") ship(event.data.object.lines);
+ */
+export function constructEvent(payload, header, secret, options = {}) {
+    const body = typeof payload === "string" ? payload : payload.toString("utf8");
+    const value = Array.isArray(header) ? header[0] : header;
+    if (!value) {
+        throw new SignatureVerificationError("malformed_header", `No ${SIGNATURE_HEADER} header.`);
+    }
+    let timestamp;
+    const signatures = [];
+    for (const part of value.split(",")) {
+        const index = part.indexOf("=");
+        if (index < 1)
+            throw new SignatureVerificationError("malformed_header", "The signature header is malformed.");
+        const key = part.slice(0, index).trim();
+        const v = part.slice(index + 1).trim();
+        if (key === "t" && /^\d{1,12}$/.test(v))
+            timestamp = Number(v);
+        else if (key === "v1")
+            signatures.push(v);
+    }
+    if (timestamp === undefined || signatures.length === 0) {
+        throw new SignatureVerificationError("malformed_header", "The signature header is malformed.");
+    }
+    const expected = Buffer.from(hmac(secret, timestamp, body), "hex");
+    const matched = signatures.some((candidate) => /^[0-9a-f]{64}$/i.test(candidate) && timingSafeEqual(Buffer.from(candidate, "hex"), expected));
+    if (!matched) {
+        throw new SignatureVerificationError("no_matching_signature", "The signature does not match: check the endpoint's signing secret, and that you passed the raw body.");
+    }
+    const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestamp) > (options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS)) {
+        throw new SignatureVerificationError("timestamp_out_of_tolerance", "The webhook's timestamp is too old (or your clock is wrong): refusing a possible replay.");
+    }
+    return JSON.parse(body);
+}
+/** Signs a payload the way Tuppence does — for testing your own webhook handler. */
+export function generateTestHeader(payload, secret, timestamp = Math.floor(Date.now() / 1000)) {
+    return `t=${timestamp},v1=${hmac(secret, timestamp, payload)}`;
+}

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@tuppence/node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The Tuppence API for Node.js — payments for developers and AI agents.",
+  "license": "MIT",
+  "homepage": "https://docs.tuppence.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZenningAI/tuppence.git",
+    "directory": "packages/node"
+  },
+  "bugs": "https://github.com/ZenningAI/tuppence/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "esbuild": "^0.25.12",
+    "openapi-typescript": "^7.13.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && mkdir -p dist/generated && cp src/generated/api.d.ts dist/generated/ && esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --outfile=dist/index.cjs --log-level=warning",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "types:generate": "openapi-typescript ../../apps/api/openapi.public.json -o src/generated/api.d.ts",
+    "types:check": "openapi-typescript ../../apps/api/openapi.public.json -o /tmp/tuppence-node-api.check.d.ts && diff -q /tmp/tuppence-node-api.check.d.ts src/generated/api.d.ts"
+  }
 }