@autifyhq/aximo-cli 0.14.0 → 0.16.0

package/dist/commands/mcp/wait.test.js

@@ -0,0 +1,91 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import { HttpResponse, http, server, TEST_BASE_URL } from "../../test-utils.js";
+import { isTerminalStatus, realClock, WAIT_POLL_INTERVAL_MS, waitForSession, } from "./wait.js";
+beforeAll(() => {
+    process.env["AXIMO_API_KEY"] = "test-key";
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    server.listen();
+});
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+const sessionId = "aaaaaaaa-aaaa-4aaa-9aaa-aaaaaaaaaaaa";
+// A clock where sleep advances time instantly, so the poll loop runs without waiting.
+function fakeClock() {
+    let t = 1_000_000;
+    const sleeps = [];
+    return {
+        sleeps,
+        now: () => t,
+        sleep: async (ms) => {
+            sleeps.push(ms);
+            t += ms;
+        },
+    };
+}
+function statusSequence(statuses) {
+    let calls = 0;
+    server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}`, () => {
+        const status = statuses[Math.min(calls, statuses.length - 1)];
+        calls += 1;
+        return HttpResponse.json({ id: sessionId, status });
+    }));
+    return () => calls;
+}
+describe("isTerminalStatus", () => {
+    it("matches the five final statuses and nothing else", () => {
+        for (const s of ["succeeded", "failed", "terminated", "error", "archived"]) {
+            expect(isTerminalStatus(s)).toBe(true);
+        }
+        for (const s of ["queued", "created", "preparing", "running", undefined]) {
+            expect(isTerminalStatus(s)).toBe(false);
+        }
+    });
+});
+describe("waitForSession", () => {
+    it("polls every 5 s and returns done once the status is final", async () => {
+        const calls = statusSequence(["running", "running", "succeeded"]);
+        const clock = fakeClock();
+        const result = await waitForSession(sessionId, 60, {}, clock);
+        expect(result.done).toBe(true);
+        expect(result.status).toBe("succeeded");
+        expect(result.waitedSeconds).toBe(10);
+        expect(result.session).toEqual({ id: sessionId, status: "succeeded" });
+        expect(result.hint).toBeUndefined();
+        expect(calls()).toBe(3);
+        expect(clock.sleeps).toEqual([WAIT_POLL_INTERVAL_MS, WAIT_POLL_INTERVAL_MS]);
+    });
+    it("returns done=false before the deadline instead of overrunning it", async () => {
+        const calls = statusSequence(["running"]);
+        const clock = fakeClock();
+        // 7 s: poll at 0 s, sleep to 5 s, poll, then 5 + 5 > 7 so stop.
+        const result = await waitForSession(sessionId, 7, {}, clock);
+        expect(result.done).toBe(false);
+        expect(result.status).toBe("running");
+        expect(result.waitedSeconds).toBe(5);
+        expect(result.hint).toMatch(/call aximo_wait_for_session again/i);
+        expect(calls()).toBe(2);
+    });
+    it("polls once and returns when the timeout is shorter than one interval", async () => {
+        const calls = statusSequence(["queued"]);
+        const clock = fakeClock();
+        const result = await waitForSession(sessionId, 1, {}, clock);
+        expect(result.done).toBe(false);
+        expect(result.status).toBe("queued");
+        expect(calls()).toBe(1);
+        expect(clock.sleeps).toEqual([]);
+    });
+    it("lets API errors through untouched so the tool layer can shape them", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}`, () => HttpResponse.json({ error: "Session not found" }, { status: 404 })));
+        await expect(waitForSession(sessionId, 10, {}, fakeClock())).rejects.toMatchObject({
+            status: 404,
+            message: "Session not found",
+        });
+    });
+});
+describe("realClock", () => {
+    it("sleeps for at least the requested time", async () => {
+        const before = realClock.now();
+        await realClock.sleep(20);
+        expect(realClock.now() - before).toBeGreaterThanOrEqual(15);
+    });
+});

package/dist/commands/schema.js

@@ -42,6 +42,10 @@ export function getSchema() {
                 cmd("get", "GET /api/sessions/{sessionId}", [
                     arg("sessionId", "positional", "Session ID", true),
                 ]),
+                cmd("cancel", "POST /api/sessions/{sessionId}/cancel", [
+                    arg("sessionId", "positional", "Session ID", true),
+                    arg("dry-run", "boolean", "Validate and show request without calling API"),
+                ]),
                 cmd("save-as-case", "POST /api/sessions/{sessionId}/save-as-case", [
                     arg("sessionId", "positional", "Session ID", true),
                     arg("title", "string", ""),

package/dist/commands/session/cancel.d.ts

@@ -0,0 +1,20 @@
+import { type ClientDeps } from "../../client.js";
+import { type DryRunResult } from "../../mutate.js";
+import type { CancelSessionResult, Envelope } from "../../types.js";
+export interface SessionCancelOptions {
+    sessionId?: unknown;
+    dryRun?: unknown;
+}
+export declare function runSessionCancel(options: SessionCancelOptions, deps?: ClientDeps): Promise<Envelope<CancelSessionResult | DryRunResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly sessionId: {
+        readonly type: "positional";
+        readonly description: "Session ID";
+        readonly required: true;
+    };
+    readonly "dry-run": {
+        readonly type: "boolean";
+        readonly description: "Validate and show request without calling API";
+    };
+}>;
+export default _default;

package/dist/commands/session/cancel.js

@@ -0,0 +1,39 @@
+import { defineCommand } from "citty";
+import { request } from "../../client.js";
+import { handleApiError } from "../../errors.js";
+import { dryRunEnvelope } from "../../mutate.js";
+import { formatSuccess, printResult, validationError } from "../../output.js";
+import { requireId } from "../../validate.js";
+export async function runSessionCancel(options, deps) {
+    let sessionId;
+    try {
+        sessionId = requireId("sessionId", options.sessionId);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    const path = `/api/sessions/${encodeURIComponent(sessionId)}/cancel`;
+    if (options.dryRun) {
+        return dryRunEnvelope("POST", path);
+    }
+    try {
+        const res = await request(path, { method: "POST" }, deps ?? {});
+        return formatSuccess(res);
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: {
+        name: "cancel",
+        description: "Cancel a queued or running session (stops it on its device)",
+    },
+    args: {
+        sessionId: { type: "positional", description: "Session ID", required: true },
+        "dry-run": { type: "boolean", description: "Validate and show request without calling API" },
+    },
+    async run({ args }) {
+        printResult(await runSessionCancel({ sessionId: args.sessionId, dryRun: args["dry-run"] }));
+    },
+});

package/dist/commands/session/export.d.ts

@@ -0,0 +1,30 @@
+import type { ClientDeps } from "../../client.js";
+import { type SessionExportResult } from "../../session-export.js";
+import type { Envelope } from "../../types.js";
+export interface SessionExportOptions {
+    sessionId?: unknown;
+    format?: unknown;
+    output?: unknown;
+    locale?: unknown;
+}
+export declare function runSessionExport(options: SessionExportOptions, deps?: ClientDeps): Promise<Envelope<SessionExportResult>>;
+declare const _default: import("citty").CommandDef<{
+    readonly sessionId: {
+        readonly type: "positional";
+        readonly description: "Session ID";
+        readonly required: true;
+    };
+    readonly format: {
+        readonly type: "string";
+        readonly description: "pdf | screenshots (default: pdf)";
+    };
+    readonly output: {
+        readonly type: "string";
+        readonly description: "File to write (default: <sessionId>.pdf or <sessionId>-screenshots.zip)";
+    };
+    readonly locale: {
+        readonly type: "string";
+        readonly description: "Report language: en | ja | ko (default: en)";
+    };
+}>;
+export default _default;

package/dist/commands/session/export.js

@@ -0,0 +1,58 @@
+import { defineCommand } from "citty";
+import { handleApiError } from "../../errors.js";
+import { formatSuccess, printResult, validationError } from "../../output.js";
+import { defaultExportFileName, exportSession, SESSION_EXPORT_FORMATS, SESSION_EXPORT_LOCALES, } from "../../session-export.js";
+import { optionalString, requireId } from "../../validate.js";
+function parseOneOf(name, allowed, value) {
+    const raw = optionalString(name, value);
+    if (raw === undefined)
+        return undefined;
+    if (!allowed.includes(raw)) {
+        throw new Error(`${name} must be one of: ${allowed.join(", ")}`);
+    }
+    return raw;
+}
+export async function runSessionExport(options, deps) {
+    let sessionId;
+    let format;
+    let locale;
+    let output;
+    try {
+        sessionId = requireId("sessionId", options.sessionId);
+        format = parseOneOf("format", SESSION_EXPORT_FORMATS, options.format) ?? "pdf";
+        locale = parseOneOf("locale", SESSION_EXPORT_LOCALES, options.locale);
+        output = optionalString("output", options.output) ?? defaultExportFileName(sessionId, format);
+    }
+    catch (err) {
+        return validationError(err);
+    }
+    try {
+        return formatSuccess(await exportSession({ sessionId, format, outputPath: output, locale }, deps));
+    }
+    catch (err) {
+        return handleApiError(err);
+    }
+}
+export default defineCommand({
+    meta: {
+        name: "export",
+        description: "Download a session's result as a PDF report or a ZIP of its screenshots",
+    },
+    args: {
+        sessionId: { type: "positional", description: "Session ID", required: true },
+        format: { type: "string", description: "pdf | screenshots (default: pdf)" },
+        output: {
+            type: "string",
+            description: "File to write (default: <sessionId>.pdf or <sessionId>-screenshots.zip)",
+        },
+        locale: { type: "string", description: "Report language: en | ja | ko (default: en)" },
+    },
+    async run({ args }) {
+        printResult(await runSessionExport({
+            sessionId: args.sessionId,
+            format: args.format,
+            output: args.output,
+            locale: args.locale,
+        }));
+    },
+});

package/dist/commands/session/index.js

@@ -4,6 +4,8 @@ export default defineCommand({
     subCommands: {
         create: () => import("./create.js").then((m) => m.default),
         get: () => import("./get.js").then((m) => m.default),
+        cancel: () => import("./cancel.js").then((m) => m.default),
+        export: () => import("./export.js").then((m) => m.default),
         "save-as-case": () => import("./save-as-case.js").then((m) => m.default),
     },
 });

package/dist/commands/session/session.test.js

@@ -1,6 +1,11 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import { server, http, HttpResponse, TEST_BASE_URL } from "../../test-utils.js";
+import { runSessionCancel } from "./cancel.js";
 import { runSessionCreate } from "./create.js";
+import { runSessionExport } from "./export.js";
 import { runSessionGet } from "./get.js";
 beforeAll(() => {
     process.env["AXIMO_API_KEY"] = "test-key";
@@ -126,3 +131,98 @@ describe("runSessionGet", () => {
             expect(result.error.code).toBe("not_found");
     });
 });
+describe("runSessionCancel", () => {
+    it("POSTs the cancel endpoint and returns the terminated session", async () => {
+        let method;
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions/s1/cancel`, ({ request: req }) => {
+            method = req.method;
+            return HttpResponse.json({ success: true, sessionId: "s1", status: "terminated" });
+        }));
+        const result = await runSessionCancel({ sessionId: "s1" });
+        expect(method).toBe("POST");
+        expect(result).toEqual({
+            ok: true,
+            data: { success: true, sessionId: "s1", status: "terminated" },
+        });
+    });
+    it("shows the request without calling the API on --dry-run", async () => {
+        const result = await runSessionCancel({ sessionId: "s1", dryRun: true });
+        expect(result).toEqual({
+            ok: true,
+            data: { dryRun: true, method: "POST", url: `${TEST_BASE_URL}/api/sessions/s1/cancel` },
+        });
+    });
+    it("rejects an empty id", async () => {
+        const result = await runSessionCancel({ sessionId: "" });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("validation_error");
+    });
+    it("maps a finished session to conflict without the archive hint", async () => {
+        server.use(http.post(`${TEST_BASE_URL}/api/sessions/s1/cancel`, () => HttpResponse.json({ error: "Cannot cancel a session that has already finished" }, { status: 409 })));
+        const result = await runSessionCancel({ sessionId: "s1" });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("conflict");
+            expect(result.error.hint).toBeUndefined();
+        }
+    });
+});
+describe("runSessionExport", () => {
+    const sessionId = "44444444-4444-4444-9444-444444444444";
+    const defaultPdf = resolve(`${sessionId}.pdf`);
+    const dir = mkdtempSync(join(tmpdir(), "aximo-session-export-"));
+    afterEach(() => rmSync(defaultPdf, { force: true }));
+    afterAll(() => rmSync(dir, { recursive: true, force: true }));
+    it("defaults to a PDF named after the session in the working directory", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/pdf`, () => new HttpResponse("%PDF-1.3\n%%EOF\n")));
+        const result = await runSessionExport({ sessionId });
+        expect(result).toEqual({
+            ok: true,
+            data: { sessionId, format: "pdf", path: defaultPdf, sizeBytes: 15 },
+        });
+    });
+    it("downloads the screenshots archive in the requested locale to --output", async () => {
+        let locale = null;
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/screenshots`, ({ request }) => {
+            locale = new URL(request.url).searchParams.get("locale");
+            const eocd = Buffer.alloc(22);
+            eocd.writeUInt32LE(0x06054b50, 0);
+            return new HttpResponse(eocd);
+        }));
+        const output = join(dir, "shots.zip");
+        const result = await runSessionExport({
+            sessionId,
+            format: "screenshots",
+            output,
+            locale: "ja",
+        });
+        expect(result.ok).toBe(true);
+        if (result.ok)
+            expect(result.data.path).toBe(output);
+        expect(locale).toBe("ja");
+    });
+    it.each([
+        [{ format: "docx" }, /format must be one of: pdf, screenshots/],
+        [{ locale: "fr" }, /locale must be one of: en, ja, ko/],
+        [{ sessionId: "" }, /sessionId/],
+    ])("rejects %o", async (overrides, message) => {
+        const result = await runSessionExport({ sessionId, ...overrides });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.code).toBe("validation_error");
+            expect(result.error.message).toMatch(message);
+        }
+    });
+    it("maps the API's 409 to a conflict envelope", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${sessionId}/export/screenshots`, () => HttpResponse.json({ error: "Session has no screenshots to export" }, { status: 409 })));
+        const result = await runSessionExport({
+            sessionId,
+            format: "screenshots",
+            output: join(dir, "x.zip"),
+        });
+        expect(result.ok).toBe(false);
+        if (!result.ok)
+            expect(result.error.code).toBe("conflict");
+    });
+});

package/dist/errors.d.ts

@@ -2,6 +2,8 @@ import type { ErrorEnvelope } from "./types.js";
 export declare function describeDetails(details: unknown): string | undefined;
 export declare function withDetails(message: string, details: unknown): string;
 export declare function featureHint(message: string, details: unknown): string | undefined;
+export declare const CREDIT_HINT = "The organization is out of credits. Ask an Aximo organization admin to add credits, then retry.";
+export declare function creditHint(message: string): string | undefined;
 export declare const ARCHIVE_FIRST_HINT = "Archive the resource first, then retry: `aximo case archive <caseId>` / `aximo plan archive <planId>` (MCP: aximo_archive_case / aximo_archive_plan).";
 export declare function isArchiveFirstConflict(message: string): boolean;
 export declare function handleApiError(error: unknown): ErrorEnvelope;

package/dist/errors.js

@@ -85,6 +85,10 @@ export function featureHint(message, details) {
     }
     return undefined;
 }
+export const CREDIT_HINT = "The organization is out of credits. Ask an Aximo organization admin to add credits, then retry.";
+export function creditHint(message) {
+    return /insufficient credits/i.test(message) ? CREDIT_HINT : undefined;
+}
 const NOT_FOUND_HINT = "Check the ID exists and you have access. List resources: aximo project list / aximo device list / aximo upload list";
 const AUTH_HINT = "Run `aximo configure` to save credentials, or set AXIMO_API_KEY via `export AXIMO_API_KEY=your-key` or `node --env-file=.env`.";
 // 403 is a permission outcome, not a credentials problem, so it no longer routes
@@ -142,6 +146,7 @@ export function handleApiError(error) {
             // when the server says which role is missing. Never the credentials hint: a
             // 403 means the key is valid.
             const hint = featureHint(error.message, details) ??
+                creditHint(error.message) ??
                 (/admin|owner/i.test(message) ? ADMIN_ROLE_HINT : undefined);
             return formatError("forbidden", message, false, hint);
         }

package/dist/errors.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { describeDetails, featureHint, handleApiError, withDetails } from "./errors.js";
+import { CREDIT_HINT, describeDetails, featureHint, handleApiError, withDetails, } from "./errors.js";
 function httpErr(status, message = `status ${status}`, retryAfter) {
     const err = Object.assign(new Error(message), { status });
     if (retryAfter !== undefined)
@@ -27,6 +27,11 @@ describe("handleApiError", () => {
         expect(r.error.code).toBe("forbidden");
         expect(r.error.hint).toContain("admin or owner");
     });
+    it("adds the credit hint when the organization is out of credits", () => {
+        const r = handleApiError(httpErr(403, "Insufficient credits to start session"));
+        expect(r.error.code).toBe("forbidden");
+        expect(r.error.hint).toBe(CREDIT_HINT);
+    });
     it("maps 404 to not_found with list hint", () => {
         const r = handleApiError(httpErr(404));
         expect(r.error.code).toBe("not_found");

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { runPlanRemoveCase } from "./commands/plan/remove-case.js";
 export { runProjectList } from "./commands/project/list.js";
 export { runSessionCreate } from "./commands/session/create.js";
 export { runSessionGet } from "./commands/session/get.js";
+export { runSessionCancel } from "./commands/session/cancel.js";
 export { runSessionSaveAsCase } from "./commands/session/save-as-case.js";
 export { runTriggerCaseGet } from "./commands/trigger/case/get.js";
 export { runTriggerCaseRun } from "./commands/trigger/case/run.js";

package/dist/index.js

@@ -11,6 +11,7 @@ export { runPlanRemoveCase } from "./commands/plan/remove-case.js";
 export { runProjectList } from "./commands/project/list.js";
 export { runSessionCreate } from "./commands/session/create.js";
 export { runSessionGet } from "./commands/session/get.js";
+export { runSessionCancel } from "./commands/session/cancel.js";
 export { runSessionSaveAsCase } from "./commands/session/save-as-case.js";
 export { runTriggerCaseGet } from "./commands/trigger/case/get.js";
 export { runTriggerCaseRun } from "./commands/trigger/case/run.js";

package/dist/session-export.d.ts

@@ -0,0 +1,30 @@
+import { type ClientDeps } from "./client.js";
+export declare const SESSION_EXPORT_FORMATS: readonly ["pdf", "screenshots"];
+export type SessionExportFormat = (typeof SESSION_EXPORT_FORMATS)[number];
+export declare const SESSION_EXPORT_LOCALES: readonly ["en", "ja", "ko"];
+export type SessionExportLocale = (typeof SESSION_EXPORT_LOCALES)[number];
+export interface SessionExportInput {
+    sessionId: string;
+    format: SessionExportFormat;
+    outputPath: string;
+    locale?: SessionExportLocale | undefined;
+}
+export interface SessionExportResult {
+    sessionId: string;
+    format: SessionExportFormat;
+    path: string;
+    sizeBytes: number;
+}
+export declare function defaultExportFileName(sessionId: string, format: SessionExportFormat): string;
+/**
+ * Both exports stream, so a server failure after the first bytes are flushed
+ * reaches the client as HTTP 200 and a truncated body. Each format's trailer is
+ * written last, so its presence is what proves the download is whole.
+ */
+export declare function isCompleteExport(path: string, format: SessionExportFormat): Promise<boolean>;
+/**
+ * Downloads a session export to `outputPath`. The bytes land in a sibling
+ * `.part` file that is renamed into place only once verified complete, so a
+ * failed export neither leaves a corrupt file behind nor replaces an existing one.
+ */
+export declare function exportSession(input: SessionExportInput, deps?: ClientDeps): Promise<SessionExportResult>;

package/dist/session-export.js

@@ -0,0 +1,72 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, rename, rm, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { requestToFile } from "./client.js";
+export const SESSION_EXPORT_FORMATS = ["pdf", "screenshots"];
+export const SESSION_EXPORT_LOCALES = ["en", "ja", "ko"];
+export function defaultExportFileName(sessionId, format) {
+    return format === "pdf" ? `${sessionId}.pdf` : `${sessionId}-screenshots.zip`;
+}
+const EOCD_SIGNATURE = 0x06054b50;
+const EOCD_MIN_LENGTH = 22;
+const EOCD_MAX_LENGTH = EOCD_MIN_LENGTH + 0xffff;
+// PDF readers look for %%EOF within the last 1024 bytes.
+const PDF_TRAILER_WINDOW = 1024;
+async function readTail(path, maxBytes) {
+    const handle = await open(path, "r");
+    try {
+        const { size } = await handle.stat();
+        const length = Math.min(size, maxBytes);
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, size - length);
+        return buffer;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Both exports stream, so a server failure after the first bytes are flushed
+ * reaches the client as HTTP 200 and a truncated body. Each format's trailer is
+ * written last, so its presence is what proves the download is whole.
+ */
+export async function isCompleteExport(path, format) {
+    if (format === "pdf") {
+        return (await readTail(path, PDF_TRAILER_WINDOW)).includes("%%EOF");
+    }
+    // The end-of-central-directory record must end the file exactly: its comment
+    // length has to account for every byte after it, which a signature that
+    // happens to appear inside compressed image data will not.
+    const tail = await readTail(path, EOCD_MAX_LENGTH);
+    for (let at = tail.length - EOCD_MIN_LENGTH; at >= 0; at--) {
+        if (tail.readUInt32LE(at) === EOCD_SIGNATURE &&
+            tail.readUInt16LE(at + 20) === tail.length - at - EOCD_MIN_LENGTH) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Downloads a session export to `outputPath`. The bytes land in a sibling
+ * `.part` file that is renamed into place only once verified complete, so a
+ * failed export neither leaves a corrupt file behind nor replaces an existing one.
+ */
+export async function exportSession(input, deps = {}) {
+    const path = resolve(input.outputPath);
+    await mkdir(dirname(path), { recursive: true });
+    const partialPath = `${path}.${randomUUID().slice(0, 8)}.part`;
+    const query = input.locale ? `?locale=${input.locale}` : "";
+    try {
+        await requestToFile(`/api/sessions/${encodeURIComponent(input.sessionId)}/export/${input.format}${query}`, partialPath, deps);
+        if (!(await isCompleteExport(partialPath, input.format))) {
+            throw new Error(`The ${input.format === "pdf" ? "PDF" : "screenshot archive"} download was truncated before it finished. Retry the export.`);
+        }
+        await rename(partialPath, path);
+    }
+    catch (error) {
+        await rm(partialPath, { force: true });
+        throw error;
+    }
+    const { size } = await stat(path);
+    return { sessionId: input.sessionId, format: input.format, path, sizeBytes: size };
+}

package/dist/session-export.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/session-export.test.js

@@ -0,0 +1,107 @@
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { exportSession, isCompleteExport } from "./session-export.js";
+import { HttpResponse, http, server, TEST_BASE_URL } from "./test-utils.js";
+const SESSION_ID = "11111111-1111-4111-9111-111111111111";
+function eocd(comment = "") {
+    const record = Buffer.alloc(22);
+    record.writeUInt32LE(0x06054b50, 0);
+    record.writeUInt16LE(comment.length, 20);
+    return Buffer.concat([record, Buffer.from(comment)]);
+}
+let dir;
+beforeAll(() => {
+    process.env["AXIMO_API_KEY"] = "test-key";
+    process.env["AXIMO_BASE_URL"] = TEST_BASE_URL;
+    server.listen();
+});
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "aximo-export-"));
+});
+afterEach(() => {
+    server.resetHandlers();
+    rmSync(dir, { recursive: true, force: true });
+});
+afterAll(() => server.close());
+function fileWith(bytes) {
+    const path = join(dir, "file");
+    writeFileSync(path, bytes);
+    return path;
+}
+describe("isCompleteExport", () => {
+    it("accepts a ZIP ending in its end-of-central-directory record", async () => {
+        const body = Buffer.concat([Buffer.from("PK\x03\x04 entries"), eocd()]);
+        expect(await isCompleteExport(fileWith(body), "screenshots")).toBe(true);
+    });
+    it("accepts a ZIP whose record carries a comment", async () => {
+        const body = Buffer.concat([Buffer.from("PK\x03\x04 entries"), eocd("made by aximo")]);
+        expect(await isCompleteExport(fileWith(body), "screenshots")).toBe(true);
+    });
+    it("rejects a ZIP cut off before its record", async () => {
+        const body = Buffer.concat([Buffer.from("PK\x03\x04 entries"), eocd()]).subarray(0, -1);
+        expect(await isCompleteExport(fileWith(body), "screenshots")).toBe(false);
+    });
+    it("rejects a signature inside entry data that does not end the file", async () => {
+        const body = Buffer.concat([
+            Buffer.from("PK\x03\x04"),
+            eocd(),
+            Buffer.from("more entry bytes"),
+        ]);
+        expect(await isCompleteExport(fileWith(body), "screenshots")).toBe(false);
+    });
+    it("rejects a file that starts with the signature but is shorter than the record", async () => {
+        expect(await isCompleteExport(fileWith(eocd().subarray(0, -1)), "screenshots")).toBe(false);
+    });
+    it("rejects an empty file", async () => {
+        expect(await isCompleteExport(fileWith(Buffer.alloc(0)), "screenshots")).toBe(false);
+        expect(await isCompleteExport(fileWith(Buffer.alloc(0)), "pdf")).toBe(false);
+    });
+    it("checks a PDF for its %%EOF trailer", async () => {
+        expect(await isCompleteExport(fileWith(Buffer.from("%PDF-1.3\n...\n%%EOF\n")), "pdf")).toBe(true);
+        expect(await isCompleteExport(fileWith(Buffer.from("%PDF-1.3\n...stream")), "pdf")).toBe(false);
+    });
+});
+describe("exportSession", () => {
+    it("streams the export to the path, creating parent directories", async () => {
+        let url;
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${SESSION_ID}/export/pdf`, ({ request }) => {
+            url = new URL(request.url);
+            return new HttpResponse("%PDF-1.3\n%%EOF\n", {
+                headers: { "Content-Type": "application/pdf" },
+            });
+        }));
+        const outputPath = join(dir, "nested", "report.pdf");
+        const result = await exportSession({
+            sessionId: SESSION_ID,
+            format: "pdf",
+            outputPath,
+            locale: "ja",
+        });
+        expect(result).toEqual({
+            sessionId: SESSION_ID,
+            format: "pdf",
+            path: outputPath,
+            sizeBytes: 15,
+        });
+        expect(url?.searchParams.get("locale")).toBe("ja");
+        expect(readdirSync(join(dir, "nested"))).toEqual(["report.pdf"]);
+    });
+    it("deletes a truncated download and keeps the file it would have replaced", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${SESSION_ID}/export/screenshots`, () => new HttpResponse(Buffer.from("PK\x03\x04 half an archive"))));
+        const outputPath = join(dir, "shots.zip");
+        writeFileSync(outputPath, "previous export");
+        await expect(exportSession({ sessionId: SESSION_ID, format: "screenshots", outputPath })).rejects.toThrow(/truncated/);
+        expect(readdirSync(dir)).toEqual(["shots.zip"]);
+    });
+    it("leaves nothing behind when the API refuses the export", async () => {
+        server.use(http.get(`${TEST_BASE_URL}/api/sessions/${SESSION_ID}/export/screenshots`, () => HttpResponse.json({ error: "Session has no screenshots to export" }, { status: 409 })));
+        await expect(exportSession({
+            sessionId: SESSION_ID,
+            format: "screenshots",
+            outputPath: join(dir, "s.zip"),
+        })).rejects.toMatchObject({ status: 409, message: "Session has no screenshots to export" });
+        expect(readdirSync(dir)).toEqual([]);
+    });
+});