@doma-protocol/orderbook-sdk v0.1.0

Doma Orderbook SDK

A TypeScript SDK for interacting with the Doma Orderbook.

Initialization

Initialize the Doma Orderbook client with your configuration:

import { createDomaOrderbookClient } from '@doma-protocol/orderbook-sdk';
import { baseSepolia } from 'viem/chains';

createDomaOrderbookClient({
  chains: [baseSepolia],
  source: 'doma.xyz',
  apiClientOptions: {
    baseUrl: 'http://localhost:5002',
    defaultHeaders: {
      'api-key': 'xxx',
    },
  },
});

Core Features

Creating Listings

const client = getDomaOrderbookClient();

await client.createListing({
  wallet: signer,
  chainId,
  params: {
    items,
    orderbook,
    source,
    marketplaceFees,
    customRoyalties,
  },
  onProgress: (steps) => {
    console.log('Progress:', steps);
  },
  onSuccess: (result) => {
    console.log('Success:', result);
  },
  onError: (error) => {
    console.error('Error:', error);
  },
});

Buying Listings

const client = getDomaOrderbookClient();

await client.buyListing({
  wallet: signer,
  chainId,
  params: {
    chainId,
    orderId,
  },
  onProgress: (steps) => {
    console.log('Progress:', steps);
  },
  onSuccess: (result) => {
    console.log('Success:', result);
  },
  onError: (error) => {
    console.error('Error:', error);
  },
});

Error Handling

The SDK implements a comprehensive error handling system through the DomaOrderbookError class.

Error Codes

enum DomaOrderbookErrorCode {
  // Generic errors
  INVALID_PARAMETERS = 'INVALID_PARAMETERS',
  WALLET_NOT_CONNECTED = 'WALLET_NOT_CONNECTED',
  BLOCKCHAIN_ERROR = 'BLOCKCHAIN_ERROR',
  API_ERROR = 'API_ERROR',
  UNKNOWN_ERROR = 'UNKNOWN_ERROR',

  // Seaport specific
  SEAPORT_APPROVAL_FAILED = 'SEAPORT_APPROVAL_FAILED',
  SEAPORT_SIGNATURE_FAILED = 'SEAPORT_SIGNATURE_FAILED',
  SEAPORT_TRANSACTION_FAILED = 'SEAPORT_TRANSACTION_FAILED',

  // Listing specific
  LISTING_CREATION_FAILED = 'LISTING_CREATION_FAILED',
  LISTING_VALIDATION_FAILED = 'LISTING_VALIDATION_FAILED',

  // Order specific
  BUY_LISTING_FAILED = 'BUY_LISTING_FAILED',
  ORDER_NOT_FOUND = 'ORDER_NOT_FOUND',

  // SDK specific
  CLIENT_NOT_INITIALIZED = 'CLIENT_NOT_INITIALIZED',
  INITIALIZATION_ERROR = 'INITIALIZATION_ERROR',
}

Error Structure

Each error contains:

• code: The specific error code from DomaOrderbookErrorCode
• message: A human-readable error message
• details: Additional error information (optional)
• context: Contextual information about when the error occurred (optional)
• timestamp: When the error occurred

Example Error Handling

try {
  await client.buyListing({
    // ... listing parameters
  });
} catch (error) {
  if (error instanceof DomaOrderbookError) {
    switch (error.code) {
      case DomaOrderbookErrorCode.WALLET_NOT_CONNECTED:
        console.error('Please connect your wallet');
        break;
      case DomaOrderbookErrorCode.SEAPORT_APPROVAL_FAILED:
        console.error('Failed to approve transaction');
        break;
      default:
        console.error('An error occurred:', error.message);
    }

    // Access additional error information
    console.log('Error details:', error.details);
    console.log('Error context:', error.context);
    console.log('Error timestamp:', error.timestamp);
  }
}

Types

BuyListingProps

type BuyListingProps = {
  orderIds: string[];
  chainId: Caip2ChainId;
  onProgress?: OnProgressCallback;
  onSuccess?: (data: BuyListingResult) => void;
  onError?: (error: ErrorInfo) => void;
};

ListingProps

type ListingProps = {
  items: ListingItem[];
  chainId: Caip2ChainId;
  orderbook?: OrderbookType;
  source?: string;
  customRoyalties?: Fee[];
  marketplaceFees?: Fee[];
  onProgress?: OnProgressCallback;
  onSuccess?: (data: CreateListingResult) => void;
  onError?: (error: ErrorInfo) => void;
};

Progress Tracking

The SDK provides progress tracking through the onProgress callback. This allows you to monitor the status of operations in real-time.

onProgress: (steps: ProgressStep[]) => {
  steps.forEach((step) => {
    console.log(`Step ${step.number}: ${step.status}`);
  });
};