SDK wallet kit

import type { CurrencyCode } from '@asteriks-aggregator/sdk/api'
import {
  createWalletKit,
  MemoryReplayStore,
  type WalletAnswer,
  type WalletHandlers,
  type WalletKit,
  type WalletWriteScope,
} from '@asteriks-aggregator/sdk/wallet'

/** Balances in minor units by player and currency; a real wallet keeps them in its own database. */
const balances = new Map<string, number>([['player-1001 EUR', 10_000]])
/** The amount each bet and win moved, by transaction_id, so a rollback can reverse it. */
const moves = new Map<string, number>()
/** The first answer of each reversed transaction: one reversal per bet or win. */
const reversals = new Map<string, WalletAnswer>()

const keyOf = (player: string, currency: CurrencyCode) => `${player} ${currency}`
type Move = { readonly player_id: string; readonly currency: CurrencyCode; readonly transaction_id: string }
const UNKNOWN_PLAYER: WalletAnswer = { error: { code: 'PLAYER_NOT_FOUND', message: 'Unknown player.' } }

/**
 * The writing step of a handler: records in memory have no rollback, so it asks `scope.held()` in the same
 * synchronous step as its writes, and writes only while the kit's claim still holds the transaction_id.
 */
function written(scope: WalletWriteScope, write: () => WalletAnswer): WalletAnswer {
  if (!scope.held()) throw new Error('The claim on this transaction_id was lost; its first answer stands.')
  return write()
}

/** Moves `amount` on a balance the wallet holds and records the move under its transaction_id, in the writing step. */
function moved(scope: WalletWriteScope, request: Move, balance: number, amount: number): WalletAnswer {
  return written(scope, () => {
    balances.set(keyOf(request.player_id, request.currency), balance + amount)
    moves.set(request.transaction_id, amount)
    return { balance: balance + amount, currency: request.currency }
  })
}

const balanceOf = (player: string, currency: CurrencyCode): WalletAnswer => {
  const balance = balances.get(keyOf(player, currency))
  return balance === undefined ? UNKNOWN_PLAYER : { balance, currency }
}

const handlers: WalletHandlers = {
  walletBalance: async ({ player_id, currency }) => balanceOf(player_id, currency),
  walletBet: async (request, scope) => {
    const { player_id, currency, amount, transaction_id } = request
    // A rollback that arrived first leaves a tombstone: the late bet is refused.
    if (reversals.has(transaction_id))
      return { error: { code: 'DUPLICATE_TRANSACTION', message: 'The bet was rolled back before it arrived.' } }
    const balance = balances.get(keyOf(player_id, currency))
    if (balance === undefined) return UNKNOWN_PLAYER
    if (balance < amount) return { error: { code: 'INSUFFICIENT_FUNDS', message: 'The balance is too low.' } }
    return moved(scope, request, balance, -amount)
  },
  walletWin: async (request, scope) => {
    const balance = balances.get(keyOf(request.player_id, request.currency))
    if (balance === undefined) return UNKNOWN_PLAYER
    return moved(scope, request, balance, request.amount)
  },
  walletRollback: async ({ player_id, currency, refers_to_transaction_id }, scope) => {
    const first = reversals.get(refers_to_transaction_id)
    if (first !== undefined) return first
    const balance = balances.get(keyOf(player_id, currency))
    if (balance === undefined) return UNKNOWN_PLAYER
    // An unknown transaction is acknowledged with the current balance; a reversed win may leave it below zero.
    const reversed = balance - (moves.get(refers_to_transaction_id) ?? 0)
    return written(scope, () => {
      const answer: WalletAnswer = { balance: reversed, currency }
      balances.set(keyOf(player_id, currency), reversed)
      reversals.set(refers_to_transaction_id, answer)
      return answer
    })
  },
  // A round close moves no money, so it writes nothing and needs no scope.
  walletRoundFinished: async ({ player_id, currency }) => balanceOf(player_id, currency),
}

/** The wallet kit, served under /wallet, accepting the API keys of `secrets` (both keys during a rotation). */
export function walletKitOf(secrets: ReadonlyMap<string, string>): WalletKit {
  return createWalletKit({
    handlers,
    store: new MemoryReplayStore(),
    secretOf: (apiKey) => secrets.get(apiKey),
    basePath: '/wallet',
  })
}

import { walletKitOf } from './wallet'

const kit = walletKitOf(new Map([['your-api-key', 'your-api-secret']]))

/** The module shape Bun and Deno serve: every request goes to the kit. */
export default { fetch: (request: Request): Promise<Response> => kit.handle(request) }

import express from 'express'
import { expressWalletHandler } from '@asteriks-aggregator/sdk/wallet'
import { walletKitOf } from './wallet'

const kit = walletKitOf(new Map([['your-api-key', 'your-api-secret']]))
const app = express()
app.use('/wallet', expressWalletHandler(kit))
app.use(express.json()) // the rest of the app may parse JSON after the wallet
app.listen(8080)

import Fastify from 'fastify'
import { fastifyWalletPlugin } from '@asteriks-aggregator/sdk/wallet'
import { walletKitOf } from './wallet'

const kit = walletKitOf(new Map([['your-api-key', 'your-api-secret']]))
const app = Fastify()
await app.register(fastifyWalletPlugin(kit), { prefix: '/wallet' })
await app.listen({ port: 8080 })

import type { CurrencyCode } from '@asteriks-aggregator/sdk/api'
import {
  createWalletKit,
  PostgresReplayStore,
  type WalletHandlers,
  type WalletKit,
  type WalletQuery,
} from '@asteriks-aggregator/sdk/wallet'

type Unsafe = (text: string, parameters: string[]) => Promise<readonly Record<string, unknown>[]>

/** The two calls of a postgres.js client the store needs; node-postgres works the same way with a pool client. */
type Sql = { unsafe: Unsafe; begin<T>(work: (transaction: { unsafe: Unsafe }) => Promise<T>): Promise<T> }

/** The store over the operator's driver: `query` is one autocommit statement, `transaction` runs one transaction. */
export function postgresStoreOf(sql: Sql): PostgresReplayStore {
  return new PostgresReplayStore({
    query: (text, parameters) => sql.unsafe(text, [...parameters]),
    transaction: (work) =>
      sql.begin((transaction) => work((text, parameters) => transaction.unsafe(text, [...parameters]))),
  })
}

/** A bet that moves money only through `scope.query`: its write commits with the first answer, or not at all. */
export const walletBet: WalletHandlers['walletBet'] = async ({ player_id, currency, amount }, scope) => {
  const query: WalletQuery | undefined = scope.query
  if (query === undefined) throw new Error('The wallet kit needs the Postgres store for this handler.')
  const rows = await query(
    'UPDATE ledger SET balance = balance - $3::bigint WHERE player = $1 AND currency = $2 AND balance >= $3::bigint RETURNING balance',
    [player_id, currency satisfies CurrencyCode, String(amount)],
  )
  const row = rows[0]
  if (row === undefined) return { error: { code: 'INSUFFICIENT_FUNDS', message: 'The balance is too low.' } }
  return { balance: Number(row.balance), currency }
}

/** The kit over the Postgres store; the other four handlers are written the same way. */
export function walletKitOf(handlers: WalletHandlers, sql: Sql, secrets: ReadonlyMap<string, string>): WalletKit {
  return createWalletKit({
    handlers: { ...handlers, walletBet },
    store: postgresStoreOf(sql),
    secretOf: (apiKey) => secrets.get(apiKey),
    basePath: '/wallet',
  })
}