@blazium/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 BlaziumPay
+
+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,306 @@
+# @blazium/sdk
+
+Official Node.js SDK for BlaziumPay - Production-ready crypto payment infrastructure.
+
+## Features
+
+- 🔐 **Secure**: HMAC-SHA256 webhook verification with timing-safe comparison
+- 💰 **Multi-Chain**: TON, Solana, Bitcoin support
+- 🎯 **Reward Locking**: Lock rewards at payment creation (400 coins = exactly 400 coins)
+- 🔄 **Idempotency**: Built-in duplicate payment prevention
+- ⚡ **Real-time**: Long polling and webhook support
+- 📊 **Balance Management**: Track earnings and withdrawals
+- 🛡️ **Type-Safe**: Full TypeScript support with Zod validation
+- 🚫 **No Database Required**: Works with any backend stack
+
+## Installation
+
+```bash
+npm install @blazium/sdk
+```
+
+## Quick Start
+
+```typescript
+import { BlaziumPayClient } from '@blazium/sdk';
+
+const client = new BlaziumPayClient({
+  apiKey: process.env.BLAZIUM_API_KEY,
+  webhookSecret: process.env.BLAZIUM_WEBHOOK_SECRET,
+  environment: 'production'
+});
+
+// Create payment with locked reward
+const payment = await client.createPayment(
+  {
+    amount: 10.00,
+    currency: 'USD',
+    description: 'Premium Pack',
+    rewardAmount: 400,
+    rewardCurrency: 'coins'
+  },
+  {
+    idempotencyKey: 'order_12345'
+  }
+);
+
+console.log('Checkout URL:', payment.checkoutUrl);
+console.log('Reward (LOCKED):', payment.rewardAmount); // Always 400
+```
+
+## Core Concepts
+
+### Reward Metadata (Developer Controlled)
+
+The `rewardAmount` and `rewardCurrency` fields are **optional metadata** that you can use to track what you plan to give users. 
+**BlaziumPay does NOT automatically grant rewards** - you must implement your own logic in webhook handlers.
+
+```typescript
+// Set reward metadata when creating payment
+const payment = await client.createPayment({
+  amount: 3.00,
+  currency: 'USD',
+  rewardAmount: 1000, // Metadata: 1000 gold to grant
+  rewardCurrency: 'gold' // Metadata: Gold currency
+});
+
+// The rewardAmount is stored in the payment object
+// You must implement your own logic to grant rewards when payment confirms
+```
+
+### Payment Lifecycle
+
+```
+CREATE → PENDING → CONFIRMED → [Your Custom Logic]
+         ↓
+       EXPIRED / FAILED / CANCELLED
+```
+
+**Important:** When a payment reaches `CONFIRMED` status, **you must implement your own webhook handler** to grant 
+premium features, add currency, unlock content, or perform any other actions. BlaziumPay handles payment processing; 
+you handle the business logic.
+
+### Webhook Verification (Critical)
+
+**Important:** Only verified webhooks receive events from BlaziumPay. You must verify your webhook endpoint in the dashboard before it will receive any events. Unverified webhooks will not receive any webhook events.
+
+```typescript
+import express from 'express';
+
+app.post('/webhooks/blazium', express.json({
+  verify: (req, res, buf) => {
+    req.rawBody = buf.toString('utf8');
+  }
+}), async (req, res) => {
+  const signature = req.headers['x-blazium-signature'];
+  
+  // CRITICAL: Verify signature
+  // Note: If webhookSecret is not configured, this will throw a ValidationError
+  // with a helpful message explaining that webhooks must be verified first
+  if (!client.verifyWebhookSignature(req.rawBody, signature)) {
+    return res.status(401).send('Invalid signature');
+  }
+  
+  const webhook = client.parseWebhook(req.rawBody, signature);
+  
+  if (webhook.event === 'payment.confirmed') {
+    const payment = webhook.payment;
+    const userId = payment.metadata.userId;
+    
+    // YOUR CUSTOM LOGIC HERE - You decide what happens:
+    
+    // Example: Grant premium features
+    if (payment.rewardCurrency === 'premium') {
+      await database.users.update(userId, { isPremium: true });
+    }
+    
+    // Example: Add in-game currency
+    if (payment.rewardCurrency === 'coins') {
+      await database.users.incrementCoins(userId, payment.rewardAmount);
+    }
+    
+    // You have full control - implement whatever logic you need!
+  }
+  
+  res.status(200).send({ received: true });
+});
+```
+
+**Webhook Verification Process:**
+1. Create a webhook endpoint in the dashboard
+2. Verify the endpoint ownership (BlaziumPay will send a challenge token)
+3. Save the webhook secret securely (shown only once after verification)
+4. Configure the secret in your SDK client
+5. Only verified webhooks receive events - unverified webhooks are ignored by BlaziumPay
+
+## API Reference
+
+### Initialize Client
+
+```typescript
+const client = new BlaziumPayClient({
+  apiKey: string,              // Required: Your API key
+  webhookSecret?: string,      // Optional: For webhook verification
+  baseUrl?: string,            // Optional: Custom API URL
+  timeout?: number,            // Optional: Request timeout (default: 15000ms)
+  environment?: 'production' | 'sandbox'
+});
+```
+
+### Create Payment
+
+```typescript
+const payment = await client.createPayment(
+  {
+    amount: number,              // Amount in fiat currency
+    currency: string,            // USD, EUR, TRY, etc.
+    description?: string,        // Payment description
+    metadata?: object,           // Custom data
+    redirectUrl?: string,        // Success redirect
+    cancelUrl?: string,          // Cancel redirect
+    expiresIn?: number,          // Expiration in seconds (60-86400)
+    rewardAmount?: number,       // LOCKED reward amount
+    rewardCurrency?: string,     // Reward currency
+    rewardData?: object          // Additional reward data
+  },
+  {
+    idempotencyKey?: string      // Prevent duplicates
+  }
+);
+```
+
+### Get Payment
+
+```typescript
+const payment = await client.getPayment(paymentId);
+
+console.log(payment.status);       // PENDING, CONFIRMED, etc.
+console.log(payment.rewardAmount); // Locked reward
+console.log(payment.txHash);       // Blockchain transaction
+```
+
+### Wait for Confirmation
+
+```typescript
+try {
+  const confirmed = await client.waitForPayment(
+    paymentId,
+    300000,  // 5 minutes timeout
+    3000     // Poll every 3 seconds
+  );
+  
+  console.log('Payment confirmed!', confirmed.txHash);
+} catch (error) {
+  console.error('Payment timeout or failed');
+}
+```
+
+### Balance & Withdrawals
+
+```typescript
+// Check merchant balance
+const balance = await client.getBalance('TON');
+
+console.log('Total Earned:', balance.totalEarned);
+console.log('Available:', balance.availableBalance);
+console.log('Pending:', balance.pendingBalance);
+
+// Request withdrawal
+const withdrawal = await client.requestWithdrawal({
+  chain: 'TON',
+  amount: 10,
+  destinationAddress: 'YOUR_TON_ADDRESS'
+});
+```
+
+### Webhook Verification
+
+```typescript
+// Verify signature (timing-safe)
+const isValid = client.verifyWebhookSignature(rawBody, signature);
+
+// Parse webhook
+const webhook = client.parseWebhook(rawBody, signature);
+
+console.log(webhook.event);   // payment.confirmed, etc.
+console.log(webhook.payment); // Full payment object
+```
+
+### Utility Methods
+
+```typescript
+client.isPaid(payment);              // true if CONFIRMED
+client.isPartiallyPaid(payment);     // true if underpaid
+client.isExpired(payment);           // true if expired
+client.isFinal(payment);             // true if no more updates
+client.getPaymentProgress(payment);  // % of amount paid
+client.formatAmount(1.5, 'TON');     // "1.5000 TON"
+```
+
+## Error Handling
+
+```typescript
+import {
+  BlaziumError,
+  AuthenticationError,
+  ValidationError,
+  NetworkError,
+  TimeoutError,
+  PaymentError
+} from '@blazium/sdk';
+
+try {
+  const payment = await client.createPayment({ /* ... */ });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof ValidationError) {
+    console.error('Invalid input:', error.details);
+  } else if (error instanceof NetworkError) {
+    console.error('Network error, retry...');
+  }
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with type definitions:
+
+```typescript
+import type {
+  Payment,
+  PaymentStatus,
+  CreatePaymentParams,
+  WebhookPayload,
+  MerchantBalance
+} from '@blazium/sdk';
+```
+
+## Security Best Practices
+
+1. **Never trust frontend signals** - Always verify payments server-side
+2. **Verify webhook signatures** - Use `verifyWebhookSignature()` - CRITICAL for security
+3. **Use idempotency keys** - Prevent duplicate payments
+4. **Implement your own reward logic** - BlaziumPay does NOT automatically grant rewards. You must implement webhook handlers to grant premium features, add currency, or perform other actions
+5. **Use rewardAmount as metadata** - Store what you promise users, but implement your own logic to grant it
+6. **Store API keys securely** - Use environment variables
+7. **Implement timeout handling** - Network issues happen
+8. **Log webhook failures** - Monitor for issues
+9. **Make webhook handlers idempotent** - Handle duplicate webhook deliveries gracefully
+
+## Requirements
+
+- Node.js >= 18
+- No database required
+- No Prisma required
+- Works with any backend framework (Express, Fastify, NestJS, etc.)
+
+## Support
+
+- Documentation: https://docs.blaziumpay.com
+- Issues: https://github.com/blaziumpay/sdk/issues
+- Email: support@blaziumpay.com
+
+## License
+
+MIT © BlaziumPay

package/dist/index.d.mts

@@ -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 };