@brninpay/sdk 0.1.0

package/src/modules/policies.ts

@@ -0,0 +1,79 @@
+import { deserializeBigInts, parsePolicyDefinition, ValidationError } from '@brninpay/core'
+import type {
+  ClientTransport,
+  CreatePolicyParams,
+  ListPoliciesParams,
+  PaginatedResult,
+  UpdatePolicyParams,
+} from '../types.js'
+
+export class PolicyClient {
+  constructor(private readonly transport: ClientTransport) {}
+
+  async createPolicy(params: CreatePolicyParams) {
+    const response = await this.transport.request<unknown>({
+      path: '/v1/policies',
+      method: 'POST',
+      body: params,
+    })
+
+    return parsePolicyDefinition(deserializeBigInts(response))
+  }
+
+  async getPolicy(id: string) {
+    if (!id.trim()) {
+      throw new ValidationError('getPolicy requires a policy id')
+    }
+
+    const response = await this.transport.request<unknown>({
+      path: `/v1/policies/${encodeURIComponent(id)}`,
+      method: 'GET',
+    })
+
+    return parsePolicyDefinition(deserializeBigInts(response))
+  }
+
+  async listPolicies(params: ListPoliciesParams = {}): Promise<PaginatedResult<ReturnType<typeof parsePolicyDefinition>>> {
+    const response = await this.transport.request<{
+      items: unknown[]
+      nextCursor?: string | null
+    }>({
+      path: '/v1/policies',
+      method: 'GET',
+      query: {
+        cursor: params.cursor,
+        limit: params.limit,
+        workspaceId: params.workspaceId,
+        actorId: params.actorId,
+        enabled: params.enabled,
+        kind: params.kind,
+      },
+    })
+
+    return {
+      items: response.items.map((item) => parsePolicyDefinition(deserializeBigInts(item))),
+      nextCursor: response.nextCursor ?? null,
+    }
+  }
+
+  async updatePolicy(params: UpdatePolicyParams) {
+    const response = await this.transport.request<unknown>({
+      path: `/v1/policies/${encodeURIComponent(params.id)}`,
+      method: 'PATCH',
+      body: params.patch,
+    })
+
+    return parsePolicyDefinition(deserializeBigInts(response))
+  }
+
+  async deletePolicy(id: string): Promise<{ deleted: true; id: string }> {
+    if (!id.trim()) {
+      throw new ValidationError('deletePolicy requires a policy id')
+    }
+
+    return this.transport.request<{ deleted: true; id: string }>({
+      path: `/v1/policies/${encodeURIComponent(id)}`,
+      method: 'DELETE',
+    })
+  }
+}

package/src/paymaster/client.ts

@@ -0,0 +1,155 @@
+import { AuthorizationError, ValidationError } from '@brninpay/core'
+import type {
+  PaymasterClientConfig,
+  SdkLogger,
+  SponsorshipContext,
+  SponsorshipData,
+  UserOperation,
+} from '../types.js'
+
+const defaultLogger: SdkLogger = {
+  debug: () => undefined,
+  info: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+}
+
+function serializeUserOperation(userOperation: UserOperation): Record<string, string> {
+  if (userOperation.version === 'v0.6') {
+    return {
+      version: userOperation.version,
+      sender: userOperation.sender,
+      nonce: userOperation.nonce.toString(),
+      initCode: userOperation.initCode,
+      callData: userOperation.callData,
+      callGasLimit: userOperation.callGasLimit.toString(),
+      verificationGasLimit: userOperation.verificationGasLimit.toString(),
+      preVerificationGas: userOperation.preVerificationGas.toString(),
+      maxFeePerGas: userOperation.maxFeePerGas.toString(),
+      maxPriorityFeePerGas: userOperation.maxPriorityFeePerGas.toString(),
+      paymasterAndData: userOperation.paymasterAndData,
+      signature: userOperation.signature,
+    }
+  }
+
+  return {
+    version: userOperation.version,
+    sender: userOperation.sender,
+    nonce: userOperation.nonce.toString(),
+    factory: userOperation.factory,
+    factoryData: userOperation.factoryData,
+    callData: userOperation.callData,
+    callGasLimit: userOperation.callGasLimit.toString(),
+    verificationGasLimit: userOperation.verificationGasLimit.toString(),
+    preVerificationGas: userOperation.preVerificationGas.toString(),
+    maxFeePerGas: userOperation.maxFeePerGas.toString(),
+    maxPriorityFeePerGas: userOperation.maxPriorityFeePerGas.toString(),
+    paymaster: userOperation.paymaster,
+    paymasterVerificationGasLimit: userOperation.paymasterVerificationGasLimit.toString(),
+    paymasterPostOpGasLimit: userOperation.paymasterPostOpGasLimit.toString(),
+    paymasterData: userOperation.paymasterData,
+    signature: userOperation.signature,
+  }
+}
+
+export class PaymasterClient {
+  private readonly timeoutMs: number
+  private readonly maxRetries: number
+  private readonly logger: SdkLogger
+  private readonly fetchImplementation: typeof fetch
+
+  constructor(private readonly config: PaymasterClientConfig) {
+    this.timeoutMs = config.timeoutMs ?? 15_000
+    this.maxRetries = config.maxRetries ?? 1
+    this.logger = config.logger ?? defaultLogger
+    this.fetchImplementation = config.fetchImplementation ?? fetch.bind(globalThis)
+  }
+
+  async requestSponsorship(
+    userOperation: UserOperation,
+    context?: SponsorshipContext
+  ): Promise<SponsorshipData> {
+    let attempt = 0
+    while (true) {
+      attempt += 1
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort('Paymaster request timed out'), this.timeoutMs)
+
+      try {
+        const response = await this.fetchImplementation(this.config.url, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            ...(this.config.apiKey ? { Authorization: `Bearer ${this.config.apiKey}` } : {}),
+            ...(this.config.headers ?? {}),
+          },
+          body: JSON.stringify({
+            userOperation: serializeUserOperation(userOperation),
+            context,
+          }),
+          signal: controller.signal,
+        })
+
+        const payload = (await response.json().catch(() => null)) as
+          | {
+              version?: 'v0.6' | 'v0.7'
+              paymasterAndData?: `0x${string}`
+              paymaster?: `0x${string}`
+              paymasterData?: `0x${string}`
+              paymasterVerificationGasLimit?: string
+              paymasterPostOpGasLimit?: string
+              code?: string
+              message?: string
+            }
+          | null
+
+        if (!response.ok) {
+          throw new AuthorizationError(
+            payload?.code ?? 'paymaster_rejected',
+            payload?.message ?? `Paymaster rejected sponsorship with status ${response.status}`,
+            payload
+          )
+        }
+
+        if (userOperation.version === 'v0.6') {
+          if (!payload?.paymasterAndData) {
+            throw new ValidationError('Paymaster response missing paymasterAndData for v0.6 user operation')
+          }
+
+          return {
+            version: 'v0.6',
+            paymasterAndData: payload.paymasterAndData,
+          }
+        }
+
+        if (
+          !payload?.paymaster ||
+          !payload.paymasterData ||
+          !payload.paymasterVerificationGasLimit ||
+          !payload.paymasterPostOpGasLimit
+        ) {
+          throw new ValidationError('Paymaster response missing v0.7 sponsorship fields')
+        }
+
+        return {
+          version: 'v0.7',
+          paymaster: payload.paymaster,
+          paymasterData: payload.paymasterData,
+          paymasterVerificationGasLimit: BigInt(payload.paymasterVerificationGasLimit),
+          paymasterPostOpGasLimit: BigInt(payload.paymasterPostOpGasLimit),
+        }
+      } catch (error) {
+        if (attempt > this.maxRetries + 1) {
+          throw error
+        }
+
+        this.logger.warn('Retrying paymaster sponsorship request', {
+          attempt,
+          error: error instanceof Error ? error.message : String(error),
+        })
+      } finally {
+        clearTimeout(timeoutId)
+      }
+    }
+  }
+}

package/src/runtimee.ts

@@ -0,0 +1,3 @@
+import { BrninpayClient } from './client.js'
+
+export class Runtimee extends BrninpayClient {}

package/src/types.ts

@@ -0,0 +1,469 @@
+export type {
+  Address,
+  AggregatedPolicyDecision,
+  EntryPointVersion,
+  GasEstimate,
+  Hex,
+  PaymentIntent,
+  PaymentIntentStatus,
+  PolicyDefinition,
+  PolicyEvaluationResult,
+  PolicyReason,
+  SmartWallet as CoreSmartWallet,
+  UserOperation,
+  UserOperationCall,
+} from '@brninpay/core'
+
+import type {
+  Address,
+  AggregatedPolicyDecision,
+  EntryPointVersion,
+  GasEstimate,
+  Hex,
+  PaymentIntent,
+  PaymentIntentStatus,
+  PolicyDefinition,
+  PolicyEvaluationResult,
+  PolicyReason,
+  SmartWallet as CoreSmartWallet,
+  UserOperation,
+  UserOperationCall,
+} from '@brninpay/core'
+
+export interface CreateActorParams {
+  name: string
+  budget: {
+    amount: string
+    currency: 'USDC'
+    period: 'monthly' | 'total'
+  }
+  policies: {
+    type: string
+    version?: string
+    config?: Record<string, unknown>
+  }[]
+}
+
+export interface PayParams {
+  target: string
+  amount: string
+  purpose: {
+    type: string
+    id: string
+    description?: string
+  }
+  idempotencyKey?: string
+}
+
+export interface PreviewPayParams {
+  target: string
+  amount: string
+  purpose: {
+    type: string
+    id: string
+    description?: string
+  }
+}
+
+export interface ActorStatus {
+  budget: {
+    total: string
+    used: string
+    remaining: string
+    period: string
+    currency: string
+  }
+  txCount: number
+}
+
+export interface ActorSummary {
+  id: string
+  name: string
+  status: 'active' | 'frozen' | 'depleted'
+  createdAt: string
+}
+
+export interface ExecutionReceipt {
+  executionId: string
+  status: 'pending' | 'confirmed' | 'failed'
+  txHash?: string
+}
+
+export interface SdkLogger {
+  debug(message: string, context?: Record<string, unknown>): void
+  info(message: string, context?: Record<string, unknown>): void
+  warn(message: string, context?: Record<string, unknown>): void
+  error(message: string, context?: Record<string, unknown>): void
+}
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+export interface RequestContext {
+  url: URL
+  method: HttpMethod
+  headers: Headers
+  bodyText?: string
+  timeoutMs: number
+  attempt: number
+}
+
+export interface ResponseContext<T = unknown> {
+  request: RequestContext
+  response: Response
+  data: T
+}
+
+export type RequestInterceptor = (
+  context: RequestContext
+) => Promise<RequestContext | void> | RequestContext | void
+
+export type ResponseInterceptor<T = unknown> = (
+  context: ResponseContext<T>
+) => Promise<ResponseContext<T> | void> | ResponseContext<T> | void
+
+export interface RetryPolicy {
+  retries: number
+  baseDelayMs: number
+  maxDelayMs: number
+  retryMethods: readonly HttpMethod[]
+}
+
+export interface RuntimeeConfig {
+  apiKey: string
+  apiSecret?: string
+  baseUrl?: string
+  timeoutMs?: number
+  retryPolicy?: Partial<RetryPolicy>
+  headers?: Record<string, string>
+  logger?: SdkLogger
+  fetchImplementation?: typeof fetch
+  requestInterceptors?: RequestInterceptor[]
+  responseInterceptors?: ResponseInterceptor[]
+}
+
+export interface PaginationParams {
+  cursor?: string
+  limit?: number
+}
+
+export interface PaginatedResult<T> {
+  items: T[]
+  nextCursor: string | null
+}
+
+export interface PaymentIntentRecipientInput {
+  address: Address
+  chainId: number
+  ensName?: string | null
+}
+
+export interface CreatePaymentIntentParams {
+  workspaceId: string
+  actorId: string
+  amount: {
+    currency: 'USDC'
+    value: bigint | string | number
+    decimals?: number
+  }
+  recipient: PaymentIntentRecipientInput
+  description?: string
+  reference?: string
+  expiresAt?: string | null
+  metadata?: Record<string, unknown>
+  idempotencyKey?: string
+}
+
+export interface PaymentIntentPreviewParams {
+  workspaceId: string
+  actorId: string
+  amount: {
+    currency: 'USDC'
+    value: bigint | string | number
+    decimals?: number
+  }
+  recipient: PaymentIntentRecipientInput
+  metadata?: Record<string, unknown>
+}
+
+export interface PaymentIntentPreview {
+  decision: AggregatedPolicyDecision['decision']
+  policyResults: PolicyEvaluationResult[]
+  estimatedGas?: bigint
+  estimatedTotalCost?: bigint
+}
+
+export interface GetPaymentIntentOptions {
+  waitForTerminalState?: boolean
+  pollIntervalMs?: number
+  timeoutMs?: number
+}
+
+export interface ListPaymentIntentsParams extends PaginationParams {
+  workspaceId?: string
+  actorId?: string
+  status?: PaymentIntentStatus
+}
+
+export interface CancelPaymentIntentParams {
+  reason?: string
+}
+
+export interface CreatePolicyParams {
+  workspaceId: string
+  actorId?: string
+  policy: PolicyDefinition
+}
+
+export interface UpdatePolicyParams {
+  id: string
+  patch: Partial<Omit<PolicyDefinition, 'kind'>> & {
+    enabled?: boolean
+  }
+}
+
+export interface ListPoliciesParams extends PaginationParams {
+  workspaceId?: string
+  actorId?: string
+  enabled?: boolean
+  kind?: PolicyDefinition['kind']
+}
+
+export interface ClientRequestOptions {
+  path: string
+  method?: HttpMethod
+  query?: Record<string, string | number | boolean | null | undefined>
+  headers?: Record<string, string>
+  body?: unknown
+  timeoutMs?: number
+  signal?: AbortSignal
+  retryPolicy?: Partial<RetryPolicy>
+}
+
+export interface ClientTransport {
+  request<T>(options: ClientRequestOptions): Promise<T>
+}
+
+export interface JsonRpcSuccess<T> {
+  jsonrpc: '2.0'
+  id: number | string | null
+  result: T
+}
+
+export interface JsonRpcErrorShape {
+  code: number
+  message: string
+  data?: unknown
+}
+
+export interface JsonRpcFailure {
+  jsonrpc: '2.0'
+  id: number | string | null
+  error: JsonRpcErrorShape
+}
+
+export interface BundlerProviderConfig {
+  name: string
+  url: string
+  headers?: Record<string, string>
+}
+
+export interface BundlerClientConfig {
+  entryPointAddress: Address
+  entryPointVersion: EntryPointVersion
+  primary: BundlerProviderConfig
+  secondary?: BundlerProviderConfig
+  timeoutMs?: number
+  pollingIntervalMs?: number
+  maxRetries?: number
+  logger?: SdkLogger
+  fetchImplementation?: typeof fetch
+}
+
+export interface UserOperationReceipt {
+  userOpHash: Hex
+  entryPoint: Address
+  sender: Address
+  nonce: bigint
+  actualGasCost: bigint
+  actualGasUsed: bigint
+  success: boolean
+  receipt: {
+    transactionHash: Hex
+    blockNumber: bigint
+    blockHash: Hex
+  }
+  logs: readonly unknown[]
+}
+
+export interface UserOperationByHash {
+  blockHash: Hex
+  blockNumber: bigint
+  entryPoint: Address
+  transactionHash: Hex
+  userOperation: UserOperation
+}
+
+export interface SponsorshipContext {
+  workspaceId?: string
+  actorId?: string
+  policyIds?: string[]
+  metadata?: Record<string, unknown>
+}
+
+export type SponsorshipData =
+  | {
+      version: 'v0.6'
+      paymasterAndData: Hex
+    }
+  | {
+      version: 'v0.7'
+      paymaster: Address | Hex
+      paymasterData: Hex
+      paymasterVerificationGasLimit: bigint
+      paymasterPostOpGasLimit: bigint
+    }
+
+export interface PaymasterClientConfig {
+  url: string
+  apiKey?: string
+  timeoutMs?: number
+  maxRetries?: number
+  headers?: Record<string, string>
+  logger?: SdkLogger
+  fetchImplementation?: typeof fetch
+}
+
+export interface PublicClientLike {
+  readContract<T = unknown>(parameters: {
+    address: Address
+    abi: readonly unknown[]
+    functionName: string
+    args?: readonly unknown[]
+  }): Promise<T>
+  getCode(parameters: { address: Address }): Promise<Hex | undefined>
+  estimateFeesPerGas?(): Promise<{
+    maxFeePerGas?: bigint
+    maxPriorityFeePerGas?: bigint
+    gasPrice?: bigint
+  }>
+  getGasPrice?(): Promise<bigint>
+}
+
+export interface SmartAccountOwner {
+  address: Address
+  signMessage(parameters: { message: string | { raw: Hex } }): Promise<Hex>
+  signTypedData?<T extends Record<string, unknown>>(parameters: T): Promise<Hex>
+}
+
+export interface SmartWalletProviderConfig {
+  publicClient: PublicClientLike
+  owner: SmartAccountOwner
+  entryPointAddress: Address
+  entryPointVersion: EntryPointVersion
+  factoryAddress: Address
+  chainId: number
+  saltNonce?: bigint
+}
+
+export interface PreparedUserOperationContext {
+  walletAddress: Address
+  walletDeployed: boolean
+  calls: readonly UserOperationCall[]
+  nonce?: bigint
+  sponsorship?: SponsorshipData
+}
+
+export interface SmartWalletAccountProvider {
+  readonly kind: CoreSmartWallet['provider']
+  readonly chainId: number
+  readonly owner: SmartAccountOwner
+  readonly entryPointAddress: Address
+  readonly entryPointVersion: EntryPointVersion
+  readonly factoryAddress: Address
+  readonly saltNonce: bigint
+  getCounterfactualAddress(): Promise<Address>
+  getFactoryArgs(): Promise<{ factory?: Address; factoryData?: Hex }>
+  encodeCalls(calls: readonly UserOperationCall[]): Promise<Hex>
+  getNonce(address: Address, key?: bigint): Promise<bigint>
+  getStubSignature(): Promise<Hex>
+  signUserOperation(userOperation: UserOperation): Promise<Hex>
+  isDeployed(address: Address): Promise<boolean>
+}
+
+export interface UserOperationBuilderConfig {
+  chainId: number
+  entryPointAddress: Address
+  entryPointVersion: EntryPointVersion
+  usdcAddress: Address
+  bundlerClient?: {
+    estimateUserOperationGas(userOperation: UserOperation): Promise<GasEstimate>
+  }
+  publicClient?: PublicClientLike
+}
+
+export interface SmartWalletConfig {
+  chainId: number
+  usdcAddress: Address
+  provider: SmartWalletAccountProvider
+  bundlerClient: {
+    sendUserOperation(userOperation: UserOperation): Promise<Hex>
+    getUserOperationReceipt(
+      hash: Hex,
+      options?: { pollingIntervalMs?: number; timeoutMs?: number }
+    ): Promise<UserOperationReceipt>
+  }
+  paymasterClient?: {
+    requestSponsorship(
+      userOperation: UserOperation,
+      context?: SponsorshipContext
+    ): Promise<SponsorshipData>
+  }
+  builder: {
+    buildUSDCTransfer(parameters: { recipient: Address; amount: bigint }): UserOperationCall
+    prepareUserOperation(
+      provider: SmartWalletAccountProvider,
+      context: PreparedUserOperationContext
+    ): Promise<UserOperation>
+  }
+}
+
+export interface BatchOperationOptions {
+  waitForReceipt?: boolean
+  pollingIntervalMs?: number
+  timeoutMs?: number
+  sponsorshipContext?: SponsorshipContext
+}
+
+export interface SmartWalletSendResult {
+  wallet: CoreSmartWallet
+  userOperation: UserOperation
+  userOperationHash: Hex
+  receipt?: UserOperationReceipt
+}
+
+export type SmartWalletInstance = CoreSmartWallet
+
+export interface PimlicoBundlerProviderParams {
+  chainId: number
+  apiKey: string
+  url?: string
+}
+
+export interface AlchemyBundlerProviderParams {
+  apiKey: string
+  network?: string
+  url?: string
+}
+
+export interface ApiErrorPayload {
+  code?: string
+  message?: string
+  details?: unknown
+  statusCode?: number
+  error?: string
+}
+
+export interface PolicyDecisionExplanation {
+  decision: AggregatedPolicyDecision['decision']
+  reasons: PolicyReason[]
+}