pithy payments

Deploy the reconciliation Workflow that keeps stored purchases agreeing with the stores, and run a pass on demand. This is the provisioning half of the payments capability.

Synopsis

pithy payments provision [--worker <name>] [--json]
pithy payments reconcile [--env <environment>] [--subject <holder>] [--rail <rail>] [--worker <name>] [--dry-run] [--json]

Both subcommands need a Cloudflare account. provision deploys a Worker per managed environment; reconcile dispatches a Workflow into an already-deployed one. Neither has a local path.

Flags

FlagApplies toDefaultPurpose
--worker <name>provisionthe project’s only WorkerThe app Worker whose payments(...) catalog is deployed, and whose wrangler.jsonc carries the per-environment DB binding and receives the PAYMENTS_RECONCILE binding. Required when a project has several
--worker <name>reconcilethe shared hostRun the pass in this Worker’s own reconcile host, <project>-<env>-<worker>---payments-reconcile, when it owns what the host binds. Any other Worker’s purchases are in the shared database, and naming it runs the shared host
--env <environment>reconcilestagingWhich deployed environment to run the pass in. dev is local-only and is refused by name
--subject <holder>reconcileevery holderReconcile one holder’s purchases, as user:<id> or organization:<id>. The support path: the same steps the cron runs, narrowed. An id on its own is refused — it names whichever user or organization carries it
--rail <rail>reconcileevery railReconcile one rail: apple, google, stripe, lemonSqueezy or paddle. Parsed here, so a mistyped rail is a sentence in this terminal rather than a Workflow that burns its retry budget unwatched
--dry-runreconcilefalseShow the plan and write nothing. The pass still runs, in the deployed reconcile Workflow, which reads the purchases, reports the drift and repairs none
--jsonbothfalseOne line of machine-readable output

provision takes no --env. It spans every managed environment in one run, and skips the ones whose app database does not exist yet rather than refusing: the answer to “which environments did you mean” is always the ones that are ready, so there is nothing to state on the command line.

What it does

pithy add payments writes bindings and touches no Cloudflare account. provision stands up the one thing those bindings point at: the prebuilt reconcile Worker that hosts the nightly pass.

For each ready environment it checks the account once up front, deploys the Worker, and then writes that environment’s workflows binding into the app’s wrangler.jsonc. The binding cannot be written by add — wrangler requires a name and a class_name on every entry, and the deployed name is per environment.

An environment is ready when its stanza in the app’s wrangler.jsonc carries a DB binding with a database_id — that is, when pithy provision --env <name> has run for it. One that is not is skipped and reported, never fatal: standing staging up and proving it before production resources exist is the ordinary bring-up, and this command used to refuse it part way through, naming production. The decision is made once, from one read, before a single deploy.

Its Worker deploy is gated. The Worker is deployed carrying a stamp naming the package version and a hash of its resolved configuration, and a run whose stamp matches both ships nothing. Anything the gate cannot establish — no Worker, no stamp, an unreachable account — deploys. pithy deploy --env <env> ships the same Worker without provisioning anything else, and pithy deploy --env <env> --kit --force re-uploads it regardless.

A Worker that owns what the host binds gets its own. When --worker names a Worker that lists a binding the payments host binds in its ownBindings, provision deploys that Worker’s own host, <project>-<env>-<worker>---payments, bound to the Worker’s own resources, and writes its Workflow bindings to reach it, <project>-<env>-<worker>---payments-<job>. The shared <project>-<env>-payments is left alone. See a Worker’s own kit hosts.

No credential is written here, and that is not an omission. Apple’s .p8, Google’s service-account key, Stripe’s key pair, and Lemon Squeezy’s and Paddle’s API keys are taken by a human from five consoles; nothing can mint them. They go in through pithy secrets create payments-provider-credentials, and this command deploys the Worker that reads them. A provision run before the secrets are set still succeeds — the first pass is what reports the missing rail.

Where each rail’s credentials come from

payments-provider-credentials is one secret with a block per rail, and each block is issued by a different company. This is the console, not the integration guide.

RailConsoleWhat to take
appleApp Store ConnectThe App Store Connect API key. Download the .p8 — it is offered exactly once — and copy the key id and the issuer id from the same screen
googleGoogle Cloud IAMThe service account and a JSON key for it. Grant that account access to the app in Play Console; the key itself is minted here
stripeStripe dashboardThe secret key. The webhook signing secret is per endpoint, one screen across
lemonSqueezyLemon Squeezy settingsThe API key, and the signing secret of the webhook you point at this project
paddlePaddle authenticationThe API key, and the notification destination’s signing secret. Not the client token — that is publishable and belongs in pithy.config.ts

Reconciliation is what a purchase that changed at the store — a refund, a lapse or a chargeback — travels through before an entitlement stops answering yes.

Each console is per environment on its own terms: Stripe’s test mode, Paddle’s and Lemon Squeezy’s sandboxes, Apple’s and Google’s separate keys. Provision staging and production from the matching one, never the same credential twice.

These are also where a credential is replaced. Rotation is manual for this secret because none of the five returns a new value over an API — a human opens the console, mints the replacement, and records it. The store holds both versions while webhooks signed under the old one drain.

reconcile runs that same pass on demand and waits for its report. With --worker naming a Worker that has its own reconcile host, it runs that host’s pass, over that Worker’s purchases. It dispatches the deployed Workflow, polls until it reaches a terminal state, and prints what it found.

Reconciliation is the repair path, never the primary one: a rising drifted count means webhooks are not arriving, which is the signal the command exists to surface.

--json

payments provision

KeyTypeMeaning
command"payments provision"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
environmentsstring[]Every environment a reconcile worker was deployed for, in order. dev is local-only and never a deploy target
skippedEnvironmentsobject[]One entry per environment nothing was provisioned for
skippedEnvironments[].envstringThe environment that was skipped
skippedEnvironments[].reasonstringWhy — env.<name> has no DB database_id.
skippedEnvironments[].actionstringWhat resolves it. For any environment but production, a command that runs as written. Production takes a --confirm phrase only a person gives, so its line says the run is a person’s decision rather than naming a fix
exitCodeintegerThe status the run exits with: 0. A run that provisions nothing writes no report

One outcome, never two. A run that went ahead writes this report alone and exits 0, whether or not some environments were skipped — exitCode says so, and it matches $?. A run in which every environment was skipped provisioned no environment, so it writes nothing on stdout: the {"error":…} line on stderr is the whole answer, exit 3, with the provisioning command as its fix.

$ pithy payments provision --worker api --json
{"command":"payments provision","schemaVersion":1,"environments":["staging"],"skippedEnvironments":[{"env":"prod","reason":"env.prod has no DB database_id.","action":"`pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix."}],"exitCode":0}
$ echo $?
0
$ pithy payments provision --worker api --json
{"error":{"code":"core/precondition_failed","status":412,"message":"No environment is ready — staging and prod have no DB database_id.","action":"Run pithy provision --env staging --yes to create its app database. `pithy provision --env prod --yes` with its --confirm phrase, which only a person gives, runs against prod, a production environment. That is a person's decision, not a fix. Once their app databases exist, run `pithy payments provision --json --worker api` again.","exit":3,"retryable":false,"fix":"pithy provision --env staging --yes"}}
$ echo $?
3

The second line is on stderr, and stdout is empty.

payments reconcile

$ pithy payments reconcile --env staging --json
{"command":"payments reconcile","schemaVersion":2,"env":"staging","dryRun":false,"report":{"pages":3,"scanned":214,"unchanged":198,"drifted":4,"superseded":11,"skipped":1,"failed":0,"truncated":false,"dryRun":false}}
KeyTypeMeaning
command"payments reconcile"The subcommand that produced the line
schemaVersionintegerThe version of this payload’s shape. Bumped only when a key is removed or retyped; pithy schema publishes the current one
envstringThe environment the pass ran in
dryRunbooleanWhether this was --dry-run. No drift was repaired when it is true
reportobjectThe Workflow’s own return value, passed through verbatim
planobjectPresent only under --dry-run: the drift the pass found as one repair under data, and a note saying the pass ran in the deployed reconcile Workflow — the one dry run that starts something on Cloudflare to plan, because the pass lives there

report is the deployed Workflow’s output, not the CLI’s. It crosses no schema on the way out, and it is absent from the line entirely when a completed Workflow returned nothing. What the capability returns today:

report keyTypeMeaning
pagesnumberPages read — one durable step each
scannednumberPurchases examined
unchangednumberPurchases whose stored state already matched the store’s
driftednumberPurchases whose stored state disagreed. The number that matters
supersedednumberPurchases a later period of the same subscription has replaced, settled on this pass
skippednumberPurchases no store could be asked about
failednumberPurchases a store refused to answer for. Counted, never thrown — one bad row must not end the pass
truncatedbooleanWhether the run stopped at its page cap with more of the catalog unexamined
dryRunbooleanWhether the run only reported

Errors

Each is a problem line then an action line. Under --json it is one {"error": …} line on stderr with exit, retryable and, where the cause is known, fix, and the process exits by its class.

The capability is not configured. No Worker under apps/ composes payments. It is core/precondition_failed, exit 3, with no fix: pithy add payments needs --set billingSubject=…, which has no default and is yours to choose. So the action names one command per value, each runnable as written — pithy add payments --worker api --with-prerequisites --set billingSubject=user or … --set billingSubject=organization — and none of them is the fix.

Cloudflare credentials are missing. Raised before any client is built.

The Secrets Store id is missing. provision only — the reconcile Worker decrypts each rail’s credentials from it.

--env dev. Checked at the flag, before a single Cloudflare client exists.

--env must be one of staging, prod. Got "dev".
This deploys to a Cloudflare account, and dev is local-only. Run `pithy dev` instead.

No environment is ready. Every environment was skipped, so nothing was deployed: exit 3, core/precondition_failed. The action names the provision each skipped environment needs. Its fix is pithy provision --env <env> --yes when exactly one of them is an environment an agent may provision; a production one is a person’s decision.

The environment has no wrangler stanza, or no DB id. Each missing value is refused rather than deploying a half-wired Worker — the purchase rows live in that database.

The environment’s secrets database does not exist. pithy secrets provision creates it, and runs against every environment, production included — so the refusal names it as a person’s decision and carries no fix.

The project has no name. Every deployed name leads with it, and it is never guessed: a wrong one dispatches into a Workflow nothing deployed.

The Workflow did not finish. reconcile polls a dispatched instance and raises when it ends errored or terminated, or is still running at the poll cap.

Examples

$ pithy payments provision
staging: reconcile worker deployed, PAYMENTS_RECONCILE bound.
prod: reconcile worker deployed, PAYMENTS_RECONCILE bound.
Set each rail's credentials with `pithy secrets create payments-provider-credentials` — nothing can mint them.
Done.

Answer my subscription isn’t showing up for one person, through the steps the cron runs:

pithy payments reconcile --env prod --subject user:usr_a1b2c3
pithy payments reconcile --env prod --rail stripe --json

See the drift without repairing it:

$ pithy payments reconcile --env staging --dry-run
214 scanned, 4 drifted, 1 skipped, 0 failed.
Dry run. Nothing repaired.
ESC