JavaScript SDK API Reference

Complete API reference for the Urban Sky JavaScript SDK for Node.js applications.

Installation

Load the SDK using our CDN loader:

// Load the SDK dynamically
const response = await fetch('https://sdk.atmosys.com/runtime/js/current/loader.js')
const loaderCode = await response.text()
eval(loaderCode) // UrbanSkySDK is now available globally

UrbanSkySDK Class

Static Initialization Method

await UrbanSkySDK.init(config)

Initializes and connects to the Urban Sky SDK with the provided configuration.

Parameters:

Parameter	Type	Description
config	Object	SDK configuration object

Returns: Promise that resolves to the initialized and connected SDK instance

Example:

// UrbanSkySDK is available globally after loading the loader
const sdk = await UrbanSkySDK.init({
  apiToken: 'your-api-token',
  // Most other options have sensible defaults and don't need to be set
})

Methods

connect()

Note

The connect() method is automatically called by UrbanSkySDK.init(). You typically don't need to call this manually.

async connect()

Establishes connection to the Urban Sky telemetry feed.

Returns: Promise that resolves when connected

Throws: SDKError if connection fails

Example:

// Usually not needed - init() handles connection automatically
try {
  await sdk.connect()
  console.log('Connected successfully')
} catch (error) {
  console.error('Connection failed:', error)
}

disconnect()

disconnect()

Disconnects from the telemetry feed and cleans up resources.

Example:

sdk.disconnect()

on(event, handler)

on(event, handler)

Registers an event handler for SDK events.

Parameters:

Parameter	Type	Description
event	string	Event type to listen for
handler	Function	Function to call when event occurs

Events:

• 'balloon:update' - Balloon telemetry update received
• 'unassigned:devices' - Unassigned device telemetry received
• 'connected' - Successfully connected to telemetry feed
• 'disconnected' - Disconnected from telemetry feed
• 'connecting' - Attempting to connect
• 'failed' - Connection failed
• 'error' - Error occurred

Example:

sdk.on('balloon:update', update => {
  console.log('Balloon update:', update)
})

sdk.on('error', error => {
  console.error('SDK error:', error)
})

off(event, handler)

off(event, handler)

Removes an event handler. If no handler is provided, removes all handlers for the event.

Parameters:

Parameter	Type	Description
event	string	Event type
handler	Function	Specific handler to remove (optional)

Example:

const handler = update => console.log(update)

sdk.on('balloon:update', handler)
sdk.off('balloon:update', handler) // Remove specific handler
sdk.off('balloon:update') // Remove all handlers for this event

Configuration

SDKConfig

{
  apiToken: string,        // Required: Your Urban Sky API token
  baseUrl?: string        // Optional: Custom API URL (rarely needed)
}

Note: Most configuration options have sensible defaults. You typically only need to provide your API token.

Property	Type	Default	Description
apiToken	string	required	Your Urban Sky API token
baseUrl	string	'https://api.ops.atmosys.com'	API base URL (rarely needs to be changed)

Data Types

BalloonUpdate

{
  balloonId: string,
  missionId: string,
  devices: Device[]
}

Device

{
  deviceId: string,
  deviceType: string,    // e.g., "PLD" (Payload), "APX" (Apex), "BLS" (Ballaster)
  lat: number,           // Latitude in decimal degrees
  lng: number,           // Longitude in decimal degrees
  altitude?: number,     // Altitude in meters (when available)
  timestamp: string      // ISO 8601 timestamp
}

Error Types

SDKError

{
  code: string,
  message: string,
  details?: any
}

Error Codes:

Code	Description
'AUTH_INVALID_TOKEN'	API token is invalid or expired
'AUTH_INSUFFICIENT_PERMISSIONS'	Token lacks SDK permissions
'CONNECTION_FAILED'	Connection to server failed
'NETWORK_ERROR'	Network connectivity issue
'SERVICE_UNAVAILABLE'	Urban Sky service temporarily unavailable

Complete Example

const fetch = require('node-fetch') // Ensure node-fetch is installed

class BalloonTracker {
  constructor(apiToken) {
    this.apiToken = apiToken
    this.sdk = null
    this.balloons = new Map()
  }

  async initialize() {
    // Load the SDK
    const response = await fetch('https://sdk.atmosys.com/runtime/js/current/loader.js')
    const loaderCode = await response.text()
    eval(loaderCode)

    // Initialize and connect SDK
    this.sdk = await UrbanSkySDK.init({
      apiToken: this.apiToken,
    })

    this.setupEventHandlers()
  }

  setupEventHandlers() {
    this.sdk.on('balloon:update', this.handleBalloonUpdate.bind(this))
    this.sdk.on('connected', this.handleConnected.bind(this))
    this.sdk.on('disconnected', this.handleDisconnected.bind(this))
    this.sdk.on('error', this.handleError.bind(this))
  }

  handleBalloonUpdate(update) {
    console.log(`Balloon ${update.balloonId} update:`)

    update.devices.forEach(device => {
      console.log(`  Device ${device.deviceId} (${device.deviceType}):`)
      console.log(`    Location: ${device.lat}, ${device.lng}`)

      if (device.altitude) {
        console.log(`    Altitude: ${device.altitude}m`)
      }

      console.log(`    Time: ${new Date(device.timestamp).toLocaleString()}`)
    })

    this.balloons.set(update.balloonId, update)
  }

  handleConnected() {
    console.log('✅ Connected to Urban Sky telemetry feed')
  }

  handleDisconnected() {
    console.log('🔌 Disconnected from telemetry feed')
  }

  handleError(error) {
    console.error('🚨 SDK Error:', error.message)

    switch (error.code) {
      case 'AUTH_INVALID_TOKEN':
        console.error('Please check your API token')
        break
      case 'CONNECTION_FAILED':
        console.error('Network connectivity issue')
        break
      default:
        console.error('Unexpected error:', error.details)
    }
  }

  async start() {
    try {
      await this.initialize()
      // SDK is already connected via init()
      console.log('Tracker started successfully')
    } catch (error) {
      console.error('Failed to start tracker:', error)
      throw error
    }
  }

  stop() {
    if (this.sdk) {
      this.sdk.disconnect()
    }
  }

  getBalloon(balloonId) {
    return this.balloons.get(balloonId)
  }

  getAllBalloons() {
    return Array.from(this.balloons.values())
  }
}

// Usage
const tracker = new BalloonTracker('your-api-token')

tracker
  .start()
  .then(() => {
    console.log('Balloon tracker started')
  })
  .catch(error => {
    console.error('Failed to start tracker:', error)
  })

// Graceful shutdown
process.on('SIGINT', () => {
  console.log('Shutting down...')
  tracker.stop()
  process.exit(0)
})

Testing Your Implementation

You can test your SDK integration using our test endpoint:

// Send a test balloon update to verify your implementation
const testResponse = await fetch('https://api.atmosys.com/sdk/test/balloon', {
  method: 'POST',
  headers: {
    'x-api-token': 'your-api-token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({}),
})

if (testResponse.ok) {
  console.log('Test message sent - you should receive it via your SDK listener')
}

Next Steps

• Imagery SDK Guide - Access mission imagery and photos
• Python SDK Reference - Python SDK documentation
• Basic Usage Examples - Practical usage examples
• Error Handling Guide - Comprehensive error handling