kempo-payments 0.1.1

package/public/utils/money.js

@@ -0,0 +1,67 @@
+/*
+  Formatting money in the browser, served at /payments/utils/money.js.
+
+  The same minor-unit rules as server/utils/money/currencies.js, kept as a separate small copy on
+  purpose: the server module imports kempo's server SDK, and a browser cannot load that. A static
+  test checks the two lists of zero- and three-decimal currencies still agree, because the day they
+  drift is the day a screen shows ¥1,200 as ¥12.00.
+*/
+
+export const ZERO_DECIMAL = new Set([
+  'bif', 'clp', 'djf', 'gnf', 'jpy', 'kmf', 'krw', 'mga',
+  'pyg', 'rwf', 'ugx', 'vnd', 'vuv', 'xaf', 'xof', 'xpf',
+]);
+
+export const THREE_DECIMAL = new Set(['bhd', 'jod', 'kwd', 'omr', 'tnd']);
+
+export const decimalsFor = currency => {
+  const code = String(currency || '').toLowerCase();
+  if(ZERO_DECIMAL.has(code)) return 0;
+  if(THREE_DECIMAL.has(code)) return 3;
+  return 2;
+};
+
+export const fromMinor = (minor, currency) => Number(minor || 0) / 10 ** decimalsFor(currency);
+
+export const toMinor = (major, currency) => {
+  const amount = Number(major);
+  if(!Number.isFinite(amount)) return null;
+  return Math.round(amount * 10 ** decimalsFor(currency));
+};
+
+export const formatAmount = (minor, currency) => {
+  const code = String(currency || 'usd').toLowerCase();
+  try {
+    return new Intl.NumberFormat(undefined, { style: 'currency', currency: code.toUpperCase() }).format(fromMinor(minor, code));
+  } catch {
+    return `${fromMinor(minor, code).toFixed(decimalsFor(code))} ${code.toUpperCase()}`;
+  }
+};
+
+/*
+  Statuses read as machine names — `requires_payment_method` — and a customer or a shop owner
+  should never see one. These are what a screen shows instead.
+*/
+export const STATUS_LABELS = {
+  requires_payment_method: 'Awaiting payment',
+  requires_confirmation: 'Awaiting confirmation',
+  requires_action: 'Awaiting the customer’s bank',
+  processing: 'Processing',
+  requires_capture: 'Authorised, not captured',
+  succeeded: 'Paid',
+  canceled: 'Cancelled',
+  failed: 'Failed',
+};
+
+export const statusLabel = status => STATUS_LABELS[status] || status;
+
+/*
+  Which colour a status badge gets. Only `succeeded` is good news, only `failed` is bad; everything
+  else is in progress and should not be coloured as though somebody needs to do something about it.
+*/
+export const statusTone = status => {
+  if(status === 'succeeded') return 'success';
+  if(status === 'failed' || status === 'canceled') return 'danger';
+  if(status === 'requires_capture') return 'warning';
+  return 'muted';
+};

package/sdk.js

@@ -0,0 +1,42 @@
+/*
+  Server-side entry point — what another extension imports to take money.
+
+  This is the interface the board item calls for: a consumer (kempo-commerce's checkout today, a
+  subscriptions extension later) creates, captures and refunds payments through these functions and
+  never learns which processor is configured. Swapping Stripe for something else is a settings
+  change, not a change to anything that called in here.
+
+  ```js
+  import { createPayment } from 'kempo-payments/sdk';
+
+  const [error, { payment, clientSecret }] = await createPayment({
+    amount: 4999,                 // always minor units — 4999 is $49.99
+    currency: 'usd',
+    owner: 'kempo-commerce',      // who is asking
+    reference: order.id,          // their id for what is being paid for
+    userId: user?.id,             // null for a guest
+    customerEmail: order.email,
+    description: `Order ${order.number}`,
+  });
+  ```
+
+  Then hand `clientSecret` to the browser and mount `<k-pay-form>` with it. Do not wait for the
+  browser to report back — listen for the `payment:succeeded` hook, which is fired from the
+  processor's webhook and arrives whether or not that browser is still open.
+
+  As in kempo's other extensions these are the *data* operations, with no permission checks of
+  their own. The routes under public/api enforce who may do what; anything calling in here is
+  server-side code that has already decided it is allowed.
+*/
+
+export { createPayment } from './server/utils/payments/create.js';
+export { capturePayment, cancelPayment, refundPayment, getClientSecret } from './server/utils/payments/actions.js';
+export { getPayment, getPaymentByRef, paymentsForReference, listPayments, listRefunds, summary } from './server/utils/payments/store.js';
+export { syncPayment, EVENTS } from './server/utils/payments/sync.js';
+export { receiveWebhook, listEvents } from './server/utils/webhooks/receive.js';
+
+export { STATUSES, FINAL, isStatus, isFinal, isAwaitingCustomer, canCapture, canCancel, refundableAmount } from './server/utils/payments/statuses.js';
+export { decimalsFor, formatAmount, fromMinor, isValidAmount, isValidCurrency, normaliseCurrency, toMinor } from './server/utils/money/currencies.js';
+
+export { readConfig, CAPTURE_METHODS, DEFAULTS, OWNER } from './server/utils/config/settings.js';
+export { activeProvider, getProvider, listProviders, providerForPayment } from './server/providers/index.js';

package/server/db/schema.js

@@ -0,0 +1,141 @@
+import { pgTable, text, boolean, integer, jsonb, timestamp, uniqueIndex, index } from 'drizzle-orm/pg-core';
+
+/*
+  Three tables, and none of them holds a card number.
+
+  Nothing sensitive ever reaches this server: the customer's details go straight from their browser
+  to the processor, and what comes back is a reference. Everything below is kempo's own record of
+  what that reference was for — who it belonged to, what it was meant to pay for, and what has
+  happened to it since. Rebuilding any of it means asking the processor, which is exactly the
+  position to be in when the processor is the one holding the money.
+
+  Amounts are integers in the currency's minor unit — cents, pence, yen. Never floats. `1.15` is
+  not representable in binary floating point, and a rounding error in a total is money that either
+  the customer or the seller is short.
+*/
+
+/*
+  One row per attempt to take money, created the moment a charge is started and updated for the
+  rest of its life. It is the row a consumer extension (checkout, a subscription, a top-up) points
+  its own order at via `reference`.
+
+  `providerRef` is the processor's own id for the same thing — Stripe's PaymentIntent. That is the
+  join back to the money, and it is what a webhook arrives carrying, so it is indexed.
+
+  `status` is a normalised vocabulary shared by every provider, not Stripe's. A second processor
+  maps its own states onto these rather than the rest of kempo learning a new set of words. See
+  server/utils/payments/statuses.js for what each one means and which of them are final.
+*/
+export const kempoPayment = pgTable('kempoPayment', {
+  id: text('id').primaryKey(),
+
+  provider: text('provider').notNull(),
+  providerRef: text('providerRef').notNull(),
+  livemode: boolean('livemode').notNull().default(false),
+
+  status: text('status').notNull(),
+  captureMethod: text('captureMethod').notNull().default('automatic'),
+
+  amount: integer('amount').notNull(),
+  amountCaptured: integer('amountCaptured').notNull().default(0),
+  amountRefunded: integer('amountRefunded').notNull().default(0),
+  currency: text('currency').notNull(),
+
+  /*
+    Who asked for the payment and what it was for, in their terms. `owner` is the extension that
+    called `createPayment` and `reference` is its own id for the thing being paid for — an order
+    number, a subscription id. Together they are how a consumer finds its payment again without
+    keeping a second table of its own mapping ids to ids.
+  */
+  owner: text('owner'),
+  reference: text('reference'),
+  description: text('description'),
+  metadata: jsonb('metadata'),
+
+  /*
+    Nullable on purpose. A guest checkout is a real payment by a person with no account, and
+    refusing to record it would mean either inventing an account or not taking the money.
+  */
+  userId: text('userId'),
+  customerEmail: text('customerEmail'),
+
+  /*
+    The last thing the processor said went wrong, kept so a declined card can be explained to
+    somebody looking at the payment later. Cleared on the next successful transition rather than
+    accumulating — a payment that eventually succeeded is not a failed one.
+  */
+  lastError: text('lastError'),
+
+  disputed: boolean('disputed').notNull().default(false),
+
+  createdAt: timestamp('createdAt').notNull(),
+  updatedAt: timestamp('updatedAt').notNull(),
+}, table => ({
+  providerRefIndex: uniqueIndex('kempoPayment_providerRef_idx').on(table.provider, table.providerRef),
+  referenceIndex: index('kempoPayment_reference_idx').on(table.owner, table.reference),
+}));
+
+/*
+  One row per refund, because a payment can have several and "amountRefunded" alone cannot say who
+  issued them, when, or why.
+
+  Kept even when the refund fails: a refund that was attempted and rejected is something the person
+  who attempted it needs to see, and a missing row reads as though nobody ever tried.
+*/
+export const kempoPaymentRefund = pgTable('kempoPaymentRefund', {
+  id: text('id').primaryKey(),
+  paymentId: text('paymentId').notNull(),
+
+  provider: text('provider').notNull(),
+  providerRef: text('providerRef').notNull(),
+
+  amount: integer('amount').notNull(),
+  currency: text('currency').notNull(),
+  status: text('status').notNull(),
+  reason: text('reason'),
+
+  // The kempo user who pressed the button, where there was one. Null for a refund the processor
+  // originated itself — a dispute lost, a card network reversal.
+  issuedBy: text('issuedBy'),
+
+  createdAt: timestamp('createdAt').notNull(),
+  updatedAt: timestamp('updatedAt').notNull(),
+}, table => ({
+  paymentIndex: index('kempoPaymentRefund_payment_idx').on(table.paymentId),
+}));
+
+/*
+  Every webhook this extension has already acted on.
+
+  Processors retry a webhook until they get a 2xx, and they are explicitly allowed to deliver the
+  same event more than once even after one. Without this table a retried `payment_intent.succeeded`
+  fires `payment:succeeded` a second time, and whatever is listening — an order confirmation email,
+  a licence key, a shipment — happens twice. Claiming a row here is what makes the handler
+  idempotent, and it is the whole reason the table exists.
+
+  The primary key is `provider:eventId` rather than a generated one, deliberately. kempo's
+  installer creates columns and primary keys and nothing else — a `unique()` or a unique index in a
+  Drizzle schema is not carried across (see install.js, which adds this extension's indexes by
+  hand). Hanging deduplication off the one constraint the installer is guaranteed to create means
+  it cannot quietly stop working on a site whose indexes did not get made.
+
+  `payload` is kept because a webhook is the only account of what the processor believed at that
+  moment, and it is the first thing anybody asks for when a payment and an order disagree.
+*/
+export const kempoPaymentEvent = pgTable('kempoPaymentEvent', {
+  id: text('id').primaryKey(),
+
+  provider: text('provider').notNull(),
+  providerEventId: text('providerEventId').notNull(),
+  type: text('type').notNull(),
+
+  paymentId: text('paymentId'),
+  payload: jsonb('payload'),
+
+  // Null until it has been processed; set even for an event that was recognised and deliberately
+  // ignored, so "seen but not actionable" is distinguishable from "still queued".
+  handledAt: timestamp('handledAt'),
+  error: text('error'),
+
+  createdAt: timestamp('createdAt').notNull(),
+});

package/server/providers/index.js

@@ -0,0 +1,84 @@
+import * as stripe from './stripe.js';
+import { getSetting } from 'kempo/server/sdk.js';
+import { DEFAULTS } from '../utils/config/settings.js';
+
+/*
+  The registry, and the contract a processor module implements.
+
+  Only Stripe ships today. The abstraction is here anyway, and from the first commit rather than
+  the day a second processor is wanted, because the alternative is that every call site grows a
+  direct dependency on one company's SDK and adding PayPal becomes a change to the whole extension
+  instead of a file in this directory.
+
+  A provider module exports:
+
+  | Export             | Shape                                                                    |
+  |--------------------|--------------------------------------------------------------------------|
+  | `name`             | the id stored on every payment row, and the last URL segment of its webhook |
+  | `label`            | what a human is shown                                                     |
+  | `webhookPath`      | the site path its events should be sent to                                |
+  | `webhookEvents`    | the events that endpoint needs subscribed, for the settings screen to list |
+  | `signatureHeader`  | the request header its webhook signature arrives in                       |
+  | `credentialFields` | the settings holding its credentials, in the order a screen shows them     |
+  | `status()`         | `[err, { configured, mode, livemode, … }]` — is it usable, and in which mode |
+  | `clientConfig()`   | `[err, { publishableKey }]` — the part of the config a browser may hold    |
+  | `createIntent()`   | `[err, { ref, status, clientSecret, … }]`                                 |
+  | `retrieveIntent()` | `[err, { ref, status, … }]`                                               |
+  | `capture()`        | `[err, { ref, status, … }]`                                               |
+  | `cancel()`         | `[err, { ref, status, … }]`                                               |
+  | `refund()`         | `[err, { ref, amount, status, … }]`                                       |
+  | `listRefunds()`    | optional: `[err, [{ ref, amount, status, … }]]` — every refund on a payment |
+  | `verifyEvent()`    | `[err, event]` — reject anything not signed by the provider               |
+  | `interpretEvent()` | `{ kind: 'payment' \| 'refund' \| 'dispute' \| 'ignored', … }`            |
+
+  Statuses coming out of any of these are kempo's, not the provider's — see
+  server/utils/payments/statuses.js. Mapping is the provider module's job precisely so that the
+  rest of the extension has one vocabulary rather than one per processor.
+
+  Roadmap processors — PayPal, Square, Mollie, Amazon Pay — each become one more file here. Wallet
+  and buy-now-pay-later methods (Apple Pay, Google Pay, Klarna, Afterpay, Affirm) are deliberately
+  *not* providers: Stripe's payment form offers them already, so modelling them separately would
+  duplicate an integration that is already done.
+*/
+
+const PROVIDERS = new Map([[stripe.name, stripe]]);
+
+export const listProviders = () => [...PROVIDERS.values()].map(provider => ({
+  name: provider.name,
+  label: provider.label,
+  webhookPath: provider.webhookPath,
+  webhookEvents: provider.webhookEvents || [],
+  credentialFields: provider.credentialFields,
+}));
+
+/*
+  Which request header a provider's webhook signature arrives in. The webhook route asks rather
+  than knowing, so a second processor's header comes with its module instead of being one more
+  fallback in an ever-growing `||` chain.
+*/
+export const signatureHeaderFor = name => PROVIDERS.get(name)?.signatureHeader || null;
+
+export const getProvider = name => {
+  const provider = PROVIDERS.get(name);
+  if(!provider) return [{ code: 400, msg: `No payment provider named "${name}" is installed` }, null];
+  return [null, provider];
+};
+
+/*
+  The provider a payment should be taken through right now.
+
+  Read fresh from settings on every call rather than cached, because the alternative is that
+  switching processors appears to work and then keeps sending money to the old one until somebody
+  restarts the server.
+*/
+export const activeProvider = async () => {
+  const [error, configured] = await getSetting('kempo-payments', 'provider', DEFAULTS.provider);
+  return getProvider(error ? DEFAULTS.provider : String(configured || DEFAULTS.provider));
+};
+
+/*
+  The provider a payment already went through, which is not necessarily the active one. Refunding a
+  Stripe charge after the site has switched to PayPal has to go back to Stripe — the money is
+  there, and asking the new processor to return it is meaningless.
+*/
+export const providerForPayment = payment => getProvider(payment?.provider);