Skip to content

README.md

Latest commit

 

History

History
136 lines (107 loc) · 5.96 KB

README.md

File metadata and controls

136 lines (107 loc) · 5.96 KB
Raw

@brain-storm/sdk — API Reference

Generated API reference for the public surface of the @brain-storm/sdk package.

The @brain-storm/sdk package provides a fully-typed, zero-dependency client for the Brain-Storm REST API. It is consumed by apps/frontend, packages/mobile-app, and third-party integrations to interact with courses, learner progress, user authentication, profiles, and Stellar account queries.

Table of Contents

  1. Installation & Setup
  2. Quick Start
  3. Public Surface Summary
  4. Client Classes
  5. Data Transfer Objects (DTOs) & Types
  6. Error Handling

Installation & Setup

# Monorepo workspace installation:
npm install @brain-storm/sdk --workspace=apps/frontend
# or
npm install @brain-storm/sdk --workspace=packages/mobile-app

Quick Start

import { BrainStormClient } from '@brain-storm/sdk';

// 1. Initialize client
const client = new BrainStormClient({
  baseURL: 'https://api.brain-storm.com', // no trailing slash or /v1 prefix
});

// 2. Authenticate
const { access_token } = await client.auth.login({
  email: 'learner@example.com',
  password: 'SecurePassword123!',
});

// 3. Set Bearer token for subsequent authenticated calls
client.setToken(access_token);

// 4. Query published courses
const courses = await client.courses.list({
  level: 'beginner',
  limit: 10,
});

console.log(`Found ${courses.total} courses:`, courses.data);

// 5. Record course progress
await client.progress.record({
  courseId: courses.data[0].id,
  progressPct: 100, // Reaching 100% triggers on-chain credential issuance
});

Public Surface Summary

Every export from packages/sdk/src/index.ts is strictly governed by the semantic versioning contract:

Main Client

Export Kind Description
BrainStormClient class Primary entry point grouping all resource namespaces.
default re-export Default export alias for BrainStormClient.

Namespaces & Methods

Namespace Methods Description
client.auth register, login, logout User registration, credential authentication, session revocation
client.courses list, get, create, update, remove Course catalogue browsing, search, authoring, and management
client.progress record, getMyCourseProgress Student progress updates and course completion tracking
client.users getProfile, updateProfile User profile retrieval and bio/avatar updates
client.stellar getBalance Relay query for Stellar/Soroban account asset balances

Types & Interfaces

Type / Interface Description
BrainStormClientOptions Constructor configuration options (baseURL, token)
LoginDto Payload for user login with optional MFA TOTP token
RegisterDto Payload for user registration
AuthResponse Access and refresh token pair
CourseDto Full course entity model
CreateCourseDto Course creation request payload
UpdateCourseDto Course partial update payload
CourseListResponse Paginated list response for courses
CourseQueryParams Filter and pagination query parameters
RecordProgressDto Course/lesson progress submission payload
ProgressDto Stored progress record with percentage and timestamps
UserDto User profile data with role and Stellar public key
UpdateUserDto User profile editable fields
StellarBalanceResponse Account balances (decimal strings for 7-decimal precision)
ApiError Standard error structure returned on non-2xx HTTP responses
HttpAdapter Abstract transport interface contract

Error Handling

When an API call returns a non-2xx HTTP response, the SDK throws an Error whose properties conform to ApiError:

import { ApiError } from '@brain-storm/sdk';

try {
  const course = await client.courses.get('invalid-uuid');
} catch (error) {
  const apiError = error as Error & Partial<ApiError>;
  console.error(`HTTP ${apiError.statusCode}: ${apiError.message}`);
  if (apiError.statusCode === 404) {
    // Handle not found
  }
}