@zkp2p/pay-shared 0.0.1 → 1.0.0

package/src/types.ts

@@ -1,464 +0,0 @@
-export const PaymentPlatform = {
-  VENMO: 'venmo',
-  CASHAPP: 'cashapp',
-  REVOLUT: 'revolut',
-  WISE: 'wise',
-  ZELLE: 'zelle',
-  PAYPAL: 'paypal',
-  MONZO: 'monzo',
-  N26: 'n26',
-} as const;
-
-export type PaymentPlatformType = typeof PaymentPlatform[keyof typeof PaymentPlatform];
-
-// Supported chains for USDC destination
-// Re-exported from chains.ts for backward compatibility
-import { SupportedChainsMap } from './chains.js';
-export const SupportedChains = SupportedChainsMap;
-
-export type SupportedChainId = keyof typeof SupportedChains;
-
-// Checkout mode determines how amounts are specified
-export const CheckoutMode = {
-  EXACT_TOKEN: 'exact-token',  // Merchant specifies USDC amount, customer pays variable fiat
-  EXACT_FIAT: 'exact-fiat',    // Merchant specifies fiat amount, customer pays fixed fiat, merchant receives variable USDC
-} as const;
-
-export type CheckoutModeType = typeof CheckoutMode[keyof typeof CheckoutMode];
-
-export const OrderStatus = {
-  SIGNAL_SUBMITTED: 'SIGNAL_SUBMITTED',  // Intent tx submitted, awaiting confirmation
-  SIGNAL_MINED: 'SIGNAL_MINED',          // Intent tx confirmed, intentHash available
-  PAYMENT_SENT: 'PAYMENT_SENT',          // User marked fiat payment as sent
-  PROOF_VERIFIED: 'PROOF_VERIFIED',      // ZKP proof verified by attestation service
-  FULFILL_SUBMITTED: 'FULFILL_SUBMITTED', // Fulfill tx submitted, awaiting confirmation
-  FULFILLED: 'FULFILLED',                // Fulfill tx confirmed, payment complete
-  CANCELLED: 'CANCELLED',                // Order cancelled
-  EXPIRED: 'EXPIRED',                    // Order expired
-  FAILED: 'FAILED',                      // Order failed due to error
-} as const;
-
-export type OrderStatusType = typeof OrderStatus[keyof typeof OrderStatus];
-
-export const ProofAttemptStatus = {
-  PENDING: 'PENDING',     // Proof received, awaiting verification
-  VERIFYING: 'VERIFYING', // Being verified by attestation service
-  VERIFIED: 'VERIFIED',   // Proof valid, fulfillment can proceed (Order tracks tx status)
-  REJECTED: 'REJECTED',   // Proof failed verification (can retry with new proof)
-} as const;
-
-export type ProofAttemptStatusType = typeof ProofAttemptStatus[keyof typeof ProofAttemptStatus];
-
-export const SessionStatus = {
-  CREATED: 'CREATED',
-  ACTIVE: 'ACTIVE',
-  COMPLETED: 'COMPLETED',
-  EXPIRED: 'EXPIRED',
-  CANCELLED: 'CANCELLED',
-} as const;
-
-export type SessionStatusType = typeof SessionStatus[keyof typeof SessionStatus];
-
-// Structured error codes for Order failures
-export const OrderErrorCode = {
-  // Proof verification errors
-  PROOF_INVALID: 'PROOF_INVALID',               // Proof data failed attestation verification
-  PROOF_EXPIRED: 'PROOF_EXPIRED',               // Proof timestamp too old
-  PROOF_AMOUNT_MISMATCH: 'PROOF_AMOUNT_MISMATCH', // Payment amount doesn't match intent
-  PROOF_RECIPIENT_MISMATCH: 'PROOF_RECIPIENT_MISMATCH', // Payment recipient doesn't match
-
-  // Transaction errors
-  FULFILL_TIMEOUT: 'FULFILL_TIMEOUT',           // On-chain tx timed out
-  FULFILL_REVERTED: 'FULFILL_REVERTED',         // On-chain tx reverted
-  SIGNAL_TIMEOUT: 'SIGNAL_TIMEOUT',             // Signal intent tx timed out
-  SIGNAL_REVERTED: 'SIGNAL_REVERTED',           // Signal intent tx reverted
-
-  // Infrastructure errors
-  RPC_ERROR: 'RPC_ERROR',                       // RPC node connection/timeout
-  RELAYER_ERROR: 'RELAYER_ERROR',               // Relayer submission failed
-  ATTESTATION_ERROR: 'ATTESTATION_ERROR',       // Attestation service unavailable
-
-  // Bridge errors (cross-chain)
-  BRIDGE_QUOTE_ERROR: 'BRIDGE_QUOTE_ERROR',     // Failed to get bridge quote
-  BRIDGE_TIMEOUT: 'BRIDGE_TIMEOUT',             // Bridge fill timed out
-
-  // Fee threshold errors (exact-fiat mode)
-  FEE_THRESHOLD_EXCEEDED: 'FEE_THRESHOLD_EXCEEDED', // Quote fee exceeds merchant's max
-
-  // Generic
-  SDK_ERROR: 'SDK_ERROR',                       // Unknown SDK error
-  UNKNOWN_ERROR: 'UNKNOWN_ERROR',               // Uncategorized error
-} as const;
-
-export type OrderErrorCodeType = typeof OrderErrorCode[keyof typeof OrderErrorCode];
-
-export const MerchantEnvironment = {
-  LIVE: 'LIVE',
-  SANDBOX: 'SANDBOX',
-} as const;
-
-export type MerchantEnvironmentType = typeof MerchantEnvironment[keyof typeof MerchantEnvironment];
-
-export type Merchant = {
-  id: string;
-  name: string;
-  logoUrl?: string | null;
-  disableBranding?: boolean;
-  apiKey: string;
-  environment?: MerchantEnvironmentType;
-  sandboxMerchantId?: string | null;
-  createdAt: string;
-  updatedAt: string;
-  // Checkout defaults
-  defaultChainId?: number | null;
-  defaultCheckoutMode?: 'exact-token' | 'exact-fiat' | null;
-  defaultFiatCurrency?: string | null;
-  defaultMaxFeePercentage?: number | null;
-  // Payment platform configuration (empty array = all platforms enabled)
-  enabledPaymentPlatforms?: PaymentPlatformType[] | null;
-};
-
-export type CreateMerchantRequest = {
-  name: string;
-  logoUrl?: string;
-};
-
-export type CheckoutSession = {
-  id: string;
-  merchantId: string;
-  amountUsdc: string;
-  netAmountUsdc?: string | null;
-  destinationChainId: number;
-  destinationToken: string;
-  recipientAddress: string;
-  status: SessionStatusType;
-  selectedPaymentPlatform?: PaymentPlatformType | null;
-  selectedFiatCurrency?: string | null;
-  successUrl?: string | null;
-  cancelUrl?: string | null;
-  metadata?: Record<string, string> | null;
-  expiresAt?: string | null;  // Session expiry time (default: 1 hour from creation)
-  activeOrderId?: string | null;
-  // Checkout mode (exact-token or exact-fiat)
-  checkoutMode?: CheckoutModeType;
-  // Exact-fiat mode fields
-  fiatAmount?: string | null;           // Customer's fixed fiat payment (exact-fiat mode)
-  fiatCurrency?: string | null;         // e.g., "USD" (exact-fiat mode)
-  maxFeePercentage?: number | null;     // Merchant's max acceptable fee % (exact-fiat mode)
-  // Bridge fields (populated when destinationChainId != Base)
-  requiresBridge?: boolean;
-  // Payment platform configuration (empty array = all platforms enabled)
-  enabledPaymentPlatforms?: PaymentPlatformType[] | null;
-  createdAt: string;
-  updatedAt: string;
-  // Included merchant relation (when fetched with include)
-  merchant?: {
-    id: string;
-    name: string;
-    logoUrl?: string | null;
-    environment?: MerchantEnvironmentType;
-    disableBranding?: boolean;
-  } | null;
-  // Included active order relation (when fetched with include)
-  activeOrder?: Order | null;
-};
-
-export type QuoteIntent = {
-  depositId: string;
-  processorName: string;
-  amount: string;
-  toAddress: string;
-  payeeDetails: string;
-  processorIntentData: Record<string, unknown>;
-  fiatCurrencyCode: string;
-  chainId: string;
-};
-
-export type Quote = {
-  fiatAmount: string;
-  fiatAmountFormatted: string;
-  tokenAmount: string;
-  tokenAmountFormatted: string;
-  paymentMethod: string;
-  payeeAddress: string;
-  conversionRate: string;
-  intent: QuoteIntent;
-  payeeData?: Record<string, string>;
-};
-
-export type Order = {
-  id: string;
-  sessionId: string;
-  merchantId: string;
-  status: OrderStatusType;
-  intentHash?: string | null;
-  signalTx?: string | null;
-  fulfillTx?: string | null;
-  paymentPlatform?: PaymentPlatformType | null;
-  fiatCurrency?: string | null;
-  amountUsdc?: string | null;
-  netAmountUsdc?: string | null;
-  conversionRate?: string | null;
-  recipient?: string | null;
-  quote?: Quote | null;
-  expiresAt?: string | null;
-  // Bridge execution data (populated for cross-chain orders)
-  bridgeCommitmentData?: string | null;  // Encoded BridgeCommitment (stored at signal)
-  bridgeFulfillData?: string | null;     // Encoded AcrossFulfillData (stored at fulfill)
-  bridgeDepositTxHash?: string | null;   // Across deposit tx hash
-  // Bridge status tracking
-  bridgeStatus?: 'pending' | 'filled' | 'expired' | null;
-  bridgeFilledAt?: string | null;
-  bridgeFilledTxHash?: string | null;    // Fill tx on destination chain
-  // Bridge info (populated when fetched with bridge data)
-  bridgeInfo?: OrderBridgeInfo | null;
-  // Proof tracking
-  currentProofId?: string | null;
-  // Cancellation tracking
-  cancelTx?: string | null;
-  cancelledAt?: string | null;
-  cancelReason?: string | null;
-  // Error tracking
-  errorCode?: string | null;
-  errorMessage?: string | null;
-  errorDetails?: Record<string, unknown> | null;
-  failedAt?: string | null;
-  createdAt: string;
-  updatedAt: string;
-};
-
-export type ProofAttempt = {
-  id: string;
-  orderId: string;
-  intentHash: string;
-  proof: Record<string, unknown>;
-  submittedAt: string;
-  status: ProofAttemptStatusType;
-  verifiedAt?: string | null;
-  attestationResponse?: Record<string, unknown> | null;
-  verificationError?: string | null;
-  verificationMessage?: string | null;
-  txHash?: string | null;
-  txSubmittedAt?: string | null;
-  txConfirmedAt?: string | null;
-  txError?: string | null;
-};
-
-// Base fields common to both checkout modes
-type CreateSessionBaseRequest = {
-  merchantId: string;
-  destinationChainId: number;
-  destinationToken: string; // Destination token alias (USDC/USDT) or token address
-  recipientAddress: string;
-  successUrl?: string;
-  cancelUrl?: string;
-  metadata?: Record<string, string>;
-  // Optional: Override merchant's enabled platforms for this session
-  enabledPaymentPlatforms?: PaymentPlatformType[];
-};
-
-// Exact-token mode: merchant specifies USDC amount, customer pays variable fiat
-type CreateSessionExactTokenRequest = CreateSessionBaseRequest & {
-  checkoutMode?: 'exact-token';
-  amountUsdc: string;
-  fiatAmount?: never;
-  fiatCurrency?: never;
-  maxFeePercentage?: never;
-};
-
-// Exact-fiat mode: merchant specifies fiat amount, customer pays fixed fiat
-type CreateSessionExactFiatRequest = CreateSessionBaseRequest & {
-  checkoutMode: 'exact-fiat';
-  amountUsdc?: never;
-  fiatAmount: string;        // Fixed fiat amount customer pays
-  fiatCurrency?: string;     // e.g., "USD" (optional: falls back to merchant defaultFiatCurrency)
-  maxFeePercentage?: number; // Max acceptable fee % (optional, default 10%)
-};
-
-export type CreateSessionRequest = CreateSessionExactTokenRequest | CreateSessionExactFiatRequest;
-
-/**
- * Bridge information returned when session requires cross-chain bridging.
- * Amounts are in raw units (6 decimals for USDC).
- */
-export type BridgeInfo = {
-  required: boolean;
-  inputAmount?: string | null;      // Amount on Base (includes fees)
-  outputAmount?: string | null;     // Expected output after fees
-  feeAmount?: string | null;        // Total bridge fee
-  minOutputAmount?: string | null;  // Merchant's requested amount
-  estimatedTimeSeconds?: number | null;
-};
-
-export type CreateSessionResponse = {
-  session: CheckoutSession;
-  sessionToken: string; // Plain-text token for checkout authentication (only returned at creation)
-  checkoutUrl: string; // Includes session ID and token
-  bridge?: BridgeInfo;
-};
-
-export type StartSessionRequest = {
-  paymentPlatform?: PaymentPlatformType;
-  fiatCurrency?: string;
-};
-
-export type StartSessionResponse = {
-  session: CheckoutSession;
-  order: Order;
-  quote: Quote;
-  intentHash: string;
-  expiresAt?: string | null;
-};
-
-export type MarkPaymentSentResponse = {
-  order: Order;
-};
-
-export type FulfillIntentRequest = {
-  intentHash: string;
-  proof: Record<string, unknown> | string;
-};
-
-export type FulfillIntentResponse = {
-  order: Order;
-  proofAttemptId: string;
-  txHash: string;
-};
-
-// Error response when proof verification fails
-// canRetry: true means user can submit new proof for the same maker
-export type FulfillIntentError = {
-  proofAttemptId: string;
-  errorCode?: string;
-  errorMessage: string;
-  canRetry: boolean;
-};
-
-// Response type for GET /api/orders/:id/proof-attempts
-export type ProofAttemptsResponse = {
-  proofAttempts: ProofAttempt[];
-};
-
-// Response type for GET /api/orders/:orderId/bridge-status
-export interface BridgeStatusResponse {
-  status: 'pending' | 'filled' | 'expired' | 'not_applicable';
-  destinationChainId?: string;  // bigint as string
-  outputAmountUsdc?: string;    // Estimated now, may be exact for filled status
-  fillTxHash?: string;          // Transaction on destination chain
-  depositTxHash?: string;       // Transaction on Base (fulfillTx)
-  acrossTrackingUrl?: string;   // URL to track on Across website
-  estimatedFillTime?: number;   // Seconds remaining (estimated)
-}
-
-/**
- * Bridge information included in order responses.
- * Tracks the status of cross-chain bridging via Across Protocol.
- */
-export interface OrderBridgeInfo {
-  status: 'PENDING' | 'DEPOSITED' | 'FILLED' | 'EXPIRED';
-  destinationChainId: string;         // bigint as string
-  outputAmountUsdc?: string;          // Net amount after bridge fees (legacy: estimate/minimum)
-  estimatedOutputAmountUsdc?: string;  // Real Across-estimated output before fulfillment slippage buffer
-  minOutputAmountUsdc?: string;       // Buffered minimum output currently enforced at fulfill
-  fillTxHash?: string | null;         // Transaction on destination chain
-  estimatedFillTime?: number | null;  // Seconds (estimated)
-}
-
-// ============ Webhook Types ============
-
-export const WebhookEventType = {
-  // Order lifecycle events
-  ORDER_CREATED: 'order.created',
-  ORDER_PAYMENT_SENT: 'order.payment_sent',
-  ORDER_FULFILLED: 'order.fulfilled',
-  ORDER_FAILED: 'order.failed',
-  ORDER_EXPIRED: 'order.expired',
-
-  // Session lifecycle events
-  SESSION_STARTED: 'session.started',
-  SESSION_COMPLETED: 'session.completed',
-  SESSION_ABANDONED: 'session.abandoned',
-} as const;
-
-export type WebhookEventTypeValue = typeof WebhookEventType[keyof typeof WebhookEventType];
-
-export const WebhookDeliveryStatus = {
-  PENDING: 'PENDING',
-  DELIVERED: 'DELIVERED',
-  FAILED: 'FAILED',
-} as const;
-
-export type WebhookDeliveryStatusType = typeof WebhookDeliveryStatus[keyof typeof WebhookDeliveryStatus];
-
-export type Webhook = {
-  id: string;
-  merchantId: string;
-  url: string;
-  events: WebhookEventTypeValue[];
-  active: boolean;
-  createdAt: string;
-  updatedAt: string;
-  // Note: secret is only returned on creation
-};
-
-export type WebhookWithSecret = Webhook & {
-  secret: string;
-};
-
-export type WebhookDelivery = {
-  id: string;
-  webhookId: string;
-  eventType: WebhookEventTypeValue;
-  eventId: string;
-  status: WebhookDeliveryStatusType;
-  attempts: number;
-  lastAttemptAt?: string | null;
-  nextRetryAt?: string | null;
-  responseCode?: number | null;
-  createdAt: string;
-};
-
-export type WebhookPayload = {
-  id: string;
-  type: WebhookEventTypeValue;
-  timestamp: string;
-  environment: MerchantEnvironmentType;
-  data: {
-    session: CheckoutSession;
-    order?: Order | null;
-    txHash?: string | null;
-    error?: {
-      code: string;
-      message: string;
-    } | null;
-  };
-};
-
-// Webhook management API types
-export type CreateWebhookRequest = {
-  url: string;
-  events?: WebhookEventTypeValue[];
-};
-
-export type CreateWebhookResponse = WebhookWithSecret;
-
-export type UpdateWebhookRequest = {
-  url?: string;
-  events?: WebhookEventTypeValue[];
-  active?: boolean;
-};
-
-export type ListWebhooksResponse = {
-  webhooks: Webhook[];
-};
-
-export type ListWebhookDeliveriesResponse = {
-  deliveries: WebhookDelivery[];
-};
-
-export type TestWebhookResponse = {
-  success: boolean;
-  deliveryId: string;
-  responseCode?: number | null;
-  error?: string | null;
-};