@autifyhq/aximo-cli 0.13.0 → 0.15.0

package/dist/errors.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { handleApiError } from "./errors.js";
+import { 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)
@@ -15,8 +15,17 @@ describe("handleApiError", () => {
         expect(r.error.hint).toContain("AXIMO_API_KEY");
         expect(r.error.hint).toContain("--env-file");
     });
-    it("maps 403 to unauthorized", () => {
-        expect(handleApiError(httpErr(403)).error.code).toBe("unauthorized");
+    // 403 is its own code as of GEN-2793: it means the key is valid but the role is
+    // not sufficient, which is a different remedy from a missing or bad key.
+    it("maps 403 to forbidden, with no credentials hint", () => {
+        const r = handleApiError(httpErr(403));
+        expect(r.error.code).toBe("forbidden");
+        expect(r.error.hint).toBeUndefined();
+    });
+    it("adds the admin-role hint only when the server names the role", () => {
+        const r = handleApiError(httpErr(403, "Only admins and owners can perform this action"));
+        expect(r.error.code).toBe("forbidden");
+        expect(r.error.hint).toContain("admin or owner");
     });
     it("maps 404 to not_found with list hint", () => {
         const r = handleApiError(httpErr(404));
@@ -86,3 +95,97 @@ describe("handleApiError", () => {
         expect(handleApiError("weird").error.message).toBe("weird");
     });
 });
+function httpErrWithDetails(status, message, details) {
+    return Object.assign(new Error(message), { status, details });
+}
+describe("describeDetails", () => {
+    it("renders path, feature, ids, unknownFields and hint", () => {
+        expect(describeDetails({ path: "apiWebConfig.hostnameOverrideIds", ids: ["a", "b"] })).toBe("at apiWebConfig.hostnameOverrideIds; ids: a, b");
+        expect(describeDetails({ feature: "multiDeviceEnabled" })).toBe("requires feature multiDeviceEnabled");
+        expect(describeDetails({ unknownFields: ["userDeviceId"], hint: "Put it inside apiDesktopConfig." })).toBe("unknown fields: userDeviceId; Put it inside apiDesktopConfig.");
+    });
+    it("walks a zod treeifyError tree into path: message lines", () => {
+        const tree = {
+            errors: ["Unrecognized key"],
+            properties: {
+                apiMobileConfig: {
+                    errors: [],
+                    properties: {
+                        deviceArn: { errors: ["Required"] },
+                        apps: {
+                            errors: [],
+                            items: [null, { errors: [], properties: { uploadArn: { errors: ["Required"] } } }],
+                        },
+                    },
+                },
+            },
+        };
+        expect(describeDetails(tree)).toBe("Unrecognized key; apiMobileConfig.deviceArn: Required; apiMobileConfig.apps[1].uploadArn: Required");
+    });
+    it("walks a zod flattenError fieldErrors map", () => {
+        expect(describeDetails({
+            formErrors: [],
+            fieldErrors: { platform: ["Invalid enum value"], limit: ["Too big"] },
+        })).toBe("platform: Invalid enum value; limit: Too big");
+    });
+    it("caps zod issues at five lines", () => {
+        const fieldErrors = {};
+        for (let i = 0; i < 8; i++)
+            fieldErrors[`f${i}`] = ["bad"];
+        expect(describeDetails({ fieldErrors })?.split("; ")).toHaveLength(5);
+    });
+    it("returns undefined for non-object or empty details", () => {
+        expect(describeDetails(undefined)).toBeUndefined();
+        expect(describeDetails("x")).toBeUndefined();
+        expect(describeDetails(["x"])).toBeUndefined();
+        expect(describeDetails({})).toBeUndefined();
+        expect(describeDetails({ errors: [], properties: { a: { errors: 5 } } })).toBeUndefined();
+    });
+});
+describe("withDetails / featureHint", () => {
+    it("appends rendered details in parentheses", () => {
+        expect(withDetails("Upload not found", { path: "apiMobileConfig.apps[0].uploadArn" })).toBe("Upload not found (at apiMobileConfig.apps[0].uploadArn)");
+        expect(withDetails("Upload not found", undefined)).toBe("Upload not found");
+    });
+    it("names the feature from details, or recognises the not-enabled message", () => {
+        expect(featureHint("Forbidden", { feature: "byodEnabled" })).toBe("Ask an Aximo organization admin to enable byodEnabled.");
+        expect(featureHint("Multi-device cases are not enabled for this organization", undefined)).toBe("Ask an Aximo organization admin to enable this feature.");
+        expect(featureHint("Forbidden", { feature: 3 })).toBeUndefined();
+    });
+});
+describe("handleApiError with details", () => {
+    it("names the failing path on a 404", () => {
+        const r = handleApiError(httpErrWithDetails(404, "Upload not found", {
+            path: "apiMultiDeviceConfig[1].apps[0].uploadArn",
+        }));
+        expect(r.error.code).toBe("not_found");
+        expect(r.error.message).toBe("Upload not found (at apiMultiDeviceConfig[1].apps[0].uploadArn)");
+    });
+    it("swaps the credentials hint for an admin hint on a feature-gated 403", () => {
+        const r = handleApiError(httpErrWithDetails(403, "Desktop cases are not enabled for this organization", {
+            feature: "byodEnabled",
+        }));
+        expect(r.error.code).toBe("forbidden");
+        expect(r.error.message).toContain("requires feature byodEnabled");
+        expect(r.error.hint).toBe("Ask an Aximo organization admin to enable byodEnabled.");
+    });
+    it("renders zod issues on a 400", () => {
+        const r = handleApiError(httpErrWithDetails(400, "Invalid request body", {
+            errors: [],
+            properties: { apiWebConfig: { errors: ["Expected object, received string"] } },
+        }));
+        expect(r.error.code).toBe("validation_error");
+        expect(r.error.message).toBe("Invalid request body (apiWebConfig: Expected object, received string)");
+    });
+});
+describe("collectIssues cap", () => {
+    it("caps issue lines even within a single errors array", () => {
+        const details = {
+            properties: {
+                scenario: { errors: Array.from({ length: 12 }, (_, i) => `msg ${i}`) },
+            },
+        };
+        const text = describeDetails(details);
+        expect(text?.split("; ")).toHaveLength(5);
+    });
+});

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([]);
+    });
+});

package/dist/types.d.ts

@@ -6,7 +6,7 @@ export interface SuccessEnvelope<T> {
     data: T;
     meta?: SuccessMeta | undefined;
 }
-export type ErrorCode = "unauthorized" | "rate_limited" | "not_found" | "validation_error" | "api_error";
+export type ErrorCode = "unauthorized" | "forbidden" | "rate_limited" | "not_found" | "validation_error" | "conflict" | "api_error";
 export interface ErrorEnvelope {
     ok: false;
     error: {
@@ -186,6 +186,17 @@ export interface Device {
     arn?: string | undefined;
     name?: string | undefined;
     platform?: Platform | undefined;
+    os?: string | undefined;
+    [key: string]: unknown;
+}
+export interface UserDevice {
+    id: string;
+    name: string;
+    platform: string;
+    os?: string | null;
+    status: string;
+    lastSeenAt?: string | null;
+    createdAt: string;
     [key: string]: unknown;
 }
 export interface CreateUploadInput {
@@ -202,6 +213,10 @@ export interface Upload {
     id?: string | undefined;
     fileName?: string | undefined;
     fileType?: FileType | undefined;
+    uploadArn?: string | undefined;
+    status?: string | undefined;
+    appName?: string | null | undefined;
+    identifier?: string | null | undefined;
     [key: string]: unknown;
 }
 export interface UploadPutResult {
@@ -232,11 +247,15 @@ export interface CreateCaseResult {
 }
 export interface UpdateCaseInput {
     title?: string | undefined;
-    description?: string | undefined;
+    description?: string | null | undefined;
     scenario?: string | undefined;
     type?: CaseType | undefined;
     format?: CaseFormat | undefined;
-    startUrl?: string | undefined;
+    startUrl?: string | null | undefined;
+    apiMobileConfig?: CaseMobileConfig | null | undefined;
+    apiDesktopConfig?: Pick<CaseDesktopConfig, "userDeviceId"> | null | undefined;
+    apiMultiDeviceConfig?: CaseMultiDeviceDevice[] | null | undefined;
+    apiWebConfig?: CaseWebConfig | null | undefined;
 }
 export interface UpdateCaseResult {
     success: boolean;
@@ -250,11 +269,30 @@ export interface UpdateCaseResult {
         format: CaseFormat;
         startUrl: string | null;
         updatedAt: string;
+        apiMobileConfig: CaseMobileConfig | null;
+        apiWebConfig: CaseWebConfig | null;
+        apiDesktopConfig: CaseDesktopConfig | null;
+        apiMultiDeviceConfig: CaseMultiDeviceDevice[] | null;
     };
 }
 export interface DeleteCaseResult {
     success: boolean;
 }
+export interface ArchiveCaseResult {
+    archived: boolean;
+}
+export interface ArchivePlanResult {
+    archived: boolean;
+}
+export interface RestoreCaseResult {
+    restored: boolean;
+}
+export interface RestorePlanResult {
+    restored: boolean;
+}
+export interface DeletePlanResult {
+    success: boolean;
+}
 export interface CreatePlanInput {
     projectId: string;
     title: string;

package/dist/validate.d.ts

@@ -17,3 +17,4 @@ export declare class JsonBodyError extends Error {
 }
 export declare function parseJsonBody(value: unknown): Record<string, unknown>;
 export declare function parseJsonObject(name: string, value: unknown): Record<string, unknown> | undefined;
+export declare function parseJsonArray(name: string, value: unknown): unknown[] | undefined;

package/dist/validate.js

@@ -130,20 +130,32 @@ export function parseJsonBody(value) {
     }
     return parsed;
 }
-export function parseJsonObject(name, value) {
+function parseJsonFlag(name, value) {
     if (value === undefined || value === "")
         return undefined;
     if (typeof value !== "string")
         throw new Error(`${name} must be a JSON string`);
-    let parsed;
     try {
-        parsed = JSON.parse(value);
+        return JSON.parse(value);
     }
     catch (err) {
         throw new Error(`${name} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
     }
+}
+export function parseJsonObject(name, value) {
+    const parsed = parseJsonFlag(name, value);
+    if (parsed === undefined)
+        return undefined;
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
         throw new Error(`${name} must be a JSON object`);
     }
     return parsed;
 }
+export function parseJsonArray(name, value) {
+    const parsed = parseJsonFlag(name, value);
+    if (parsed === undefined)
+        return undefined;
+    if (!Array.isArray(parsed))
+        throw new Error(`${name} must be a JSON array`);
+    return parsed;
+}

package/dist/validate.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { requireString, requireId, parseCaseFormat, parseCaseType, parsePlatform, parseSaveAsCaseType, parseFileType, parseTags, parseJsonObject, parseJsonBody, JsonBodyError, } from "./validate.js";
+import { requireString, requireId, parseCaseFormat, parseCaseType, parsePlatform, parseSaveAsCaseType, parseFileType, parseTags, parseJsonObject, parseJsonArray, parseJsonBody, JsonBodyError, } from "./validate.js";
 describe("requireId", () => {
     it("accepts plain IDs", () => {
         expect(requireId("sessionId", "abc123_-")).toBe("abc123_-");
@@ -132,3 +132,20 @@ describe("parseCaseFormat", () => {
         expect(() => parseCaseFormat("klingon")).toThrow(/must be gherkin, markdown, or plain_text/);
     });
 });
+describe("parseJsonArray", () => {
+    it("parses a JSON array", () => {
+        expect(parseJsonArray("multiDeviceConfig", '[{"kind":"web"}]')).toEqual([{ kind: "web" }]);
+    });
+    it("rejects objects", () => {
+        expect(() => parseJsonArray("x", "{}")).toThrow("must be a JSON array");
+    });
+    it("rejects invalid JSON and non-strings", () => {
+        expect(() => parseJsonArray("x", "[bad")).toThrow("not valid JSON");
+        expect(() => parseJsonArray("x", 5)).toThrow("must be a JSON string");
+        expect(() => parseJsonObject("x", 5)).toThrow("must be a JSON string");
+    });
+    it("returns undefined for empty input", () => {
+        expect(parseJsonArray("x", "")).toBeUndefined();
+        expect(parseJsonArray("x", undefined)).toBeUndefined();
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autifyhq/aximo-cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Autify Aximo Command Line Interface (CLI)",
   "keywords": [
     "autify",