@bloque/payments-react 0.0.2

package/README.md

@@ -0,0 +1,319 @@
+# @bloque/payments-react
+
+React wrapper for `@bloque/payments-elements` web components.
+
+## Installation
+
+```bash
+# Using bun
+bun add @bloque/payments-react
+
+# Using pnpm
+pnpm add @bloque/payments-react
+
+# Using npm
+npm install @bloque/payments-react
+
+# Using yarn
+yarn add @bloque/payments-react
+```
+
+## Usage
+
+### How it Works
+
+```
+┌─────────────────┐      ┌─────────────────┐      ┌──────────────┐
+│ React Component │─────▶│  Your Backend   │─────▶│  Bloque API  │
+│  (Frontend)     │      │   (SDK Usage)   │      │              │
+└─────────────────┘      └─────────────────┘      └──────────────┘
+```
+
+1. **React Component** captures payment data from user
+2. **`onSubmit`** sends complete `PaymentSubmitPayload` to your backend
+3. **Your Backend** uses `@bloque/payments` to process the payment
+
+### Basic Example
+
+```tsx
+import { BloqueCheckout } from '@bloque/payments-react';
+import type { PaymentSubmitPayload } from '@bloque/payments-react';
+
+function App() {
+  const handleSubmit = async (payload: PaymentSubmitPayload) => {
+    const response = await fetch('/api/payments', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      throw new Error('Payment failed');
+    }
+
+    return response.json();
+  };
+
+  return (
+    <BloqueCheckout
+      onSubmit={handleSubmit}
+      requireEmail={true}
+    />
+  );
+}
+```
+
+**Your Backend (using `@bloque/payments`):**
+
+```typescript
+import { Bloque } from '@bloque/payments';
+
+const bloque = new Bloque({
+  apiKey: process.env.BLOQUE_API_KEY!,
+  server: 'production',
+});
+
+app.post('/api/payments', async (req, res) => {
+  const payload = req.body;
+
+  const payment = await bloque.payments.create({
+    payment: payload,
+  });
+
+  res.json(payment);
+});
+```
+
+### With Configuration and Appearance
+
+```tsx
+import { BloqueCheckout } from '@bloque/payments-react';
+import type {
+  CheckoutConfig,
+  AppearanceConfig,
+  PaymentSubmitPayload,
+} from '@bloque/payments-react';
+
+function CheckoutPage() {
+  const config: CheckoutConfig = {
+    payment_methods: ['card', 'pse'],
+    amount: 120_000,
+    currency: 'COP',
+  };
+
+  const appearance: AppearanceConfig = {
+    primaryColor: '#10b981',
+    borderRadius: '12px',
+    fontFamily: 'Inter, system-ui, sans-serif',
+  };
+
+  const handleSubmit = async (payload: PaymentSubmitPayload) => {
+    const response = await fetch('/api/payments', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      throw new Error('Payment failed');
+    }
+
+    return response.json();
+  };
+
+  const handleSuccess = (event: CustomEvent<PaymentSubmitPayload>) => {
+    console.log('Payment successful!', event.detail);
+    window.location.href = '/success';
+  };
+
+  const handleError = (event: CustomEvent<PaymentSubmitPayload & { error: string }>) => {
+    console.error('Payment failed:', event.detail.error);
+  };
+
+  return (
+    <BloqueCheckout
+      config={config}
+      appearance={appearance}
+      onSubmit={handleSubmit}
+      onSuccess={handleSuccess}
+      onError={handleError}
+    />
+  );
+}
+```
+
+### With Custom Styling
+
+```tsx
+import { BloqueCheckout } from '@bloque/payments-react';
+
+function App() {
+  return (
+    <div className="checkout-container">
+      <BloqueCheckout
+        onSubmit={handleSubmit}
+        className="custom-checkout"
+        style={{ maxWidth: '600px', margin: '0 auto' }}
+      />
+    </div>
+  );
+}
+```
+
+## Props
+
+### `BloqueCheckout`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `config` | `CheckoutConfig` | `undefined` | Configuration object from backend SDK |
+| `appearance` | `AppearanceConfig` | `undefined` | Appearance customization |
+| `amount` | `number` | `undefined` | Payment amount (can also be set via `config.amount`) |
+| `availableMethods` | `PaymentMethodType[]` | `['card', 'pse', 'cash']` | Available payment methods |
+| `requireEmail` | `boolean` | `true` | Whether email is required for card payments |
+| `showMethodSelector` | `boolean` | `true` | Whether to show the payment method selector |
+| `onSubmit` | `function` | `undefined` | Function called when user submits payment |
+| `onSuccess` | `function` | `undefined` | Event handler for successful payment |
+| `onError` | `function` | `undefined` | Event handler for payment errors |
+| `className` | `string` | `undefined` | CSS class name |
+| `style` | `React.CSSProperties` | `undefined` | Inline styles |
+
+### `CheckoutConfig`
+
+```typescript
+interface CheckoutConfig {
+  payment_methods?: PaymentMethodType[];
+  amount?: number;
+  currency?: string;
+}
+```
+
+### `AppearanceConfig`
+
+```typescript
+interface AppearanceConfig {
+  primaryColor?: string;
+  borderRadius?: string;
+  fontFamily?: string;
+}
+```
+
+## TypeScript
+
+The package includes full TypeScript definitions with discriminated union types for type safety:
+
+```typescript
+import type {
+  BloqueCheckoutProps,
+  PaymentSubmitPayload,
+  CheckoutConfig,
+  AppearanceConfig,
+} from '@bloque/payments-react';
+
+// PaymentSubmitPayload is a discriminated union type
+// TypeScript automatically narrows the type based on the 'type' field
+const handleSubmit = async (payload: PaymentSubmitPayload) => {
+  // Type narrowing example
+  switch (payload.type) {
+    case 'card':
+      // payload.data is CardPaymentFormData
+      console.log('Card ending in:', payload.data.cardNumber.slice(-4));
+      break;
+    case 'pse':
+      // payload.data is PSEPaymentFormData
+      console.log('Bank:', payload.data.bankCode);
+      break;
+    case 'cash':
+      // payload.data is CashPaymentFormData
+      console.log('Name:', payload.data.fullName);
+      break;
+  }
+
+  // Send complete payload to your backend
+  const response = await fetch('/api/payments', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  return response.json();
+};
+```
+
+## Events
+
+### `onSubmit`
+
+Called when the user submits a payment form. Send the complete payload to your backend, which will use `@bloque/payments` to process the payment.
+
+```typescript
+onSubmit?: (payload: PaymentSubmitPayload) => Promise<void>;
+```
+
+**Example:**
+```typescript
+const handleSubmit = async (payload: PaymentSubmitPayload) => {
+  const response = await fetch('/api/payments', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) throw new Error('Payment failed');
+  return response.json();
+};
+```
+
+**Type definition:**
+```typescript
+type PaymentSubmitPayload =
+  | { type: 'card'; data: CardPaymentFormData }
+  | { type: 'pse'; data: PSEPaymentFormData }
+  | { type: 'cash'; data: CashPaymentFormData };
+```
+
+**Your backend should:**
+```typescript
+import { Bloque } from '@bloque/payments';
+
+const bloque = new Bloque({
+  apiKey: process.env.BLOQUE_API_KEY!,
+  server: 'production',
+});
+
+app.post('/api/payments', async (req, res) => {
+  const payload = req.body;
+
+  const payment = await bloque.payments.create({
+    payment: payload,
+  });
+
+  res.json(payment);
+});
+```
+
+### `onSuccess`
+
+Fired when the payment is successfully processed.
+
+```typescript
+onSuccess?: (event: CustomEvent<PaymentSubmitPayload>) => void;
+```
+
+### `onError`
+
+Fired when payment processing fails.
+
+```typescript
+onError?: (event: CustomEvent<PaymentSubmitPayload & { error: string }>) => void;
+```
+
+## Payment Methods
+
+- **Card** - Credit and debit card payments
+- **PSE** - Colombian online banking system
+- **Cash** - Generate receipt for cash payment at physical locations
+
+## License
+
+[MIT](../../LICENSE)

package/dist/bloque-checkout.d.ts

@@ -0,0 +1,25 @@
+import '@bloque/payments-elements';
+import type { AppearanceConfig, CheckoutConfig, PaymentMethodType, PaymentSubmitPayload } from '@bloque/payments-elements';
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            'bloque-checkout': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement>;
+        }
+    }
+}
+export interface BloqueCheckoutProps {
+    config?: CheckoutConfig;
+    appearance?: AppearanceConfig;
+    amount?: number;
+    availableMethods?: PaymentMethodType[];
+    requireEmail?: boolean;
+    showMethodSelector?: boolean;
+    onSubmit?: (payload: PaymentSubmitPayload) => Promise<void>;
+    onSuccess?: (event: CustomEvent<PaymentSubmitPayload>) => void;
+    onError?: (event: CustomEvent<PaymentSubmitPayload & {
+        error: string;
+    }>) => void;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare function BloqueCheckout({ config, appearance, amount, availableMethods, requireEmail, showMethodSelector, onSubmit, onSuccess, onError, className, style, }: BloqueCheckoutProps): import("react/jsx-runtime").JSX.Element;

package/dist/bloque-checkout.js

@@ -0,0 +1,50 @@
+import { jsx } from "react/jsx-runtime";
+import "@bloque/payments-elements";
+import { useEffect, useRef } from "react";
+function BloqueCheckout({ config, appearance, amount, availableMethods, requireEmail = true, showMethodSelector = true, onSubmit, onSuccess, onError, className, style }) {
+    const checkoutRef = useRef(null);
+    useEffect(()=>{
+        const element = checkoutRef.current;
+        if (!element) return;
+        if (config) element.config = config;
+        if (appearance) element.appearance = appearance;
+        if (void 0 !== amount) element.amount = amount;
+        if (availableMethods) element.availableMethods = availableMethods;
+        element.requireEmail = requireEmail;
+        element.showMethodSelector = showMethodSelector;
+        if (onSubmit) element.onSubmit = onSubmit;
+    }, [
+        config,
+        appearance,
+        amount,
+        availableMethods,
+        requireEmail,
+        showMethodSelector,
+        onSubmit
+    ]);
+    useEffect(()=>{
+        const element = checkoutRef.current;
+        if (!element) return;
+        const handleSuccess = (event)=>{
+            if (onSuccess) onSuccess(event);
+        };
+        const handleError = (event)=>{
+            if (onError) onError(event);
+        };
+        element.addEventListener('payment-success', handleSuccess);
+        element.addEventListener('payment-error', handleError);
+        return ()=>{
+            element.removeEventListener('payment-success', handleSuccess);
+            element.removeEventListener('payment-error', handleError);
+        };
+    }, [
+        onSuccess,
+        onError
+    ]);
+    return /*#__PURE__*/ jsx("bloque-checkout", {
+        ref: checkoutRef,
+        className: className,
+        style: style
+    });
+}
+export { BloqueCheckout };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { AppearanceConfig, CheckoutConfig, PaymentSubmitPayload, } from '@bloque/payments-elements';
+export type { BloqueCheckoutProps } from './bloque-checkout';
+export { BloqueCheckout } from './bloque-checkout';

package/dist/index.js

@@ -0,0 +1,2 @@
+import { BloqueCheckout } from "./bloque-checkout.js";
+export { BloqueCheckout };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@bloque/payments-react",
+  "version": "0.0.2",
+  "description": "React wrapper for Bloque payments web components",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "react",
+    "payments",
+    "checkout",
+    "bloque",
+    "colombia",
+    "pse",
+    "card",
+    "cash"
+  ],
+  "author": "Nestor Cortina <nexckycort@gmail.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "rslib build",
+    "clean": "rm -rf node_modules && rm -rf dist",
+    "check": "biome check --write",
+    "dev": "rslib build --watch",
+    "storybook": "storybook dev",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@bloque/payments-elements": "workspace:*"
+  },
+  "devDependencies": {
+    "@rsbuild/core": "catalog:",
+    "@rsbuild/plugin-react": "^1.4.2",
+    "@rslib/core": "catalog:",
+    "@storybook/addon-docs": "^10.1.4",
+    "@storybook/addon-onboarding": "^10.1.4",
+    "@storybook/react": "^10.1.4",
+    "@types/react": "^19.2.7",
+    "@typescript/native-preview": "catalog:",
+    "react": "^19.2.1",
+    "storybook": "^10.1.4",
+    "storybook-addon-rslib": "^3.1.0",
+    "storybook-react-rsbuild": "^3.1.0",
+    "typescript": "catalog:"
+  },
+  "peerDependencies": {
+    "react": ">=16.9.0",
+    "react-dom": ">=16.9.0"
+  },
+  "homepage": "git+https://github.com/bloque-app/payments.git#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bloque-app/payments.git",
+    "directory": "packages/payments-react"
+  }
+}