@superbuilders/primer-tives 0.9.0 → 1.1.0

package/dist/server/index.js

@@ -1,6 +1,3 @@
-// src/server/exchange.ts
-import * as errors2 from "@superbuilders/errors";
-
 // src/errors.ts
 import * as errors from "@superbuilders/errors";
 var ErrNetwork = errors.new("network");
@@ -15,6 +12,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");
@@ -23,17 +21,60 @@ 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");
-
 // src/server/exchange.ts
-var EXCHANGE_PATH = "/api/v0/auth/exchange";
-function isAbortError(err) {
-  if (err instanceof DOMException && err.name === "AbortError") {
-    return true;
+import * as errors2 from "@superbuilders/errors";
+var STUDENT_EXCHANGE_PATH = "/api/v0/auth/exchange";
+var TIMEBACK_EXCHANGE_PATH = "/api/v0/auth/exchange/timeback";
+function isObjectRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function toExchangeErrorBody(data) {
+  if (!isObjectRecord(data)) {
+    return {};
   }
-  if (err instanceof DOMException && err.name === "TimeoutError") {
-    return true;
+  return typeof data.error === "string" ? { error: data.error } : {};
+}
+function parseSessionTokenSuccessBody(data) {
+  if (!isObjectRecord(data)) {
+    return;
   }
-  return false;
+  if (typeof data.access_token !== "string") {
+    return;
+  }
+  if (data.token_type !== "Bearer") {
+    return;
+  }
+  if (!isFiniteNumber(data.expires_in)) {
+    return;
+  }
+  if (typeof data.scope !== "string") {
+    return;
+  }
+  return {
+    access_token: data.access_token,
+    token_type: data.token_type,
+    expires_in: data.expires_in,
+    scope: data.scope
+  };
+}
+function parseTimebackExchangeSuccessBody(data) {
+  const session = parseSessionTokenSuccessBody(data);
+  if (!session || !isObjectRecord(data) || typeof data.student_id !== "string") {
+    return;
+  }
+  return {
+    student_id: data.student_id,
+    access_token: session.access_token,
+    token_type: session.token_type,
+    expires_in: session.expires_in,
+    scope: session.scope
+  };
+}
+function isAbortError(err) {
+  return err.name === "AbortError" || err.name === "TimeoutError";
 }
 function mapBadRequest(body) {
   if (body.error === "unsupported_grade") {
@@ -51,12 +92,15 @@ function httpSentinel(status, body) {
   if (status === 404) {
     return ErrStudentNotFound;
   }
+  if (status === 409) {
+    if (body.error === "external_authority_required") {
+      return ErrExternalAuthorityRequired;
+    }
+    return ErrConflict;
+  }
   if (status === 502) {
     return ErrTimebackUnavailable;
   }
-  if (status >= 500 && status < 600) {
-    return ErrServerError;
-  }
   return ErrServerError;
 }
 async function readErrorBody(res) {
@@ -68,70 +112,155 @@ async function readErrorBody(res) {
   if (!parsed.ok) {
     return {};
   }
-  return parsed.data;
+  return toExchangeErrorBody(parsed.data);
 }
-async function exchangeToken(config, provider, studentId) {
-  const log = config.logger;
+async function sendExchangeRequest(config, path, body, logContext) {
+  const logger = config.logger;
   const fetchFn = config.fetch ? config.fetch : globalThis.fetch;
   const signal = config.abort ? config.abort.signal : undefined;
-  log?.debug("exchange request", { provider });
-  const url = `${config.origin}${EXCHANGE_PATH}`;
+  const url = `${config.origin}${path}`;
   const fetchResult = await fetchFn(url, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${config.secretKey}`
     },
-    body: JSON.stringify({ provider, student_id: studentId }),
+    body: JSON.stringify(body),
     signal
-  }).then(function ok(r) {
-    return { ok: true, response: r };
+  }).then(function ok(response) {
+    return { ok: true, response };
   }, function fail(err) {
     return { ok: false, error: err };
   });
   if (!fetchResult.ok) {
     if (isAbortError(fetchResult.error)) {
-      log?.error("exchange timeout", { provider });
+      logger.error("exchange timeout", { path, ...logContext });
       throw errors2.wrap(ErrTimeout, fetchResult.error.message);
     }
-    log?.error("exchange network error", { provider, error: fetchResult.error });
+    logger.error("exchange network error", { path, ...logContext, error: fetchResult.error });
     throw errors2.wrap(ErrNetwork, fetchResult.error.message);
   }
-  const res = fetchResult.response;
-  if (!res.ok) {
-    const body = await readErrorBody(res);
-    const sentinel = httpSentinel(res.status, body);
-    const detail = body.error ? `${res.status} ${body.error}` : `${res.status}`;
-    log?.error("exchange http error", { provider, status: res.status, body });
-    throw errors2.wrap(sentinel, detail);
+  return fetchResult.response;
+}
+async function parseSessionTokenSuccess(config, res, logContext) {
+  const logger = config.logger;
+  const jsonResult = await res.json().then(function ok(data) {
+    return { ok: true, data };
+  }, function fail(err) {
+    return { ok: false, error: err };
+  });
+  if (!jsonResult.ok) {
+    logger.error("exchange json parse failed", { ...logContext, error: jsonResult.error });
+    throw errors2.wrap(ErrJsonParse, jsonResult.error.message);
   }
+  const body = parseSessionTokenSuccessBody(jsonResult.data);
+  if (!body) {
+    logger.error("exchange success body had invalid shape", {
+      ...logContext,
+      body: jsonResult.data
+    });
+    throw errors2.wrap(ErrJsonParse, "exchange success body had invalid shape");
+  }
+  logger.debug("exchange success", {
+    ...logContext,
+    expiresIn: body.expires_in
+  });
+  return {
+    accessToken: body.access_token,
+    expiresInSeconds: body.expires_in
+  };
+}
+async function parseTimebackSessionSuccess(config, res, sourcedId) {
+  const logger = config.logger;
   const jsonResult = await res.json().then(function ok(data) {
     return { ok: true, data };
   }, function fail(err) {
     return { ok: false, error: err };
   });
   if (!jsonResult.ok) {
-    log?.error("exchange json parse failed", { provider, error: jsonResult.error });
+    logger.error("timeback exchange json parse failed", { sourcedId, error: jsonResult.error });
     throw errors2.wrap(ErrJsonParse, jsonResult.error.message);
   }
-  log?.debug("exchange success", { provider, expiresIn: jsonResult.data.expires_in });
+  const body = parseTimebackExchangeSuccessBody(jsonResult.data);
+  if (!body) {
+    logger.error("timeback exchange success body had invalid shape", {
+      sourcedId,
+      body: jsonResult.data
+    });
+    throw errors2.wrap(ErrJsonParse, "timeback exchange success body had invalid shape");
+  }
+  logger.debug("timeback exchange success", {
+    sourcedId,
+    studentId: body.student_id,
+    expiresIn: body.expires_in
+  });
   return {
-    accessToken: jsonResult.data.access_token,
-    expiresInSeconds: jsonResult.data.expires_in
+    studentId: body.student_id,
+    accessToken: body.access_token,
+    expiresInSeconds: body.expires_in
   };
 }
+async function exchangeStudent(config, studentId) {
+  const logger = config.logger;
+  logger.debug("exchange student request", { studentId });
+  const res = await sendExchangeRequest(config, STUDENT_EXCHANGE_PATH, { student_id: studentId }, { studentId, exchangeKind: "student_id" });
+  if (!res.ok) {
+    const body = await readErrorBody(res);
+    const sentinel = httpSentinel(res.status, body);
+    const detail = body.error ? `${res.status} ${body.error}` : `${res.status}`;
+    logger.error("exchange student http error", { status: res.status, body, studentId });
+    throw errors2.wrap(sentinel, detail);
+  }
+  return parseSessionTokenSuccess(config, res, { studentId, exchangeKind: "student_id" });
+}
+async function exchangeTimebackStudent(config, sourcedId) {
+  const logger = config.logger;
+  logger.debug("exchange timeback student request", { sourcedId });
+  const res = await sendExchangeRequest(config, TIMEBACK_EXCHANGE_PATH, { sourced_id: sourcedId }, { sourcedId, exchangeKind: "timeback" });
+  if (!res.ok) {
+    const body = await readErrorBody(res);
+    const sentinel = httpSentinel(res.status, body);
+    const detail = body.error ? `${res.status} ${body.error}` : `${res.status}`;
+    logger.error("exchange timeback student http error", { status: res.status, body, sourcedId });
+    throw errors2.wrap(sentinel, detail);
+  }
+  return parseTimebackSessionSuccess(config, res, sourcedId);
+}
 
-// src/server/students.ts
+// src/server/hints.ts
 import * as errors3 from "@superbuilders/errors";
+
+// src/grade-level.ts
+var GRADE_LEVELS = ["K", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
+
+// src/server/hints.ts
 var STUDENTS_PATH = "/api/v0/students";
-function isAbortError2(err) {
-  if (err instanceof DOMException && err.name === "AbortError") {
-    return true;
+function isObjectRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function toHintsErrorBody(data) {
+  if (!isObjectRecord2(data)) {
+    return {};
+  }
+  return typeof data.error === "string" ? { error: data.error } : {};
+}
+function parseHintsSuccess(data) {
+  if (!isObjectRecord2(data)) {
+    return;
   }
-  if (err instanceof DOMException && err.name === "TimeoutError") {
-    return true;
+  if (typeof data.student_id !== "string") {
+    return;
   }
-  return false;
+  if (data.grade_level !== null && typeof data.grade_level !== "string") {
+    return;
+  }
+  return {
+    student_id: data.student_id,
+    grade_level: data.grade_level
+  };
+}
+function isAbortError2(err) {
+  return err.name === "AbortError" || err.name === "TimeoutError";
 }
 function httpSentinel2(status) {
   if (status === 400) {
@@ -154,94 +283,235 @@ async function readErrorBody2(res) {
   if (!parsed.ok) {
     return {};
   }
-  return parsed.data;
+  return toHintsErrorBody(parsed.data);
+}
+function buildRequestBody(hints) {
+  const body = {};
+  if (hints.gradeLevel !== undefined) {
+    body.grade_level = hints.gradeLevel;
+  }
+  return JSON.stringify(body);
 }
-async function sendStudentsRequest(config, path, method, body) {
-  const log = config.logger;
+async function sendSetHintsRequest(config, studentId, hints) {
+  const logger = config.logger;
   const fetchFn = config.fetch ? config.fetch : globalThis.fetch;
   const signal = config.abort ? config.abort.signal : undefined;
-  const url = `${config.origin}${path}`;
+  const url = `${config.origin}${STUDENTS_PATH}/${encodeURIComponent(studentId)}/hints`;
   const fetchResult = await fetchFn(url, {
-    method,
+    method: "PATCH",
     headers: {
-      "Content-Type": "application/json",
-      Authorization: `Bearer ${config.secretKey}`
+      Authorization: `Bearer ${config.secretKey}`,
+      "Content-Type": "application/json"
     },
-    body: JSON.stringify(body),
+    body: buildRequestBody(hints),
     signal
-  }).then(function ok(r) {
-    return { ok: true, response: r };
+  }).then(function ok(response) {
+    return { ok: true, response };
   }, function fail(err) {
     return { ok: false, error: err };
   });
   if (!fetchResult.ok) {
     if (isAbortError2(fetchResult.error)) {
-      log?.error("students timeout", { path, method });
+      logger.error("set student hints timeout", { studentId });
       throw errors3.wrap(ErrTimeout, fetchResult.error.message);
     }
-    log?.error("students network error", { path, method, error: fetchResult.error });
+    logger.error("set student hints network error", {
+      studentId,
+      error: fetchResult.error
+    });
     throw errors3.wrap(ErrNetwork, fetchResult.error.message);
   }
   return fetchResult.response;
 }
-async function createStudent(config, gradeLevel) {
-  const log = config.logger;
-  log?.debug("create student request", { gradeLevel });
-  const res = await sendStudentsRequest(config, STUDENTS_PATH, "POST", {
-    grade_level: gradeLevel
+async function parseHintsSuccessResponse(config, res) {
+  const logger = config.logger;
+  const jsonResult = await res.json().then(function ok(data) {
+    return { ok: true, data };
+  }, function fail(err) {
+    return { ok: false, error: err };
   });
+  if (!jsonResult.ok) {
+    logger.error("set hints response parse failed", { error: jsonResult.error });
+    throw errors3.wrap(ErrJsonParse, jsonResult.error.message);
+  }
+  const body = parseHintsSuccess(jsonResult.data);
+  if (!body) {
+    logger.error("set hints response had invalid shape", { body: jsonResult.data });
+    throw errors3.wrap(ErrJsonParse, "set hints success body had invalid shape");
+  }
+  logger.debug("set hints response success", {
+    studentId: body.student_id,
+    gradeLevel: body.grade_level
+  });
+  return {
+    studentId: body.student_id,
+    gradeLevel: coerceGradeLevel(body.grade_level)
+  };
+}
+function coerceGradeLevel(value) {
+  if (value === null) {
+    return null;
+  }
+  for (const g of GRADE_LEVELS) {
+    if (g === value) {
+      return g;
+    }
+  }
+  return null;
+}
+async function setStudentHints(config, studentId, hints) {
+  const logger = config.logger;
+  logger.debug("set student hints request", { studentId, hints });
+  const res = await sendSetHintsRequest(config, studentId, hints);
   if (!res.ok) {
     const body = await readErrorBody2(res);
     const sentinel = httpSentinel2(res.status);
     const detail = body.error ? `${res.status} ${body.error}` : `${res.status}`;
-    log?.error("create student http error", { status: res.status, body });
+    logger.error("set student hints http error", {
+      studentId,
+      status: res.status,
+      body
+    });
     throw errors3.wrap(sentinel, detail);
   }
+  return parseHintsSuccessResponse(config, res);
+}
+
+// src/server/students.ts
+import * as errors4 from "@superbuilders/errors";
+var STUDENTS_PATH2 = "/api/v0/students";
+function isObjectRecord3(value) {
+  return typeof value === "object" && value !== null;
+}
+function toStudentsErrorBody(data) {
+  if (!isObjectRecord3(data)) {
+    return {};
+  }
+  return typeof data.error === "string" ? { error: data.error } : {};
+}
+function parseStudentIdSuccessBody(data) {
+  if (!isObjectRecord3(data)) {
+    return;
+  }
+  if (typeof data.student_id !== "string") {
+    return;
+  }
+  return { student_id: data.student_id };
+}
+function isAbortError3(err) {
+  return err.name === "AbortError" || err.name === "TimeoutError";
+}
+function httpSentinel3(status) {
+  if (status === 400) {
+    return ErrBadRequest;
+  }
+  if (status === 401) {
+    return ErrInvalidSecretKey;
+  }
+  if (status === 409) {
+    return ErrConflict;
+  }
+  return ErrServerError;
+}
+async function readErrorBody3(res) {
+  const parsed = await res.json().then(function ok(data) {
+    return { ok: true, data };
+  }, function fail() {
+    return { ok: false };
+  });
+  if (!parsed.ok) {
+    return {};
+  }
+  return toStudentsErrorBody(parsed.data);
+}
+async function sendCreateStudentRequest(config) {
+  const logger = config.logger;
+  const fetchFn = config.fetch ? config.fetch : globalThis.fetch;
+  const signal = config.abort ? config.abort.signal : undefined;
+  const url = `${config.origin}${STUDENTS_PATH2}`;
+  const fetchResult = await fetchFn(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${config.secretKey}`
+    },
+    signal
+  }).then(function ok(response) {
+    return { ok: true, response };
+  }, function fail(err) {
+    return { ok: false, error: err };
+  });
+  if (!fetchResult.ok) {
+    if (isAbortError3(fetchResult.error)) {
+      logger.error("students timeout", { path: STUDENTS_PATH2 });
+      throw errors4.wrap(ErrTimeout, fetchResult.error.message);
+    }
+    logger.error("students network error", {
+      path: STUDENTS_PATH2,
+      error: fetchResult.error
+    });
+    throw errors4.wrap(ErrNetwork, fetchResult.error.message);
+  }
+  return fetchResult.response;
+}
+async function parseStudentIdSuccess(config, res) {
+  const logger = config.logger;
   const jsonResult = await res.json().then(function ok(data) {
     return { ok: true, data };
   }, function fail(err) {
     return { ok: false, error: err };
   });
   if (!jsonResult.ok) {
-    log?.error("create student json parse failed", { error: jsonResult.error });
-    throw errors3.wrap(ErrJsonParse, jsonResult.error.message);
+    logger.error("student id response parse failed", {
+      operation: "create student",
+      error: jsonResult.error
+    });
+    throw errors4.wrap(ErrJsonParse, jsonResult.error.message);
+  }
+  const body = parseStudentIdSuccessBody(jsonResult.data);
+  if (!body) {
+    logger.error("student id response had invalid shape", {
+      operation: "create student",
+      body: jsonResult.data
+    });
+    throw errors4.wrap(ErrJsonParse, "create student success body had invalid shape");
   }
-  log?.debug("create student success", { studentId: jsonResult.data.student_id });
-  return jsonResult.data.student_id;
+  logger.debug("student id response success", {
+    operation: "create student",
+    studentId: body.student_id
+  });
+  return body.student_id;
 }
-async function updateStudentGradeLevel(config, studentId, gradeLevel) {
-  const log = config.logger;
-  log?.debug("update student grade request", { studentId, gradeLevel });
-  const res = await sendStudentsRequest(config, `${STUDENTS_PATH}/${encodeURIComponent(studentId)}`, "PATCH", { gradeLevel });
+async function createStudent(config) {
+  const logger = config.logger;
+  logger.debug("create student request");
+  const res = await sendCreateStudentRequest(config);
   if (!res.ok) {
-    const body = await readErrorBody2(res);
-    const sentinel = httpSentinel2(res.status);
+    const body = await readErrorBody3(res);
+    const sentinel = httpSentinel3(res.status);
     const detail = body.error ? `${res.status} ${body.error}` : `${res.status}`;
-    log?.error("update student http error", { status: res.status, body });
-    throw errors3.wrap(sentinel, detail);
+    logger.error("create student http error", { status: res.status, body });
+    throw errors4.wrap(sentinel, detail);
   }
-  log?.debug("update student success", { studentId });
+  return parseStudentIdSuccess(config, res);
 }
 
 // src/server/create-server.ts
 function createPrimerServer(config) {
   return {
-    createNativeStudent(gradeLevel) {
-      return createStudent(config, gradeLevel);
+    createStudent() {
+      return createStudent(config);
     },
-    updateNativeStudentGradeLevel(studentId, gradeLevel) {
-      return updateStudentGradeLevel(config, studentId, gradeLevel);
+    setStudentHints(studentId, hints) {
+      return setStudentHints(config, studentId, hints);
     },
-    exchangeNativeStudentForAccessToken(studentId) {
-      return exchangeToken(config, "native", studentId);
+    exchangeStudentForAccessToken(studentId) {
+      return exchangeStudent(config, studentId);
     },
     exchangeTimebackStudentForAccessToken(sourcedId) {
-      return exchangeToken(config, "timeback", sourcedId);
+      return exchangeTimebackStudent(config, sourcedId);
     }
   };
 }
-// src/grade-level.ts
-var GRADE_LEVELS = ["K", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"];
 export {
   createPrimerServer,
   GRADE_LEVELS,
@@ -253,7 +523,9 @@ export {
   ErrNetwork,
   ErrJsonParse,
   ErrInvalidSecretKey,
+  ErrExternalAuthorityRequired,
+  ErrConflict,
   ErrBadRequest
 };
 
-//# debugId=3128BCEC46D85F5764756E2164756E21
+//# debugId=36162738F428CAE464756E2164756E21