@aastrika/ai-elements 0.2.0 → 0.3.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

@@ -9,7 +9,7 @@ Svelte or plain HTML.
 | `<aastrika-assessment>` | Source material becomes a validated MCQ set |
 | `<aastrika-reports>` | Who used what, and what it cost *(admin only)* |
 
-One file, **86 kB** over the wire, **no dependencies**. Angular is compiled
+One file, **~99 kB gzipped** (86 kB brotli), **no dependencies**. Angular is compiled
 inside, so you never install it and never upgrade because we did.
 
 ---
@@ -20,6 +20,8 @@ inside, so you never install it and never upgrade because we did.
 |---|---|
 | [The three features](#the-three-features) | What each element does |
 | [Setup](#setup) | Install, access, configure, mount |
+| [Integration guide](../../../docs/INTEGRATION.md) | Step by step, both auth paths |
+| [Angular example](../../lib-demo-app/) | A runnable app |
 | [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 |
@@ -80,7 +82,7 @@ flowchart LR
     cfg -.->|apiBase · auth · creator| int
     tag --> el
     el --> int
-    int -->|"Authorization<br/>x-aastrika-creator"| gw
+    int -->|"Authorization<br/>creator in the body"| gw
     gw --> api
     api -.->|JSON| el
     el -.->|onError| cfg
@@ -110,7 +112,7 @@ cost estimate, and can revise it in writing as many times as they like. Only
 While it renders they get five-phase progress and a live log; at the end they
 can play, download or delete it.
 
-[Full walkthrough →](features/content-studio/README.md)
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/frontend/src/lib/features/content-studio/README.md)
 
 ### `<aastrika-assessment>`
 
@@ -121,7 +123,7 @@ 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.
 
-[Full walkthrough →](features/assessment/README.md)
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/frontend/src/lib/features/assessment/README.md)
 
 ### `<aastrika-reports>`
 
@@ -133,7 +135,7 @@ 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.
 
-[Full walkthrough →](features/reports/README.md)
+[Full walkthrough →](https://github.com/Sphere/aastrika-ai-service/blob/master/frontend/src/lib/features/reports/README.md)
 
 ---
 
@@ -260,7 +262,7 @@ Three things, and nothing else.
 |---|---|
 | `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` | The username of whoever is signed into **your** application. |
+| `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. |
 
 **Both are functions, and both are called on every request.** Tokens expire: a
@@ -268,6 +270,9 @@ 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.
 
+`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.
+
 `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.
@@ -284,8 +289,8 @@ needs:
 
 | Feature | Groups |
 |---|---|
-| `aastrika-content-studio` | `contentCreate`, `contentRead`, `contentUpdate` |
-| `aastrika-assessment` | `contentCreate`, `contentRead`, `contentUpdate` |
+| `aastrika-content-studio` | `contentCreate`, `contentAccess`, `contentUpdate` |
+| `aastrika-assessment` | `contentCreate`, `contentAccess`, `contentUpdate` |
 | `aastrika-reports` | `contentAdmin` |
 
 Deleting anything needs `contentAdmin` as well. Without `contentUpdate` the
@@ -363,6 +368,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
@@ -370,6 +376,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` |
@@ -377,7 +411,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
@@ -404,14 +438,14 @@ 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 |
 
 ---
 
 ## 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
 

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(