@tallypay/core

Framework-agnostic primitives for x402 payment flows and TallyPay lifecycle tracing. Zero runtime dependencies beyond the Web/Node globals used (fetch, crypto).

Install

npm install @tallypay/core

What’s included

| Export | Description | |--------|-------------| | generateTraceId() | Time-sortable trace ID (ULID-style) for correlating events across client and server. | | createEventEmitter(config) | Batched, non-blocking emitter that POSTs lifecycle events to the TallyPay collector. Drops events if the collector is unreachable—observability never blocks payments. | | wrapFetch(fetch, config) | Wraps fetch to handle HTTP 402: parse payment-required, call your signer, retry with payment-signature. | | Types | PaymentRequired, PaymentRequirements, PaymentPayload, PaymentResponse (aligned with the x402 shape you use in headers/body). | | Lifecycle types | PaymentLifecycleEvent, PaymentLifecycleEventType (402_ISSUED, 402_RECEIVED, PAYMENT_SIGNED, …). |

Trace IDs

import { generateTraceId } from "@tallypay/core";

const traceId = generateTraceId();

Event emitter (server or Node)

import { createEventEmitter } from "@tallypay/core";

const emitter = createEventEmitter({
  apiKey: "tp_live_...", // from TallyPay dashboard
  collectorUrl: "https://collector.tallypay.dev", // optional override
});

emitter.emit({
  traceId,
  eventType: "VERIFY_REQUESTED",
  source: "server",
  metadata: { endpoint: "/api/premium" },
});

await emitter.flush();

Wrapped fetch (browser or Node 18+)

import { wrapFetch } from "@tallypay/core";

const paymentFetch = wrapFetch(fetch, {
  onPaymentRequired: async (paymentRequired, url) => {
    // Return the value for the `payment-signature` header (base64 payload per your stack).
    return signAndEncodePayment(paymentRequired, url);
  },
  onLifecycleEvent: (eventType, metadata) => {
    console.debug(eventType, metadata);
  },
});

const res = await paymentFetch("https://api.example.com/premium");

Testing

From the monorepo root:

pnpm --filter @tallypay/core test

Or from this package: pnpm test (Vitest).

License

MIT. Source code will be published on GitHub at launch; until then see tallypay.dev.

Links

• TallyPay
• Documentation (when live)