Choose an example
All three use the same SDK, server adapter and prepared browser measurement. The rules in
lib/actions.mjs are sample customer policies that you can replace.
Run locally
Start a disposable local PostgreSQL database:heretic-next-postgres directory, in another terminal:
http://localhost:3300. Choose a local account and redeem WELCOME. The example records one completed allocation in PostgreSQL. Reloading reuses the measurement; redeeming the same resource on the same account is refused by the example policy. LIMITED has one allocation for concurrency testing.
The fixture’s ceremony is clearly labelled and collects no real device data. To exercise it, set HERETIC_FIXTURE_VERDICT=contradicted in .env, restart, and use a fresh browser session. Background preparation stays quiet; submitting an action opens the fixture. Set HERETIC_FIXTURE_DELAY_MS=5000 to exercise an early submission while measurement is pending.
npm run setup preserves existing allocations. Use a fresh disposable database for a fresh inventory. Stop the example database with docker stop heretic-example-postgres.
Application files
The catch-all route is small because the package handles the continuation protocol:
handler() and the provider implementation are included in the archive. Use them with the action contract rather than creating your own token parser or polling loop.
Connect production authentication
The local account chooser, session implementation and fixed test address are fixture-only. The example refuses production context until you replace itsappContext(request) function.
Return the current authenticated account ID, authenticated session ID and trusted request IP from your actual application. Registration uses a server-owned pending principal until the account exists; other actions must require an authenticated session. See the registration example. Do not take the account ID from the action body. Confirm which proxy supplies client addresses and which hops are trusted. Call client.status() after an authentication change so the SDK updates its opaque context.
Replace the example resource, eligibility and commit SQL with your existing application tables. All writes in commit use the supplied transaction client. Choose a shared resource key that covers the accounts competing for the same constrained resource.
The local registration flow creates a record without proving email ownership or signing in. The checkout flow stops at a payment outbox entry. Connect your authentication provider and payment processing, including delivery, reconciliation and cancellation, before using those examples in production.
Configure production
Set a verified real site key and server secret, an HTTPSAPP_ORIGIN, your PostgreSQL connection settings, and HERETIC_FIXTURE_MODE=false. Use the default Heretic API origin. Keep secrets on the server. Run the package migration and diagnostic command, then verify the browser’s CSP and preparation.
Use a pool sized for your deployment. Pending actions, evidence and receipts live in PostgreSQL, so another application instance can continue them after a restart. The in-process pool and key cache are not the source of action authorization.
Before enabling enforcement, test a normal action, duplicate request, account switch, expired measurement, declined/dismissed ceremony and concurrent inventory claim. Keep the example’s fixture mode restricted to loopback hosts. It must never authorize production traffic.