Install the SDK

This page shows how to install and configure the SDK. What it covers is in the SDK overview.

Before you start

Node.js 18.18.2 or later (node --version).
A personal access token: acc pat create --name my-app. Copy it; it is shown once. See Create and use access tokens.
A project id: acc projects list.

1. Install

npm install @alternatefutures/sdk

2. Configure

Put the token and the project id in .env, and add .env to .gitignore:

# .env
AF_TOKEN=...          # your personal access token
AF_PROJECT_ID=...     # from acc projects list

No endpoint configuration is needed. The published package (0.2.4) targets https://api.alternatefutures.ai/graphql, the API that runs today, for both the token exchange and every query.

3. Construct the SDK

Import from the package root, on Node as well as in the browser. The token service takes the token and the project.

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

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

The package also lists a @alternatefutures/sdk/node entry point. In 0.2.4 it does not load under Node (see Troubleshooting), so use the root import.

To talk to another API host, for example a staging deployment, pass graphqlServiceApiUrl to both constructors:

const graphqlServiceApiUrl = 'https://api.alternatefutures.ai/graphql';

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

4. Verify

const projects = await sdk.projects().list();
console.log(projects.map((p) => p.name));

A list of your project names means the token, the project, and the endpoint are all right.

Troubleshooting

ERR_PACKAGE_PATH_NOT_EXPORTED naming files-from-path when importing @alternatefutures/sdk/node. That entry point's CommonJS bundle requires an ESM-only dependency and fails on every Node version. Import from @alternatefutures/sdk instead.
UnknownError: Unexpected error. Repeat the action or contact support. The SDK reports every API error this way, including a wrong, revoked, or out-of-project token. Check the token with acc pat list and the project with acc projects list. The API's own message is not passed through; Handle errors shows how to get it with curl.
SdkRequiredNodeRuntimeError. A legacy Node-only client was called. Those clients are retired; see the overview.