Skip to main content

TypeScript SDK

The SixDegree TypeScript/JavaScript SDK provides a type-safe client for frontend and Node.js applications.

Installation​

npm install @sixdegree-ai/typescript-sixdegree

Requirements:

  • Node.js 18 or later
  • TypeScript 5.0+ (recommended)

Quick Start​

import { SixDegreeClient } from '@sixdegree-ai/typescript-sixdegree';

const client = new SixDegreeClient({
  baseURL: 'https://api.sixdegree.ai',
  token: 'your-api-token',
});

// List environments
const environments = await client.environments.list();
console.log(environments);

Authentication​

API Token​

const client = new SixDegreeClient({
  baseURL: 'https://api.sixdegree.ai',
  token: process.env.SIXDEGREE_API_TOKEN,
});

Updating the Token​

For applications that refresh tokens (e.g., OAuth flows):

client.setToken('your-new-token');

Environment Variable​

export SIXDEGREE_API_TOKEN="sd_your_api_token"
const client = new SixDegreeClient({
  baseURL: 'https://api.sixdegree.ai',
  token: process.env.SIXDEGREE_API_TOKEN,
});

Environments​

Environments provide isolated namespaces for your entities and relationships.

List Environments​

const { environments } = await client.environments.list();

for (const env of environments) {
  console.log(`${env.name} (${env.id})`);
}

Create Environment​

const environment = await client.environments.create({
  name: 'Production',
  description: 'Production environment',
});

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

Get Environment​

const environment = await client.environments.get('env-id');
console.log(environment.name, environment.createdAt);

Delete Environment​

await client.environments.delete('env-id');

Entities​

List Entities​

const { entities, total, page, totalPages } = await client.entities.list('env-id', {
  type: 'Repository',
  limit: 100,
  offset: 0,
});

console.log(`Found ${total} repositories (page ${page}/${totalPages})`);

for (const entity of entities) {
  console.log(`${entity.name} (${entity.kind})`);
}

Get Entity​

const entity = await client.entities.get('env-id', 'entity-id');

console.log(entity.name);
console.log(entity.kind);
console.log(entity.properties);

Create Entity​

const entity = await client.entities.create('env-id', {
  group: 'core',
  version: 'v1',
  namespace: 'default',
  kind: 'Service',
  name: 'auth-service',
  properties: {
    url: 'https://auth.example.com',
    port: 8080,
  },
});

Update Entity​

await client.entities.update('env-id', 'entity-id', {
  properties: {
    status: 'active',
    replicas: 3,
  },
});

Delete Entity​

await client.entities.delete('env-id', 'entity-id');

Get Relationships​

const { relations } = await client.entities.getRelationships('env-id', 'entity-id');

for (const rel of relations) {
  console.log(`${rel.from} -[${rel.type}]-> ${rel.to}`);
}

Create Relationship​

await client.entities.createRelationship('env-id', {
  from: 'repo-uid',
  to: 'service-uid',
  type: 'DEPLOYS_TO',
  properties: {
    environment: 'production',
  },
});

Pagination​

Handle paginated responses:

async function getAllEntities(envId: string, kind: string) {
  const allEntities = [];
  const pageSize = 100;
  let offset = 0;

  while (true) {
    const { entities, total } = await client.entities.list(envId, {
      type: kind,
      limit: pageSize,
      offset,
    });

    allEntities.push(...entities);

    if (offset + pageSize >= total) break;
    offset += pageSize;
  }

  return allEntities;
}

const allRepos = await getAllEntities('env-id', 'Repository');

Chat​

Create Session​

const session = await client.chat.createSession('env-id', {
  modelId: 'claude-sonnet-4-5-20250514',
});

console.log(`Session: ${session.id}`);

Send Message​

const response = await client.chat.sendMessage('env-id', session.id, {
  content: 'What repositories do I have?',
});

console.log(response.content);

Stream Chat​

For real-time streaming responses:

const stream = await client.chat.stream(
  'env-id',
  session.id,
  'Show me all Go repositories'
);

for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}

List Chat Sessions​

const { chats } = await client.chat.list('env-id', { limit: 20 });

for (const chat of chats) {
  console.log(`${chat.id}: ${chat.title}`);
}

Get Chat History​

const { messages } = await client.chat.get('env-id', 'chat-id');

for (const msg of messages) {
  console.log(`[${msg.role}] ${msg.content}`);
}

MCP Endpoints​

List Endpoints​

const { endpoints } = await client.mcp.list('env-id');

for (const endpoint of endpoints) {
  console.log(`${endpoint.name} (${endpoint.transport})`);
}

Create Endpoint​

const endpoint = await client.mcp.create('env-id', {
  name: 'PostgreSQL Tools',
  url: 'https://mcp-postgres.example.com',
  transport: 'http',
  authConfig: {
    type: 'bearer',
    token: 'xxx',
  },
});

List Available Tools​

const { tools } = await client.mcp.listTools('env-id', 'endpoint-id');

for (const tool of tools) {
  console.log(`${tool.name}: ${tool.description}`);
}

Discovery​

List Configured Molecules​

const { molecules } = await client.discovery.listMolecules('env-id');

for (const mol of molecules) {
  console.log(`${mol.name} (${mol.status})`);
}

Run Discovery​

const run = await client.discovery.run('env-id', {
  moleculeId: 'github',
});

console.log(`Started: ${run.id}`);

Check Status​

const status = await client.discovery.getStatus('env-id', run.id);

console.log(status.state); // 'pending' | 'running' | 'completed' | 'failed'
console.log(`Entities discovered: ${status.entitiesCreated}`);

Error Handling​

Catching API Errors​

import { SixDegreeError } from '@sixdegree-ai/typescript-sixdegree';

try {
  const entity = await client.entities.get('env-id', 'entity-id');
} catch (error) {
  if (error instanceof SixDegreeError) {
    console.error(`API Error (${error.statusCode}): ${error.message}`);

    switch (error.statusCode) {
      case 401:
        console.error('Authentication failed — check your API token');
        break;
      case 404:
        console.error('Entity not found');
        break;
      case 429:
        console.error('Rate limited — retry after delay');
        break;
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Retry Pattern​

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  delay = 1000
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (
        error instanceof SixDegreeError &&
        error.statusCode === 429 &&
        attempt < maxRetries
      ) {
        await new Promise(resolve => setTimeout(resolve, delay * (attempt + 1)));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

const entities = await withRetry(() =>
  client.entities.list('env-id', { type: 'Repository' })
);

React Integration​

Basic Hook​

import { useSixDegree } from '@sixdegree-ai/typescript-sixdegree/react';

function EnvironmentList() {
  const { data: environments, loading, error } = useSixDegree(
    client => client.environments.list()
  );

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <ul>
      {environments.map(env => (
        <li key={env.id}>{env.name}</li>
      ))}
    </ul>
  );
}

With Parameters​

function EntityList({ envId, kind }: { envId: string; kind: string }) {
  const { data, loading, error, refetch } = useSixDegree(
    client => client.entities.list(envId, { type: kind, limit: 50 }),
    [envId, kind] // re-fetch when these change
  );

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <p>Found {data.total} entities</p>
      <button onClick={refetch}>Refresh</button>
      <ul>
        {data.entities.map(entity => (
          <li key={entity.uid}>{entity.name} ({entity.kind})</li>
        ))}
      </ul>
    </div>
  );
}

Complete Example​

import { SixDegreeClient, SixDegreeError } from '@sixdegree-ai/typescript-sixdegree';

async function main() {
  const client = new SixDegreeClient({
    baseURL: 'https://api.sixdegree.ai',
    token: process.env.SIXDEGREE_API_TOKEN!,
  });

  const envId = 'env_abc123';

  // 1. Create entities
  console.log('Creating entities...');
  const repo = await client.entities.create(envId, {
    group: 'core',
    version: 'v1',
    namespace: 'default',
    kind: 'Repository',
    name: 'api-service',
    properties: { language: 'Go', url: 'https://github.com/org/api-service' },
  });

  const service = await client.entities.create(envId, {
    group: 'core',
    version: 'v1',
    namespace: 'default',
    kind: 'Service',
    name: 'api-production',
    properties: { url: 'https://api.prod.example.com' },
  });

  // 2. Create relationship
  console.log('Linking entities...');
  await client.entities.createRelationship(envId, {
    from: repo.uid,
    to: service.uid,
    type: 'DEPLOYS_TO',
  });

  // 3. Query
  console.log('Querying...');
  const { entities } = await client.entities.list(envId, {
    type: 'Repository',
  });

  for (const entity of entities) {
    console.log(`${entity.name} (${entity.uid})`);

    const { relations } = await client.entities.getRelationships(envId, entity.uid);
    for (const rel of relations) {
      console.log(`  -> ${rel.to} [${rel.type}]`);
    }
  }

  // 4. Chat with AI
  console.log('Asking AI...');
  const session = await client.chat.createSession(envId);
  const response = await client.chat.sendMessage(envId, session.id, {
    content: 'What services are deployed from the api-service repository?',
  });

  console.log(`AI: ${response.content}`);
}

main().catch(console.error);

Next Steps​