Skip to main content

TypeScript SDK

Installation​

npm install @terragnos/sdk-admin

Or with yarn:

yarn add @terragnos/sdk-admin

Requirements​

  • Node.js 18+ (with native fetch support)
  • TypeScript 4.5+ (optional, for type definitions)

Basic Usage​

Creating a Client​

import { TerragnosAdminClient } from '@terragnos/sdk-admin';

const client = new TerragnosAdminClient({
  baseUrl: 'https://core.example.com/v1',
  token: process.env.TERRAGNOS_TOKEN,
});

Listing Objects​

const { items, pagination } = await client.listObjects({
  typeId: 'traffic-signal',
  limit: 25,
});

console.log(`Found ${items.length} objects`);
items.forEach(obj => {
  console.log(`${obj.publicId}: ${obj.typeId}`);
});

Creating Objects​

const object = await client.createObject({
  typeId: 'traffic-signal',
  attributes: {
    signalType: 'standard',
    intersectionId: 'INT-001',
  },
  geometry: {
    type: 'Point',
    coordinates: [19.04, 47.49],
  },
});

console.log(`Created object: ${object.id}`);

Updating Objects​

const updated = await client.updateObject({
  id: 'object-id',
  version: 1, // Optimistic locking
  attributes: {
    signalType: 'pedestrian',
  },
});

Workflow Transitions​

await client.transitionWorkflow({
  objectId: 'object-id',
  targetState: 'approved',
  metadata: {
    reason: 'Meets all requirements',
  },
});

Query Service​

const results = await client.runQuery({
  filters: [
    {
      field: 'typeId',
      operator: 'equals',
      value: 'traffic-signal',
    },
    {
      field: 'attributes.status',
      operator: 'equals',
      value: 'active',
    },
  ],
  sorts: [
    {
      field: 'createdAt',
      order: 'desc',
    },
  ],
  limit: 50,
});

Error Handling​

try {
  const object = await client.getObject({ id: 'object-id' });
} catch (error) {
  if (error instanceof TerragnosError) {
    switch (error.statusCode) {
      case 401:
        console.error('Authentication failed');
        break;
      case 403:
        console.error('Permission denied');
        break;
      case 404:
        console.error('Object not found');
        break;
      case 409:
        console.error('Optimistic locking conflict');
        break;
      default:
        console.error('API error:', error.message);
    }
  }
}

Custom HTTP Configuration​

const client = new TerragnosAdminClient({
  baseUrl: 'https://core.example.com/v1',
  token: process.env.TERRAGNOS_TOKEN,
  fetchFn: async (url, options) => {
    // Custom fetch implementation with retry logic, etc.
    return fetch(url, options);
  },
});

Type Safety​

The SDK provides full TypeScript types:

import type { Object, ObjectType, Workflow } from '@terragnos/sdk-admin';

const object: Object = await client.getObject({ id: 'object-id' });
const type: ObjectType = await client.getObjectType({ id: 'type-id' });

Best Practices​

  1. Reuse client instances – Create one client and reuse it
  2. Handle errors – Always wrap API calls in try-catch
  3. Use types – Leverage TypeScript types for better IDE support
  4. Environment variables – Store tokens in environment variables
  5. Retry logic – Implement retry for transient failures
  6. Rate limiting – Be mindful of API rate limits