@kasuvia/sdk 0.0.8 → 0.0.9

package/src/services/payment.service.ts

@@ -1,18 +1,55 @@
 /**
  * Payment Service
- * 
- * Customer-facing payment API for payment initiation and verification.
+ *
+ * Customer-facing payment API for payment initiation and verification via
+ * kasuvia-payment-system-go.
  * Stateless - all configuration passed as parameters.
  */
 import type { SdkConfig } from '../config'
 import type {
-  ConversionQuote,
   DVACreateRequest,
   DVADetails,
+  GatewayMethods,
   PaymentInitiateRequest,
   PaymentInitiateResponse,
   TransactionVerifyResponse,
+  WalletBalanceResponse,
+  WalletLedgerResponse,
 } from '../types/payments/index'
+import { apiRequest, storefrontHeaders, authHeaders, JSON_HEADERS } from '../utils/http-client'
+
+function isValidUUID(str: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(str)
+}
+
+/**
+ * Fetch available payment methods and gateways for a storefront region.
+ *
+ * REAL BUG FIXED (2026-09-22): `currency`/`countryCode` used to default to
+ * 'NGN'/'NG' as SDK-level JS defaults — an independent copy of a value the
+ * real backend already declares itself (`query:"currency" default:"NGN"` /
+ * `query:"country_code" default:"NG"`, kasuvia-payment-system-go's own real,
+ * documented default for this route). Duplicating it client-side risks the
+ * two silently drifting apart if the backend's real default is ever
+ * changed. Now optional with no client-side default at all — when omitted,
+ * the query param is left out entirely and the backend's own declared
+ * default applies, the single source of truth for what "unspecified"
+ * means here.
+ */
+export async function getAvailablePaymentMethods(
+  config: SdkConfig,
+  currency?: string,
+  countryCode?: string
+): Promise<GatewayMethods[]> {
+  const params: Record<string, string> = {}
+  if (currency) params.currency = currency
+  if (countryCode) params.country_code = countryCode
+  const query = new URLSearchParams(params).toString()
+  return apiRequest<GatewayMethods[]>(`${config.backendUrls.payment}/payments/storefront/methods${query ? `?${query}` : ''}`, {
+    headers: storefrontHeaders(config),
+    fallbackErrorMessage: 'Failed to fetch available payment methods',
+  })
+}
 
 /**
  * Create a Monnify Dedicated Virtual Account so the customer can pay via
@@ -21,77 +58,82 @@ import type {
  */
 export async function createDedicatedAccount(
   config: SdkConfig,
-  accessToken: string,
+  accessToken: string | null | undefined,
   request: DVACreateRequest
 ): Promise<DVADetails> {
-  const isValidUUID = (str: string) => {
-    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-    return uuidRegex.test(str);
+  const origin = request.storefront_origin || (typeof window !== 'undefined' ? window.location.origin : '');
+
+  const headers: Record<string, string> = { ...JSON_HEADERS, ...storefrontHeaders(config) }
+  if (accessToken) {
+    headers["Authorization"] = `Bearer ${accessToken}`
+  }
+  if (origin) {
+    headers["Origin"] = origin
   }
 
-  const response = await fetch(`${config.backendUrls.payment}/payments/dedicated-account`, {
+  return apiRequest<DVADetails>(`${config.backendUrls.payment}/payments/storefront/dedicated-account`, {
     method: 'POST',
-    headers: { 
-      'Content-Type': 'application/json',
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+    headers,
     body: JSON.stringify({
       order_id: request.order_id && isValidUUID(request.order_id) ? request.order_id : undefined,
       amount: request.amount,
       customer_email: request.customer_email,
       customer_name: request.customer_name,
       currency: request.currency,
+      gateway: request.gateway,
       idempotency_key: request.idempotency_key,
     }),
+    fallbackErrorMessage: 'Failed to create dedicated account',
   })
-  if (!response.ok) throw new Error('Failed to create dedicated account')
-  const data = await response.json()
-  return data
 }
 
 /**
- * Initiate a card payment (customer → business owner).
- * Routes to Monnify (NGN) or Flutterwave (non-NGN) on the backend.
+ * Initiate a payment (customer → business owner).
+ * Routes to Monnify, Flutterwave, or Paystack on the backend based on region/selection.
  * Returns a checkout_url to redirect the customer to the gateway.
  */
 export async function initiatePayment(
   config: SdkConfig,
-  accessToken: string,
+  accessToken: string | null | undefined,
   request: PaymentInitiateRequest
 ): Promise<PaymentInitiateResponse> {
-  const isValidUUID = (str: string) => {
-    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-    return uuidRegex.test(str);
-  }
-
   const validOrderId = request.order_id && isValidUUID(request.order_id) ? request.order_id : undefined;
+  const origin = request.storefront_origin || (typeof window !== 'undefined' ? window.location.origin : '');
 
-  const response = await fetch(`${config.backendUrls.payment}/payments/storefront/initiate`, {
-    method: 'POST',
-    headers: { 
-      'Content-Type': 'application/json',
-      "Authorization": `Bearer ${accessToken}`,
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
-    body: JSON.stringify({
-      amount: request.amount,
-      currency: request.currency,
-      order_id: validOrderId,
-      quote_id: request.quote_id,
-      metadata_json: {
-        customer_email: request.customer_email,
-        customer_name: request.customer_name ?? '',
+  const headers: Record<string, string> = { ...JSON_HEADERS, ...storefrontHeaders(config) }
+  if (accessToken) {
+    headers["Authorization"] = `Bearer ${accessToken}`
+  }
+  if (origin) {
+    headers["Origin"] = origin
+  }
+
+  const data = await apiRequest<PaymentInitiateResponse & { metadata_json?: { checkout_url?: string } }>(
+    `${config.backendUrls.payment}/payments/storefront/initiate`,
+    {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        amount: request.amount,
+        currency: request.currency,
+        // Same real backend default as getAvailablePaymentMethods above
+        // (huma's own `default:"NG"` on this field) — omit rather than
+        // hardcode a client-side copy of it.
+        country_code: request.country_code,
+        gateway: request.gateway,
         order_id: validOrderId,
-        ...(request.metadata ?? {}),
-      },
-      idempotency_key: request.idempotency_key,
-    }),
-  })
-  if (!response.ok) throw new Error('Failed to initiate payment')
-  const data = await response.json()
+        quote_id: request.quote_id,
+        metadata_json: {
+          customer_email: request.customer_email,
+          customer_name: request.customer_name ?? '',
+          order_id: validOrderId,
+          ...(request.metadata ?? {}),
+        },
+        idempotency_key: request.idempotency_key,
+      }),
+      fallbackErrorMessage: 'Failed to initiate payment',
+    }
+  )
 
   return {
     id: data.id,
@@ -103,80 +145,87 @@ export async function initiatePayment(
 }
 
 /**
- * Request a 15-minute rate-locked conversion quote for non-NGN transactions.
+ * Verify a payment after the gateway redirects back to /checkout/verify.
  */
-export async function requestQuote(
+export async function verifyTransaction(
   config: SdkConfig,
-  amount: number
-): Promise<ConversionQuote> {
-  const response = await fetch(`${config.backendUrls.payment}/payments/quote`, {
+  reference: string
+): Promise<TransactionVerifyResponse> {
+  return apiRequest<TransactionVerifyResponse>(`${config.backendUrls.payment}/payments/verify/${reference}`, {
     method: 'POST',
-    headers: { 
-      'Content-Type': 'application/json',
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
-    body: JSON.stringify({ amount }),
+    headers: { ...JSON_HEADERS, ...storefrontHeaders(config) },
+    fallbackErrorMessage: 'Failed to verify transaction',
   })
-  if (!response.ok) throw new Error('Failed to request quote')
-  const data = await response.json()
-  return data
 }
 
 /**
- * Verify a payment after the gateway redirects back to /checkout/verify.
+ * Poll transaction status by internal transaction ID.
  */
-export async function verifyTransaction(
-  configOrReference: SdkConfig | string,
-  reference?: string
+export async function getTransactionStatus(
+  config: SdkConfig,
+  transactionId: string
 ): Promise<TransactionVerifyResponse> {
-  if (typeof configOrReference === 'string') {
-    const ref = configOrReference
-    const response = await fetch(`/api/payments/verify/${ref}`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-    })
-    if (!response.ok) throw new Error('Failed to verify transaction')
-    return response.json()
-  }
+  return apiRequest<TransactionVerifyResponse>(`${config.backendUrls.payment}/payments/transactions/${transactionId}`, {
+    headers: storefrontHeaders(config),
+    fallbackErrorMessage: 'Failed to get transaction status',
+  })
+}
 
-  const config = configOrReference
-  const ref = reference || ''
-  const response = await fetch(`${config.backendUrls.payment}/payments/verify/${ref}`, {
-    method: 'POST',
-    headers: { 
-      'Content-Type': 'application/json',
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+/**
+ * Fetch authenticated customer's wallet balance.
+ */
+export async function getWalletBalance(
+  config: SdkConfig,
+  accessToken: string
+): Promise<WalletBalanceResponse> {
+  return apiRequest<WalletBalanceResponse>(`${config.backendUrls.payment}/wallet/balance`, {
+    headers: authHeaders(config, accessToken),
+    fallbackErrorMessage: 'Failed to fetch wallet balance',
   })
-  if (!response.ok) throw new Error('Failed to verify transaction')
-  const data = await response.json()
-  return data
 }
 
 /**
- * Poll transaction status by internal transaction ID.
+ * Fetch authenticated customer's wallet ledger (transaction history).
  */
-export async function getTransactionStatus(
+export async function getWalletLedger(
   config: SdkConfig,
-  transactionId: string
-): Promise<TransactionVerifyResponse> {
-  const response = await fetch(`${config.backendUrls.payment}/payments/transactions/${transactionId}`, {
-    headers: { 
-      "X-Storefront-Key": config.storefrontApiKey,
-      "X-Business-ID": config.businessId,
-    },
+  accessToken: string,
+  params?: { page?: number; page_size?: number }
+): Promise<WalletLedgerResponse> {
+  const page = params?.page ?? 1
+  const pageSize = params?.page_size ?? 20
+  return apiRequest<WalletLedgerResponse>(
+    `${config.backendUrls.payment}/wallet/ledger?page=${page}&page_size=${pageSize}`,
+    {
+      headers: authHeaders(config, accessToken),
+      fallbackErrorMessage: 'Failed to fetch wallet ledger',
+    }
+  )
+}
+
+/**
+ * Claim a pending guest wallet credit into the authenticated customer's wallet.
+ */
+export async function claimWalletCredit(
+  config: SdkConfig,
+  accessToken: string,
+  claimToken: string
+): Promise<WalletBalanceResponse> {
+  return apiRequest<WalletBalanceResponse>(`${config.backendUrls.payment}/wallet/claim`, {
+    method: 'POST',
+    headers: { ...JSON_HEADERS, ...authHeaders(config, accessToken) },
+    body: JSON.stringify({ claim_token: claimToken }),
+    fallbackErrorMessage: 'Failed to claim wallet credit',
   })
-  if (!response.ok) throw new Error('Failed to get transaction status')
-  const data = await response.json()
-  return data
 }
 
 export const paymentService = {
+  getAvailablePaymentMethods,
   createDedicatedAccount,
   initiatePayment,
-  requestQuote,
   verifyTransaction,
   getTransactionStatus,
+  getWalletBalance,
+  getWalletLedger,
+  claimWalletCredit,
 } as const