@sablepay/angular-sablepay-js

Angular/TypeScript SDK for integrating SablePay stablecoin payments. Provides secure, type-safe payment creation, status polling, QR generation, and one-line payment launch APIs.

Features

• Payment Creation - Create stablecoin payment requests
• Status Tracking - Two-phase polling strategy (fixed + exponential backoff)
• One-line Launch API - SablePay.launchPayment() for end-to-end flow
• QR Generation - Data URL/SVG/Canvas generation for payment links
• Retry + Timeout Handling - Retryable API/network error support
• Warm-up Support - Preload SDK components for faster first payment
• Angular Services Included - Injectable service wrappers for Angular apps

Requirements

• Angular 13+
• Node.js 16+
• RxJS 7+

Installation

npm install @sablepay/angular-sablepay-js

Quick Start

1. Initialize SDK once

import { SablePay } from '@sablepay/angular-sablepay-js';

SablePay.initialize({
  apiKey: 'sable_sk_sand_...',
  merchantId: '00000000-0000-0000-0000-000000000000',
  enableLogging: false,
});

// Optional: pre-warm dependencies and network connection for lower first-payment latency
await SablePay.warmUp(true);

2. Create a payment (low-level API)

const sdk = SablePay.getInstance();

const payment = await sdk.createPayment({
  amount: 10.50,
  metadata: { order_id: '12345' },
});

const status = await sdk.getPaymentStatus(payment.paymentId);
console.log(status.status, status.txHash ?? status.transactionId);

3. Launch end-to-end flow (recommended)

SablePay.launchPayment({
  amount: 10.50,
  items: [{ name: 'Coffee', quantity: 1, price: 10.50 }],
  metadata: { order_id: '12345' },
}, {
  onPaymentCreated: (_response, qrDataUrl) => {
    // Render QR in your UI
    this.qrUrl = qrDataUrl;
  },
  onStatusUpdate: (status) => {
    this.statusLabel = status.status;
  },
  onSuccess: (result) => {
    this.statusLabel = `Completed: ${result.transactionHash}`;
  },
  onFailure: (error) => {
    this.statusLabel = `Failed: ${error.message}`;
  },
});

API Reference

SablePay (static)

• initialize(config) - Initialize singleton SDK instance
• getInstance() - Get initialized SDK instance
• isInitialized() - Check initialization state
• createPaymentFlow(options?) - Build a reusable flow controller
• launchPayment(amount, callbacks?, metadata?, options?) - One-line payment flow
• launchPayment(request, callbacks?, options?) - One-line payment flow with full request
• cancelPayment() - Cancel active launched flow
• warmUp(establishConnection?) - Pre-warm QR + optional API connection
• release() - Clear credentials and release singleton

SablePay (instance)

• createPayment(request, enableRetry?)
• getPaymentStatus(paymentId, enableRetry?)
• listPayments(limit?, offset?)
• isConfigured()
• getEnvironment()

PaymentFlow

• startPayment(amount, listener?, metadata?)
• cancel()
• release()
• state and isActive

PaymentStatusResponse compatibility

Transaction hash is available with both field names on status responses:

• txHash (Android-compatible)
• transactionId (web-compatible alias)

launchPayment(...).onSuccess returns a PaymentResult with Android-style fields such as transactionHash, paidToken, and paidNetwork.

Error Handling

import { ApiException } from '@sablepay/angular-sablepay-js';

try {
  await SablePay.getInstance().createPayment({ amount: 10.5 });
} catch (error) {
  if (error instanceof ApiException) {
    if (error.statusCode === 401) {
      // auth error
    } else if (error.isRateLimitError && error.retryAfter) {
      // retry after error.retryAfter seconds
    }
  }
}

Polling Strategy

Default strategy matches Android SDK:

• Phase 1: poll every 3s for first 60s
• Phase 2: exponential backoff (3s -> 6s -> 10s cap)
• Stop conditions: terminal status, timeout (10 minutes), or cancel

Angular Service Usage

Use injectable wrappers from SablePayService and PaymentFlowService if you prefer DI-driven integration instead of static APIs.

Documentation

• QUICKSTART.md - Fast integration checklist
• docs/API.md - API details and type notes
• docs/ARCHITECTURE.md - SDK structure and design
• docs/SECURITY.md - Security guidance for browser/Angular integrations
• docs/MIGRATION_GUIDE.md - Migration guidance
• CHANGELOG.md - Release notes

Example App

See example-app/ for a complete integration sample.

License

MIT