@superbuilders/primer-tives 0.9.0 → 1.0.0

package/dist/server/create-server.d.ts

@@ -1,40 +1,42 @@
-import type { GradeLevel } from "../grade-level";
 import type { PrimerLogger } from "../logger";
-import { type SessionToken } from "./exchange";
+import { type SessionToken, type TimebackSession } from "./exchange";
+import { type PlacementHints, type PlacementHintsResult } from "./hints";
 interface PrimerServerConfig {
     readonly origin: string;
     readonly secretKey: string;
     readonly fetch?: typeof globalThis.fetch;
     readonly abort?: AbortController;
-    readonly logger?: PrimerLogger;
+    readonly logger: PrimerLogger;
 }
 interface PrimerServer {
     /**
-     * Native only: provision a new Primer-owned student. Returns a stable
-     * studentId string you persist in your own DB keyed by your user. Pair
-     * this value with `exchangeNativeStudentForAccessToken` on every
-     * session start. Timeback integrations do NOT call this — they
-     * provision automatically on exchange.
+     * Provisions a frontend-owned Primer student and returns the stable
+     * student id you persist in your own DB keyed by your user. Native
+     * students are created hint-less; call `setStudentHints` at least
+     * once (with a `gradeLevel`) before the student's first session, or
+     * the first `/advance` call will 500.
      */
-    createNativeStudent(gradeLevel: GradeLevel): Promise<string>;
+    createStudent(): Promise<string>;
     /**
-     * Native only: update an existing Primer student's grade level. For
-     * Timeback, grade changes flow from the SIS — do not call this.
+     * Partial update of a student's placement-routing hints. Pass only
+     * the fields you want to set; omitted fields are left untouched.
+     * Returns the persisted state after upsert. Today the only hint is
+     * `gradeLevel`; future hint kinds (raw context, interests, etc.)
+     * will appear as additional optional fields.
      */
-    updateNativeStudentGradeLevel(studentId: string, gradeLevel: GradeLevel): Promise<void>;
+    setStudentHints(studentId: string, hints: PlacementHints): Promise<PlacementHintsResult>;
     /**
-     * Native only: exchange a Primer-minted studentId for a short-lived
+     * Exchanges a frontend-owned native/manual student id for a short-lived
      * access token. Pass `accessToken` from the returned `SessionToken` to
      * `create()` on the browser SDK.
      */
-    exchangeNativeStudentForAccessToken(studentId: string): Promise<SessionToken>;
+    exchangeStudentForAccessToken(studentId: string): Promise<SessionToken>;
     /**
-     * Timeback only: exchange a OneRoster sourcedId for a short-lived
-     * access token. The underlying Primer student is auto-provisioned on
-     * first exchange. Pass `accessToken` from the returned `SessionToken`
-     * to `create()` on the browser SDK.
+     * Verifies the learner against live Timeback authority, resolves or
+     * provisions the corresponding frontend-owned Primer student, and
+     * returns both the stable student id and a short-lived access token.
      */
-    exchangeTimebackStudentForAccessToken(sourcedId: string): Promise<SessionToken>;
+    exchangeTimebackStudentForAccessToken(sourcedId: string): Promise<TimebackSession>;
 }
 declare function createPrimerServer(config: PrimerServerConfig): PrimerServer;
 export type { PrimerServer, PrimerServerConfig };

package/dist/server/create-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-server.d.ts","sourceRoot":"","sources":["../../src/server/create-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAA;AACzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AACtE,OAAO,EAAE,KAAK,YAAY,EAAiB,MAAM,6CAA6C,CAAA;AAG9F,UAAU,kBAAkB;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAC9B;AAED,UAAU,YAAY;IACrB;;;;;;OAMG;IACH,mBAAmB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE5D;;;OAGG;IACH,6BAA6B,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEvF;;;;OAIG;IACH,mCAAmC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAE7E;;;;;OAKG;IACH,qCAAqC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;CAC/E;AAED,iBAAS,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAepE;AAED,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,CAAA"}
+{"version":3,"file":"create-server.d.ts","sourceRoot":"","sources":["../../src/server/create-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AACtE,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,eAAe,EAGpB,MAAM,6CAA6C,CAAA;AACpD,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,oBAAoB,EAEzB,MAAM,0CAA0C,CAAA;AAGjD,UAAU,kBAAkB;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAC7B;AAED,UAAU,YAAY;IACrB;;;;;;OAMG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAEhC;;;;;;OAMG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAExF;;;;OAIG;IACH,6BAA6B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAA;IAEvE;;;;OAIG;IACH,qCAAqC,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAClF;AAED,iBAAS,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,YAAY,CAepE;AAED,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,CAAA"}

package/dist/server/exchange.d.ts

@@ -1,17 +1,22 @@
 import type { PrimerLogger } from "../logger";
-type Provider = "native" | "timeback";
 interface ExchangeConfig {
     readonly origin: string;
     readonly secretKey: string;
     readonly fetch?: typeof globalThis.fetch;
     readonly abort?: AbortController;
-    readonly logger?: PrimerLogger;
+    readonly logger: PrimerLogger;
 }
 interface SessionToken {
     readonly accessToken: string;
     readonly expiresInSeconds: number;
 }
-declare function exchangeToken(config: ExchangeConfig, provider: Provider, studentId: string): Promise<SessionToken>;
-export type { ExchangeConfig, SessionToken };
-export { exchangeToken };
+interface TimebackSession {
+    readonly studentId: string;
+    readonly accessToken: string;
+    readonly expiresInSeconds: number;
+}
+declare function exchangeStudent(config: ExchangeConfig, studentId: string): Promise<SessionToken>;
+declare function exchangeTimebackStudent(config: ExchangeConfig, sourcedId: string): Promise<TimebackSession>;
+export type { ExchangeConfig, SessionToken, TimebackSession };
+export { exchangeStudent, exchangeTimebackStudent };
 //# sourceMappingURL=exchange.d.ts.map

package/dist/server/exchange.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exchange.d.ts","sourceRoot":"","sources":["../../src/server/exchange.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAItE,KAAK,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAA;AAErC,UAAU,cAAc;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;CAC9B;AAED,UAAU,YAAY;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CACjC;AAgED,iBAAe,aAAa,CAC3B,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,CAAC,CAoEvB;AAED,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,CAAA"}
+{"version":3,"file":"exchange.d.ts","sourceRoot":"","sources":["../../src/server/exchange.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAKtE,UAAU,cAAc;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAC7B;AAED,UAAU,YAAY;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CACjC;AAED,UAAU,eAAe;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CACjC;AA8OD,iBAAe,eAAe,CAAC,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAmB/F;AAED,iBAAe,uBAAuB,CACrC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC,CAmB1B;AAED,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,CAAA;AAC7D,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,CAAA"}

package/dist/server/hints.d.ts

@@ -0,0 +1,25 @@
+import { type GradeLevel } from "../grade-level";
+import type { PrimerLogger } from "../logger";
+interface HintsConfig {
+    readonly origin: string;
+    readonly secretKey: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly abort?: AbortController;
+    readonly logger: PrimerLogger;
+}
+/**
+ * Partial update of a student's placement hints. Pass only the fields
+ * you want to set; omitted fields are left untouched. The server
+ * returns the persisted state after upsert.
+ */
+interface PlacementHints {
+    readonly gradeLevel?: GradeLevel;
+}
+interface PlacementHintsResult {
+    readonly studentId: string;
+    readonly gradeLevel: GradeLevel | null;
+}
+declare function setStudentHints(config: HintsConfig, studentId: string, hints: PlacementHints): Promise<PlacementHintsResult>;
+export type { HintsConfig, PlacementHints, PlacementHintsResult };
+export { setStudentHints };
+//# sourceMappingURL=hints.d.ts.map

package/dist/server/hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hints.d.ts","sourceRoot":"","sources":["../../src/server/hints.ts"],"names":[],"mappings":"AAUA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,yCAAyC,CAAA;AACvF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAItE,UAAU,WAAW;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAA;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;CAC7B;AAED;;;;GAIG;AACH,UAAU,cAAc;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CAChC;AAED,UAAU,oBAAoB;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAA;CACtC;AAwKD,iBAAe,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,cAAc,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAkB/B;AAED,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,oBAAoB,EAAE,CAAA;AACjE,OAAO,EAAE,eAAe,EAAE,CAAA"}

package/dist/server/index.d.ts

@@ -1,8 +1,9 @@
 export { createPrimerServer } from "./create-server";
 export type { PrimerServer, PrimerServerConfig } from "./create-server";
-export type { SessionToken } from "./exchange";
-export type { PrimerLogger } from "../logger";
+export type { SessionToken, TimebackSession } from "./exchange";
+export type { PlacementHints, PlacementHintsResult } from "./hints";
 export type { GradeLevel } from "../grade-level";
 export { GRADE_LEVELS } from "../grade-level";
-export { ErrBadRequest, ErrInvalidSecretKey, ErrJsonParse, ErrNetwork, ErrServerError, ErrStudentNotFound, ErrTimebackUnavailable, ErrTimeout, ErrUnsupportedGrade } from "../errors";
+export type { PrimerLogger } from "../logger";
+export { ErrBadRequest, ErrConflict, ErrExternalAuthorityRequired, ErrInvalidSecretKey, ErrJsonParse, ErrNetwork, ErrServerError, ErrStudentNotFound, ErrTimebackUnavailable, ErrTimeout, ErrUnsupportedGrade } from "../errors";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAA;AACrF,YAAY,EACX,YAAY,EACZ,kBAAkB,EAClB,MAAM,kDAAkD,CAAA;AAEzD,YAAY,EAAE,YAAY,EAAE,MAAM,6CAA6C,CAAA;AAE/E,YAAY,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AACtE,YAAY,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAA;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAA;AAEtE,OAAO,EACN,aAAa,EACb,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,UAAU,EACV,mBAAmB,EACnB,MAAM,oCAAoC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAA;AACrF,YAAY,EACX,YAAY,EACZ,kBAAkB,EAClB,MAAM,kDAAkD,CAAA;AAEzD,YAAY,EACX,YAAY,EACZ,eAAe,EACf,MAAM,6CAA6C,CAAA;AACpD,YAAY,EACX,cAAc,EACd,oBAAoB,EACpB,MAAM,0CAA0C,CAAA;AACjD,YAAY,EAAE,UAAU,EAAE,MAAM,yCAAyC,CAAA;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAA;AACtE,YAAY,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AAEtE,OAAO,EACN,aAAa,EACb,WAAW,EACX,4BAA4B,EAC5B,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,UAAU,EACV,mBAAmB,EACnB,MAAM,oCAAoC,CAAA"}