@zahlen/checkout 0.1.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@zahlen/checkout",
+  "version": "0.1.0",
+  "description": "Modern, Gen Z-friendly payment checkout modal for the web",
+  "author": "Zahlen",
+  "license": "MIT",
+  "main": "./index.cjs.js",
+  "module": "./index.esm.js",
+  "types": "./index.d.ts",
+  "sideEffects": false,
+  "keywords": [
+    "zahlen",
+    "checkout",
+    "payment",
+    "modal",
+    "fintech",
+    "nigeria",
+    "stripe-alternative",
+    "payment-gateway"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Havenix-Technologies-LTD/zahlen.git",
+    "directory": "libs/zahlen-checkout"
+  },
+  "homepage": "https://github.com/Havenix-Technologies-LTD/zahlen#readme",
+  "bugs": {
+    "url": "https://github.com/Havenix-Technologies-LTD/zahlen/issues"
+  },
+  "files": [
+    "index.cjs.js",
+    "index.esm.js",
+    "index.d.ts",
+    "src/**/*.d.ts"
+  ],
+  "dependencies": {}
+}

package/src/components/modal.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Zahlen Checkout Modal Component
+ * A modern, glassmorphism payment modal
+ */
+import type { CheckoutOptions } from '../types';
+export interface ModalState {
+    cardNumber: string;
+    expiry: string;
+    cvv: string;
+    errors: {
+        cardNumber?: string;
+        expiry?: string;
+        cvv?: string;
+    };
+    isProcessing: boolean;
+    isSuccess: boolean;
+}
+export declare class ZahlenModal {
+    private options;
+    private state;
+    private container;
+    private overlay;
+    constructor(options: CheckoutOptions);
+    /**
+     * Open the checkout modal
+     */
+    open(): void;
+    /**
+     * Close the checkout modal
+     */
+    close(): void;
+    /**
+     * Inject styles if not already present
+     */
+    private injectStyles;
+    /**
+     * Render the modal HTML
+     */
+    private render;
+    /**
+     * Get modal HTML
+     */
+    private getModalHTML;
+    /**
+     * Render success view
+     */
+    private renderSuccessView;
+    /**
+     * Attach event listeners
+     */
+    private attachEventListeners;
+    private handleEscape;
+    /**
+     * Handle card number input
+     */
+    private handleCardInput;
+    /**
+     * Handle expiry input
+     */
+    private handleExpiryInput;
+    /**
+     * Handle CVV input
+     */
+    private handleCVVInput;
+    /**
+     * Validate a specific field
+     */
+    private validateField;
+    /**
+     * Show error for a field
+     */
+    private showError;
+    /**
+     * Clear error for a field
+     */
+    private clearError;
+    /**
+     * Handle form submission
+     */
+    private handleSubmit;
+    /**
+     * Set processing state
+     */
+    private setProcessing;
+    /**
+     * Process payment (placeholder - integrate with your backend)
+     */
+    private processPayment;
+    /**
+     * Get base styles
+     */
+    private getStyles;
+}

package/src/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @zahlen/checkout - Modern Payment Checkout SDK
+ *
+ * A beautiful, Gen Z-friendly payment modal for the web.
+ *
+ * @example
+ * ```html
+ * <script src="https://unpkg.com/@zahlen/checkout"></script>
+ * <script>
+ *   Zahlen.init({ apiKey: 'pk_live_xxxxx' });
+ *
+ *   Zahlen.checkout({
+ *     amount: 4999,
+ *     currency: 'NGN',
+ *     onSuccess: (result) => console.log('Paid!', result),
+ *     onError: (error) => console.error('Failed', error),
+ *   });
+ * </script>
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { Zahlen, ZahlenSDK } from './zahlen';
+export type { ZahlenConfig, ZahlenTheme, CheckoutOptions, PaymentResult, PaymentError, CardInfo, } from './types';
+export { detectCardBrand, validateCardNumber, validateExpiry, validateCVV, luhnCheck, } from './utils/card-validator';
+export { formatCardNumber, formatExpiry, formatCVV, formatAmount, getCurrencySymbol, } from './utils/formatter';
+export { Zahlen as default } from './zahlen';

package/src/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Zahlen Checkout Type Definitions
+ */
+/**
+ * Configuration for initializing Zahlen
+ */
+export interface ZahlenConfig {
+    /** Your Zahlen API key (starts with pk_live_ or pk_test_) */
+    apiKey: string;
+    /** Theme mode: 'dark' (default), 'light', or 'auto' (follows system) */
+    theme?: 'dark' | 'light' | 'auto';
+    /** Locale for formatting (e.g., 'en-US', 'en-NG') */
+    locale?: string;
+    /** Custom CSS variables to override default theme */
+    customStyles?: Partial<ZahlenTheme>;
+}
+/**
+ * Custom theme variables
+ */
+export interface ZahlenTheme {
+    '--zahlen-primary': string;
+    '--zahlen-secondary': string;
+    '--zahlen-accent': string;
+    '--zahlen-bg': string;
+    '--zahlen-surface': string;
+    '--zahlen-border': string;
+    '--zahlen-text': string;
+    '--zahlen-text-muted': string;
+    '--zahlen-border-radius': string;
+}
+/**
+ * Options for opening a checkout session
+ */
+export interface CheckoutOptions {
+    /** Payment amount in smallest currency unit (e.g., kobo for NGN, cents for USD) */
+    amount: number;
+    /** ISO 4217 currency code (e.g., 'NGN', 'USD', 'EUR') */
+    currency: string;
+    /** Short description of the payment (shown in modal) */
+    description?: string;
+    /** Customer's email address (optional, for receipts) */
+    customerEmail?: string;
+    /** Additional metadata to attach to the payment */
+    metadata?: Record<string, unknown>;
+    /** Callback when payment succeeds */
+    onSuccess: (result: PaymentResult) => void;
+    /** Callback when payment fails */
+    onError: (error: PaymentError) => void;
+    /** Callback when modal is closed (optional) */
+    onClose?: () => void;
+}
+/**
+ * Result returned on successful payment
+ */
+export interface PaymentResult {
+    /** Unique payment ID */
+    id: string;
+    /** Payment status */
+    status: 'success' | 'pending';
+    /** Amount charged in smallest currency unit */
+    amount: number;
+    /** Currency code */
+    currency: string;
+    /** ISO timestamp of the payment */
+    timestamp: string;
+    /** Transaction reference (if available) */
+    reference?: string;
+    /** Additional data from payment processor */
+    data?: Record<string, unknown>;
+}
+/**
+ * Error returned on payment failure
+ */
+export interface PaymentError {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Whether the error is recoverable (user can retry) */
+    recoverable?: boolean;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+}
+/**
+ * Card information (sanitized - no full card numbers)
+ */
+export interface CardInfo {
+    /** Card brand (visa, mastercard, verve, etc.) */
+    brand: string;
+    /** Last 4 digits of the card */
+    last4: string;
+    /** Expiry month (1-12) */
+    expiryMonth: number;
+    /** Expiry year (full year) */
+    expiryYear: number;
+}

package/src/utils/card-validator.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Card validation utilities for Zahlen Checkout
+ */
+export interface CardBrand {
+    name: string;
+    code: string;
+    pattern: RegExp;
+    lengths: number[];
+    cvvLength: number;
+}
+export declare const CARD_BRANDS: CardBrand[];
+/**
+ * Detect card brand from card number
+ */
+export declare function detectCardBrand(cardNumber: string): CardBrand | null;
+/**
+ * Luhn algorithm for card validation
+ */
+export declare function luhnCheck(cardNumber: string): boolean;
+/**
+ * Validate card number
+ */
+export declare function validateCardNumber(cardNumber: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Validate expiry date
+ */
+export declare function validateExpiry(expiry: string): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Validate CVV
+ */
+export declare function validateCVV(cvv: string, cardNumber?: string): {
+    valid: boolean;
+    error?: string;
+};

package/src/utils/formatter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Input formatting utilities for Zahlen Checkout
+ */
+/**
+ * Format card number with spaces every 4 digits
+ */
+export declare function formatCardNumber(value: string): string;
+/**
+ * Format expiry date as MM/YY
+ */
+export declare function formatExpiry(value: string): string;
+/**
+ * Format CVV (numbers only, max 4 digits)
+ */
+export declare function formatCVV(value: string): string;
+/**
+ * Format currency amount
+ */
+export declare function formatAmount(amount: number, currency: string): string;
+/**
+ * Get currency symbol
+ */
+export declare function getCurrencySymbol(currency: string): string;

package/src/zahlen.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Zahlen - Modern Payment Checkout SDK
+ *
+ * A beautiful, Gen Z-friendly payment modal for the web.
+ *
+ * @example
+ * ```javascript
+ * // Initialize Zahlen
+ * Zahlen.init({ apiKey: 'pk_live_xxxxx' });
+ *
+ * // Open checkout
+ * Zahlen.checkout({
+ *   amount: 4999,
+ *   currency: 'NGN',
+ *   description: 'Premium Plan',
+ *   onSuccess: (result) => console.log('Paid!', result),
+ *   onError: (error) => console.error('Failed', error),
+ * });
+ * ```
+ */
+import type { ZahlenConfig, CheckoutOptions } from './types';
+declare class ZahlenSDK {
+    private config;
+    private currentModal;
+    private initialized;
+    /**
+     * Initialize Zahlen with your configuration
+     * @param config - Configuration object with API key and optional settings
+     */
+    init(config: ZahlenConfig): void;
+    /**
+     * Open the checkout modal
+     * @param options - Checkout options including amount, currency, and callbacks
+     */
+    checkout(options: CheckoutOptions): void;
+    /**
+     * Close the current checkout modal
+     */
+    closeModal(): void;
+    /**
+     * Set the theme
+     * @param theme - 'dark', 'light', or 'auto'
+     */
+    setTheme(theme: 'dark' | 'light' | 'auto'): void;
+    /**
+     * Apply system theme preference
+     */
+    private applyAutoTheme;
+    /**
+     * Apply custom CSS variables
+     */
+    private applyCustomStyles;
+    /**
+     * Get the SDK version
+     */
+    get version(): string;
+    /**
+     * Check if SDK is initialized
+     */
+    get isInitialized(): boolean;
+}
+declare const Zahlen: ZahlenSDK;
+export { Zahlen, ZahlenSDK };
+export type { ZahlenConfig, CheckoutOptions, ZahlenTheme } from './types';
+export type { PaymentResult, PaymentError, CardInfo } from './types';