Skip to main content

​
JavaScript SDK

The official JavaScript/TypeScript SDK for PolarGrid.

​
Installation

npm install @polargrid/polargrid-sdk

​
Quick Start

import { PolarGrid } from '@polargrid/polargrid-sdk';

// Auto-select best region by latency (recommended)
const client = await PolarGrid.create({
  apiKey: 'pg_your_api_key',
});

console.log(`Connected to: ${client.getRegionName()}`); // e.g., "Vancouver"

// Chat completion
const response = await client.chatCompletion({
  model: 'llama-3.1-8b',
  messages: [
    { role: 'user', content: 'Hello!' }
  ]
});

console.log(response.choices[0].message.content);

​
Configuration

// Sync constructor (uses default region)
const client = new PolarGrid({
  // API key (or set POLARGRID_API_KEY env var)
  apiKey: 'pg_your_api_key',

  // Region: 'toronto', 'vancouver', 'montreal' (or yto-01, yvr-02, yul-01)
  region: 'toronto',

  // Request timeout in ms (default: 30000)
  timeout: 30000,

  // Max retry attempts (default: 3)
  maxRetries: 3,

  // Enable debug logging
  debug: true,

  // Use mock data for development
  useMockData: false,
});

// Async factory with auto-routing (recommended)
const client = await PolarGrid.create({
  apiKey: 'pg_your_api_key',
  debug: true,
});

​
Auto-Routing

The PolarGrid.create() factory tests latency to all regions and picks the fastest: 
const client = await PolarGrid.create({
  apiKey: 'pg_your_api_key',
  debug: true, // See latency test results
});

// [PolarGrid] Auto-routing: latency results: yto-01=32ms, yvr-02=45ms, yul-01=82ms
// [PolarGrid] Auto-routing: selected Toronto (yto-01) with 32ms latency

console.log(client.getRegionId());   // 'yto-01'
console.log(client.getRegionName()); // 'Toronto'

​
Streaming

for await (const chunk of client.chatCompletionStream({
  model: 'llama-3.1-8b',
  messages: [{ role: 'user', content: 'Tell me a story' }],
})) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}

​
Mock Mode

Perfect for frontend development without a backend: 
const client = new PolarGrid({
  useMockData: true,  // No API calls, instant realistic responses
  debug: true,
});

// All methods work with realistic mock data
const response = await client.chatCompletion({
  model: 'llama-3.1-8b',
  messages: [{ role: 'user', content: 'Hello!' }]
});

​
Environment Variables

POLARGRID_API_KEY=pg_your_api_key
POLARGRID_BASE_URL=https://api.yto-01.edge.polargrid.ai  # Optional override

​
Next Steps

Full Reference

Complete API reference

Voice Guide

Text-to-speech and speech-to-text