@applitools/eyes-results 0.2.0

package/dist/api/session-fetch.js

@@ -0,0 +1,35 @@
+import { getJson, reqTransport } from './polling.js';
+import { simplifySession } from '../sessions/session.js';
+/** Fetches the raw Eyes session API response — no shaping. */
+export async function fetchRawSession(options, fetchImpl = reqTransport) {
+    const { baseUrl, batchId, sessionId, accountId, keys } = options;
+    const url = `${baseUrl}/api/sessions/batches/${batchId}/${sessionId}?accountId=${accountId}&apiKey=${encodeURIComponent(keys.getReadKey())}`;
+    return getJson(url, fetchImpl);
+}
+/** Fetches a session and shapes it via `sessions/session`'s `simplifySession`. */
+export async function fetchSession(options, fetchImpl = reqTransport) {
+    return simplifySession(await fetchRawSession(options, fetchImpl));
+}
+/**
+ * Fetches the raw list of sessions in a batch — no shaping.
+ * Normalizes the response shape: the Eyes API returns either a bare array or `{ sessions: [...] }`.
+ */
+export async function fetchRawBatchSessions(options, fetchImpl = reqTransport) {
+    const { baseUrl, batchId, accountId, keys } = options;
+    const url = `${baseUrl}/api/sessions/batches/${batchId}?accountId=${accountId}&apiKey=${encodeURIComponent(keys.getReadKey())}`;
+    const data = await getJson(url, fetchImpl);
+    return Array.isArray(data) ? data : data.sessions ?? [];
+}
+/**
+ * Fetches the raw batch entity itself (name, timing, and — the reason this exists —
+ * its server-maintained aggregate counts, shaped by `sessions/batch`'s `toBatchStats` —
+ * see `BatchInfo` there) — a different endpoint from `fetchRawBatchSessions`, which lists
+ * the batch's individual sessions. This aggregate is eventually consistent: it can lag
+ * behind a resolve/save call by several seconds, unlike a session list (or anything derived
+ * from one), which is always current.
+ */
+export async function fetchBatchInfo(options, fetchImpl = reqTransport) {
+    const { baseUrl, batchId, accountId, keys } = options;
+    const url = `${baseUrl}/api/sessions/batches/${batchId}/batch?accountId=${accountId}&apiKey=${encodeURIComponent(keys.getReadKey())}`;
+    return getJson(url, fetchImpl);
+}

package/dist/api/session-history-fetch.js

@@ -0,0 +1,73 @@
+import { Buffer } from 'buffer';
+import * as crypto from 'crypto';
+import { getJsonResult, reqTransport } from './polling.js';
+import { defaultFsCacheDeps, cacheFilePath } from './fs-cache.js';
+/**
+ * Builds the `where=` filter clauses for a session-history query. Each clause's payload is a
+ * plain UTF-8 string, base64-encoded — not `encodeURIComponent(JSON.stringify(...))` — and
+ * `IsViewport` in particular is a custom `{width:N,height:N}` literal (unquoted keys, not
+ * valid JSON), confirmed by decoding a real sample URL. Returns only the clauses for fields
+ * actually present in `env`, `&&`-joined; a caller further `encodeURIComponent`s the whole
+ * result when building the request URL — this returns the raw (unencoded) filter text.
+ */
+export function buildSessionHistoryEnvFilter(env) {
+    const clauses = [];
+    const b64 = (value) => Buffer.from(value, 'utf8').toString('base64');
+    if (env.hostingApp)
+        clauses.push(`(IsHostApp:${b64(env.hostingApp)})`);
+    if (env.os)
+        clauses.push(`(IsHostOS:${b64(env.os)})`);
+    if (env.displaySize) {
+        const { width, height } = env.displaySize;
+        clauses.push(`(IsViewport:${b64(`{width:${width},height:${height}}`)})`);
+    }
+    return clauses.join('&&');
+}
+export const defaultFetchSessionHistoryDeps = {
+    ...defaultFsCacheDeps,
+    fetchImpl: reqTransport,
+};
+/**
+ * Fetches (or reads from cache) a page of a scenario's historic sessions matching `env`, at or
+ * before `ranAtOrBefore`. Confirmed live as an async-job endpoint (a `202` with a `Location`
+ * status-poll header, same convention as `images/get-compatible-selectors` in
+ * `selector-mapping.ts` — there a POST initiates it, here a plain GET does), so this goes
+ * through `getJsonResult`, not `getJson` (which assumes a synchronous body).
+ *
+ * Named for what it returns — a session history — not for `scenarioId`, which is only one of
+ * several inputs (alongside `env`) narrowing which sessions come back; the endpoint itself is
+ * scoped by scenario, but the result is a plain list of full raw sessions, not scenario-level
+ * aggregate data.
+ *
+ * Cached indefinitely, keyed by a hash of every input that affects the result — unlike a
+ * session/batch fetch (deliberately never cached elsewhere in `api/`, since those can change),
+ * a `ranAtOrBefore`-pinned query against the past is immutable once made.
+ *
+ * Confirmed live: the response is `{ "sessions": [...] }`, each entry a full raw session
+ * object (the same shape `fetchRawSession` returns) — but a bare-array response is still
+ * normalized defensively, mirroring `fetchRawBatchSessions`, in case an edge case omits the
+ * wrapper.
+ */
+export async function fetchSessionHistory(options, deps = defaultFetchSessionHistoryDeps) {
+    const { baseUrl, scenarioId, accountId, keys, env, ranAtOrBefore, count } = options;
+    const apiKey = keys.getReadKey();
+    const where = buildSessionHistoryEnvFilter(env);
+    const cacheKey = crypto
+        .createHash('sha256')
+        .update(JSON.stringify({ scenarioId, where, ranAtOrBefore, count }))
+        .digest('hex');
+    const cachePath = cacheFilePath(deps, 'eyes-session-history', cacheKey, 'json');
+    const cached = deps.readFile(cachePath);
+    if (cached !== null)
+        return JSON.parse(cached);
+    const url = `${baseUrl}/api/sessions/scenarios/${scenarioId}/query` +
+        `?ranAtOrBefore=${encodeURIComponent(ranAtOrBefore)}` +
+        `&where=${encodeURIComponent(where)}` +
+        `&count=${count}` +
+        `&accountId=${accountId}&apiKey=${encodeURIComponent(apiKey)}`;
+    const response = await deps.fetchImpl(url);
+    const data = await getJsonResult(response, apiKey, deps.fetchImpl, deps.sleepFn, url);
+    const sessions = Array.isArray(data) ? data : data?.sessions ?? [];
+    deps.writeFile(cachePath, JSON.stringify(sessions));
+    return sessions;
+}

package/dist/api/session-updates.js

@@ -0,0 +1,37 @@
+import { postJson, getJsonResult, reqTransport } from './polling.js';
+/**
+ * POSTs a batch of per-session step updates (accept/reject decisions, region changes) in one
+ * call — confirmed live to accept multiple sessions at once, one entry per session id.
+ */
+export async function postStepUpdates(options, stepUpdatesBySession, fetchImpl = reqTransport) {
+    const { baseUrl, batchId, accountId, keys } = options;
+    const apiKey = keys.getWriteKey();
+    const apiUrl = `${baseUrl}/api/sessions/batches/${batchId}/updates?accountId=${accountId}&apiKey=${encodeURIComponent(apiKey)}`;
+    const updates = [...stepUpdatesBySession.entries()].map(([id, stepUpdates]) => ({ id, batchId, stepUpdates }));
+    const response = await postJson(apiUrl, { updates }, fetchImpl);
+    await getJsonResult(response, apiKey, fetchImpl, undefined, apiUrl);
+}
+/** Commits every pending accept/reject/region change in the batch to the baseline. The endpoint returns nothing useful to the caller — a resolved promise signals success. */
+export async function saveBaselines(options, fetchImpl = reqTransport) {
+    const { baseUrl, batchId, accountId, keys } = options;
+    const apiKey = keys.getWriteKey();
+    const apiUrl = `${baseUrl}/api/sessions/batches/${batchId}/baselines?accountId=${accountId}&apiKey=${encodeURIComponent(apiKey)}`;
+    const response = await postJson(apiUrl, undefined, fetchImpl);
+    await getJsonResult(response, apiKey, fetchImpl, undefined, apiUrl);
+}
+/** Reverts a session's shared baseline object to the revision it originally ran against. */
+export async function restoreBaseline(options, fetchImpl = reqTransport) {
+    const { baseUrl, accountId, baselineId, baselineRev, keys } = options;
+    const apiKey = keys.getWriteKey();
+    const url = `${baseUrl}/api/baselines/${baselineId}/${baselineRev}/restore?accountId=${accountId}&apiKey=${encodeURIComponent(apiKey)}`;
+    const response = await postJson(url, undefined, fetchImpl);
+    await getJsonResult(response, apiKey, fetchImpl, undefined, url);
+}
+/** Clears every given session's pending (unsaved) accept/reject/region resolution back to unresolved — a no-op, not an error, for a session with nothing pending. */
+export async function resetBatchSessions(options, sessionIds, fetchImpl = reqTransport) {
+    const { baseUrl, batchId, accountId, keys } = options;
+    const apiKey = keys.getWriteKey();
+    const url = `${baseUrl}/api/sessions/batches/${batchId}/reset?accountId=${accountId}&apiKey=${encodeURIComponent(apiKey)}`;
+    const response = await postJson(url, { ids: sessionIds }, fetchImpl);
+    await getJsonResult(response, apiKey, fetchImpl, undefined, url);
+}

package/dist/api/tasks.js

@@ -0,0 +1,48 @@
+import { makeReqResults } from './req-results.js';
+export const TASK_STATUS_PATH = (taskId) => `/api/tasks/${taskId}/status`;
+export const TASK_RESULT_PATH = (taskId) => `/api/tasks/${taskId}/result`;
+/** Extracts the taskId out of a submit response's `Location` (`/api/tasks/{taskId}/status`). */
+export function taskIdFromLocation(location) {
+    const match = location.match(/\/api\/tasks\/([^/?]+)\/status/);
+    if (!match)
+        throw new Error(`Location does not name a task-status URL: ${location}`);
+    return match[1];
+}
+/**
+ * One probe of a task's status — no client-side polling loop: `running` hands the taskId back so
+ * the caller decides when (and whether) to check again; `201` means done, and the result the
+ * response's `Location` points at is fetched and returned in the same call, so a ready task never
+ * costs the caller a second round trip. `404` (unknown or expired task) is terminal and throws
+ * with the contract's own wording. A *rejected* task also finishes as `201` here — its rejection
+ * surfaces as `503` on the result fetch (TasksController puts it there, not on status); transient
+ * transport failures are the configured req's standard retry policy, not handled here.
+ */
+export async function getTaskStatus(baseUrl, taskId, keys, deps = {}) {
+    const req = makeReqResults({ serverUrl: baseUrl, apiKey: keys.getReadKey(), ...deps });
+    const response = await req(TASK_STATUS_PATH(taskId), {
+        name: 'getTaskStatus',
+        expected: [200, 201, 404],
+    });
+    if (response.status === 200)
+        return { status: 'running', taskId };
+    if (response.status === 201) {
+        const resultUrl = response.headers.get('Location') ?? TASK_RESULT_PATH(taskId);
+        return { status: 'ready', result: await fetchTaskResult(baseUrl, resultUrl, keys, deps) };
+    }
+    throw new Error(`Unknown or expired task: ${taskId}`);
+}
+/**
+ * Fetches a finished task's result and parses it as JSON. The response is gzipped on the wire
+ * when the request advertises `Accept-Encoding` — the transport negotiates and decompresses that
+ * transparently, so no explicit gunzip step exists here (unlike endpoints that return a gzip
+ * *body*, e.g. `fetchPrunedDom`). `503` is the result endpoint's "task rejected" — terminal by
+ * the task contract (and excluded from the retry policy for exactly that reason), thrown with
+ * the contract's own wording.
+ */
+export async function fetchTaskResult(baseUrl, resultUrl, keys, deps = {}) {
+    const req = makeReqResults({ serverUrl: baseUrl, apiKey: keys.getReadKey(), ...deps });
+    const response = await req(resultUrl, { name: 'fetchTaskResult', expected: [200, 503] });
+    if (response.status === 503)
+        throw new Error(`Task rejected by the server: ${resultUrl}`);
+    return response.json();
+}

package/dist/api/url-parsing.js

@@ -0,0 +1,33 @@
+/**
+ * Parses an Applitools dashboard URL (session or batch) into its components.
+ * Does not require a sessionId to be present — use parseSessionUrl/parseBatchUrl
+ * for callers that need to enforce one shape or the other.
+ */
+export function parseApplitoolsUrl(url) {
+    const urlMatch = url.match(/^(https?:\/\/[^/]+)/);
+    if (!urlMatch)
+        throw new Error(`Invalid URL format: "${url}"`);
+    const batchMatch = url.match(/\/app\/test-results\/([^/?]+)/);
+    if (!batchMatch)
+        throw new Error(`Invalid URL format: "${url}"`);
+    const accountIdMatch = url.match(/accountId=([^&]+)/);
+    if (!accountIdMatch)
+        throw new Error(`Missing accountId in URL: "${url}"`);
+    const sessionMatch = url.match(/\/app\/test-results\/[^/?]+\/([^/?]+)/);
+    const sessionId = sessionMatch ? sessionMatch[1] : null;
+    return { baseUrl: urlMatch[1], batchId: batchMatch[1], sessionId, accountId: accountIdMatch[1] };
+}
+/** Throws if the URL doesn't include a sessionId segment (i.e. it's a batch-only URL). */
+export function parseSessionUrl(url) {
+    const parsed = parseApplitoolsUrl(url);
+    if (!parsed.sessionId) {
+        throw new Error('The input URL is a batch URL while a session URL is expected. ' +
+            'Use the eyes_fetch_visual_results MCP tool to obtain URLs of sessions in this batch.');
+    }
+    return parsed;
+}
+/** Batch-scoped: parses the batchId/accountId and always forces sessionId to null, ignoring any session segment. */
+export function parseBatchUrl(url) {
+    const parsed = parseApplitoolsUrl(url);
+    return { ...parsed, sessionId: null };
+}

package/dist/common/common.js

@@ -0,0 +1,2 @@
+export * from './region-mapping.js';
+export * from './diff-rects.js';

package/dist/common/diff-rects.js

@@ -0,0 +1,64 @@
+import * as crypto from 'crypto';
+import { cacheFilePath, defaultFsCacheDeps, compareStep, fetchStepDiff } from '../api/api.js';
+import { getEffectiveMatchSettings } from '../sessions/match.js';
+import { imageForSide } from '../sessions/regions.js';
+export const defaultFetchRawDiffsDeps = {
+    fetchStepDiff,
+    compareStep,
+    readFile: defaultFsCacheDeps.readFile,
+    writeFile: defaultFsCacheDeps.writeFile,
+};
+/**
+ * The two-way visual diff for one step — `image1` in the baseline image's own coordinate
+ * space, `image2` in the checkpoint's, exactly mirroring both the plain `GET .../diff`
+ * endpoint's and `compareStep`'s own response shape. When the step's resolution state is
+ * unchanged from the original test run (`appOutputResolution[stepIndex].isChanged` is not
+ * `true`), the cheap `GET .../diff` endpoint is used as-is — nothing about the step's
+ * effective match settings differs from what the test already ran with. Otherwise, the step's
+ * current effective regions are folded into a fresh `compareStep` request so the returned diff
+ * reflects any region added since the test ran — that (more expensive) result is cached on
+ * disk, keyed by a hash of the full request body, so repeated calls against the same resolved
+ * state don't repeatedly hit the endpoint.
+ *
+ * Takes an already-fetched `rawSession` rather than fetching its own — `batchId`/`sessionId`
+ * are read straight off it (`rawSession.batchId`/`rawSession.id`), so a caller that already has
+ * the raw session in hand (e.g. for its own domId lookups) never pays for a second fetch just
+ * to hand this function a `url` it would otherwise re-resolve into the same session itself.
+ *
+ * `matchSettings` comes straight from `getEffectiveMatchSettings` — the raw session's own
+ * scalars/regions, shaped directly into the request format, with no baseline/checkpoint
+ * pairing and no healing: that shaping only exists for diagnostic region output (which needs
+ * both sides shown, healing in whichever one the raw session doesn't encode), never for a
+ * compare request. Re-deriving "accepted ⇒ checkpoint, else baseline" here would duplicate
+ * logic the raw session's own `annotations` field already resolves — and healing in the other
+ * side would cost an extra network round trip per region for nothing a compare request needs.
+ */
+export async function fetchRawDiffs(rawSession, stepIndex, baseUrl, accountId, keys, deps = defaultFetchRawDiffsDeps) {
+    const batchId = rawSession?.batchId;
+    const sessionId = rawSession?.id;
+    if (rawSession?.appOutputResolution?.[stepIndex]?.isChanged !== true) {
+        return deps.fetchStepDiff({ baseUrl, batchId, sessionId, stepIndex, accountId, keys });
+    }
+    const requestBody = {
+        matchSettings: getEffectiveMatchSettings(rawSession, stepIndex),
+        image1: imageForSide(rawSession, stepIndex, 'baseline'),
+        image2: imageForSide(rawSession, stepIndex, 'checkpoint'),
+        sessionId: rawSession.id,
+        batchId: rawSession.batchId,
+        runningSessionId: rawSession.runningSessionId,
+        stepIndex,
+    };
+    // SHA-256 (not SHA-1): this is only a content-addressed cache key, but the hashed body carries
+    // session identifiers, so a collision-prone digest is neither needed nor acceptable here.
+    const requestHash = crypto.createHash('sha256').update(JSON.stringify(requestBody)).digest('hex').slice(0, 16);
+    const cachePath = cacheFilePath(defaultFsCacheDeps, 'eyes-compare', requestHash);
+    const cached = deps.readFile(cachePath);
+    if (cached !== null) {
+        const parsed = JSON.parse(cached);
+        return { image1: parsed.image1 ?? [], image2: parsed.image2 ?? [] };
+    }
+    const result = await deps.compareStep(requestBody, { baseUrl, accountId, keys });
+    const rects = { image1: result.image1 ?? [], image2: result.image2 ?? [] };
+    deps.writeFile(cachePath, JSON.stringify(rects));
+    return rects;
+}

package/dist/common/region-mapping.js

@@ -0,0 +1,50 @@
+import { findNodeBySelector } from '../sessions/dom.js';
+import { resolveDomIdSide, imageForSide } from '../sessions/regions.js';
+// findNodeBySelector/findNodeByRect return a nested {domSelector, rect} shape (DomNode);
+// the Region shape needed elsewhere is flat (domSelector alongside left/top/width/height).
+function toRegion(resolved) {
+    return { domSelector: resolved.domSelector, ...resolved.rect };
+}
+/**
+ * Maps every `anchored` pair's `domSelector` to the other side via one batched
+ * get-compatible-selectors call, resolving each mapped selector's accurate rect locally
+ * against that side's DOM (the API only returns the mapped selector, never a rect). Falls
+ * back to treating every selector as unmapped if the batch call itself fails for some reason
+ * other than a bad input selector (`sessions`'s own `checkRegions` already filters those out).
+ * Mutates each pair's missing side in place. Returns whether anything was attempted (i.e.
+ * `anchored` was non-empty and both sides have an image to map between).
+ *
+ * Lives here, not in `atoms/sessions` (where the rest of the region-healing pipeline this composes
+ * into — `checkRegions`/`clearStaleSelectors`/`healNonAnchoredRegionsBySourceRect` — lives):
+ * this is the one step of that pipeline that actually calls the network (`getCompatibleSelectors`),
+ * and `atoms` must never depend on `api`/`common` (so it can't reference `ApiKeyProvider` or make
+ * network calls) — the orchestration belongs in `common`, which depends on both instead.
+ */
+export async function mapAnchoredRegionsBySelector(rawSession, stepIndex, anchored, deps) {
+    if (anchored.length === 0)
+        return false;
+    const sourceSide = resolveDomIdSide('unchanged', rawSession, stepIndex);
+    const missingSide = sourceSide === 'baseline' ? 'checkpoint' : 'baseline';
+    const imageSource = imageForSide(rawSession, stepIndex, sourceSide);
+    const imageMissing = imageForSide(rawSession, stepIndex, missingSide);
+    if (!imageSource || !imageMissing)
+        return false;
+    const domMissing = await deps.fetchDomForSide(rawSession, stepIndex, missingSide, deps.baseUrl).catch(() => null);
+    // `anchored` pairs are guaranteed a truthy domSelector by checkRegions's own definition of "anchored".
+    const selectors = anchored.map(p => (p.baseline ?? p.checkpoint).domSelector);
+    let mapped;
+    try {
+        mapped = await deps.getCompatibleSelectors({ baseUrl: deps.baseUrl, accountId: deps.accountId, keys: deps.keys }, imageSource, imageMissing, selectors);
+    }
+    catch {
+        mapped = selectors.map(() => null); // the batch itself failed — treat every one as unmapped rather than throwing
+    }
+    anchored.forEach((pair, i) => {
+        const newSelector = mapped[i];
+        const resolved = newSelector && domMissing ? findNodeBySelector(domMissing, newSelector) : null;
+        pair[missingSide] = resolved
+            ? toRegion(resolved)
+            : { ...(pair.baseline ?? pair.checkpoint), domSelector: newSelector ?? '' };
+    });
+    return true;
+}

package/dist/geometry/geometry.js

@@ -0,0 +1,72 @@
+export function parseRect(s) {
+    const parts = s.split(',').map(Number);
+    if (parts.length !== 4 || parts.some(isNaN)) {
+        throw new Error(`Invalid rect format: "${s}". Expected "left,top,width,height"`);
+    }
+    return { left: parts[0], top: parts[1], width: parts[2], height: parts[3] };
+}
+/** Inverse of `parseRect` — formats a rect back into `"left,top,width,height"`. */
+export function formatRect(rect) {
+    return `${rect.left},${rect.top},${rect.width},${rect.height}`;
+}
+/**
+ * Returns true if outer completely contains inner (all edges of inner are within outer).
+ * Equal rectangles are considered to contain each other.
+ */
+export function rectContains(outer, inner) {
+    return (outer.left <= inner.left &&
+        outer.top <= inner.top &&
+        outer.left + outer.width >= inner.left + inner.width &&
+        outer.top + outer.height >= inner.top + inner.height);
+}
+export function rectsIntersect(a, b) {
+    return a.left < b.left + b.width && a.left + a.width > b.left && a.top < b.top + b.height && a.top + a.height > b.top;
+}
+export function intersectionArea(a, b) {
+    const w = Math.min(a.left + a.width, b.left + b.width) - Math.max(a.left, b.left);
+    const h = Math.min(a.top + a.height, b.top + b.height) - Math.max(a.top, b.top);
+    return w > 0 && h > 0 ? w * h : 0;
+}
+export function boundingRect(a, b) {
+    const left = Math.min(a.left, b.left);
+    const top = Math.min(a.top, b.top);
+    const right = Math.max(a.left + a.width, b.left + b.width);
+    const bottom = Math.max(a.top + a.height, b.top + b.height);
+    return { left, top, width: right - left, height: bottom - top };
+}
+/**
+ * Expands a rect by `padding` pixels on every side.
+ * When `imageWidth`/`imageHeight` are provided the result is clipped to the image bounds.
+ */
+export function padRect(rect, padding, imageWidth = Infinity, imageHeight = Infinity) {
+    const left = Math.max(0, rect.left - padding);
+    const top = Math.max(0, rect.top - padding);
+    const right = Math.min(imageWidth, rect.left + rect.width + padding);
+    const bottom = Math.min(imageHeight, rect.top + rect.height + padding);
+    return { left, top, width: right - left, height: bottom - top };
+}
+/** Merges pairs of rects that overlap by more than 10% of the smaller rect's area. */
+export function unifyRects(rects) {
+    let result = [...rects];
+    let merged = true;
+    while (merged) {
+        merged = false;
+        outer: for (let i = 0; i < result.length; i++) {
+            for (let j = i + 1; j < result.length; j++) {
+                const overlap = intersectionArea(result[i], result[j]);
+                const smallerArea = Math.min(result[i].width * result[i].height, result[j].width * result[j].height);
+                if (overlap / smallerArea > 0.1) {
+                    result = [
+                        ...result.slice(0, i),
+                        ...result.slice(i + 1, j),
+                        ...result.slice(j + 1),
+                        boundingRect(result[i], result[j]),
+                    ];
+                    merged = true;
+                    break outer;
+                }
+            }
+        }
+    }
+    return result;
+}

package/dist/index.js

@@ -0,0 +1,14 @@
+export * from './lib/api-key-provider.js';
+export * from './lib/env.js';
+export * from './lib/phase-tracker.js';
+export * from './geometry/geometry.js';
+export * from './sessions/batch.js';
+export * from './sessions/diffs.js';
+export * from './sessions/dom-history.js';
+export * from './sessions/dom-search.js';
+export * from './sessions/dom.js';
+export * from './sessions/match.js';
+export * from './sessions/regions.js';
+export * from './sessions/session.js';
+export * from './api/api.js';
+export * from './common/common.js';

package/dist/lib/api-key-provider.js

@@ -0,0 +1,26 @@
+/**
+ * Wraps already-resolved key strings. A getter throws a clear error if its key wasn't supplied —
+ * e.g. a write key deliberately withheld when building a provider for a read-only call — rather
+ * than returning `undefined` and letting a missing credential fail confusingly further down.
+ */
+export class StaticApiKeyProvider {
+    keys;
+    constructor(keys) {
+        this.keys = keys;
+    }
+    getReadKey() {
+        return this.require('readKey', 'read');
+    }
+    getWriteKey() {
+        return this.require('writeKey', 'write');
+    }
+    getRunKey() {
+        return this.require('runKey', 'run');
+    }
+    require(field, label) {
+        const key = this.keys[field];
+        if (key === undefined)
+            throw new Error(`No ${label} API key is available for this call.`);
+        return key;
+    }
+}

package/dist/lib/env.js

@@ -0,0 +1,26 @@
+import * as dotenv from 'dotenv';
+import * as fs from 'fs';
+import * as path from 'path';
+export const defaultLoadEnvDeps = {
+    existsSync: fs.existsSync,
+    configDotenv: dotenv.config,
+};
+/**
+ * Walks up from `startDir` (default: the current working directory) looking for a `.env`
+ * file, loading the first one found via `dotenv`. Mirrors the behavior every skill's own
+ * `main.ts` used to inline directly.
+ */
+export function loadEnvFromCwd(startDir = process.cwd(), deps = defaultLoadEnvDeps) {
+    let dir = startDir;
+    while (true) {
+        const envPath = path.join(dir, '.env');
+        if (deps.existsSync(envPath)) {
+            deps.configDotenv({ path: envPath });
+            return;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return;
+        dir = parent;
+    }
+}