@dichovsky/testrail-api-client 1.0.0 → 2.1.0

package/dist/schemas.js

@@ -0,0 +1,419 @@
+import { z } from 'zod';
+const zObject = (shape) => z.object(shape).passthrough();
+/**
+ * Core schemas for common TestRail API structures.
+ * These are used to validate API responses and provide static type inference via `z.infer`.
+ */
+// ── Common & Foundational Schemas ─────────────────────────────────────────────
+export const PaginationSchema = zObject({
+    limit: z.number().optional(),
+    offset: z.number().optional(),
+});
+export const TestRailConfigSchema = zObject({
+    baseUrl: z.string().url(),
+    email: z.string().email(),
+    apiKey: z.string().min(1),
+    timeout: z.number().optional(),
+    maxRetries: z.number().int().nonnegative().optional(),
+    enableCache: z.boolean().optional(),
+    cacheTtl: z.number().int().positive().optional(),
+    cacheCleanupInterval: z.number().int().positive().optional(),
+    maxCacheSize: z.number().int().positive().optional(),
+    rateLimiter: zObject({
+        maxRequests: z.number().int().positive(),
+        windowMs: z.number().int().positive(),
+    }).optional(),
+    allowInsecure: z.boolean().optional(),
+    allowPrivateHosts: z.boolean().optional(),
+});
+// ── Identity & User Schemas ───────────────────────────────────────────────────
+export const UserSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    email: z.string().email(),
+    is_active: z.boolean(),
+    role_id: z.number().optional(),
+    role: z.string().optional(),
+});
+export const RoleSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    is_default: z.boolean(),
+});
+export const GroupSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    user_ids: z.array(z.number()).optional(),
+});
+// ── Project & Suite Schemas ────────────────────────────────────────────────────
+export const ProjectSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    announcement: z.string().optional(),
+    show_announcement: z.boolean().optional(),
+    is_completed: z.boolean().optional(),
+    completed_on: z.number().optional(),
+    suite_mode: z.number(),
+    url: z.string(),
+});
+export const SuiteSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    description: z.string().optional(),
+    project_id: z.number(),
+    is_master: z.boolean().optional(),
+    is_baseline: z.boolean().optional(),
+    is_completed: z.boolean().optional(),
+    completed_on: z.number().optional(),
+    url: z.string(),
+});
+// ── Case & Section Schemas ─────────────────────────────────────────────────────
+export const CaseSchema = zObject({
+    id: z.number(),
+    title: z.string(),
+    section_id: z.number(),
+    template_id: z.number().optional(),
+    type_id: z.number().optional(),
+    priority_id: z.number().optional(),
+    milestone_id: z.number().optional(),
+    refs: z.string().optional(),
+    created_by: z.number(),
+    created_on: z.number(),
+    updated_by: z.number(),
+    updated_on: z.number(),
+    estimate: z.string().optional(),
+    estimate_forecast: z.string().optional(),
+    suite_id: z.number(),
+    display_order: z.number().optional(),
+    is_deleted: z.number().optional(),
+    custom_fields: z.record(z.string(), z.unknown()).optional(),
+});
+export const SectionSchema = zObject({
+    id: z.number(),
+    suite_id: z.number(),
+    name: z.string(),
+    description: z.string().optional(),
+    parent_id: z.number().optional(),
+    display_order: z.number(),
+    depth: z.number(),
+});
+// ── Run Schema (forward declaration needed for PlanEntry) ─────────────────────
+export const RunSchema = zObject({
+    id: z.number(),
+    suite_id: z.number(),
+    name: z.string(),
+    description: z.string().optional(),
+    milestone_id: z.number().optional(),
+    assignedto_id: z.number().optional(),
+    include_all: z.boolean(),
+    is_completed: z.boolean(),
+    completed_on: z.number().optional(),
+    config: z.string().optional(),
+    config_ids: z.array(z.number()).optional(),
+    passed_count: z.number(),
+    blocked_count: z.number(),
+    untested_count: z.number(),
+    retest_count: z.number(),
+    failed_count: z.number(),
+    custom_status1_count: z.number().optional(),
+    custom_status2_count: z.number().optional(),
+    custom_status3_count: z.number().optional(),
+    custom_status4_count: z.number().optional(),
+    custom_status5_count: z.number().optional(),
+    custom_status6_count: z.number().optional(),
+    custom_status7_count: z.number().optional(),
+    project_id: z.number(),
+    plan_id: z.number().optional(),
+    created_on: z.number(),
+    created_by: z.number(),
+    refs: z.string().optional(),
+    url: z.string(),
+});
+// ── Plan Entry & Plan Schemas ─────────────────────────────────────────────────
+export const PlanEntrySchema = zObject({
+    id: z.string(),
+    suite_id: z.number(),
+    name: z.string(),
+    description: z.string().optional(),
+    assignedto_id: z.number().optional(),
+    include_all: z.boolean(),
+    case_ids: z.array(z.number()).optional(),
+    config_ids: z.array(z.number()).optional(),
+    runs: z.array(RunSchema),
+});
+export const PlanSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    description: z.string().optional(),
+    milestone_id: z.number().optional(),
+    assignedto_id: z.number().optional(),
+    is_completed: z.boolean(),
+    completed_on: z.number().optional(),
+    passed_count: z.number(),
+    blocked_count: z.number(),
+    untested_count: z.number(),
+    retest_count: z.number(),
+    failed_count: z.number(),
+    custom_status1_count: z.number().optional(),
+    custom_status2_count: z.number().optional(),
+    custom_status3_count: z.number().optional(),
+    custom_status4_count: z.number().optional(),
+    custom_status5_count: z.number().optional(),
+    custom_status6_count: z.number().optional(),
+    custom_status7_count: z.number().optional(),
+    project_id: z.number(),
+    created_on: z.number(),
+    created_by: z.number(),
+    url: z.string(),
+    entries: z.array(PlanEntrySchema).optional(),
+});
+// ── Test & Result Schemas ─────────────────────────────────────────────────────
+export const TestSchema = zObject({
+    id: z.number(),
+    case_id: z.number(),
+    status_id: z.number(),
+    assignedto_id: z.number().optional(),
+    run_id: z.number(),
+    title: z.string(),
+    template_id: z.number().optional(),
+    type_id: z.number().optional(),
+    priority_id: z.number().optional(),
+    estimate: z.string().optional(),
+    estimate_forecast: z.string().optional(),
+    refs: z.string().optional(),
+    milestone_id: z.number().optional(),
+    custom_fields: z.record(z.string(), z.unknown()).optional(),
+});
+export const ResultSchema = zObject({
+    id: z.number().optional(),
+    test_id: z.number().optional(),
+    status_id: z.number(),
+    comment: z.string().optional(),
+    version: z.string().optional(),
+    elapsed: z.string().optional(),
+    defects: z.string().optional(),
+    assignedto_id: z.number().optional(),
+    created_by: z.number().optional(),
+    created_on: z.number().optional(),
+    custom_fields: z.record(z.string(), z.unknown()).optional(),
+});
+// ── Milestone Schema ──────────────────────────────────────────────────────────
+export const MilestoneSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    description: z.string().optional(),
+    start_on: z.number().optional(),
+    started_on: z.number().optional(),
+    is_completed: z.boolean(),
+    completed_on: z.number().optional(),
+    due_on: z.number().optional(),
+    project_id: z.number(),
+    parent_id: z.number().optional(),
+    refs: z.string().optional(),
+    url: z.string(),
+    // Sub-milestones are typed as unknown[] to avoid a recursive schema definition.
+    milestones: z.array(z.unknown()).optional(),
+});
+// ── Status & Priority Schemas ──────────────────────────────────────────────────
+export const StatusSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    label: z.string(),
+    color_dark: z.number(),
+    color_medium: z.number(),
+    color_bright: z.number(),
+    is_system: z.boolean(),
+    is_untested: z.boolean(),
+    is_final: z.boolean(),
+});
+export const PrioritySchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    short_name: z.string(),
+    is_default: z.boolean(),
+    priority: z.number(),
+});
+// ── Field Config Schemas ──────────────────────────────────────────────────────
+const FieldConfigOptionsSchema = zObject({
+    is_required: z.boolean(),
+    default_value: z.string(),
+    items: z.string().optional(),
+    format: z.string().optional(),
+    rows: z.string().optional(),
+});
+const FieldConfigContextSchema = zObject({
+    is_global: z.boolean(),
+    project_ids: z.array(z.number()),
+});
+export const CaseFieldConfigSchema = zObject({
+    context: FieldConfigContextSchema,
+    options: FieldConfigOptionsSchema,
+});
+export const CaseFieldSchema = zObject({
+    id: z.number(),
+    system_name: z.string(),
+    label: z.string(),
+    name: z.string(),
+    type_id: z.number(),
+    display_order: z.number(),
+    configs: z.array(CaseFieldConfigSchema),
+    is_active: z.boolean(),
+    include_all: z.boolean(),
+    template_ids: z.array(z.number()),
+    description: z.string().optional(),
+});
+export const ResultFieldConfigSchema = zObject({
+    context: FieldConfigContextSchema,
+    options: FieldConfigOptionsSchema,
+});
+export const ResultFieldSchema = zObject({
+    id: z.number(),
+    system_name: z.string(),
+    label: z.string(),
+    name: z.string(),
+    type_id: z.number(),
+    display_order: z.number(),
+    configs: z.array(ResultFieldConfigSchema),
+    is_active: z.boolean(),
+    include_all: z.boolean(),
+    template_ids: z.array(z.number()),
+    description: z.string().optional(),
+});
+// ── Case Type & Template Schemas ──────────────────────────────────────────────
+export const CaseTypeSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    is_default: z.boolean(),
+});
+export const TemplateSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    is_default: z.boolean(),
+});
+// ── Configuration Schemas ─────────────────────────────────────────────────────
+export const ConfigurationSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    group_id: z.number(),
+});
+export const ConfigurationGroupSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    project_id: z.number(),
+    configs: z.array(ConfigurationSchema),
+});
+// ── Attachment Schema ─────────────────────────────────────────────────────────
+export const AttachmentSchema = zObject({
+    attachment_id: z.number(),
+    name: z.string(),
+    filename: z.string().optional(),
+    size: z.number().optional(),
+    created_on: z.number().optional(),
+    created_by: z.number().optional(),
+    entity_id: z.number().optional(),
+});
+// ── Shared Steps Schema ───────────────────────────────────────────────────────
+export const SharedStepSchema = zObject({
+    id: z.number(),
+    title: z.string(),
+    project_id: z.number().optional(),
+    case_ids: z.array(z.number()).optional(),
+    created_on: z.number().optional(),
+    created_by: z.number().optional(),
+    updated_on: z.number().optional(),
+    updated_by: z.number().optional(),
+    custom_steps_separated: z.array(z.record(z.string(), z.unknown())).optional(),
+});
+// ── Variable & Dataset Schemas ────────────────────────────────────────────────
+export const VariableSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+});
+export const DatasetSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    project_id: z.number().optional(),
+    created_on: z.number().optional(),
+    created_by: z.number().optional(),
+});
+// ── Report Schemas ────────────────────────────────────────────────────────────
+export const ReportSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    description: z.string().optional(),
+    is_shared: z.boolean().optional(),
+});
+export const ReportResultSchema = zObject({
+    report_url: z.string(),
+    user_report_url: z.string().optional(),
+});
+// ── Write Payload Schemas ─────────────────────────────────────────────────────
+// Source-of-truth schemas for POST bodies sent by the TestRail client. Each is
+// `.passthrough()` via `zObject`, so TestRail's user-configured `custom_*`
+// fields (or any other forward-compatible extension) pass through unchanged.
+// TypeScript payload types are derived via `z.infer` and exported alongside
+// each schema; no separate handwritten interface lives in `src/types.ts`.
+export const AddCasePayloadSchema = zObject({
+    title: z.string(),
+    template_id: z.number().optional(),
+    type_id: z.number().optional(),
+    priority_id: z.number().optional(),
+    estimate: z.string().optional(),
+    milestone_id: z.number().optional(),
+    refs: z.string().optional(),
+    custom_fields: z.record(z.string(), z.unknown()).optional(),
+});
+export const UpdateCasePayloadSchema = zObject({
+    title: z.string().optional(),
+    template_id: z.number().optional(),
+    type_id: z.number().optional(),
+    priority_id: z.number().optional(),
+    estimate: z.string().optional(),
+    milestone_id: z.number().optional(),
+    refs: z.string().optional(),
+    custom_fields: z.record(z.string(), z.unknown()).optional(),
+});
+export const AddRunPayloadSchema = zObject({
+    name: z.string(),
+    suite_id: z.number().optional(),
+    description: z.string().optional(),
+    milestone_id: z.number().optional(),
+    assignedto_id: z.number().optional(),
+    include_all: z.boolean().optional(),
+    case_ids: z.array(z.number()).optional(),
+    refs: z.string().optional(),
+});
+export const UpdateRunPayloadSchema = zObject({
+    name: z.string().optional(),
+    description: z.string().optional(),
+    milestone_id: z.number().optional(),
+    assignedto_id: z.number().optional(),
+    include_all: z.boolean().optional(),
+    case_ids: z.array(z.number()).optional(),
+    refs: z.string().optional(),
+});
+export const AddResultPayloadSchema = zObject({
+    status_id: z.number(),
+    comment: z.string().optional(),
+    version: z.string().optional(),
+    elapsed: z.string().optional(),
+    defects: z.string().optional(),
+    assignedto_id: z.number().optional(),
+    custom_fields: z.record(z.string(), z.unknown()).optional(),
+});
+// Inlined rather than `.extend(AddResultPayloadSchema)` so the passthrough()
+// behavior is unambiguous and the inferred type stays a plain object literal.
+export const AddResultForCasePayloadSchema = zObject({
+    case_id: z.number(),
+    status_id: z.number(),
+    comment: z.string().optional(),
+    version: z.string().optional(),
+    elapsed: z.string().optional(),
+    defects: z.string().optional(),
+    assignedto_id: z.number().optional(),
+    custom_fields: z.record(z.string(), z.unknown()).optional(),
+});
+export const AddResultsForCasesPayloadSchema = zObject({
+    results: z.array(AddResultForCasePayloadSchema),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { AddRunPayload } from './schemas.js';
 /**
  * TestRail API client configuration options
  */
@@ -237,26 +238,6 @@ export interface Priority {
     is_default: boolean;
     priority: number;
 }
-export interface AddCasePayload {
-    title: string;
-    template_id?: number;
-    type_id?: number;
-    priority_id?: number;
-    estimate?: string;
-    milestone_id?: number;
-    refs?: string;
-    custom_fields?: Record<string, unknown>;
-}
-export interface UpdateCasePayload {
-    title?: string;
-    template_id?: number;
-    type_id?: number;
-    priority_id?: number;
-    estimate?: string;
-    milestone_id?: number;
-    refs?: string;
-    custom_fields?: Record<string, unknown>;
-}
 /**
  * Filter options for `getCases()`.
  * All date filters accept Unix timestamps (seconds since epoch).
@@ -319,41 +300,6 @@ export interface UpdatePlanEntryPayload {
     config_ids?: number[];
     runs?: AddRunPayload[];
 }
-export interface AddRunPayload {
-    suite_id?: number;
-    name: string;
-    description?: string;
-    milestone_id?: number;
-    assignedto_id?: number;
-    include_all?: boolean;
-    case_ids?: number[];
-    refs?: string;
-}
-export interface UpdateRunPayload {
-    name?: string;
-    description?: string;
-    milestone_id?: number;
-    assignedto_id?: number;
-    include_all?: boolean;
-    case_ids?: number[];
-    refs?: string;
-}
-export interface AddResultPayload {
-    /** e.g., 1=Passed */
-    status_id: number;
-    comment?: string;
-    version?: string;
-    elapsed?: string;
-    defects?: string;
-    assignedto_id?: number;
-    custom_fields?: Record<string, unknown>;
-}
-export interface AddResultsForCasesPayload {
-    results: AddResultForCasePayload[];
-}
-export interface AddResultForCasePayload extends AddResultPayload {
-    case_id: number;
-}
 export interface AddSectionPayload {
     name: string;
     suite_id?: number;

package/dist/utils.d.ts

@@ -2,4 +2,6 @@
 export declare function base64Encode(str: string): string;
 /** Resolves after `ms` milliseconds. */
 export declare function sleep(ms: number): Promise<void>;
+/** Serializes numeric ID filters for TestRail list endpoints. */
+export declare function serializeIdList(ids?: number[]): string | undefined;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -10,4 +10,8 @@ export function base64Encode(str) {
 export function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/** Serializes numeric ID filters for TestRail list endpoints. */
+export function serializeIdList(ids) {
+    return ids !== undefined && ids.length > 0 ? ids.join(',') : undefined;
+}
 //# sourceMappingURL=utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dichovsky/testrail-api-client",
-    "version": "1.0.0",
+    "version": "2.1.0",
     "description": "TypeScript API client for TestRail",
     "keywords": [
         "testrail",
@@ -18,9 +18,6 @@
         "url": "git+https://github.com/dichovsky/testrail-api-client.git"
     },
     "license": "MIT",
-    "publishConfig": {
-        "access": "public"
-    },
     "author": "Igor Magdich",
     "type": "module",
     "exports": {
@@ -42,35 +39,46 @@
     "files": [
         "dist",
         "src",
+        "skill",
         "README.md",
         "LICENSE"
     ],
     "scripts": {
-        "build": "rm -rf dist && tsc",
+        "build": "rm -rf dist && tsc -p tsconfig.prod.json",
         "clean:maps": "find dist -name '*.map' -delete",
         "codemap": "node scripts/generate-codemap.js",
+        "codemap:check": "node scripts/generate-codemap.js --check",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "lint": "eslint .",
-        "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run build && npm run clean:maps",
+        "prepublishOnly": "npm run typecheck && npm run lint && npm test && npm run skill && npm run skill:check && npm run clean:maps",
+        "pretest": "npm run typecheck && npm run lint && npm run format:check && npm run codemap:check",
+        "skill": "npm run build && node scripts/generate-skill.js",
+        "skill:check": "git diff --exit-code skill/SKILL.md",
         "test": "vitest run",
         "test:coverage": "vitest run --coverage",
         "test:fast": "vitest run --reporter=dot --no-coverage",
         "test:watch": "vitest",
-        "typecheck": "tsc --noEmit"
+        "typecheck": "tsc"
+    },
+    "dependencies": {
+        "zod": "^4.4.3"
     },
     "devDependencies": {
         "@eslint/js": "^10.0.1",
-        "@types/node": "^25.6.0",
-        "@typescript-eslint/eslint-plugin": "^8.58.1",
-        "@typescript-eslint/parser": "^8.58.1",
-        "@vitest/coverage-v8": "^4.1.4",
-        "eslint": "^10.2.0",
-        "prettier": "~3.8.2",
-        "typescript": "~6.0.2",
-        "vitest": "^4.1.4"
+        "@types/node": "^25.7.0",
+        "@typescript-eslint/eslint-plugin": "^8.59.3",
+        "@typescript-eslint/parser": "^8.59.3",
+        "@vitest/coverage-v8": "^4.1.6",
+        "eslint": "^10.3.0",
+        "prettier": "~3.8.3",
+        "typescript": "~6.0.3",
+        "vitest": "^4.1.6"
     },
     "engines": {
         "node": "^20.19.0 || ^22.13.0 || >=24"
+    },
+    "publishConfig": {
+        "access": "public"
     }
 }