azirid-react 0.9.4 → 0.9.7

package/README.md

@@ -667,6 +667,163 @@ const { data: proofs } = useTransferProofs()
 // [{ id, status: 'PENDING_REVIEW' | 'APPROVED' | 'REJECTED', ... }]
 ```
 
+### `usePayphoneCheckout`
+
+Hook that returns a **renderable widget component** and **payment status**. Pass an `intentId` and get full control over where the widget renders and how to react to the payment result.
+
+```tsx
+import { usePayphoneCheckout } from 'azirid-react'
+
+function CheckoutPage({ intentId }: { intentId: string }) {
+  const { PayphoneWidget, status, error } = usePayphoneCheckout({
+    intentId,
+    onSuccess: (data) => {
+      // data: { status: 'confirmed' | 'cancelled' | 'already_confirmed', intentId: string }
+      console.log('Payment result:', data.status)
+    },
+    onError: (err) => console.error(err),
+  })
+
+  return (
+    <div>
+      <h1>Pay</h1>
+      <PayphoneWidget />
+      {status === 'loading' && <p>Preparing checkout...</p>}
+      {status === 'confirming' && <p>Confirming payment...</p>}
+      {status === 'confirmed' && <p>Payment confirmed!</p>}
+      {status === 'cancelled' && <p>Payment was cancelled</p>}
+      {status === 'error' && <p>Error: {error?.message}</p>}
+    </div>
+  )
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `intentId` | `string` | **Required.** Payment intent ID |
+| `onSuccess` | `(data) => void` | Called after payment confirmation |
+| `onError` | `(error) => void` | Called on any error |
+
+| Return | Type | Description |
+|--------|------|-------------|
+| `PayphoneWidget` | `() => ReactElement \| null` | Component to render the Payphone widget |
+| `status` | `PayphoneCheckoutStatus` | `'idle' \| 'loading' \| 'ready' \| 'confirming' \| 'confirmed' \| 'cancelled' \| 'error'` |
+| `intentId` | `string` | The intent ID passed in |
+| `error` | `Error \| null` | Error details if status is `'error'` |
+
+The hook handles both phases automatically:
+1. **Widget phase**: Calls checkout API, loads Payphone SDK, widget renders via `<PayphoneWidget />`.
+2. **Confirmation phase**: After Payphone redirects back (same page), detects URL params and confirms the payment.
+
+### `usePayButton`
+
+Hook that returns **renderable components** and **state** for a complete payment flow. Supports all providers (Stripe, PayPal, Payphone, Manual Transfer, Nuvei). You control the layout.
+
+```tsx
+import { usePayButton } from 'azirid-react'
+
+function CheckoutPage({ intentId }: { intentId: string }) {
+  const {
+    providers, checkout, ProviderSelector,
+    TransferDetails, PayphoneWidget, status, error,
+  } = usePayButton({
+    intentId,
+    onSuccess: (data) => console.log('Paid!', data),
+    onError: (err) => console.error(err),
+  })
+
+  return (
+    <div>
+      {/* Option A: built-in provider selector */}
+      <ProviderSelector />
+
+      {/* Option B: custom UI with providers array */}
+      {providers.map(p => (
+        <button key={p.provider} onClick={() => checkout(p.provider)}>
+          {p.provider}
+        </button>
+      ))}
+
+      {/* Renders automatically based on selected provider */}
+      <PayphoneWidget />
+      <TransferDetails />
+
+      {status === 'processing' && <p>Processing...</p>}
+      {status === 'redirecting' && <p>Redirecting to payment...</p>}
+      {status === 'error' && <p>Error: {error?.message}</p>}
+    </div>
+  )
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `intentId` | `string` | Payment intent ID |
+| `planId` | `string` | Plan ID (alternative to intentId) |
+| `onSuccess` | `(data) => void` | Called after successful payment |
+| `onError` | `(error) => void` | Called on any error |
+
+| Return | Type | Description |
+|--------|------|-------------|
+| `providers` | `AvailableProvider[]` | Enabled payment providers |
+| `checkout` | `(provider) => void` | Trigger checkout for a specific provider |
+| `ProviderSelector` | Component | Built-in provider selection list |
+| `TransferDetails` | Component | Bank transfer details (after MANUAL_TRANSFER checkout) |
+| `PayphoneWidget` | Component | Payphone widget (after PAYPHONE checkout) |
+| `status` | `PayButtonStatus` | `'idle' \| 'loading_providers' \| 'ready' \| 'processing' \| 'redirecting' \| 'success' \| 'error'` |
+| `selectedProvider` | `PaymentProviderType \| null` | Currently selected provider |
+| `checkoutData` | `CheckoutResponse \| null` | Full checkout response |
+| `isPending` | `boolean` | Checkout API call in progress |
+| `error` | `Error \| null` | Error details |
+
+### `useTransferPayment`
+
+Hook for manual bank transfer payments. Pass an `intentId` and get a component with bank details + a function to submit proof of payment.
+
+```tsx
+import { useTransferPayment } from 'azirid-react'
+
+function TransferPage({ intentId }: { intentId: string }) {
+  const { TransferDetails, submitProof, status, error } = useTransferPayment({
+    intentId,
+    onProofSubmitted: (proof) => console.log('Proof sent:', proof.id),
+    onError: (err) => console.error(err),
+  })
+
+  return (
+    <div>
+      <TransferDetails />
+      {status === 'ready' && (
+        <button onClick={() => submitProof({
+          fileUrl: 'https://...', amount: 29.99, notes: 'Transfer ref #123'
+        })}>
+          Submit proof
+        </button>
+      )}
+      {status === 'submitting' && <p>Submitting...</p>}
+      {status === 'submitted' && <p>Proof submitted!</p>}
+      {status === 'error' && <p>Error: {error?.message}</p>}
+    </div>
+  )
+}
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `intentId` | `string` | **Required.** Payment intent ID |
+| `onSuccess` | `(data) => void` | Called after checkout completes |
+| `onProofSubmitted` | `(proof) => void` | Called after proof is submitted |
+| `onError` | `(error) => void` | Called on any error |
+
+| Return | Type | Description |
+|--------|------|-------------|
+| `TransferDetails` | Component | Amount, bank details, and transfer instructions |
+| `submitProof` | `(data) => void` | Submit transfer proof (fileUrl, amount, notes, etc.) |
+| `status` | `TransferPaymentStatus` | `'idle' \| 'loading' \| 'ready' \| 'submitting' \| 'submitted' \| 'error'` |
+| `checkoutData` | `CheckoutResponse \| null` | Full checkout response |
+| `isSubmitting` | `boolean` | Proof submission in progress |
+| `error` | `Error \| null` | Error details |
+
 ### `usePayphoneConfirm`
 
 Confirm a Payphone payment callback. Used on the Payphone return URL page.
@@ -1564,6 +1721,7 @@ import type {
 | `UsePasswordResetOptions` / `UsePasswordResetReturn`   | Options and return type for `usePasswordReset()`   |
 | `UseCheckoutOptions` / `CheckoutParams`                | Options and params for `useCheckout()`             |
 | `UsePayphoneConfirmOptions` / `PayphoneConfirmParams`  | Options and params for `usePayphoneConfirm()`      |
+| `PayphoneCheckoutProps`                                | Props for `PayphoneCheckout` component              |
 | `SimpleMutationOptions<T>`                             | Options for hooks created via `createMutationHook` |
 | `MutationHookConfig<TData, TInput>`                    | Configuration for `createMutationHook()`           |