@superbuilders/primer-tives 1.1.4 → 2.0.0

package/dist/client/index.js

@@ -21,6 +21,8 @@ var ErrInvalidSecretKey = errors.new("invalid secret key");
 var ErrStudentNotFound = errors.new("student not found");
 var ErrUnsupportedGrade = errors.new("unsupported grade");
 var ErrTimebackUnavailable = errors.new("timeback unavailable");
+var ErrNeedsHints = errors.new("student needs hints set before /advance");
+var ErrSdkUpgradeRequired = errors.new("sdk upgrade required");
 // src/contracts/content.ts
 function inlinesToPlainText(nodes) {
   const parts = [];
@@ -335,18 +337,22 @@ import * as errors10 from "@superbuilders/errors";
 
 // src/client/transport.ts
 import * as errors2 from "@superbuilders/errors";
+
+// src/version.ts
+var SDK_VERSION = "2.0.0";
+var NPM_PACKAGE_URL = "https://www.npmjs.com/package/@superbuilders/primer-tives";
+
+// src/client/transport.ts
 var ADVANCE_PATH = "/api/v0/advance";
-function isAdvanceErrorBody(value) {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-  if ("error" in value && value.error !== undefined && typeof value.error !== "string") {
-    return false;
+function readStringField(value, key) {
+  if (!(key in value)) {
+    return;
   }
-  if ("detail" in value && value.detail !== undefined && typeof value.detail !== "string") {
-    return false;
+  const v = Reflect.get(value, key);
+  if (typeof v !== "string") {
+    return;
   }
-  return true;
+  return v;
 }
 function parseAdvanceErrorBody(body) {
   if (body.length === 0) {
@@ -358,13 +364,39 @@ function parseAdvanceErrorBody(body) {
   if (parsed.error) {
     return null;
   }
-  if (!isAdvanceErrorBody(parsed.data)) {
+  const raw = parsed.data;
+  if (typeof raw !== "object" || raw === null) {
     return null;
   }
-  return parsed.data;
+  const result = {};
+  const error = readStringField(raw, "error");
+  if (error !== undefined) {
+    result.error = error;
+  }
+  const detail = readStringField(raw, "detail");
+  if (detail !== undefined) {
+    result.detail = detail;
+  }
+  const minimumSdkVersion = readStringField(raw, "minimumSdkVersion");
+  if (minimumSdkVersion !== undefined) {
+    result.minimumSdkVersion = minimumSdkVersion;
+  }
+  const receivedSdkVersion = readStringField(raw, "receivedSdkVersion");
+  if (receivedSdkVersion !== undefined) {
+    result.receivedSdkVersion = receivedSdkVersion;
+  }
+  const upgradeUrl = readStringField(raw, "upgradeUrl");
+  if (upgradeUrl !== undefined) {
+    result.upgradeUrl = upgradeUrl;
+  }
+  return result;
 }
 function httpSentinel(status, body) {
   if (status === 400) {
+    const parsed = parseAdvanceErrorBody(body);
+    if (parsed?.error === "sdk_upgrade_required") {
+      return ErrSdkUpgradeRequired;
+    }
     return ErrBadRequest;
   }
   if (status === 401) {
@@ -383,6 +415,9 @@ function httpSentinel(status, body) {
   if (status === 409) {
     return ErrConflict;
   }
+  if (status === 412) {
+    return ErrNeedsHints;
+  }
   if (status === 429) {
     return ErrRateLimited;
   }
@@ -391,6 +426,29 @@ function httpSentinel(status, body) {
   }
   return ErrServerError;
 }
+function buildSdkUpgradeRequiredError(sentinel, text, logger) {
+  const parsed = parseAdvanceErrorBody(text);
+  if (parsed === null) {
+    logger.error("sdk upgrade required", {
+      receivedSdkVersion: null,
+      minimumSdkVersion: "<unknown>",
+      upgradeUrl: NPM_PACKAGE_URL
+    });
+    const message2 = `<missing> < <unknown>; bump @superbuilders/primer-tives at ${NPM_PACKAGE_URL}`;
+    return errors2.wrap(sentinel, message2);
+  }
+  const minimumSdkVersion = parsed.minimumSdkVersion === undefined ? "<unknown>" : parsed.minimumSdkVersion;
+  const receivedSdkVersion = parsed.receivedSdkVersion === undefined ? null : parsed.receivedSdkVersion;
+  const receivedDisplay = receivedSdkVersion === null ? "<missing>" : receivedSdkVersion;
+  const upgradeUrl = parsed.upgradeUrl === undefined ? NPM_PACKAGE_URL : parsed.upgradeUrl;
+  logger.error("sdk upgrade required", {
+    receivedSdkVersion,
+    minimumSdkVersion,
+    upgradeUrl
+  });
+  const message = `${receivedDisplay} < ${minimumSdkVersion}; bump @superbuilders/primer-tives at ${upgradeUrl}`;
+  return errors2.wrap(sentinel, message);
+}
 function isAbortError(err) {
   if (err instanceof DOMException && err.name === "AbortError") {
     return true;
@@ -402,7 +460,7 @@ function isAbortError(err) {
 }
 function createTransport(tc) {
   const fetchFn = tc.fetch ? tc.fetch : globalThis.fetch;
-  const log = tc.log;
+  const logger = tc.logger;
   function transportSignal() {
     if (tc.abort) {
       return tc.abort.signal;
@@ -410,7 +468,7 @@ function createTransport(tc) {
     return;
   }
   async function transport(body) {
-    log?.debug("transport request", {
+    logger.debug("transport request", {
       intentKind: body.intent.kind,
       subject: body.subject
     });
@@ -419,7 +477,8 @@ function createTransport(tc) {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Bearer ${tc.accessToken}`
+        Authorization: `Bearer ${tc.accessToken}`,
+        "X-Primer-SDK-Version": SDK_VERSION
       },
       body: JSON.stringify(body),
       signal: transportSignal()
@@ -430,12 +489,12 @@ function createTransport(tc) {
     });
     if (!fetchResult.ok) {
       if (isAbortError(fetchResult.error)) {
-        log?.error("transport timeout", {
+        logger.error("transport timeout", {
           intentKind: body.intent.kind
         });
         return { ok: false, error: errors2.wrap(ErrTimeout, fetchResult.error.message) };
       }
-      log?.error("transport network error", {
+      logger.error("transport network error", {
         error: fetchResult.error
       });
       return { ok: false, error: errors2.wrap(ErrNetwork, fetchResult.error.message) };
@@ -446,7 +505,10 @@ function createTransport(tc) {
         return "";
       });
       const sentinel = res.status === 422 ? ErrUnsupportedPci : httpSentinel(res.status, text);
-      log?.error("transport http error", {
+      if (errors2.is(sentinel, ErrSdkUpgradeRequired)) {
+        return { ok: false, error: buildSdkUpgradeRequiredError(sentinel, text, logger) };
+      }
+      logger.error("transport http error", {
         status: res.status
       });
       return { ok: false, error: errors2.wrap(sentinel, text) };
@@ -457,12 +519,12 @@ function createTransport(tc) {
       return { ok: false, error: err };
     });
     if (!jsonResult.ok) {
-      log?.error("transport json parse failed", {
+      logger.error("transport json parse failed", {
         error: jsonResult.error
       });
       return { ok: false, error: errors2.wrap(ErrJsonParse, jsonResult.error.message) };
     }
-    log?.debug("transport success", {
+    logger.debug("transport success", {
       intentKind: body.intent.kind
     });
     return { ok: true, data: jsonResult.data };
@@ -480,7 +542,7 @@ function poisonToJSON() {
 
 // src/client/choice-state.ts
 import * as errors3 from "@superbuilders/errors";
-function choiceState(ctx, stimulus, interaction, options, maxChoices, minChoices) {
+function choiceState(ctx, body, stimulus, interaction, options, maxChoices, minChoices) {
   let submitPending;
   let submitKey;
   let timeoutPending;
@@ -498,7 +560,7 @@ function choiceState(ctx, stimulus, interaction, options, maxChoices, minChoices
     }
     const validation = validateSubmissionForInteraction(interaction, submission);
     if (!validation.ok) {
-      ctx.log?.error("choice submit invalid", { selectedKeys, issues: validation.issues });
+      ctx.logger.error("choice submit invalid", { selectedKeys, issues: validation.issues });
       return Promise.resolve(ctx.errored(errors3.wrap(ErrInvalidSubmission, submissionValidationMessage(validation)), "interaction", { kind: "interaction", submission }));
     }
     submitKey = key;
@@ -524,6 +586,7 @@ function choiceState(ctx, stimulus, interaction, options, maxChoices, minChoices
   return {
     phase: "interaction",
     kind: "choice",
+    body,
     stimulus,
     interaction,
     options,
@@ -537,7 +600,7 @@ function choiceState(ctx, stimulus, interaction, options, maxChoices, minChoices
 
 // src/client/extended-text-state.ts
 import * as errors4 from "@superbuilders/errors";
-function extendedTextState(ctx, stimulus, interaction) {
+function extendedTextState(ctx, body, stimulus, interaction) {
   if (interaction.cardinality === "single") {
     let submitText = function(value) {
       const submission = { type: "extended-text", values: [value] };
@@ -553,7 +616,7 @@ function extendedTextState(ctx, stimulus, interaction) {
       }
       const validation = validateSubmissionForInteraction(interaction, submission);
       if (!validation.ok) {
-        ctx.log?.error("extended-text submit invalid", { value, issues: validation.issues });
+        ctx.logger.error("extended-text submit invalid", { value, issues: validation.issues });
         return Promise.resolve(ctx.errored(errors4.wrap(ErrInvalidSubmission, submissionValidationMessage(validation)), "interaction", { kind: "interaction", submission }));
       }
       submitKey2 = key;
@@ -582,6 +645,7 @@ function extendedTextState(ctx, stimulus, interaction) {
       phase: "interaction",
       kind: "extended-text",
       cardinality: "single",
+      body,
       stimulus,
       interaction,
       submitText,
@@ -607,7 +671,7 @@ function extendedTextState(ctx, stimulus, interaction) {
     }
     const validation = validateSubmissionForInteraction(multi, submission);
     if (!validation.ok) {
-      ctx.log?.error("extended-text submit invalid", { values, issues: validation.issues });
+      ctx.logger.error("extended-text submit invalid", { values, issues: validation.issues });
       return Promise.resolve(ctx.errored(errors4.wrap(ErrInvalidSubmission, submissionValidationMessage(validation)), "interaction", { kind: "interaction", submission }));
     }
     submitKey = key;
@@ -634,6 +698,7 @@ function extendedTextState(ctx, stimulus, interaction) {
     phase: "interaction",
     kind: "extended-text",
     cardinality: "multiple",
+    body,
     stimulus,
     interaction: multi,
     maxStrings: multi.maxStrings,
@@ -645,10 +710,11 @@ function extendedTextState(ctx, stimulus, interaction) {
 }
 
 // src/client/feedback-state.ts
-function feedbackState(ctx, stimulus, interaction, submission, isCorrect, feedbackContent, review) {
+function feedbackState(ctx, body, stimulus, interaction, submission, isCorrect, feedbackContent, review) {
   let pending;
   return {
     phase: "feedback",
+    body,
     stimulus,
     interaction,
     submission,
@@ -668,7 +734,7 @@ function feedbackState(ctx, stimulus, interaction, submission, isCorrect, feedba
 
 // src/client/match-state.ts
 import * as errors5 from "@superbuilders/errors";
-function matchState(ctx, stimulus, interaction) {
+function matchState(ctx, body, stimulus, interaction) {
   let submitPending;
   let submitKey;
   let timeoutPending;
@@ -686,7 +752,7 @@ function matchState(ctx, stimulus, interaction) {
     }
     const validation = validateSubmissionForInteraction(interaction, submission);
     if (!validation.ok) {
-      ctx.log?.error("match submit invalid", { pairs, issues: validation.issues });
+      ctx.logger.error("match submit invalid", { pairs, issues: validation.issues });
       return Promise.resolve(ctx.errored(errors5.wrap(ErrInvalidSubmission, submissionValidationMessage(validation)), "interaction", { kind: "interaction", submission }));
     }
     submitKey = key;
@@ -712,6 +778,7 @@ function matchState(ctx, stimulus, interaction) {
   return {
     phase: "interaction",
     kind: "match",
+    body,
     stimulus,
     interaction,
     sourceChoices: interaction.sourceChoices,
@@ -725,10 +792,11 @@ function matchState(ctx, stimulus, interaction) {
 }
 
 // src/client/observation-state.ts
-function observationState(ctx, stimulus) {
+function observationState(ctx, body, stimulus) {
   let pending;
   return {
     phase: "observation",
+    body,
     stimulus,
     advance: function advance() {
       if (pending) {
@@ -743,7 +811,7 @@ function observationState(ctx, stimulus) {
 
 // src/client/order-state.ts
 import * as errors6 from "@superbuilders/errors";
-function orderState(ctx, stimulus, interaction) {
+function orderState(ctx, body, stimulus, interaction) {
   let submitPending;
   let submitKey;
   let timeoutPending;
@@ -761,7 +829,7 @@ function orderState(ctx, stimulus, interaction) {
     }
     const validation = validateSubmissionForInteraction(interaction, submission);
     if (!validation.ok) {
-      ctx.log?.error("order submit invalid", { orderedKeys, issues: validation.issues });
+      ctx.logger.error("order submit invalid", { orderedKeys, issues: validation.issues });
       return Promise.resolve(ctx.errored(errors6.wrap(ErrInvalidSubmission, submissionValidationMessage(validation)), "interaction", { kind: "interaction", submission }));
     }
     submitKey = key;
@@ -787,6 +855,7 @@ function orderState(ctx, stimulus, interaction) {
   return {
     phase: "interaction",
     kind: "order",
+    body,
     stimulus,
     interaction,
     choices: interaction.choices,
@@ -800,7 +869,7 @@ function orderState(ctx, stimulus, interaction) {
 
 // src/client/pci-state.ts
 import * as errors7 from "@superbuilders/errors";
-function pciInteractionState(ctx, stimulus, interaction) {
+function pciInteractionState(ctx, body, stimulus, interaction) {
   let submitPending;
   let submitKey;
   let timeoutPending;
@@ -817,7 +886,7 @@ function pciInteractionState(ctx, stimulus, interaction) {
       }
       return Promise.resolve(ctx.errored(errors7.wrap(ErrConflict, "cannot submit a different pci payload while submit is in flight"), "interaction", { kind: "interaction", submission }));
     }
-    ctx.log?.debug("pci submit", { pciId });
+    ctx.logger.debug("pci submit", { pciId });
     submitKey = key;
     submitPending = ctx.execute({ kind: "interaction", submission }, "interaction").finally(function clearPending() {
       submitPending = undefined;
@@ -833,7 +902,7 @@ function pciInteractionState(ctx, stimulus, interaction) {
     if (timeoutPending) {
       return timeoutPending;
     }
-    ctx.log?.debug("pci timeout", { pciId });
+    ctx.logger.debug("pci timeout", { pciId });
     timeoutPending = ctx.execute(intent, "timeout").finally(function clearPending() {
       timeoutPending = undefined;
     });
@@ -842,6 +911,7 @@ function pciInteractionState(ctx, stimulus, interaction) {
   return {
     phase: "interaction",
     kind: "portable-custom",
+    body,
     stimulus,
     interaction,
     pciId,
@@ -854,7 +924,7 @@ function pciInteractionState(ctx, stimulus, interaction) {
 
 // src/client/text-entry-state.ts
 import * as errors8 from "@superbuilders/errors";
-function textEntryState(ctx, stimulus, interaction) {
+function textEntryState(ctx, body, stimulus, interaction) {
   let submitPending;
   let submitKey;
   let timeoutPending;
@@ -872,7 +942,7 @@ function textEntryState(ctx, stimulus, interaction) {
     }
     const validation = validateSubmissionForInteraction(interaction, submission);
     if (!validation.ok) {
-      ctx.log?.error("text-entry submit invalid", { value, issues: validation.issues });
+      ctx.logger.error("text-entry submit invalid", { value, issues: validation.issues });
       return Promise.resolve(ctx.errored(errors8.wrap(ErrInvalidSubmission, submissionValidationMessage(validation)), "interaction", { kind: "interaction", submission }));
     }
     submitKey = key;
@@ -898,6 +968,7 @@ function textEntryState(ctx, stimulus, interaction) {
   return {
     phase: "interaction",
     kind: "text-entry",
+    body,
     stimulus,
     interaction,
     submitText,
@@ -913,6 +984,8 @@ var FATAL_SENTINELS = [
   ErrTokenExpired,
   ErrForbidden,
   ErrNotFound,
+  ErrNeedsHints,
+  ErrSdkUpgradeRequired,
   ErrUnsupportedPci
 ];
 function isFatalError(err) {
@@ -927,13 +1000,24 @@ function isRetriableError(err) {
   return !errors9.is(err, ErrInvalidSubmission);
 }
 function makeSession(sc) {
-  const log = sc.log;
+  const logger = sc.logger;
   function resolve(result) {
     switch (result.outcome) {
       case "advanced":
-        return fromAdvanced(result.stimulus, result.interaction);
-      case "submitted":
-        return feedbackState(ctx, result.stimulus, result.interaction, result.submission, result.isCorrect, result.feedbackContent, result.review);
+        return fromAdvanced(result.frame.body, result.frame.stimulus, result.frame.interaction);
+      case "submitted": {
+        const interaction = result.frame.interaction;
+        if (interaction === null) {
+          logger.error("submitted result without interaction");
+          return {
+            phase: "fatal",
+            error: errors9.wrap(ErrBadRequest, "submitted result missing interaction"),
+            retriable: false,
+            toJSON: poisonToJSON
+          };
+        }
+        return feedbackState(ctx, result.frame.body, result.frame.stimulus, interaction, result.submission, result.isCorrect, result.feedbackContent, result.review);
+      }
       case "completed":
         return { phase: "completed", toJSON: poisonToJSON };
     }
@@ -947,13 +1031,13 @@ function makeSession(sc) {
       retriable,
       retry: function retry() {
         if (!retriable) {
-          log?.debug("retry ignored for non-retriable error", { failedPhase });
+          logger.debug("retry ignored for non-retriable error", { failedPhase });
           return Promise.resolve(state);
         }
         if (pending) {
           return pending;
         }
-        log?.debug("retrying from errored state", { failedPhase });
+        logger.debug("retrying from errored state", { failedPhase });
         pending = execute(intent, failedPhase);
         return pending;
       },
@@ -970,7 +1054,7 @@ function makeSession(sc) {
     const result = await sc.transport(body);
     if (!result.ok) {
       if (isFatalError(result.error)) {
-        log?.error("fatal transport error", { error: result.error, phase });
+        logger.error("fatal transport error", { error: result.error, phase });
         return { phase: "fatal", error: result.error, retriable: false, toJSON: poisonToJSON };
       }
       return errored(result.error, phase, intent);
@@ -985,13 +1069,13 @@ function makeSession(sc) {
     }
     return false;
   }
-  function fromAdvanced(stimulus, interaction) {
+  function fromAdvanced(body, stimulus, interaction) {
     if (interaction === null) {
-      return observationState(ctx, stimulus);
+      return observationState(ctx, body, stimulus);
     }
     if (interaction.type === "portable-custom") {
       if (!isPciSupported(interaction.pciId)) {
-        log?.error("unsupported pci in frame", { pciId: interaction.pciId });
+        logger.error("unsupported pci in frame", { pciId: interaction.pciId });
         return {
           phase: "fatal",
           error: errors9.wrap(ErrUnsupportedPci, `pci '${interaction.pciId}'`),
@@ -1000,25 +1084,25 @@ function makeSession(sc) {
         };
       }
     }
-    return pendingInteractionState(stimulus, interaction);
+    return pendingInteractionState(body, stimulus, interaction);
   }
-  function pendingInteractionState(stimulus, interaction) {
+  function pendingInteractionState(body, stimulus, interaction) {
     switch (interaction.type) {
       case "choice":
-        return choiceState(ctx, stimulus, interaction, interaction.options, interaction.maxChoices, interaction.minChoices);
+        return choiceState(ctx, body, stimulus, interaction, interaction.options, interaction.maxChoices, interaction.minChoices);
       case "text-entry":
-        return textEntryState(ctx, stimulus, interaction);
+        return textEntryState(ctx, body, stimulus, interaction);
       case "extended-text":
-        return extendedTextState(ctx, stimulus, interaction);
+        return extendedTextState(ctx, body, stimulus, interaction);
       case "order":
-        return orderState(ctx, stimulus, interaction);
+        return orderState(ctx, body, stimulus, interaction);
       case "match":
-        return matchState(ctx, stimulus, interaction);
+        return matchState(ctx, body, stimulus, interaction);
       case "portable-custom":
-        return pciInteractionState(ctx, stimulus, interaction);
+        return pciInteractionState(ctx, body, stimulus, interaction);
     }
   }
-  const ctx = { log, execute, errored };
+  const ctx = { logger, execute, errored };
   return { execute };
 }
 
@@ -1032,9 +1116,9 @@ function isMalformedJws(token) {
   return dotCount !== 2;
 }
 function create(config) {
-  const log = config.logger;
+  const logger = config.logger;
   if (isMalformedJws(config.accessToken)) {
-    log?.error("malformed access token", { prefix: ACCESS_TOKEN_PREFIX });
+    logger.error("malformed access token", { prefix: ACCESS_TOKEN_PREFIX });
     throw errors10.wrap(ErrMalformedAccessToken, `token must start with '${ACCESS_TOKEN_PREFIX}' and contain two dots`);
   }
   const transport = createTransport({
@@ -1043,15 +1127,15 @@ function create(config) {
     origin: config.origin,
     fetch: config.fetch,
     abort: config.abort,
-    log
+    logger
   });
   let startPromise;
   async function doStart() {
-    log?.debug("start", { subject: config.subject });
+    logger.debug("start", { subject: config.subject });
     const s = makeSession({
       supportedPcis: config.supportedPcis,
       subject: config.subject,
-      log,
+      logger,
       transport
     });
     return s.execute({ kind: "observation" }, "observation");
@@ -1059,7 +1143,7 @@ function create(config) {
   return {
     start() {
       if (startPromise) {
-        log?.debug("start already called");
+        logger.debug("start already called");
         return startPromise;
       }
       startPromise = doStart();
@@ -1071,4 +1155,4 @@ export {
   create
 };
 
-//# debugId=FDB6BAAD7743405564756E2164756E21
+//# debugId=5A77D78E02028F9D64756E2164756E21