speqs 0.4.0 → 0.5.0

package/dist/lib/output.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Output formatting utilities.
+ * Supports both human-readable and JSON output modes.
+ */
+export declare function output(data: unknown, json: boolean): void;
+export declare function outputList(rows: unknown[], json: boolean): void;
+export declare function outputError(err: unknown, json: boolean): void;
+export declare function printTable(headers: string[], rows: string[][]): void;
+export declare function printKeyValue(obj: Record<string, unknown>, indent?: string): void;
+export declare function formatWorkspaceList(workspaces: Record<string, unknown>[], json: boolean): void;
+export declare function formatWorkspaceDetail(workspace: Record<string, unknown>, json: boolean): void;
+export declare function formatStudyList(studies: Record<string, unknown>[], json: boolean): void;
+export declare function formatStudyDetail(study: Record<string, unknown>, json: boolean): void;
+export declare function formatStudyResults(study: Record<string, unknown>, json: boolean): void;
+export declare function formatIterationList(iterations: Record<string, unknown>[], json: boolean): void;
+export declare function formatTesterDetail(tester: Record<string, unknown>, json: boolean): void;
+export declare function formatTesterProfileList(profiles: unknown, json: boolean, limit?: number): void;
+export declare function formatSimulationPoll(results: Record<string, unknown>[], json: boolean): void;
+export declare function formatConfigList(configs: Record<string, unknown>[], json: boolean): void;

package/dist/lib/output.js

@@ -0,0 +1,454 @@
+/**
+ * Output formatting utilities.
+ * Supports both human-readable and JSON output modes.
+ */
+import { ApiError } from "./api-client.js";
+// --- JSON mode: always full data ---
+export function output(data, json) {
+    if (json) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    if (data === null || data === undefined)
+        return;
+    if (Array.isArray(data)) {
+        outputList(data, json);
+        return;
+    }
+    if (typeof data === "object") {
+        printKeyValue(data);
+        return;
+    }
+    console.log(String(data));
+}
+export function outputList(rows, json) {
+    if (json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log("No results.");
+        return;
+    }
+    // Generic list: show name + key fields
+    for (const row of rows) {
+        if (typeof row === "object" && row !== null) {
+            const obj = row;
+            const parts = [];
+            if (obj.name)
+                parts.push(String(obj.name));
+            if (obj.status)
+                parts.push(`[${obj.status}]`);
+            if (obj.modality)
+                parts.push(String(obj.modality));
+            console.log("  " + parts.join("  "));
+        }
+        else {
+            console.log("  " + String(row));
+        }
+    }
+}
+export function outputError(err, json) {
+    if (err instanceof ApiError) {
+        if (json) {
+            console.error(JSON.stringify({
+                error: err.message,
+                error_code: err.error_code,
+                status: err.status,
+                retryable: err.retryable,
+            }));
+        }
+        else {
+            if (err.status === 402) {
+                console.error("Error: Insufficient credits. Purchase more at https://app.speqs.io");
+            }
+            else {
+                console.error(`Error: ${err.message}`);
+            }
+        }
+    }
+    else if (err instanceof Error) {
+        if (json) {
+            console.error(JSON.stringify({ error: err.message, error_code: "client_error", retryable: false }));
+        }
+        else {
+            console.error(`Error: ${err.message}`);
+        }
+    }
+    else {
+        if (json) {
+            console.error(JSON.stringify({ error: String(err), error_code: "unknown_error", retryable: false }));
+        }
+        else {
+            console.error(`Error: ${err}`);
+        }
+    }
+}
+// --- Entity-specific formatters (human mode) ---
+export function printTable(headers, rows) {
+    const colWidths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] || "").length)));
+    console.log("  " + headers.map((h, i) => h.padEnd(colWidths[i])).join("  "));
+    for (const row of rows) {
+        console.log("  " + row.map((cell, i) => (cell || "").padEnd(colWidths[i])).join("  "));
+    }
+}
+export function printKeyValue(obj, indent = "  ") {
+    const entries = Object.entries(obj).filter(([, v]) => v !== null && v !== undefined);
+    if (entries.length === 0)
+        return;
+    const maxKeyLen = Math.max(...entries.map(([k]) => k.length));
+    for (const [key, value] of entries) {
+        const label = formatLabel(key);
+        const displayValue = typeof value === "object" && value !== null
+            ? JSON.stringify(value)
+            : String(value);
+        console.log(`${indent}${label.padEnd(maxKeyLen + 2)}${displayValue}`);
+    }
+}
+function formatLabel(key) {
+    return key
+        .replace(/_/g, " ")
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+// --- Workspace formatting ---
+export function formatWorkspaceList(workspaces, json) {
+    if (json) {
+        console.log(JSON.stringify(workspaces, null, 2));
+        return;
+    }
+    if (workspaces.length === 0) {
+        console.log("No workspaces.");
+        return;
+    }
+    printTable(["ID", "NAME", "CREATED"], workspaces.map((w) => [
+        String(w.id || ""),
+        String(w.name || ""),
+        formatDate(w.created_at),
+    ]));
+}
+export function formatWorkspaceDetail(workspace, json) {
+    if (json) {
+        console.log(JSON.stringify(workspace, null, 2));
+        return;
+    }
+    const display = {
+        Name: workspace.name,
+        Description: workspace.description || "-",
+        "Base URL": workspace.base_url || "-",
+        Created: formatDate(workspace.created_at),
+    };
+    printKeyValue(display);
+}
+// --- Study formatting ---
+export function formatStudyList(studies, json) {
+    if (json) {
+        console.log(JSON.stringify(studies, null, 2));
+        return;
+    }
+    if (studies.length === 0) {
+        console.log("No studies.");
+        return;
+    }
+    printTable(["ID", "NAME", "MODALITY", "STATUS", "TESTERS"], studies.map((s) => [
+        String(s.id || ""),
+        String(s.name || ""),
+        String(s.modality || "-"),
+        String(s.status || "draft"),
+        String(s.tester_count ?? "0"),
+    ]));
+}
+export function formatStudyDetail(study, json) {
+    if (json) {
+        console.log(JSON.stringify(study, null, 2));
+        return;
+    }
+    // Header
+    console.log(String(study.name || "Untitled"));
+    if (study.description)
+        console.log(String(study.description));
+    console.log(`${study.modality || "-"} · ${study.status || "draft"} · ${formatDate(study.created_at)}`);
+    // Assignments
+    const assignments = Array.isArray(study.assignments) ? study.assignments : [];
+    if (assignments.length > 0) {
+        console.log("\nAssignments:");
+        for (let i = 0; i < assignments.length; i++) {
+            const a = assignments[i];
+            console.log(`  ${i + 1}. ${a.name || "Untitled"}`);
+            if (a.instructions) {
+                console.log(`     ${truncate(String(a.instructions), 80)}`);
+            }
+        }
+    }
+    // Interview Questions
+    const questions = Array.isArray(study.interview_questions) ? study.interview_questions : [];
+    if (questions.length > 0) {
+        console.log("\nInterview Questions:");
+        for (let i = 0; i < questions.length; i++) {
+            const q = questions[i];
+            const typeStr = formatQuestionType(q);
+            console.log(`  ${i + 1}. ${q.question || "Untitled"} ${typeStr}`);
+        }
+    }
+    // Testers summary
+    const allTesters = collectTesters(study);
+    if (allTesters.length > 0) {
+        console.log(`\nTesters (${allTesters.length}):`);
+        printTable(["ID", "NAME", "ITERATION", "STATUS", "INTERACTIONS"], allTesters.map((t) => [
+            t.id,
+            t.name,
+            t.iterationLabel,
+            t.status,
+            String(t.interactionCount),
+        ]));
+    }
+}
+export function formatStudyResults(study, json) {
+    if (json) {
+        console.log(JSON.stringify(study, null, 2));
+        return;
+    }
+    const allTesters = collectTesters(study);
+    const totalInteractions = allTesters.reduce((sum, t) => sum + t.interactionCount, 0);
+    // Header
+    console.log(`${study.name || "Untitled"} — Results`);
+    console.log(`${allTesters.length} tester${allTesters.length !== 1 ? "s" : ""} · ${totalInteractions} total interactions`);
+    // Sentiment summary
+    const totalSentiment = {};
+    for (const t of allTesters) {
+        for (const [label, count] of Object.entries(t.sentimentCounts)) {
+            totalSentiment[label] = (totalSentiment[label] || 0) + count;
+        }
+    }
+    const sentimentParts = Object.entries(totalSentiment).map(([label, count]) => `${count} ${label.toLowerCase()}`);
+    console.log(`\nSentiment: ${sentimentParts.length > 0 ? sentimentParts.join(", ") : "none"}`);
+    // Interview Answers grouped by question
+    const questions = Array.isArray(study.interview_questions) ? study.interview_questions : [];
+    if (questions.length > 0) {
+        console.log("\nInterview Answers:");
+        for (const q of questions) {
+            const qObj = q;
+            const typeStr = formatQuestionType(qObj);
+            console.log(`\n  "${qObj.question}" ${typeStr}`);
+            for (const t of allTesters) {
+                const answer = t.interviewAnswers.find((a) => a.questionId === qObj.id);
+                if (answer) {
+                    const answerStr = typeof answer.answer === "string"
+                        ? `"${truncate(answer.answer, 70)}"`
+                        : String(answer.answer);
+                    console.log(`    ${t.name} (${t.iterationLabel}):  ${answerStr}`);
+                }
+            }
+        }
+    }
+    // Testers table
+    if (allTesters.length > 0) {
+        console.log("\nTesters:");
+        printTable(["ID", "NAME", "ITERATION", "STATUS", "INTERACTIONS", "SENTIMENT"], allTesters.map((t) => {
+            const parts = Object.entries(t.sentimentCounts).map(([label, count]) => `${count} ${label.toLowerCase()}`);
+            return [
+                t.id,
+                t.name,
+                t.iterationLabel,
+                t.status,
+                String(t.interactionCount),
+                parts.length > 0 ? parts.join(", ") : "-",
+            ];
+        }));
+        console.log("\nRun `speqs tester get <id> --json` for full interaction details.");
+    }
+}
+function collectTesters(study) {
+    const iterations = Array.isArray(study.iterations) ? study.iterations : [];
+    const testers = [];
+    for (const iter of iterations) {
+        const it = iter;
+        const iterLabel = String(it.label || it.name || "-");
+        const iterTesters = Array.isArray(it.testers) ? it.testers : [];
+        for (const tester of iterTesters) {
+            const t = tester;
+            const profile = t.tester_profile;
+            const interactions = Array.isArray(t.interactions) ? t.interactions : [];
+            const sentimentCounts = {};
+            for (const interaction of interactions) {
+                const ix = interaction;
+                const sentiment = ix.sentiment;
+                if (sentiment?.label) {
+                    const label = String(sentiment.label);
+                    sentimentCounts[label] = (sentimentCounts[label] || 0) + 1;
+                }
+            }
+            const answers = Array.isArray(t.interview_answers) ? t.interview_answers : [];
+            testers.push({
+                id: String(t.id || ""),
+                name: String(profile?.name || t.instance_name || "Unknown"),
+                iterationLabel: iterLabel,
+                status: String(t.status || "-"),
+                interactionCount: interactions.length,
+                sentimentCounts,
+                interviewAnswers: answers.map((a) => ({
+                    questionId: String(a.question_id || ""),
+                    answer: a.answer,
+                })),
+            });
+        }
+    }
+    return testers;
+}
+function formatQuestionType(q) {
+    if (!q.type)
+        return "";
+    if (q.type === "slider" && q.min !== undefined && q.max !== undefined) {
+        return `[${q.type} ${q.min}-${q.max}]`;
+    }
+    return `[${q.type}]`;
+}
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + "...";
+}
+// --- Iteration formatting ---
+export function formatIterationList(iterations, json) {
+    if (json) {
+        console.log(JSON.stringify(iterations, null, 2));
+        return;
+    }
+    if (iterations.length === 0) {
+        console.log("No iterations.");
+        return;
+    }
+    printTable(["ID", "LABEL", "NAME", "TESTERS", "CREATED"], iterations.map((it) => {
+        const testers = Array.isArray(it.testers) ? it.testers.length : 0;
+        return [
+            String(it.id || ""),
+            String(it.label || "-"),
+            String(it.name || ""),
+            String(testers),
+            formatDate(it.created_at),
+        ];
+    }));
+}
+// --- Tester formatting ---
+export function formatTesterDetail(tester, json) {
+    if (json) {
+        console.log(JSON.stringify(tester, null, 2));
+        return;
+    }
+    const profile = tester.tester_profile;
+    const profileName = profile?.name ? String(profile.name) : "Unknown";
+    const interactions = Array.isArray(tester.interactions) ? tester.interactions : [];
+    // Count sentiments
+    const sentimentCounts = {};
+    for (const interaction of interactions) {
+        const it = interaction;
+        const sentiment = it.sentiment;
+        if (sentiment?.label) {
+            const label = String(sentiment.label);
+            sentimentCounts[label] = (sentimentCounts[label] || 0) + 1;
+        }
+    }
+    const sentimentParts = Object.entries(sentimentCounts).map(([label, count]) => `${count} ${label.toLowerCase()}`);
+    const display = {
+        Profile: profileName,
+        Status: tester.status || "-",
+        Platform: tester.platform || "-",
+        Language: tester.language || "-",
+        Interactions: `${interactions.length} interactions`,
+        ...(sentimentParts.length > 0 && {
+            Sentiment: sentimentParts.join(", "),
+        }),
+    };
+    printKeyValue(display);
+}
+// --- Tester Profile formatting ---
+export function formatTesterProfileList(profiles, json, limit) {
+    if (json) {
+        console.log(JSON.stringify(profiles, null, 2));
+        return;
+    }
+    // The API may return { items: [...], total, limit, offset } or a flat array
+    const wrapper = profiles;
+    const fullList = Array.isArray(profiles) ? profiles
+        : Array.isArray(wrapper?.items) ? wrapper.items
+            : Array.isArray(wrapper?.profiles) ? wrapper.profiles
+                : null;
+    if (!Array.isArray(fullList) || fullList.length === 0) {
+        console.log("No tester profiles.");
+        return;
+    }
+    // Client-side limit (server may not enforce it)
+    const list = limit ? fullList.slice(0, limit) : fullList;
+    printTable(["ID", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
+        String(p.id || ""),
+        String(p.name || ""),
+        String(p.occupation || "-"),
+        String(p.country || "-"),
+        String(p.gender || "-"),
+        formatAge(p.date_of_birth),
+    ]));
+    if (fullList.length > list.length) {
+        console.log(`\n  Showing ${list.length} of ${fullList.length} profiles. Use --limit and --offset for more.`);
+    }
+}
+// --- Simulation poll formatting ---
+export function formatSimulationPoll(results, json) {
+    if (json) {
+        console.log(JSON.stringify({ results }, null, 2));
+        return;
+    }
+    if (results.length === 0) {
+        console.log("No simulations found.");
+        return;
+    }
+    printTable(["ID", "TESTER", "STATUS", "INTERACTIONS"], results.map((r) => [
+        String(r.id || r.tester_id || ""),
+        String(r.tester_name || "Unknown"),
+        String(r.status || "UNKNOWN"),
+        String(r.interaction_count ?? "0"),
+    ]));
+}
+// --- Config formatting ---
+export function formatConfigList(configs, json) {
+    if (json) {
+        console.log(JSON.stringify(configs, null, 2));
+        return;
+    }
+    if (configs.length === 0) {
+        console.log("No simulation configs.");
+        return;
+    }
+    printTable(["ID", "NAME", "SOURCE", "CREATED"], configs.map((c) => [
+        String(c.id || ""),
+        String(c.name || ""),
+        String(c.source_type || "manual"),
+        formatDate(c.created_at),
+    ]));
+}
+// --- Helpers ---
+function formatAge(dob) {
+    if (!dob)
+        return "-";
+    try {
+        const birth = new Date(String(dob));
+        const now = new Date();
+        let age = now.getFullYear() - birth.getFullYear();
+        const monthDiff = now.getMonth() - birth.getMonth();
+        if (monthDiff < 0 || (monthDiff === 0 && now.getDate() < birth.getDate()))
+            age--;
+        return String(age);
+    }
+    catch {
+        return "-";
+    }
+}
+function formatDate(value) {
+    if (!value)
+        return "-";
+    const str = String(value);
+    try {
+        return new Date(str).toLocaleDateString("en-CA"); // YYYY-MM-DD
+    }
+    catch {
+        return str.slice(0, 10);
+    }
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,202 @@
+/**
+ * TypeScript interfaces for Speqs API entities.
+ */
+export interface Product {
+    id: string;
+    name: string;
+    description?: string;
+    color?: string;
+    base_url?: string;
+    product_type?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ProductCreateInput {
+    name: string;
+    description?: string;
+    color?: string;
+    base_url?: string;
+}
+export interface ProductUpdateInput {
+    name?: string;
+    description?: string;
+    color?: string;
+    base_url?: string;
+}
+export interface Assignment {
+    id?: string;
+    name: string;
+    instructions: string;
+}
+export interface InterviewQuestion {
+    id?: string;
+    question: string;
+    type?: string;
+    timing?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    labels?: string[];
+    options?: string[];
+}
+export interface Study {
+    id: string;
+    product_id: string;
+    name: string;
+    description?: string;
+    modality?: string;
+    content_type?: string;
+    status?: string;
+    start_frame_id?: string;
+    source_study_id?: string;
+    assignments?: Assignment[];
+    interview_questions?: InterviewQuestion[];
+    frames?: unknown[];
+    iterations?: Iteration[];
+    created_at: string;
+    updated_at: string;
+    created_by?: string;
+}
+export interface StudyCreateInput {
+    product_id: string;
+    name: string;
+    description?: string;
+    modality?: string;
+    content_type?: string;
+    assignments?: Assignment[];
+    interview_questions?: InterviewQuestion[];
+    start_frame_id?: string;
+}
+export interface StudyUpdateInput {
+    name?: string;
+    description?: string;
+    status?: string;
+    modality?: string;
+    content_type?: string;
+    assignments?: Assignment[];
+    interview_questions?: InterviewQuestion[];
+    start_frame_id?: string;
+}
+export interface StudyGenerateInput {
+    problem_description: string;
+    target_url?: string;
+}
+export interface Iteration {
+    id: string;
+    study_id: string;
+    name?: string;
+    description?: string;
+    label?: string;
+    details?: Record<string, unknown>;
+    testers?: Tester[];
+    created_at: string;
+    updated_at: string;
+}
+export interface IterationCreateInput {
+    name: string;
+    description?: string;
+    details?: Record<string, unknown>;
+}
+export interface IterationUpdateInput {
+    name?: string;
+    description?: string;
+    details?: Record<string, unknown>;
+    label?: string;
+}
+export interface TesterProfile {
+    id: string;
+    name: string;
+    [key: string]: unknown;
+}
+export interface Tester {
+    id: string;
+    iteration_id: string;
+    tester_profile_id: string;
+    instance_name?: string;
+    instance_number?: number;
+    status: string;
+    language?: string;
+    platform?: string;
+    tester_type?: string;
+    viewport_width?: number;
+    viewport_height?: number;
+    created_at: string;
+}
+export interface TesterCreateInput {
+    tester_profile_id: string;
+    instance_name?: string;
+    status?: string;
+    language?: string;
+    platform?: string;
+    tester_type?: string;
+}
+export interface SimulationStartInput {
+    product_id: string;
+    study_id: string;
+    tester_id: string;
+    config_id?: string;
+    platform?: string;
+    url?: string;
+    screen_format?: string;
+    max_interactions?: number;
+    language?: string;
+    locale?: string;
+    config_overrides?: Record<string, unknown>;
+}
+export interface SimulationStartResponse {
+    tester_id: string;
+    study_id: string;
+    job_id: string | null;
+    message: string;
+}
+export interface SimulationBatchItem {
+    study_id: string;
+    tester_id: string;
+    config_id?: string;
+    language?: string;
+    locale?: string;
+    config_overrides?: Record<string, unknown>;
+}
+export interface SimulationBatchStartInput {
+    product_id: string;
+    simulations: SimulationBatchItem[];
+    url?: string;
+    screen_format?: string;
+    platform?: string;
+    max_interactions?: number;
+}
+export interface SimulationBatchStartResponse {
+    results: SimulationStartResponse[];
+}
+export interface MediaSimulationStartInput {
+    product_id: string;
+    study_id: string;
+    tester_id: string;
+    config_id?: string;
+    max_interactions?: number;
+    language?: string;
+    config_overrides?: Record<string, unknown>;
+}
+export interface SimulationStatus {
+    job_id: string;
+    status: string | null;
+    create_time?: string;
+    completion_time?: string;
+    error?: string;
+}
+export interface SimulationCancelResponse {
+    job_id: string;
+    success: boolean;
+    message: string;
+}
+export interface SimulationConfig {
+    id: string;
+    name: string;
+    model_settings?: Record<string, unknown>;
+    simulation_settings?: Record<string, unknown>;
+    prompts?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+    source_type?: string;
+    created_at: string;
+    updated_at: string;
+}

package/dist/lib/types.js

@@ -0,0 +1,4 @@
+/**
+ * TypeScript interfaces for Speqs API entities.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speqs",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The command-line interface for Speqs",
   "type": "module",
   "bin": {