Package Exports

@treza/sdk
@treza/sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@treza/sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Treza Platform SDK

TypeScript/JavaScript SDK for the Treza Platform API. This SDK enables developers to manage secure enclaves, integrate GitHub repositories, and handle platform resources with wallet-based authentication.

Features

🔐 Enclave Management - Create, update, delete, and manage secure enclaves
⏸️ Lifecycle Control - Pause, resume, and terminate enclaves with real-time status tracking
📜 Comprehensive Logs - Access application, deployment, and error logs from all sources
🐳 Docker Integration - Search Docker Hub and browse image tags
🏗️ Provider System - Support for multiple enclave providers (AWS Nitro, etc.)
⚙️ Task Scheduling - Create and manage scheduled tasks within enclaves
🔑 API Key Management - Generate and manage API keys with fine-grained permissions
🐙 GitHub Integration - OAuth flow, repository access, and branch management
💳 Wallet Authentication - Secure wallet-based authentication system
🌍 Multi-Region Support - Deploy enclaves across different AWS regions
📱 TypeScript First - Full TypeScript support with comprehensive type definitions

Installation

npm install @treza/sdk

Quick Start

import { TrezaClient } from '@treza/sdk';

// Initialize the client
const client = new TrezaClient();
const walletAddress = '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB';

// Get available providers
const providers = await client.getProviders();

// Create an enclave
const enclave = await client.createEnclave({
  name: 'My Trading Bot',
  description: 'Secure environment for trading algorithms',
  region: 'us-east-1',
  walletAddress: walletAddress,
  providerId: providers[0].id, // Use the first available provider
  providerConfig: {
    dockerImage: 'trading-bot:latest',
    cpuCount: 2,
    memoryMiB: 512
  }
});

console.log('Enclave created:', enclave.id);
console.log('Status:', enclave.status); // PENDING_DEPLOY, DEPLOYING, DEPLOYED, etc.

// 🆕 NEW: Manage enclave lifecycle
if (enclave.status === 'DEPLOYED') {
  // Pause the enclave
  const pausedEnclave = await client.pauseEnclave(enclave.id, walletAddress);
  console.log('Enclave paused:', pausedEnclave.enclave.status); // PAUSING
  
  // Resume the enclave
  const resumedEnclave = await client.resumeEnclave(enclave.id, walletAddress);
  console.log('Enclave resumed:', resumedEnclave.enclave.status); // RESUMING
}

// 🆕 NEW: Get comprehensive logs
const logs = await client.getEnclaveLogs(enclave.id, 'application');
console.log('Application logs:', logs.logs.application?.length || 0);

// 🆕 NEW: Search Docker Hub
const dockerImages = await client.searchDockerImages('hello-world');
console.log('Found', dockerImages.results.length, 'Docker images');

// Get all enclaves for a wallet
const enclaves = await client.getEnclaves(walletAddress);
console.log('Total enclaves:', enclaves.length);

Configuration

The TrezaClient accepts the following configuration options:

const client = new TrezaClient({
  baseUrl: 'https://app.trezalabs.com', // Optional: API base URL (default shown)
  timeout: 30000                    // Optional: Request timeout in ms (default: 30000)
});

API Reference

Provider Management

`getProviders(): Promise<Provider[]>`

Retrieve all available enclave providers.

const providers = await client.getProviders();
console.log('Available providers:', providers.length);
providers.forEach(provider => {
  console.log(`- ${provider.name} (${provider.id})`);
  console.log(`  Regions: ${provider.regions.join(', ')}`);
});

`getProvider(providerId: string): Promise<Provider>`

Get details for a specific provider.

const provider = await client.getProvider('aws-nitro');
console.log('Provider:', provider.name);
console.log('Config schema:', provider.configSchema);

Enclave Management

`getEnclaves(walletAddress: string): Promise<Enclave[]>`

Retrieve all enclaves associated with a wallet address.

const enclaves = await client.getEnclaves('0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB');
console.log('Found enclaves:', enclaves.length);

`createEnclave(request: CreateEnclaveRequest): Promise<Enclave>`

Create a new secure enclave.

const enclave = await client.createEnclave({
  name: 'ML Training Environment',
  description: 'Secure environment for model training',
  region: 'us-east-1',
  walletAddress: '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB',
  providerId: 'aws-nitro',
  providerConfig: {
    dockerImage: 'ml-training:latest',
    cpuCount: 4,
    memoryMiB: 2048
  },
  githubConnection: {
    isConnected: false
  }
});

`updateEnclave(request: UpdateEnclaveRequest): Promise<Enclave>`

Update an existing enclave.

const updatedEnclave = await client.updateEnclave({
  id: 'enc_123456',
  walletAddress: '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB',
  description: 'Updated description',
  region: 'us-west-2',
  providerConfig: {
    dockerImage: 'ml-training:v2',
    cpuCount: 8,
    memoryMiB: 4096
  }
});

`deleteEnclave(enclaveId: string, walletAddress: string): Promise<string>`

Delete an enclave.

const message = await client.deleteEnclave('enc_123456', '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB');
console.log(message); // "Enclave deleted successfully"

🆕 Enclave Lifecycle Management

`getEnclave(enclaveId: string): Promise<Enclave>`

Get details for a specific enclave.

const enclave = await client.getEnclave('enc_123456');
console.log('Enclave status:', enclave.status);
console.log('Enclave region:', enclave.region);

`pauseEnclave(enclaveId: string, walletAddress: string): Promise<EnclaveLifecycleResponse>`

Pause a running enclave.

const result = await client.pauseEnclave('enc_123456', '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB');
console.log('Message:', result.message);
console.log('New status:', result.enclave.status); // PAUSING

`resumeEnclave(enclaveId: string, walletAddress: string): Promise<EnclaveLifecycleResponse>`

Resume a paused enclave.

const result = await client.resumeEnclave('enc_123456', '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB');
console.log('Message:', result.message);
console.log('New status:', result.enclave.status); // RESUMING

`terminateEnclave(enclaveId: string, walletAddress: string): Promise<EnclaveLifecycleResponse>`

Terminate an enclave (this will destroy the enclave).

const result = await client.terminateEnclave('enc_123456', '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB');
console.log('Message:', result.message);
console.log('New status:', result.enclave.status); // PENDING_DESTROY

🆕 Enclave Logs

`getEnclaveLogs(enclaveId: string, logType?: string, limit?: number): Promise<LogsResponse>`

Get logs for an enclave from various sources.

// Get all logs
const allLogs = await client.getEnclaveLogs('enc_123456', 'all', 100);
console.log('Available log types:', Object.keys(allLogs.logs));

// Get only application logs
const appLogs = await client.getEnclaveLogs('enc_123456', 'application', 50);
const applicationLogs = appLogs.logs.application || [];
console.log('Application log entries:', applicationLogs.length);

// Get only error logs
const errorLogs = await client.getEnclaveLogs('enc_123456', 'errors', 20);
const errors = errorLogs.logs.errors || [];
console.log('Error entries:', errors.length);

// Available log types: 'all', 'ecs', 'stepfunctions', 'lambda', 'application', 'errors'

Task Management

`getTasks(walletAddress: string): Promise<Task[]>`

Retrieve all tasks associated with a wallet address.

const tasks = await client.getTasks('0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB');
console.log('Found tasks:', tasks.length);

`createTask(request: CreateTaskRequest): Promise<Task>`

Create a new scheduled task.

const task = await client.createTask({
  name: 'Daily Price Monitor',
  description: 'Monitor cryptocurrency prices and send alerts',
  enclaveId: 'enc_123456',
  schedule: '0 9 * * *', // Every day at 9 AM
  walletAddress: '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB'
});

`updateTask(request: UpdateTaskRequest): Promise<Task>`

Update an existing task.

const updatedTask = await client.updateTask({
  id: 'task_123456',
  walletAddress: '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB',
  schedule: '0 */6 * * *', // Every 6 hours
  status: 'running'
});

`deleteTask(taskId: string, walletAddress: string): Promise<string>`

Delete a task.

const message = await client.deleteTask('task_123456', '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB');
console.log(message); // "Task deleted successfully"

API Key Management

`getApiKeys(walletAddress: string): Promise<ApiKey[]>`

Retrieve all API keys associated with a wallet address.

const apiKeys = await client.getApiKeys('0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB');
console.log('Found API keys:', apiKeys.length);

`createApiKey(request: CreateApiKeyRequest): Promise<ApiKey>`

Create a new API key with specified permissions.

const apiKey = await client.createApiKey({
  name: 'Production API Key',
  permissions: ['enclaves:read', 'tasks:read', 'logs:read'],
  walletAddress: '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB'
});
console.log('API Key created:', apiKey.key); // Only shown on creation

`updateApiKey(request: UpdateApiKeyRequest): Promise<ApiKey>`

Update an existing API key.

const updatedApiKey = await client.updateApiKey({
  id: 'key_123456',
  walletAddress: '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB',
  permissions: ['enclaves:read', 'enclaves:write', 'tasks:read'],
  status: 'active'
});

`deleteApiKey(apiKeyId: string, walletAddress: string): Promise<string>`

Delete an API key.

const message = await client.deleteApiKey('key_123456', '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB');
console.log(message); // "API key deleted successfully"

GitHub Integration

`getGitHubAuthUrl(state?: string): Promise<GitHubAuthResponse>`

Get GitHub OAuth authorization URL.

const auth = await client.getGitHubAuthUrl('custom-state');
console.log('Visit this URL to authorize:', auth.authUrl);

`exchangeGitHubCode(request: GitHubTokenRequest): Promise<GitHubTokenResponse>`

Exchange OAuth authorization code for access token.

const tokenResponse = await client.exchangeGitHubCode({
  code: 'authorization-code-from-callback',
  state: 'custom-state'
});

console.log('Access token:', tokenResponse.access_token);
console.log('User:', tokenResponse.user.login);

`getGitHubRepositories(accessToken: string): Promise<RepositoriesResponse>`

Get user's GitHub repositories.

const repos = await client.getGitHubRepositories('gho_xxxxxxxxxxxxxxxxxxxx');
console.log('Repositories:', repos.repositories.length);

`getRepositoryBranches(request: GetBranchesRequest): Promise<BranchesResponse>`

Get branches for a specific repository.

const branches = await client.getRepositoryBranches({
  accessToken: 'gho_xxxxxxxxxxxxxxxxxxxx',
  repository: 'username/repo-name'
});

console.log('Branches:', branches.branches.map(b => b.name));

🆕 Docker Hub Integration

`searchDockerImages(query: string): Promise<DockerSearchResponse>`

Search Docker Hub for container images.

const searchResults = await client.searchDockerImages('hello-world');
console.log('Found images:', searchResults.count);

searchResults.results.forEach(image => {
  console.log(`- ${image.name}: ${image.description}`);
  console.log(`  ⭐ ${image.stars} stars, Official: ${image.official}`);
});

`getDockerTags(repository: string): Promise<DockerTagsResponse>`

Get available tags for a specific Docker repository.

const tags = await client.getDockerTags('library/node');
console.log('Available tags:', tags.tags.length);

tags.tags.slice(0, 5).forEach(tag => {
  const sizeMB = (tag.size / (1024 * 1024)).toFixed(1);
  console.log(`- ${tag.name} (${sizeMB}MB, updated: ${tag.lastUpdated})`);
});

Usage Examples

Complete Enclave Setup

import { TrezaClient } from '@treza/sdk';

const client = new TrezaClient();
const walletAddress = '0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB';

async function setupEnclave() {
  try {
    // Get available providers
    const providers = await client.getProviders();
    console.log('🏗️  Available providers:', providers.length);

    // Create enclave
    const enclave = await client.createEnclave({
      name: 'Data Analytics Enclave',
      description: 'Secure environment for data processing',
      region: 'us-east-1',
      walletAddress: walletAddress,
      providerId: providers[0].id,
      providerConfig: {
        dockerImage: 'analytics:latest',
        cpuCount: 4,
        memoryMiB: 2048
      }
    });

    console.log('✅ Enclave created:', enclave.id);
    console.log('📊 Status:', enclave.status);
    console.log('🌍 Region:', enclave.region);
    console.log('🏗️  Provider:', enclave.providerId);

    // Create a scheduled task
    const task = await client.createTask({
      name: 'Data Processing Task',
      description: 'Process data files every hour',
      enclaveId: enclave.id,
      schedule: '0 * * * *', // Every hour
      walletAddress: walletAddress
    });

    console.log('⚙️  Task created:', task.id);

    // Update enclave with GitHub integration
    const updatedEnclave = await client.updateEnclave({
      id: enclave.id,
      walletAddress: walletAddress,
      githubConnection: {
        isConnected: true,
        selectedRepo: 'myorg/data-analytics',
        selectedBranch: 'main'
      }
    });

    console.log('🔗 GitHub connected:', updatedEnclave.githubConnection?.selectedRepo);

  } catch (error) {
    console.error('❌ Setup failed:', error);
  }
}

setupEnclave();

GitHub OAuth Flow

import { TrezaClient } from '@treza/sdk';

const client = new TrezaClient();

async function handleGitHubAuth() {
  try {
    // Step 1: Get authorization URL
    const auth = await client.getGitHubAuthUrl();
    console.log('🔗 Authorize GitHub access at:', auth.authUrl);
    
    // Step 2: User visits URL and authorizes
    // Step 3: Handle the callback (you'll get the code)
    const code = 'code-from-callback'; // This comes from your OAuth callback
    
    // Step 4: Exchange code for token
    const tokenResponse = await client.exchangeGitHubCode({ code });
    console.log('✅ GitHub authenticated for user:', tokenResponse.user.login);
    
    // Step 5: Use token to access repositories
    const repos = await client.getGitHubRepositories(tokenResponse.access_token);
    console.log('📚 Available repositories:');
    repos.repositories.forEach(repo => {
      console.log(`  - ${repo.fullName} (${repo.language || 'No language'})`);
    });

  } catch (error) {
    console.error('❌ GitHub auth failed:', error);
  }
}

Repository and Branch Management

async function manageRepository() {
  const accessToken = 'gho_xxxxxxxxxxxxxxxxxxxx';
  
  try {
    // Get repositories
    const repos = await client.getGitHubRepositories(accessToken);
    const selectedRepo = repos.repositories[0];
    
    console.log('📊 Selected repository:', selectedRepo.fullName);
    console.log('🔒 Private:', selectedRepo.private);
    console.log('⭐ Language:', selectedRepo.language);
    
    // Get branches for selected repository
    const branches = await client.getRepositoryBranches({
      accessToken: accessToken,
      repository: selectedRepo.fullName
    });
    
    console.log('🌿 Available branches:');
    branches.branches.forEach(branch => {
      console.log(`  - ${branch.name} (${branch.commit.sha.substring(0, 7)})`);
    });
    
  } catch (error) {
    console.error('❌ Repository management failed:', error);
  }
}

Error Handling

import { TrezaSdkError } from '@treza/sdk';

async function handleErrors() {
  try {
    const enclaves = await client.getEnclaves('invalid-wallet');
  } catch (error) {
    if (error instanceof TrezaSdkError) {
      console.error('🚨 Treza SDK Error:', {
        message: error.message,
        code: error.code,
        statusCode: error.statusCode,
        details: error.details
      });
      
      // Handle specific error types
      if (error.statusCode === 400) {
        console.log('💡 Tip: Check your wallet address format');
      } else if (error.statusCode === 404) {
        console.log('💡 Tip: Enclave not found or access denied');
      }
    } else {
      console.error('❌ Unexpected error:', error);
    }
  }
}

TypeScript Support

The SDK is built with TypeScript and exports comprehensive type definitions:

import {
  // Core types
  TrezaConfig,
  Enclave,
  Provider,
  Task,
  ApiKey,
  GitHubConnection,
  
  // Request/Response types
  CreateEnclaveRequest,
  UpdateEnclaveRequest,
  CreateTaskRequest,
  UpdateTaskRequest,
  CreateApiKeyRequest,
  UpdateApiKeyRequest,
  EnclaveResponse,
  EnclavesResponse,
  ProviderResponse,
  ProvidersResponse,
  TaskResponse,
  TasksResponse,
  ApiKeyResponse,
  ApiKeysResponse,
  
  // 🆕 NEW: Lifecycle management types
  EnclaveLifecycleRequest,
  EnclaveLifecycleResponse,
  
  // 🆕 NEW: Logs types
  LogEntry,
  LogsResponse,
  
  // 🆕 NEW: Docker types
  DockerImage,
  DockerTag,
  DockerSearchResponse,
  DockerTagsResponse,
  
  // GitHub types
  GitHubUser,
  Repository,
  Branch,
  GitHubAuthResponse,
  GitHubTokenResponse,
  
  // Utility types
  ApiError,
  TrezaSdkError
} from '@treza/sdk';

Environment Variables

For development and testing, you can set these environment variables:

# Optional: Custom API endpoint
TREZA_BASE_URL=https://app.trezalabs.com

# For examples: Your wallet address
WALLET_ADDRESS=0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB

# For GitHub integration examples
GITHUB_ACCESS_TOKEN=gho_xxxxxxxxxxxxxxxxxxxx

Development

Building

npm run build

Development Mode

npm run dev

Testing

npm test

Linting

npm run lint
npm run lint:fix

Examples

Check out the comprehensive examples in the examples/ directory:

Basic Usage (examples/basic-usage.ts) - Complete examples of all SDK functionality
Provider Management - Discovering and using enclave providers
Enclave Management - Creating, updating, and managing enclaves with provider configuration
Task Management - Creating and scheduling tasks within enclaves
API Key Management - Generating and managing API keys with permissions
GitHub Integration - OAuth flow and repository management
Error Handling - Proper error handling patterns

Run the examples:

# Set your environment variables first
export WALLET_ADDRESS=0x4B0897b0513fdc7C541B6d9D7E929C4e5364D2dB
export GITHUB_ACCESS_TOKEN=gho_xxxxxxxxxxxxxxxxxxxx

# Run the examples
npx ts-node examples/basic-usage.ts

Contributing

We welcome contributions! Please see our contributing guidelines for more details.

License

MIT License - see LICENSE file for details.

Support

📖 Documentation: docs.trezalabs.com
🐛 Issues: GitHub Issues

About Treza

Treza provides secure enclave infrastructure for decentralized applications, enabling developers to build with confidence in secure, verifiable execution environments.

⭐ Star this repository if you find it helpful!