@brninpay/sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,472 @@
+import {
+  AllowlistDeniedError,
+  AuthorizationError,
+  BudgetExhaustedError,
+  ErrorCode,
+  ExecutionError,
+  HmacVerificationError,
+  NetworkError,
+  RateLimitExceededError,
+  ValidationError,
+  deserializeBigInts,
+  generateNonce,
+  sha256Hex,
+  signHmacSha256,
+} from '@brninpay/core'
+import { ActorClient } from './actor-client.js'
+import { PaymentIntentClient } from './modules/payment-intents.js'
+import { PolicyClient } from './modules/policies.js'
+import type {
+  ApiErrorPayload,
+  ClientRequestOptions,
+  ClientTransport,
+  RequestContext,
+  RequestInterceptor,
+  ResponseContext,
+  ResponseInterceptor,
+  RetryPolicy,
+  RuntimeeConfig,
+  SdkLogger,
+} from './types.js'
+
+const DEFAULT_BASE_URL = 'https://api.runtimee.dev'
+const DEFAULT_TIMEOUT_MS = 15_000
+const DEFAULT_RETRY_POLICY: RetryPolicy = {
+  retries: 2,
+  baseDelayMs: 250,
+  maxDelayMs: 2_000,
+  retryMethods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+}
+
+const defaultLogger: SdkLogger = {
+  debug: () => undefined,
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+}
+
+function validateBaseUrl(baseUrl: string): URL {
+  const url = new URL(baseUrl)
+  const isLocalhost = ['localhost', '127.0.0.1'].includes(url.hostname)
+
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLocalhost)) {
+    throw new ValidationError(
+      'SDK baseUrl must use HTTPS unless it points to localhost for development',
+      { baseUrl }
+    )
+  }
+
+  return url
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function mergeRetryPolicy(policy?: Partial<RetryPolicy>): RetryPolicy {
+  return {
+    retries: policy?.retries ?? DEFAULT_RETRY_POLICY.retries,
+    baseDelayMs: policy?.baseDelayMs ?? DEFAULT_RETRY_POLICY.baseDelayMs,
+    maxDelayMs: policy?.maxDelayMs ?? DEFAULT_RETRY_POLICY.maxDelayMs,
+    retryMethods: policy?.retryMethods ?? DEFAULT_RETRY_POLICY.retryMethods,
+  }
+}
+
+function buildQueryString(
+  query: Record<string, string | number | boolean | null | undefined> | undefined
+): string {
+  if (!query) {
+    return ''
+  }
+
+  const search = new URLSearchParams()
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined && value !== null) {
+      search.set(key, String(value))
+    }
+  }
+
+  const encoded = search.toString()
+  return encoded ? `?${encoded}` : ''
+}
+
+function normalizePath(path: string): string {
+  return path.startsWith('/') ? path : `/${path}`
+}
+
+function createAbortSignal(signal: AbortSignal | undefined, timeoutMs: number): {
+  signal: AbortSignal
+  cleanup(): void
+} {
+  const controller = new AbortController()
+  const timeoutId = setTimeout(() => controller.abort('Request timed out'), timeoutMs)
+
+  const onAbort = () => controller.abort(signal?.reason)
+  signal?.addEventListener('abort', onAbort, { once: true })
+
+  return {
+    signal: controller.signal,
+    cleanup() {
+      clearTimeout(timeoutId)
+      signal?.removeEventListener('abort', onAbort)
+    },
+  }
+}
+
+function isRetriableStatus(status: number): boolean {
+  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500
+}
+
+function getRetryAfterMs(response: Response): number | null {
+  const retryAfter = response.headers.get('retry-after')
+  if (!retryAfter) {
+    return null
+  }
+
+  const seconds = Number(retryAfter)
+  if (Number.isFinite(seconds)) {
+    return seconds * 1000
+  }
+
+  const dateMs = new Date(retryAfter).getTime()
+  if (Number.isNaN(dateMs)) {
+    return null
+  }
+
+  return Math.max(dateMs - Date.now(), 0)
+}
+
+function computeBackoffMs(attempt: number, policy: RetryPolicy, response?: Response): number {
+  const retryAfterMs = response ? getRetryAfterMs(response) : null
+  if (retryAfterMs !== null) {
+    return retryAfterMs
+  }
+
+  const exponentialDelay = Math.min(
+    policy.baseDelayMs * 2 ** Math.max(attempt - 1, 0),
+    policy.maxDelayMs
+  )
+  const jitter = Math.floor(Math.random() * Math.min(100, policy.baseDelayMs))
+  return exponentialDelay + jitter
+}
+
+function formatRequestBody(body: unknown): string | undefined {
+  if (body === undefined) {
+    return undefined
+  }
+
+  return JSON.stringify(body, (_key, value) => (typeof value === 'bigint' ? value.toString() : value))
+}
+
+async function parseResponsePayload(response: Response): Promise<unknown> {
+  const contentType = response.headers.get('content-type') ?? ''
+
+  if (contentType.includes('application/json')) {
+    return deserializeBigInts(await response.json())
+  }
+
+  if (contentType.startsWith('text/')) {
+    return response.text()
+  }
+
+  if (response.status === 204) {
+    return null
+  }
+
+  const text = await response.text()
+  if (!text) {
+    return null
+  }
+
+  try {
+    return deserializeBigInts(JSON.parse(text))
+  } catch {
+    return text
+  }
+}
+
+function normalizeApiError(payload: unknown): ApiErrorPayload {
+  if (payload && typeof payload === 'object') {
+    const value = payload as Record<string, unknown>
+    return {
+      code: typeof value.code === 'string' ? value.code : undefined,
+      message:
+        typeof value.message === 'string'
+          ? value.message
+          : typeof value.error === 'string'
+            ? value.error
+            : undefined,
+      details: value.details,
+      statusCode: typeof value.statusCode === 'number' ? value.statusCode : undefined,
+      error: typeof value.error === 'string' ? value.error : undefined,
+    }
+  }
+
+  if (typeof payload === 'string') {
+    return { message: payload, error: payload }
+  }
+
+  return {}
+}
+
+function mapApiError(status: number, payload: unknown): Error {
+  const apiError = normalizeApiError(payload)
+  const message = apiError.message ?? apiError.error ?? `Request failed with status ${status}`
+
+  switch (apiError.code) {
+    case ErrorCode.VALIDATION_ERROR:
+      return new ValidationError(message, apiError.details)
+    case ErrorCode.BUDGET_EXHAUSTED: {
+      const details = (apiError.details ?? {}) as Record<string, unknown>
+      return new BudgetExhaustedError(
+        typeof details.policyId === 'string' ? details.policyId : 'unknown',
+        BigInt(typeof details.budgetUsed === 'string' ? details.budgetUsed : '0'),
+        BigInt(typeof details.budgetLimit === 'string' ? details.budgetLimit : '0')
+      )
+    }
+    case ErrorCode.ALLOWLIST_DENIED: {
+      const details = (apiError.details ?? {}) as Record<string, unknown>
+      return new AllowlistDeniedError(
+        typeof details.policyId === 'string' ? details.policyId : 'unknown',
+        typeof details.target === 'string' ? details.target : 'unknown'
+      )
+    }
+    case ErrorCode.RATE_LIMIT_EXCEEDED: {
+      const details = (apiError.details ?? {}) as Record<string, unknown>
+      return new RateLimitExceededError(
+        typeof details.policyId === 'string' ? details.policyId : 'unknown',
+        typeof details.windowMs === 'number' ? details.windowMs : 0,
+        typeof details.maxCalls === 'number' ? details.maxCalls : 0
+      )
+    }
+    case ErrorCode.HMAC_VERIFICATION_FAILED:
+      return new HmacVerificationError(message, apiError.details)
+  }
+
+  if (status === 400) {
+    return new ValidationError(message, apiError.details)
+  }
+
+  if (status === 401 || status === 403) {
+    return new AuthorizationError(apiError.code ?? ErrorCode.AUTHORIZATION_ERROR, message, apiError.details)
+  }
+
+  if (status === 429) {
+    return new RateLimitExceededError('api', 0, 0, { cause: payload as Error })
+  }
+
+  if (status >= 500) {
+    return new ExecutionError(apiError.code ?? ErrorCode.EXECUTION_ERROR, message, apiError.details)
+  }
+
+  return new ExecutionError(apiError.code ?? ErrorCode.EXECUTION_ERROR, message, apiError.details)
+}
+
+export class BrninpayClient implements ClientTransport {
+  public readonly actors: ActorClient
+  public readonly paymentIntents: PaymentIntentClient
+  public readonly policies: PolicyClient
+
+  protected readonly fetchImplementation: typeof fetch
+  protected readonly logger: SdkLogger
+  protected readonly baseUrl: URL
+  protected readonly apiKey: string
+  protected readonly apiSecret?: string
+  protected readonly timeoutMs: number
+  protected readonly defaultHeaders: Record<string, string>
+  protected readonly retryPolicy: RetryPolicy
+  protected readonly requestInterceptors: RequestInterceptor[]
+  protected readonly responseInterceptors: ResponseInterceptor[]
+
+  constructor(config: RuntimeeConfig) {
+    if (!config.apiKey?.trim()) {
+      throw new ValidationError('Runtimee SDK requires a non-empty apiKey')
+    }
+
+    this.baseUrl = validateBaseUrl(config.baseUrl ?? DEFAULT_BASE_URL)
+    this.apiKey = config.apiKey
+    this.apiSecret = config.apiSecret?.trim() || undefined
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    this.fetchImplementation = config.fetchImplementation ?? fetch.bind(globalThis)
+    this.logger = config.logger ?? defaultLogger
+    this.defaultHeaders = { ...(config.headers ?? {}) }
+    this.retryPolicy = mergeRetryPolicy(config.retryPolicy)
+    this.requestInterceptors = config.requestInterceptors ?? []
+    this.responseInterceptors = config.responseInterceptors ?? []
+
+    if (!Number.isInteger(this.timeoutMs) || this.timeoutMs <= 0) {
+      throw new ValidationError('Runtimee SDK timeoutMs must be a positive integer', {
+        timeoutMs: config.timeoutMs,
+      })
+    }
+
+    this.actors = new ActorClient(this)
+    this.paymentIntents = new PaymentIntentClient(this)
+    this.policies = new PolicyClient(this)
+  }
+
+  async request<T>(options: ClientRequestOptions): Promise<T> {
+    const method = options.method ?? 'GET'
+    const retryPolicy = mergeRetryPolicy(options.retryPolicy)
+
+    if (!retryPolicy.retryMethods.includes(method) && retryPolicy.retries > 0) {
+      this.logger.debug('Retries disabled for HTTP method', { method, path: options.path })
+    }
+
+    let lastError: Error | undefined
+
+    for (let attempt = 1; attempt <= retryPolicy.retries + 1; attempt += 1) {
+      try {
+        return await this.executeRequest<T>({
+          ...options,
+          method,
+          retryPolicy,
+          attempt,
+        })
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error))
+        const isLastAttempt = attempt > retryPolicy.retries
+
+        if (isLastAttempt || !retryPolicy.retryMethods.includes(method)) {
+          throw lastError
+        }
+
+        const response = (error as Error & { response?: Response }).response
+        if (response && !isRetriableStatus(response.status)) {
+          throw lastError
+        }
+
+        const backoffMs = computeBackoffMs(attempt, retryPolicy, response)
+        this.logger.warn('Retrying SDK request after failure', {
+          attempt,
+          method,
+          path: options.path,
+          backoffMs,
+          error: lastError.message,
+        })
+        await sleep(backoffMs)
+      }
+    }
+
+    throw lastError ?? new Error('SDK request failed without an error object')
+  }
+
+  private async executeRequest<T>(
+    options: ClientRequestOptions & {
+      method: NonNullable<ClientRequestOptions['method']>
+      retryPolicy: RetryPolicy
+      attempt: number
+    }
+  ): Promise<T> {
+    const path = normalizePath(options.path)
+    const url = new URL(`${this.baseUrl.origin}${path}${buildQueryString(options.query)}`)
+    const bodyText = formatRequestBody(options.body)
+    const headers = new Headers({
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      'X-API-Key': this.apiKey,
+      ...this.defaultHeaders,
+      ...(options.headers ?? {}),
+    })
+    const timeoutMs = options.timeoutMs ?? this.timeoutMs
+
+    const requestContext: RequestContext = {
+      url,
+      method: options.method,
+      headers,
+      bodyText,
+      timeoutMs,
+      attempt: options.attempt,
+    }
+
+    for (const interceptor of this.requestInterceptors) {
+      const nextContext = await interceptor(requestContext)
+      if (nextContext) {
+        requestContext.url = nextContext.url
+        requestContext.method = nextContext.method
+        requestContext.headers = nextContext.headers
+        requestContext.bodyText = nextContext.bodyText
+        requestContext.timeoutMs = nextContext.timeoutMs
+      }
+    }
+
+    await this.applyAuthentication(requestContext)
+
+    const { signal, cleanup } = createAbortSignal(options.signal, requestContext.timeoutMs)
+
+    try {
+      const response = await this.fetchImplementation(requestContext.url, {
+        method: requestContext.method,
+        headers: requestContext.headers,
+        body: requestContext.bodyText,
+        signal,
+      })
+
+      const payload = await parseResponsePayload(response)
+
+      if (!response.ok) {
+        const mappedError = mapApiError(response.status, payload) as Error & { response?: Response }
+        mappedError.response = response
+        throw mappedError
+      }
+
+      let responseContext: ResponseContext<T> = {
+        request: requestContext,
+        response,
+        data: payload as T,
+      }
+
+      for (const interceptor of this.responseInterceptors) {
+        const nextContext = await interceptor(responseContext)
+        if (nextContext) {
+          responseContext = nextContext as ResponseContext<T>
+        }
+      }
+
+      return responseContext.data
+    } catch (error) {
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new NetworkError(`Request timed out after ${requestContext.timeoutMs}ms`, {
+          path,
+          method: requestContext.method,
+        })
+      }
+
+      if (error instanceof TypeError) {
+        throw new NetworkError(error.message, { path, method: requestContext.method }, { cause: error })
+      }
+
+      throw error
+    } finally {
+      cleanup()
+    }
+  }
+
+  private async applyAuthentication(context: RequestContext): Promise<void> {
+    if (!this.apiSecret) {
+      context.headers.set('Authorization', `Bearer ${this.apiKey}`)
+      return
+    }
+
+    const timestamp = new Date().toISOString()
+    const nonce = generateNonce()
+    const payloadHash = await sha256Hex(context.bodyText ?? '')
+    const signingPayload = [
+      timestamp,
+      nonce,
+      context.method.toUpperCase(),
+      `${context.url.pathname}${context.url.search}`,
+      payloadHash,
+    ].join('.')
+
+    const signature = await signHmacSha256({
+      secret: this.apiSecret,
+      message: signingPayload,
+    })
+
+    context.headers.set('X-API-Key', this.apiKey)
+    context.headers.set('X-Signature', signature)
+    context.headers.set('X-Timestamp', timestamp)
+    context.headers.set('X-Nonce', nonce)
+  }
+}

package/src/conversion.ts

@@ -0,0 +1,25 @@
+const USDC_DECIMALS = 6
+const MULTIPLIER = 10n ** BigInt(USDC_DECIMALS)
+
+export function parseUsdc(amount: string): bigint {
+  const parts = amount.split('.')
+  if (parts.length > 2) throw new Error(`Invalid USDC amount: ${amount}`)
+  const whole = parts[0] || '0'
+  let fraction = parts[1] || ''
+  if (fraction.length > USDC_DECIMALS) {
+    fraction = fraction.slice(0, USDC_DECIMALS)
+  }
+  fraction = fraction.padEnd(USDC_DECIMALS, '0')
+  const full = whole + fraction
+  const parsed = BigInt(full)
+  if (parsed < 0n) throw new Error(`Negative USDC amount: ${amount}`)
+  return parsed
+}
+
+export function formatUsdc(amount: bigint): string {
+  const whole = amount / MULTIPLIER
+  const fraction = amount % MULTIPLIER
+  if (fraction === 0n) return whole.toString()
+  const fractionStr = fraction.toString().padStart(USDC_DECIMALS, '0').replace(/0+$/, '')
+  return `${whole}.${fractionStr}`
+}

package/src/erc4337/builder.ts

@@ -0,0 +1,181 @@
+import {
+  ValidationError,
+  type Address,
+  type GasEstimate,
+  type UserOperation,
+  type UserOperationCall,
+} from '@brninpay/core'
+import { encodeFunctionData } from 'viem'
+import type {
+  PreparedUserOperationContext,
+  SmartWalletAccountProvider,
+  UserOperationBuilderConfig,
+} from '../types.js'
+
+const USDC_ABI = [
+  {
+    type: 'function',
+    name: 'transfer',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'to', type: 'address' },
+      { name: 'value', type: 'uint256' },
+    ],
+    outputs: [{ name: '', type: 'bool' }],
+  },
+] as const
+
+function appendFactoryToInitCode(factory: Address, factoryData: `0x${string}`): `0x${string}` {
+  return `${factory}${factoryData.slice(2)}` as `0x${string}`
+}
+
+export class UserOperationBuilder {
+  constructor(private readonly config: UserOperationBuilderConfig) {}
+
+  buildUSDCTransfer(parameters: { recipient: Address; amount: bigint }): UserOperationCall {
+    if (parameters.amount <= 0n) {
+      throw new ValidationError('USDC transfer amount must be greater than zero')
+    }
+
+    return {
+      to: this.config.usdcAddress,
+      value: 0n,
+      data: encodeFunctionData({
+        abi: USDC_ABI,
+        functionName: 'transfer',
+        args: [parameters.recipient, parameters.amount],
+      }),
+    }
+  }
+
+  buildBatchOperations(calls: readonly UserOperationCall[]): readonly UserOperationCall[] {
+    if (calls.length === 0) {
+      throw new ValidationError('buildBatchOperations requires at least one call')
+    }
+
+    return calls.map((call) => ({ ...call }))
+  }
+
+  async prepareUserOperation(
+    provider: SmartWalletAccountProvider,
+    context: PreparedUserOperationContext
+  ): Promise<UserOperation> {
+    const callData = await provider.encodeCalls(context.calls)
+    const nonce = context.nonce ?? (await provider.getNonce(context.walletAddress))
+    const fees = await this.getSuggestedFees()
+    const stubSignature = await provider.getStubSignature()
+    const factoryArgs = context.walletDeployed ? {} : await provider.getFactoryArgs()
+
+    const baseUserOperation: UserOperation =
+      this.config.entryPointVersion === 'v0.6'
+        ? {
+            version: 'v0.6',
+            sender: context.walletAddress,
+            nonce,
+            initCode:
+              factoryArgs.factory && factoryArgs.factoryData
+                ? appendFactoryToInitCode(factoryArgs.factory, factoryArgs.factoryData)
+                : '0x',
+            callData,
+            callGasLimit: 0n,
+            verificationGasLimit: 0n,
+            preVerificationGas: 0n,
+            maxFeePerGas: fees.maxFeePerGas,
+            maxPriorityFeePerGas: fees.maxPriorityFeePerGas,
+            paymasterAndData:
+              context.sponsorship?.version === 'v0.6' ? context.sponsorship.paymasterAndData : '0x',
+            signature: stubSignature,
+          }
+        : {
+            version: 'v0.7',
+            sender: context.walletAddress,
+            nonce,
+            factory: factoryArgs.factory ?? '0x',
+            factoryData: factoryArgs.factoryData ?? '0x',
+            callData,
+            callGasLimit: 0n,
+            verificationGasLimit: 0n,
+            preVerificationGas: 0n,
+            maxFeePerGas: fees.maxFeePerGas,
+            maxPriorityFeePerGas: fees.maxPriorityFeePerGas,
+            paymaster: context.sponsorship?.version === 'v0.7' ? context.sponsorship.paymaster : '0x',
+            paymasterVerificationGasLimit:
+              context.sponsorship?.version === 'v0.7'
+                ? context.sponsorship.paymasterVerificationGasLimit
+                : 0n,
+            paymasterPostOpGasLimit:
+              context.sponsorship?.version === 'v0.7'
+                ? context.sponsorship.paymasterPostOpGasLimit
+                : 0n,
+            paymasterData:
+              context.sponsorship?.version === 'v0.7' ? context.sponsorship.paymasterData : '0x',
+            signature: stubSignature,
+          }
+
+    if (!this.config.bundlerClient) {
+      return this.applyGasEstimate(baseUserOperation, {
+        callGasLimit: 180_000n,
+        verificationGasLimit: 120_000n,
+        preVerificationGas: 60_000n,
+        maxFeePerGas: fees.maxFeePerGas,
+        maxPriorityFeePerGas: fees.maxPriorityFeePerGas,
+      })
+    }
+
+    const gasEstimate = await this.config.bundlerClient.estimateUserOperationGas(baseUserOperation)
+    return this.applyGasEstimate(baseUserOperation, gasEstimate)
+  }
+
+  private applyGasEstimate(userOperation: UserOperation, gasEstimate: GasEstimate): UserOperation {
+    if (userOperation.version === 'v0.6') {
+      return {
+        ...userOperation,
+        callGasLimit: gasEstimate.callGasLimit,
+        verificationGasLimit: gasEstimate.verificationGasLimit,
+        preVerificationGas: gasEstimate.preVerificationGas,
+        maxFeePerGas: gasEstimate.maxFeePerGas,
+        maxPriorityFeePerGas: gasEstimate.maxPriorityFeePerGas,
+      }
+    }
+
+    return {
+      ...userOperation,
+      callGasLimit: gasEstimate.callGasLimit,
+      verificationGasLimit: gasEstimate.verificationGasLimit,
+      preVerificationGas: gasEstimate.preVerificationGas,
+      maxFeePerGas: gasEstimate.maxFeePerGas,
+      maxPriorityFeePerGas: gasEstimate.maxPriorityFeePerGas,
+      paymasterVerificationGasLimit:
+        gasEstimate.paymasterVerificationGasLimit ?? userOperation.paymasterVerificationGasLimit,
+      paymasterPostOpGasLimit:
+        gasEstimate.paymasterPostOpGasLimit ?? userOperation.paymasterPostOpGasLimit,
+    }
+  }
+
+  private async getSuggestedFees(): Promise<{
+    maxFeePerGas: bigint
+    maxPriorityFeePerGas: bigint
+  }> {
+    if (this.config.publicClient?.estimateFeesPerGas) {
+      const fees = await this.config.publicClient.estimateFeesPerGas()
+      const gasPrice = fees.gasPrice ?? 0n
+      return {
+        maxFeePerGas: fees.maxFeePerGas ?? gasPrice,
+        maxPriorityFeePerGas: fees.maxPriorityFeePerGas ?? gasPrice,
+      }
+    }
+
+    if (this.config.publicClient?.getGasPrice) {
+      const gasPrice = await this.config.publicClient.getGasPrice()
+      return {
+        maxFeePerGas: gasPrice,
+        maxPriorityFeePerGas: gasPrice,
+      }
+    }
+
+    return {
+      maxFeePerGas: 1_000_000_000n,
+      maxPriorityFeePerGas: 100_000_000n,
+    }
+  }
+}