@vindhq/sloud-payment-sdk 1.0.0

package/README.md

@@ -0,0 +1,398 @@
+# Sloud Payment SDK
+
+A secure, embeddable payment widget built in React, usable in **any JavaScript application** (React, Angular, Vue, or vanilla JS). Ships with **ESM builds** for easy integration.
+
+---
+
+## Features
+
+- **Developer-friendly**: authored in React for easy maintenance and composability.
+- **Framework-agnostic**: works with React (peer dependency required).
+- **ESM build format** for modern npm/React apps.
+- **Bundled CSS** via PostCSS.
+- **Asset support** (SVG icons) included in the build.
+- **Built-in validation** using Formik and Yup.
+- **Toast notifications** via react-hot-toast.
+
+---
+
+## Installation
+
+```bash
+# Using npm
+npm install sloud-payment-sdk
+
+# Using yarn
+yarn add sloud-payment-sdk
+```
+
+**Note:** This widget has peer dependencies on React 19.1.1+. Make sure you have React and ReactDOM installed:
+
+```bash
+npm install react react-dom
+```
+
+---
+
+## Usage
+
+The payment widget supports three payment types: **external**, **storefront**, and **sloudfront**. Each type has its own set of required fields.
+
+### External Payment (Simple Payments)
+
+For straightforward payments with customer details:
+
+```tsx
+import PaymentWidget from "sloud-payment-sdk";
+
+const widget = new PaymentWidget({
+  type: "external",
+  public_key: "your-public-api-key",
+  amount: 10000, // Amount in smallest currency unit (e.g., kobo for NGN)
+  customer: {
+    first_name: "John",
+    last_name: "Doe",
+    phone_number: "+2348012345678",
+    email: "john.doe@example.com",
+  },
+  isLocalEnv: false, // Optional: set to true for local development
+});
+
+widget.showPopup();
+```
+
+### Storefront Payment (E-commerce Orders)
+
+For e-commerce orders with products and delivery:
+
+```tsx
+import PaymentWidget from "sloud-payment-sdk";
+
+const widget = new PaymentWidget({
+  type: "storefront",
+  public_key: "your-public-api-key",
+  slug: "my-store",
+  amount: 5000, // Additional amount (e.g., shipping fees)
+  discount: 1000, // Optional discount
+  channel: "delivery", // "pickup" or "delivery"
+  customer: {
+    first_name: "Jane",
+    last_name: "Smith",
+    phone_number: "+2348098765432",
+    email: "jane.smith@example.com",
+  },
+  delivery_details: {
+    street: "123 Main Street",
+    city: "Lagos",
+    state: "Lagos",
+    country: "Nigeria",
+    note: "Please call on arrival", // Optional
+  },
+  products: [
+    {
+      product_id: "prod_123",
+      quantity: 2,
+      variation: ["Large", "Blue"], // Optional
+    },
+    {
+      product_id: "prod_456",
+      quantity: 1,
+    },
+  ],
+});
+
+// Payment method will be selected by the user in the widget UI
+
+widget.showPopup();
+```
+
+### Sloudfront Payment (Manual Orders)
+
+For manual orders with existing transaction/customer/business IDs:
+
+```tsx
+import PaymentWidget from "sloud-payment-sdk";
+
+const widget = new PaymentWidget({
+  type: "sloudfront",
+  public_key: "your-public-api-key",
+  transaction_id: "txn_abc123",
+  customer_id: "cust_xyz789",
+  business_id: "biz_def456",
+  amount: 5000,
+  discount: 500,
+  channel: "pickup", // "pickup" or "delivery"
+  customer: {
+    first_name: "Alice",
+    last_name: "Johnson",
+    phone_number: "+2348011223344",
+    email: "alice.johnson@example.com",
+  },
+  delivery_details: {
+    street: "456 Oak Avenue",
+    city: "Abuja",
+    state: "FCT",
+    country: "Nigeria",
+  },
+  products: [
+    {
+      product_id: "prod_789",
+      quantity: 1,
+    },
+  ],
+});
+
+// Payment method will be selected by the user in the widget UI
+
+widget.showPopup();
+```
+
+---
+
+## API
+
+### `new PaymentWidget(options: PaymentWidgetOptions)`
+
+Creates a new payment widget instance.
+
+#### Common Options (All Payment Types)
+
+| Parameter | Type | Required | Description |
+| --------------- | --------- | -------- | -------------------------------------------------- |
+| `type` | `PaymentType` | Yes | Payment type: `"external"`, `"storefront"`, or `"sloudfront"` |
+| `public_key` | `string` | Yes | Your public API key for secure payments |
+| `isLocalEnv` | `boolean` | No | Set to `true` for local development environment |
+
+#### External Payment Options
+
+| Parameter | Type | Required | Description |
+| ---------- | --------- | -------- | ------------------------------------------ |
+| `amount` | `number` | Yes | Payment amount in smallest currency unit |
+| `customer` | `Customer` | Yes | Customer information object |
+
+#### Storefront Payment Options
+
+| Parameter | Type | Required | Description |
+| -------------------- | ------------------ | -------- | ------------------------------------------ |
+| `slug` | `string` | Yes | Store identifier |
+| `amount` | `number` | Yes | Additional amount (e.g., shipping fees) |
+| `discount` | `number` | No | Discount amount |
+| `channel` | `ChannelType` | Yes | Delivery channel: `"pickup"` or `"delivery"` |
+| `customer` | `Customer` | Yes | Customer information object |
+| `delivery_details` | `DeliveryDetails` | Yes | Delivery address and notes |
+| `products` | `Product[]` | Yes | Array of products in the order |
+
+**Note:** Payment method is selected by the user within the widget UI based on available payment options.
+
+#### Sloudfront Payment Options
+
+| Parameter | Type | Required | Description |
+| -------------------- | ------------------ | -------- | ------------------------------------------ |
+| `transaction_id` | `string` | Yes | Existing transaction ID |
+| `customer_id` | `string` | Yes | Existing customer ID |
+| `business_id` | `string` | Yes | Existing business ID |
+| `amount` | `number` | Yes | Additional amount |
+| `discount` | `number` | No | Discount amount |
+| `channel` | `ChannelType` | Yes | Delivery channel: `"pickup"` or `"delivery"` |
+| `customer` | `Customer` | Yes | Customer information object |
+| `delivery_details` | `DeliveryDetails` | Yes | Delivery address and notes |
+| `products` | `Product[]` | Yes | Array of products in the order |
+
+**Note:** Payment method is selected by the user within the widget UI based on available payment options.
+
+#### Type Definitions
+
+**Customer**
+```ts
+interface Customer {
+  first_name: string;
+  last_name: string;
+  phone_number: string;
+  email: string;
+}
+```
+
+**DeliveryDetails**
+```ts
+interface DeliveryDetails {
+  street: string;
+  city: string;
+  state: string;
+  country: string;
+  note?: string;
+}
+```
+
+**Product**
+```ts
+interface Product {
+  product_id: string;
+  quantity: number;
+  variation?: string[];
+}
+```
+
+**PaymentType**
+```ts
+type PaymentType = "external" | "storefront" | "sloudfront";
+```
+
+**ChannelType**
+```ts
+type ChannelType = "pickup" | "delivery";
+```
+
+#### Methods
+
+##### `showPopup()`
+
+Displays the payment widget popup modal.
+
+```ts
+widget.showPopup();
+```
+
+##### `hidePopup()`
+
+Hides and unmounts the payment widget popup.
+
+```ts
+widget.hidePopup();
+```
+
+---
+
+## Validation and Error Handling
+
+The SDK includes built-in validation for all payment types:
+
+```ts
+import {
+  PaymentWidget,
+  validatePaymentWidgetOptions,
+  PaymentWidgetValidationError,
+} from "sloud-payment-sdk";
+
+try {
+  const options = {
+    type: "external",
+    public_key: "pk_test_123",
+    amount: 10000,
+    customer: {
+      first_name: "John",
+      last_name: "Doe",
+      phone_number: "+2348012345678",
+      email: "invalid-email", // Invalid email format
+    },
+  };
+
+  // Validate before creating widget
+  validatePaymentWidgetOptions(options);
+
+  const widget = new PaymentWidget(options);
+  widget.showPopup();
+} catch (error) {
+  if (error instanceof PaymentWidgetValidationError) {
+    console.error("Validation error:", error.message);
+  }
+}
+```
+
+## Advanced Usage
+
+### Extensible Payload Builders
+
+The SDK uses a builder pattern for payment payloads and can be extended with custom payment types:
+
+```ts
+import {
+  buildPaymentInstrumentPayload,
+  registerPayloadBuilder,
+  getRegisteredPaymentTypes,
+} from "sloud-payment-sdk";
+
+// Get all registered payment types
+const types = getRegisteredPaymentTypes();
+console.log(types); // ["external", "storefront", "sloudfront"]
+
+// Build payload from options
+const payload = buildPaymentInstrumentPayload({
+  type: "external",
+  // ... other options
+});
+```
+
+### TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```ts
+import type {
+  PaymentWidgetOptions,
+  ExternalPaymentWidgetOptions,
+  StorefrontPaymentWidgetOptions,
+  SloudfrontPaymentWidgetOptions,
+  PaymentType,
+  ChannelType,
+  Customer,
+  DeliveryDetails,
+  Product,
+} from "sloud-payment-sdk";
+
+// TypeScript will enforce correct fields based on payment type
+const options: StorefrontPaymentWidgetOptions = {
+  type: "storefront",
+  public_key: "pk_test_123",
+  slug: "my-store",
+  // ... TypeScript ensures all required fields are present
+};
+```
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Run dev server with live reload
+yarn dev
+
+# Build production bundles
+yarn build
+```
+
+- Development server serves `dist` and `public` folders at `http://localhost:8080`.
+- Includes live reload for fast iteration.
+
+---
+
+## Folder Structure
+
+```
+Payment-Widget/
+├─ src/
+│  ├─ index.ts         # Entry point
+│  ├─ widget.ts        # Widget class
+│  ├─ components/      # React components
+│  └─ styles/          # SCSS/CSS files
+├─ dist/               # Bundled output (ESM, CJS, UMD)
+├─ public/             # Dev server HTML
+├─ rollup.config.ts    # Rollup configuration
+└─ package.json
+```
+
+---
+
+## Build Details
+
+- **ESM/CJS** → externalizes React for React apps.
+- **PostCSS** → injects and minifies CSS.
+- **Assets** → SVG/PNG handled automatically.
+
+---
+
+## License
+
+Specify your license here (e.g., MIT).
+
+---