@superbuilders/primer-tives 1.1.2 → 1.1.3

package/README.md

@@ -2,13 +2,6 @@
 
 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
 ```
@@ -17,10 +10,15 @@ Dependency note: `@superbuilders/errors` is installed automatically and is used
 
 ## Entrypoints
 
-| Import | Runs on | Wraps |
+| Import | Runs on | Use for |
 |---|---|---|
 | `@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` |
+| `@superbuilders/primer-tives/contracts` | either side | shared interaction/submission types, Zod schemas, optional submission validator |
+| `@superbuilders/primer-tives/errors` | either side | every error sentinel |
+| `@superbuilders/primer-tives` (root) | either side | convenience re-export of `/contracts` + `/errors` |
+
+`/server` and `/client` are not on the root — pick the side of the wire you are on and import from its subpath. `/contracts` and `/errors` are wire-neutral and safe on either side.
 
 ## Supported student flows
 
@@ -703,3 +701,71 @@ Same shape on both sides. Plug in your slog/pino/console adapter.
 - **Session resumption.** A returning student resumes wherever the server last placed them. No client-side cursor management.
 - **Live state.** `PrimerState` holds real closures (action methods, pending-promise caches). Don't serialize it; don't store it across reloads. Call `start()` again on boot.
 - **PCI type safety.** `Config.supportedPcis` is a `const` generic; only those URNs flow through `PciInteractionState`/`PciSubmission` at the type level. Mismatch at runtime is a `fatal` with `ErrUnsupportedPci`.
+
+---
+
+# `/contracts`
+
+Wire-shape types, Zod schemas, and an optional submission validator. Safe to import from either side of the wire.
+
+```ts
+import {
+  // schemas
+  ChoiceSubmissionSchema,
+  TextEntrySubmissionSchema,
+  ExtendedTextSubmissionSchema,
+  OrderSubmissionSchema,
+  MatchSubmissionSchema,
+  MatchPairSchema,
+  DivisionRemainderPciSubmissionSchema,
+  FractionAdditionPciSubmissionSchema,
+  RendererSubmissionSchema,
+  // validator
+  validateSubmissionForInteraction,
+  submissionValidationMessage,
+  // types
+  type RendererInteraction,
+  type RendererSubmission,
+  type StandardRendererInteraction,
+  type PciInteraction,
+  type PciSubmission,
+  type BodyStimulus,
+  type ImageStimulus,
+  type MatchPair,
+  type RendererChoice,
+  type RendererMatchChoice,
+  type RendererStimulus,
+  type SubmissionValidationResult,
+  type SubmissionValidationSuccess,
+  type SubmissionValidationFailure
+} from "@superbuilders/primer-tives/contracts"
+```
+
+## Schemas
+
+Every `RendererSubmission` variant has a Zod schema; `RendererSubmissionSchema` is the discriminated union over all of them and is the canonical `safeParse`-able wire shape.
+
+```ts
+const result = RendererSubmissionSchema.safeParse(unknownPayload)
+if (!result.success) { /* … */ }
+const submission = result.data    // typed as RendererSubmission
+```
+
+## `validateSubmissionForInteraction(interaction, submission)`
+
+Optional semantic validator. Checks a submission against the interaction it claims to answer (cardinality bounds, identifier membership, duplicate rules, PCI payload shape).
+
+```ts
+function validateSubmissionForInteraction(
+  interaction: RendererInteraction,
+  submission: RendererSubmission
+): SubmissionValidationResult
+
+type SubmissionValidationResult =
+  | { ok: true;  value: RendererSubmission }
+  | { ok: false; issues: readonly string[] }
+```
+
+`submissionValidationMessage(failure)` joins `failure.issues` with `"; "` for cases where you want a single string.
+
+Validation is **optional at every layer.** The Primer server grades submissions independently and is the only correctness boundary that matters. The browser SDK's built-in interaction state machines call this validator on your behalf before each submit; if you bypass those state machines and write to the wire yourself, you decide whether to validate.

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

@@ -0,0 +1,8 @@
+import type { SessionContext } from "./session-context";
+import type { PciId } from "./pci";
+import type { PrimerState, RendererChoice, RendererInteraction, RendererStimulus } from "./types";
+declare function choiceState<Pcis extends PciId>(ctx: SessionContext<Pcis>, stimulus: RendererStimulus | null, interaction: Extract<RendererInteraction<Pcis>, {
+    type: "choice";
+}>, options: RendererChoice[], maxChoices: number, minChoices: number): PrimerState<Pcis>;
+export { choiceState };
+//# sourceMappingURL=choice-state.d.ts.map

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

@@ -0,0 +1 @@
+{"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/consumed.d.ts

@@ -0,0 +1,3 @@
+declare function poisonToJSON(): never;
+export { poisonToJSON };
+//# sourceMappingURL=consumed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"consumed.d.ts","sourceRoot":"","sources":["../../src/client/consumed.ts"],"names":[],"mappings":"AAEA,iBAAS,YAAY,IAAI,KAAK,CAG7B;AAED,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/client/content.d.ts

@@ -0,0 +1,20 @@
+type ContentSpan = {
+    type: "text";
+    value: string;
+} | {
+    type: "italic";
+    value: string;
+};
+type ContentInline = ContentSpan | {
+    type: "latex";
+    value: string;
+};
+type ContentBlock = {
+    type: "paragraph";
+    children: ContentInline[];
+};
+declare function inlinesToPlainText(nodes: ContentInline[]): string;
+declare function blocksToPlainText(blocks: ContentBlock[]): string;
+export type { ContentBlock, ContentInline, ContentSpan };
+export { blocksToPlainText, inlinesToPlainText };
+//# sourceMappingURL=content.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/client/content.ts"],"names":[],"mappings":"AAAA,KAAK,WAAW,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtF,KAAK,aAAa,GAAG,WAAW,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEnE,KAAK,YAAY,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,aAAa,EAAE,CAAA;CAAE,CAAA;AAEpE,iBAAS,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,MAAM,CAgB1D;AAED,iBAAS,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,CAMzD;AAED,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,CAAA"}

package/dist/client/create.d.ts

@@ -0,0 +1,20 @@
+import type { PrimerLogger } from "../logger";
+import type { PciId } from "./pci";
+import type { SubjectScope } from "../subject";
+import type { PrimerState } from "./types";
+interface Config<Pcis extends PciId = PciId> {
+    readonly accessToken: string;
+    readonly supportedPcis: readonly Pcis[];
+    readonly origin: string;
+    readonly subject: SubjectScope;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly abort?: AbortController;
+    readonly logger?: PrimerLogger;
+}
+interface Client<Pcis extends PciId = PciId> {
+    start(): Promise<PrimerState<Pcis>>;
+}
+declare function create<const Pcis extends PciId>(config: Config<Pcis>): Client<Pcis>;
+export { create };
+export type { Client, Config };
+//# sourceMappingURL=create.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/client/create.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAA;AACtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wCAAwC,CAAA;AACnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0CAA0C,CAAA;AAM3E,UAAU,MAAM,CAAC,IAAI,SAAS,KAAK,GAAG,KAAK;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,aAAa,EAAE,SAAS,IAAI,EAAE,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,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,MAAM,CAAC,IAAI,SAAS,KAAK,GAAG,KAAK;IAC1C,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAA;CACnC;AAUD,iBAAS,MAAM,CAAC,KAAK,CAAC,IAAI,SAAS,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CA4C5E;AAED,OAAO,EAAE,MAAM,EAAE,CAAA;AACjB,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,CAAA"}

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

@@ -0,0 +1,8 @@
+import type { SessionContext } from "./session-context";
+import type { PciId } from "./pci";
+import type { PrimerState, RendererStimulus, StandardRendererInteraction } from "./types";
+declare function extendedTextState<Pcis extends PciId>(ctx: SessionContext<Pcis>, stimulus: RendererStimulus | null, interaction: Extract<StandardRendererInteraction, {
+    type: "extended-text";
+}>): PrimerState<Pcis>;
+export { extendedTextState };
+//# sourceMappingURL=extended-text-state.d.ts.map

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

@@ -0,0 +1 @@
+{"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/feedback-state.d.ts

@@ -0,0 +1,7 @@
+import type { ContentInline } from "./content";
+import type { SessionContext } from "./session-context";
+import type { PciId } from "./pci";
+import type { InteractionReview, PrimerState, RendererInteraction, RendererStimulus, RendererSubmission } from "./types";
+declare function feedbackState<Pcis extends PciId>(ctx: SessionContext<Pcis>, stimulus: RendererStimulus | null, interaction: RendererInteraction<Pcis>, submission: RendererSubmission<Pcis>, isCorrect: boolean, feedbackContent: ContentInline[], review: InteractionReview<Pcis> | null): PrimerState<Pcis>;
+export { feedbackState };
+//# sourceMappingURL=feedback-state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feedback-state.d.ts","sourceRoot":"","sources":["../../src/client/feedback-state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4CAA4C,CAAA;AAC/E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oDAAoD,CAAA;AACxF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wCAAwC,CAAA;AACnE,OAAO,KAAK,EACX,iBAAiB,EACjB,WAAW,EACX,mBAAmB,EACnB,gBAAgB,EAChB,kBAAkB,EAClB,MAAM,0CAA0C,CAAA;AAEjD,iBAAS,aAAa,CAAC,IAAI,SAAS,KAAK,EACxC,GAAG,EAAE,cAAc,CAAC,IAAI,CAAC,EACzB,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,WAAW,EAAE,mBAAmB,CAAC,IAAI,CAAC,EACtC,UAAU,EAAE,kBAAkB,CAAC,IAAI,CAAC,EACpC,SAAS,EAAE,OAAO,EAClB,eAAe,EAAE,aAAa,EAAE,EAChC,MAAM,EAAE,iBAAiB,CAAC,IAAI,CAAC,GAAG,IAAI,GACpC,WAAW,CAAC,IAAI,CAAC,CAmBnB;AAED,OAAO,EAAE,aAAa,EAAE,CAAA"}

package/dist/client/index.d.ts

@@ -0,0 +1,11 @@
+export { create } from "./create";
+export type { Client, Config } from "./create";
+export type { PrimerLogger } from "../logger";
+export { SUBJECTS } from "../subject";
+export type { Subject, SubjectScope } from "../subject";
+export { ErrBadRequest, ErrConflict, ErrForbidden, ErrInvalidAccessToken, ErrInvalidSubmission, ErrJsonParse, ErrMalformedAccessToken, ErrNetwork, ErrNotFound, ErrNotSerializable, ErrRateLimited, ErrServerError, ErrServiceUnavailable, ErrTimeout, ErrTokenExpired, ErrUnsupportedPci } from "../errors";
+export type { BodyStimulus, ChoiceReview, ChoiceState, CompletedState, ErroredState, ExtendedTextMultipleState, ExtendedTextReview, ExtendedTextSingleState, ExtendedTextState, FatalState, FeedbackState, ImageStimulus, InteractionReview, InteractionState, MatchPair, MatchReview, MatchState, NonSerializable, ObservationState, OrderReview, OrderState, PciInteraction, PciInteractionState, PciPendingRenderProps, PciRenderProps, PciReview, PciSubmission, PciSubmittedRenderProps, PrimerState, RendererChoice, RendererInteraction, RendererMatchChoice, RendererStimulus, RendererSubmission, ReviewRecordField, ReviewRecordFieldBaseType, ReviewScalarValue, StandardRendererInteraction, TextEntryReview, TextEntryState } from "./types";
+export type { ContentBlock, ContentInline, ContentSpan } from "./content";
+export { blocksToPlainText, inlinesToPlainText } from "./content";
+export type { DivisionRemainderProps, DivisionRemainderSubmission, FractionAdditionProps, FractionAdditionSubmission, PciId, PciProps, PciRegistry, PciUrn, PciValue } from "./pci";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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;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"}