shakers-cli-beta 0.8.0-beta.0

package/src/interview-client.js

@@ -0,0 +1,226 @@
+'use strict';
+
+// InterviewClient — the TEXT-over-LiveKit transport for a turn-based interview.
+
+const CHAT_TOPIC = 'lk.chat';
+// The agent's own protocol channel; it announces the end there with `interview-complete`.
+const PROTOCOL_TOPIC = 'interview-protocol';
+const DEFAULT_TURN_TIMEOUT_MS = 90000;
+// A message is held this long before it is shown, so an `interview-complete`
+// sent right after the goodbye marks it as the last one instead of prompting
+// the Talent to answer a farewell.
+const DEFAULT_SETTLE_MS = 400;
+
+class LiveKitNotInstalledError extends Error {
+  constructor(cause) {
+    super('The optional @livekit/rtc-node package is not installed');
+    this.name = 'LiveKitNotInstalledError';
+    this.kind = 'livekit-not-installed';
+    this.cause = cause || null;
+  }
+}
+
+// Mute rtc-node's pino logger ("lk-rtc").
+function silenceLiveKitLogger() {
+  try {
+    const path = require('path');
+    const logPath = path.join(path.dirname(require.resolve('@livekit/rtc-node')), 'log.cjs');
+    const logModule = require(logPath);
+    if (logModule && logModule.log) logModule.log.level = 'silent';
+  } catch {}
+}
+
+// The ONLY place the native package is required.
+function loadLiveKitSdk() {
+  try {
+    // eslint-disable-next-line global-require
+    const sdk = require('@livekit/rtc-node');
+    silenceLiveKitLogger();
+    return sdk;
+  } catch (e) {
+    throw new LiveKitNotInstalledError(e);
+  }
+}
+
+class InterviewClient {
+  constructor({ topic = CHAT_TOPIC, turnTimeoutMs = DEFAULT_TURN_TIMEOUT_MS, sdk = null, isClosing = null, settleMs = DEFAULT_SETTLE_MS } = {}) {
+    this._topic = topic;
+    this._turnTimeoutMs = turnTimeoutMs;
+    this._sdk = sdk; // injectable; null => lazy-require the native SDK at connect()
+    this._isClosing = typeof isClosing === 'function' ? isClosing : null;
+    this._room = null;
+    this._queue = []; // completed agent messages waiting to be delivered
+    this._waiter = null; // { resolve, timer } for a pending receiveTurn()
+    this._disconnected = false;
+    this._connected = false;
+    this._settleMs = settleMs;
+    this._settling = 0; // messages still inside their settle window
+    this._ended = false; // the agent said the interview is over
+  }
+
+  get connected() {
+    return this._connected;
+  }
+
+  // Join the room.
+  async connect(livekitUrl, token, opts = {}) {
+    if (this._connected) throw new Error('already-connected');
+    if (!livekitUrl || !token) throw new Error('missing-credentials');
+    // A client reused after disconnect() starts clean, not already ended.
+    this._ended = false;
+    this._disconnected = false;
+    this._settling = 0;
+    this._queue = [];
+
+    const sdk = this._sdk || loadLiveKitSdk();
+    this._sdk = sdk;
+    const { Room, RoomEvent } = sdk;
+    const room = new Room();
+    this._room = room;
+
+    if (typeof room.registerTextStreamHandler !== 'function') {
+      // Text streams landed in @livekit/rtc-node ~0.13; older builds cannot carry lk.chat.
+      throw Object.assign(new Error('installed @livekit/rtc-node is too old for text streams'), { kind: 'livekit-no-text-streams' });
+    }
+
+    room.registerTextStreamHandler(this._topic, (reader) => {
+      // Counted as settling from the moment the stream opens, so an end signal that
+      // lands while a long goodbye is still being read waits for it.
+      this._settling += 1;
+      Promise.resolve()
+        .then(() => reader.readAll())
+        .then((text) => this._settle(String(text == null ? '' : text)))
+        // A failed read yields no turn; the loop still ends via the end signal, timeout or Disconnected.
+        .catch(() => this._settle(null));
+    });
+
+    if (RoomEvent && RoomEvent.Disconnected && typeof room.on === 'function') {
+      room.on(RoomEvent.Disconnected, () => this._markDisconnected());
+    }
+
+    // The end of the interview is a protocol message, not a sentence: matching the
+    // goodbye text never fired (certs sends no closingMessage), so the CLI kept
+    // asking for answers until its turn-timeout (new-works, 2026-09-25).
+    if (RoomEvent && RoomEvent.DataReceived && typeof room.on === 'function') {
+      room.on(RoomEvent.DataReceived, (payload, _participant, _kind, topic) => {
+        if (topic !== PROTOCOL_TOPIC) return;
+        let message = null;
+        try {
+          message = JSON.parse(Buffer.from(payload).toString('utf8'));
+        } catch {
+          return;
+        }
+        if (message && message.type === 'interview-complete') this._markEnded();
+      });
+    }
+
+    await room.connect(livekitUrl, token, opts);
+    this._connected = true;
+    return { ok: true };
+  }
+
+  // Resolve the NEXT agent message.
+  receiveTurn() {
+    return new Promise((resolve, reject) => {
+      if (this._queue.length) return resolve(this._deliver(this._queue.shift()));
+      if (this._disconnected || (this._ended && this._settling === 0)) return resolve({ text: '', ended: true });
+      const timer = setTimeout(() => {
+        this._waiter = null;
+        reject(Object.assign(new Error('turn-timeout'), { kind: 'turn-timeout' }));
+      }, this._turnTimeoutMs);
+      this._waiter = { resolve, timer };
+    });
+  }
+
+  // Send one candidate turn as lk.chat text, then wait for the agent's reply.
+  async sendTurn(text) {
+    if (!this._connected) throw new Error('not-connected');
+    const lp = this._room && this._room.localParticipant;
+    if (!lp || typeof lp.sendText !== 'function') throw new Error('no-local-participant');
+    await lp.sendText(String(text == null ? '' : text), { topic: this._topic });
+    return this.receiveTurn();
+  }
+
+  async disconnect() {
+    const room = this._room;
+    const sdk = this._sdk;
+    this._room = null;
+    this._connected = false;
+    if (this._waiter) {
+      const w = this._waiter;
+      this._waiter = null;
+      clearTimeout(w.timer);
+      w.resolve({ text: '', ended: true });
+    }
+    if (room) {
+      try { room.unregisterTextStreamHandler(this._topic); } catch {}
+      try { await room.disconnect(); } catch {}
+    }
+    // The FFI runtime keeps the event loop alive; dispose lets a one-shot CLI exit.
+    if (sdk && typeof sdk.dispose === 'function') {
+      try { await sdk.dispose(); } catch {}
+    }
+  }
+
+  _deliver(text) {
+    const ended = this._ended || (this._isClosing ? !!this._isClosing(text) : false);
+    return { text, ended };
+  }
+
+  _settle(text) {
+    const done = () => {
+      this._settling -= 1;
+      if (text !== null) this._release(text);
+      else if (this._ended) this._resolveEnded();
+    };
+    if (this._settleMs > 0) setTimeout(done, this._settleMs);
+    else done();
+  }
+
+  _resolveEnded() {
+    if (this._settling > 0 || !this._waiter || this._queue.length) return;
+    const w = this._waiter;
+    this._waiter = null;
+    clearTimeout(w.timer);
+    w.resolve({ text: '', ended: true });
+  }
+
+  _release(text) {
+    if (this._waiter) {
+      const w = this._waiter;
+      this._waiter = null;
+      clearTimeout(w.timer);
+      w.resolve(this._deliver(text));
+    } else {
+      this._queue.push(text);
+    }
+  }
+
+  _markEnded() {
+    this._ended = true;
+    // The goodbye and the end signal travel on different channels and can land in
+    // either order: give a goodbye still being read the same window to arrive, so
+    // it is shown as the last message instead of being cut off. A message still
+    // settling carries `ended` itself when it is released.
+    setTimeout(() => this._resolveEnded(), this._settleMs > 0 ? this._settleMs : 0);
+  }
+
+  _markDisconnected() {
+    this._disconnected = true;
+    if (this._waiter && !this._queue.length) {
+      const w = this._waiter;
+      this._waiter = null;
+      clearTimeout(w.timer);
+      w.resolve({ text: '', ended: true });
+    }
+  }
+}
+
+module.exports = {
+  InterviewClient,
+  LiveKitNotInstalledError,
+  loadLiveKitSdk,
+  CHAT_TOPIC,
+  PROTOCOL_TOPIC,
+  DEFAULT_TURN_TIMEOUT_MS,
+};

package/src/interview-transcript.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// TranscriptBuffer — records the onboarding interview Q&A as it happens over LiveKit text (lk.chat), in the exact shape certs' `PATCH /interviews/:id/ complete` persists.
+
+// Upper case: certs validates the role against its AGENT/USER enum and 400s the
+// whole PATCH otherwise, so every terminal onboarding lost its transcript
+// ("no se pudo guardar la transcripcion (http-400)", new-works 2026-09-25).
+const ROLE_AGENT = 'AGENT';
+const ROLE_USER = 'USER';
+
+class TranscriptBuffer {
+  constructor({ now = Date.now } = {}) {
+    this._now = typeof now === 'function' ? now : Date.now;
+    this._turns = [];
+    this._firstAt = null;
+  }
+
+  // Returns true if the turn was recorded, false if dropped (empty / bad role).
+  record(role, message) {
+    if (role !== ROLE_AGENT && role !== ROLE_USER) return false;
+    const msg = String(message == null ? '' : message).trim();
+    if (!msg) return false;
+    const at = this._now();
+    if (this._firstAt === null) this._firstAt = at;
+    this._turns.push({
+      role,
+      message: msg,
+      timestamp: new Date(at).toISOString(),
+      timeInCallSecs: Math.max(0, Math.floor((at - this._firstAt) / 1000)),
+    });
+    return true;
+  }
+
+  recordAgent(message) {
+    return this.record(ROLE_AGENT, message);
+  }
+
+  recordUser(message) {
+    return this.record(ROLE_USER, message);
+  }
+
+  get length() {
+    return this._turns.length;
+  }
+
+  // A defensive copy so callers cannot mutate the buffered turns.
+  toTranscripts() {
+    return this._turns.map((t) => ({ ...t }));
+  }
+}
+
+module.exports = {
+  TranscriptBuffer,
+  ROLE_AGENT,
+  ROLE_USER,
+};

package/src/inventory-client.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const { postJsonWithTimeout } = require('./backend-request');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function authHeaders({ accessToken } = {}) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+function normalizeSkill(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const skillId = typeof entry.skillId === 'number' ? entry.skillId : null;
+  const skillName = typeof entry.skillName === 'string' ? entry.skillName : null;
+  if (skillId === null || !skillName) return null;
+  const technologies = Array.isArray(entry.technologies)
+    ? entry.technologies.filter((tech) => typeof tech === 'string' && tech)
+    : [];
+  return { skillId, skillName, technologies };
+}
+
+function normalizeAgent(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const name = typeof entry.name === 'string' ? entry.name : null;
+  if (!name) return null;
+  const tools = Array.isArray(entry.tools)
+    ? entry.tools.filter((tool) => typeof tool === 'string' && tool)
+    : [];
+  const model = typeof entry.model === 'string' && entry.model ? entry.model : null;
+  const category = typeof entry.category === 'string' && entry.category ? entry.category : null;
+  const role = typeof entry.role === 'string' && entry.role ? entry.role : null;
+  const level = typeof entry.level === 'string' && entry.level ? entry.level : null;
+  const code = typeof entry.code === 'string' && entry.code ? entry.code : null;
+  const whatItDoes = typeof entry.whatItDoes === 'string' && entry.whatItDoes ? entry.whatItDoes : null;
+  const method = typeof entry.method === 'string' && entry.method ? entry.method : null;
+  return { name, tools, model, category, role, level, code, whatItDoes, method };
+}
+
+async function requestDiscoveredInventory({ accessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, authHeaders({ accessToken }));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+
+  if (res.status === 404) return { ok: false, reason: 'no-inventory' };
+  if (res.status < 200 || res.status >= 300) {
+    return { ok: false, reason: `http-${res.status}` };
+  }
+
+  const json = parseJson(res.raw);
+  const data = json && typeof json === 'object' ? json.data : null;
+  if (!data || typeof data !== 'object') return { ok: false, reason: 'bad-response' };
+
+  const skills = (Array.isArray(data.skills) ? data.skills : []).map(normalizeSkill).filter(Boolean);
+  const agents = (Array.isArray(data.agents) ? data.agents : []).map(normalizeAgent).filter(Boolean);
+  return { ok: true, skills, agents };
+}
+
+// Same read, but a `http-401` (expired hub JWT — certs validates it via hub JWKS)
+// triggers one token refresh and a single retry, so an expired token never breaks the
+// inventory read (add-agent / list_addable). `request` is injectable for tests.
+async function requestDiscoveredInventoryWithRefresh(
+  { accessToken, refreshToken } = {},
+  { endpoint, timeoutMs, request = requestDiscoveredInventory } = {},
+) {
+  let res = await request({ accessToken }, { endpoint, timeoutMs });
+  if (res && res.reason === 'http-401' && typeof refreshToken === 'function') {
+    let fresh = null;
+    try { fresh = await refreshToken(); } catch { fresh = null; }
+    const nextToken = fresh && (fresh.accessToken || fresh.hubAccessToken);
+    if (nextToken) res = await request({ accessToken: nextToken }, { endpoint, timeoutMs });
+  }
+  return res;
+}
+
+module.exports = { requestDiscoveredInventory, requestDiscoveredInventoryWithRefresh };

package/src/invitations-client.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// Received-invitations client (hub `works/positions/received-invitations`,
+// talent Bearer). Returns the talent's UNREAD position invitations.
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+function normalizeInvitation(raw) {
+  const it = raw && typeof raw === 'object' ? raw : {};
+  return {
+    projectId: typeof it.projectId === 'string' ? it.projectId : null,
+    name: typeof it.name === 'string' ? it.name : null,
+    invitationChatId: typeof it.invitationChatId === 'string' ? it.invitationChatId : null,
+  };
+}
+
+async function requestReceivedInvitations({ hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+
+  const env = parseJson(res.raw);
+  const data = env && env.status === 'OK' ? env.data : env;
+  const rows = Array.isArray(data) ? data : (Array.isArray(data && data.items) ? data.items : null);
+  if (!rows) return { ok: false, reason: 'bad-response' };
+  return { ok: true, items: rows.map(normalizeInvitation) };
+}
+
+async function fetchInvitations(deps = {}, { hubAccessToken, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const {
+    getReceivedInvitationsEndpoint = require('./config').getReceivedInvitationsEndpoint,
+    requestReceivedInvitations: request = requestReceivedInvitations,
+  } = deps;
+  const endpoint = getReceivedInvitationsEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return request({ hubAccessToken }, { endpoint, timeoutMs });
+}
+
+module.exports = {
+  normalizeInvitation,
+  requestReceivedInvitations,
+  fetchInvitations,
+};

package/src/invitations-flow.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// `invitations` flow: list the talent's unread position invitations. Read-only.
+
+const { styleLabelPrefix } = require('./ansi');
+
+function makeInvitationsDeps(overrides = {}) {
+  const client = require('./invitations-client');
+  return {
+    fetchInvitations: (opts) => client.fetchInvitations({}, opts),
+    ...overrides,
+  };
+}
+
+async function runInvitations({ io, rawOut, session, catalog, opts = {}, deps = makeInvitationsDeps() }) {
+  const fp = catalog.invitations;
+  const hubAccessToken = session ? session.hubAccessToken : null;
+
+  const doFetch = () => deps.fetchInvitations({ hubAccessToken });
+  const res = opts.json ? await doFetch() : await io.withProgress(fp.loading, doFetch);
+  if (!res.ok) {
+    io.error(fp.fetchFailed(res.reason));
+    return { ok: false, reason: res.reason };
+  }
+  const items = Array.isArray(res.items) ? res.items : [];
+
+  if (opts.json) {
+    (rawOut || ((s) => process.stdout.write(s)))(`${JSON.stringify({ ok: true, items }, null, 2)}\n`);
+    return { ok: true, items };
+  }
+
+  io.section(fp.title);
+  if (items.length === 0) {
+    io.notify(fp.none);
+    return { ok: true, items };
+  }
+  // Human render never prints the project id (it stays in --json only).
+  items.forEach((inv, i) => {
+    if (i > 0) io.notify('');
+    io.notify(`${i + 1}) ${inv.name || fp.untitled}${inv.invitationChatId ? ` · ${fp.hasChat}` : ''}`);
+  });
+  io.notify(styleLabelPrefix(fp.countNote(items.length)));
+  io.success(fp.done);
+  return { ok: true, items };
+}
+
+module.exports = {
+  makeInvitationsDeps,
+  runInvitations,
+};

package/src/lang-client.js

@@ -0,0 +1,147 @@
+'use strict';
+
+// Languages client. VIEW = GET `works/talents/me/work-details/languages`; the
+// catalog (id<->name) = GET `static-data/languages` (@Public); SET = PATCH the
+// same work-details endpoint (REPLACE-ALL: send the full list of {id, level}).
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+const LEVELS = ['NATIVE', 'ADVANCED', 'INTERMEDIATE', 'INTERMEDIATE_WRITTEN'];
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+function num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+
+function str(v) {
+  return typeof v === 'string' && v ? v : null;
+}
+
+// The hub returns `language.name` as an i18n KEY (staticDataLanguagesName_N),
+// which the CLI cannot resolve — so we display by ISO code, mapping the common
+// ones to a readable name and falling back to the bare code. NEVER the key.
+const LANGUAGE_NAMES = {
+  ES: 'Spanish', EN: 'English', FR: 'French', DE: 'German', IT: 'Italian',
+  PT: 'Portuguese', CA: 'Catalan', EU: 'Basque', GL: 'Galician', NL: 'Dutch',
+  ZH: 'Chinese', JA: 'Japanese', KO: 'Korean', AR: 'Arabic', RU: 'Russian',
+  PL: 'Polish', TR: 'Turkish', SV: 'Swedish', NO: 'Norwegian', DA: 'Danish',
+  FI: 'Finnish', EL: 'Greek', CS: 'Czech', RO: 'Romanian', HU: 'Hungarian',
+  UK: 'Ukrainian', HE: 'Hebrew', HI: 'Hindi', ID: 'Indonesian', VI: 'Vietnamese',
+};
+
+function languageName(code) {
+  const c = str(code) ? String(code).toUpperCase() : null;
+  if (!c) return null;
+  return LANGUAGE_NAMES[c] || c;
+}
+
+function rowsOf(raw) {
+  const env = parseJson(raw);
+  const data = env && env.status === 'OK' ? env.data : env;
+  return Array.isArray(data) ? data : (Array.isArray(data && data.items) ? data.items : null);
+}
+
+// The talent's languages: [{ id, code, name, level }].
+async function requestLanguages({ hubAccessToken } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+  const rows = rowsOf(res.raw);
+  if (!rows) return { ok: false, reason: 'bad-response' };
+  const languages = rows.map((r) => {
+    const lang = r && r.language && typeof r.language === 'object' ? r.language : {};
+    const code = str(lang.code) || str(r && r.code);
+    // `name` is derived from the code (readable or bare code), never the raw
+    // i18n-key the hub sends (staticDataLanguagesName_N), which we can't resolve.
+    return { id: num(lang.id) ?? num(r && r.id), code, name: languageName(code), level: str(r && r.level) };
+  }).filter((l) => l.id != null);
+  return { ok: true, languages };
+}
+
+// The full language catalog (id/name/code), for picking a language to add.
+async function requestLanguageCatalog(_ = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, null, timeoutMs, 'GET', null, {});
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+  const rows = rowsOf(res.raw);
+  if (!rows) return { ok: false, reason: 'bad-response' };
+  // Same rule: display by code (readable or bare), never the i18n-key name.
+  const catalog = rows.map((r) => { const code = str(r && r.code); return { id: num(r && r.id), code, name: languageName(code) }; }).filter((l) => l.id != null && l.name);
+  return { ok: true, catalog };
+}
+
+// REPLACE-ALL: `languages` is the FULL desired set of { id, level }.
+async function requestSetLanguages({ hubAccessToken, languages } = {}, { endpoint, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  if (!Array.isArray(languages)) return { ok: false, reason: 'no-languages' };
+  let res;
+  try {
+    res = await postJsonWithTimeout(endpoint, { languages }, timeoutMs, 'PATCH', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+  return { ok: true };
+}
+
+async function fetchLanguages(deps = {}, { hubAccessToken, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const getEndpoint = deps.getLanguagesEndpoint || require('./config').getLanguagesEndpoint;
+  const request = deps.requestLanguages || requestLanguages;
+  const endpoint = getEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return request({ hubAccessToken }, { endpoint, timeoutMs });
+}
+
+async function fetchLanguageCatalog(deps = {}, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const getEndpoint = deps.getLanguagesCatalogEndpoint || require('./config').getLanguagesCatalogEndpoint;
+  const request = deps.requestLanguageCatalog || requestLanguageCatalog;
+  const endpoint = getEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return request({}, { endpoint, timeoutMs });
+}
+
+async function saveLanguages(deps = {}, { hubAccessToken, languages, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const getEndpoint = deps.getLanguagesEndpoint || require('./config').getLanguagesEndpoint;
+  const request = deps.requestSetLanguages || requestSetLanguages;
+  const endpoint = getEndpoint();
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  return request({ hubAccessToken, languages }, { endpoint, timeoutMs });
+}
+
+module.exports = {
+  LEVELS,
+  languageName,
+  requestLanguages,
+  requestLanguageCatalog,
+  requestSetLanguages,
+  fetchLanguages,
+  fetchLanguageCatalog,
+  saveLanguages,
+};

package/src/lang-codes.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const LANG_CODES = ['es', 'en', 'it', 'pt', 'fr'];
+
+function toLowerLang(language) {
+  const lower = String(language || 'en').trim().toLowerCase();
+  return LANG_CODES.includes(lower) ? lower : 'en';
+}
+
+function toUpperLang(language) {
+  return toLowerLang(language).toUpperCase();
+}
+
+module.exports = { LANG_CODES, toLowerLang, toUpperLang };