@timeback/oneroster 0.1.0

package/dist/errors.js

@@ -0,0 +1,1414 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+// ../../internal/constants/src/endpoints.ts
+var DEFAULT_PLATFORM = "BEYOND_AI";
+var BEYONDAI_TOKEN_URLS = {
+  staging: "https://staging-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token",
+  production: "https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token"
+};
+var BEYONDAI_API_URLS = {
+  staging: "https://api.staging.alpha-1edtech.ai",
+  production: "https://api.alpha-1edtech.ai"
+};
+var BEYONDAI_CALIPER_URLS = {
+  staging: "https://caliper.staging.alpha-1edtech.ai",
+  production: "https://caliper.alpha-1edtech.ai"
+};
+var BEYONDAI_QTI_URLS = {
+  staging: "https://qti.alpha-1edtech.ai/api",
+  production: "https://qti.alpha-1edtech.ai/api"
+};
+var LEARNWITHAI_TOKEN_URLS = {
+  staging: "https://platform.dev.timeback.com/auth/1.0/token",
+  production: "https://platform.timeback.com/auth/1.0/token"
+};
+var LEARNWITHAI_API_URLS = {
+  staging: "https://platform.dev.timeback.com",
+  production: "https://platform.timeback.com"
+};
+var LEARNWITHAI_CALIPER_URLS = {
+  staging: "https://platform.dev.timeback.com",
+  production: "https://platform.timeback.com"
+};
+var LEARNWITHAI_QTI_URLS = {
+  staging: "https://platform.dev.timeback.com",
+  production: "https://platform.timeback.com"
+};
+var PLATFORM_ENDPOINTS = {
+  BEYOND_AI: {
+    token: BEYONDAI_TOKEN_URLS,
+    api: BEYONDAI_API_URLS,
+    caliper: BEYONDAI_CALIPER_URLS,
+    qti: BEYONDAI_QTI_URLS
+  },
+  LEARNWITH_AI: {
+    token: LEARNWITHAI_TOKEN_URLS,
+    api: LEARNWITHAI_API_URLS,
+    caliper: LEARNWITHAI_CALIPER_URLS,
+    qti: LEARNWITHAI_QTI_URLS
+  }
+};
+// ../../internal/constants/src/typescript.ts
+var TypeScriptPackages = {
+  tsc: "tsc",
+  nativePreview: "@typescript/native-preview@7.0.0-dev.20251217.1"
+};
+var TYPESCRIPT_PACKAGE = TypeScriptPackages.nativePreview;
+// ../../internal/logger/src/debug.ts
+var patterns = null;
+var debugAll = false;
+var debugEnvSet = false;
+function patternToRegex(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+  const regexStr = escaped.replace(/\*/g, ".*");
+  return new RegExp(`^${regexStr}$`);
+}
+function parseDebugEnv() {
+  if (patterns !== null)
+    return;
+  patterns = [];
+  if (typeof process === "undefined" || !process.env?.DEBUG) {
+    debugEnvSet = false;
+    return;
+  }
+  debugEnvSet = true;
+  const debugValue = process.env.DEBUG.trim();
+  if (debugValue === "1" || debugValue === "true" || debugValue === "*") {
+    debugAll = true;
+    return;
+  }
+  const parts = debugValue.split(",").map((p) => p.trim()).filter(Boolean);
+  for (const part of parts) {
+    if (part.startsWith("-")) {
+      patterns.push({
+        regex: patternToRegex(part.slice(1)),
+        exclude: true
+      });
+    } else {
+      patterns.push({
+        regex: patternToRegex(part),
+        exclude: false
+      });
+    }
+  }
+  const hasInclude = patterns.some((p) => !p.exclude);
+  if (!hasInclude && patterns.length > 0) {
+    debugAll = true;
+  }
+}
+function shouldShowDebug(scope) {
+  parseDebugEnv();
+  if (!debugEnvSet) {
+    return true;
+  }
+  if (debugAll) {
+    if (scope) {
+      for (const pattern of patterns) {
+        if (pattern.exclude && pattern.regex.test(scope)) {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+  if (!scope) {
+    return false;
+  }
+  for (const pattern of patterns) {
+    if (pattern.exclude && pattern.regex.test(scope)) {
+      return false;
+    }
+  }
+  for (const pattern of patterns) {
+    if (!pattern.exclude && pattern.regex.test(scope)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// ../../internal/logger/src/env.ts
+function isBrowser() {
+  return typeof globalThis !== "undefined" && "window" in globalThis;
+}
+function detectEnvironment() {
+  if (isBrowser()) {
+    return "browser";
+  }
+  if (typeof process !== "undefined" && process.env) {
+    if (process.env["NODE_ENV"] === "test" || process.env["BUN_ENV"] === "test") {
+      return "test";
+    }
+    if (false) {}
+    if (process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI || process.env.CIRCLECI || process.env.JENKINS_URL || process.env.BUILDKITE) {
+      return "ci";
+    }
+  }
+  return "terminal";
+}
+
+// ../../internal/logger/src/formatters/terminal.ts
+var nodeInspect;
+if (!isBrowser()) {
+  try {
+    const util = await import("node:util");
+    nodeInspect = util.inspect;
+  } catch {}
+}
+var colors = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  red: "\x1B[31m",
+  yellow: "\x1B[33m",
+  blue: "\x1B[34m",
+  cyan: "\x1B[36m"
+};
+function getLevelColor(level) {
+  switch (level) {
+    case "debug":
+      return colors.blue;
+    case "info":
+      return colors.cyan;
+    case "warn":
+      return colors.yellow;
+    case "error":
+      return colors.red;
+  }
+}
+function getConsoleMethod(level) {
+  switch (level) {
+    case "debug":
+      return console.debug;
+    case "info":
+      return console.info;
+    case "warn":
+      return console.warn;
+    case "error":
+      return console.error;
+  }
+}
+function formatContext(context) {
+  if (nodeInspect) {
+    return nodeInspect(context, {
+      depth: null,
+      colors: true,
+      breakLength: 80,
+      compact: false
+    });
+  }
+  return JSON.stringify(context, null, 2);
+}
+var terminalFormatter = (entry) => {
+  const levelColor = getLevelColor(entry.level);
+  const consoleMethod = getConsoleMethod(entry.level);
+  const levelUpper = entry.level.toUpperCase().padEnd(5);
+  const isoString = entry.timestamp.toISOString().replace(/\.\d{3}Z$/, "");
+  const timestamp = `${colors.dim}[${isoString}]${colors.reset}`;
+  const level = `${levelColor}${levelUpper}${colors.reset}`;
+  const scope = entry.scope ? `${colors.bold}[${entry.scope}]${colors.reset} ` : "";
+  const prefix = `${timestamp} ${level} ${scope}${entry.message}`;
+  if (entry.context && Object.keys(entry.context).length > 0) {
+    consoleMethod(prefix, formatContext(entry.context));
+  } else {
+    consoleMethod(prefix);
+  }
+};
+// ../../internal/logger/src/formatters/ci.ts
+var LEVEL_PREFIX = {
+  debug: "[DEBUG]",
+  info: "[INFO]",
+  warn: "[WARN]",
+  error: "[ERROR]"
+};
+function formatContext2(context) {
+  return Object.entries(context).map(([key, value]) => `${key}=${formatValue(value)}`).join(" ");
+}
+function formatValue(value) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  if (typeof value === "boolean")
+    return String(value);
+  if (value === null)
+    return "null";
+  if (value === undefined)
+    return "undefined";
+  return JSON.stringify(value);
+}
+var ciFormatter = (entry) => {
+  const parts = [];
+  parts.push(entry.timestamp.toISOString());
+  parts.push(LEVEL_PREFIX[entry.level]);
+  if (entry.scope) {
+    parts.push(`[${entry.scope}]`);
+  }
+  parts.push(entry.message);
+  if (entry.context && Object.keys(entry.context).length > 0) {
+    parts.push(formatContext2(entry.context));
+  }
+  console.log(parts.join(" "));
+};
+// ../../internal/logger/src/formatters/production.ts
+var productionFormatter = (entry) => {
+  const output = {
+    timestamp: entry.timestamp.toISOString(),
+    level: entry.level,
+    ...entry.scope && { scope: entry.scope },
+    msg: entry.message
+  };
+  if (entry.context && Object.keys(entry.context).length > 0) {
+    Object.assign(output, entry.context);
+  }
+  console.log(JSON.stringify(output));
+};
+// ../../internal/logger/src/formatters/browser.ts
+var LEVEL_STYLES = {
+  debug: "color: gray",
+  info: "color: #0ea5e9",
+  warn: "color: #f59e0b",
+  error: "color: #ef4444; font-weight: bold"
+};
+var LEVEL_METHODS = {
+  debug: "log",
+  info: "info",
+  warn: "warn",
+  error: "error"
+};
+var browserFormatter = (entry) => {
+  const method = LEVEL_METHODS[entry.level];
+  const style = LEVEL_STYLES[entry.level];
+  const prefix = entry.scope ? `[${entry.scope}]` : "";
+  const label = `%c${prefix} ${entry.message}`;
+  if (entry.context && Object.keys(entry.context).length > 0) {
+    console[method](label, style, entry.context);
+  } else {
+    console[method](label, style);
+  }
+};
+// ../../internal/logger/src/logger.ts
+var LOG_LEVELS = ["debug", "info", "warn", "error"];
+function getFormatter(env) {
+  switch (env) {
+    case "terminal":
+      return terminalFormatter;
+    case "ci":
+      return ciFormatter;
+    case "production":
+      return productionFormatter;
+    case "browser":
+      return browserFormatter;
+    case "test":
+      return () => {};
+  }
+}
+function getDefaultMinLevel() {
+  if (typeof process !== "undefined" && process.env?.DEBUG) {
+    return "debug";
+  }
+  return "info";
+}
+function shouldLog(level, minLevel) {
+  return LOG_LEVELS.indexOf(level) >= LOG_LEVELS.indexOf(minLevel);
+}
+
+class Logger {
+  scope;
+  minLevel;
+  environment;
+  formatter;
+  defaultContext;
+  constructor(options = {}) {
+    this.scope = options.scope;
+    this.minLevel = options.minLevel ?? getDefaultMinLevel();
+    this.defaultContext = options.defaultContext ?? {};
+    this.environment = options.environment ?? detectEnvironment();
+    this.formatter = getFormatter(this.environment);
+  }
+  child(scope) {
+    const childScope = this.scope ? `${this.scope}:${scope}` : scope;
+    return new Logger({
+      scope: childScope,
+      minLevel: this.minLevel,
+      environment: this.environment,
+      defaultContext: { ...this.defaultContext }
+    });
+  }
+  withContext(context) {
+    return new Logger({
+      scope: this.scope,
+      minLevel: this.minLevel,
+      environment: this.environment,
+      defaultContext: { ...this.defaultContext, ...context }
+    });
+  }
+  debug(message, context) {
+    this.log("debug", message, context);
+  }
+  info(message, context) {
+    this.log("info", message, context);
+  }
+  warn(message, context) {
+    this.log("warn", message, context);
+  }
+  error(message, context) {
+    this.log("error", message, context);
+  }
+  log(level, message, context) {
+    if (level === "debug" && !shouldShowDebug(this.scope)) {
+      return;
+    }
+    if (!shouldLog(level, this.minLevel)) {
+      return;
+    }
+    const entry = {
+      level,
+      message,
+      scope: this.scope,
+      context: context || Object.keys(this.defaultContext).length > 0 ? { ...this.defaultContext, ...context } : undefined,
+      timestamp: new Date
+    };
+    this.formatter(entry);
+  }
+}
+function createLogger(options = {}) {
+  return new Logger(options);
+}
+// ../../internal/client-infra/src/auth/token-manager.ts
+function isDebug() {
+  try {
+    const debug = typeof process === "undefined" ? undefined : process.env["DEBUG"];
+    return debug === "1" || debug === "true";
+  } catch {
+    return false;
+  }
+}
+var log = createLogger({ scope: "auth", minLevel: isDebug() ? "debug" : "warn" });
+
+class TokenManager {
+  config;
+  accessToken = null;
+  tokenExpiry = 0;
+  pendingRequest = null;
+  fetchFn;
+  constructor(config) {
+    this.config = config;
+    this.fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  async getToken() {
+    if (this.accessToken && Date.now() < this.tokenExpiry) {
+      log.debug("Using cached token");
+      return this.accessToken;
+    }
+    if (this.pendingRequest) {
+      log.debug("Waiting for in-flight token request");
+      return this.pendingRequest;
+    }
+    this.pendingRequest = this.fetchToken();
+    try {
+      return await this.pendingRequest;
+    } finally {
+      this.pendingRequest = null;
+    }
+  }
+  async fetchToken() {
+    log.debug("Fetching new access token...");
+    const { clientId, clientSecret } = this.config.credentials;
+    const credentials = btoa(`${clientId}:${clientSecret}`);
+    const start = performance.now();
+    const response = await this.fetchFn(this.config.tokenUrl, {
+      method: "POST",
+      headers: {
+        Authorization: `Basic ${credentials}`,
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: "grant_type=client_credentials"
+    });
+    const duration = Math.round(performance.now() - start);
+    if (!response.ok) {
+      log.error(`Token request failed: ${response.status} ${response.statusText}`);
+      throw new Error(`Failed to obtain access token: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    this.accessToken = data.access_token;
+    this.tokenExpiry = Date.now() + (data.expires_in - 60) * 1000;
+    log.debug(`Token acquired (${duration}ms, expires in ${data.expires_in}s)`);
+    return this.accessToken;
+  }
+  invalidate() {
+    log.debug("Token invalidated");
+    this.accessToken = null;
+    this.tokenExpiry = 0;
+  }
+}
+// ../../internal/client-infra/src/config/paths.ts
+var BEYONDAI_PATHS = {
+  caliper: {
+    send: "/caliper/event",
+    validate: "/caliper/event/validate",
+    list: "/caliper/events",
+    get: "/caliper/events/{id}",
+    jobStatus: "/jobs/{id}/status"
+  },
+  oneroster: {
+    rostering: "/ims/oneroster/rostering/v1p2",
+    gradebook: "/ims/oneroster/gradebook/v1p2",
+    resources: "/ims/oneroster/resources/v1p2"
+  },
+  edubridge: {
+    base: "/edubridge"
+  }
+};
+var LEARNWITHAI_PATHS = {
+  caliper: {
+    send: "/events/1.0/",
+    validate: null,
+    list: null,
+    get: null,
+    jobStatus: null
+  },
+  oneroster: {
+    rostering: "/rostering/1.0",
+    gradebook: "/gradebook/1.0",
+    resources: "/resources/1.0"
+  },
+  edubridge: null
+};
+var PLATFORM_PATHS = {
+  BEYOND_AI: BEYONDAI_PATHS,
+  LEARNWITH_AI: LEARNWITHAI_PATHS
+};
+
+// ../../internal/client-infra/src/config/provider.ts
+function isEnvConfig(config) {
+  return "env" in config && !("baseUrl" in config) && !("services" in config);
+}
+function isExplicitConfig(config) {
+  return "baseUrl" in config && !("services" in config);
+}
+function isServicesConfig(config) {
+  return "services" in config;
+}
+function resolvePathProfiles(pathProfile, customPaths) {
+  const basePaths = pathProfile ? PLATFORM_PATHS[pathProfile] ?? BEYONDAI_PATHS : BEYONDAI_PATHS;
+  return {
+    caliper: customPaths?.caliper ?? basePaths.caliper,
+    oneroster: customPaths?.oneroster ?? basePaths.oneroster,
+    edubridge: customPaths?.edubridge ?? basePaths.edubridge
+  };
+}
+
+class TimebackProvider {
+  platform;
+  env;
+  auth;
+  timeout;
+  endpoints;
+  authUrl;
+  pathProfiles;
+  tokenManagers = new Map;
+  constructor(config) {
+    this.timeout = config.timeout ?? 30000;
+    if (isEnvConfig(config)) {
+      this.auth = config.auth;
+      const platform = config.platform ?? DEFAULT_PLATFORM;
+      const env = config.env;
+      this.platform = platform;
+      this.env = env;
+      const platformEndpoints = PLATFORM_ENDPOINTS[platform];
+      if (!platformEndpoints) {
+        throw new Error(`Unknown platform: ${platform}`);
+      }
+      this.authUrl = platformEndpoints.token[env];
+      this.pathProfiles = PLATFORM_PATHS[platform] ?? BEYONDAI_PATHS;
+      this.endpoints = {
+        oneroster: {
+          baseUrl: platformEndpoints.api[env],
+          authUrl: this.authUrl
+        },
+        edubridge: {
+          baseUrl: platformEndpoints.api[env],
+          authUrl: this.authUrl
+        },
+        caliper: {
+          baseUrl: platformEndpoints.caliper[env],
+          authUrl: this.authUrl
+        },
+        qti: {
+          baseUrl: platformEndpoints.qti[env],
+          authUrl: this.authUrl
+        }
+      };
+    } else if (isExplicitConfig(config)) {
+      this.auth = config.auth;
+      this.authUrl = config.authUrl;
+      this.pathProfiles = resolvePathProfiles(config.pathProfile, config.paths);
+      this.endpoints = {
+        oneroster: { baseUrl: config.baseUrl, authUrl: this.authUrl },
+        edubridge: { baseUrl: config.baseUrl, authUrl: this.authUrl },
+        caliper: { baseUrl: config.baseUrl, authUrl: this.authUrl },
+        qti: { baseUrl: config.baseUrl, authUrl: this.authUrl }
+      };
+    } else if (isServicesConfig(config)) {
+      this.auth = config.auth;
+      this.authUrl = config.authUrl;
+      this.pathProfiles = resolvePathProfiles(config.pathProfile, config.paths);
+      this.endpoints = {};
+      for (const [service, baseUrl] of Object.entries(config.services)) {
+        if (baseUrl) {
+          this.endpoints[service] = {
+            baseUrl,
+            authUrl: this.authUrl
+          };
+        }
+      }
+    } else {
+      throw new Error("Invalid provider configuration");
+    }
+  }
+  getEndpoint(service) {
+    const endpoint = this.endpoints[service];
+    if (!endpoint) {
+      throw new Error(`Service "${service}" is not configured in this provider`);
+    }
+    return endpoint;
+  }
+  hasService(service) {
+    return service in this.endpoints;
+  }
+  getAvailableServices() {
+    return Object.keys(this.endpoints);
+  }
+  getTokenUrl() {
+    return this.authUrl;
+  }
+  getEndpointWithPaths(service) {
+    const endpoint = this.getEndpoint(service);
+    const paths = this.getServicePaths(service);
+    return { ...endpoint, paths };
+  }
+  getPaths() {
+    return this.pathProfiles;
+  }
+  getServicePaths(service) {
+    const paths = this.pathProfiles[service];
+    if (!paths) {
+      throw new Error(`Service "${service}" is not supported on ${this.platform ?? "this"} platform.`);
+    }
+    return paths;
+  }
+  hasServiceSupport(service) {
+    return this.pathProfiles[service] !== null;
+  }
+  getTokenProvider(service) {
+    const endpoint = this.getEndpoint(service);
+    const { authUrl } = endpoint;
+    if (!authUrl) {
+      return;
+    }
+    if (!this.auth) {
+      throw new Error(`Service "${service}" requires authentication but no credentials were provided`);
+    }
+    let manager = this.tokenManagers.get(authUrl);
+    if (!manager) {
+      manager = new TokenManager({
+        tokenUrl: authUrl,
+        credentials: {
+          clientId: this.auth.clientId,
+          clientSecret: this.auth.clientSecret
+        }
+      });
+      this.tokenManagers.set(authUrl, manager);
+    }
+    return manager;
+  }
+  async checkAuth() {
+    if (!this.authUrl || !this.auth) {
+      throw new Error("No auth configured on this provider");
+    }
+    const startTime = Date.now();
+    let manager = this.tokenManagers.get(this.authUrl);
+    if (!manager) {
+      manager = new TokenManager({
+        tokenUrl: this.authUrl,
+        credentials: {
+          clientId: this.auth.clientId,
+          clientSecret: this.auth.clientSecret
+        }
+      });
+      this.tokenManagers.set(this.authUrl, manager);
+    }
+    try {
+      await manager.getToken();
+      return {
+        ok: true,
+        latencyMs: Date.now() - startTime,
+        checks: { tokenAcquisition: true }
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        latencyMs: Date.now() - startTime,
+        error: error instanceof Error ? error.message : String(error),
+        checks: { tokenAcquisition: false }
+      };
+    }
+  }
+  invalidateTokens() {
+    for (const manager of this.tokenManagers.values()) {
+      manager.invalidate?.();
+    }
+    this.tokenManagers.clear();
+  }
+}
+// ../../internal/client-infra/src/utils/utils.ts
+function getEnv(key) {
+  try {
+    return typeof process === "undefined" ? undefined : process.env[key];
+  } catch {
+    return;
+  }
+}
+function isDebug2() {
+  const debug = getEnv("DEBUG");
+  return debug === "1" || debug === "true";
+}
+function generateRequestId() {
+  return Math.random().toString(16).slice(2, 10);
+}
+function createScopedLogger(scope) {
+  return createLogger({
+    scope,
+    minLevel: isDebug2() ? "debug" : "warn"
+  });
+}
+// ../../internal/client-infra/src/config/registry.ts
+var DEFAULT_PROVIDER_REGISTRY = {
+  defaultPlatform: DEFAULT_PLATFORM,
+  templates: {
+    BEYOND_AI: {
+      staging: { platform: "BEYOND_AI", env: "staging" },
+      production: { platform: "BEYOND_AI", env: "production" }
+    },
+    LEARNWITH_AI: {
+      staging: { platform: "LEARNWITH_AI", env: "staging" },
+      production: { platform: "LEARNWITH_AI", env: "production" }
+    }
+  }
+};
+
+// ../../internal/client-infra/src/config/resolve.ts
+function validateEnv(env) {
+  if (env !== "staging" && env !== "production") {
+    throw new Error(`Invalid env "${env}": must be "staging" or "production"`);
+  }
+  return env;
+}
+function validateAuth(auth, envVars) {
+  const clientId = auth?.clientId ?? getEnv(envVars.clientId);
+  const clientSecret = auth?.clientSecret ?? getEnv(envVars.clientSecret);
+  if (!clientId) {
+    throw new Error(`Missing clientId: provide in config or set ${envVars.clientId}`);
+  }
+  if (!clientSecret) {
+    throw new Error(`Missing clientSecret: provide in config or set ${envVars.clientSecret}`);
+  }
+  return { clientId, clientSecret };
+}
+function validateAuthOptional(auth, envVars, requireAuth) {
+  if (!requireAuth) {
+    return;
+  }
+  return validateAuth(auth, envVars);
+}
+function buildMissingEnvError(envVars) {
+  const baseUrl = getEnv(envVars.baseUrl);
+  const authUrl = getEnv(envVars.authUrl);
+  const clientId = getEnv(envVars.clientId);
+  const clientSecret = getEnv(envVars.clientSecret);
+  if (baseUrl === undefined && clientId === undefined) {
+    const hint = envVars.env ?? envVars.baseUrl;
+    return `Missing env: provide in config or set ${hint}`;
+  }
+  const missing = [];
+  if (baseUrl === undefined) {
+    missing.push(envVars.env ?? envVars.baseUrl);
+  }
+  if (baseUrl !== undefined && authUrl === undefined) {
+    missing.push(envVars.authUrl);
+  }
+  if (clientId === undefined) {
+    missing.push(envVars.clientId);
+  }
+  if (clientSecret === undefined) {
+    missing.push(envVars.clientSecret);
+  }
+  return `Missing environment variables: ${missing.join(", ")}`;
+}
+var MODE_TRANSPORT = {
+  name: "transport",
+  matches(config) {
+    return "transport" in config && !!config.transport;
+  },
+  resolve(config) {
+    const c = config;
+    return { mode: "transport", transport: c.transport };
+  }
+};
+var MODE_PROVIDER = {
+  name: "provider",
+  matches(config) {
+    return "provider" in config && !!config.provider;
+  },
+  resolve(config) {
+    const c = config;
+    return { mode: "provider", provider: c.provider };
+  }
+};
+var MODE_ENV_CONFIG = {
+  name: "env-config",
+  matches(config) {
+    return "env" in config;
+  },
+  resolve(config, envVars, registry) {
+    const c = config;
+    const env = validateEnv(c.env);
+    const auth = validateAuth(c.auth, envVars);
+    const platform = c.platform ?? registry.defaultPlatform;
+    const platformTemplates = registry.templates[platform];
+    if (!platformTemplates) {
+      const available = Object.keys(registry.templates).join(", ");
+      throw new Error(`Unknown platform "${platform}": available platforms are ${available}`);
+    }
+    const template = platformTemplates[env];
+    if (!template) {
+      const available = Object.keys(platformTemplates).join(", ");
+      throw new Error(`Unknown env "${env}" for platform "${platform}": available environments are ${available}`);
+    }
+    return {
+      mode: "provider",
+      provider: new TimebackProvider({
+        platform: template.platform,
+        env: template.env,
+        auth,
+        timeout: c.timeout
+      })
+    };
+  }
+};
+var MODE_EXPLICIT_CONFIG = {
+  name: "explicit-config",
+  matches(config) {
+    return "baseUrl" in config;
+  },
+  resolve(config, envVars) {
+    const c = config;
+    const authUrl = c.authUrl ?? c.auth?.authUrl;
+    const requireAuth = !!authUrl;
+    const auth = validateAuthOptional(c.auth, envVars, requireAuth);
+    return {
+      mode: "provider",
+      provider: new TimebackProvider({
+        baseUrl: c.baseUrl,
+        authUrl,
+        auth,
+        timeout: c.timeout,
+        pathProfile: c.pathProfile,
+        paths: c.paths
+      })
+    };
+  }
+};
+var MODE_ENV_FALLBACK_PLATFORM = {
+  name: "env-fallback-platform",
+  matches(config, envVars) {
+    if (Object.keys(config).length > 0)
+      return false;
+    const env = envVars.env ? getEnv(envVars.env) : undefined;
+    const clientId = getEnv(envVars.clientId);
+    const clientSecret = getEnv(envVars.clientSecret);
+    return env !== undefined && clientId !== undefined && clientSecret !== undefined;
+  },
+  resolve(_config, envVars, registry) {
+    const env = validateEnv(getEnv(envVars.env));
+    const clientId = getEnv(envVars.clientId);
+    const clientSecret = getEnv(envVars.clientSecret);
+    const platform = registry.defaultPlatform;
+    const template = registry.templates[platform]?.[env];
+    if (!template) {
+      throw new Error(`Unknown env "${env}" for platform "${platform}"`);
+    }
+    return {
+      mode: "provider",
+      provider: new TimebackProvider({
+        platform: template.platform,
+        env: template.env,
+        auth: { clientId, clientSecret }
+      })
+    };
+  }
+};
+var MODE_ENV_FALLBACK_EXPLICIT = {
+  name: "env-fallback-explicit",
+  matches(config, envVars) {
+    if (Object.keys(config).length > 0)
+      return false;
+    const baseUrl = getEnv(envVars.baseUrl);
+    const authUrl = getEnv(envVars.authUrl);
+    const clientId = getEnv(envVars.clientId);
+    const clientSecret = getEnv(envVars.clientSecret);
+    return baseUrl !== undefined && authUrl !== undefined && clientId !== undefined && clientSecret !== undefined;
+  },
+  resolve(_config, envVars) {
+    const baseUrl = getEnv(envVars.baseUrl);
+    const authUrl = getEnv(envVars.authUrl);
+    const clientId = getEnv(envVars.clientId);
+    const clientSecret = getEnv(envVars.clientSecret);
+    return {
+      mode: "provider",
+      provider: new TimebackProvider({
+        baseUrl,
+        authUrl,
+        auth: { clientId, clientSecret }
+      })
+    };
+  }
+};
+var MODE_TOKEN_PROVIDER = {
+  name: "token-provider",
+  matches(config) {
+    return "tokenProvider" in config;
+  },
+  resolve() {
+    throw new Error("TokenProvider mode is not supported with provider pattern. " + "Use { provider: TimebackProvider } or { env, auth } instead.");
+  }
+};
+var MODES = [
+  MODE_TRANSPORT,
+  MODE_PROVIDER,
+  MODE_ENV_CONFIG,
+  MODE_TOKEN_PROVIDER,
+  MODE_EXPLICIT_CONFIG,
+  MODE_ENV_FALLBACK_PLATFORM,
+  MODE_ENV_FALLBACK_EXPLICIT
+];
+function resolveToProvider(config, envVars, registry = DEFAULT_PROVIDER_REGISTRY) {
+  for (const mode of MODES) {
+    if (mode.matches(config, envVars)) {
+      return mode.resolve(config, envVars, registry);
+    }
+  }
+  throw new Error(buildMissingEnvError(envVars));
+}
+// ../../internal/client-infra/src/errors/errors.ts
+class ApiError extends Error {
+  statusCode;
+  response;
+  name = "ApiError";
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+  }
+  get minorCodes() {
+    const ims = this.response;
+    if (!ims?.imsx_CodeMinor?.imsx_codeMinorField) {
+      return [];
+    }
+    return ims.imsx_CodeMinor.imsx_codeMinorField.map((field) => ({
+      field: field.imsx_codeMinorFieldName,
+      value: field.imsx_codeMinorFieldValue
+    }));
+  }
+  get details() {
+    const ims = this.response;
+    return ims?.imsx_error_details ?? [];
+  }
+}
+
+class UnauthorizedError extends ApiError {
+  name = "UnauthorizedError";
+  constructor(message = "Unauthorized", response) {
+    super(message, 401, response);
+  }
+}
+
+class ForbiddenError extends ApiError {
+  name = "ForbiddenError";
+  constructor(message = "Forbidden", response) {
+    super(message, 403, response);
+  }
+}
+
+class NotFoundError extends ApiError {
+  name = "NotFoundError";
+  constructor(message = "Not Found", response) {
+    super(message, 404, response);
+  }
+}
+
+class ValidationError extends ApiError {
+  name = "ValidationError";
+  constructor(message = "Validation Error", response) {
+    super(message, 422, response);
+  }
+}
+// ../../internal/client-infra/src/transport/constants.ts
+var MAX_RETRIES = 3;
+var RETRY_STATUS_CODES = [429, 503];
+var INITIAL_RETRY_DELAY_MS = 1000;
+
+// ../../internal/client-infra/src/transport/transport.ts
+class BaseTransport {
+  config;
+  log;
+  constructor(options) {
+    const { config, logger } = options;
+    const fetchFn = config.fetch ?? globalThis.fetch.bind(globalThis);
+    let tokenProvider;
+    if ("tokenProvider" in config && config.tokenProvider) {
+      tokenProvider = config.tokenProvider;
+    } else if ("auth" in config && config.auth) {
+      tokenProvider = new TokenManager({
+        tokenUrl: config.auth.authUrl,
+        credentials: {
+          clientId: config.auth.clientId,
+          clientSecret: config.auth.clientSecret
+        },
+        fetch: fetchFn
+      });
+    }
+    this.config = {
+      baseUrl: config.baseUrl,
+      timeout: config.timeout ?? 30000,
+      fetch: fetchFn,
+      tokenProvider
+    };
+    this.log = logger.child("http");
+  }
+  get baseUrl() {
+    return this.config.baseUrl;
+  }
+  async request(path, options = {}) {
+    const response = await this.requestRaw(path, options);
+    return this.handleResponse(response);
+  }
+  async requestRaw(path, options = {}) {
+    const { method = "GET", params, body, headers = {} } = options;
+    const url = this.buildUrl(path, params);
+    const requestId = options.requestId ?? generateRequestId();
+    const operationStart = Date.now();
+    const operationDeadline = operationStart + this.config.timeout;
+    for (let attempt = 0;attempt < MAX_RETRIES; attempt++) {
+      const remainingTime = operationDeadline - Date.now();
+      if (remainingTime <= 0) {
+        this.log.error("Request timeout before attempt", isDebug2() ? { requestId, path } : { path });
+        throw new ApiError("Request timeout", 408);
+      }
+      const token = await this.getAccessToken();
+      const isLastAttempt = attempt === MAX_RETRIES - 1;
+      const start = performance.now();
+      this.log.debug(`→ ${method} ${url}`, {
+        requestId,
+        attempt: attempt > 0 ? attempt + 1 : undefined
+      });
+      const requestHeaders = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "X-Request-ID": requestId,
+        ...headers
+      };
+      if (token) {
+        requestHeaders.Authorization = `Bearer ${token}`;
+      }
+      const response = await this.config.fetch(url, {
+        method,
+        headers: requestHeaders,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(Math.min(remainingTime, this.config.timeout))
+      });
+      const duration = Math.round(performance.now() - start);
+      this.log.debug(`← ${response.status} ${response.statusText} (${duration}ms)`, {
+        requestId
+      });
+      const shouldRetry = RETRY_STATUS_CODES.includes(response.status) && !isLastAttempt;
+      if (shouldRetry) {
+        const retryAfter = response.headers.get("Retry-After");
+        const delayMs = this.parseRetryAfter(retryAfter, attempt);
+        const timeRemaining = operationDeadline - Date.now();
+        if (delayMs >= timeRemaining) {
+          this.log.error("Request timeout during retry backoff", isDebug2() ? { requestId, path } : { path });
+          throw new ApiError("Request timeout", 408);
+        }
+        this.log.warn(`Retrying in ${delayMs}ms (attempt ${attempt + 1}/${MAX_RETRIES})`, {
+          ...isDebug2() && { requestId },
+          status: response.status
+        });
+        await this.sleep(delayMs);
+        continue;
+      }
+      if (!response.ok) {
+        return this.handleErrorResponse(response, requestId);
+      }
+      return response;
+    }
+    this.log.error("Max retries exceeded", isDebug2() ? { requestId, path } : { path });
+    throw new ApiError("Max retries exceeded");
+  }
+  getAccessToken() {
+    if (!this.config.tokenProvider) {
+      return Promise.resolve(undefined);
+    }
+    return this.config.tokenProvider.getToken();
+  }
+  buildUrl(path, params) {
+    if (/^[a-z][a-z0-9+.-]*:/i.test(path)) {
+      throw new Error(`Absolute URLs are not allowed in path: ${path}. Use relative paths only.`);
+    }
+    const url = new URL(path, this.config.baseUrl);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  async handleResponse(response) {
+    if (!response.ok) {
+      await this.handleErrorResponse(response);
+    }
+    if (response.status === 204) {
+      return;
+    }
+    const contentLength = response.headers.get("content-length");
+    if (contentLength === "0") {
+      return;
+    }
+    return this.parseJsonResponse(response);
+  }
+  async parseJsonResponse(response) {
+    const text = await response.text();
+    if (!text || text.trim() === "") {
+      return;
+    }
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      const preview = text.length > 200 ? text.slice(0, 200) + "..." : text;
+      const parseError = error instanceof Error ? error.message : String(error);
+      const url = response.url || "unknown";
+      this.log.error("Failed to parse JSON response", {
+        url,
+        status: response.status,
+        contentType: response.headers.get("content-type"),
+        bodyPreview: preview,
+        error: parseError
+      });
+      throw new ApiError(`Invalid JSON response from ${url}`, response.status, {
+        parseError,
+        body: preview
+      });
+    }
+  }
+  async handleErrorResponse(response, requestId) {
+    let errorBody;
+    const text = await response.text().catch(() => "");
+    if (text) {
+      try {
+        errorBody = JSON.parse(text);
+      } catch (parseError) {
+        const parseWarning = parseError instanceof Error ? parseError.message : "Unknown parse error";
+        errorBody = { rawBody: text.slice(0, 500), parseError: parseWarning };
+        this.log.warn("Failed to parse error response as JSON", {
+          ...isDebug2() && { requestId },
+          url: response.url,
+          status: response.status,
+          parseError: parseWarning,
+          bodyPreview: text.slice(0, 200)
+        });
+      }
+    }
+    const message = this.extractErrorMessage(errorBody, response.statusText);
+    if (response.status !== 404) {
+      this.log.error(`Request failed: ${response.status} ${message}`, isDebug2() ? { requestId } : undefined);
+    }
+    switch (response.status) {
+      case 401:
+        this.config.tokenProvider?.invalidate?.();
+        throw new UnauthorizedError(message, errorBody);
+      case 403:
+        throw new ForbiddenError(message, errorBody);
+      case 404:
+        throw new NotFoundError(message, errorBody);
+      case 422:
+        throw new ValidationError(message, errorBody);
+      default:
+        throw new ApiError(message, response.status, errorBody);
+    }
+  }
+  extractErrorMessage(body, fallback) {
+    if (typeof body === "object" && body !== null) {
+      const obj = body;
+      if (typeof obj.message === "string")
+        return obj.message;
+      if (typeof obj.error === "string")
+        return obj.error;
+      if (typeof obj.imsx_description === "string")
+        return obj.imsx_description;
+    }
+    return fallback;
+  }
+  sleep(ms) {
+    return new Promise((resolve) => {
+      setTimeout(resolve, ms);
+    });
+  }
+  parseRetryAfter(retryAfter, attempt) {
+    if (!retryAfter) {
+      return INITIAL_RETRY_DELAY_MS * Math.pow(2, attempt);
+    }
+    const seconds = parseInt(retryAfter, 10);
+    if (!isNaN(seconds)) {
+      return seconds * 1000;
+    }
+    const date = Date.parse(retryAfter);
+    if (!isNaN(date)) {
+      const delayMs = date - Date.now();
+      return Math.max(0, delayMs);
+    }
+    return INITIAL_RETRY_DELAY_MS * Math.pow(2, attempt);
+  }
+}
+// ../../internal/client-infra/src/filter/where/where.ts
+function escapeValue(value) {
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  if (typeof value === "number") {
+    return String(value);
+  }
+  return value.replaceAll("'", "''");
+}
+function formatValue2(value) {
+  const escaped = escapeValue(value);
+  const needsQuotes = typeof value === "string" || value instanceof Date;
+  return needsQuotes ? `'${escaped}'` : escaped;
+}
+function fieldToConditions(field, condition) {
+  if (typeof condition === "string" || typeof condition === "number" || typeof condition === "boolean" || condition instanceof Date) {
+    return [`${field}=${formatValue2(condition)}`];
+  }
+  if (typeof condition === "object" && condition !== null) {
+    const ops = condition;
+    const conditions = [];
+    if (ops.ne !== undefined) {
+      conditions.push(`${field}!=${formatValue2(ops.ne)}`);
+    }
+    if (ops.gt !== undefined) {
+      conditions.push(`${field}>${formatValue2(ops.gt)}`);
+    }
+    if (ops.gte !== undefined) {
+      conditions.push(`${field}>=${formatValue2(ops.gte)}`);
+    }
+    if (ops.lt !== undefined) {
+      conditions.push(`${field}<${formatValue2(ops.lt)}`);
+    }
+    if (ops.lte !== undefined) {
+      conditions.push(`${field}<=${formatValue2(ops.lte)}`);
+    }
+    if (ops.contains !== undefined) {
+      conditions.push(`${field}~${formatValue2(ops.contains)}`);
+    }
+    if (ops.in !== undefined && ops.in.length > 0) {
+      const inConditions = ops.in.map((v) => `${field}=${formatValue2(v)}`);
+      const joined = inConditions.join(" OR ");
+      conditions.push(inConditions.length > 1 ? `(${joined})` : joined);
+    }
+    if (ops.notIn !== undefined && ops.notIn.length > 0) {
+      const notInConditions = ops.notIn.map((v) => `${field}!=${formatValue2(v)}`);
+      conditions.push(notInConditions.join(" AND "));
+    }
+    return conditions;
+  }
+  return [];
+}
+function isOrCondition(clause) {
+  return "OR" in clause && Array.isArray(clause.OR);
+}
+function whereToFilter(where) {
+  if (isOrCondition(where)) {
+    const orParts = where.OR.map((clause) => whereToFilter(clause)).filter((s) => s !== undefined);
+    return orParts.length > 0 ? orParts.join(" OR ") : undefined;
+  }
+  const conditions = [];
+  for (const [field, condition] of Object.entries(where)) {
+    if (condition !== undefined) {
+      conditions.push(...fieldToConditions(field, condition));
+    }
+  }
+  return conditions.length > 0 ? conditions.join(" AND ") : undefined;
+}
+// ../../internal/client-infra/src/pagination/pagination.ts
+var DEFAULT_LIMIT = 100;
+var DEFAULT_MAX_ITEMS = 1e4;
+
+class Paginator {
+  fetcher;
+  path;
+  params;
+  max;
+  unwrapKey;
+  log;
+  transform;
+  constructor(options) {
+    this.fetcher = options.fetcher;
+    this.path = options.path;
+    this.params = options.params ?? {};
+    this.max = options.max;
+    this.unwrapKey = options.unwrapKey;
+    this.log = options.logger?.child("pagination") ?? createScopedLogger("pagination");
+    this.transform = options.transform;
+  }
+  buildRequestParams(limit, offset) {
+    const { where, fields, ...rest } = this.params;
+    return {
+      ...rest,
+      filter: where ? whereToFilter(where) : undefined,
+      fields: fields?.join(","),
+      limit,
+      offset
+    };
+  }
+  extractItems(data, pageNumber) {
+    let items;
+    if (this.unwrapKey) {
+      const wrapped = data;
+      items = wrapped[this.unwrapKey] ?? [];
+    } else {
+      items = data;
+    }
+    return this.validateItems(items, pageNumber);
+  }
+  validateItems(data, pageNumber) {
+    if (data === null || data === undefined) {
+      this.log.warn(`Page ${pageNumber}: response data is ${data}, treating as empty`);
+      return [];
+    }
+    if (!Array.isArray(data)) {
+      const type = typeof data;
+      throw new Error(`Expected array for page ${pageNumber}, got ${type}. ` + (this.unwrapKey ? `Check unwrapKey '${this.unwrapKey}' is correct.` : ""));
+    }
+    return data;
+  }
+  hasMorePages(response, itemCount, offset, limit) {
+    if (itemCount === 0) {
+      return false;
+    }
+    const hasMoreFromLink = response.hasMore;
+    const hasMoreFromTotal = response.total !== undefined && offset + itemCount < response.total;
+    const hasMoreFromPageSize = itemCount === limit;
+    return hasMoreFromLink || hasMoreFromTotal || hasMoreFromPageSize && response.total === undefined;
+  }
+  async* [Symbol.asyncIterator]() {
+    let offset = this.params.offset ?? 0;
+    const limit = this.params.limit ?? DEFAULT_LIMIT;
+    let hasMore = true;
+    let pageNumber = 1;
+    let totalYielded = 0;
+    while (hasMore) {
+      this.log.debug(`Fetching page ${pageNumber} (offset: ${offset}, limit: ${limit})`);
+      const response = await this.fetcher(this.path, {
+        params: this.buildRequestParams(limit, offset)
+      });
+      const items = this.extractItems(response.data, pageNumber);
+      this.log.debug(`Page ${pageNumber}: ${items.length} items`);
+      for (const item of items) {
+        yield this.transform ? this.transform(item) : item;
+        totalYielded++;
+        if (this.max !== undefined && totalYielded >= this.max) {
+          this.log.debug(`Pagination complete: reached max of ${this.max} items`);
+          return;
+        }
+      }
+      hasMore = this.hasMorePages(response, items.length, offset, limit);
+      offset += items.length;
+      pageNumber++;
+    }
+    this.log.debug(`Pagination complete: ${totalYielded} total items`);
+  }
+  async toArray(options = {}) {
+    const maxItems = options.maxItems ?? DEFAULT_MAX_ITEMS;
+    const items = [];
+    for await (const item of this) {
+      if (items.length >= maxItems) {
+        throw new Error(`toArray() exceeded maxItems limit of ${maxItems}. ` + `Use 'for await...of' to stream large datasets, or increase maxItems.`);
+      }
+      items.push(item);
+    }
+    return items;
+  }
+  async firstPage() {
+    const limit = this.params.limit ?? DEFAULT_LIMIT;
+    const offset = this.params.offset ?? 0;
+    const response = await this.fetcher(this.path, {
+      params: this.buildRequestParams(limit, offset)
+    });
+    const rawItems = this.extractItems(response.data, 1);
+    const items = this.transform ? rawItems.map(this.transform) : rawItems;
+    const hasMore = this.hasMorePages(response, items.length, offset, limit);
+    this.log.debug(`First page: ${items.length} items, total: ${response.total}, hasMore: ${hasMore}`);
+    return {
+      data: items,
+      hasMore,
+      total: response.total,
+      nextOffset: hasMore ? offset + items.length : undefined
+    };
+  }
+}
+// ../../internal/client-infra/src/pagination/strategies.ts
+function hasNextLink(linkHeader) {
+  if (!linkHeader)
+    return false;
+  return /rel=["']?next["']?(?:\s|;|,|$)/i.test(linkHeader);
+}
+function parseHeaderPagination(response, data) {
+  const linkHeader = response.headers.get("Link");
+  const totalHeader = response.headers.get("X-Total-Count");
+  const parsedTotal = totalHeader ? parseInt(totalHeader, 10) : undefined;
+  const total = parsedTotal !== undefined && !Number.isNaN(parsedTotal) ? parsedTotal : undefined;
+  return {
+    data,
+    hasMore: hasNextLink(linkHeader),
+    total
+  };
+}
+export {
+  ValidationError,
+  UnauthorizedError,
+  ApiError as OneRosterError,
+  NotFoundError,
+  ForbiddenError
+};