@aastrika/ai-elements 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+`@aastrika/ai-elements`. Newest first. One line per change, so a host team can
+see at a glance what to expect when they upgrade.
+
+Versions follow semver: a **minor** adds something, a **patch** fixes something,
+and neither removes anything a host was using.
+
+## 0.3.0
+
+**Added**
+- `default-translate-into` on `<aastrika-assessment>` — produce the same
+  questions in other languages, comma-separated: `"ta,or,bn"`
+- `assessmentReady` now carries `languages`, the translations actually produced
+- Reviewers get a tab per language; Excel exports one sheet per language, CSV
+  one language at a time
+
+**Fixed**
+- `onError` was never called for hosts configuring through `provideAastrika()`
+
+**Notes for integrators**
+- Nothing is removed and nothing changes for a host that ignores the new input
+- `languages` can be shorter than what was asked for: a translation that fails
+  its checks is dropped rather than stored wrong
+
+## 0.2.1
+
+**Fixed**
+- Documentation corrections in the published README
+
+## 0.2.0
+
+**Added**
+- Starting-value inputs (`default-language`, `default-difficulty` and others),
+  events (`planReady`, `videoReady`, `assessmentReady`, `reportLoaded`) and an
+  `onError` callback
+
+## 0.1.0
+
+**Added**
+- First release: `<aastrika-content-studio>`, `<aastrika-assessment>` and
+  `<aastrika-reports>` as custom elements, with `configure()`

package/README.md

@@ -1,42 +1,37 @@
+<div align="center">
+
 # @aastrika/ai-elements
 
-**Three Aastrika features as custom elements.** Works in React, Vue, Angular,
-Svelte or plain HTML.
+**Three AI features. Three HTML tags. Any framework.**
 
-| Tag | What it does |
-|---|---|
-| `<aastrika-content-studio>` | A document becomes a narrated, illustrated training video |
-| `<aastrika-assessment>` | Source material becomes a validated MCQ set |
-| `<aastrika-reports>` | Who used what, and what it cost *(admin only)* |
+[![npm](https://img.shields.io/npm/v/@aastrika/ai-elements?color=A98229&label=npm)](https://www.npmjs.com/package/@aastrika/ai-elements)
+[![size](https://img.shields.io/badge/gzipped-99%20kB-A98229)](https://www.npmjs.com/package/@aastrika/ai-elements)
+[![deps](https://img.shields.io/badge/dependencies-0-A98229)](https://www.npmjs.com/package/@aastrika/ai-elements)
+[![licence](https://img.shields.io/npm/l/@aastrika/ai-elements?color=A98229)](https://github.com/Sphere/aastrika-ai-service/blob/master/LICENSE)
 
-One file, **86 kB** over the wire, **no dependencies**. Angular is compiled
-inside, so you never install it and never upgrade because we did.
+</div>
 
----
-
-## Contents
+```html
+<aastrika-content-studio></aastrika-content-studio>   <!-- document → narrated video -->
+<aastrika-assessment></aastrika-assessment>           <!-- material → MCQ set, translated -->
+<aastrika-reports></aastrika-reports>                 <!-- who used what, and what it cost -->
+```
 
-| | |
-|---|---|
-| [The three features](#the-three-features) | What each element does |
-| [Setup](#setup) | Install, access, configure, mount |
-| [Framework notes](#framework-notes) | React · Angular · Plain HTML |
-| [Configuration](#configuration) | The three values, and why two are functions |
-| [Access](#access) | Which gateway groups each feature needs |
-| [Theming](#theming) | CSS custom properties |
-| [Knowing when something failed](#knowing-when-something-failed) | Routing errors to your monitoring |
-| [Inputs and events](#inputs-and-events) | Opening the form set up, and acting on the result |
-| [When it does not work](#when-it-does-not-work) | Symptom → cause |
-| [Browser support](#browser-support) · [Server rendering](#server-rendering) | Constraints |
+Works in **React, Vue, Angular, Svelte or plain HTML**. Angular is compiled
+inside the package, so you never install it and never upgrade because we did.
 
 ---
 
-## Quick start
+## Ship it in three steps
+
+**1 — Install.** No peer dependencies, nothing to match.
 
 ```bash
 npm i @aastrika/ai-elements
 ```
 
+**2 — Configure once**, before anything renders.
+
 ```js
 import { configure } from '@aastrika/ai-elements';
 
@@ -47,53 +42,43 @@ configure({
 });
 ```
 
+**3 — Write the tag.** Importing the package registers it, so there is no step 4.
+
 ```html
-<aastrika-content-studio></aastrika-content-studio>
+<aastrika-assessment default-language="hi" default-translate-into="ta,or"></aastrika-assessment>
 ```
 
-That is the whole integration. The rest of this file is detail.
-
-> **You also need gateway access.** The package authenticates nobody — see
-> [Access](#access) for the groups each feature requires.
+<div align="center">
 
----
+**That is the whole integration.**
+A trainer uploads a PDF and gets a validated quiz in Hindi, Tamil and Odia —
+same questions, same answer key, ready to download.
 
-## How it fits together
+</div>
 
-```mermaid
-flowchart LR
-    subgraph host["Your application"]
-        cfg["configure()"]
-        tag["&lt;aastrika-content-studio&gt;"]
-    end
+> [!IMPORTANT]
+> **You also need gateway access.** This package authenticates nobody — your
+> gateway decides. See [Access](#access) for the groups each feature needs.
 
-    subgraph pkg["@aastrika/ai-elements"]
-        el["Custom element"]
-        int["Interceptor"]
-    end
+---
 
-    subgraph svc["Aastrika"]
-        gw["Gateway<br/>checks the token"]
-        api["AI service"]
-    end
+## Where to look
 
-    cfg -.->|apiBase · auth · creator| int
-    tag --> el
-    el --> int
-    int -->|"Authorization<br/>x-aastrika-creator"| gw
-    gw --> api
-    api -.->|JSON| el
-    el -.->|onError| cfg
-
-    classDef a fill:#0F766E,stroke:none,color:#fff
-    classDef b fill:#f1f5f4,stroke:#cbd5d3,color:#16181d
-    class el,int a
-    class cfg,tag,gw,api b
-```
+| | |
+|---|---|
+| **[The three features](#the-three-features)** | What each element actually does |
+| **[Setup](#setup)** | Install · access · configure · mount |
+| **[Configuration](#configuration)** | The three values, and why two are functions |
+| **[Access](#access)** | Which gateway groups each feature needs |
+| **[Inputs and events](#inputs-and-events)** | Open the form set up, act on the result |
+| **[Error reporting](#knowing-when-something-failed)** | Route failures to your monitoring |
+| | |
+| [Integration guide ↗](https://github.com/Sphere/aastrika-ai-service/blob/master/docs/INTEGRATION.md) | Step by step, both auth paths |
+| [Runnable Angular app ↗](https://github.com/Sphere/aastrika-ai-service/tree/master/frontend/lib-demo-app) | Clone it, change one line, run it |
+| [Changelog ↗](./CHANGELOG.md) | What changed in each version |
 
-**Your application supplies three values. The package does the rest** — builds
-every request from `apiBase`, calls your two functions on each one, and renders
-into your page, styled through CSS custom properties.
+*Framework notes, theming, troubleshooting and server rendering are collapsed
+below — open the one you need.*
 
 ---
 
@@ -101,45 +86,65 @@ into your page, styled through CSS custom properties.
 
 ### `<aastrika-content-studio>`
 
-Upload a PDF, pick a style, language and voice, and get back a narrated,
-illustrated training video.
+**A PDF goes in. A narrated, illustrated training video comes out.**
+
+```
+ upload ──▶ pick style ──▶ review the plan ──▶ generate ──▶ play / download
+            language        free, revisable      the only
+            voice           cost shown first     paid step
+```
 
-Planning is free and repeatable — the user sees the scene-by-scene plan and a
-cost estimate, and can revise it in writing as many times as they like. Only
-**Generate video** spends money, and the user sees what it will cost first.
-While it renders they get five-phase progress and a live log; at the end they
-can play, download or delete it.
+The user uploads source material, picks a style, language and voice, and sees a
+scene-by-scene plan with an estimated cost. **Planning is free and repeatable** —
+they can rewrite it in plain words as often as they like. Only *Generate video*
+spends money, and the estimate is on screen before they commit.
 
-[Full walkthrough →](features/content-studio/README.md)
+While it renders they see five-phase progress and a live log. At the end they
+can play it, download it, or delete it.
+
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/docs/API.md)
 
 ### `<aastrika-assessment>`
 
-Files and links in, a validated multiple-choice set out — with control over
-language, question count, difficulty and Bloom level.
+**Training material goes in. A validated MCQ set comes out — in as many
+languages as you need.**
+
+```
+ files & links ──▶ settings ──▶ questions ──▶ review each ──▶ export
+                   language      checked       language on     xlsx / csv
+                   count         before you    its own tab
+                   difficulty    see them
+```
+
+Every question is checked before it reaches the user: exactly one correct
+option, no duplicates, nothing the source material does not support.
 
-Every question is checked before it is returned: one correct option, no
-duplicates, nothing the source material does not support. The user can fix
-wording, re-tick the correct option, then export XLSX or CSV.
+Ask for other languages and you get the **same** questions translated — same
+order, same options, same answer key — so one answer key marks every paper and
+scores compare across them. The reviewer reads each language on its own tab and
+fixes wording in place; the correct option is shared, so it is set once.
 
-[Full walkthrough →](features/assessment/README.md)
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/docs/API.md)
 
 ### `<aastrika-reports>`
 
-Who used what, and what it cost — totals for videos, assessments, people and
-estimated spend, split by tool, with a searchable table of creators.
+**Who made what, and what it cost.**
+
+Totals for videos, assessments, people and estimated spend, split by tool, with
+a searchable table of creators.
 
-**Needs `contentAdmin` at the gateway**, and most consumers should not have it:
-spend figures are not for a partner's ordinary users. The service applies no
-role check of its own, so the gateway's ACL is the only thing keeping them
-apart.
+> [!WARNING]
+> **Needs `contentAdmin`, and most consumers should not have it.** Spend figures
+> are not for a partner's ordinary users. The service applies no role check of
+> its own — the gateway's ACL is the only thing keeping them apart.
 
-[Full walkthrough →](features/reports/README.md)
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/docs/API.md)
 
 ---
 
 ## Setup
 
-The [Quick start](#quick-start) above is the whole integration. What each step
+The [Quick start](#ship-it-in-three-steps) above is the whole integration. What each step
 is actually doing:
 
 | | Step | Notes |
@@ -151,7 +156,8 @@ is actually doing:
 
 ---
 
-## Framework notes
+<details>
+<summary><b>React · Angular · Vue · plain HTML</b></summary>
 
 ### React
 
@@ -252,31 +258,79 @@ calling it, as above, prevents both.
 
 ---
 
+</details>
+
+---
+
+## How it fits together
+
+```mermaid
+flowchart LR
+    subgraph host["Your application"]
+        cfg["configure()"]
+        tag["&lt;aastrika-content-studio&gt;"]
+    end
+
+    subgraph pkg["@aastrika/ai-elements"]
+        el["Custom element"]
+        int["Interceptor"]
+    end
+
+    subgraph svc["Aastrika"]
+        gw["Gateway<br/>checks the token"]
+        api["AI service"]
+    end
+
+    cfg -.->|apiBase · auth · creator| int
+    tag --> el
+    el --> int
+    int -->|"Authorization<br/>creator in the body"| gw
+    gw --> api
+    api -.->|JSON| el
+    el -.->|onError| cfg
+
+    classDef a fill:#0F766E,stroke:none,color:#fff
+    classDef b fill:#f1f5f4,stroke:#cbd5d3,color:#16181d
+    class el,int a
+    class cfg,tag,gw,api b
+```
+
+**Your application supplies three values. The package does the rest** — builds
+every request from `apiBase`, calls your two functions on each one, and renders
+into your page, styled through CSS custom properties.
+
+---
+
 ## Configuration
 
-Three things, and nothing else.
+Three values. That is the whole contract.
 
-| | |
-|---|---|
-| `apiBase` | Where the service is, no trailing slash. Empty string means same-origin. |
-| `getAuthHeaders` | Headers proving the caller may use the service — in practice a bearer token. |
-| `creator` | Who is signed into **your** application — their name or email, shown as-is in the usage report. |
-| `onError` | Optional. Called whenever a request fails, so your monitoring hears about it. |
+| | | |
+|---|---|---|
+| `apiBase` | **required** | Where the service is, no trailing slash. `''` means same-origin |
+| `getAuthHeaders` | **required** | Headers proving the caller may use the service — a bearer token in practice |
+| `creator` | **required** | Who is signed into *your* app. A name or email, shown as-is in the usage report |
+| `onError` | optional | Called whenever a request fails, so your monitoring hears about it |
+
+### Why two of them are functions
 
-**Both are functions, and both are called on every request.** Tokens expire: a
-string handed over at startup stops working mid-session and the package has no
-way to ask for a fresh one. A function lets you return whatever your own auth
-library currently holds, and lets you switch user without reloading.
+Tokens expire. A string handed over at startup stops working mid-session, and
+the package has no way to ask for a fresh one.
 
-`creator` should be a **name or email** — it is displayed as-is in the usage
-report, so `asha.kumari` reads well and a UUID does not.
+```js
+getAuthHeaders: async () => ({ Authorization: `Bearer ${await auth.token()}` }),
+//              ^^^^^ called on every request, so a refreshed token just works
+```
 
-`creator` is **attribution, not identity**. It is recorded against anything the
-call creates and the usage report groups by it. Nothing verifies it — the
-gateway decides whether the call is allowed at all.
+The same goes for `creator`: a function lets you switch user without reloading
+the page.
 
-The package authenticates nobody and has no login of its own. You are already
-signed in, and you know who that is better than we could.
+> [!NOTE]
+> **`creator` is attribution, not identity.** It is recorded against whatever
+> the call creates and the usage report groups by it. Nothing verifies it — the
+> gateway decides whether the call is allowed at all.
+>
+> Use `asha.kumari`, not a UUID. It appears as-is in the report.
 
 ---
 
@@ -294,12 +348,14 @@ needs:
 Deleting anything needs `contentAdmin` as well. Without `contentUpdate` the
 features still work, but the revise step returns 403.
 
+> [!CAUTION]
 > **`generate-video` is the only call that spends real money**, and it sits on a
 > deliberately low rate limit. Users see a cost estimate before triggering it.
 
 ---
 
-## Theming
+<details>
+<summary><b>Theming with CSS custom properties</b></summary>
 
 CSS custom properties are the styling surface:
 
@@ -319,6 +375,10 @@ stylesheet is broad, scope it away from the three tags.
 
 ---
 
+</details>
+
+---
+
 ## Knowing when something failed
 
 The elements show their own error to the user. `onError` is the second copy, for
@@ -366,6 +426,7 @@ All are **starting values** the user can still change.
 | `assessment` | `default-language` | |
 | | `default-question-count` | |
 | | `default-difficulty` | `mixed`, `easy`, `medium`, `hard` |
+| | `default-translate-into` | Also produce the same questions in these languages, comma-separated: `"ta,or,bn"` |
 | `reports` | `creator-filter` | Opens filtered to one creator |
 
 ```html
@@ -373,6 +434,34 @@ All are **starting values** the user can still change.
 </aastrika-content-studio>
 ```
 
+### One quiz, several languages
+
+`default-translate-into` produces the **same** questions in other languages —
+same order, same options, same answer key — so one answer key marks every
+language and scores compare across them.
+
+```html
+<aastrika-assessment default-language="hi" default-translate-into="en,mr">
+</aastrika-assessment>
+```
+
+The reviewer gets a tab per language. Excel holds every language, one sheet
+each; CSV holds one language at a time.
+
+`assessmentReady` reports what came back:
+
+```js
+el.addEventListener('assessmentReady', (e) => {
+  e.detail.language;   // 'hi'         — the one the questions were written in
+  e.detail.languages;  // ['en','mr']  — the translations produced
+});
+```
+
+`languages` can be shorter than what was asked for. A translation is checked for
+question count, ids, answer key, clinical numbers and script; one that fails is
+dropped rather than stored wrong. What is **not** checked is whether the
+translation reads well — that still needs someone who speaks the language.
+
 ### Events
 
 | Element | Event | Fires when | `detail` |
@@ -380,7 +469,7 @@ All are **starting values** the user can still change.
 | `content-studio` | `planReady` | A plan comes back. **Repeatable** — free, so this can fire several times | `jobId`, `title`, `sceneCount`, `estimatedUsd` |
 | | `videoStarted` | The user commits to a render. **This is where money is spent** | `jobId` |
 | | `videoReady` | The video is finished | `jobId`, `videoUrl` |
-| `assessment` | `assessmentReady` | A validated question set comes back | `jobId`, `questionCount`, `language` |
+| `assessment` | `assessmentReady` | A validated question set comes back | `jobId`, `questionCount`, `language`, `languages` |
 | `reports` | `reportLoaded` | The figures are on screen | `videos`, `assessments`, `users`, `spendUsd` |
 
 ```js
@@ -398,7 +487,8 @@ any DOM event: `(videoReady)="onReady($event)"`.
 
 ---
 
-## When it does not work
+<details>
+<summary><b>Troubleshooting — symptom → cause</b></summary>
 
 | Symptom | Cause |
 |---|---|
@@ -407,16 +497,21 @@ any DOM event: `(videoReady)="onReady($event)"`.
 | `403` on revise only | missing `contentUpdate` |
 | `403` on delete only | missing `contentAdmin` |
 | `429` on Generate video | the low rate limit, and it is intentional |
-| Creator recorded as `unknown` | the gateway's CORS config is dropping `x-aastrika-creator` — tell us |
+| Everything recorded as `admin` | `creator` was not set, or it returned null |
 | Blank box, no errors | the module did not load, so the tag is an unknown element |
 
 ---
 
+</details>
+
+---
+
 ## Browser support
 
-Any browser with Custom Elements v1 and Shadow DOM — everything since 2018.
+Any browser with Custom Elements v1 — everything since 2018.
 
-## Server rendering
+<details>
+<summary><b>Server rendering (Next.js, Angular Universal)</b></summary>
 
 **Import this package only in browser code.** It is not server-renderable, and
 the failure is a crash rather than an empty box: `@angular/elements` declares a
@@ -440,3 +535,8 @@ Angular Universal: keep the import inside a browser-only guard, or load it in
 Nothing is lost by this. The elements have no server-rendered output to hydrate
 — they fetch everything at runtime — so a client-only import renders exactly the
 same page.
+
+</details>
+
+---
+

package/aastrika-elements.d.ts

@@ -20,8 +20,15 @@
 
 /** What a request failure tells the host. Stable across features. */
 export interface AastrikaError {
-  /** Which element the failure came from. */
-  feature: 'content-studio' | 'assessment' | 'reports';
+  /**
+   * Which element the failure came from.
+   *
+   * The three shipped today, and open to more: a future feature emits a name
+   * not in this list, and narrowing the type to only these three would turn
+   * that into a compile error in every host's handler. The literals stay so
+   * an editor still suggests them.
+   */
+  feature: 'content-studio' | 'assessment' | 'reports' | (string & {});
   /** The sentence already shown to the user. */
   message: string;
   /** HTTP status. 0 means the request never left the browser — usually CORS. */
@@ -116,11 +123,29 @@ interface AastrikaAssessmentElement extends HTMLElement {
   defaultQuestionCount?: number;
   /** `'mixed'`, `'easy'`, `'medium'` or `'hard'`. */
   defaultDifficulty?: string;
+  /**
+   * Languages to render the same questions into, comma-separated
+   * (`"ta,or,bn"`), written as `default-translate-into` in HTML. The SAME
+   * assessment in each — same order, same options, same answer key — so one
+   * key marks every language.
+   *
+   * A starting value like the others: the user can change the selection before
+   * generating.
+   */
+  defaultTranslateInto?: string;
 
-  /** A validated question set came back. */
+  /**
+   * A validated question set came back.
+   *
+   * `language` is the primary; `languages` lists the translations that were
+   * produced, which may be shorter than what was asked for — a language the
+   * model could not render faithfully is dropped rather than stored wrong.
+   */
   addEventListener(
     type: 'assessmentReady',
-    listener: (e: CustomEvent<{ jobId: string; questionCount: number; language: string }>) => void,
+    listener: (e: CustomEvent<{
+      jobId: string; questionCount: number; language: string; languages: string[];
+    }>) => void,
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(