@blazium/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,333 @@
+import { z } from 'zod';
+
+declare enum BlaziumChain {
+    SOL = "SOL",
+    TON = "TON",
+    BTC = "BTC"
+}
+declare enum BlaziumFiat {
+    USD = "USD",
+    EUR = "EUR",
+    TRY = "TRY"
+}
+declare enum PaymentStatus {
+    CREATED = "CREATED",
+    PENDING = "PENDING",
+    PARTIALLY_PAID = "PARTIALLY_PAID",
+    CONFIRMED = "CONFIRMED",
+    FAILED = "FAILED",
+    EXPIRED = "EXPIRED",
+    CANCELLED = "CANCELLED"
+}
+declare enum BlaziumEnvironment {
+    PRODUCTION = "production",
+    SANDBOX = "sandbox"
+}
+declare enum WithdrawalStatus {
+    PENDING = "PENDING",
+    PROCESSING = "PROCESSING",
+    COMPLETED = "COMPLETED",
+    FAILED = "FAILED",
+    CANCELLED = "CANCELLED"
+}
+declare const BlaziumConfigSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    baseUrl: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    environment: z.ZodDefault<z.ZodOptional<z.ZodNativeEnum<typeof BlaziumEnvironment>>>;
+    webhookSecret: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+    environment: BlaziumEnvironment;
+    webhookSecret?: string | undefined;
+}, {
+    apiKey: string;
+    baseUrl?: string | undefined;
+    timeout?: number | undefined;
+    environment?: BlaziumEnvironment | undefined;
+    webhookSecret?: string | undefined;
+}>;
+type BlaziumConfig = z.input<typeof BlaziumConfigSchema>;
+type BlaziumConfigInternal = z.output<typeof BlaziumConfigSchema>;
+interface Payment {
+    id: string;
+    status: PaymentStatus;
+    amount: number;
+    currency: string;
+    checkoutUrl: string;
+    createdAt: string;
+    expiresAt: string;
+    description?: string;
+    metadata?: Record<string, unknown>;
+    updatedAt?: string;
+    payCurrency?: BlaziumChain;
+    payAmount?: number;
+    payAddress?: string;
+    txHash?: string;
+    networkFee?: number;
+    blockHeight?: string;
+    confirmedAt?: string;
+    addressIndex?: number;
+    quotedRate?: number;
+    quoteExpiresAt?: string;
+    rewardAmount?: number;
+    rewardCurrency?: string;
+    rewardData?: Record<string, unknown>;
+    rewardDelivered?: boolean;
+    partialPayment?: {
+        amount: number;
+        txHash: string;
+        detectedAt: string;
+        expectedAmount: number;
+    };
+}
+declare const CreatePaymentSchema: z.ZodObject<{
+    amount: z.ZodNumber;
+    currency: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    redirectUrl: z.ZodOptional<z.ZodString>;
+    cancelUrl: z.ZodOptional<z.ZodString>;
+    expiresIn: z.ZodOptional<z.ZodNumber>;
+    rewardAmount: z.ZodOptional<z.ZodNumber>;
+    rewardCurrency: z.ZodOptional<z.ZodString>;
+    rewardData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    amount: number;
+    currency: string;
+    description?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    redirectUrl?: string | undefined;
+    cancelUrl?: string | undefined;
+    expiresIn?: number | undefined;
+    rewardAmount?: number | undefined;
+    rewardCurrency?: string | undefined;
+    rewardData?: Record<string, unknown> | undefined;
+}, {
+    amount: number;
+    currency: string;
+    description?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    redirectUrl?: string | undefined;
+    cancelUrl?: string | undefined;
+    expiresIn?: number | undefined;
+    rewardAmount?: number | undefined;
+    rewardCurrency?: string | undefined;
+    rewardData?: Record<string, unknown> | undefined;
+}>;
+type CreatePaymentParams = z.infer<typeof CreatePaymentSchema>;
+interface CreatePaymentOptions {
+    idempotencyKey?: string;
+}
+declare enum WebhookEventType {
+    PAYMENT_CREATED = "payment.created",
+    PAYMENT_PENDING = "payment.pending",
+    PAYMENT_CONFIRMED = "payment.confirmed",
+    PAYMENT_FAILED = "payment.failed",
+    PAYMENT_EXPIRED = "payment.expired",
+    PAYMENT_PARTIALLY_PAID = "payment.partially_paid"
+}
+interface WebhookPayload {
+    id: string;
+    webhook_id: string;
+    event: WebhookEventType;
+    payment_id: string;
+    payment: Payment;
+    timestamp: string;
+    createdAt: string;
+}
+interface PaymentStats {
+    total: number;
+    confirmed: number;
+    pending: number;
+    failed: number;
+    totalVolume: number;
+    currency: string;
+}
+interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        page: number;
+        pageSize: number;
+        totalPages: number;
+        totalItems: number;
+    };
+}
+interface ListPaymentsParams {
+    status?: PaymentStatus;
+    currency?: string;
+    page?: number;
+    pageSize?: number;
+    startDate?: string;
+    endDate?: string;
+}
+interface MerchantBalance {
+    chain: string;
+    totalEarned: string;
+    availableBalance: string;
+    pendingBalance: string;
+    totalWithdrawn: string;
+    holdAmount: string;
+    settlementPeriodDays: number;
+}
+interface Withdrawal {
+    id: string;
+    status: WithdrawalStatus;
+    amount: string;
+    chain: string;
+    destinationAddress: string;
+    txHash?: string;
+    networkFee?: string;
+    finalAmount?: string;
+    errorMessage?: string;
+    requestedAt: string;
+    completedAt?: string;
+}
+interface WithdrawalRequest {
+    chain: string;
+    amount: number;
+    destinationAddress: string;
+}
+
+declare class BlaziumError extends Error {
+    code: string;
+    details?: unknown;
+    constructor(message: string, code?: string, details?: unknown);
+    /**
+     * Convert error to JSON format
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        details: unknown;
+        stack: string | undefined;
+    };
+}
+declare class AuthenticationError extends BlaziumError {
+    constructor(message?: string);
+}
+declare class ValidationError extends BlaziumError {
+    constructor(message: string, errors?: unknown);
+}
+declare class NetworkError extends BlaziumError {
+    constructor(message?: string);
+}
+declare class RateLimitError extends BlaziumError {
+    retryAfter?: number;
+    constructor(message?: string, retryAfter?: number);
+}
+declare class TimeoutError extends BlaziumError {
+    constructor(message?: string, code?: string);
+}
+declare class APIError extends BlaziumError {
+    statusCode: number;
+    constructor(message: string, statusCode: number, code?: string);
+}
+/**
+ * ✅ NEW: Payment specific errors
+ */
+declare class PaymentError extends BlaziumError {
+    constructor(message: string, code?: string, details?: unknown);
+}
+declare class PaymentNotFoundError extends PaymentError {
+    constructor(paymentId: string);
+}
+declare class PaymentExpiredError extends PaymentError {
+    constructor(paymentId: string);
+}
+declare class InsufficientPaymentError extends PaymentError {
+    constructor(received: number, expected: number);
+}
+/**
+ * ✅ NEW: Webhook specific errors
+ */
+declare class WebhookError extends BlaziumError {
+    constructor(message: string, code?: string, details?: unknown);
+}
+declare class InvalidSignatureError extends WebhookError {
+    constructor();
+}
+
+declare class BlaziumPayClient {
+    private client;
+    private config;
+    constructor(config: BlaziumConfig);
+    /**
+     * Create a new payment with idempotency support.
+     *
+     * Note: rewardAmount and rewardCurrency are optional metadata fields for developer reference.
+     * BlaziumPay does NOT automatically grant rewards - developers must implement their own
+     * logic in webhook handlers to grant premium features, add currency, or perform other actions.
+     */
+    createPayment(params: CreatePaymentParams, options?: CreatePaymentOptions): Promise<Payment>;
+    /**
+     * Get payment details
+     */
+    getPayment(paymentId: string): Promise<Payment>;
+    /**
+     * List payments with filters
+     */
+    listPayments(params?: ListPaymentsParams): Promise<PaginatedResponse<Payment>>;
+    /**
+     * Cancel a payment
+     */
+    cancelPayment(paymentId: string): Promise<Payment>;
+    /**
+     * Get payment statistics
+     */
+    getStats(): Promise<PaymentStats>;
+    /**
+     * Get merchant balance for a specific chain
+     */
+    getBalance(chain: string): Promise<MerchantBalance>;
+    /**
+     * Request withdrawal
+     */
+    requestWithdrawal(request: WithdrawalRequest): Promise<Withdrawal>;
+    /**
+     * List withdrawal history
+     */
+    listWithdrawals(): Promise<Withdrawal[]>;
+    /**
+     * Get specific withdrawal status
+     */
+    getWithdrawal(withdrawalId: string): Promise<Withdrawal>;
+    /**
+     * Wait for a payment to be confirmed (Long Polling helper)
+     */
+    waitForPayment(paymentId: string, timeoutMs?: number, pollIntervalMs?: number): Promise<Payment>;
+    /**
+     * Verify webhook signature
+     *
+     * Note: Only verified webhooks receive events. Unverified webhooks will not receive
+     * any webhook events from BlaziumPay. You must verify your webhook endpoint in the
+     * dashboard before it will receive events and require signature verification.
+     */
+    verifyWebhookSignature(payload: string, signature: string): boolean;
+    /**
+     * Parse and verify webhook payload
+     *
+     * @param rawPayload - Raw JSON string of webhook payload
+     * @param signature - Signature from HTTP header 'X-Blazium-Signature'
+     * @returns Parsed and verified webhook payload
+     *
+     * Note: Signature is verified from HTTP header, not from payload.
+     * Only verified webhooks receive events. Unverified webhooks will not receive
+     * any webhook events from BlaziumPay.
+     */
+    parseWebhook(rawPayload: string, signature: string): WebhookPayload;
+    private normalizePayment;
+    private sleep;
+    private isFinalStatus;
+    isFinal(payment: Payment): boolean;
+    isPaid(payment: Payment): boolean;
+    isPartiallyPaid(payment: Payment): boolean;
+    isExpired(payment: Payment): boolean;
+    getPaymentProgress(payment: Payment): number;
+    formatAmount(amount: number, currency: string): string;
+}
+
+export { APIError, AuthenticationError, BlaziumChain, type BlaziumConfig, type BlaziumConfigInternal, BlaziumConfigSchema, BlaziumEnvironment, BlaziumError, BlaziumFiat, BlaziumPayClient, type CreatePaymentOptions, type CreatePaymentParams, CreatePaymentSchema, InsufficientPaymentError, InvalidSignatureError, type ListPaymentsParams, type MerchantBalance, NetworkError, type PaginatedResponse, type Payment, PaymentError, PaymentExpiredError, PaymentNotFoundError, type PaymentStats, PaymentStatus, RateLimitError, TimeoutError, ValidationError, WebhookError, WebhookEventType, type WebhookPayload, type Withdrawal, type WithdrawalRequest, WithdrawalStatus };