azirid-react 0.9.5 → 0.9.8

package/README.md

@@ -1,8 +1,8 @@
 # azirid-react
 
-Authentication components and hooks for React and Next.js — powered by [TanStack Query](https://tanstack.com/query) and [Zod](https://zod.dev).
+Authentication, billing, and referral components and hooks for React and Next.js — powered by [TanStack Query](https://tanstack.com/query) and [Zod](https://zod.dev).
 
-Drop-in `<LoginForm>`, `<SignupForm>` and more, **or** use the headless hooks to build fully custom UIs.
+Drop-in `<LoginForm>`, `<SignupForm>`, `<PayButton>` and more, **or** use the headless hooks to build fully custom UIs.
 
 ## Installation
 
@@ -715,6 +715,115 @@ 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.