Urban Sky SDK

Appearance

Type Definitions ​

Complete type reference for the Urban Sky SDK interfaces and types.

Core Types ​

BalloonUpdate ​

Main data structure for balloon telemetry updates.

typescript
interface BalloonUpdate {
  balloonId: string    // Unique balloon identifier
  missionId: string    // Associated mission ID
  devices: Device[]    // Array of device telemetry data
}

Device ​

Individual device telemetry data within a balloon update.

typescript
interface Device {
  deviceId: string       // Unique device identifier
  deviceType: string     // Device type (PLD, APX, BLS, etc.)
  lat: number           // Latitude (decimal degrees)
  lng: number           // Longitude (decimal degrees)
  altitude?: number     // Altitude in meters
  timestamp: string     // ISO 8601 timestamp
}

SDKConfig ​

Configuration object for initializing the SDK.

typescript
interface SDKConfig {
  apiToken: string;        // Your Urban Sky API token
  baseUrl?: string;        // API base URL (defaults to production)
  debug?: boolean;         // Enable debug logging
}

ConnectionState ​

Represents the current connection state.

typescript
interface ConnectionState {
  state: "connected" | "connecting" | "disconnected" | "failed";
  reason?: string;  // Error reason if state is "failed"
}

Configuration Types ​

SDKConfig ​

Configuration options for SDK initialization.

typescript
interface SDKConfig {
  apiToken: string              // Required: Your Urban Sky API token
  baseUrl?: string             // Optional: API base URL
  reconnect?: boolean          // Optional: Enable auto-reconnection
  reconnectDelay?: number      // Optional: Reconnection delay (ms)
  maxReconnectAttempts?: number // Optional: Max reconnection attempts
  connectionTimeout?: number    // Optional: Connection timeout (ms)
  heartbeatInterval?: number    // Optional: Heartbeat interval (ms)
  debug?: boolean              // Optional: Enable debug logging
}

Event Types ​

SDKEventType ​

Available event types you can listen for.

typescript
type SDKEventType =
  | "balloon:update"      // Balloon telemetry updates (mission-assigned devices)
  | "unassigned:devices"  // Unassigned device updates (devices not assigned to missions)
  | "connected"           // Successfully connected
  | "disconnected"        // Disconnected from service
  | "connecting"          // Attempting to connect
  | "failed"              // Connection failed
  | "error";              // General error occurred

Event Handler Types ​

Type definitions for event handlers.

typescript
type BalloonUpdateHandler = (update: BalloonUpdate) => void
type ConnectionHandler = () => void
type ErrorHandler = (error: SDKError) => void

type EventHandler = 
  | BalloonUpdateHandler
  | ConnectionHandler
  | ErrorHandler

Error Types ​

SDKError ​

Error class for SDK-specific errors.

typescript
class SDKError extends Error {
  code: string      // Error code identifier
  details?: any     // Additional error details
  
  constructor(message: string, code?: string, details?: any)
}

Error Codes ​

Standard error codes used throughout the SDK.

typescript
type ErrorCode = 
  | 'INVALID_TOKEN'
  | 'AUTHENTICATION_FAILED'
  | 'CONNECTION_LOST'
  | 'NETWORK_ERROR'
  | 'TIMEOUT'
  | 'RATE_LIMITED'
  | 'UNKNOWN_ERROR'

Utility Types ​

DeviceType ​

Common device type identifiers.

typescript
type DeviceType = 
  | 'PLD'    // Payload
  | 'APX'    // Apex
  | 'BLS'    // Ballaster
  | 'TRK'    // Tracker
  | 'CUT'    // Cutter
  | string   // Custom device types

FlightStage ​

Flight stage identifiers.

typescript
type FlightStage = 
  | 'pre-flight'
  | 'ascent'
  | 'float'
  | 'descent'
  | 'landed'
  | 'terminated'
  | string   // Custom stages

Constants ​

Default Values ​

Default configuration values.

typescript
const DEFAULT_CONFIG: Required<Omit<SDKConfig, 'apiToken'>> = {
  baseUrl: 'https://api.ops.atmosys.com',
  reconnect: true,
  reconnectDelay: 5000,
  maxReconnectAttempts: 10,
  connectionTimeout: 30000,
  heartbeatInterval: 30000,
  debug: false
}

Common Device Types ​

Predefined device type constants.

typescript
const DEVICE_TYPES = {
  PAYLOAD: 'PLD',
  APEX: 'APX',
  BALLASTER: 'BLS',
  TRACKER: 'TRK',
  CUTTER: 'CUT'
} as const

Flight Stages ​

Predefined flight stage constants.

typescript
const FLIGHT_STAGES = {
  PRE_FLIGHT: 'pre-flight',
  ASCENT: 'ascent',
  FLOAT: 'float',
  DESCENT: 'descent',
  LANDED: 'landed',
  TERMINATED: 'terminated'
} as const

Python Type Equivalents ​

For Python SDK users, here are the equivalent types:

python
from typing import Optional, List, Dict, Any
from dataclasses import dataclass
from enum import Enum

@dataclass
class BalloonUpdate:
    balloon_id: str
    mission_id: str
    devices: List['Device']

@dataclass
class Device:
    device_id: str
    device_type: str
    lat: float
    lng: float
    altitude: Optional[float]
    timestamp: str

class SDKEventType(Enum):
    BALLOON_UPDATE = "balloon:update"
    CONNECTED = "connected"
    DISCONNECTED = "disconnected"
    CONNECTING = "connecting"
    FAILED = "failed"
    ERROR = "error"

class SDKError(Exception):
    def __init__(self, message: str, code: Optional[str] = None, details: Any = None):
        super().__init__(message)
        self.code = code
        self.details = details

Version Compatibility ​

Type Evolution ​

Types may evolve between SDK versions. Always check compatibility:

typescript
// Check SDK version compatibility
const SDK_VERSION = '1.0.0'
const MIN_SUPPORTED_VERSION = '0.9.0'

function isVersionSupported(version: string): boolean {
  // Version checking logic
  return true
}

Migration Guide ​

When upgrading SDK versions:

  1. Check breaking changes in the changelog
  2. Update type imports if interfaces have changed
  3. Test with new types before deploying

Related Documentation:

Data Types ​

UnassignedDevicesUpdate ​

Real-time telemetry data for devices not assigned to any mission.

typescript
interface UnassignedDevicesUpdate {
  devices: Array<{
    deviceId: string;     // Device MAC address
    deviceType: string;   // Device type (e.g., "payload", "apex", "ballaster")
    lat: number;          // Latitude in decimal degrees
    lng: number;          // Longitude in decimal degrees
    altitude?: number;    // Altitude in meters (optional)
    timestamp: string;    // ISO 8601 timestamp
  }>;
}

Event Handlers ​

SDKEventHandler ​

Generic event handler function type.

typescript
type SDKEventHandler<T = unknown> = (data: T) => void;

Specific Event Handlers ​

typescript
// Balloon update handler
sdk.on('balloon:update', (update: BalloonUpdate) => {
  // Handle balloon telemetry
});

// Unassigned devices handler
sdk.on('unassigned:devices', (update: UnassignedDevicesUpdate) => {
  // Handle unassigned device telemetry
});

// Connection state handlers
sdk.on('connected', (state: ConnectionState) => {
  // Handle successful connection
});

sdk.on('disconnected', (state: ConnectionState) => {
  // Handle disconnection
});

sdk.on('connecting', (state: ConnectionState) => {
  // Handle connection attempt
});

sdk.on('failed', (state: ConnectionState) => {
  // Handle connection failure
});

// Error handler
sdk.on('error', (error: { message: string; error?: string }) => {
  // Handle SDK errors
});

Data Flow ​

Mission-Assigned Devices (Balloon Updates) ​

  1. Device sends telemetry data
  2. Data is assigned to a mission based on device assignment
  3. Data is batched by mission/balloon
  4. balloon:update events are emitted with all devices in the mission

Unassigned Devices ​

  1. Device sends telemetry data
  2. Device has no mission assignment
  3. Data is cached by organization
  4. unassigned:devices events are emitted with all unassigned devices in the organization

Usage Patterns ​

Handle Both Event Types ​

typescript
const sdk = await UrbanSkySDK.init({ apiToken: 'your-token' });

// Handle mission-assigned devices
sdk.on('balloon:update', (update) => {
  console.log(`Mission ${update.missionId} has ${update.devices.length} devices`);
  // Process mission telemetry
});

// Handle unassigned devices
sdk.on('unassigned:devices', (update) => {
  console.log(`${update.devices.length} unassigned devices detected`);
  // Process or alert on unassigned devices
});

Filter by Device Type ​

typescript
sdk.on('balloon:update', (update) => {
  const payloadDevices = update.devices.filter(d => d.deviceType === 'payload');
  const apexDevices = update.devices.filter(d => d.deviceType === 'apex');
  
  // Handle different device types
});

sdk.on('unassigned:devices', (update) => {
  const unknownDevices = update.devices.filter(d => d.deviceType === 'unknown');
  
  if (unknownDevices.length > 0) {
    console.warn('Unknown device types detected:', unknownDevices);
  }
});

Copyright © 2024 Urban Sky