@dichovsky/testrail-api-client 1.0.0 → 2.1.0

package/src/schemas.ts

@@ -0,0 +1,551 @@
+import { z } from 'zod';
+
+const zObject = <T extends z.ZodRawShape>(shape: T) => 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(),
+});
+
+export type TestRailConfig = z.infer<typeof TestRailConfigSchema>;
+
+// ── 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 type User = z.infer<typeof UserSchema>;
+
+export const RoleSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    is_default: z.boolean(),
+});
+
+export type Role = z.infer<typeof RoleSchema>;
+
+export const GroupSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    user_ids: z.array(z.number()).optional(),
+});
+
+export type Group = z.infer<typeof GroupSchema>;
+
+// ── 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 type Project = z.infer<typeof ProjectSchema>;
+
+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(),
+});
+
+export type Suite = z.infer<typeof SuiteSchema>;
+
+// ── 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 type Case = z.infer<typeof CaseSchema>;
+
+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(),
+});
+
+export type Section = z.infer<typeof SectionSchema>;
+
+// ── 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(),
+});
+
+export type Run = z.infer<typeof RunSchema>;
+
+// ── 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 type PlanEntry = z.infer<typeof PlanEntrySchema>;
+
+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(),
+});
+
+export type Plan = z.infer<typeof PlanSchema>;
+
+// ── 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 type Test = z.infer<typeof TestSchema>;
+
+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(),
+});
+
+export type Result = z.infer<typeof ResultSchema>;
+
+// ── 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(),
+});
+
+export type Milestone = z.infer<typeof MilestoneSchema>;
+
+// ── 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 type Status = z.infer<typeof StatusSchema>;
+
+export const PrioritySchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    short_name: z.string(),
+    is_default: z.boolean(),
+    priority: z.number(),
+});
+
+export type Priority = z.infer<typeof PrioritySchema>;
+
+// ── 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 type CaseFieldConfig = z.infer<typeof CaseFieldConfigSchema>;
+
+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 type CaseField = z.infer<typeof CaseFieldSchema>;
+
+export const ResultFieldConfigSchema = zObject({
+    context: FieldConfigContextSchema,
+    options: FieldConfigOptionsSchema,
+});
+
+export type ResultFieldConfig = z.infer<typeof ResultFieldConfigSchema>;
+
+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(),
+});
+
+export type ResultField = z.infer<typeof ResultFieldSchema>;
+
+// ── Case Type & Template Schemas ──────────────────────────────────────────────
+
+export const CaseTypeSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    is_default: z.boolean(),
+});
+
+export type CaseType = z.infer<typeof CaseTypeSchema>;
+
+export const TemplateSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    is_default: z.boolean(),
+});
+
+export type Template = z.infer<typeof TemplateSchema>;
+
+// ── Configuration Schemas ─────────────────────────────────────────────────────
+
+export const ConfigurationSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    group_id: z.number(),
+});
+
+export type Configuration = z.infer<typeof ConfigurationSchema>;
+
+export const ConfigurationGroupSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    project_id: z.number(),
+    configs: z.array(ConfigurationSchema),
+});
+
+export type ConfigurationGroup = z.infer<typeof ConfigurationGroupSchema>;
+
+// ── 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(),
+});
+
+export type Attachment = z.infer<typeof AttachmentSchema>;
+
+// ── 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(),
+});
+
+export type SharedStep = z.infer<typeof SharedStepSchema>;
+
+// ── Variable & Dataset Schemas ────────────────────────────────────────────────
+
+export const VariableSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+});
+
+export type Variable = z.infer<typeof VariableSchema>;
+
+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(),
+});
+
+export type Dataset = z.infer<typeof DatasetSchema>;
+
+// ── Report Schemas ────────────────────────────────────────────────────────────
+
+export const ReportSchema = zObject({
+    id: z.number(),
+    name: z.string(),
+    description: z.string().optional(),
+    is_shared: z.boolean().optional(),
+});
+
+export type Report = z.infer<typeof ReportSchema>;
+
+export const ReportResultSchema = zObject({
+    report_url: z.string(),
+    user_report_url: z.string().optional(),
+});
+
+export type ReportResult = z.infer<typeof ReportResultSchema>;
+
+// ── 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 type AddCasePayload = z.infer<typeof AddCasePayloadSchema>;
+
+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 type UpdateCasePayload = z.infer<typeof UpdateCasePayloadSchema>;
+
+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 type AddRunPayload = z.infer<typeof AddRunPayloadSchema>;
+
+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 type UpdateRunPayload = z.infer<typeof UpdateRunPayloadSchema>;
+
+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(),
+});
+
+export type AddResultPayload = z.infer<typeof AddResultPayloadSchema>;
+
+// 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 type AddResultForCasePayload = z.infer<typeof AddResultForCasePayloadSchema>;
+
+export const AddResultsForCasesPayloadSchema = zObject({
+    results: z.array(AddResultForCasePayloadSchema),
+});
+
+export type AddResultsForCasesPayload = z.infer<typeof AddResultsForCasesPayloadSchema>;

package/src/types.ts

@@ -1,3 +1,9 @@
+// AddRunPayload is the source-of-truth payload type derived from
+// `AddRunPayloadSchema` in `./schemas.ts`. It's re-imported here because
+// `AddPlanEntryPayload` / `UpdatePlanEntryPayload` (which remain handwritten
+// in this file as part of v2.1 scope) contain `runs?: AddRunPayload[]`.
+import type { AddRunPayload } from './schemas.js';
+
 /**
  * TestRail API client configuration options
  */
@@ -253,27 +259,8 @@ export interface Priority {
     priority: number; // weight/level
 }
 
-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>;
-}
+// AddCasePayload and UpdateCasePayload now live in `./schemas.ts` as Zod
+// schemas (source of truth for runtime validation + inferred TS types).
 
 /**
  * Filter options for `getCases()`.
@@ -342,45 +329,9 @@ export interface UpdatePlanEntryPayload {
     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; // e.g. "5m 30s"
-    defects?: string;
-    assignedto_id?: number;
-    custom_fields?: Record<string, unknown>;
-}
-
-export interface AddResultsForCasesPayload {
-    results: AddResultForCasePayload[];
-}
-
-export interface AddResultForCasePayload extends AddResultPayload {
-    case_id: number;
-}
+// AddRunPayload, UpdateRunPayload, AddResultPayload, AddResultsForCasesPayload,
+// and AddResultForCasePayload now live in `./schemas.ts` as Zod schemas
+// (source of truth for runtime validation + inferred TS types).
 
 export interface AddSectionPayload {
     name: string;

package/src/utils.ts

@@ -13,3 +13,8 @@ export function base64Encode(str: string): string {
 export function sleep(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+/** Serializes numeric ID filters for TestRail list endpoints. */
+export function serializeIdList(ids?: number[]): string | undefined {
+    return ids !== undefined && ids.length > 0 ? ids.join(',') : undefined;
+}