@reevit/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Reevit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @reevit/core
+
+The foundation for all Reevit payment SDKs. It provides the shared API client, state machine logic, type definitions, and utility functions used by the React, Vue, and Svelte SDKs.
+
+## Installation
+
+```bash
+npm install @reevit/core
+```
+
+## Features
+
+- **ReevitAPIClient**: A lightweight, promise-based client for interacting with the Reevit backend.
+- **State Machine**: Framework-agnostic logic for managing checkout flows.
+- **Utilities**: Amount formatting, phone validation, network detection, and more.
+- **Types**: Comprehensive TypeScript definitions for the entire Reevit ecosystem.
+- **Styles**: Shared CSS for the "Unified Payment Widget" appearance.
+
+## Usage (Low-level API)
+
+If you're building a custom integration or another framework SDK, you can use the core components directly.
+
+### Interacting with the API
+
+```typescript
+import { ReevitAPIClient } from '@reevit/core';
+
+const client = new ReevitAPIClient({
+  publicKey: 'pk_test_xxx',
+});
+
+// Create a payment intent
+const { data, error } = await client.createPaymentIntent({
+  amount: 5000,
+  currency: 'GHS',
+  email: 'customer@example.com',
+}, 'card');
+
+if (data) {
+  console.log('Intent created:', data.id);
+}
+```
+
+### Using Utilities
+
+```typescript
+import { formatAmount, validatePhone, detectNetwork } from '@reevit/core';
+
+console.log(formatAmount(10000, 'GHS')); // "GH₵ 100.00"
+console.log(validatePhone('0241234567')); // true
+console.log(detectNetwork('0241234567')); // "mtn"
+```
+
+## License
+
+MIT © Reevit

package/dist/index.d.mts

@@ -0,0 +1,332 @@
+/**
+ * Reevit Core Types
+ * Shared type definitions for all Reevit SDKs
+ */
+type PaymentMethod = 'card' | 'mobile_money' | 'bank_transfer';
+type MobileMoneyNetwork = 'mtn' | 'vodafone' | 'airteltigo';
+type PSPType = 'paystack' | 'hubtel' | 'flutterwave' | 'stripe' | 'monnify' | 'mpesa';
+interface ReevitCheckoutConfig {
+    /** Your Reevit public key (pk_live_xxx or pk_test_xxx) */
+    publicKey: string;
+    /** Amount in the smallest currency unit (e.g., pesewas for GHS) */
+    amount: number;
+    /** Currency code (e.g., 'GHS', 'NGN', 'USD') */
+    currency: string;
+    /** Customer email address */
+    email?: string;
+    /** Customer phone number (required for mobile money) */
+    phone?: string;
+    /** Unique reference for this transaction */
+    reference?: string;
+    /** Additional metadata to attach to the payment */
+    metadata?: Record<string, unknown>;
+    /** Payment methods to display */
+    paymentMethods?: PaymentMethod[];
+}
+interface ReevitCheckoutCallbacks {
+    /** Called when payment is successful */
+    onSuccess?: (result: PaymentResult) => void;
+    /** Called when payment fails */
+    onError?: (error: PaymentError) => void;
+    /** Called when user closes the checkout */
+    onClose?: () => void;
+    /** Called when checkout state changes */
+    onStateChange?: (state: CheckoutState) => void;
+}
+type CheckoutState = 'idle' | 'loading' | 'ready' | 'method_selected' | 'processing' | 'success' | 'failed' | 'closed';
+interface PaymentResult {
+    /** Unique payment ID from Reevit */
+    paymentId: string;
+    /** Reference provided or generated */
+    reference: string;
+    /** Amount paid in smallest currency unit */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Payment method used */
+    paymentMethod: PaymentMethod;
+    /** PSP that processed the payment */
+    psp: string;
+    /** PSP's transaction reference */
+    pspReference: string;
+    /** Payment status */
+    status: 'success' | 'pending';
+    /** Any additional data from the PSP */
+    metadata?: Record<string, unknown>;
+}
+interface PaymentError {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Whether the error is recoverable (user can retry) */
+    recoverable?: boolean;
+    /** Original error from PSP if available */
+    originalError?: unknown;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+interface ReevitTheme {
+    /** Primary brand color */
+    primaryColor?: string;
+    /** Background color */
+    backgroundColor?: string;
+    /** Text color */
+    textColor?: string;
+    /** Border radius for inputs and buttons */
+    borderRadius?: string;
+    /** Font family to use */
+    fontFamily?: string;
+    /** Whether to use dark mode */
+    darkMode?: boolean;
+}
+interface PSPConfig {
+    id: string;
+    name: string;
+    supportedMethods: PaymentMethod[];
+    supportedCurrencies: string[];
+}
+interface MobileMoneyFormData {
+    phone: string;
+    network: MobileMoneyNetwork;
+}
+interface CardFormData {
+    /** Token from PSP's hosted fields */
+    token: string;
+    /** Last 4 digits for display */
+    last4?: string;
+    /** Card brand (visa, mastercard, etc.) */
+    brand?: string;
+}
+interface PaymentIntent {
+    /** Unique payment intent ID */
+    id: string;
+    /** Client secret for authenticating client-side operations */
+    clientSecret: string;
+    /** Amount in smallest currency unit */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** Payment status */
+    status: 'pending' | 'processing' | 'succeeded' | 'failed' | 'cancelled';
+    /** Recommended PSP based on routing rules */
+    recommendedPsp: PSPType;
+    /** Available payment methods for this intent */
+    availableMethods: PaymentMethod[];
+    /** Connection ID (from Reevit backend) */
+    connectionId?: string;
+    /** Provider name (from backend) */
+    provider?: string;
+    /** Fee amount charged by PSP */
+    feeAmount?: number;
+    /** Fee currency */
+    feeCurrency?: string;
+    /** Net amount after fees */
+    netAmount?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Reevit API Client
+ *
+ * Handles communication with the Reevit backend for payment operations.
+ */
+
+interface CreatePaymentIntentRequest {
+    amount: number;
+    currency: string;
+    method: string;
+    country: string;
+    customer_id?: string;
+    metadata?: Record<string, unknown>;
+    description?: string;
+    policy?: {
+        prefer?: string[];
+        max_amount?: number;
+        blocked_bins?: string[];
+        allowed_bins?: string[];
+        velocity_max_per_minute?: number;
+    };
+}
+interface PaymentIntentResponse {
+    id: string;
+    connection_id: string;
+    provider: string;
+    status: string;
+    client_secret: string;
+    amount: number;
+    currency: string;
+    fee_amount: number;
+    fee_currency: string;
+    net_amount: number;
+}
+interface ConfirmPaymentRequest {
+    provider_ref_id: string;
+    provider_data?: Record<string, unknown>;
+}
+interface PaymentDetailResponse {
+    id: string;
+    connection_id: string;
+    provider: string;
+    method: string;
+    status: string;
+    amount: number;
+    currency: string;
+    fee_amount: number;
+    fee_currency: string;
+    net_amount: number;
+    customer_id?: string;
+    client_secret: string;
+    provider_ref_id?: string;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+interface APIErrorResponse {
+    code: string;
+    message: string;
+    details?: Record<string, string>;
+}
+interface ReevitAPIClientConfig {
+    /** Your Reevit public key */
+    publicKey: string;
+    /** Base URL for the Reevit API (defaults to production) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Reevit API Client
+ */
+declare class ReevitAPIClient {
+    private readonly publicKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(config: ReevitAPIClientConfig);
+    /**
+     * Makes an authenticated API request
+     */
+    private request;
+    /**
+     * Creates a payment intent
+     */
+    createPaymentIntent(config: ReevitCheckoutConfig, method: PaymentMethod, country?: string): Promise<{
+        data?: PaymentIntentResponse;
+        error?: PaymentError;
+    }>;
+    /**
+     * Retrieves a payment intent by ID
+     */
+    getPaymentIntent(paymentId: string): Promise<{
+        data?: PaymentDetailResponse;
+        error?: PaymentError;
+    }>;
+    /**
+     * Confirms a payment after PSP callback
+     */
+    confirmPayment(paymentId: string): Promise<{
+        data?: PaymentDetailResponse;
+        error?: PaymentError;
+    }>;
+    /**
+     * Cancels a payment intent
+     */
+    cancelPaymentIntent(paymentId: string): Promise<{
+        data?: PaymentDetailResponse;
+        error?: PaymentError;
+    }>;
+    /**
+     * Maps SDK payment method to backend format
+     */
+    private mapPaymentMethod;
+}
+/**
+ * Creates a new Reevit API client instance
+ */
+declare function createReevitClient(config: ReevitAPIClientConfig): ReevitAPIClient;
+
+/**
+ * Utility Functions
+ * Shared utilities for Reevit SDKs
+ */
+
+/**
+ * Formats an amount from smallest currency unit to display format
+ */
+declare function formatAmount(amount: number, currency: string): string;
+/**
+ * Generates a unique payment reference
+ */
+declare function generateReference(prefix?: string): string;
+/**
+ * Validates a phone number for mobile money
+ */
+declare function validatePhone(phone: string, country?: string): boolean;
+/**
+ * Formats a phone number for display
+ */
+declare function formatPhone(phone: string, country?: string): string;
+/**
+ * Detects mobile money network from phone number (Ghana)
+ */
+declare function detectNetwork(phone: string): MobileMoneyNetwork | null;
+/**
+ * Creates CSS custom property variables from theme
+ */
+declare function createThemeVariables(theme: ReevitTheme): Record<string, string>;
+/**
+ * Simple class name concatenation utility
+ */
+declare function cn(...classes: (string | boolean | undefined | null)[]): string;
+/**
+ * Detects country code from currency
+ */
+declare function detectCountryFromCurrency(currency: string): string;
+
+/**
+ * Reevit State Machine
+ * Shared state management logic for all SDKs
+ */
+
+interface ReevitState {
+    status: CheckoutState;
+    paymentIntent: PaymentIntent | null;
+    selectedMethod: PaymentMethod | null;
+    error: PaymentError | null;
+    result: PaymentResult | null;
+}
+type ReevitAction = {
+    type: 'INIT_START';
+} | {
+    type: 'INIT_SUCCESS';
+    payload: PaymentIntent;
+} | {
+    type: 'INIT_ERROR';
+    payload: PaymentError;
+} | {
+    type: 'SELECT_METHOD';
+    payload: PaymentMethod;
+} | {
+    type: 'PROCESS_START';
+} | {
+    type: 'PROCESS_SUCCESS';
+    payload: PaymentResult;
+} | {
+    type: 'PROCESS_ERROR';
+    payload: PaymentError;
+} | {
+    type: 'RESET';
+} | {
+    type: 'CLOSE';
+};
+/**
+ * Creates the initial state for the checkout
+ */
+declare function createInitialState(): ReevitState;
+/**
+ * State reducer for checkout flow
+ */
+declare function reevitReducer(state: ReevitState, action: ReevitAction): ReevitState;
+
+export { type APIErrorResponse, type CardFormData, type CheckoutState, type ConfirmPaymentRequest, type CreatePaymentIntentRequest, type MobileMoneyFormData, type MobileMoneyNetwork, type PSPConfig, type PSPType, type PaymentDetailResponse, type PaymentError, type PaymentIntent, type PaymentIntentResponse, type PaymentMethod, type PaymentResult, ReevitAPIClient, type ReevitAPIClientConfig, type ReevitAction, type ReevitCheckoutCallbacks, type ReevitCheckoutConfig, type ReevitState, type ReevitTheme, cn, createInitialState, createReevitClient, createThemeVariables, detectCountryFromCurrency, detectNetwork, formatAmount, formatPhone, generateReference, reevitReducer, validatePhone };