@superbuilders/primer-tives 1.0.0 → 1.1.0

package/README.md

@@ -19,7 +19,7 @@ Dependency note: `@superbuilders/errors` is installed automatically and is used
 
 | Import | Runs on | Wraps |
 |---|---|---|
-| `@superbuilders/primer-tives/server` | your backend | `POST /api/v0/students`, `POST /api/v0/auth/exchange`, `POST /api/v0/auth/exchange/timeback` |
+| `@superbuilders/primer-tives/server` | your backend | `POST /api/v0/students`, `PATCH /api/v0/students/:id/hints`, `POST /api/v0/auth/exchange`, `POST /api/v0/auth/exchange/timeback` |
 | `@superbuilders/primer-tives/client` | the browser | `POST /api/v0/advance` |
 
 ## Supported student flows
@@ -32,8 +32,9 @@ 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.
+3. **Before the student's first session**, call `setStudentHints(studentId, { gradeLevel })` at least once. Native students are created hint-less, and the first `/advance` call fails without a `gradeLevel` on record.
+4. At each session start, call `exchangeStudentForAccessToken(studentId)`.
+5. Hand the returned `accessToken` to the browser SDK.
 
 ### 2. Live-authoritative Timeback students
 
@@ -56,6 +57,7 @@ Persisting the returned `studentId` is fine if you want a stable local foreign k
 import * as errors from "@superbuilders/errors"
 import {
   createPrimerServer,
+  ErrBadRequest,
   ErrConflict,
   ErrInvalidSecretKey,
   ErrStudentNotFound
@@ -63,7 +65,7 @@ import {
 
 const primer = createPrimerServer({
   origin: "https://sb-primer.vercel.app",
-  secretKey: process.env.PRIMER_CLIENT_SECRET_KEY_DEV!,
+  secretKey: process.env.PRIMER_DEMO_SECRET_KEY!,
   logger: console
 })
 
@@ -81,6 +83,20 @@ if (createResult.error) {
 const studentId = createResult.data
 // persist `studentId` alongside your own user record
 
+// Required before the first session for native students.
+const hintsResult = await errors.try(
+  primer.setStudentHints(studentId, { gradeLevel: "3" })
+)
+if (hintsResult.error) {
+  if (errors.is(hintsResult.error, ErrStudentNotFound)) {
+    throw new Error("Stored Primer student id no longer exists on this frontend")
+  }
+  if (errors.is(hintsResult.error, ErrBadRequest)) {
+    throw new Error("Invalid hint payload (e.g. unsupported gradeLevel)")
+  }
+  throw hintsResult.error
+}
+
 // Every session start.
 const tokenResult = await errors.try(
   primer.exchangeStudentForAccessToken(studentId)
@@ -114,7 +130,7 @@ import {
 
 const primer = createPrimerServer({
   origin: "https://sb-primer.vercel.app",
-  secretKey: process.env.PRIMER_CLIENT_SECRET_KEY_DEV!,
+  secretKey: process.env.PRIMER_DEMO_SECRET_KEY!,
   logger: console
 })
 
@@ -201,6 +217,10 @@ import {
   type PrimerServerConfig,
   type SessionToken,
   type TimebackSession,
+  type PlacementHints,
+  type PlacementHintsResult,
+  type GradeLevel,
+  GRADE_LEVELS,
   type PrimerLogger,
   ErrBadRequest,
   ErrConflict,
@@ -230,11 +250,12 @@ interface PrimerServerConfig {
 function createPrimerServer(config: PrimerServerConfig): PrimerServer
 ```
 
-Returns a `PrimerServer` with exactly **three** methods:
+Returns a `PrimerServer` with exactly **four** methods:
 
 ```ts
 interface PrimerServer {
   createStudent(): Promise<string>
+  setStudentHints(studentId: string, hints: PlacementHints): Promise<PlacementHintsResult>
   exchangeStudentForAccessToken(studentId: string): Promise<SessionToken>
   exchangeTimebackStudentForAccessToken(sourcedId: string): Promise<TimebackSession>
 }
@@ -256,9 +277,26 @@ Notes:
 
 - Call this when your system is the source of truth for learner identity.
 - Persist the returned `studentId` in your own database.
+- **Before the first session**, call `setStudentHints(studentId, { gradeLevel })`. Native students are created without a `gradeLevel`, and `/advance` requires one.
 - 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.
 
+### `setStudentHints(studentId, hints): Promise<PlacementHintsResult>`
+
+Partial upsert of a native/manual student's placement-routing hints. Omitted fields are left untouched; the server returns the persisted state after upsert.
+
+```ts
+const { gradeLevel } = await primer.setStudentHints(studentId, {
+  gradeLevel: "3"
+})
+```
+
+- **Required** for native/manual students before their first session. Without a `gradeLevel` on record, the first `/advance` call fails server-side.
+- `gradeLevel` is the only hint today; future hint kinds (raw context, interests, etc.) will appear as additional optional fields on `PlacementHints`.
+- Safe to call repeatedly — each call is a partial upsert.
+- Not needed for Timeback-linked students: `exchangeTimebackStudentForAccessToken` syncs the grade level from the authority on every call.
+- Throws `ErrStudentNotFound` if `studentId` is unknown; `ErrBadRequest` if the payload fails validation (e.g., unsupported `gradeLevel`).
+
 ### `exchangeStudentForAccessToken(studentId): Promise<SessionToken>`
 
 Mint a short-lived access token for an existing **native/manual** Primer student.
@@ -320,6 +358,27 @@ interface TimebackSession {
 }
 ```
 
+### `PlacementHints`
+
+```ts
+interface PlacementHints {
+  readonly gradeLevel?: GradeLevel
+}
+```
+
+Partial shape: pass only the fields you want to set. Today the only hint is `gradeLevel` (the learner's current grade). Re-export `GRADE_LEVELS` enumerates the supported values.
+
+### `PlacementHintsResult`
+
+```ts
+interface PlacementHintsResult {
+  readonly studentId: string
+  readonly gradeLevel: GradeLevel | null
+}
+```
+
+The persisted state after upsert. `gradeLevel` is `null` only on native students who have never had one set.
+
 ## Error sentinels (`/server`)
 
 All `/server` methods throw sentinel-wrapped `Error`s. Use `errors.try()` and `errors.is()` from `@superbuilders/errors`.
@@ -351,7 +410,7 @@ import {
 
 const primer = createPrimerServer({
   origin: "https://sb-primer.vercel.app",
-  secretKey: process.env.PRIMER_CLIENT_SECRET_KEY_DEV!,
+  secretKey: process.env.PRIMER_DEMO_SECRET_KEY!,
   logger: console
 })
 

package/dist/client/choice-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"choice-state.d.ts","sourceRoot":"","sources":["../../src/client/choice-state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wCAAwC,CAAA;AACnE,OAAO,KAAK,EACX,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,MAAM,0CAA0C,CAAA;AA6CjD,iBAAS,WAAW,CAAC,IAAI,SAAS,KAAK,EACtC,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,EACnE,OAAO,EAAE,cAAc,EAAE,EACzB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GAChB,WAAW,CAAC,IAAI,CAAC,CAsFnB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}
+{"version":3,"file":"choice-state.d.ts","sourceRoot":"","sources":["../../src/client/choice-state.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wCAAwC,CAAA;AACnE,OAAO,KAAK,EACX,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,MAAM,0CAA0C,CAAA;AAGjD,iBAAS,WAAW,CAAC,IAAI,SAAS,KAAK,EACtC,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,EACnE,OAAO,EAAE,cAAc,EAAE,EACzB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GAChB,WAAW,CAAC,IAAI,CAAC,CAqFnB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}

package/dist/client/extended-text-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extended-text-state.d.ts","sourceRoot":"","sources":["../../src/client/extended-text-state.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wCAAwC,CAAA;AACnE,OAAO,KAAK,EACX,WAAW,EACX,gBAAgB,EAChB,2BAA2B,EAC3B,MAAM,0CAA0C,CAAA;AAoBjD,iBAAS,iBAAiB,CAAC,IAAI,SAAS,KAAK,EAC5C,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,OAAO,CAAC,2BAA2B,EAAE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,GAC1E,WAAW,CAAC,IAAI,CAAC,CA0JnB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}
+{"version":3,"file":"extended-text-state.d.ts","sourceRoot":"","sources":["../../src/client/extended-text-state.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wCAAwC,CAAA;AACnE,OAAO,KAAK,EACX,WAAW,EACX,gBAAgB,EAChB,2BAA2B,EAC3B,MAAM,0CAA0C,CAAA;AAGjD,iBAAS,iBAAiB,CAAC,IAAI,SAAS,KAAK,EAC5C,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,OAAO,CAAC,2BAA2B,EAAE;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC,GAC1E,WAAW,CAAC,IAAI,CAAC,CAqKnB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAClE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAE/E,YAAY,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAEtE,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAA;AAC9D,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AAEhF,OAAO,EACN,aAAa,EACb,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,MAAM,oCAAoC,CAAA;AAE3C,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,cAAc,EACd,YAAY,EACZ,yBAAyB,EACzB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,aAAa,EACb,uBAAuB,EACvB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,2BAA2B,EAC3B,eAAe,EACf,cAAc,EACd,MAAM,0CAA0C,CAAA;AAEjD,YAAY,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,MAAM,4CAA4C,CAAA;AACnD,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,MAAM,4CAA4C,CAAA;AAEnD,YAAY,EACX,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,0BAA0B,EAC1B,KAAK,EACL,QAAQ,EACR,WAAW,EACX,MAAM,EACN,QAAQ,EACR,MAAM,wCAAwC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAClE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAA;AAE/E,YAAY,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAEtE,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAA;AAC9D,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AAEhF,OAAO,EACN,aAAa,EACb,WAAW,EACX,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,MAAM,oCAAoC,CAAA;AAE3C,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,cAAc,EACd,YAAY,EACZ,yBAAyB,EACzB,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,UAAU,EACV,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,WAAW,EACX,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,cAAc,EACd,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,aAAa,EACb,uBAAuB,EACvB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,yBAAyB,EACzB,iBAAiB,EACjB,2BAA2B,EAC3B,eAAe,EACf,cAAc,EACd,MAAM,0CAA0C,CAAA;AAEjD,YAAY,EACX,YAAY,EACZ,aAAa,EACb,WAAW,EACX,MAAM,4CAA4C,CAAA;AAEnD,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,MAAM,4CAA4C,CAAA;AAEnD,YAAY,EACX,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,0BAA0B,EAC1B,KAAK,EACL,QAAQ,EACR,WAAW,EACX,MAAM,EACN,QAAQ,EACR,MAAM,wCAAwC,CAAA"}