@superbuilders/primer-tives 0.8.1 → 1.0.0

package/README.md

@@ -1,64 +1,161 @@
 # @superbuilders/primer-tives
 
-TypeScript SDK for the Primer adaptive learning engine. Wraps the raw HTTP protocol in two tiny, fully typed surfaces — one for your backend, one for the browser — so it's mechanically impossible to misuse.
+TypeScript SDK for the Primer adaptive learning engine.
+
+The package exposes **two explicit subpaths**:
+
+- `@superbuilders/primer-tives/server` — runs on your backend, authenticates with your Primer `sk_...` secret key, and starts student sessions.
+- `@superbuilders/primer-tives/client` — runs in the browser and drives the Primer lesson state machine.
+
+There is **no root export**. You must choose the side of the wire you are on.
 
 ```sh
 bun add @superbuilders/primer-tives
 ```
 
-Dependency: `@superbuilders/errors` is installed automatically.
+Dependency note: `@superbuilders/errors` is installed automatically and is used for `errors.try()` / `errors.is()`.
 
-## Two entrypoints
-
-The package ships two subpaths. There is no root export — you must pick the side of the wire you're on:
+## Entrypoints
 
 | Import | Runs on | Wraps |
 |---|---|---|
-| `@superbuilders/primer-tives/server` | your backend | `POST /api/v0/auth/exchange`, `POST /api/v0/students`, `PATCH /api/v0/students/{id}` |
-| `@superbuilders/primer-tives/client` | the browser | `POST /api/v0/advance` (the lesson state machine) |
+| `@superbuilders/primer-tives/server` | your backend | `POST /api/v0/students`, `POST /api/v0/auth/exchange`, `POST /api/v0/auth/exchange/timeback` |
+| `@superbuilders/primer-tives/client` | the browser | `POST /api/v0/advance` |
+
+## Supported student flows
+
+Primer intentionally supports **two** backend-authenticated student flows.
+
+### 1. Primer-native / manual students
+
+Use this when **your system** owns the learner identity.
+
+1. Call `createStudent()` once to mint a stable Primer `studentId`.
+2. Persist that `studentId` in your own database alongside your user record.
+3. At each session start, call `exchangeStudentForAccessToken(studentId)`.
+4. Hand the returned `accessToken` to the browser SDK.
+
+### 2. Live-authoritative Timeback students
+
+Use this when **Timeback / OneRoster** remains the live authority for each login.
 
-No route strings, no `fetch()` calls, no snake_case wire bodies on your side. Both surfaces normalize transport failures into sentinel errors from `@superbuilders/errors`.
+1. At each session start, call `exchangeTimebackStudentForAccessToken(sourcedId)`.
+2. Primer verifies the learner against Timeback on **every call**.
+3. Primer resolves or provisions the frontend-owned Primer student row behind the scenes.
+4. The call returns both the stable Primer `studentId` and a short-lived `accessToken`.
+5. Hand the returned `accessToken` to the browser SDK.
 
-## Round trip
+Persisting the returned `studentId` is fine if you want a stable local foreign key. Session startup for this flow still begins from `sourcedId`, and the returned `accessToken` is the session credential you pass to the browser SDK.
 
-Your backend provisions a student (once), exchanges a `sk_` for a short-lived access token (each session), and hands the token to your frontend. Your frontend passes the token to `create()` and drives the returned state machine.
+## End-to-end examples
+
+### Native/manual flow
 
 ```ts
 // ── your backend ─────────────────────────────────────────────────────
 import * as errors from "@superbuilders/errors"
-import { createPrimerServer } from "@superbuilders/primer-tives/server"
+import {
+  createPrimerServer,
+  ErrConflict,
+  ErrInvalidSecretKey,
+  ErrStudentNotFound
+} from "@superbuilders/primer-tives/server"
 
 const primer = createPrimerServer({
   origin: "https://sb-primer.vercel.app",
-  secretKey: process.env.PRIMER_CLIENT_SECRET_KEY_DEV
+  secretKey: process.env.PRIMER_CLIENT_SECRET_KEY_DEV!,
+  logger: console
 })
 
-// One-time per user: provision a Primer-owned student.
-const studentId = await primer.createNativeStudent("4")
-// persist `studentId` alongside your user record
+// One time per user.
+const createResult = await errors.try(primer.createStudent())
+if (createResult.error) {
+  if (errors.is(createResult.error, ErrInvalidSecretKey)) {
+    throw new Error("Primer secret key is invalid")
+  }
+  if (errors.is(createResult.error, ErrConflict)) {
+    throw new Error("This Primer frontend is not provisioned with routable content")
+  }
+  throw createResult.error
+}
+const studentId = createResult.data
+// persist `studentId` alongside your own user record
 
-// Every session: mint a short-lived access token.
-const result = await errors.try(
-  primer.exchangeNativeStudentForAccessToken(studentId)
+// Every session start.
+const tokenResult = await errors.try(
+  primer.exchangeStudentForAccessToken(studentId)
 )
-if (result.error) {
-  // map ErrInvalidSecretKey / ErrStudentNotFound / ErrServerError etc.
-  throw result.error
+if (tokenResult.error) {
+  if (errors.is(tokenResult.error, ErrInvalidSecretKey)) {
+    throw new Error("Primer secret key is invalid")
+  }
+  if (errors.is(tokenResult.error, ErrStudentNotFound)) {
+    throw new Error("Stored Primer student id no longer exists on this frontend")
+  }
+  throw tokenResult.error
+}
+
+const { accessToken, expiresInSeconds } = tokenResult.data
+```
+
+### Live-authoritative Timeback flow
+
+```ts
+// ── your backend ─────────────────────────────────────────────────────
+import * as errors from "@superbuilders/errors"
+import {
+  createPrimerServer,
+  ErrConflict,
+  ErrInvalidSecretKey,
+  ErrStudentNotFound,
+  ErrTimebackUnavailable,
+  ErrUnsupportedGrade
+} from "@superbuilders/primer-tives/server"
+
+const primer = createPrimerServer({
+  origin: "https://sb-primer.vercel.app",
+  secretKey: process.env.PRIMER_CLIENT_SECRET_KEY_DEV!,
+  logger: console
+})
+
+const sessionResult = await errors.try(
+  primer.exchangeTimebackStudentForAccessToken("student-123")
+)
+if (sessionResult.error) {
+  if (errors.is(sessionResult.error, ErrInvalidSecretKey)) {
+    throw new Error("Primer secret key is invalid")
+  }
+  if (errors.is(sessionResult.error, ErrStudentNotFound)) {
+    throw new Error("Timeback sourcedId was not found upstream")
+  }
+  if (errors.is(sessionResult.error, ErrUnsupportedGrade)) {
+    throw new Error("Timeback returned a grade Primer does not support")
+  }
+  if (errors.is(sessionResult.error, ErrConflict)) {
+    throw new Error("This Primer frontend is not provisioned with routable content")
+  }
+  if (errors.is(sessionResult.error, ErrTimebackUnavailable)) {
+    throw new Error("Timeback is temporarily unavailable")
+  }
+  throw sessionResult.error
 }
-const { accessToken, expiresInSeconds } = result.data
-// ship `accessToken` to the browser
+
+const { studentId, accessToken, expiresInSeconds } = sessionResult.data
+// persist `studentId` if you want a stable Primer foreign key
+// use `accessToken` for this session only
 ```
 
+### Browser flow
+
 ```ts
 // ── your frontend ────────────────────────────────────────────────────
 import {
   create,
-  ErrRateLimited,
   type PrimerState
 } from "@superbuilders/primer-tives/client"
 
 const client = create({
-  accessToken,                            // from your backend
+  accessToken,
   origin: "https://sb-primer.vercel.app",
   subject: "math",
   supportedPcis: [
@@ -103,8 +200,19 @@ import {
   type PrimerServer,
   type PrimerServerConfig,
   type SessionToken,
-  type GradeLevel,
-  GRADE_LEVELS
+  type TimebackSession,
+  type PrimerLogger,
+  ErrBadRequest,
+  ErrConflict,
+  ErrExternalAuthorityRequired,
+  ErrInvalidSecretKey,
+  ErrJsonParse,
+  ErrNetwork,
+  ErrServerError,
+  ErrStudentNotFound,
+  ErrTimebackUnavailable,
+  ErrTimeout,
+  ErrUnsupportedGrade
 } from "@superbuilders/primer-tives/server"
 ```
 
@@ -112,100 +220,168 @@ import {
 
 ```ts
 interface PrimerServerConfig {
-  readonly origin: string                     // e.g. https://sb-primer.vercel.app (no trailing slash)
-  readonly secretKey: string                  // your sk_… key
-  readonly fetch?: typeof globalThis.fetch    // override (defaults to globalThis.fetch)
-  readonly abort?: AbortController            // wired into every request signal
-  readonly logger?: PrimerLogger              // optional structured logger
+  readonly origin: string                  // e.g. https://sb-primer.vercel.app (no trailing slash)
+  readonly secretKey: string               // your sk_… key
+  readonly fetch?: typeof globalThis.fetch // override (tests, proxies, instrumentation)
+  readonly abort?: AbortController         // wired into every request signal
+  readonly logger: PrimerLogger            // required debug/info/warn/error logger (console works)
 }
 
 function createPrimerServer(config: PrimerServerConfig): PrimerServer
 ```
 
-Returns a `PrimerServer` with four methods. Each method throws a sentinel-wrapped `Error` — use `errors.try()` from `@superbuilders/errors` at the call site.
-
-### `createNativeStudent(gradeLevel): Promise<string>`
-
-Provision a new Primer-owned student. Returns the `studentId` string — persist it in your own database keyed by your user. Call this **once per user**.
+Returns a `PrimerServer` with exactly **three** methods:
 
 ```ts
-const studentId = await primer.createNativeStudent("5")
+interface PrimerServer {
+  createStudent(): Promise<string>
+  exchangeStudentForAccessToken(studentId: string): Promise<SessionToken>
+  exchangeTimebackStudentForAccessToken(sourcedId: string): Promise<TimebackSession>
+}
 ```
 
-**Do not call this for Timeback integrations.** Timeback students are provisioned automatically on first `exchangeTimebackStudentForAccessToken`.
+## Method reference
+
+### `createStudent(): Promise<string>`
 
-### `updateNativeStudentGradeLevel(studentId, gradeLevel): Promise<void>`
+Provision a new **frontend-owned Primer student** and return its stable `studentId`.
 
-Change a Primer student's grade level.
+Use this only for the native/manual flow.
 
 ```ts
-await primer.updateNativeStudentGradeLevel(studentId, "6")
+const studentId = await primer.createStudent()
 ```
 
-**Do not call this for Timeback students.** Grade-level changes flow from the SIS.
+Notes:
 
-### `exchangeNativeStudentForAccessToken(studentId): Promise<SessionToken>`
+- Call this when your system is the source of truth for learner identity.
+- Persist the returned `studentId` in your own database.
+- Use that stored `studentId` with `exchangeStudentForAccessToken(studentId)` at each session start.
+- `logger` is required. Pass any object implementing `debug/info/warn/error`; `console` is acceptable for basic integrations.
 
-Mint a short-lived access token for an existing Primer-owned student. Call this **every session start**; tokens expire in 15 minutes by default.
+### `exchangeStudentForAccessToken(studentId): Promise<SessionToken>`
+
+Mint a short-lived access token for an existing **native/manual** Primer student.
 
 ```ts
-const { accessToken, expiresInSeconds } = await primer.exchangeNativeStudentForAccessToken(studentId)
+const { accessToken, expiresInSeconds } =
+  await primer.exchangeStudentForAccessToken(studentId)
 ```
 
-### `exchangeTimebackStudentForAccessToken(sourcedId): Promise<SessionToken>`
+Call this at **every session start**.
+
+Important:
+
+- This is for **native/manual** students only.
+- If `studentId` belongs to a Timeback-linked student, the method throws `ErrExternalAuthorityRequired`.
+- Tokens are short-lived (typically 15 minutes).
+
+### `exchangeTimebackStudentForAccessToken(sourcedId): Promise<TimebackSession>`
+
+Perform a **live-authoritative Timeback session start**.
 
-Mint a short-lived access token by OneRoster `sourcedId`. The server contacts the Timeback API to verify identity and grade, auto-provisions the Primer student row on first use, and returns the token. Subsequent exchanges for the same `sourcedId` reuse the existing row.
+Primer verifies the learner against Timeback on every call, then resolves or provisions the corresponding frontend-owned Primer student and returns:
+
+- the stable Primer `studentId`
+- a short-lived `accessToken`
+- `expiresInSeconds`
 
 ```ts
-const { accessToken, expiresInSeconds } = await primer.exchangeTimebackStudentForAccessToken(sourcedId)
+const { studentId, accessToken, expiresInSeconds } =
+  await primer.exchangeTimebackStudentForAccessToken(sourcedId)
 ```
 
-## `SessionToken`
+Use this at **every Timeback session start**.
+
+Operational rule:
+
+- Call this at every Timeback session start.
+- Persist `studentId` if you need a stable Primer foreign key in your own system.
+- Use the returned `accessToken` for the active browser session.
+
+## Return types
+
+### `SessionToken`
 
 ```ts
 interface SessionToken {
-  readonly accessToken: string          // HS256 JWS — pass to client SDK as Config.accessToken
-  readonly expiresInSeconds: number     // typically 900 (15 min)
+  readonly accessToken: string
+  readonly expiresInSeconds: number
 }
 ```
 
-Hand `accessToken` to your frontend over whatever channel you already use (cookie, HTML response, WebSocket, API response). The browser passes it to `create()`.
-
-## `GradeLevel`
+### `TimebackSession`
 
 ```ts
-type GradeLevel = "K" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12"
+interface TimebackSession {
+  readonly studentId: string
+  readonly accessToken: string
+  readonly expiresInSeconds: number
+}
 ```
 
-Exported as both `GradeLevel` and the `GRADE_LEVELS` readonly tuple.
-
 ## Error sentinels (`/server`)
 
+All `/server` methods throw sentinel-wrapped `Error`s. Use `errors.try()` and `errors.is()` from `@superbuilders/errors`.
+
 | Sentinel | Raised when |
 |---|---|
 | `ErrInvalidSecretKey` | HTTP 401 — missing, malformed, or unknown `sk_` |
-| `ErrStudentNotFound` | HTTP 404 — student doesn't exist (native) or sourced ID unknown (timeback) |
-| `ErrUnsupportedGrade` | HTTP 400 — Timeback user's grade is outside K–12 |
-| `ErrTimebackUnavailable` | HTTP 502 — Timeback OneRoster endpoint failed |
-| `ErrBadRequest` | HTTP 400 (non-grade) — validation failure |
+| `ErrStudentNotFound` | HTTP 404 — native `studentId` unknown on this frontend, or Timeback `sourcedId` unknown upstream |
+| `ErrUnsupportedGrade` | HTTP 400 — Timeback returned a grade outside Primer's supported range |
+| `ErrTimebackUnavailable` | HTTP 502 — Timeback OneRoster endpoint failed during live exchange |
+| `ErrExternalAuthorityRequired` | HTTP 409 — attempted native/manual exchange for a Timeback-linked student |
+| `ErrConflict` | HTTP 409 — frontend is not provisioned for routing/content |
+| `ErrBadRequest` | HTTP 400 — validation failure |
 | `ErrServerError` | HTTP 5xx |
-| `ErrJsonParse` | Success response body wasn't valid JSON |
-| `ErrNetwork` | fetch() rejected (DNS, connection, TLS) |
+| `ErrJsonParse` | Success response body was not valid JSON or had the wrong shape |
+| `ErrNetwork` | fetch() rejected (DNS, connection, TLS, etc.) |
 | `ErrTimeout` | fetch() aborted (your `AbortController` or `TimeoutError`) |
 
-All server methods follow the same pattern:
+### Recommended error-handling pattern
 
 ```ts
-const result = await errors.try(primer.createNativeStudent("5"))
+import * as errors from "@superbuilders/errors"
+import {
+  createPrimerServer,
+  ErrExternalAuthorityRequired,
+  ErrInvalidSecretKey,
+  ErrStudentNotFound
+} from "@superbuilders/primer-tives/server"
+
+const primer = createPrimerServer({
+  origin: "https://sb-primer.vercel.app",
+  secretKey: process.env.PRIMER_CLIENT_SECRET_KEY_DEV!,
+  logger: console
+})
+
+const result = await errors.try(
+  primer.exchangeStudentForAccessToken(studentId)
+)
 if (result.error) {
   if (errors.is(result.error, ErrInvalidSecretKey)) {
-    // rotate the sk_ and retry
+    // rotate or fix your sk_
+  }
+  if (errors.is(result.error, ErrStudentNotFound)) {
+    // your stored studentId is stale or wrong for this frontend
+  }
+  if (errors.is(result.error, ErrExternalAuthorityRequired)) {
+    // this student must authenticate through live Timeback exchange
   }
   throw result.error
 }
-const studentId = result.data
+
+const { accessToken } = result.data
 ```
 
+## Rules of the road
+
+- **Native/manual flow:** `createStudent()` once, then `exchangeStudentForAccessToken(studentId)` every session.
+- **Timeback flow:** `exchangeTimebackStudentForAccessToken(sourcedId)` every session.
+- **Student ids are stable identifiers, not browser credentials.** Always hand the browser a fresh `accessToken` from your backend.
+- **Server-only secrets.** Keep `secretKey` on your backend; never ship it to the browser.
+- **Explicit subpaths only.** Import from `/server` or `/client`, never a package root.
+
 ---
 
 # `/client`

package/dist/client/index.js

@@ -15,6 +15,7 @@ var ErrTimeout = errors.new("timeout");
 var ErrForbidden = errors.new("forbidden");
 var ErrNotFound = errors.new("not found");
 var ErrConflict = errors.new("conflict");
+var ErrExternalAuthorityRequired = errors.new("external authority required");
 var ErrRateLimited = errors.new("rate limited");
 var ErrServiceUnavailable = errors.new("service unavailable");
 var ErrNotSerializable = errors.new("PrimerState is live in-memory state and must not be serialized or stored");
@@ -735,11 +736,9 @@ function isRetriableError(err) {
 }
 function makeSession(sc) {
   const log = sc.log;
-  let currentFrameContext = null;
   function resolve(result) {
     switch (result.outcome) {
       case "advanced":
-        currentFrameContext = result.frameContext;
         return fromAdvanced(result.stimulus, result.interaction);
       case "submitted":
         return feedbackState(ctx, result.stimulus, result.interaction, result.submission, result.isCorrect, result.feedbackContent, result.review);
@@ -771,32 +770,11 @@ function makeSession(sc) {
     return state;
   }
   async function execute(intent, phase) {
-    let body;
-    if (intent.kind === "observation") {
-      body = {
-        supportedPcis: sc.supportedPcis,
-        intent,
-        subject: sc.subject
-      };
-    } else {
-      if (currentFrameContext === null) {
-        log?.error("missing frame context for non-observation intent", {
-          phase,
-          intentKind: intent.kind
-        });
-        return {
-          phase: "fatal",
-          error: ErrBadRequest,
-          retriable: false,
-          toJSON: poisonToJSON
-        };
-      }
-      body = {
-        supportedPcis: sc.supportedPcis,
-        intent: { ...intent, frameContext: currentFrameContext },
-        subject: sc.subject
-      };
-    }
+    const body = {
+      supportedPcis: sc.supportedPcis,
+      intent,
+      subject: sc.subject
+    };
     const result = await sc.transport(body);
     if (!result.ok) {
       if (isFatalError(result.error)) {
@@ -946,4 +924,4 @@ export {
   ErrBadRequest
 };
 
-//# debugId=77F88432A1CED38764756E2164756E21
+//# debugId=03C66069BFA6BE2F64756E2164756E21