@aastrika/ai-elements 0.1.0 → 0.2.0

package/README.md

@@ -1,16 +1,101 @@
 # @aastrika/ai-elements
 
-Three Aastrika features as custom elements. Works in React, Vue, Angular, Svelte
-or plain HTML.
+**Three Aastrika features as custom elements.** Works in React, Vue, Angular,
+Svelte or plain HTML.
 
+| 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)* |
+
+One file, **86 kB** over the wire, **no dependencies**. Angular is compiled
+inside, so you never install it and never upgrade because we did.
+
+---
+
+## Contents
+
+| | |
+|---|---|
+| [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 |
+
+---
+
+## Quick start
+
+```bash
+npm i @aastrika/ai-elements
 ```
-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)
+
+```js
+import { configure } from '@aastrika/ai-elements';
+
+configure({
+  apiBase: 'https://api.aastrika.org/ai-studio',
+  getAuthHeaders: async () => ({ Authorization: `Bearer ${await auth.token()}` }),
+  creator: () => currentUser.username,
+});
+```
+
+```html
+<aastrika-content-studio></aastrika-content-studio>
 ```
 
-One file, 86 kB over the wire, no dependencies. Angular is compiled inside, so
-you never install it and never upgrade because we did.
+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.
+
+---
+
+## 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/>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
+```
+
+**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.
+
+---
 
 ## The three features
 
@@ -50,63 +135,113 @@ apart.
 
 [Full walkthrough →](features/reports/README.md)
 
+---
+
 ## Setup
 
-### 1. Install
+The [Quick start](#quick-start) above is the whole integration. What each step
+is actually doing:
 
-```bash
-npm i @aastrika/ai-elements
+| | Step | Notes |
+|---|---|---|
+| **1** | `npm i @aastrika/ai-elements` | No peer dependencies, no framework to match. Any bundler, or none |
+| **2** | Get gateway access | The package authenticates nobody — your gateway decides. See [Access](#access), then ask the Aastrika platform team |
+| **3** | `configure({ ... })` | Once, before the first element renders. Two of the three values are **functions** — see [Configuration](#configuration) |
+| **4** | Write the tag | Registration happens on import, so there is no third step |
+
+---
+
+## Framework notes
+
+### React
+
+```jsx
+import '@aastrika/ai-elements';
+
+<aastrika-content-studio />
 ```
 
-No peer dependencies, no framework to match. Any bundler, or none.
+React 19 passes properties and custom events natively — no wrapper, no `ref`.
 
-### 2. Get gateway access
+### Angular
 
-The package authenticates nobody. Your application is already signed in, and the
-Aastrika gateway decides whether a call is allowed — so before anything works
-you need a Kong consumer with the right groups. See [Access](#access) for which
-feature needs which, and ask the Aastrika platform team to set it up.
+Two steps: call `configure()` once at bootstrap, then add
+`CUSTOM_ELEMENTS_SCHEMA` to whichever component writes the tag.
 
-### 3. Configure, once, at startup
+**1. Configure at bootstrap** — `main.ts`, or an `APP_INITIALIZER` if the values
+come from something you have to load first:
 
-```js
+```ts
 import { configure } from '@aastrika/ai-elements';
+import { environment } from './environments/environment';
 
 configure({
-  apiBase: 'https://api.aastrika.org/ai-studio',
-  getAuthHeaders: async () => ({ Authorization: `Bearer ${await auth.token()}` }),
-  creator: () => currentUser.username,
+  apiBase: environment.aastrikaApiBase,
+  getAuthHeaders: async () => ({ Authorization: `Bearer ${await authService.token()}` }),
+  creator: () => authService.username(),
 });
+
+bootstrapApplication(AppComponent, appConfig);
 ```
 
-Call it before the first element renders. Read [Configuration](#configuration)
-for why two of those three are functions — it is the difference between a
-session that keeps working and one that dies when the token expires.
+Import order matters: the import registers the three tags as a side effect, so it
+has to run before Angular renders a template containing one.
 
-### 4. Drop in a tag
+**2. Host the tag**
 
-```html
-<aastrika-content-studio></aastrika-content-studio>
+```ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@Component({
+  selector: 'app-training',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<aastrika-content-studio></aastrika-content-studio>`,
+})
+export class TrainingComponent {}
 ```
 
-That is the whole integration.
+<details>
+<summary><strong>Routing, styling, and why the schema matters</strong></summary>
 
-## Framework notes
+`CUSTOM_ELEMENTS_SCHEMA` switches off template checking for **every** unknown
+tag in that component, not just ours — which is why the package ships tag
+declarations. They give it back for these three, so a typo in
+`aastrika-assessment` is still an error rather than a silently empty box.
 
-### React
-
-```jsx
-import '@aastrika/ai-elements';
+**Little else to wire.** `apiBase`, the auth headers and the creator all come
+from `configure()`, and each element manages its own state, so there is no
+cleanup to write. Beyond that there are optional
+[inputs and events](#inputs-and-events) — and `edit-mode`, which is worth
+knowing about up front:
 
-<aastrika-content-studio />
+```html
+<aastrika-content-studio edit-mode="on"></aastrika-content-studio>
 ```
 
-React 19 passes properties and custom events natively — no wrapper, no `ref`.
+`edit-mode` turns on the segment editor for an uploaded video, and defaults to
+`off`. Leave it off unless the host is **same-origin** with the service: the
+editor loads per-segment thumbnails the service streams off local disk, and
+unlike the finished video those have no presigned URL, so they cannot load from
+another origin. The other two elements take no attributes.
 
-### Angular
+**Routing** works normally — put the tag in a lazily loaded route and the element
+mounts on navigation, unmounts on leaving.
+
+**Styling** goes through CSS custom properties. Angular's view encapsulation
+rewrites a component-scoped rule into something that will not match the
+element, so set the properties from a global stylesheet:
+
+```css
+/* styles.css */
+aastrika-content-studio { --aastrika-gold: #0F766E; }
+```
+
+**A blank box** almost always means `configure()` ran after the template, or the
+import was tree-shaken because nothing referenced it. Importing `configure` and
+calling it, as above, prevents both.
 
-Add `CUSTOM_ELEMENTS_SCHEMA` to the component that uses the tag. The package
-ships tag declarations, so these three keep their template checking.
+</details>
 
 ### Plain HTML
 
@@ -115,6 +250,8 @@ ships tag declarations, so these three keep their template checking.
 <aastrika-content-studio></aastrika-content-studio>
 ```
 
+---
+
 ## Configuration
 
 Three things, and nothing else.
@@ -124,6 +261,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. |
+| `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
 string handed over at startup stops working mid-session and the package has no
@@ -137,6 +275,8 @@ gateway decides whether the call is allowed at all.
 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.
 
+---
+
 ## Access
 
 Ask the Aastrika platform team for a Kong consumer with the groups each feature
@@ -154,11 +294,11 @@ features still work, but the revise step returns 403.
 > **`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
 
-CSS custom properties are the entire styling surface. Everything renders inside
-a shadow root, so your CSS cannot reach in — and the package cannot reach out
-and break your layout.
+CSS custom properties are the styling surface:
 
 ```css
 aastrika-content-studio {
@@ -168,14 +308,93 @@ aastrika-content-studio {
 }
 ```
 
-## Events
+**These render into your page, not a shadow root.** Angular's emulated view
+encapsulation scopes the package's own CSS, so it will not leak out and break
+your layout. It does not stop your CSS reaching in: a global rule on a common
+class name — `.card`, `.btn`, `.field` — will hit these elements too. If your
+stylesheet is broad, scope it away from the three tags.
+
+---
+
+## Knowing when something failed
+
+The elements show their own error to the user. `onError` is the second copy, for
+your monitoring:
+
+```js
+configure({
+  apiBase: '...',
+  onError: ({ feature, message, status, code }) => {
+    Sentry.captureMessage(`aastrika/${feature}: ${message}`, { extra: { status, code } });
+  },
+});
+```
+
+| | |
+|---|---|
+| `feature` | `content-studio`, `assessment` or `reports` |
+| `message` | The sentence shown to the user |
+| `status` | HTTP status. **`0` means the request never left the browser** — usually CORS |
+| `code` | The service's code, when it sent one, e.g. `RENDER_TIMEOUT` |
+
+Without it, an element failing every call looks exactly like one nobody has
+used yet. Throwing from inside it is safe — the exception is swallowed, so a
+broken reporter cannot break the feature reporting to it.
+
+---
+
+## Inputs and events
+
+Every element works with nothing bound. These are for hosts that want to open
+the form already set up, or act on what the user produced.
+
+### Inputs
+
+Attributes in HTML, properties in JS — Angular Elements maps one to the other.
+All are **starting values** the user can still change.
+
+| Element | Input | |
+|---|---|---|
+| `content-studio` | `default-language` | `hi`, `en`, `kn`, `te` |
+| | `default-aspect-ratio` | `16:9` or `9:16` |
+| | `default-depth` | How much detail the video goes into |
+| | `default-voice` | A voice id from `/v1/studio/list-voices` |
+| | `edit-mode` | `on` shows the segment editor. Same-origin hosts only |
+| `assessment` | `default-language` | |
+| | `default-question-count` | |
+| | `default-difficulty` | `mixed`, `easy`, `medium`, `hard` |
+| `reports` | `creator-filter` | Opens filtered to one creator |
+
+```html
+<aastrika-content-studio default-language="kn" default-aspect-ratio="9:16">
+</aastrika-content-studio>
+```
+
+### Events
+
+| Element | Event | Fires when | `detail` |
+|---|---|---|---|
+| `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` |
+| `reports` | `reportLoaded` | The figures are on screen | `videos`, `assessments`, `users`, `spendUsd` |
 
 ```js
-el.addEventListener('aastrika-job-started', (e) => save(e.detail.jobId));
-el.addEventListener('aastrika-video-ready', (e) => show(e.detail.videoUrl));
-el.addEventListener('aastrika-error',       (e) => toast(e.detail.message));
+el.addEventListener('videoReady', (e) => {
+  saveToOurRecords(e.detail.jobId, e.detail.videoUrl);
+});
 ```
 
+`videoUrl` plays without an `Authorization` header, so it can go straight into a
+`<video src>` or be stored as-is. It is null on the local storage driver, where
+there is nothing to presign.
+
+**React** passes properties and listeners natively. **Angular** binds them like
+any DOM event: `(videoReady)="onReady($event)"`.
+
+---
+
 ## When it does not work
 
 | Symptom | Cause |
@@ -188,7 +407,33 @@ el.addEventListener('aastrika-error',       (e) => toast(e.detail.message));
 | Creator recorded as `unknown` | the gateway's CORS config is dropping `x-aastrika-creator` — tell us |
 | 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.
-Not server-rendered; the elements hydrate client-side.
+
+## Server rendering
+
+**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
+class extending `HTMLElement` at module scope, so merely importing the package
+where there is no DOM throws `ReferenceError: HTMLElement is not defined`.
+
+Next.js:
+
+```jsx
+import dynamic from 'next/dynamic';
+
+const Studio = dynamic(
+  () => import('@aastrika/ai-elements').then(() => () => <aastrika-content-studio />),
+  { ssr: false },
+);
+```
+
+Angular Universal: keep the import inside a browser-only guard, or load it in
+`ngAfterViewInit` rather than at module scope.
+
+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.

package/aastrika-elements.d.ts

@@ -1,21 +1,157 @@
 /**
- * Tag declarations for consumers.
+ * The published type surface. This file IS the public API.
  *
- * An Angular host embedding these has to add CUSTOM_ELEMENTS_SCHEMA, which
- * switches off template checking for every unknown tag in that component — not
- * just ours. Declaring the tags here gives that back for these three, so a
- * typo in `aastrika-assessment` is still an error rather than a silently empty
- * box. React and Vue hosts get editor completion from the same declarations.
+ * It is hand-written rather than generated, because the bundle Angular emits is
+ * one file with no declarations and the three values a consumer touches are
+ * stable enough to state directly. Two rules follow from that:
+ *
+ *   - Anything exported from src/elements/main.ts must be declared here, or a
+ *     TypeScript consumer gets `any` for the one call the README mandates.
+ *   - Anything declared here is a promise. Removing or renaming it is a
+ *     breaking change; tests/lib/public-surface.test.ts fails on any drift.
+ *
+ * The tag declarations matter for a second reason. An Angular host embedding
+ * these adds CUSTOM_ELEMENTS_SCHEMA, which switches off template checking for
+ * every unknown tag in that component — not just ours. Declaring the tags gives
+ * it back for these three, so a typo in `aastrika-assessment` is still an error
+ * rather than a silently empty box. React and Vue hosts get completion from the
+ * same declarations.
+ */
+
+/** What a request failure tells the host. Stable across features. */
+export interface AastrikaError {
+  /** Which element the failure came from. */
+  feature: 'content-studio' | 'assessment' | 'reports';
+  /** The sentence already shown to the user. */
+  message: string;
+  /** HTTP status. 0 means the request never left the browser — usually CORS. */
+  status?: number;
+  /** The service's stable code, when it sent one, e.g. `RENDER_TIMEOUT`. */
+  code?: string;
+}
+
+/** Everything a host application tells this package. */
+export interface AastrikaConfig {
+  /** Where the service is, no trailing slash. Empty string means same-origin. */
+  apiBase: string;
+  /** Headers proving the caller may use the service. Called before every request. */
+  getAuthHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+  /** The username signed into YOUR application. Attribution, never verified. */
+  creator?: () => string | null;
+  /** Called whenever a request fails, so your monitoring hears about it. */
+  onError?: (error: AastrikaError) => void;
+}
+
+/**
+ * Point the package at a service. Call once, before or after the elements are
+ * on the page; calling again replaces the configuration.
+ */
+export declare function configure(config: AastrikaConfig): void;
+
+/**
+ * Resolves once the three tags are registered.
+ *
+ * Importing this module registers them as a side effect, so a host rarely needs
+ * this — it is here for code that must not run until the elements exist.
  */
+export declare const ready: Promise<unknown>;
 
-interface AastrikaElement extends HTMLElement {}
+/**
+ * Attributes are set in HTML (`default-language="kn"`), properties in JS
+ * (`el.defaultLanguage = 'kn'`), and events with addEventListener. Angular
+ * Elements maps one to the other, so a host uses whichever suits it.
+ *
+ * Every input is a STARTING value the user can still change, and every event
+ * is safe to ignore — an element with nothing bound behaves exactly as before.
+ */
+
+/** `<aastrika-content-studio>` — a document becomes a narrated training video. */
+interface AastrikaContentStudioElement extends HTMLElement {
+  /**
+   * `'on'` shows the segment editor for an uploaded video. Defaults to `'off'`.
+   *
+   * Off by default because the editor loads per-segment thumbnails the service
+   * streams off local disk, which — unlike the finished video — have no
+   * presigned URL and so cannot load from another origin. Turn it on only for a
+   * same-origin host.
+   */
+  editMode?: 'on' | 'off';
+  /** Language the form opens on, e.g. `'hi'`, `'en'`, `'kn'`, `'te'`. */
+  defaultLanguage?: string;
+  /** `'16:9'` or `'9:16'`. */
+  defaultAspectRatio?: string;
+  /** How much detail the video goes into, e.g. `'standard'`. */
+  defaultDepth?: string;
+  /** A voice id from `/v1/studio/list-voices`. */
+  defaultVoice?: string;
+
+  /** A plan came back. Free and repeatable, so this can fire more than once. */
+  addEventListener(
+    type: 'planReady',
+    listener: (e: CustomEvent<{ jobId: string; title: string; sceneCount: number; estimatedUsd: number | null }>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  /** The user committed to a render. This is the point money is spent. */
+  addEventListener(type: 'videoStarted', listener: (e: CustomEvent<{ jobId: string }>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  /** The video finished. `videoUrl` plays without an Authorization header. */
+  addEventListener(
+    type: 'videoReady',
+    listener: (e: CustomEvent<{ jobId: string; videoUrl: string }>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+}
+
+/** `<aastrika-assessment>` — source material becomes a validated MCQ set. */
+interface AastrikaAssessmentElement extends HTMLElement {
+  /** Language the form opens on. */
+  defaultLanguage?: string;
+  /** How many questions to ask for. */
+  defaultQuestionCount?: number;
+  /** `'mixed'`, `'easy'`, `'medium'` or `'hard'`. */
+  defaultDifficulty?: string;
+
+  /** A validated question set came back. */
+  addEventListener(
+    type: 'assessmentReady',
+    listener: (e: CustomEvent<{ jobId: string; questionCount: number; language: string }>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+}
+
+/** `<aastrika-reports>` — usage and spend. Needs `contentAdmin` at the gateway. */
+interface AastrikaReportsElement extends HTMLElement {
+  /** Opens filtered to one creator. The user can still clear it. */
+  creatorFilter?: string;
+
+  /** The figures are on screen. */
+  addEventListener(
+    type: 'reportLoaded',
+    listener: (e: CustomEvent<{ videos: number; assessments: number; users: number; spendUsd: number }>) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+}
 
 declare global {
   interface HTMLElementTagNameMap {
-    'aastrika-content-studio': AastrikaElement;
-    'aastrika-assessment': AastrikaElement;
-    'aastrika-reports': AastrikaElement;
+    'aastrika-content-studio': AastrikaContentStudioElement;
+    'aastrika-assessment': AastrikaAssessmentElement;
+    'aastrika-reports': AastrikaReportsElement;
   }
 }
-
-export {};