@algebrakit/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Algebrakit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# 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
+
+```bash
+npm install @algebrakit/sdk
+```
+
+Requires Node.js 18 or newer.
+
+## Usage
+
+### Initialize the API Client
+
+```typescript
+import { ApiClient } from '@algebrakit/sdk';
+
+const apiClient = new ApiClient('https://api.algebrakit.com', 'your-api-key');
+```
+
+### Create a Session
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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:
+   ```bash
+   npm run demo:setup
+   # Then edit demo/cli/.env with your actual API key
+   ```
+
+2. Run the demo:
+   ```bash
+   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:
+   ```bash
+   npm run play-exercise:setup
+   # Then edit demo/play-exercise/.env with your actual API key
+   ```
+
+2. Run the web demo:
+   ```bash
+   npm run play-exercise
+   ```
+
+3. Open `http://localhost:3000` in your browser.
+
+## Error Handling
+
+Use the `handleApiError` utility to standardize error messages:
+
+```typescript
+import { handleApiError } from '@algebrakit/sdk';
+
+apiClient.createSession(request).catch(error => {
+  console.error(handleApiError(error));
+});
+```
+
+## License
+
+Licensed under the [MIT License](LICENSE).

package/dist/ApiClient.d.ts

@@ -0,0 +1,59 @@
+import { CreateSessionRequest, CreateSessionResponse, SessionScoreRequest, SessionScoreResponse, SessionLockRequest, SessionLockResponse, SessionInfoRequest, SessionInfoResponse, SessionRetrieveRequest, ExerciseValidateRequest, ExerciseInfoRequest } from './types/ApiTypes';
+import { SessionRetrieveResponse, ExerciseValidateResponse, ExerciseInfoResponse } from './types/ApiTypes';
+/**
+ * ApiClient is a wrapper around Axios to interact with the Algebrakit Webservice API.
+ */
+export declare class ApiClient {
+    private baseUrl;
+    private apiKey;
+    private axiosInstance;
+    /**
+     * Initialize the API client with a base URL and API key.
+     * @param baseUrl The base URL of the Algebrakit Webservice API.
+     * @param apiKey The API key for authentication.
+     */
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * Create new exercise sessions.
+     * @param request The request payload for creating sessions.
+     * @returns The response containing session creation results.
+     */
+    createSession(request: CreateSessionRequest): Promise<CreateSessionResponse>;
+    /**
+     * Retrieve results from exercise sessions.
+     * @param request The request payload for retrieving session scores.
+     * @returns The response containing session scores.
+     */
+    getSessionScore(request: SessionScoreRequest): Promise<SessionScoreResponse>;
+    /**
+     * Lock or unlock exercise sessions.
+     * @param request The request payload for locking/unlocking sessions.
+     * @returns The response confirming the action.
+     */
+    lockSession(request: SessionLockRequest): Promise<SessionLockResponse>;
+    /**
+     * Retrieve detailed information about a session.
+     * @param request The request payload for retrieving session information.
+     * @returns The response containing session details.
+     */
+    getSessionInfo(request: SessionInfoRequest): Promise<SessionInfoResponse>;
+    /**
+     * Retrieve existing sessions by their IDs.
+     * @param request The request payload containing session IDs.
+     * @returns The response containing session data for each ID.
+     */
+    retrieveSession(request: SessionRetrieveRequest): Promise<SessionRetrieveResponse>;
+    /**
+     * Validate an exercise definition or ID.
+     * @param request The request payload for exercise validation.
+     * @returns The response containing validation results and details.
+     */
+    validateExercise(request: ExerciseValidateRequest): Promise<ExerciseValidateResponse>;
+    /**
+     * Retrieve published information about an exercise (structure, versions, history).
+     * @param request The request payload containing the exercise ID.
+     * @returns The response containing published info about the exercise.
+     */
+    getExercisePublishedInfo(request: ExerciseInfoRequest): Promise<ExerciseInfoResponse>;
+}
+//# sourceMappingURL=ApiClient.d.ts.map

package/dist/ApiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiClient.d.ts","sourceRoot":"","sources":["../src/ApiClient.ts"],"names":[],"mappings":"AACA,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,qBAAa,SAAS;IAQR,OAAO,CAAC,OAAO;IAAU,OAAO,CAAC,MAAM;IAPnD,OAAO,CAAC,aAAa,CAAgB;IAErC;;;;OAIG;gBACiB,OAAO,EAAE,MAAM,EAAU,MAAM,EAAE,MAAM;IAU3D;;;;OAIG;IACU,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAIzF;;;;OAIG;IACU,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAIzF;;;;OAIG;IACU,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAInF;;;;OAIG;IACU,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAItF;;;;OAIG;IACU,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAI/F;;;;OAIG;IACU,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAIlG;;;;OAIG;IACU,wBAAwB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAGnG"}

package/dist/ApiClient.js

@@ -0,0 +1,109 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiClient = void 0;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * ApiClient is a wrapper around Axios to interact with the Algebrakit Webservice API.
+ */
+class ApiClient {
+    /**
+     * Initialize the API client with a base URL and API key.
+     * @param baseUrl The base URL of the Algebrakit Webservice API.
+     * @param apiKey The API key for authentication.
+     */
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl;
+        this.apiKey = apiKey;
+        this.axiosInstance = axios_1.default.create({
+            baseURL: baseUrl,
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': apiKey
+            },
+        });
+    }
+    /**
+     * Create new exercise sessions.
+     * @param request The request payload for creating sessions.
+     * @returns The response containing session creation results.
+     */
+    createSession(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.axiosInstance.post('/session/create', request).then(r => r.data);
+        });
+    }
+    /**
+     * Retrieve results from exercise sessions.
+     * @param request The request payload for retrieving session scores.
+     * @returns The response containing session scores.
+     */
+    getSessionScore(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.axiosInstance.post('/session/score', request).then(r => r.data);
+        });
+    }
+    /**
+     * Lock or unlock exercise sessions.
+     * @param request The request payload for locking/unlocking sessions.
+     * @returns The response confirming the action.
+     */
+    lockSession(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.axiosInstance.post('/sessions/lock', request).then(r => r.data);
+        });
+    }
+    /**
+     * Retrieve detailed information about a session.
+     * @param request The request payload for retrieving session information.
+     * @returns The response containing session details.
+     */
+    getSessionInfo(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.axiosInstance.post('/session/info', request).then(r => r.data);
+        });
+    }
+    /**
+     * Retrieve existing sessions by their IDs.
+     * @param request The request payload containing session IDs.
+     * @returns The response containing session data for each ID.
+     */
+    retrieveSession(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.axiosInstance.post('/session/retrieve', request).then(r => r.data);
+        });
+    }
+    /**
+     * Validate an exercise definition or ID.
+     * @param request The request payload for exercise validation.
+     * @returns The response containing validation results and details.
+     */
+    validateExercise(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.axiosInstance.post('/exercise/validate', request).then(r => r.data);
+        });
+    }
+    /**
+     * Retrieve published information about an exercise (structure, versions, history).
+     * @param request The request payload containing the exercise ID.
+     * @returns The response containing published info about the exercise.
+     */
+    getExercisePublishedInfo(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.axiosInstance.post('/exercise/published-info', request).then(r => r.data);
+        });
+    }
+}
+exports.ApiClient = ApiClient;
+//# sourceMappingURL=ApiClient.js.map

package/dist/ApiClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiClient.js","sourceRoot":"","sources":["../src/ApiClient.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,kDAA6C;AAoB7C;;GAEG;AACH,MAAa,SAAS;IAGpB;;;;OAIG;IACH,YAAoB,OAAe,EAAU,MAAc;QAAvC,YAAO,GAAP,OAAO,CAAQ;QAAU,WAAM,GAAN,MAAM,CAAQ;QACzD,IAAI,CAAC,aAAa,GAAG,eAAK,CAAC,MAAM,CAAC;YAChC,OAAO,EAAE,OAAO;YAChB,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,WAAW,EAAE,MAAM;aACpB;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACU,aAAa,CAAC,OAA6B;;YACtD,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAwB,iBAAiB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtG,CAAC;KAAA;IAED;;;;OAIG;IACU,eAAe,CAAC,OAA4B;;YACvD,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAuB,gBAAgB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpG,CAAC;KAAA;IAED;;;;OAIG;IACU,WAAW,CAAC,OAA2B;;YAClD,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAsB,gBAAgB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACnG,CAAC;KAAA;IAED;;;;OAIG;IACU,cAAc,CAAC,OAA2B;;YACrD,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAsB,eAAe,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClG,CAAC;KAAA;IAED;;;;OAIG;IACU,eAAe,CAAC,OAA+B;;YAC1D,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAA0B,mBAAmB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1G,CAAC;KAAA;IAED;;;;OAIG;IACU,gBAAgB,CAAC,OAAgC;;YAC5D,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAA2B,oBAAoB,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC5G,CAAC;KAAA;IAED;;;;OAIG;IACU,wBAAwB,CAAC,OAA4B;;YAChE,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAuB,0BAA0B,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC9G,CAAC;KAAA;CACF;AAhFD,8BAgFC"}

package/dist/demo/config.js

@@ -0,0 +1,63 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+const dotenv = __importStar(require("dotenv"));
+const path = __importStar(require("path"));
+// Load environment variables from .env file
+dotenv.config({ path: path.join(__dirname, '.env') });
+/**
+ * Loads and validates configuration from environment variables
+ */
+function loadConfig() {
+    const apiKey = process.env.ALGEBRAKIT_API_KEY;
+    const apiUrl = process.env.ALGEBRAKIT_API_URL || 'https://api.algebrakit.com';
+    // Validate configuration
+    if (!apiKey) {
+        console.error('\n❌ Error: ALGEBRAKIT_API_KEY is not set');
+        console.error('Please create a .env file in the demo directory with your API key.');
+        console.error('You can copy .env.example to .env and add your key.\n');
+        process.exit(1);
+    }
+    if (apiKey === 'your_api_key_here') {
+        console.error('\n❌ Error: Please replace the placeholder API key with your actual key');
+        console.error('Edit the .env file and add your real Algebrakit API key.\n');
+        process.exit(1);
+    }
+    return {
+        apiKey,
+        apiUrl
+    };
+}