@dichovsky/testrail-api-client 1.0.0

package/dist/cli.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { createRequire } from 'node:module';
+import { TestRailClient } from './client.js';
+// ── Version ───────────────────────────────────────────────────────────────────
+const require = createRequire(import.meta.url);
+const VERSION = require('../package.json').version;
+// ── Arg Parsing ───────────────────────────────────────────────────────────────
+const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        'base-url': { type: 'string' },
+        email: { type: 'string' },
+        'api-key': { type: 'string' },
+        format: { type: 'string', default: 'json' },
+        quiet: { type: 'boolean', default: false },
+        help: { type: 'boolean', default: false },
+        version: { type: 'boolean', default: false },
+        'project-id': { type: 'string' },
+        'suite-id': { type: 'string' },
+        'run-id': { type: 'string' },
+        'case-id': { type: 'string' },
+        limit: { type: 'string' },
+        offset: { type: 'string' },
+    },
+    allowPositionals: true,
+    strict: false,
+});
+// ── Output Helpers ────────────────────────────────────────────────────────────
+const quiet = values.quiet === true;
+const format = values.format ?? 'json';
+function out(data) {
+    if (quiet)
+        return;
+    if (format === 'table') {
+        process.stdout.write(`${renderTable(data)}\n`);
+    }
+    else {
+        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+    }
+}
+function err(message) {
+    if (!quiet)
+        process.stderr.write(`Error: ${message}\n`);
+}
+function valueToString(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    if (typeof v === 'string')
+        return v;
+    if (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'bigint')
+        return String(v);
+    if (typeof v === 'symbol')
+        return v.toString();
+    return '[Function]';
+}
+function renderTable(data) {
+    const rows = Array.isArray(data) ? data : [data];
+    if (rows.length === 0)
+        return '(empty)';
+    const first = rows[0];
+    if (typeof first !== 'object' || first === null) {
+        return rows.map(String).join('\n');
+    }
+    const keys = Object.keys(first);
+    const widths = keys.map((k) => Math.max(k.length, ...rows.map((r) => valueToString(r[k]).length)));
+    const line = widths.map((w) => '-'.repeat(w)).join('-+-');
+    const header = keys.map((k, i) => k.padEnd(widths[i] ?? k.length)).join(' | ');
+    const body = rows.map((r) => keys.map((k, i) => valueToString(r[k]).padEnd(widths[i] ?? k.length)).join(' | '));
+    return [header, line, ...body].join('\n');
+}
+// ── Help ──────────────────────────────────────────────────────────────────────
+const HELP = `
+testrail <resource> <action> [id] [options]
+
+Resources & actions:
+  project  get <id> | list [--limit N] [--offset N]
+  suite    get <id> | list --project-id <id>
+  case     get <id> | list --project-id <id> [--suite-id <id>]
+  run      get <id> | list --project-id <id> [--limit N] [--offset N]
+  result   list --run-id <id> [--limit N] [--offset N]
+  milestone  get <id> | list --project-id <id> [--limit N] [--offset N]
+  user     get <id> | list [--limit N] [--offset N]
+
+Auth (env var or flag):
+  TESTRAIL_BASE_URL / --base-url <url>
+  TESTRAIL_EMAIL    / --email <email>
+  TESTRAIL_API_KEY  / --api-key <key>
+
+Options:
+  --format json|table   Output format (default: json)
+  --quiet               Suppress output; use exit code 0/1
+  --help                Show this help
+  --version             Print version
+`.trim();
+// ── Entry Point ───────────────────────────────────────────────────────────────
+if (values.version === true) {
+    process.stdout.write(`testrail-cli v${VERSION}\n`);
+    process.exit(0);
+}
+if (values.help === true || positionals.length === 0) {
+    process.stdout.write(`${HELP}\n`);
+    process.exit(0);
+}
+const [resource, action, idArg] = positionals;
+if (resource === undefined || resource === '' || action === undefined || action === '') {
+    process.stderr.write('Usage: testrail <resource> <action> [id] [options]\nRun with --help for details.\n');
+    process.exit(1);
+}
+// ── Auth Resolution ───────────────────────────────────────────────────────────
+const baseUrl = values['base-url'] ?? process.env['TESTRAIL_BASE_URL'];
+const email = values['email'] ?? process.env['TESTRAIL_EMAIL'];
+const apiKey = values['api-key'] ?? process.env['TESTRAIL_API_KEY'];
+if (baseUrl === undefined ||
+    baseUrl === '' ||
+    email === undefined ||
+    email === '' ||
+    apiKey === undefined ||
+    apiKey === '') {
+    err('Missing auth. Set TESTRAIL_BASE_URL, TESTRAIL_EMAIL, TESTRAIL_API_KEY or use --base-url, --email, --api-key flags.');
+    process.exit(1);
+}
+const config = { baseUrl, email, apiKey };
+const client = new TestRailClient(config);
+// ── Numeric Helpers ───────────────────────────────────────────────────────────
+function parseId(raw, name) {
+    const n = Number(raw);
+    if (raw === undefined || raw === '' || !Number.isInteger(n) || n <= 0) {
+        err(`${name} must be a positive integer (got: ${raw ?? '(none)'})`);
+        process.exit(1);
+    }
+    return n;
+}
+function optInt(raw) {
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+const suiteId = optInt(values['suite-id']);
+const limit = optInt(values.limit);
+const offset = optInt(values.offset);
+// ── Command Dispatch ──────────────────────────────────────────────────────────
+async function run(res, act) {
+    switch (res) {
+        case 'project': {
+            if (act === 'get') {
+                const id = parseId(idArg, 'project id');
+                out(await client.getProject(id));
+            }
+            else if (act === 'list') {
+                out(await client.getProjects(limit, offset));
+            }
+            else {
+                err(`Unknown action '${act}' for project. Use: get, list`);
+                process.exit(1);
+            }
+            break;
+        }
+        case 'suite': {
+            if (act === 'get') {
+                const id = parseId(idArg, 'suite id');
+                out(await client.getSuite(id));
+            }
+            else if (act === 'list') {
+                const pid = parseId(values['project-id'], '--project-id');
+                out(await client.getSuites(pid));
+            }
+            else {
+                err(`Unknown action '${act}' for suite. Use: get, list`);
+                process.exit(1);
+            }
+            break;
+        }
+        case 'case': {
+            if (act === 'get') {
+                const id = parseId(idArg, 'case id');
+                out(await client.getCase(id));
+            }
+            else if (act === 'list') {
+                const pid = parseId(values['project-id'], '--project-id');
+                out(await client.getCases(pid, suiteId !== undefined ? { suiteId } : undefined));
+            }
+            else {
+                err(`Unknown action '${act}' for case. Use: get, list`);
+                process.exit(1);
+            }
+            break;
+        }
+        case 'run': {
+            if (act === 'get') {
+                const id = parseId(idArg, 'run id');
+                out(await client.getRun(id));
+            }
+            else if (act === 'list') {
+                const pid = parseId(values['project-id'], '--project-id');
+                out(await client.getRuns(pid, {
+                    ...(limit !== undefined && { limit }),
+                    ...(offset !== undefined && { offset }),
+                }));
+            }
+            else {
+                err(`Unknown action '${act}' for run. Use: get, list`);
+                process.exit(1);
+            }
+            break;
+        }
+        case 'result': {
+            if (act === 'list') {
+                const rid = parseId(values['run-id'], '--run-id');
+                const resultOpts = { ...(limit !== undefined && { limit }), ...(offset !== undefined && { offset }) };
+                out(await client.getResultsForRun(rid, resultOpts));
+            }
+            else {
+                err(`Unknown action '${act}' for result. Use: list`);
+                process.exit(1);
+            }
+            break;
+        }
+        case 'milestone': {
+            if (act === 'get') {
+                const id = parseId(idArg, 'milestone id');
+                out(await client.getMilestone(id));
+            }
+            else if (act === 'list') {
+                const pid = parseId(values['project-id'], '--project-id');
+                const msOpts = { ...(limit !== undefined && { limit }), ...(offset !== undefined && { offset }) };
+                out(await client.getMilestones(pid, msOpts));
+            }
+            else {
+                err(`Unknown action '${act}' for milestone. Use: get, list`);
+                process.exit(1);
+            }
+            break;
+        }
+        case 'user': {
+            if (act === 'get') {
+                const id = parseId(idArg, 'user id');
+                out(await client.getUser(id));
+            }
+            else if (act === 'list') {
+                out(await client.getUsers(limit, offset));
+            }
+            else {
+                err(`Unknown action '${act}' for user. Use: get, list`);
+                process.exit(1);
+            }
+            break;
+        }
+        default: {
+            err(`Unknown resource '${res}'. Use: project, suite, case, run, result, milestone, user`);
+            process.exit(1);
+        }
+    }
+}
+run(resource, action)
+    .then(() => {
+    client.destroy();
+    process.exit(0);
+})
+    .catch((e) => {
+    err(e instanceof Error ? e.message : String(e));
+    client.destroy();
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/client-core.d.ts

@@ -0,0 +1,103 @@
+import type { TestRailConfig } from './types.js';
+/**
+ * HTTP pipeline, caching, rate limiting, retry logic, and lifecycle management.
+ * Extended by {@link TestRailClient} which adds all API endpoint methods.
+ */
+export declare class TestRailClientCore {
+    private readonly baseUrl;
+    private auth;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly enableCache;
+    private readonly cacheTtl;
+    private readonly cacheCleanupInterval;
+    private readonly maxCacheSize;
+    private readonly cache;
+    private cacheCleanupTimer;
+    private readonly rateLimiter;
+    private isDestroyed;
+    constructor(config: TestRailConfig);
+    private validateConfig;
+    private getRetryDelay;
+    /**
+     * Parses the Retry-After header value to milliseconds
+     *
+     * @param response - The HTTP response containing the Retry-After header
+     * @returns The delay in milliseconds, or null if header is absent or invalid
+     */
+    private parseRetryAfterMs;
+    /** Sliding window rate limiter. @throws {TestRailApiError} when limit exceeded */
+    private checkRateLimit;
+    /**
+     * Validates that an ID is a positive integer.
+     * @throws {TestRailValidationError} When ID is invalid
+     */
+    protected validateId(id: number, name: string): void;
+    /**
+     * Validates that a string entry ID is non-empty.
+     * @throws {TestRailValidationError} When entryId is not a non-empty string
+     */
+    protected validateEntryId(entryId: string): void;
+    /**
+     * Validates optional pagination parameters.
+     * @throws {TestRailValidationError} When limit is not a positive integer or offset is not a non-negative integer
+     */
+    protected validatePaginationParams(limit?: number, offset?: number): void;
+    /**
+     * Builds a TestRail endpoint URL with optional query parameters.
+     * Appends params using `&key=value` (TestRail URL quirk — uses `&`, not `?`).
+     * Keys and values are automatically percent-encoded via `encodeURIComponent`.
+     * Do NOT pre-encode values before passing them; doing so will cause double-encoding.
+     */
+    protected buildEndpoint(base: string, params?: Record<string, string | number | undefined>): string;
+    private getCachedData;
+    private setCachedData;
+    /**
+     * Clears the entire cache.
+     */
+    clearCache(): void;
+    private startCacheCleanup;
+    private stopCacheCleanup;
+    private cleanupExpiredCache;
+    /**
+     * Releases all resources held by this client instance.
+     * Stops the cache cleanup timer, clears the cache, and removes this instance
+     * from the active-clients registry. Safe to call multiple times (idempotent).
+     * Also called automatically on `exit`, `SIGINT`, and `SIGTERM`.
+     */
+    destroy(): void;
+    /**
+     * Makes an HTTP request to the TestRail API with caching, rate limiting, and retry logic.
+     *
+     * @param method - HTTP method (GET, POST)
+     * @param endpoint - API endpoint path (without base URL prefix)
+     * @param data - Optional request body
+     * @param retryCount - Current retry attempt (internal — do not pass)
+     * @param skipCache - Skip cache lookup and storage for this request
+     * @throws {TestRailApiError} When the API request fails or network error occurs
+     * @throws {Error} When called after `destroy()`
+     */
+    protected request<T>(method: string, endpoint: string, data?: unknown, retryCount?: number, skipCache?: boolean): Promise<T>;
+    /**
+     * Makes a multipart/form-data POST request to the TestRail API.
+     * Used exclusively for file attachment uploads. Applies rate limiting
+     * and throws on failure, but does NOT retry (uploads are not idempotent).
+     *
+     * @param endpoint - API endpoint path (without base URL prefix)
+     * @param file - File content as Blob, Uint8Array, or File
+     * @param filename - Filename to send in the multipart disposition
+     * @throws {TestRailApiError} When the API request fails or network error occurs
+     * @throws {Error} When called after `destroy()`
+     */
+    protected requestMultipart<T>(endpoint: string, file: globalThis.Blob | Uint8Array | globalThis.File, filename: string): Promise<T>;
+    /**
+     * Makes a GET request to the TestRail API and returns the raw binary response.
+     * Used for downloading attachment contents.
+     *
+     * @param endpoint - API endpoint path (without base URL prefix)
+     * @throws {TestRailApiError} When the API request fails or network error occurs
+     * @throws {Error} When called after `destroy()`
+     */
+    protected requestBinary(endpoint: string, retryCount?: number): Promise<ArrayBuffer>;
+}
+//# sourceMappingURL=client-core.d.ts.map