orbis1-sdk-rn 0.0.6 → 0.0.8

package/src/features/gas-free/GasFreeModule.ts

@@ -22,27 +22,17 @@ import type {
   GasFreeTransferRequest,
   GasFreeTransferResult,
 } from './types/GasFreeRequest';
+import type {
+  FeeQuote,
+  VerificationResult,
+  PSBTBuildResult,
+  PSBTSubmitResult,
+  BroadcastResult,
+  TransferState,
+} from './types';
 import { GasFreeError, GasFreeErrorCode } from './errors/GasFreeError';
 import type { AssignmentType } from '../../core/Interfaces';
-
-/**
- * Transfer state tracking
- */
-interface TransferState {
-  quoteId?: string;
-  quoteExpiresAt?: number;
-  psbtBase64?: string;
-  txid?: string;
-  status:
-    | 'idle'
-    | 'quote-requested'
-    | 'psbt-built'
-    | 'submitted'
-    | 'broadcasted'
-    | 'verified'
-    | 'failed';
-  error?: Error;
-}
+import { Feature } from '../../types/Feature';
 
 /**
  * Gas-Free Transfer Module
@@ -55,7 +45,7 @@ interface TransferState {
  * 5. Verify transfer completion
  */
 export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
-  public readonly name = 'gasFree' as const;
+  public readonly name = Feature.GAS_FREE;
   public readonly version = '1.0.0';
   public readonly config: GasFreeConfig;
 
@@ -156,8 +146,19 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
    *
    * @param request - Transfer request parameters
    * @returns Fee quote with pricing and expiration details
+   *
+   * @example
+   * ```typescript
+   * const quote = await gasFree.requestFeeQuote({
+   *   userId: 'user-123',
+   *   assetId: 'rgb:...',
+   *   amount: '100',
+   *   recipientInvoice: 'rgb:...'
+   * });
+   * console.log('Service fee:', quote.serviceFeeAmount);
+   * ```
    */
-  async requestFeeQuote(request: GasFreeTransferRequest): Promise<any> {
+  async requestFeeQuote(request: GasFreeTransferRequest): Promise<FeeQuote> {
     this.logger?.debug('Requesting fee quote', {
       assetId: request.assetId,
       amount: request.amount,
@@ -197,7 +198,7 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
   }
 
   /**
-   * Stage 2: Confirm and execute transfer using a fee quote
+   * Stage 2: Confirm and execute transfer using a fee quote (One-shot method)
    *
    * Executes the complete transfer workflow:
    * 1. Build PSBT with external mining inputs
@@ -205,13 +206,26 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
    * 3. Sign RGB inputs and broadcast transaction
    * 4. Verify transfer completion with service
    *
+   * For advanced users who need more control, use the individual stage methods:
+   * - buildPSBT()
+   * - submitPSBT()
+   * - broadcastTransfer()
+   * - verifyTransfer()
+   *
    * @param request - Original transfer request parameters
    * @param feeQuote - Fee quote obtained from requestFeeQuote()
    * @returns Transfer result with txid and fee breakdown
+   *
+   * @example
+   * ```typescript
+   * const quote = await gasFree.requestFeeQuote(request);
+   * const result = await gasFree.confirmTransfer(request, quote);
+   * console.log('Transaction ID:', result.txid);
+   * ```
    */
   async confirmTransfer(
     request: GasFreeTransferRequest,
-    feeQuote: any
+    feeQuote: FeeQuote
   ): Promise<GasFreeTransferResult> {
     this.logger?.debug('Confirming transfer with quote', {
       quoteId: feeQuote.quoteId,
@@ -355,9 +369,32 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
   }
 
   /**
-   * Step 2: Build PSBT with external inputs using Wallet
+   * Advanced Stage 2a: Build PSBT with external mining inputs
+   *
+   * Builds an unsigned PSBT that includes:
+   * - External mining input from the service (provides BTC for fees)
+   * - User's RGB asset inputs
+   * - Two RGB recipients: merchant + service fee
+   * - External change output (BTC change back to service)
+   *
+   * This method writes the RGB consignment file to disk which will be read
+   * in the next stage (submitPSBT).
+   *
+   * @param request - Transfer request parameters
+   * @param feeQuote - Fee quote from requestFeeQuote()
+   * @returns PSBT build result with unsigned PSBT and mining details
+   *
+   * @example
+   * ```typescript
+   * const quote = await gasFree.requestFeeQuote(request);
+   * const psbtResult = await gasFree.buildPSBT(request, quote);
+   * console.log('Unsigned PSBT:', psbtResult.unsignedPsbt);
+   * ```
    */
-  private async buildPSBT(request: GasFreeTransferRequest, feeQuote: any) {
+  async buildPSBT(
+    request: GasFreeTransferRequest,
+    feeQuote: FeeQuote
+  ): Promise<PSBTBuildResult> {
     this.logger?.debug('Step 2: Building PSBT with external inputs');
 
     // Check quote not expired
@@ -404,6 +441,8 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
 
     // Build recipient map for sendBegin
     // Note: Recipient requires assignment field with type and amount
+    // Important: Decoded invoices may have 'ANY' type (wildcard), but sendBegin
+    // requires a concrete assignment type. Always use 'FUNGIBLE' for asset transfers.
     const recipientMap: Record<
       string,
       Array<{
@@ -417,11 +456,10 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
           // Recipient 1: The actual transfer to the merchant / end recipient
           recipientId: decodedRecipientInvoice.recipientId,
           assignment: {
-            type: decodedRecipientInvoice.assignment.type || 'FUNGIBLE',
-            // Use amount from request (user-specified) or from invoice if available
-            amount:
-              parseInt(request.amount, 10) ||
-              decodedRecipientInvoice.assignment.amount,
+            // Use FUNGIBLE type for asset transfers (invoice may have 'ANY' wildcard type)
+            type: 'FUNGIBLE',
+            // Use amount from request (in base units (w/ precision), as integer)
+            amount: parseInt(request.amount, 10),
           },
           transportEndpoints: decodedRecipientInvoice.transportEndpoints,
         },
@@ -430,11 +468,10 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
           // as payment for covering the Bitcoin mining fee.
           recipientId: decodedServiceInvoice.recipientId,
           assignment: {
-            type: decodedServiceInvoice.assignment.type || 'FUNGIBLE',
-            // Use service fee amount from quote or from invoice if available
-            amount:
-              feeQuote.serviceFeeAmount ||
-              decodedServiceInvoice.assignment.amount,
+            // Use FUNGIBLE type for service fee (invoice may have 'ANY' wildcard type)
+            type: 'FUNGIBLE',
+            // Use service fee amount from quote
+            amount: feeQuote.serviceFeeAmount, // includes precision
           },
           transportEndpoints: decodedServiceInvoice.transportEndpoints,
         },
@@ -467,22 +504,39 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
   }
 
   /**
-   * Step 3: Submit UNSIGNED PSBT + consignment to service
+   * Advanced Stage 2b: Submit unsigned PSBT to service for co-signing
+   *
+   * Submits the unsigned PSBT along with the RGB consignment to the service.
+   * The service will:
+   * 1. Cryptographically verify the RGB fee allocation in the consignment
+   * 2. Co-sign the mining input
+   * 3. Return the PSBT with its signature attached
    *
-   * The service:
-   *   1. Verifies the consignment cryptographically
-   *   2. Co-signs the mining input
-   *   3. Returns the PSBT with its signature attached — user's RGB inputs
-   *      are still unsigned at this point
+   * Note: User's RGB inputs remain unsigned at this stage.
    *
-   * Consignment is read directly from the file that sendBegin() wrote to disk
+   * @param quoteId - Quote ID from the fee quote
+   * @param psbtResult - PSBT build result from buildPSBT()
+   * @param serviceFeeInvoice - Service fee RGB invoice from the quote
+   * @param assetId - Asset ID being transferred
+   * @returns Submit result with service-signed PSBT
+   *
+   * @example
+   * ```typescript
+   * const submitResult = await gasFree.submitPSBT(
+   *   quote.quoteId,
+   *   psbtResult,
+   *   quote.serviceFeeInvoice,
+   *   request.assetId
+   * );
+   * console.log('Service signed PSBT:', submitResult.signedPsbtBase64);
+   * ```
    */
-  private async submitPSBT(
+  async submitPSBT(
     quoteId: string,
-    psbtResult: any,
+    psbtResult: PSBTBuildResult,
     serviceFeeInvoice: string,
     assetId: string
-  ) {
+  ): Promise<PSBTSubmitResult> {
     this.logger?.debug('Step 3: Reading consignment and submitting to service');
 
     const consignmentBase64 = await this.consignmentReader!.readForAsset(
@@ -508,20 +562,27 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
   }
 
   /**
-   * Step 4: User signs RGB inputs + broadcast via sendEnd
+   * Advanced Stage 2c: Sign RGB inputs and broadcast transaction
    *
    * Takes the PSBT returned by the service (mining input already signed),
-   * adds the user's RGB input signatures, then calls sendEnd() which:
-   *   - Finalizes all inputs (combines witness data)
-   *   - Posts consignments to the RGB proxy
-   *   - Broadcasts the transaction to the Bitcoin network
+   * adds the user's RGB input signatures, then calls wallet.sendEnd() which:
+   * - Finalizes all inputs (combines witness data)
+   * - Posts consignments to the RGB proxy
+   * - Broadcasts the transaction to the Bitcoin network
+   *
+   * @param serviceSignedPsbt - Service-signed PSBT from submitPSBT()
+   * @returns Broadcast result with txid and fully-signed PSBT
    *
-   * Returns the txid from sendEnd (the ground-truth broadcast result) and
-   * the fully-signed PSBT for the verify-transfer call.
+   * @example
+   * ```typescript
+   * const broadcastResult = await gasFree.broadcastTransfer(
+   *   submitResult.signedPsbtBase64
+   * );
+   * console.log('Transaction ID:', broadcastResult.txid);
+   * console.log('Fully signed PSBT:', broadcastResult.userSignedPsbt);
+   * ```
    */
-  private async broadcastTransfer(
-    serviceSignedPsbt: string
-  ): Promise<{ txid: string; userSignedPsbt: string }> {
+  async broadcastTransfer(serviceSignedPsbt: string): Promise<BroadcastResult> {
     this.logger?.debug(
       'Step 4: User signs RGB inputs and broadcasts via sendEnd'
     );
@@ -550,17 +611,34 @@ export class GasFreeModule implements IFeatureModule<GasFreeConfig> {
   }
 
   /**
-   * Step 5: Verify transfer completion
+   * Advanced Stage 2d: Verify transfer completion with service
    *
    * Notifies the service that the transaction has been broadcast. The service
-   * will look up the txid in mempool to confirm it landed, then call its own
-   * wallet.refresh() to claim the RGB service fee from the proxy.
+   * will:
+   * - Look up the txid in mempool to confirm it landed
+   * - Call its own wallet.refresh() to claim the RGB service fee
+   *
+   * @param quoteId - Quote ID from the fee quote
+   * @param txid - Transaction ID from broadcastTransfer()
+   * @param signedPsbtBase64 - Fully-signed PSBT from broadcastTransfer()
+   * @returns Verification result from the service
+   *
+   * @example
+   * ```typescript
+   * const verifyResult = await gasFree.verifyTransfer(
+   *   quote.quoteId,
+   *   broadcastResult.txid,
+   *   broadcastResult.userSignedPsbt
+   * );
+   * console.log('Verification status:', verifyResult.status);
+   * console.log('In mempool:', verifyResult.inMempool);
+   * ```
    */
-  private async verifyTransfer(
+  async verifyTransfer(
     quoteId: string,
     txid: string,
     signedPsbtBase64: string
-  ) {
+  ): Promise<VerificationResult> {
     this.logger?.debug('Step 4: Verifying transfer');
 
     const verifyResult = await this.serviceClient!.verifyTransfer({

package/src/features/gas-free/types/StageResults.ts

@@ -0,0 +1,95 @@
+/**
+ * Gas-Free Transfer Stage Result Types
+ *
+ * Result types for individual stages of the gas-free transfer workflow.
+ * These types are used by advanced users who want granular control over
+ * each stage of the transfer process.
+ *
+ * @module features/gas-free/types/StageResults
+ */
+
+/**
+ * Transfer state tracking
+ *
+ * Internal state used by the GasFreeModule to track the progress
+ * of a gas-free transfer through its various stages.
+ */
+export interface TransferState {
+  /** Quote ID from the fee quote */
+  quoteId?: string;
+  /** Quote expiration timestamp (milliseconds) */
+  quoteExpiresAt?: number;
+  /** Base64-encoded PSBT */
+  psbtBase64?: string;
+  /** Transaction ID */
+  txid?: string;
+  /** Current transfer status */
+  status:
+    | 'idle'
+    | 'quote-requested'
+    | 'psbt-built'
+    | 'submitted'
+    | 'broadcasted'
+    | 'verified'
+    | 'failed';
+  /** Error if transfer failed */
+  error?: Error;
+}
+
+/**
+ * Result of PSBT building stage (buildPSBT)
+ *
+ * Contains the unsigned PSBT with external mining inputs from the service,
+ * along with details about the mining fee and external inputs.
+ */
+export interface PSBTBuildResult {
+  /** Unsigned PSBT (base64) with external mining inputs */
+  unsignedPsbt: string;
+  /** Mining fee in satoshis */
+  miningFee: number;
+  /** External inputs added to the PSBT */
+  externalInputs: Array<{
+    txid: string;
+    vout: number;
+    value: number;
+    scriptPubkey: string;
+  }>;
+}
+
+/**
+ * Result of PSBT submission stage (submitPSBT)
+ *
+ * Contains the service-signed PSBT along with transaction details
+ * and the RGB consignment data.
+ */
+export interface PSBTSubmitResult {
+  /** Quote ID used */
+  quoteId: string;
+  /** Base64-encoded signed PSBT with service signatures */
+  signedPsbtBase64: string;
+  /** Transaction ID */
+  transactionId: string;
+  /** Estimated transaction size in vBytes */
+  estimatedTxSize: number;
+  /** Mining UTXO transaction ID */
+  miningUtxoTxid: string;
+  /** Mining UTXO output index */
+  miningUtxoVout: number;
+  /** Timestamp when signed */
+  signedAt: string;
+  /** Base64-encoded consignment data */
+  consignmentBase64: string;
+}
+
+/**
+ * Result of broadcast stage (broadcastTransfer)
+ *
+ * Contains the transaction ID from the successful broadcast and
+ * the fully-signed PSBT with both user and service signatures.
+ */
+export interface BroadcastResult {
+  /** Transaction ID from the broadcast */
+  txid: string;
+  /** Fully signed PSBT (user + service signatures) */
+  userSignedPsbt: string;
+}

package/src/features/gas-free/types/index.ts

@@ -48,3 +48,11 @@ export {
   isTransferSuccessful,
   getTransferDuration,
 } from './GasFreeResult';
+
+// Stage result types (for advanced users)
+export type {
+  TransferState,
+  PSBTBuildResult,
+  PSBTSubmitResult,
+  BroadcastResult,
+} from './StageResults';

package/src/features/watch-tower/WatchTowerModule.ts

@@ -13,10 +13,13 @@ import type { IFeatureModule } from '../../types/IFeatureModule';
 import type { Wallet } from '../../core/Wallet';
 import type { Logger } from '../../utils/logger';
 import type { WatchTowerConfig } from './types';
+import type { AddToWatchTowerParams } from './types/WatchTowerRequest';
+import type { AddToWatchTowerResponse } from './types/WatchTowerResponse';
 import { getWatchTowerServiceUrl } from './types/WatchTowerConfig';
+import { Feature } from '../../types/Feature';
 
 export class WatchTowerModule implements IFeatureModule<WatchTowerConfig> {
-  readonly name = 'watchTower' as const;
+  readonly name = Feature.WATCH_TOWER;
   readonly config: WatchTowerConfig;
 
   private client: AxiosInstance | null = null;
@@ -75,12 +78,17 @@ export class WatchTowerModule implements IFeatureModule<WatchTowerConfig> {
   }
 
   /**
-   * Add an invoice to the Watch Tower.
+   * Register an RGB invoice with the Watch Tower service.
    *
-   * @param invoice - The invoice string to add to watchtower
-   * @returns Promise with the response data
+   * @param params - Invoice string plus optional FCM token, email, or web push subscription
+   * @returns Successful response body (`status`, `message`, `data`). Errors throw.
    */
-  async addToWatchTower(invoice: string): Promise<unknown> {
+  async addToWatchTower({
+    invoice,
+    fcmToken,
+    email,
+    webPushNotification,
+  }: AddToWatchTowerParams): Promise<AddToWatchTowerResponse> {
     if (!this.isReady() || !this.client) {
       throw new Error(
         'Orbis1 SDK not initialized. Call initOrbis1({ apiKey }) first.'
@@ -91,13 +99,18 @@ export class WatchTowerModule implements IFeatureModule<WatchTowerConfig> {
       invoicePrefix: invoice.slice(0, 20) + '...',
     });
 
-    const payload: { invoice: string; fcmToken?: string } = { invoice };
-    if (this.fcmToken) {
-      payload.fcmToken = this.fcmToken;
-    }
+    const payload: AddToWatchTowerParams = {
+      invoice,
+      fcmToken: fcmToken ?? this.fcmToken,
+      ...(email && { email }),
+      ...(webPushNotification && { webPushNotification }),
+    };
 
     try {
-      const response = await this.client.post('/addToWatchTower', payload);
+      const response = await this.client.post<AddToWatchTowerResponse>(
+        '/addToWatchTower',
+        payload
+      );
       this.logger?.debug('Invoice added successfully');
       return response.data;
     } catch (error) {

package/src/features/watch-tower/index.ts

@@ -5,4 +5,12 @@
  */
 
 export { WatchTowerModule } from './WatchTowerModule';
-export type { WatchTowerConfig } from './types';
+export type {
+  WatchTowerConfig,
+  AddToWatchTowerParams,
+  AddToWatchTowerResponse,
+  AddToWatchTowerResponseData,
+  AddToWatchTowerWebPushEcho,
+  WatchTowerWebPushKeys,
+  WatchTowerWebPushSubscription,
+} from './types';

package/src/features/watch-tower/types/WatchTowerRequest.ts

@@ -0,0 +1,47 @@
+/**
+ * Watch Tower request types
+ *
+ * Parameters for Watch Tower service calls
+ *
+ * @module features/watch-tower/types/WatchTowerRequest
+ */
+
+/**
+ * Web Push subscription keys (from `PushSubscription.getKey()`)
+ */
+export interface WatchTowerWebPushKeys {
+  /** Base64 URL-safe P-256 ECDH public key */
+  p256dh: string;
+
+  /** Base64 URL-safe authentication secret */
+  auth: string;
+}
+
+/**
+ * Web Push subscription payload for the Watch Tower service
+ */
+export interface WatchTowerWebPushSubscription {
+  /** Push service endpoint URL */
+  endpoint: string;
+
+  /** Encryption keys from the browser push subscription */
+  keys: WatchTowerWebPushKeys;
+}
+
+/** Parameters for WatchTowerModule.addToWatchTower */
+export interface AddToWatchTowerParams {
+  /** RGB invoice string to monitor */
+  invoice: string;
+
+  /**
+   * FCM device token for mobile push notifications.
+   * If omitted, the default from WatchTowerModule.setFcmToken is used when set.
+   */
+  fcmToken?: string;
+
+  /** Email address for notifications */
+  email?: string;
+
+  /** Web Push subscription for browser notifications */
+  webPushNotification?: WatchTowerWebPushSubscription;
+}

package/src/features/watch-tower/types/WatchTowerResponse.ts

@@ -0,0 +1,52 @@
+/**
+ * Watch Tower API response types
+ *
+ * @module features/watch-tower/types/WatchTowerResponse
+ */
+
+import type { WatchTowerWebPushKeys } from './WatchTowerRequest';
+
+/**
+ * Web push subscription as returned by the service (`webPushSubscription` field).
+ * Mirrors the stored subscription shape (distinct request field name `webPushNotification`).
+ */
+export interface AddToWatchTowerWebPushEcho {
+  endpoint: string;
+  keys: WatchTowerWebPushKeys;
+}
+
+/**
+ * `data` payload on successful `POST /addToWatchTower`
+ */
+export interface AddToWatchTowerResponseData {
+  /** RGB invoice registered with Watch Tower */
+  invoice: string;
+
+  /** Parsed recipient / UTXO identifier from the invoice */
+  recipient_id: string;
+
+  /** RGB transport endpoint extracted from the invoice */
+  endpoint_url: string;
+
+  /** Present when an FCM token was registered */
+  fcmToken?: string;
+
+  /** Present when a web push subscription was registered */
+  webPushSubscription?: AddToWatchTowerWebPushEcho;
+
+  /** Present when an email was registered */
+  email?: string;
+
+  /** Watch Tower expiry for this registration (Unix seconds) */
+  expiry: number;
+}
+
+/**
+ * Successful JSON body returned by `addToWatchTower` (HTTP 2xx).
+ * Error responses are thrown as `Error` with optional `status` / `data`.
+ */
+export interface AddToWatchTowerResponse {
+  status: string;
+  message: string;
+  data: AddToWatchTowerResponseData;
+}

package/src/features/watch-tower/types/index.ts

@@ -1 +1,11 @@
 export type { WatchTowerConfig } from './WatchTowerConfig';
+export type {
+  AddToWatchTowerParams,
+  WatchTowerWebPushKeys,
+  WatchTowerWebPushSubscription,
+} from './WatchTowerRequest';
+export type {
+  AddToWatchTowerResponse,
+  AddToWatchTowerResponseData,
+  AddToWatchTowerWebPushEcho,
+} from './WatchTowerResponse';

package/src/{index.tsx → index.ts}

@@ -9,6 +9,7 @@
 // Core exports
 export * from './core/Interfaces';
 export * from './core/KeyManager';
+export type { Wallet } from './core/Wallet';
 
 // SDK
 export { Orbis1SDK } from './Orbis1SDK';
@@ -29,7 +30,15 @@ export { Logger, createLogger } from './utils/logger';
 
 // Watch Tower feature
 export { WatchTowerModule } from './features/watch-tower';
-export type { WatchTowerConfig } from './features/watch-tower';
+export type {
+  WatchTowerConfig,
+  AddToWatchTowerParams,
+  AddToWatchTowerResponse,
+  AddToWatchTowerResponseData,
+  AddToWatchTowerWebPushEcho,
+  WatchTowerWebPushKeys,
+  WatchTowerWebPushSubscription,
+} from './features/watch-tower';
 
 // Gas-Free feature
 export { GasFreeModule, createGasFreeModule } from './features/gas-free';
@@ -38,5 +47,9 @@ export type {
   GasFreeTransferRequest,
   GasFreeTransferResult,
   FeeQuote,
+  PSBTBuildResult,
+  PSBTSubmitResult,
+  BroadcastResult,
+  TransferState,
 } from './features/gas-free/types';
 export { GasFreeError, GasFreeErrorCode } from './features/gas-free/errors';

package/src/types/SDKConfig.ts

@@ -49,9 +49,11 @@ export enum LogLevel {
  */
 export enum Environment {
   /** Testnet4 environment */
-  TESTNET = 'testnet',
+  TESTNET4 = 'TESTNET4',
+  /** Regtest environment */
+  REGTEST = 'REGTEST',
   /** Mainnet environment (production) */
-  MAINNET = 'mainnet',
+  MAINNET = 'MAINNET',
 }
 
 /**
@@ -216,10 +218,13 @@ export function validateSDKConfig(config: SDKConfig): void {
   const apiKey = config.apiKey;
   const environment = config.environment ?? Environment.MAINNET;
 
-  if (environment === Environment.TESTNET) {
+  if (
+    environment === Environment.TESTNET4 ||
+    environment === Environment.REGTEST
+  ) {
     if (!apiKey.startsWith('pk_test')) {
       throw new Error(
-        `API key mismatch: testnet environment requires a testnet API key (prefix: pk_test), but got a key with prefix: ${apiKey.substring(
+        `API key mismatch: ${environment} environment requires a testnet API key (prefix: pk_test), but got a key with prefix: ${apiKey.substring(
           0,
           7
         )}`