Skip to content
Paykit
Esc
↑↓navigate↵open⌘Jpreview
On this page

Paykit

Billing and entitlement for Alchemy.

Billing and entitlement for Alchemy.

Entry points

Import Source
@potion.run/paykit src/index.ts
@potion.run/paykit/Admin src/Admin.ts
@potion.run/paykit/Atom src/Atom.ts
@potion.run/paykit/Billing src/Billing/index.ts
@potion.run/paykit/Foldkit src/Foldkit.ts
@potion.run/paykit/Read src/Read.ts
@potion.run/paykit/Surfaces src/Surfaces.ts
@potion.run/paykit/Webhooks src/Webhooks.ts
@potion.run/paykit/Database src/Database/index.ts
@potion.run/paykit/Database/Postgres src/Database/Postgres.ts
@potion.run/paykit/Database/Sqlite src/Database/Sqlite.ts
@potion.run/paykit/Database/D1 src/Database/D1.ts
@potion.run/paykit/Database/Drizzle src/Database/Drizzle.ts
@potion.run/paykit/Database/MySQL src/Database/MySQL.ts

Modules

  • actionsFor: The actions that make sense for a standing, in a stable display order.
  • BillingMcp: The surfaces an Api projects onto, without a second declaration.
  • BillingStack: The deploy-time billing stack, in one call.
  • BillingStack.resource: The deploy-time billing stack: it records the validated catalog, the provider descriptors and the store kind, retains on removal, and versions that state shape with BILLING_STACK_VERSION.
  • CatalogGuard: Exports CatalogGuard, CatalogGuardLive.
  • CatalogRpc: Exports PaykitCatalogRpcs, PaykitCatalogClient.
  • doctor: Rebuild every read model from billing_event and diff it.
  • Handler: Exports moneyRoutes, handler.
  • httpStatus: The HTTP status a paykit refusal deserves.
  • make: Billing as Effect atoms: the tenant bindings, shaped for a client.
  • Outbound: The outbound edge as a port: the endpoints to notify and the transport that sends a signed request.
  • Paykit: The four export groups as one namespace, so the docs’ Paykit.feature(…) and the flat named exports are the same functions.
  • Payments: Exports providerSet, resolveProvider.
  • planVersionOf: The generation of a plan’s terms the catalog currently sells, or null when the catalog has no such plan.
  • providers: Every Alchemy provider this package owns, as one Layer, so a stack declares Paykit.providers() beside Cloudflare.providers().
  • resolvePolarProductId: Resolve a tier’s product handle to the id Polar’s API expects.
  • TierCommand: Exports TierGrantInput, withGrants, subscribeInputOf, scheduleTierChangeInputOf, purchaseCreditsInputOf, planChangeTier.
  • timelineOf: Fold a log into a timeline.
  • Verify: Check one account’s standing against the catalog and the configured provider.
  • Webhooks: Exports WEBHOOK_TRANSITIONS, webhookActionOf.
  • world: One deployment graph, built from the parts a host chooses.

Admin

  • ChangeTier: Exports AdminChangeTier, AdminChangeTierClient.
  • Reads: Exports AdminReads, makeAdminReads, AdminReadsClient.
  • Refund: Exports AdminRefund, AdminRefundClient.

Auth

  • Actor: The caller of a request, provided by the Session or Admin middleware and carried with the command.
  • FromHeaders: Exports accountFromHeaders, InsecureSessionFromHeaders, InsecureAdminFromHeaders, InsecureDevGuards.
  • FromResolver: Exports ActorResolver, SessionFrom, authenticate, AdminFrom, GuardsFrom.
  • Guards: Exports Session, Admin.

Billing

  • AddAddOn: Attach an add-on plan beside whatever the account already runs.
  • Admin: Exports GrantCredits, ExtendTrial, EnterGrace, Recover, Expire, RecordPayment, RecordPaymentFailure, Refund.
  • Attach: Exports Attach, Update, PreviewAttach, PreviewUpdate.
  • Balances: A customer’s balances: the read side of the entitlement plane, one shape for check, track and this.
  • Balances.layer: Exports BalancesRead, BalancesLive.
  • BillingAdminApiLayer: Every operator binding, implemented over BillingAdminApi — the Api whose commands declare Admin, so a tenant session cannot reach one.
  • BillingAdminInProcess: Every operator binding, implemented in the process that hosts the model.
  • BillingApiLayer: Every paykit tenant binding, implemented over BillingApi — the Api’s own Session middleware decides whether this caller may act for this account, and its reply decoding turns a rejection back into the class a caller matches.
  • BillingInProcess: Every paykit binding, implemented in the process that hosts the model.
  • Bindings: Exports BindingFailed, BindingCall.
  • Cancel: Exports ScheduleCancellation, Resume.
  • ChangeTier: Change the tier a standing is on.
  • ChargeQuantityProration: Collect the money a quantity change moved.
  • Check: The entitlement plane: one local read, no provider round trip, and the balance the customer has of one feature.
  • CheckOverTransport: Check over a transport: delegate the question to whatever serves the entitlement elsewhere — an HTTP call, a Durable Object, another Worker’s binding.
  • CheckReadModel: Check over the edge read model: one row from billing_rm_, no event fold and no view to resolve.
  • Commands: Exports BillingCommands, BillingCommandsLive, BillingCommandsClient.
  • ConsumeCredits: Spend credits from the account’s pool: one pool per account, whatever feature the work belonged to.
  • CreateCustomer: Record the identity a billing page shows for this account: its name and its email address.
  • Customers: A customer’s record: the identity it recorded, the plans it holds and the controls it states over them.
  • Customers.layer: Exports CustomersRead, CustomersLive.
  • Entities: A customer’s child scopes: a team, a project, a workspace.
  • Entities.layer: Exports EntitiesRead, EntityWrites, EntitiesLive.
  • GrantBalance: Create a standalone grant of a counted feature: the API behind Paykit.Balances(account).create.
  • Hold: Hold capacity for work that has not finished: an agent turn, a long job, a request whose cost is known up front.
  • List: One page of accounts, in a stable cursor order.
  • MultiPlan: Exports MultiAttach, MultiUpdate.
  • Portal: Exports Portal, ChargeProration.
  • Preview: Run the model’s pure decide and report what a command would produce: the events, the state after them, and the proration it would charge.
  • ReleaseHold: Return a hold without billing it: the work failed, was cancelled, or never ran.
  • ScheduleTierChange: Exports ScheduleTierChange, WithdrawTierChange.
  • SetBillingControls: Replace a customer’s billing controls: its auto top-up line, its spend ceilings and its usage alerts (ADR 0038).
  • SetQuantity: Set a non-consumable feature’s quantity.
  • SettleHold: Turn a hold into usage: bill what ran and return the rest, in the same command.
  • SetupPayment: Add a payment method without a purchase.
  • SetUsage: Set how much of a non-consumable feature is in use.
  • StartTrial: Open a trial on a tier.
  • Subscribe: The one door to a purchase.
  • TrackUsage: Record usage in the same transaction that checks the allowance.
  • TransferBalance: Move balance units between the customer’s own scope and one of its entities, or between two entities.
  • TransferBalance.layer: Exports TransferBalanceWrite, TransferBalanceLive.
  • Webhook: The webhook edge as a binding: the model’s services resolved once, an event applied per delivery.

Database

  • D1: A Cloudflare D1 billing database.
  • Database: Exports DatabaseService, Database.
  • Drizzle: The billing model on a Postgres database a Drizzle instance already opened.
  • MySQL: A MySQL billing database, from any connection source.
  • Postgres: A Postgres billing database, from any connection source: a Hyperdrive connection string, Neon, PlanetScale Postgres, RDS, or a literal URL.
  • registerMigrations: Register the deploy-time migration Action for a Database, mirroring Alchemy’s own BetterAuth.Migrate.
  • Sqlite: A bun:sqlite billing database — development, tests, and a single-process host.

Migrations

  • converge: Converge the shipped description against the target, additively.
  • Migrations: Exports migrationFiles, schemaFingerprint, migrationFingerprint, migrateDryRun, migrate, sync.

Store

  • d1Executor: A SqlExecutor over Cloudflare’s D1, implementing the asynchronous half of the port that Alchemy’s D1 executor implements (@alchemy.run/cloudflare/D1/ApplyMigrations, makeD1MigrationExecutor): query/get for reads, write/batch for writes, and atomic for a unit.
  • mysqlExecutor: A SqlExecutor over an @effect/sql-mysql2 client — the client @alchemy.run/sql/MySQL builds from a connection URL.
  • PostgresDriver: Exports toPostgresPlaceholders, postgresExecutor, pgPoolExecutor.
  • SqlAggregateStore: A Domain.AggregateStore over SqlEventLog.
  • SqlBillingReadStore: The projection’s port, backed by the same database as the event log: one schema holds the truth and its read models, so a dashboard, the edge read path and doctor all see the same rows without a second store to drift.
  • SqlConsumers: Exports SqlViewStore, SqlPolicyStore, SqlStreamStore.
  • SqlEventLog: The durable half of the store: events are the truth, receipts dedupe by command id, the outbox carries deliveries, and the read model is rebuildable.
  • SqlPlatform: Exports SqlPlatform, layerSqlPlatform.

Subscription

  • ArchiveEntity: Archive an entity and sweep its unspent own sources to the customer in the same command.
  • AttachEntity: Create an entity under a customer.
  • autoTopUp: The auto top-up policy’s configuration.
  • CreateCustomer: Record the customer’s identity: the name and email a billing page shows.
  • dunning: Turn on a dunning retry ladder.
  • HoldPhase: Exports HOLD_STATUS_TRANSITIONS, nextHoldStatus.
  • StandingPhase: Exports standingPhaseOf, standingPhaseOfView, standingPhaseTagOfStatus, standingConditionsOf, STANDING_PHASE_TRANSITIONS, nextStandingPhase, standingTransitionOf, STANDING_PHASE_EDGES.
  • TransferBalance: Move units between two scopes of one customer: the customer’s own scope and one of its entities, or two entities.
  • UpdateEntity: Rename an entity, or clear its name.

Was this page helpful?