EcoBackend SDK

TypeScript SDK for EcoBackend microservices providing type-safe clients for AI, Blockchain, Eco, Entity, and Payment APIs.

Changelog

v2.1.2 (2026-03-16)

• Merchant Model Updates: Added EVM wallet fields to Merchant models
  • Added addressEvm?: string - Ethereum Virtual Machine wallet address
  • Added nonce?: string - Cryptographic nonce for wallet operations
  • Updated all Merchant variants: Merchant, MerchantPreview, MerchantWrite, MerchantSearch, MerchantUpdate
• Testing: All integration tests passing with wallet ownership feature support

v2.1.1 (2026-02-13)

• New Utility: Added UuidUtils static class for UUID operations
  • isNilUuid() - Check if UUID is nil UUID (00000000-0000-0000-0000-000000000000)
  • isValidUuid() - Validate UUID format
  • isValidAndNotNil() - Check if UUID is valid and not nil
  • normalize() - Normalize UUID to lowercase
  • getNilUuid() - Get nil UUID constant

v2.1.0 (2026-02-12)

• Breaking Changes: Aligned TypeScript models with C# models
  • Fixed field naming conventions: merchantId → merchantFk, activityId → activityFk, userId → userFk, etc.
  • Updated OnlinePayment field: transactionId → transactionRef
  • Changed TravelPreference.createdAt from Date to number (Unix timestamp)
• New Interfaces: Added missing types for badge operations
  • UserBadgePreview, UserBadgeWrite, UserBadgeSearch, UserBadgeUpdate
• Enhancements: Added missing fields to Merchant (createdAt, updatedAt, updatedBy)
• Quality: All TypeScript models now mirror their C# counterparts exactly
• Testing: All 62 integration tests passing with updated models

Installation

npm install ecobackend-sdk

Usage

Eco1155 Signer Client

import { Eco1155SignerClient } from 'ecobackend-sdk';

const client = new Eco1155SignerClient({
  baseUrl: 'http://localhost:5003',
  apiKey: 'your-api-key',
  timeout: 30000 // optional
});

try {
  const response = await client.createMintWithSignature({
    addressToMint: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
    id: 1
  }, 'user-id');
  
  console.log('Mint successful:', response.data);
} catch (error) {
  if (error instanceof Eco1155ApiError) {
    console.error('API Error:', error.apiMessage);
  }
}

Microservice Clients

AI API Client

import { AIClient } from 'ecobackend-sdk';

const aiClient = new AIClient('http://localhost:5001', 'api-key');

// Travel preferences
const preferences = await aiClient.travelPreference.getAll();
const newPreference = await aiClient.travelPreference.create(preferenceData);

// Eco destinations 
const destinations = await aiClient.ecoDestinations.getAll();

Blockchain API Client

import { BlockchainClient } from 'ecobackend-sdk';

const blockchainClient = new BlockchainClient('http://localhost:5003', 'api-key');

// Badges management
const badges = await blockchainClient.badge.getAll();
const newBadge = await blockchainClient.badge.create(badgeData);

// User blockchain info
const userInfo = await blockchainClient.userBlockchainInfo.getById(userId);

// User badges
const userBadges = await blockchainClient.userBadge.getAll();

// ECO1155 NFT signing
const mintResult = await blockchainClient.eco1155Signer.createMintWithSignature({
  addressToMint: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
  id: 1
}, userId);

Eco API Client

import { EcoClient } from 'ecobackend-sdk';

const ecoClient = new EcoClient('http://localhost:5005', 'api-key');

// Activities management
const activities = await ecoClient.activity.getAll();
const newActivity = await ecoClient.activity.create(activityData);

// Activity bookings
const booking = await ecoClient.activityBooking.create(bookingData);

// Fortresses and conquest
const fortresses = await ecoClient.fortress.getAll();
const conquered = await ecoClient.conqueredFortress.getByUserId(userId);

// Reviews and ratings
const reviews = await ecoClient.review.getAll();
const newReview = await ecoClient.review.create(reviewData);

// User points system
const points = await ecoClient.userPoint.getByUserId(userId);

Entity API Client

import { EntityClient } from 'ecobackend-sdk';

const entityClient = new EntityClient('http://localhost:5007', 'api-key');

// Merchants management
const merchants = await entityClient.merchant.getAll();
const newMerchant = await entityClient.merchant.create(merchantData);

Payment API Client

import { PaymentClient } from 'ecobackend-sdk';

const paymentClient = new PaymentClient('http://localhost:5009', 'api-key');

// Online payments
const payments = await paymentClient.onlinePayment.getAll();
const newPayment = await paymentClient.onlinePayment.create(paymentData);

Complete Example

import { AIClient, BlockchainClient, EcoClient } from 'ecobackend-sdk';

// Initialize all microservice clients
const ai = new AIClient('http://localhost:5001', 'api-key');
const blockchain = new BlockchainClient('http://localhost:5003', 'api-key');  
const eco = new EcoClient('http://localhost:5005', 'api-key');

// Use organized sub-clients
const preferences = await ai.travelPreference.getAll();
const badges = await blockchain.badge.getAll();
const activities = await eco.activity.getAll();

Features

• 🔷 Type Safety: Full TypeScript support with generated types
• 🛡️ Error Handling: Structured error responses with Eco1155ApiError
• ⚡ Performance: Efficient HTTP client with timeout support
• 📝 Validation: Input validation for Ethereum addresses and data
• 🔍 Debugging: Detailed error messages and status codes

Error Handling

The SDK uses structured error handling:

import { Eco1155ApiError } from 'ecobackend-sdk';

try {
  await client.createMintWithSignature(input, userId);
} catch (error) {
  if (error instanceof Eco1155ApiError) {
    console.log(`API Error ${error.statusCode}: ${error.apiMessage}`);
    if (error.apiError) {
      console.log('Details:', error.apiError);
    }
  }
}

Development

# Build the SDK
npm run build

# Watch mode
npm run dev

# Type checking
npm run type-check

License

MIT