SDK quick start

This page shows the first working calls with the SDK. It assumes you finished Install the SDK: AF_TOKEN and AF_PROJECT_ID are set.

Set up

import 'dotenv/config';
import {
  AlternateFuturesSdk,
  PersonalAccessTokenService,
  type Project,
} from '@alternatefutures/sdk';

const sdk = new AlternateFuturesSdk({
  accessTokenService: new PersonalAccessTokenService({
    personalAccessToken: process.env.AF_TOKEN!,
    projectId: process.env.AF_PROJECT_ID!,
  }),
});

List projects

const projects: Project[] = await sdk.projects().list();
for (const project of projects) {
  console.log(project.id, project.name);
}

Create a project

const project = await sdk.projects().create({ name: 'my-app-staging' });
console.log('created', project.id);

Use the new id as AF_PROJECT_ID for a token service scoped to that project.

List your access tokens

const tokens = await sdk.user().listPersonalAccessTokens();
for (const token of tokens) {
  console.log(token.name, token.maskedToken, token.createdAt);
}

Tokens are created and revoked with the CLI: acc pat create --name <name>, acc pat delete <tokenId>.

The SDK reports every failed call, including a wrong, revoked, or out-of-project token, as an UnknownError whose message is always "Unexpected error. Repeat the action or contact support." and whose data is empty. The API's own message is not passed through. Catch it by name, then check the inputs with the CLI:

try {
  await sdk.projects().list();
} catch (error) {
  if (error instanceof Error && error.name === 'UnknownError') {
    console.error('The API rejected the call. Check acc pat list and acc projects list.');
  } else {
    throw error;
  }
}

To see the API's actual message, send the same query directly:

curl -s https://api.alternatefutures.ai/graphql \
  -H "Authorization: Bearer $AF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ projects { data { id name } } }"}'

A bad token answers Not authenticated; a good one returns your projects.

Deploy something

Deploying services, reading logs, and choosing templates or regions are not in the SDK. From the same script, shell out to the CLI; every command runs without prompts once AF_TOKEN and AF_PROJECT_ID are set:

import { execFileSync } from 'node:child_process';

const out = execFileSync('acc', ['services', 'list'], { encoding: 'utf8' });
console.log(out);

Or call the GraphQL API directly at https://api.alternatefutures.ai/graphql with the token as a bearer token. The command reference lists what the CLI can do; Docs for AI agents covers the non-interactive contract.

Set up

List projects

Create a project

List your access tokens

Handle errors

Deploy something

Next steps

On this page