simcapture-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 georgegiosue
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# simcapture-sdk
+
+SimCapture API client shared across the UPCH Simulation Center microservices
+and frontends. Replaces the per-service hand-rolled `axios` + login code that was
+duplicated across SIMCAPTURE-MS, REPORT-MS, ENGINEERING-MS and the frontend.
+
+Published to GitHub Packages under the `@upch` scope. Add an `.npmrc`:
+
+```
+@upch:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+```bash
+npm install simcapture-sdk
+```
+
+## Usage
+
+```ts
+import { SimCaptureClient, SimCaptureError } from "simcapture-sdk";
+
+const sc = new SimCaptureClient({
+  apiUrl: process.env.SIMCAPTURE_API!,            // https://api.simcapture.com
+  inventoryUrl: process.env.SIMCAPTURE_INVENTORY_API!,
+  credentials: {
+    username: process.env.SIMCAPTURE_USER!,
+    password: process.env.SIMCAPTURE_PASSWORD!,
+    // clientSubdomain defaults to "simulacion-upch"
+  },
+});
+
+const orgs = await sc.organizations.findAll();
+const reservations = await sc.reservations.findAll({
+  endAfterTs: "2025-07-01T05:00:00.000Z",
+  startBeforeTs: "2026-12-31T05:00:00.000Z",
+});
+
+try {
+  await sc.reservations.findOne("bad-id");
+} catch (e) {
+  if (e instanceof SimCaptureError) {
+    console.error(e.status, e.code, e.body); // real upstream status, not a blanket 400
+  }
+}
+```
+
+### Resources
+
+| Resource | Methods |
+|---|---|
+| `organizations` | `findAll` |
+| `locations` | `findAll` |
+| `reservations` | `findAll`, `findOne`, `update`, `updateDetails`, `delete` |
+| `courses` | `find`, `getItems` |
+| `scenarios` | `findOne`, `updateSetup`, `updateDetails`, `getAttachment` |
+| `simulators` | `findAll`, `findOne`, `update`, `getConfig` |
+| `notifications` | `send` |
+| `inventory` | `findAll`, `findOne`, `edit` *(inventory server)* |
+
+## Auth behaviour
+
+- Tokens are cached and reused until a soft TTL (`tokenTtlMs`, default 30 min) elapses.
+- A `401` clears the cache, re-logins **once**, and retries the failed request once.
+- Concurrent callers share a single in-flight `/auth` request.
+
+## Architecture (DDD)
+
+```
+domain/          entities, value-objects, ports (HttpClient, TokenStore), models, errors
+application/     use-cases: Authenticator + one resource class per domain
+infrastructure/  axios transport adapter + in-memory token store
+config/          SimCaptureConfig + resolution/validation
+client.ts        composition root wiring infra → application
+```
+
+```mermaid
+flowchart TB
+    Consumer["Consumer (MS / frontend)"] --> Client["SimCaptureClient<br/>(composition root)"]
+
+    subgraph application["application"]
+        Resources["Resources<br/>reservations · scenarios · …"]
+        Auth["Authenticator<br/>token cache · 401 retry"]
+    end
+
+    subgraph domain["domain (no deps)"]
+        Ports["Ports<br/>HttpClient · TokenStore"]
+        Models["Models · VOs · SimCaptureError"]
+    end
+
+    subgraph infrastructure["infrastructure"]
+        Axios["AxiosHttpClient"]
+        Store["InMemoryTokenStore"]
+    end
+
+    Client --> Resources
+    Client --> Auth
+    Resources --> Auth
+    Resources -.depends on.-> Ports
+    Auth -.depends on.-> Ports
+    Auth --> Models
+
+    Axios -.implements.-> Ports
+    Store -.implements.-> Ports
+    Axios --> SimCapture["SimCapture API<br/>api + inventory servers"]
+
+    Client -. injects .-> Axios
+    Client -. injects .-> Store
+```
+
+Dependencies point inward — the domain/application layers depend only on the
+`HttpClient`/`TokenStore` ports, so they are unit-tested with fakes (no network).
+Advanced consumers can inject their own transport or a shared token store via the
+second `SimCaptureClient` constructor argument.
+
+## Development (Bun)
+
+```bash
+bun install
+bun run typecheck   # tsc --noEmit (strict)
+bun test            # unit tests against the ports (no real network)
+bun run build       # tsup → ESM + CJS + .d.ts in dist/ (Node-compatible)
+```
+
+The published artifact is built with `tsup` for Node ≥18 (ESM + CJS + types). Bun is
+the dev/build/test toolchain only — there are no `bun:*` imports in shipped code.

package/dist/index.cjs

@@ -0,0 +1,549 @@
+'use strict';
+
+var axios = require('axios');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var axios__default = /*#__PURE__*/_interopDefault(axios);
+
+// src/domain/errors/simcapture-error.ts
+var SimCaptureError = class _SimCaptureError extends Error {
+  /** HTTP status returned by SimCapture, or 0 when the request never completed. */
+  status;
+  /** Stable machine-readable code for branching (e.g. `AUTH_FAILED`). */
+  code;
+  /** Raw upstream response body, when available. */
+  body;
+  constructor(params) {
+    super(params.message, params.cause !== void 0 ? { cause: params.cause } : void 0);
+    this.name = "SimCaptureError";
+    this.status = params.status;
+    this.code = params.code;
+    this.body = params.body ?? null;
+    Object.setPrototypeOf(this, _SimCaptureError.prototype);
+  }
+};
+
+// src/domain/auth/auth-credentials.vo.ts
+var AuthCredentials = class _AuthCredentials {
+  static DEFAULT_SUBDOMAIN = "simulacion-upch";
+  username;
+  password;
+  clientSubdomain;
+  constructor(params) {
+    if (!params.username) {
+      throw new SimCaptureError({
+        message: "SimCapture credentials: `username` is required.",
+        status: 0,
+        code: "CONFIG_INVALID"
+      });
+    }
+    if (!params.password) {
+      throw new SimCaptureError({
+        message: "SimCapture credentials: `password` is required.",
+        status: 0,
+        code: "CONFIG_INVALID"
+      });
+    }
+    this.username = params.username;
+    this.password = params.password;
+    this.clientSubdomain = params.clientSubdomain ?? _AuthCredentials.DEFAULT_SUBDOMAIN;
+  }
+  toAuthRequest() {
+    return {
+      username: this.username,
+      password: this.password,
+      clientSubdomain: this.clientSubdomain
+    };
+  }
+};
+
+// src/domain/auth/token.vo.ts
+var Token = class _Token {
+  value;
+  /** Epoch ms after which the token is considered stale, or null when no TTL. */
+  expiresAt;
+  constructor(value, expiresAt = null) {
+    this.value = value;
+    this.expiresAt = expiresAt;
+  }
+  static issue(value, ttlMs, now = Date.now()) {
+    const expiresAt = ttlMs > 0 ? now + ttlMs : null;
+    return new _Token(value, expiresAt);
+  }
+  isExpired(now = Date.now()) {
+    return this.expiresAt !== null && now >= this.expiresAt;
+  }
+};
+
+// src/application/auth/authenticator.ts
+var Authenticator = class {
+  http;
+  store;
+  credentials;
+  tokenTtlMs;
+  now;
+  inFlightLogin = null;
+  constructor(options) {
+    this.http = options.http;
+    this.store = options.store;
+    this.credentials = options.credentials;
+    this.tokenTtlMs = options.tokenTtlMs;
+    this.now = options.now ?? Date.now;
+  }
+  /** Returns a valid token, logging in only when none is cached or it is stale. */
+  async getToken() {
+    const cached = this.store.get();
+    if (cached && !cached.isExpired(this.now())) return cached;
+    return this.login();
+  }
+  /** Forces a fresh login, deduping concurrent calls into one `/auth` request. */
+  async login() {
+    if (this.inFlightLogin) return this.inFlightLogin;
+    this.inFlightLogin = this.requestToken().then((token) => {
+      this.store.set(token);
+      return token;
+    }).finally(() => {
+      this.inFlightLogin = null;
+    });
+    return this.inFlightLogin;
+  }
+  /**
+   * Sends `req` with the cached token attached. On a 401 it refreshes the token
+   * once and retries the request a single time; a second 401 propagates.
+   */
+  async authorizedRequest(req) {
+    const token = await this.getToken();
+    try {
+      return await this.http.request(withToken(req, token.value));
+    } catch (error) {
+      if (!isUnauthorized(error)) throw error;
+      this.store.clear();
+      const fresh = await this.login();
+      return this.http.request(withToken(req, fresh.value));
+    }
+  }
+  async requestToken() {
+    const response = await this.http.request({
+      method: "POST",
+      path: "/auth",
+      body: this.credentials.toAuthRequest(),
+      skipAuth: true
+    });
+    const value = response.data?.token;
+    if (!value) {
+      throw new SimCaptureError({
+        message: "SimCapture /auth did not return a token.",
+        status: response.status,
+        code: "AUTH_FAILED",
+        body: response.data
+      });
+    }
+    return Token.issue(value, this.tokenTtlMs, this.now());
+  }
+};
+function withToken(req, token) {
+  return { ...req, headers: { ...req.headers, token } };
+}
+function isUnauthorized(error) {
+  return error instanceof SimCaptureError && error.status === 401;
+}
+
+// src/application/resources/base.resource.ts
+var BaseResource = class {
+  constructor(auth) {
+    this.auth = auth;
+  }
+  auth;
+  async exec(req) {
+    const response = await this.auth.authorizedRequest(req);
+    return response.data;
+  }
+};
+
+// src/application/resources/courses.resource.ts
+var CoursesResource = class extends BaseResource {
+  constructor(auth) {
+    super(auth);
+  }
+  /** `POST /courses` — one page of results. */
+  find(query) {
+    return this.exec({ method: "POST", path: "/courses", body: query });
+  }
+  /** `GET /courses/{courseId}/items` — scenarios / evaluation templates. */
+  getItems(courseId, params = {}) {
+    return this.exec({
+      method: "GET",
+      path: `/courses/${encodeURIComponent(courseId)}/items`,
+      query: {
+        includeScenarios: params.includeScenarios,
+        includeEvaluationTemplates: params.includeEvaluationTemplates,
+        hasScenarioReflections: params.hasScenarioReflections,
+        hasScenarioEvaluations: params.hasScenarioEvaluations
+      }
+    });
+  }
+};
+
+// src/application/resources/inventory.resource.ts
+var InventoryResource = class extends BaseResource {
+  constructor(auth) {
+    super(auth);
+  }
+  /** `GET /items` (server B) */
+  findAll() {
+    return this.exec({ method: "GET", path: "/items", server: "inventory" });
+  }
+  /** `GET /item/{itemId}` (server B) */
+  findOne(itemId) {
+    return this.exec({
+      method: "GET",
+      path: `/item/${encodeURIComponent(itemId)}`,
+      server: "inventory"
+    });
+  }
+  /** `POST /item/{itemId}/edit` (server B) — stock adjustment. */
+  edit(itemId, body) {
+    return this.exec({
+      method: "POST",
+      path: `/item/${encodeURIComponent(itemId)}/edit`,
+      server: "inventory",
+      body
+    });
+  }
+};
+
+// src/application/resources/locations.resource.ts
+var LocationsResource = class extends BaseResource {
+  constructor(auth) {
+    super(auth);
+  }
+  /** `GET /locations?order=...` */
+  findAll(params = {}) {
+    return this.exec({
+      method: "GET",
+      path: "/locations",
+      query: { order: params.order }
+    });
+  }
+};
+
+// src/application/resources/notifications.resource.ts
+var NotificationsResource = class extends BaseResource {
+  constructor(auth) {
+    super(auth);
+  }
+  /** `POST /notifications` — send an email / notification. */
+  send(body) {
+    return this.exec({ method: "POST", path: "/notifications", body });
+  }
+};
+
+// src/application/resources/organizations.resource.ts
+var OrganizationsResource = class extends BaseResource {
+  constructor(auth) {
+    super(auth);
+  }
+  /** `GET /organizations` */
+  findAll() {
+    return this.exec({ method: "GET", path: "/organizations" });
+  }
+};
+
+// src/application/resources/reservations.resource.ts
+var ReservationsResource = class extends BaseResource {
+  constructor(auth) {
+    super(auth);
+  }
+  /** `GET /reservations?endAfterTs=&startBeforeTs=&limitFetchedReservationDetails=` */
+  findAll(params) {
+    return this.exec({
+      method: "GET",
+      path: "/reservations",
+      query: {
+        endAfterTs: params.endAfterTs,
+        startBeforeTs: params.startBeforeTs,
+        limitFetchedReservationDetails: params.limitFetchedReservationDetails ?? false
+      }
+    });
+  }
+  /** `GET /reservation/{id}` */
+  findOne(reservationId) {
+    return this.exec({
+      method: "GET",
+      path: `/reservation/${encodeURIComponent(reservationId)}`
+    });
+  }
+  /** `PUT /reservation/{id}` — overview or setup update. */
+  update(reservationId, body) {
+    return this.exec({
+      method: "PUT",
+      path: `/reservation/${encodeURIComponent(reservationId)}`,
+      body
+    });
+  }
+  /** `PUT /reservation/{id}/details` (ENGINEERING-MS flow). */
+  updateDetails(reservationId, body) {
+    return this.exec({
+      method: "PUT",
+      path: `/reservation/${encodeURIComponent(reservationId)}/details`,
+      body
+    });
+  }
+  /** `DELETE /reservation/{id}` */
+  delete(reservationId) {
+    return this.exec({
+      method: "DELETE",
+      path: `/reservation/${encodeURIComponent(reservationId)}`
+    });
+  }
+};
+
+// src/application/resources/scenarios.resource.ts
+var ScenariosResource = class extends BaseResource {
+  constructor(auth) {
+    super(auth);
+  }
+  /** `GET /scenarios/{id}` */
+  findOne(scenarioId) {
+    return this.exec({
+      method: "GET",
+      path: `/scenarios/${encodeURIComponent(scenarioId)}`
+    });
+  }
+  /** `PUT /scenarios/{id}` — setup update. */
+  updateSetup(scenarioId, body) {
+    return this.exec({
+      method: "PUT",
+      path: `/scenarios/${encodeURIComponent(scenarioId)}`,
+      body
+    });
+  }
+  /** `PUT /scenarios/{id}/details` — detail update. */
+  updateDetails(scenarioId, body) {
+    return this.exec({
+      method: "PUT",
+      path: `/scenarios/${encodeURIComponent(scenarioId)}/details`,
+      body
+    });
+  }
+  /**
+   * `GET /scenarios/{id}/attachments/{assetName}` — returns the raw PDF bytes.
+   * The token is sent both as a query param and the header (matching the API).
+   */
+  async getAttachment(scenarioId, assetName, params) {
+    const token = await this.auth.getToken();
+    const response = await this.auth.authorizedRequest({
+      method: "GET",
+      path: `/scenarios/${encodeURIComponent(scenarioId)}/attachments/${encodeURIComponent(assetName)}`,
+      query: { "client-id": params.clientId, token: token.value },
+      responseType: "blob"
+    });
+    return response.data;
+  }
+};
+
+// src/application/resources/simulators.resource.ts
+var SimulatorsResource = class extends BaseResource {
+  constructor(auth) {
+    super(auth);
+  }
+  /** `GET /simulators` */
+  findAll() {
+    return this.exec({ method: "GET", path: "/simulators" });
+  }
+  /** `GET /simulators/{id}` */
+  findOne(simulatorId) {
+    return this.exec({
+      method: "GET",
+      path: `/simulators/${encodeURIComponent(simulatorId)}`
+    });
+  }
+  /** `PUT /simulators/{id}` */
+  update(simulatorId, body) {
+    return this.exec({
+      method: "PUT",
+      path: `/simulators/${encodeURIComponent(simulatorId)}`,
+      body
+    });
+  }
+  /** `GET /simulator-configs/{id}` */
+  getConfig(simulatorId) {
+    return this.exec({
+      method: "GET",
+      path: `/simulator-configs/${encodeURIComponent(simulatorId)}`
+    });
+  }
+};
+
+// src/config/sdk-config.ts
+var SIMCAPTURE_DEFAULTS = {
+  apiUrl: "https://api.simcapture.com",
+  inventoryUrl: "https://inventory-management-production.us-east-1.simcapture.com",
+  tokenTtlMs: 30 * 60 * 1e3,
+  timeoutMs: 30 * 1e3
+};
+function resolveConfig(config) {
+  const apiUrl = stripTrailingSlash(config.apiUrl || SIMCAPTURE_DEFAULTS.apiUrl);
+  const inventoryUrl = stripTrailingSlash(config.inventoryUrl || SIMCAPTURE_DEFAULTS.inventoryUrl);
+  if (!config.credentials?.username || !config.credentials?.password) {
+    throw new SimCaptureError({
+      message: "SimCapture config: `credentials.username` and `credentials.password` are required.",
+      status: 0,
+      code: "CONFIG_INVALID"
+    });
+  }
+  return {
+    apiUrl,
+    inventoryUrl,
+    credentials: config.credentials,
+    tokenTtlMs: config.tokenTtlMs ?? SIMCAPTURE_DEFAULTS.tokenTtlMs,
+    timeoutMs: config.timeoutMs ?? SIMCAPTURE_DEFAULTS.timeoutMs
+  };
+}
+function stripTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+
+// src/infrastructure/cache/in-memory-token-store.ts
+var InMemoryTokenStore = class {
+  token = null;
+  get() {
+    return this.token;
+  }
+  set(token) {
+    this.token = token;
+  }
+  clear() {
+    this.token = null;
+  }
+};
+var AxiosHttpClient = class {
+  instances;
+  constructor(options) {
+    this.instances = {
+      api: axios__default.default.create({ baseURL: options.apiUrl, timeout: options.timeoutMs }),
+      inventory: axios__default.default.create({ baseURL: options.inventoryUrl, timeout: options.timeoutMs })
+    };
+  }
+  async request(req) {
+    const instance = this.instances[req.server ?? "api"];
+    const config = {
+      method: req.method,
+      url: req.path,
+      responseType: req.responseType ?? "json"
+    };
+    const params = pruneUndefined(req.query);
+    if (params) config.params = params;
+    if (req.body !== void 0) config.data = req.body;
+    if (req.headers) config.headers = req.headers;
+    try {
+      const response = await instance.request(config);
+      return { status: response.status, data: response.data };
+    } catch (error) {
+      throw toSimCaptureError(error);
+    }
+  }
+};
+function pruneUndefined(query) {
+  if (!query) return void 0;
+  const out = {};
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0) out[key] = value;
+  }
+  return out;
+}
+function toSimCaptureError(error) {
+  if (error instanceof SimCaptureError) return error;
+  if (axios.isAxiosError(error)) {
+    const status = error.response?.status ?? 0;
+    if (status === 0) {
+      return new SimCaptureError({
+        message: `SimCapture request failed: ${error.message}`,
+        status: 0,
+        code: "NETWORK",
+        cause: error
+      });
+    }
+    return new SimCaptureError({
+      message: `SimCapture responded ${status}: ${error.message}`,
+      status,
+      code: status === 401 ? "UNAUTHORIZED" : "UPSTREAM_ERROR",
+      body: error.response?.data,
+      cause: error
+    });
+  }
+  return new SimCaptureError({
+    message: error instanceof Error ? error.message : "Unknown SimCapture error",
+    status: 0,
+    code: "NETWORK",
+    cause: error
+  });
+}
+
+// src/client.ts
+var SimCaptureClient = class {
+  organizations;
+  locations;
+  reservations;
+  courses;
+  scenarios;
+  simulators;
+  notifications;
+  inventory;
+  authenticator;
+  constructor(config, deps = {}) {
+    const resolved = resolveConfig(config);
+    const http = deps.httpClient ?? new AxiosHttpClient({
+      apiUrl: resolved.apiUrl,
+      inventoryUrl: resolved.inventoryUrl,
+      timeoutMs: resolved.timeoutMs
+    });
+    const store = deps.tokenStore ?? new InMemoryTokenStore();
+    const authenticatorOptions = {
+      http,
+      store,
+      credentials: new AuthCredentials(resolved.credentials),
+      tokenTtlMs: resolved.tokenTtlMs,
+      ...deps.now ? { now: deps.now } : {}
+    };
+    this.authenticator = new Authenticator(authenticatorOptions);
+    this.organizations = new OrganizationsResource(this.authenticator);
+    this.locations = new LocationsResource(this.authenticator);
+    this.reservations = new ReservationsResource(this.authenticator);
+    this.courses = new CoursesResource(this.authenticator);
+    this.scenarios = new ScenariosResource(this.authenticator);
+    this.simulators = new SimulatorsResource(this.authenticator);
+    this.notifications = new NotificationsResource(this.authenticator);
+    this.inventory = new InventoryResource(this.authenticator);
+  }
+  /** Force a fresh login. Rarely needed — auth is handled lazily per request. */
+  login() {
+    return this.authenticator.login().then(() => void 0);
+  }
+  /** Returns a valid session token, logging in only if none is cached. */
+  async getToken() {
+    const token = await this.authenticator.getToken();
+    return { token: token.value };
+  }
+};
+
+exports.AuthCredentials = AuthCredentials;
+exports.Authenticator = Authenticator;
+exports.AxiosHttpClient = AxiosHttpClient;
+exports.CoursesResource = CoursesResource;
+exports.InMemoryTokenStore = InMemoryTokenStore;
+exports.InventoryResource = InventoryResource;
+exports.LocationsResource = LocationsResource;
+exports.NotificationsResource = NotificationsResource;
+exports.OrganizationsResource = OrganizationsResource;
+exports.ReservationsResource = ReservationsResource;
+exports.SIMCAPTURE_DEFAULTS = SIMCAPTURE_DEFAULTS;
+exports.ScenariosResource = ScenariosResource;
+exports.SimCaptureClient = SimCaptureClient;
+exports.SimCaptureError = SimCaptureError;
+exports.SimulatorsResource = SimulatorsResource;
+exports.Token = Token;
+exports.resolveConfig = resolveConfig;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map