@vindhq/sloud-payment-sdk 1.0.9 → 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,297 @@
+/**
+ * Common fields shared across all payment types
+ */
+/**
+ * Data passed to the onSuccess callback after a successful payment
+ */
+interface PaymentSuccessData {
+    reference: string;
+    amount: number;
+    currency: string;
+}
+interface BasePaymentWidgetOptions {
+    public_key: string;
+    isLocalEnv?: boolean;
+    transaction_id?: string;
+    customer_id?: string;
+    business_id?: string;
+    /** Called when a payment completes successfully */
+    onSuccess?: (data: PaymentSuccessData) => void;
+}
+interface Customer {
+    first_name: string;
+    last_name: string;
+    phone_number: string;
+    email: string;
+}
+interface DeliveryDetails {
+    street: string;
+    city: string;
+    state: string;
+    country: string;
+    note?: string;
+}
+interface Product {
+    product_id: string;
+    quantity: number;
+    variation?: string[];
+    selected_variation_id?: string;
+}
+/**
+ * String literal types for payment modes
+ * These provide better IntelliSense suggestions
+ */
+type PaymentType = "external" | "storefront" | "sloudfront";
+/**
+ * String literal types for channel options
+ * These provide better IntelliSense suggestions
+ */
+type ChannelType = "pickup" | "delivery";
+/**
+ * Enum for backward compatibility and convenience
+ * Use either string literals or enum values
+ */
+declare enum ModeType {
+    Storefront = "storefront",
+    External = "external",
+    Sloudfront = "sloudfront"
+}
+/**
+ * Options for external payment type
+ * Used for simple payments with customer details
+ */
+interface ExternalPaymentWidgetOptions extends BasePaymentWidgetOptions {
+    type: "external";
+    amount: number;
+    customer: Customer;
+}
+/**
+ * Base options for storefront payment type (shared fields)
+ */
+interface BaseStorefrontPaymentWidgetOptions extends BasePaymentWidgetOptions {
+    type: "storefront";
+    slug: string;
+    amount: number;
+    discount?: number;
+    customer: Customer;
+    products: Product[];
+}
+/**
+ * Storefront options when channel is 'pickup' - delivery_details is optional
+ */
+interface StorefrontPickupOptions extends BaseStorefrontPaymentWidgetOptions {
+    channel: "pickup";
+    delivery_details?: DeliveryDetails;
+}
+/**
+ * Storefront options when channel is 'delivery' - delivery_details is required
+ */
+interface StorefrontDeliveryOptions extends BaseStorefrontPaymentWidgetOptions {
+    channel: "delivery";
+    delivery_details: DeliveryDetails;
+}
+/**
+ * Options for storefront payment type
+ * Used for e-commerce orders with products and delivery
+ * delivery_details is required only when channel is 'delivery'
+ */
+type StorefrontPaymentWidgetOptions = StorefrontPickupOptions | StorefrontDeliveryOptions;
+/**
+ * Base options for sloudfront payment type (shared fields)
+ */
+interface BaseSloudfrontPaymentWidgetOptions extends BasePaymentWidgetOptions {
+    type: "sloudfront";
+    amount: number;
+    discount?: number;
+    customer: Customer;
+    products: Product[];
+    transaction_id?: string;
+    customer_id: string;
+    business_id: string;
+}
+/**
+ * Sloudfront options when channel is 'pickup' - delivery_details is optional
+ */
+interface SloudfrontPickupOptions extends BaseSloudfrontPaymentWidgetOptions {
+    channel: "pickup";
+    delivery_details?: DeliveryDetails;
+}
+/**
+ * Sloudfront options when channel is 'delivery' - delivery_details is required
+ */
+interface SloudfrontDeliveryOptions extends BaseSloudfrontPaymentWidgetOptions {
+    channel: "delivery";
+    delivery_details: DeliveryDetails;
+}
+/**
+ * Options for sloudfront payment type
+ * delivery_details is required only when channel is 'delivery'
+ */
+type SloudfrontPaymentWidgetOptions = SloudfrontPickupOptions | SloudfrontDeliveryOptions;
+/**
+ * Discriminated union of all payment widget option types
+ * TypeScript will enforce that the correct fields are provided based on the type
+ */
+type PaymentWidgetOptions = ExternalPaymentWidgetOptions | StorefrontPaymentWidgetOptions | SloudfrontPaymentWidgetOptions;
+
+declare class PaymentWidget {
+    private options;
+    private container;
+    private root;
+    constructor(options: PaymentWidgetOptions);
+    /**
+     * Creates the container div if it doesn’t exist.
+     */
+    private ensureContainer;
+    /**
+     * Renders the widget popup.
+     */
+    showPopup(): void;
+    /**
+     * Optionally allow hiding/unmounting the widget.
+     */
+    hidePopup(): void;
+}
+
+declare class PaymentWidgetValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates payment widget options based on the type
+ * @throws {PaymentWidgetValidationError} if validation fails
+ */
+declare function validatePaymentWidgetOptions(options: PaymentWidgetOptions): void;
+
+interface IExternalPaymentPayload {
+    type: "external";
+    amount: number;
+    customer: {
+        first_name: string;
+        last_name: string;
+        phone_number: string;
+        email: string;
+    };
+}
+interface IStorefrontPaymentPayload {
+    type: "storefront";
+    slug: string;
+    order: {
+        additional_amount?: number;
+        discount?: number;
+        items: Array<{
+            product_id: string;
+            quantity: number;
+            variation?: string[];
+            selected_variation_id?: string;
+        }>;
+        payment_method?: string;
+        channel?: string;
+        buyer_details: {
+            first_name: string;
+            last_name: string;
+            email: string;
+            phone_number: string;
+        };
+        delivery_details?: {
+            street: string;
+            city: string;
+            state: string;
+            country: string;
+            note?: string;
+        };
+    };
+}
+interface ISloudfrontPaymentPayload {
+    type: "sloudfront";
+    manual_order: {
+        additional_amount?: number;
+        discount?: number;
+        items: Array<{
+            product_id: string;
+            quantity: number;
+            variation?: string[];
+            selected_variation_id?: string;
+        }>;
+        payment_method?: string;
+        channel?: string;
+        buyer_details?: {
+            first_name: string;
+            last_name: string;
+            email: string;
+            phone_number: string;
+        };
+        delivery_details?: {
+            street: string;
+            city: string;
+            state: string;
+            country: string;
+            note?: string;
+        };
+        transaction_id?: string;
+        customer_id: string;
+        business_id: string;
+    };
+}
+type IGeneratePaymentInstrumentPayload = IExternalPaymentPayload | IStorefrontPaymentPayload | ISloudfrontPaymentPayload;
+
+/**
+ * Base interface for payload builders
+ */
+interface PayloadBuilder<T extends IGeneratePaymentInstrumentPayload> {
+    build(options: PaymentWidgetOptions, payment_method?: string): T;
+}
+/**
+ * Factory function to build payment instrument payload based on options type
+ *
+ * @param options - Payment widget options
+ * @returns Constructed payload for the payment instrument API
+ * @throws Error if the payment type is not supported
+ *
+ * @example
+ * // External payment
+ * const payload = buildPaymentInstrumentPayload({
+ *   type: "external",
+ *   amount: 25000,
+ *   // ... other options
+ * });
+ *
+ * @example
+ * // Storefront payment
+ * const payload = buildPaymentInstrumentPayload({
+ *   type: "storefront",
+ *   slug: "my-store",
+ *   products: [...],
+ *   // ... other options
+ * });
+ */
+declare function buildPaymentInstrumentPayload(options: PaymentWidgetOptions, payment_method?: string): IGeneratePaymentInstrumentPayload;
+/**
+ * Register a new payload builder for a custom payment type
+ * This allows for extending the system with new payment types without modifying existing code
+ *
+ * @param type - The payment type identifier
+ * @param builder - The payload builder instance
+ *
+ * @example
+ * class SubscriptionPaymentPayloadBuilder implements PayloadBuilder<ISubscriptionPaymentPayload> {
+ *   build(options: PaymentWidgetOptions): ISubscriptionPaymentPayload {
+ *     return {
+ *       type: "subscription",
+ *       plan_id: options.plan_id,
+ *       // ... other fields
+ *     };
+ *   }
+ * }
+ *
+ * registerPayloadBuilder("subscription", new SubscriptionPaymentPayloadBuilder());
+ */
+declare function registerPayloadBuilder(type: string, builder: PayloadBuilder<IGeneratePaymentInstrumentPayload>): void;
+/**
+ * Get all registered payment types
+ *
+ * @returns Array of registered payment type identifiers
+ */
+declare function getRegisteredPaymentTypes(): string[];
+
+export { ModeType, PaymentWidgetValidationError, buildPaymentInstrumentPayload, PaymentWidget as default, getRegisteredPaymentTypes, registerPayloadBuilder, validatePaymentWidgetOptions };
+export type { ChannelType, ExternalPaymentWidgetOptions, PaymentSuccessData, PaymentType, PaymentWidgetOptions, SloudfrontPaymentWidgetOptions, StorefrontPaymentWidgetOptions };