SDK Reference

Overview

The IOTA Repstation SDK provides a comprehensive TypeScript API for integrating decentralized reputation management into your applications. The SDK supports both browser and server environments with full type safety.

Installation

npm install @repstation/sdk

Import Paths

The SDK provides optimized bundles for different environments:

import { RepstationClient } from '@repstation/sdk';

Core Classes

RepstationClient

The main client class for interacting with the IOTA Repstation system:

class RepstationClient {
  constructor(config: NetworkConfig, client?: IotaClient);
  
  // Static factory method (recommended)
  static async create(config: RepstationConfig): Promise<RepstationClient>;
  
  // Deal Management (returns Transaction objects for signing)
  openDealAdmin(params: OpenDealAdminParams): Transaction;
  openDealClient(params: OpenDealClientParams): Transaction;
  acceptDeal(params: AcceptDealParams): Transaction;
  closeDeal(params: CloseDealParams): Transaction;
  
  // Rating System (returns Transaction objects for signing)
  rate(params: RateParams): Transaction;
  updateRating(params: UpdateRatingParams): Transaction;
  revokeRating(params: RevokeRatingParams): Transaction;
  
  // Reputation Queries (async operations)
  getReputationProfile(params: GetReputationProfileParams): Promise<GetReputationProfileResponse>;
  getObject(params: GetObjectParams): Promise<any>;
  getProviderMetadata(params: GetProviderMetadataParams): Promise<GetProviderMetadataResponse>;
  
  // App Management (returns Transaction objects for signing)
  registerApp(params: RegisterAppParams): Transaction;
  mintClientCap(params: MintClientCapParams): Transaction;
  updateProviderMetadata(params: UpdateProviderMetadataParams): Transaction;
}

Configuration Types

RepstationConfig

interface RepstationConfig {
  network: 'testnet' | 'mainnet' | 'custom';
  packageId: string;
  rpcUrl?: string;          // Required for custom networks
  client?: IotaClient;      // Optional: provide your own client
}

interface NetworkConfig {
  packageId: string;
  registryId: string;       // Required
  aggregatesId: string;     // Required
  rpcUrl?: string;
}

Deal Management Types

Deal Creation

interface OpenDealAdminParams {
  admin_cap: string;        // AdminCap object ID
  party_b: string;          // Address of party B
  subject_ref: string;      // Deal subject reference as string
  amount: string;           // Deal amount as string
}

interface OpenDealClientParams {
  client_cap: string;       // ClientCap object ID
  party_b: string;          // Address of party B
  subject_ref: string;      // Deal subject reference as string
  amount: string;           // Deal amount as string
}

// Methods return Transaction objects for signing, not result objects
// The transaction needs to be signed and submitted by the caller

Deal Lifecycle

interface AcceptDealParams {
  deal_id: string;          // Deal object ID to accept
}

interface CloseDealParams {
  deal_id: string;          // Deal object ID to close
}

Rating System Types

Rating Creation

interface RateParams {
  deal_id: string;          // Deal object ID to rate
  score: number;            // Rating score (1-100)
  category?: string;        // Optional rating category
}

interface UpdateRatingParams {
  endorsement_id: string;   // Endorsement object ID
  endorsement_cap: string;  // EndorsementCap object ID
  new_score: number;        // New rating score (1-100)
}

interface RevokeRatingParams {
  endorsement_id: string;   // Endorsement object ID
  endorsement_cap: string;  // EndorsementCap object ID
}

Provider Management Types

Provider Registration

interface RegisterAppParams {
  providerMetadata: {
    providerName: string;   // Required provider name
    publicUrl: string;      // Required public URL
    xHandle?: string;       // Optional X/Twitter handle
  };
}

interface UpdateProviderMetadataParams {
  adminCapId: string;       // AdminCap object ID
  providerName: string;     // Updated provider name
  publicUrl: string;        // Updated public URL
  xHandle?: string;         // Updated X/Twitter handle
}

interface MintClientCapParams {
  admin_cap: string;        // AdminCap object ID
  to: string;              // Address to mint capability to
  expires_at_ms?: number;   // Optional expiration timestamp
}

Reputation Query Types

Reputation Profile

interface GetReputationProfileParams {
  walletAddress: string;    // Wallet address to query
}

interface GetReputationProfileResponse {
  success: boolean;
  profile?: ReputationProfile;
  error?: string;
}

interface ReputationProfile {
  walletAddress: string;
  global?: ReputationStats;
  appScoped: AppScopedReputationData[];
  queryTimestamp: string;
}

interface ReputationStats {
  total: string;
  count: string;
  average: string;
}

interface AppScopedReputationData {
  appOwner: string;
  walletAddress: string;
  stats: ReputationStats;
}

Provider Metadata Query Types

interface GetProviderMetadataParams {
  namespaceId: string;      // Provider namespace ID
}

interface GetProviderMetadataResponse {
  success: boolean;
  metadata?: ProviderMetadata;
  error?: string;
}

interface ProviderMetadata {
  providerName: string;
  publicUrl: string;
  xHandle?: string;
}

Usage Examples

Basic Client Setup

import { RepstationClient } from '@repstation/sdk';

// Create client using factory method (recommended)
const client = await RepstationClient.create({
  network: 'testnet',
  packageId: '0xYOUR_PACKAGE_ID'
});

// Or create directly with network config
const client = new RepstationClient({
  network: 'testnet',
  packageId: '0xYOUR_PACKAGE_ID',
  registryId: '0xREGISTRY_ID',
  aggregatesId: '0xAGGREGATES_ID'
});

Working with Deals

// Open a deal (returns Transaction object)
const dealTx = client.openDealAdmin({
  admin_cap: '0xADMIN_CAP_ID',
  party_b: '0xCOUNTERPARTY_ADDRESS',
  subject_ref: 'NFT_12345',
  amount: '1000'
});

// Sign and submit the transaction
const result = await wallet.signAndSubmit(dealTx);
console.log('Deal ID:', result.objectChanges[0].objectId);

Rating and Reputation

// Submit a rating
const rateTx = client.rate({
  deal_id: '0xDEAL_ID',
  score: 85,
  category: 'quality'
});

// Get reputation profile
const profile = await client.getReputationProfile({
  walletAddress: '0xUSER_ADDRESS'
});

if (profile.success) {
  console.log('Global reputation:', profile.profile?.global?.average);
}

Error Handling

The SDK provides comprehensive error handling with custom error types:

class RepstationError extends Error {
  constructor(
    message: string,
    public code: string,
    public details?: any
  ) {
    super(message);
    this.name = 'RepstationError';
  }
}

// Usage example
try {
  await client.rate({
    deal_id: 'invalid-id',
    score: 85,
    category: 'delivery'
  });
} catch (error) {
  if (error instanceof RepstationError) {
    console.error('Contract error:', error.code, error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Common Error Codes

Code	Description	Solution
`INVALID_DEAL_ID`	Deal ID not found or invalid format	Verify deal ID exists and is correctly formatted
`DEAL_NOT_CLOSED`	Attempting to rate before deal is closed	Close the deal first using `closeDeal()`
`ALREADY_RATED`	User has already rated this deal	Use `updateRating()` instead of `rate()`
`NOT_PARTY_MEMBER`	User is not a participant in the deal	Only deal participants can rate each other
`INVALID_SCORE`	Score outside valid range (1-100)	Provide a score between 1 and 100

Mock Client

For development and testing, the SDK includes a mock client:

// Mock client is used automatically when no real IOTA client is provided
const mockClient = new RepstationClient({
  network: 'testnet',
  packageId: '0xMOCK_PACKAGE'
  // No client provided - uses MockIotaClient
});

// All operations return mock responses
const result = await mockClient.openDealAdmin({
  signer: '0xMOCK_SIGNER',
  admin_cap_id: '0xMOCK_CAP',
  party_b: '0xMOCK_PARTY_B',
  subject_ref: { type: 'TEST', id: '123' },
  amount: '1000'
});

console.log(result.deal_id); // Returns mock object ID

Bundle Information

The SDK provides optimized bundles:

ESM Bundle: ~27KB - Modern ES modules for bundlers
CJS Bundle: ~30KB - CommonJS for Node.js compatibility
Types Bundle: ~8KB - Full TypeScript definitions
Browser Bundle: Optimized for frontend applications
Server Bundle: Optimized for Node.js applications

Browser Compatibility

Chrome 91+
Firefox 90+
Safari 14+
Edge 91+

Node.js Compatibility

Node.js 16+
TypeScript 4.5+

Next Steps

Deal Management

Explore deal creation and lifecycle management APIs.

Rating System

Understand rating creation and management APIs.

Reputation Queries

Learn about reputation data retrieval.

Integration Examples

See real-world integration patterns.

Deal Management

Rating System

Reputation Queries

​Overview

​Installation

​Import Paths

​Core Classes

​RepstationClient

​Configuration Types

​RepstationConfig

​Deal Management Types

​Deal Creation

​Deal Lifecycle

​Rating System Types

​Rating Creation

​Provider Management Types

​Provider Registration

​Reputation Query Types

​Reputation Profile

​Provider Metadata Query Types

​Usage Examples

​Basic Client Setup

​Working with Deals

​Rating and Reputation

​Error Handling

​Common Error Codes

​Mock Client

​Bundle Information

​Browser Compatibility

​Node.js Compatibility

​Next Steps

Deal Management

Rating System

Reputation Queries

Integration Examples

Overview

Installation

Import Paths

Core Classes

RepstationClient

Configuration Types

RepstationConfig

Deal Management Types

Deal Creation

Deal Lifecycle

Rating System Types

Rating Creation

Provider Management Types

Provider Registration

Reputation Query Types

Reputation Profile

Provider Metadata Query Types

Usage Examples

Basic Client Setup

Working with Deals

Rating and Reputation

Error Handling

Common Error Codes

Mock Client

Bundle Information

Browser Compatibility

Node.js Compatibility

Next Steps