javascript-sdk

Sunra Clients - JavaScript/TypeScript SDK Developer Role Document

Overview

This document defines the role and responsibilities of a JavaScript/TypeScript SDK Developer for the Sunra Clients project. The JavaScript SDK provides a comprehensive TypeScript-first client library for interacting with Sunra.ai services, supporting both Node.js and browser environments.

Project Structure

The JavaScript SDK is organized as follows:

• src/: Main source directory
  • client.ts: Main client implementation
  • config.ts: Configuration management
  • queue.ts: Queue operations
  • request.ts: HTTP request handling
  • storage.ts: File storage operations
  • types.ts: TypeScript type definitions
  • utils.ts: Utility functions
  • index.ts: Public API exports

Development Guidelines

1. Code Style and Standards

TypeScript Style Guide

• Use strict TypeScript configuration
• Use 2 spaces for indentation (as per user preference)
• Maximum line length: 120 characters
• Use camelCase for functions and variables: submitRequest, getStatus
• Use PascalCase for classes and interfaces: SunraClient, QueueClient
• Use UPPER_SNAKE_CASE for constants: DEFAULT_TIMEOUT, MAX_RETRIES

Type Safety

• Prefer explicit types over any
• Use union types and literal types for better type safety
• Implement generic types for reusable components
• Use type guards for runtime type checking

Import/Export Patterns

// Use ES6 imports
import { SunraClient } from './client'
import type { QueueStatus, SubscribeOptions } from './types'

// Prefer named exports
export { SunraClient }
export type { QueueStatus, SubscribeOptions }

// Use barrel exports in index.ts
export * from './client'
export * from './types'

2. Architecture Patterns

Client Architecture

export interface SunraClientConfig {
  credentials?: string
  proxyUrl?: string
  apiEndpoint?: string
  queueDomain?: string
  timeout?: number
}

export class SunraClient {
  private readonly config: Required<SunraClientConfig>
  private readonly httpClient: HttpClient
  public readonly queue: QueueClient
  public readonly storage: StorageClient

  constructor(config: SunraClientConfig = {}) {
    this.config = {
      credentials: config.credentials ?? process.env.SUNRA_KEY ?? '',
      proxyUrl: config.proxyUrl ?? '',
      apiEndpoint: config.apiEndpoint ?? process.env.SUNRA_API_ENDPOINT ?? '',
      queueDomain: config.queueDomain ?? process.env.SUNRA_QUEUE_DOMAIN ?? '',
      timeout: config.timeout ?? 300000,
    }

    this.httpClient = new HttpClient(this.config)
    this.queue = new QueueClient(this.httpClient)
    this.storage = new StorageClient(this.httpClient)
  }
}