pipework 0.251.0 → 0.252.1

package/src/infra/credits/index.ts

@@ -0,0 +1,5 @@
+export { createCredits } from './handle.js'
+export type {
+  Credits, CreditsConfig, CreditGrant, GrantOptions, GrantResult, CreditReservation, ReserveResult,
+  CreditBalance, CreditLedgerEntry, HistoryOptions, HistoryPage, LowBalanceState, LowBalanceCrossing,
+} from './handle.js'

package/src/infra/credits/namespace.ts

@@ -0,0 +1,7 @@
+import { createCredits } from './handle.js'
+
+/** Credits namespace — prepaid usage credits per tenant: expiring grants, reserve / settle / release by job. */
+export const credits = {
+  /** Creates a credits handle. */
+  create: createCredits,
+} as const

package/src/infra/credits/schema.ts

@@ -0,0 +1,83 @@
+// The five tables behind prepaid credits, all tenant-scoped (forced row-level
+// security in generated migrations). Amounts are whole units in bigint columns.
+
+import { define } from '../../data/domain/index.js'
+import { field } from '../../data/domain/field.js'
+import { schema } from '../../data/schema/namespace.js'
+import { index, uniqueIndex } from '../../data/db/idx/index.js'
+
+export const CREDIT_RESERVATION_STATUSES = ['held', 'settled', 'released'] as const
+export const CREDIT_LEDGER_KINDS = ['grant', 'reserve', 'settle', 'release', 'expire'] as const
+
+export const creditGrant = define('credit_grant', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  kind: field.text(),
+  amount: field.bigint(),
+  remaining: field.bigint(),
+  grantedAt: field.timestamp().default('now'),
+  expiresAt: field.timestamp().nullable(),
+  sourceRef: field.text().nullable(),
+  metadata: field.jsonb(schema.check.json()).nullable(),
+}, {
+  indexes: (t) => ({
+    bySource: uniqueIndex('uq_credit_grant_source').on(t['tenantId'], t['sourceRef']),
+    byExpiry: index('idx_credit_grant_expiry').on(t['tenantId'], t['expiresAt']),
+  }),
+})
+
+export const creditReservation = define('credit_reservation', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  jobId: field.text(),
+  amount: field.bigint(),
+  status: field.enum(CREDIT_RESERVATION_STATUSES),
+  settledAmount: field.bigint().nullable(),
+  overdraft: field.bigint().default(0n),
+  createdAt: field.timestamp().default('now'),
+  settledAt: field.timestamp().nullable(),
+}, {
+  indexes: (t) => ({
+    byJob: uniqueIndex('uq_credit_reservation_job').on(t['tenantId'], t['jobId']),
+  }),
+})
+
+export const creditDraw = define('credit_draw', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  reservationId: field.uuid(),
+  grantId: field.uuid(),
+  amount: field.bigint(),
+  seq: field.integer(),
+}, {
+  indexes: (t) => ({
+    byReservation: index('idx_credit_draw_reservation').on(t['reservationId']),
+  }),
+})
+
+export const creditAccount = define('credit_account', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  lowBalanceLine: field.bigint().nullable(),
+  updatedAt: field.timestamp().default('now'),
+}, {
+  indexes: (t) => ({
+    byTenant: uniqueIndex('uq_credit_account_tenant').on(t['tenantId']),
+  }),
+})
+
+export const creditLedger = define('credit_ledger', {
+  id: field.uuid().defaultRandom().primaryKey(),
+  tenantId: field.uuid().tenant(),
+  at: field.timestamp().default('now'),
+  kind: field.enum(CREDIT_LEDGER_KINDS),
+  amount: field.bigint(),
+  grantId: field.uuid().nullable(),
+  reservationId: field.uuid().nullable(),
+  jobId: field.text().nullable(),
+  availableAfter: field.bigint(),
+}, {
+  indexes: (t) => ({
+    byTenantTime: index('idx_credit_ledger_tenant_at').on(t['tenantId'], t['at'], t['id']),
+  }),
+})

package/src/infra/email/audit.ts

@@ -0,0 +1,36 @@
+import { sql } from '../../data/db/sql.js'
+import { pipeSystem } from '../../data/db/db.js'
+import type { DB } from '../../data/db/index.js'
+import { boundTransaction } from '../../data/write/audit/bound-transaction.js'
+import { getContext } from '../../request/context/store.js'
+import { resolveActorId } from '../../data/write/audit/actor.js'
+import { getBaseLogger } from '../../core/logging/index.js'
+import { recordFault, faultMessage } from '../alerts/faults.js'
+
+/**
+ * Writes an audit record (entity `Email` unless given) under the Flow's open trace step; does nothing when no step is open.
+ * In the Flow's transaction on that database when one is open (a savepoint, so a failed write cannot abort it; it
+ * commits or rolls back with it), else on the system channel.
+ */
+export async function auditEmail(verb: string, entityId: string | null, details: Record<string, unknown>, entity = 'Email'): Promise<void> {
+  const flow = getContext()
+  const trace = flow?.trace
+  const stepId = trace?.buffer.openStepId ?? null
+  if (flow === undefined || trace === undefined || trace === null || stepId === null) return
+  try {
+    const write = async (db: DB): Promise<void> => {
+      await db.execute(sql`
+        INSERT INTO audit_record
+          (trace_day, trace_id, trace_step_id, tenant_id, actor_id, entity, verb, entity_id, after, occurred_at)
+        VALUES (${trace.openedDay}, ${trace.id}, ${stepId}, ${flow.tenant}, ${resolveActorId(flow)},
+          ${entity}, ${verb}, ${entityId}, ${JSON.stringify(details)}::jsonb, now())
+      `)
+    }
+    const tx = boundTransaction(flow)
+    if (tx === null) await write(pipeSystem())
+    else await tx.transaction(write)
+  } catch (err) {
+    getBaseLogger().error({ err, traceId: trace.id }, `Failed to write the email ${verb} audit record`)
+    void recordFault('audit-write', faultMessage(err), { entity: 'Email', verb })
+  }
+}