@brninpay/core 0.1.0

package/src/types/errors.ts

@@ -0,0 +1,215 @@
+export enum ErrorCode {
+  VALIDATION_ERROR = 'validation_error',
+  AUTHORIZATION_ERROR = 'authorization_error',
+  BUDGET_EXHAUSTED = 'budget_exhausted',
+  ALLOWLIST_DENIED = 'allowlist_denied',
+  RATE_LIMIT_EXCEEDED = 'rate_limit_exceeded',
+  AUTHORIZATION_EXPIRED = 'authorization_expired',
+  EXECUTION_ERROR = 'execution_error',
+  NETWORK_ERROR = 'network_error',
+  GAS_ESTIMATION_ERROR = 'gas_estimation_error',
+  BROADCAST_ERROR = 'broadcast_error',
+  REORG_DETECTED = 'reorg_detected',
+  HMAC_VERIFICATION_FAILED = 'hmac_verification_failed',
+}
+
+export interface ErrorCodeMessage {
+  code: string
+  message: string
+}
+
+export interface SerializedError {
+  name: string
+  code: string
+  message: string
+  statusCode: number
+  details?: unknown
+}
+
+export class RuntimeeError extends Error {
+  public readonly code: string
+  public readonly statusCode: number
+  public readonly details?: unknown
+
+  constructor(
+    code: string,
+    message: string,
+    statusCode = 500,
+    details?: unknown,
+    options?: ErrorOptions
+  ) {
+    super(message, options)
+    this.name = new.target.name
+    this.code = code
+    this.statusCode = statusCode
+    this.details = details
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+
+  toJSON(): SerializedError {
+    return serializeError(this)
+  }
+}
+
+export class ValidationError extends RuntimeeError {
+  constructor(message: string, details?: unknown, options?: ErrorOptions) {
+    super(ErrorCode.VALIDATION_ERROR, message, 400, details, options)
+  }
+}
+
+export class AuthorizationError extends RuntimeeError {
+  constructor(code: string, message: string, details?: unknown, options?: ErrorOptions) {
+    super(code, message, 403, details, options)
+  }
+}
+
+export class BudgetExhaustedError extends AuthorizationError {
+  public readonly policyId: string
+  public readonly budgetUsed: bigint
+  public readonly budgetLimit: bigint
+
+  constructor(policyId: string, used: bigint, limit: bigint, options?: ErrorOptions) {
+    super(
+      ErrorCode.BUDGET_EXHAUSTED,
+      `Budget exhausted: ${used} used of ${limit} limit`,
+      {
+        policyId,
+        budgetUsed: used.toString(),
+        budgetLimit: limit.toString(),
+      },
+      options
+    )
+    this.policyId = policyId
+    this.budgetUsed = used
+    this.budgetLimit = limit
+  }
+}
+
+export class AllowlistDeniedError extends AuthorizationError {
+  public readonly policyId: string
+  public readonly target: string
+
+  constructor(policyId: string, target: string, options?: ErrorOptions) {
+    super(
+      ErrorCode.ALLOWLIST_DENIED,
+      `Target "${target}" not in allowlist`,
+      {
+        policyId,
+        target,
+      },
+      options
+    )
+    this.policyId = policyId
+    this.target = target
+  }
+}
+
+export class RateLimitExceededError extends AuthorizationError {
+  public readonly policyId: string
+  public readonly windowMs: number
+  public readonly maxCalls: number
+
+  constructor(policyId: string, windowMs: number, maxCalls: number, options?: ErrorOptions) {
+    super(
+      ErrorCode.RATE_LIMIT_EXCEEDED,
+      `Rate limit exceeded: max ${maxCalls} calls per ${windowMs}ms window`,
+      {
+        policyId,
+        windowMs,
+        maxCalls,
+      },
+      options
+    )
+    this.policyId = policyId
+    this.windowMs = windowMs
+    this.maxCalls = maxCalls
+  }
+}
+
+export class AuthorizationExpiredError extends AuthorizationError {
+  constructor(options?: ErrorOptions) {
+    super(
+      ErrorCode.AUTHORIZATION_EXPIRED,
+      'Authorization preview has expired. Re-simulate.',
+      undefined,
+      options
+    )
+  }
+}
+
+export class ExecutionError extends RuntimeeError {
+  constructor(code: string, message: string, details?: unknown, options?: ErrorOptions) {
+    super(code, message, 502, details, options)
+  }
+}
+
+export class NetworkError extends ExecutionError {
+  constructor(message: string, details?: unknown, options?: ErrorOptions) {
+    super(ErrorCode.NETWORK_ERROR, message, details, options)
+  }
+}
+
+export class GasEstimationError extends ExecutionError {
+  constructor(message: string, details?: unknown, options?: ErrorOptions) {
+    super(ErrorCode.GAS_ESTIMATION_ERROR, message, details, options)
+  }
+}
+
+export class BroadcastError extends ExecutionError {
+  constructor(message: string, details?: unknown, options?: ErrorOptions) {
+    super(ErrorCode.BROADCAST_ERROR, message, details, options)
+  }
+}
+
+export class ReorgDetectedError extends ExecutionError {
+  public readonly depth: number
+
+  constructor(depth: number, options?: ErrorOptions) {
+    super(
+      ErrorCode.REORG_DETECTED,
+      `Chain reorg detected at depth ${depth}`,
+      { depth },
+      options
+    )
+    this.depth = depth
+  }
+}
+
+export class HmacVerificationError extends RuntimeeError {
+  constructor(message: string, details?: unknown, options?: ErrorOptions) {
+    super(ErrorCode.HMAC_VERIFICATION_FAILED, message, 401, details, options)
+  }
+}
+
+export function isRuntimeeError(error: unknown): error is RuntimeeError {
+  return error instanceof RuntimeeError
+}
+
+export function serializeError(error: unknown): SerializedError {
+  if (error instanceof RuntimeeError) {
+    return {
+      name: error.name,
+      code: error.code,
+      message: error.message,
+      statusCode: error.statusCode,
+      details: error.details,
+    }
+  }
+
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      code: ErrorCode.EXECUTION_ERROR,
+      message: error.message,
+      statusCode: 500,
+    }
+  }
+
+  return {
+    name: 'UnknownError',
+    code: ErrorCode.EXECUTION_ERROR,
+    message: 'Unknown error',
+    statusCode: 500,
+    details: error,
+  }
+}

package/src/types/payment.ts

@@ -0,0 +1,297 @@
+import { ValidationError } from './errors.js'
+import type { Address } from './wallet.js'
+
+export const PAYMENT_INTENT_STATUSES = [
+  'draft',
+  'pending_policy',
+  'pending_approval',
+  'approved',
+  'rejected',
+  'pending_submission',
+  'submitted',
+  'confirming',
+  'succeeded',
+  'failed',
+  'cancelled',
+  'expired',
+] as const
+
+export type PaymentIntentStatus = (typeof PAYMENT_INTENT_STATUSES)[number]
+
+export interface PaymentAmount {
+  currency: 'USDC'
+  value: bigint
+  decimals: number
+}
+
+export interface PaymentRecipient {
+  address: Address
+  chainId: number
+  ensName?: string | null
+}
+
+export interface PaymentIntentFailure {
+  code: string
+  message: string
+  retryable: boolean
+  detail?: Record<string, unknown>
+}
+
+export type PaymentMetadataValue =
+  | string
+  | number
+  | boolean
+  | null
+  | PaymentMetadataValue[]
+  | { [key: string]: PaymentMetadataValue }
+
+export interface PaymentIntent {
+  id: string
+  workspaceId: string
+  actorId: string
+  status: PaymentIntentStatus
+  amount: PaymentAmount
+  recipient: PaymentRecipient
+  createdAt: string
+  updatedAt: string
+  expiresAt?: string | null
+  idempotencyKey?: string | null
+  description?: string | null
+  reference?: string | null
+  transactionHash?: `0x${string}` | null
+  failure?: PaymentIntentFailure | null
+  metadata?: Record<string, PaymentMetadataValue>
+}
+
+export interface SerializedBigInt {
+  __type: 'bigint'
+  value: string
+}
+
+export const PAYMENT_INTENT_TERMINAL_STATUSES = new Set<PaymentIntentStatus>([
+  'rejected',
+  'succeeded',
+  'failed',
+  'cancelled',
+  'expired',
+])
+
+export const PAYMENT_INTENT_TRANSITIONS: Record<
+  PaymentIntentStatus,
+  readonly PaymentIntentStatus[]
+> = {
+  draft: ['pending_policy', 'cancelled', 'expired'],
+  pending_policy: ['pending_approval', 'approved', 'rejected', 'cancelled', 'expired'],
+  pending_approval: ['approved', 'rejected', 'cancelled', 'expired'],
+  approved: ['pending_submission', 'submitted', 'cancelled', 'expired'],
+  rejected: [],
+  pending_submission: ['submitted', 'failed', 'cancelled', 'expired'],
+  submitted: ['confirming', 'succeeded', 'failed'],
+  confirming: ['succeeded', 'failed'],
+  succeeded: [],
+  failed: [],
+  cancelled: [],
+  expired: [],
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function assertIsoTimestamp(value: string, fieldName: string): void {
+  if (Number.isNaN(Date.parse(value))) {
+    throw new ValidationError(`${fieldName} must be a valid ISO-8601 timestamp`, {
+      field: fieldName,
+      value,
+    })
+  }
+}
+
+export function validatePaymentAmount(amount: PaymentAmount): void {
+  if (amount.currency !== 'USDC') {
+    throw new ValidationError('Payment amount currency must be USDC', {
+      field: 'amount.currency',
+      value: amount.currency,
+    })
+  }
+
+  if (amount.value <= 0n) {
+    throw new ValidationError('Payment amount must be greater than zero', {
+      field: 'amount.value',
+      value: amount.value.toString(),
+    })
+  }
+
+  if (!Number.isInteger(amount.decimals) || amount.decimals < 0 || amount.decimals > 18) {
+    throw new ValidationError('Payment amount decimals must be an integer between 0 and 18', {
+      field: 'amount.decimals',
+      value: amount.decimals,
+    })
+  }
+}
+
+export function isPaymentIntentTerminalStatus(status: PaymentIntentStatus): boolean {
+  return PAYMENT_INTENT_TERMINAL_STATUSES.has(status)
+}
+
+export function canTransitionPaymentIntentStatus(
+  currentStatus: PaymentIntentStatus,
+  nextStatus: PaymentIntentStatus
+): boolean {
+  return PAYMENT_INTENT_TRANSITIONS[currentStatus].includes(nextStatus)
+}
+
+export function assertValidPaymentIntentTransition(
+  currentStatus: PaymentIntentStatus,
+  nextStatus: PaymentIntentStatus
+): void {
+  if (!canTransitionPaymentIntentStatus(currentStatus, nextStatus)) {
+    throw new ValidationError(
+      `Invalid payment intent transition from ${currentStatus} to ${nextStatus}`,
+      {
+        currentStatus,
+        nextStatus,
+      }
+    )
+  }
+}
+
+export function assertPaymentIntent(value: unknown): asserts value is PaymentIntent {
+  if (!isObject(value)) {
+    throw new ValidationError('Payment intent payload must be an object')
+  }
+
+  if (typeof value.id !== 'string' || !value.id.trim()) {
+    throw new ValidationError('Payment intent id is required', { field: 'id' })
+  }
+
+  if (typeof value.workspaceId !== 'string' || !value.workspaceId.trim()) {
+    throw new ValidationError('Payment intent workspaceId is required', {
+      field: 'workspaceId',
+    })
+  }
+
+  if (typeof value.actorId !== 'string' || !value.actorId.trim()) {
+    throw new ValidationError('Payment intent actorId is required', {
+      field: 'actorId',
+    })
+  }
+
+  if (
+    typeof value.status !== 'string' ||
+    !PAYMENT_INTENT_STATUSES.includes(value.status as PaymentIntentStatus)
+  ) {
+    throw new ValidationError('Payment intent status is invalid', {
+      field: 'status',
+      value: value.status,
+    })
+  }
+
+  if (!isObject(value.amount)) {
+    throw new ValidationError('Payment intent amount is required', { field: 'amount' })
+  }
+
+  if (!isObject(value.recipient)) {
+    throw new ValidationError('Payment intent recipient is required', {
+      field: 'recipient',
+    })
+  }
+
+  if (typeof value.recipient.address !== 'string' || !value.recipient.address.startsWith('0x')) {
+    throw new ValidationError('Payment intent recipient address is invalid', {
+      field: 'recipient.address',
+      value: value.recipient.address,
+    })
+  }
+
+  if (
+    typeof value.recipient.chainId !== 'number' ||
+    !Number.isInteger(value.recipient.chainId) ||
+    value.recipient.chainId <= 0
+  ) {
+    throw new ValidationError('Payment intent recipient chainId is invalid', {
+      field: 'recipient.chainId',
+      value: value.recipient.chainId,
+    })
+  }
+
+  validatePaymentAmount(value.amount as unknown as PaymentAmount)
+
+  if (typeof value.createdAt !== 'string') {
+    throw new ValidationError('Payment intent createdAt is required', {
+      field: 'createdAt',
+    })
+  }
+
+  if (typeof value.updatedAt !== 'string') {
+    throw new ValidationError('Payment intent updatedAt is required', {
+      field: 'updatedAt',
+    })
+  }
+
+  assertIsoTimestamp(value.createdAt, 'createdAt')
+  assertIsoTimestamp(value.updatedAt, 'updatedAt')
+
+  if (value.expiresAt !== undefined && value.expiresAt !== null && typeof value.expiresAt !== 'string') {
+    throw new ValidationError('Payment intent expiresAt must be a timestamp string', {
+      field: 'expiresAt',
+    })
+  }
+
+  if (value.expiresAt) {
+    assertIsoTimestamp(value.expiresAt, 'expiresAt')
+  }
+}
+
+export function serializeBigInts(value: unknown): unknown {
+  if (typeof value === 'bigint') {
+    return {
+      __type: 'bigint',
+      value: value.toString(),
+    } satisfies SerializedBigInt
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((entry) => serializeBigInts(entry))
+  }
+
+  if (isObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, serializeBigInts(entry)])
+    )
+  }
+
+  return value
+}
+
+export function deserializeBigInts<T>(value: unknown): T {
+  if (Array.isArray(value)) {
+    return value.map((entry) => deserializeBigInts(entry)) as T
+  }
+
+  if (isObject(value)) {
+    if (value.__type === 'bigint' && typeof value.value === 'string') {
+      return BigInt(value.value) as T
+    }
+
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, deserializeBigInts(entry)])
+    ) as T
+  }
+
+  return value as T
+}
+
+export function serializePaymentIntent(paymentIntent: PaymentIntent): string {
+  assertPaymentIntent(paymentIntent)
+
+  // Preserve bigint fidelity over JSON transport without leaking decimal precision.
+  return JSON.stringify(serializeBigInts(paymentIntent))
+}
+
+export function deserializePaymentIntent(payload: string | unknown): PaymentIntent {
+  const candidate = typeof payload === 'string' ? JSON.parse(payload) : payload
+  const paymentIntent = deserializeBigInts<unknown>(candidate)
+  assertPaymentIntent(paymentIntent)
+  return paymentIntent
+}