API Provider (spa-api-provider)

A React context provider for embedded CAPTRS SPAs (survey-builder, mini-games, etc.): configuration, game data, scores, events, and typed helpers that call the game-platform HTTP APIs (via axios).

Installation

npm install spa-api-provider

Use ^2.0.1 (or >=2.0.1) so the AI chat discriminator serializes as lineage (Jackson / Kotlin defaults). 2.0.0 used modelLineage, which does not bind server-side — see 2.0.1 in CHANGELOG.md. Team comms: RELEASE.md.

Usage

Import and wrap your app

import React from 'react';
import { ApiProvider } from 'spa-api-provider';

const App = () => {
  return (
    // Optional: <ApiProvider apiUrl="https://api.example.com" token="your-token">
    <ApiProvider>
      <YourComponent />
    </ApiProvider>
  );
};

export default App;

Using the API context

import { useApi } from 'spa-api-provider';

const YourComponent = () => {
  const { getGameScores, saveGameScore, platformContext } = useApi();

  const fetchScores = async () => {
    const scores = await getGameScores();
    console.log(scores);
  };

  console.log(platformContext?.exerciseId);
  console.log(platformContext?.organizationId);

  return (
    <div>
      <button onClick={fetchScores}>Get Scores</button>
    </div>
  );
};

AI chat (POST /api/ai/chat)

From useApi(), aiChat(params) posts JSON matching the platform AIChatRequestDTO: include lineage (PLATFORM_MANAGED or CLIENT_OVERRIDE) — the JSON name matches the Kotlin property under Jackson defaults. Type exports: AiModelLineage, AIChatRequestDTO (discriminated union), optional assertAIChatRequestRuntime for dynamic input.

Platform-managed — omit models (do not send an empty array):

import { useApi, AiModelLineage } from 'spa-api-provider';

const { aiChat } = useApi();

await aiChat({
  lineage: AiModelLineage.PLATFORM_MANAGED,
  messages: [{ role: 'user', content: 'Hello' }],
});

Client override — models is required (non-empty at runtime):

import { useApi, AiModelLineage } from 'spa-api-provider';

const { aiChat } = useApi();

await aiChat({
  lineage: AiModelLineage.CLIENT_OVERRIDE,
  models: ['gpt-4.1-mini'],
  messages: [{ role: 'user', content: 'Hello' }],
});

See CHANGELOG.md (v2.0.1) for the lineage wire key. If you are on 2.0.0, replace modelLineage with lineage.

Platform context (optional)

useApi() exposes an optional platformContext object:

• exerciseId?: string
• appInstanceId?: string
• gameConfigId?: string (explicit value if provided, otherwise derived from appInstanceId)
• organizationId?: string
• rawConfig?: Record<string, unknown>

All fields are optional. Apps that only use providerConfig (apiUrl and token) keep working as before.

The provider normalizes these from incoming CONFIG messages in this order:

1. camelCase top-level fields
2. snake_case top-level fields
3. context.* fallbacks