@flopay/vue 0.0.0-stage → 1.13.1

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# @flopay/vue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vue 3 components and composables for FloPay checkout, card setup and one-click payments: the Vue counterpart of `@flopay/react`, with the same props, events and behaviour.
+
+## Installation
+
+```bash
+npm install @flopay/vue
+```
+
+`vue` (`>=3.3.0`) is a peer dependency. `@flopay/js` and `@flopay/shared` are installed with the package.
+
+## Usage
+
+Render `FloPayCheckout` with a session the merchant server created, or with an inline `createSession` draft. Notification callbacks are Vue events: React's `onComplete` is `@complete` in templates and `onComplete` in `h()`.
+
+```ts
+import { FloPayCheckout } from '@flopay/vue';
+import { h } from 'vue';
+
+export default {
+  setup() {
+    return () =>
+      h(FloPayCheckout, {
+        sessionId: 'sess_123',
+        nonce: 'nonce_123',
+        onComplete: (result) => console.log(result.status),
+        onDecline: (decline) => console.log(decline.message),
+      });
+  },
+};
+```
+
+Browser work (session reads, SDK loading, the hosted card widget) starts in `onMounted`, so server rendering never touches `window` and renders the loading state.
+
+## Examples
+
+Card setup from the Stripe-free subpath:
+
+```ts
+import { FloPayCardSetup } from '@flopay/vue/card-setup';
+import { h } from 'vue';
+
+const render = () =>
+  h(FloPayCardSetup, {
+    sessionId: 'sess_setup_123',
+    nonce: 'nonce_setup_123',
+    onComplete: (event) => console.log(event.sessionId),
+  });
+```
+
+One-click payment with the buyer's saved payment method:
+
+```ts
+import { FloPayAutomaticPaymentButton } from '@flopay/vue';
+import { h } from 'vue';
+
+const render = () =>
+  h(FloPayAutomaticPaymentButton, {
+    clientId: 'client_123',
+    account: { userId: 'user_123', email: 'buyer@example.com' },
+    products: [{ code: 'pro-monthly', quantity: 1 }],
+    successUrl: 'https://example.com/success',
+    cancelUrl: 'https://example.com/cancel',
+    onSuccess: (event) => console.log(event.autoCompleted),
+  });
+```
+
+## Public API
+
+Every `@flopay/react` component and hook has a same-name Vue export. React's notification callbacks are Vue events with the same payloads.
+
+| Export | React (`@flopay/react`) | Vue (`@flopay/vue`) |
+|--------|-------------------------|---------------------|
+| `FloPayProvider` | `<FloPayProvider>` | `FloPayProvider`, provided to descendants; `@instrument` |
+| `FloPayCheckout` | `<FloPayCheckout>` | `FloPayCheckout`: `@complete`, `@decline`, `@error`, `@button-click` |
+| `SplitCardForm` | `<SplitCardForm>` | `SplitCardForm`: `@complete`, `@decline`, `@error` |
+| `VaultCardFields` | `<VaultCardFields>` | `VaultCardFields`: `@ready`, `@error`, `@validation` |
+| `DirectPayPalButton` | `<DirectPayPalButton>` | `DirectPayPalButton` |
+| `FloPayAutomaticPaymentButton` | `<FloPayAutomaticPaymentButton>` | `FloPayAutomaticPaymentButton`: `@success`, `@error`, `@decline` |
+| `FloPayCardSetup` | `<FloPayCardSetup>` | `FloPayCardSetup`: `@ready`, `@complete`, `@decline`, `@cancel`, `@error` |
+| `FloPayPaymentMethodSetup` | `<FloPayPaymentMethodSetup>` | `FloPayPaymentMethodSetup` |
+| `useFloPay` | `useFloPay()` | `useFloPay()`: a ref, `null` until `loadFloPay()` resolves |
+| `usePayPalFloPay` | `usePayPalFloPay()` | `usePayPalFloPay()`: a ref |
+| `useCheckout` | `useCheckout()` | `useCheckout()`: a reactive checkout state |
+| `FloPayCardSetupError` | `FloPayCardSetupError` | `FloPayCardSetupError` |
+| `dropThirdPartyOnlyError` | `dropThirdPartyOnlyError` | `dropThirdPartyOnlyError` |
+
+React `children` and custom layouts are slots. `FloPayCheckout`'s `layout` slot replaces the built-in form, and a `SplitCardForm` inside it receives the session, nonce and `submitLabel` unless it sets them itself.
+
+Entry points: `@flopay/vue`, `@flopay/vue/card-setup` and `@flopay/vue/payment-method-setup`.
+
+## Errors
+
+Errors are `FloPayError` instances from `@flopay/shared`, emitted through `@error`.
+
+| Code | Meaning |
+|------|---------|
+| `UnsupportedBackendVaultCapability` | The session has no hosted vault card form and no other usable method. |
+| `stored_payment_method_unsupported` | The buyer's saved method cannot be charged; ask for another method. |
+| `MissingCheckoutSessionToken` | A session id was given without its `nonce`. |
+
+Setup surfaces emit `FloPayCardSetupError`, whose `retryable` says whether trying again can help.