Algebrakit Webservice API SDK

Official Node.js/TypeScript SDK for the Algebrakit Webservice API. It provides methods for creating sessions, retrieving scores, locking/unlocking sessions, and fetching session information.

Installation

npm install @algebrakit/sdk

Requires Node.js 18 or newer.

Usage

Initialize the API Client

import { ApiClient } from '@algebrakit/sdk';

const apiClient = new ApiClient('https://api.algebrakit.com', 'your-api-key');

Create a Session

import { CreateSessionRequest } from '@algebrakit/sdk';

const request: CreateSessionRequest = {
  exercises: [
    { exerciseId: 'fa42e943-8213-41a6-8a91-8c22a929ffe9', version: 'latest' },
  ],
  apiVersion: 2,
};

apiClient.createSession(request).then(response => {
  console.log('Session created:', response);
}).catch(error => {
  console.error('Error creating session:', error);
});

Retrieve Session Scores

import { SessionScoreRequest } from '@algebrakit/sdk';

const request: SessionScoreRequest = {
  sessionId: '0a405901-8b89-4665-9ea0-6dbdff3602fc',
  lockSession: true,
};

apiClient.getSessionScore(request).then(response => {
  console.log('Session scores:', response);
}).catch(error => {
  console.error('Error retrieving scores:', error);
});

Lock or Unlock Sessions

import { SessionLockRequest } from '@algebrakit/sdk';

const request: SessionLockRequest = {
  action: 'LOCK',
  sessionIds: ['f2f62104-3b5a-4156-aeaf-291167e5f9e3'],
};

apiClient.lockSession(request).then(response => {
  console.log('Session locked:', response);
}).catch(error => {
  console.error('Error locking session:', error);
});

Retrieve Session Information

import { SessionInfoRequest } from '@algebrakit/sdk';

const request: SessionInfoRequest = {
  sessionId: '0a405901-8b89-4665-9ea0-6dbdff3602fc',
};

apiClient.getSessionInfo(request).then(response => {
  console.log('Session info:', response);
}).catch(error => {
  console.error('Error retrieving session info:', error);
});

Running the Demos

Each demo lives in its own folder under demo/ with its own configuration.

CLI Demo (demo/cli/)

Demonstrates SDK API calls with text output.

1. Set up your API key:

   npm run demo:setup
   # Then edit demo/cli/.env with your actual API key

2. Run the demo:

   npm run demo

Web Demo (demo/play-exercise/)

Renders a working Algebrakit exercise in the browser with learning event logging.

1. Set up your API key:

   npm run play-exercise:setup
   # Then edit demo/play-exercise/.env with your actual API key

2. Run the web demo:

   npm run play-exercise

3. Open http://localhost:3000 in your browser.

Error Handling

Use the handleApiError utility to standardize error messages:

import { handleApiError } from '@algebrakit/sdk';

apiClient.createSession(request).catch(error => {
  console.error(handleApiError(error));
});

License

Licensed under the MIT License.