JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 110
  • Score
    100M100P100Q79501F
  • License MIT

Wallet block for 23blocks SDK - digital wallets, transactions, and authorization codes

Package Exports

  • @23blocks/block-wallet
  • @23blocks/block-wallet/package.json

Readme

@23blocks/block-wallet

Wallet block for the 23blocks SDK - digital wallets, transactions, and authorization codes.

npm version License: MIT

Installation

npm install @23blocks/block-wallet @23blocks/transport-http

Overview

This package provides digital wallet functionality including:

  • Wallets - Digital wallet management with balance operations
  • Transactions - Transaction history and tracking
  • Authorization Codes - One-time codes for secure transactions

Quick Start

import { createHttpTransport } from '@23blocks/transport-http';
import { createWalletBlock } from '@23blocks/block-wallet';

const transport = createHttpTransport({
  baseUrl: 'https://api.yourapp.com',
  headers: () => {
    const token = localStorage.getItem('access_token');
    return token ? { Authorization: `Bearer ${token}` } : {};
  },
});

const wallet = createWalletBlock(transport, {
  apiKey: 'your-api-key',
});

// Get user's wallet
const userWallet = await wallet.wallets.getByUser('user-id');
console.log('Balance:', userWallet.balance);

// Credit wallet
await wallet.wallets.credit('wallet-id', {
  amount: 50,
  reason: 'Referral bonus',
});

Services

wallets - Wallet Management

// List wallets
const { data: wallets } = await wallet.wallets.list({
  limit: 20,
  status: 'active',
});

// Get wallet by ID
const w = await wallet.wallets.get('wallet-id');

// Get wallet by user
const userWallet = await wallet.wallets.getByUser('user-id');

// Create wallet
const newWallet = await wallet.wallets.create({
  userId: 'user-id',
  currency: 'USD',
  initialBalance: 0,
});

// Update wallet
await wallet.wallets.update('wallet-id', {
  status: 'frozen',
  frozenReason: 'Suspicious activity',
});

// Credit wallet (add funds)
await wallet.wallets.credit('wallet-id', {
  amount: 100,
  reason: 'deposit',
  referenceId: 'payment-123',
  notes: 'Bank transfer deposit',
});

// Debit wallet (remove funds)
await wallet.wallets.debit('wallet-id', {
  amount: 25,
  reason: 'purchase',
  referenceId: 'order-456',
  notes: 'Product purchase',
});

// Delete wallet
await wallet.wallets.delete('wallet-id');

transactions - Transaction History

// List transactions
const { data: transactions, meta } = await wallet.transactions.list({
  walletId: 'wallet-id',
  limit: 50,
});

transactions.forEach((tx) => {
  console.log(tx.type, tx.amount, tx.reason, tx.createdAt);
});

// Get transaction by ID
const transaction = await wallet.transactions.get('transaction-id');

// Filter transactions by type
const credits = await wallet.transactions.list({
  walletId: 'wallet-id',
  type: 'credit',
});

const debits = await wallet.transactions.list({
  walletId: 'wallet-id',
  type: 'debit',
});

// Filter by date range
const recent = await wallet.transactions.list({
  walletId: 'wallet-id',
  startDate: '2024-01-01',
  endDate: '2024-12-31',
});

authorizationCodes - Secure Transaction Codes

// List authorization codes
const { data: codes } = await wallet.authorizationCodes.list({
  walletId: 'wallet-id',
  status: 'active',
});

// Get code by ID
const code = await wallet.authorizationCodes.get('code-id');

// Create authorization code
const newCode = await wallet.authorizationCodes.create({
  walletId: 'wallet-id',
  amount: 50,
  expiresAt: new Date(Date.now() + 30 * 60 * 1000).toISOString(), // 30 minutes
  singleUse: true,
  purpose: 'in_store_payment',
});

console.log('Code:', newCode.code);
console.log('Expires:', newCode.expiresAt);

// Validate code
const validation = await wallet.authorizationCodes.validate({
  code: 'ABC123',
  walletId: 'wallet-id',
});

if (validation.valid) {
  console.log('Code is valid for amount:', validation.amount);
} else {
  console.log('Invalid code:', validation.error);
}

// Use authorization code (debit wallet)
await wallet.authorizationCodes.use({
  code: 'ABC123',
  walletId: 'wallet-id',
  merchantId: 'merchant-123',
  referenceId: 'purchase-789',
});

// Void unused code
await wallet.authorizationCodes.void('code-id');

Types

import type {
  Wallet,
  Transaction,
  TransactionType,
  AuthorizationCode,
  CreateWalletRequest,
  CreditWalletRequest,
  DebitWalletRequest,
  CreateAuthorizationCodeRequest,
  ValidateAuthorizationCodeRequest,
  UseAuthorizationCodeRequest,
  ListTransactionsParams,
} from '@23blocks/block-wallet';

Wallet

Property Type Description
id string Wallet ID
userId string Owner user ID
balance number Current balance
currency string Currency code
status string active, frozen, closed

Transaction

Property Type Description
id string Transaction ID
walletId string Wallet ID
type TransactionType credit or debit
amount number Transaction amount
balanceAfter number Balance after transaction
reason string Transaction reason
referenceId string External reference
createdAt Date Transaction timestamp

TransactionType

  • credit - Funds added to wallet
  • debit - Funds removed from wallet

AuthorizationCode

Property Type Description
id string Code ID
code string The authorization code
walletId string Associated wallet
amount number Authorized amount
status string active, used, expired, voided
expiresAt Date Expiration timestamp
singleUse boolean One-time use only

Error Handling

import { isBlockErrorException, ErrorCodes } from '@23blocks/contracts';

try {
  await wallet.wallets.debit('wallet-id', { amount: 1000 });
} catch (error) {
  if (isBlockErrorException(error)) {
    switch (error.code) {
      case 'INSUFFICIENT_BALANCE':
        console.log('Not enough funds in wallet');
        break;
      case 'WALLET_FROZEN':
        console.log('Wallet is frozen');
        break;
      case ErrorCodes.NOT_FOUND:
        console.log('Wallet not found');
        break;
    }
  }
}

License

MIT - Copyright (c) 2024 23blocks