Type Definitions

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

Core Types

BalloonUpdate

Main data structure for balloon telemetry updates.

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.

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
  motion?: {
    // Motion data
    ascentRate?: number
    groundSpeed?: number | null
    heading?: number | null
  }
  internal?: InternalTelemetry // Extended fields (internal_testing orgs only)
}

InternalTelemetry

Extended telemetry fields available only to organizations with internal_testing enabled. See Internal Telemetry Guide for details.

interface InternalTelemetry {
  ack?: boolean // Device acknowledged last command
  batteryVoltage?: number // Battery voltage (V)
  batterySoc?: number // Battery state of charge (%)
  batteryTemp?: number // Battery temperature (°C)
  tempBoard?: number // Board temperature (°C)
  airTemp?: number // External air temperature (°C)
  batteryHeating?: boolean // Battery heater active
  firmwareVersion?: string // Running firmware version
  hardwareVersion?: string // Hardware version
  flightStage?: string // PREFLIGHT | ASCENT | FLOAT | DESCENT | GROUNDED
  geofenceActive?: boolean // Geofence currently active
  geofenceBroken?: boolean // Geofence boundary violated
  gpsFixStatus?: number // GPS fix type
  gpsSatellites?: number // Satellites in view
  ascentRate?: number // Ascent rate (m/s)
  uptime?: number // System uptime (ms)
  massDropped?: number // Ballast dropped (g, ballaster only)
  dispenserIsDropping?: boolean // Dispenser active (ballaster only)
}

SDKConfig

Configuration object for initializing the SDK.

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.

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

Configuration Types

SDKConfig

Configuration options for SDK initialization.

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.

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.

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.

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.

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

Utility Types

DeviceType

Common device type identifiers.

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

FlightStage

Flight stage identifiers.

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

Constants

Default Values

Default configuration values.

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.

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

Flight Stages

Predefined flight stage constants.

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:

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:

// 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:

• JavaScript SDK Reference - JavaScript API documentation
• Python SDK Reference - Python API documentation

Data Types

UnassignedDevicesUpdate

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

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.

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

Specific Event Handlers

// 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

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

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)
  }
})