SDK Overview

The Freeq TypeScript SDK provides a high-level, strongly-typed interface for integrating with the Freeq API. Built on top of our REST API, it simplifies common workflows and provides rich object models with full TypeScript support.

When to Use the SDK

The SDK is ideal for:

• Modern web applications using TypeScript or JavaScript
• Rapid development with minimal boilerplate code
• Type safety and IDE autocomplete support
• Simplified error handling with built-in retry logic
• Object-oriented workflows instead of raw HTTP requests

SDK vs REST API

Feature	TypeScript SDK	REST API
Type Safety	Full TypeScript definitions	Manual type handling
Error Handling	Built-in retry and error management	Manual implementation
Authentication	Automatic token management	Manual JWT handling
Response Parsing	Rich object models	Raw JSON responses
Learning Curve	Minimal - method-based	Moderate - HTTP-based
Flexibility	High-level abstractions	Complete control

Prerequisites

Before using the SDK, ensure you've completed our setup requirements:

• Prerequisites Checklist - JWT configuration and project key
• Integration Guide - Understanding the authentication flow
• Node.js 16+ and TypeScript 4.5+ (recommended)

Quick Start

Installation

npm install @freeq/sdk
# or
yarn add @freeq/sdk

Basic Usage

import FreeqSDK from '@freeq/sdk';

// Initialize the SDK
const sdk = new FreeqSDK({
  baseUrl: process.env.FREEQ_API_URL || "https://api.testnet.superfreeq.com",
  apiKey: process.env.FREEQ_PROJECT_KEY || "your-project-key-here"
});

// Authenticate user and get wallet
const userToken = generateUserJWT(user); // Your JWT generation logic
const wallet = await sdk.signIn(userToken);

console.log('User wallet address:', wallet.address);

Complete Integration Example

import FreeqSDK from '@freeq/sdk';

class UserService {
  private sdk: FreeqSDK;

  constructor() {
    this.sdk = new FreeqSDK({
      baseUrl: process.env.FREEQ_API_URL,
      apiKey: process.env.FREEQ_PROJECT_KEY
    });
  }

  async authenticateUser(email: string, password: string) {
    try {
      // 1. Authenticate with your system
      const user = await this.authenticateWithYourSystem(email, password);
      
      // 2. Generate JWT for user
      const userJWT = this.generateJWT(user);
      
      // 3. Sign in to Freeq (creates wallet if needed)
      const wallet = await this.sdk.signIn(userJWT);
      
      // 4. Get user's organisations
      const organisations = await this.sdk.getOrganisations();
      
      return {
        user,
        wallet,
        organisations
      };
    } catch (error) {
      console.error('Authentication failed:', error);
      throw error;
    }
  }
}

Core Concepts

Authentication Flow

The SDK handles the same authentication flow described in our Getting Started Guide, but abstracts the HTTP requests:

// SDK handles this workflow automatically:
// 1. Validate your JWT
// 2. Call /signin or /createasync as needed  
// 3. Return structured Wallet object
const wallet = await sdk.signIn(userJWT);

Error Handling

The SDK provides structured error handling with retry logic:

import { FreeqError, AuthenticationError, NetworkError } from '@freeq/sdk';

try {
  const wallet = await sdk.signIn(userToken);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // JWT validation failed - check prerequisites
    console.error('Auth error:', error.message);
  } else if (error instanceof NetworkError) {
    // Network issue - retry logic already applied
    console.error('Network error:', error.message);
  } else {
    // Other SDK errors
    console.error('SDK error:', error);
  }
}

TypeScript Support

The SDK provides full TypeScript definitions:

// Rich type information and autocomplete
interface Wallet {
  address: string;
  id: number;
  createdAt: Date;
  // ... other properties
}

interface Organisation {
  id: string;
  name: string;
  projects: Project[];
  // ... other properties
}

SDK Architecture

Main Classes

The SDK is organized around key domain objects:

• FreeqSDK - Main entry point and authentication
• Wallet - User wallet operations and transactions
• Organisation - Organisation management
• Project - Project-specific operations
• Membership - Token-based access control

Method Mapping to API Endpoints

SDK methods correspond to REST API endpoints:

SDK Method	API Endpoint	Documentation
sdk.signIn()	POST /api/v1/signin	Authentication
wallet.getInventory()	GET /api/v1/wallets/{address}/inventory	Inventory
membership.issue()	POST /api/v1/membership/issue	Membership
project.getMembers()	GET /api/v1/projects/{id}/members	Organizations

Integration with Other Documentation

Getting Started → SDK → API Reference

1. Start with Getting Started to understand Freeq concepts
2. Use the SDK for streamlined TypeScript integration
3. Reference the REST API docs for advanced features or troubleshooting

When to Use REST API Instead

Consider the REST API directly when you need:

• Non-JavaScript environments (Python, PHP, Go, etc.)
• Maximum control over HTTP requests and responses
• Custom retry logic or error handling
• Advanced features not yet available in the SDK
• Webhook endpoints (server-side only)

Advanced Features

Webhook Integration

While the SDK handles API calls, webhooks require server-side REST API integration:

// SDK for client operations
const wallet = await sdk.signIn(userToken);

// REST API for webhook handling (server-side)
app.post('/webhooks/freeq', (req, res) => {
  // Handle webhook payload
  // See: ../api/webhooks
});

Custom Configuration

const sdk = new FreeqSDK({
  baseUrl: process.env.FREEQ_API_URL || "https://api.testnet.superfreeq.com",
  apiKey: process.env.FREEQ_PROJECT_KEY
});

Troubleshooting

Common SDK Issues

Authentication Errors

// Check JWT configuration
if (error instanceof AuthenticationError) {
  // Review: ../getting-started/prerequisites
  console.error('Check JWT configuration:', error.details);
}

Network Timeouts

// Increase timeout for wallet creation
const sdk = new FreeqSDK({
  // ...
  timeout: 60000 // 60 seconds for wallet creation
});

TypeScript Compilation Issues

# Ensure compatibility
npm install typescript@^4.5.0
npm install @types/node@^16.0.0

For detailed troubleshooting, see our Troubleshooting Guide.

Next Steps

Explore SDK Classes

• FreeqSDK - Main SDK class and authentication
• Wallet - Wallet operations and transactions
• Organisation - Organisation management
• Project - Project-specific operations

Related Documentation

• Getting Started Guide - Step-by-step implementation
• REST API Reference - Complete endpoint documentation
• Advanced Features - Smart contracts and token issuance

Examples and Tutorials

• Authentication Example - Complete auth flow
• Wallet Management - Asset operations
• Organisation Setup - Multi-tenant patterns

---

The TypeScript SDK provides the fastest path to Freeq integration while maintaining the flexibility to use the REST API directly when needed. Start here for modern web applications, then explore the complete API reference for advanced use cases.