@tahanabavi/typefetch 1.5.6 → 1.6.0

package/dist/index.d.mts

@@ -37,6 +37,56 @@ type EncryptionConfig<TReq, TRes> = {
  */
 type RequestSchema = z.ZodTypeAny;
 type ResponseSchema = z.ZodTypeAny;
+/**
+ * EndpointTestContext
+ * ===================
+ * Shared runtime state used by the API test runner.
+ * It allows one endpoint test to store values that later tests can reuse.
+ */
+type EndpointTestContext = {
+    data: Record<string, unknown>;
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    has(key: string): boolean;
+};
+type EndpointTestInputFactory<TReq> = (ctx: EndpointTestContext) => TReq | Promise<TReq>;
+type EndpointTestAssertion<TReq, TRes> = (result: {
+    input: TReq;
+    response: TRes;
+    ctx: EndpointTestContext;
+}) => void | Promise<void>;
+type EndpointTestCase<TReq, TRes> = {
+    /** Human-readable name shown in the generated report. */
+    name?: string;
+    /** Static input or a factory that can read/write shared test context. */
+    input?: TReq | EndpointTestInputFactory<TReq>;
+    /** Skip this specific case. A string is used as the skip reason. */
+    skip?: boolean | string;
+    /** Expected HTTP status. Defaults to any successful client response. */
+    expectStatus?: number | number[];
+    /** Optional user-defined assertion after a successful response. */
+    expect?: EndpointTestAssertion<TReq, TRes>;
+    /** Per-case timeout in milliseconds. */
+    timeout?: number;
+    /** Tags used by the runner for include/exclude filtering. */
+    tags?: string[];
+};
+type EndpointTestConfig<TReq, TRes> = {
+    /** Disable all generated/manual tests for this endpoint. */
+    enabled?: boolean;
+    /** Tags used by the runner for include/exclude filtering. */
+    tags?: string[];
+    /** Mark endpoints such as DELETE/reset/payment as unsafe for default runs. */
+    destructive?: boolean;
+    /** Default input used when cases are not provided. */
+    input?: TReq | EndpointTestInputFactory<TReq>;
+    /** One or more test cases for this endpoint. */
+    cases?: Array<EndpointTestCase<TReq, TRes>>;
+    /** Runs before the endpoint cases. */
+    setup?: (ctx: EndpointTestContext) => void | Promise<void>;
+    /** Runs after the endpoint cases. */
+    teardown?: (ctx: EndpointTestContext) => void | Promise<void>;
+};
 /**
  * EndpointDef
  * ============
@@ -81,6 +131,10 @@ type EndpointDef<TReq extends RequestSchema, TRes extends ResponseSchema> = {
      * - `"form-data"`: multipart form
      */
     bodyType?: "json" | "form-data";
+    /**
+     * Optional contract-driven tests used by the TypeFetch test runner.
+     */
+    test?: EndpointTestConfig<z.infer<TReq>, z.infer<TRes>>;
 };
 /**
  * Contracts
@@ -406,4 +460,167 @@ declare const makeRequestSchema: <TPath extends z.ZodRawShape = {}, TQuery exten
     headers: THeaders;
 }, z.core.$strip>;
 
-export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type DeepEncryptionMap, type EncryptionConfig, type EncryptionMethod, type EncryptionOptions, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Method, type Middleware, type MiddlewareContext, type MiddlewareNext, type RequestOptions, type RequestParts, type RequestSchema, type ResponseSchema, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, encryptionMiddleware, loggingMiddleware, makeRequestSchema, processDeep, retryMiddleware };
+declare class TypeFetchTestContext implements EndpointTestContext {
+    data: Record<string, unknown>;
+    constructor(initialData?: Record<string, unknown>);
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    has(key: string): boolean;
+}
+
+type ApiTestMode = "schema" | "mock" | "live" | "full";
+type ApiTestStatus = "passed" | "failed" | "skipped";
+type ApiTestReportFormat = "json" | "markdown" | "html";
+type AutoInputValue = unknown | ((path: string) => unknown);
+type AutoInputOptions = {
+    /** Maximum recursive generation depth for nested schemas. */
+    maxDepth?: number;
+    /** Prefer optional object fields when generating inputs. Default: true. */
+    includeOptional?: boolean;
+    /** Generate one item for arrays by default. Default: true. */
+    includeArrayItems?: boolean;
+    /** Overrides by full dot path, field name, or request part path. */
+    values?: Record<string, AutoInputValue>;
+    /** Custom fallback for files. Defaults to Blob when available, otherwise string. */
+    fileFactory?: () => unknown;
+};
+type ApiTestRunnerOptions = {
+    mode?: ApiTestMode;
+    timeout?: number;
+    concurrency?: number;
+    stopOnFail?: boolean;
+    includeDestructive?: boolean;
+    includeTags?: string[];
+    excludeTags?: string[];
+    autoInput?: AutoInputOptions;
+    requestOptions?: RequestOptions;
+};
+type ApiTestRunnerConfig<C extends Contracts = Contracts> = {
+    contracts: C;
+    /** Initialized ApiClient instance or compatible object with modules. */
+    client: {
+        modules: Record<string, Record<string, (input: any, options?: RequestOptions) => Promise<any>>>;
+    };
+    options?: ApiTestRunnerOptions;
+    context?: Record<string, unknown>;
+};
+type ApiTestCaseMeta = {
+    module: string;
+    endpoint: string;
+    caseName: string;
+    phase: ApiTestMode | "schema" | "mock" | "live";
+    method: Method;
+    path: string;
+    tags: string[];
+    destructive: boolean;
+};
+type ApiTestError = {
+    name?: string;
+    message: string;
+    status?: number;
+    code?: string;
+    issues?: unknown;
+    stack?: string;
+};
+type ApiTestResult = ApiTestCaseMeta & {
+    status: ApiTestStatus;
+    durationMs: number;
+    input?: unknown;
+    response?: unknown;
+    error?: ApiTestError;
+    skipReason?: string;
+};
+type ApiTestReportSummary = {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    durationMs: number;
+};
+type ApiTestReport = {
+    generatedAt: string;
+    mode: ApiTestMode;
+    summary: ApiTestReportSummary;
+    results: ApiTestResult[];
+};
+
+declare function generateInput(schema: z.ZodTypeAny, options?: AutoInputOptions): unknown;
+
+declare function createMarkdownReport(report: ApiTestReport): string;
+declare function createHtmlReport(report: ApiTestReport): string;
+
+declare function createApiTestRunner<C extends Contracts>(config: ApiTestRunnerConfig<C>): ApiTestRunner<C>;
+declare class ApiTestRunner<C extends Contracts> {
+    private readonly config;
+    private readonly ctx;
+    private readonly options;
+    constructor(config: ApiTestRunnerConfig<C>);
+    run(): Promise<ApiTestReport>;
+    private discoverEndpoints;
+    private runEndpoint;
+    private getEndpointSkipReason;
+    private getCases;
+    private getPhases;
+    private runCasePhase;
+    private callClient;
+}
+
+type TypeFetchCliCommand = "test" | "list" | "init" | "release-doc" | "help" | "version";
+type ParsedCliArgs = {
+    command: TypeFetchCliCommand;
+    flags: Record<string, string | boolean | string[]>;
+    positionals: string[];
+    raw: string[];
+};
+type TypeFetchClientLike = {
+    init?: () => void;
+    modules: Record<string, Record<string, (input: any, options?: RequestOptions) => Promise<any>>>;
+};
+type TypeFetchCreateClientOptions = {
+    baseUrl?: string;
+    token?: string;
+};
+type TypeFetchReportConfig = {
+    /** Path base or full file path. Examples: ./typefetch-report/report or ./typefetch-report/report.md */
+    output?: string;
+    formats?: ApiTestReportFormat[];
+};
+type TypeFetchCliTestConfig<C extends Contracts = Contracts> = {
+    contracts: C;
+    /** Use client for simple projects. */
+    client?: TypeFetchClientLike;
+    /** Prefer createClient when you want CLI flags like --base-url and --token to work. */
+    createClient?: (options: TypeFetchCreateClientOptions) => TypeFetchClientLike | Promise<TypeFetchClientLike>;
+    options?: ApiTestRunnerOptions;
+    context?: Record<string, unknown>;
+    report?: TypeFetchReportConfig;
+};
+type CliResolvedOptions = {
+    mode?: ApiTestMode;
+    baseUrl?: string;
+    token?: string;
+    timeout?: number;
+    includeTags?: string[];
+    excludeTags?: string[];
+    includeDestructive?: boolean;
+    stopOnFail?: boolean;
+    output?: string;
+    formats?: ApiTestReportFormat[];
+    config?: string;
+};
+type InitCommandOptions = {
+    force?: boolean;
+    packageName?: string;
+    contractsPath?: string;
+    output?: string;
+};
+type ReleaseDocCommandOptions = {
+    force?: boolean;
+    version?: string;
+    outputDir?: string;
+    title?: string;
+};
+
+declare function defineTypeFetchTestConfig<C extends Contracts>(config: TypeFetchCliTestConfig<C>): TypeFetchCliTestConfig<C>;
+
+export { ApiClient, type ApiTestCaseMeta, type ApiTestError, type ApiTestMode, type ApiTestReport, type ApiTestReportFormat, type ApiTestReportSummary, type ApiTestResult, ApiTestRunner, type ApiTestRunnerConfig, type ApiTestRunnerOptions, type ApiTestStatus, type AuthOptions, type AutoInputOptions, type CacheOptions, type CliResolvedOptions, type Contracts, type DeepEncryptionMap, type EncryptionConfig, type EncryptionMethod, type EncryptionOptions, type EndpointDef, type EndpointDefZ, type EndpointMethods, type EndpointTestAssertion, type EndpointTestCase, type EndpointTestConfig, type EndpointTestContext, type EndpointTestInputFactory, type ErrorLike, type InitCommandOptions, type LoggingOptions, type Method, type Middleware, type MiddlewareContext, type MiddlewareNext, type ParsedCliArgs, type ReleaseDocCommandOptions, type RequestOptions, type RequestParts, type RequestSchema, type ResponseSchema, type RetryOptions, RichError, type TokenProvider, type TypeFetchCliCommand, type TypeFetchCliTestConfig, type TypeFetchClientLike, type TypeFetchCreateClientOptions, type TypeFetchReportConfig, TypeFetchTestContext, authMiddleware, cacheMiddleware, createApiTestRunner, createHtmlReport, createMarkdownReport, defineTypeFetchTestConfig, encryptionMiddleware, generateInput, loggingMiddleware, makeRequestSchema, processDeep, retryMiddleware };

package/dist/index.d.ts

@@ -37,6 +37,56 @@ type EncryptionConfig<TReq, TRes> = {
  */
 type RequestSchema = z.ZodTypeAny;
 type ResponseSchema = z.ZodTypeAny;
+/**
+ * EndpointTestContext
+ * ===================
+ * Shared runtime state used by the API test runner.
+ * It allows one endpoint test to store values that later tests can reuse.
+ */
+type EndpointTestContext = {
+    data: Record<string, unknown>;
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    has(key: string): boolean;
+};
+type EndpointTestInputFactory<TReq> = (ctx: EndpointTestContext) => TReq | Promise<TReq>;
+type EndpointTestAssertion<TReq, TRes> = (result: {
+    input: TReq;
+    response: TRes;
+    ctx: EndpointTestContext;
+}) => void | Promise<void>;
+type EndpointTestCase<TReq, TRes> = {
+    /** Human-readable name shown in the generated report. */
+    name?: string;
+    /** Static input or a factory that can read/write shared test context. */
+    input?: TReq | EndpointTestInputFactory<TReq>;
+    /** Skip this specific case. A string is used as the skip reason. */
+    skip?: boolean | string;
+    /** Expected HTTP status. Defaults to any successful client response. */
+    expectStatus?: number | number[];
+    /** Optional user-defined assertion after a successful response. */
+    expect?: EndpointTestAssertion<TReq, TRes>;
+    /** Per-case timeout in milliseconds. */
+    timeout?: number;
+    /** Tags used by the runner for include/exclude filtering. */
+    tags?: string[];
+};
+type EndpointTestConfig<TReq, TRes> = {
+    /** Disable all generated/manual tests for this endpoint. */
+    enabled?: boolean;
+    /** Tags used by the runner for include/exclude filtering. */
+    tags?: string[];
+    /** Mark endpoints such as DELETE/reset/payment as unsafe for default runs. */
+    destructive?: boolean;
+    /** Default input used when cases are not provided. */
+    input?: TReq | EndpointTestInputFactory<TReq>;
+    /** One or more test cases for this endpoint. */
+    cases?: Array<EndpointTestCase<TReq, TRes>>;
+    /** Runs before the endpoint cases. */
+    setup?: (ctx: EndpointTestContext) => void | Promise<void>;
+    /** Runs after the endpoint cases. */
+    teardown?: (ctx: EndpointTestContext) => void | Promise<void>;
+};
 /**
  * EndpointDef
  * ============
@@ -81,6 +131,10 @@ type EndpointDef<TReq extends RequestSchema, TRes extends ResponseSchema> = {
      * - `"form-data"`: multipart form
      */
     bodyType?: "json" | "form-data";
+    /**
+     * Optional contract-driven tests used by the TypeFetch test runner.
+     */
+    test?: EndpointTestConfig<z.infer<TReq>, z.infer<TRes>>;
 };
 /**
  * Contracts
@@ -406,4 +460,167 @@ declare const makeRequestSchema: <TPath extends z.ZodRawShape = {}, TQuery exten
     headers: THeaders;
 }, z.core.$strip>;
 
-export { ApiClient, type AuthOptions, type CacheOptions, type Contracts, type DeepEncryptionMap, type EncryptionConfig, type EncryptionMethod, type EncryptionOptions, type EndpointDef, type EndpointDefZ, type EndpointMethods, type ErrorLike, type LoggingOptions, type Method, type Middleware, type MiddlewareContext, type MiddlewareNext, type RequestOptions, type RequestParts, type RequestSchema, type ResponseSchema, type RetryOptions, RichError, type TokenProvider, authMiddleware, cacheMiddleware, encryptionMiddleware, loggingMiddleware, makeRequestSchema, processDeep, retryMiddleware };
+declare class TypeFetchTestContext implements EndpointTestContext {
+    data: Record<string, unknown>;
+    constructor(initialData?: Record<string, unknown>);
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T): void;
+    has(key: string): boolean;
+}
+
+type ApiTestMode = "schema" | "mock" | "live" | "full";
+type ApiTestStatus = "passed" | "failed" | "skipped";
+type ApiTestReportFormat = "json" | "markdown" | "html";
+type AutoInputValue = unknown | ((path: string) => unknown);
+type AutoInputOptions = {
+    /** Maximum recursive generation depth for nested schemas. */
+    maxDepth?: number;
+    /** Prefer optional object fields when generating inputs. Default: true. */
+    includeOptional?: boolean;
+    /** Generate one item for arrays by default. Default: true. */
+    includeArrayItems?: boolean;
+    /** Overrides by full dot path, field name, or request part path. */
+    values?: Record<string, AutoInputValue>;
+    /** Custom fallback for files. Defaults to Blob when available, otherwise string. */
+    fileFactory?: () => unknown;
+};
+type ApiTestRunnerOptions = {
+    mode?: ApiTestMode;
+    timeout?: number;
+    concurrency?: number;
+    stopOnFail?: boolean;
+    includeDestructive?: boolean;
+    includeTags?: string[];
+    excludeTags?: string[];
+    autoInput?: AutoInputOptions;
+    requestOptions?: RequestOptions;
+};
+type ApiTestRunnerConfig<C extends Contracts = Contracts> = {
+    contracts: C;
+    /** Initialized ApiClient instance or compatible object with modules. */
+    client: {
+        modules: Record<string, Record<string, (input: any, options?: RequestOptions) => Promise<any>>>;
+    };
+    options?: ApiTestRunnerOptions;
+    context?: Record<string, unknown>;
+};
+type ApiTestCaseMeta = {
+    module: string;
+    endpoint: string;
+    caseName: string;
+    phase: ApiTestMode | "schema" | "mock" | "live";
+    method: Method;
+    path: string;
+    tags: string[];
+    destructive: boolean;
+};
+type ApiTestError = {
+    name?: string;
+    message: string;
+    status?: number;
+    code?: string;
+    issues?: unknown;
+    stack?: string;
+};
+type ApiTestResult = ApiTestCaseMeta & {
+    status: ApiTestStatus;
+    durationMs: number;
+    input?: unknown;
+    response?: unknown;
+    error?: ApiTestError;
+    skipReason?: string;
+};
+type ApiTestReportSummary = {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    durationMs: number;
+};
+type ApiTestReport = {
+    generatedAt: string;
+    mode: ApiTestMode;
+    summary: ApiTestReportSummary;
+    results: ApiTestResult[];
+};
+
+declare function generateInput(schema: z.ZodTypeAny, options?: AutoInputOptions): unknown;
+
+declare function createMarkdownReport(report: ApiTestReport): string;
+declare function createHtmlReport(report: ApiTestReport): string;
+
+declare function createApiTestRunner<C extends Contracts>(config: ApiTestRunnerConfig<C>): ApiTestRunner<C>;
+declare class ApiTestRunner<C extends Contracts> {
+    private readonly config;
+    private readonly ctx;
+    private readonly options;
+    constructor(config: ApiTestRunnerConfig<C>);
+    run(): Promise<ApiTestReport>;
+    private discoverEndpoints;
+    private runEndpoint;
+    private getEndpointSkipReason;
+    private getCases;
+    private getPhases;
+    private runCasePhase;
+    private callClient;
+}
+
+type TypeFetchCliCommand = "test" | "list" | "init" | "release-doc" | "help" | "version";
+type ParsedCliArgs = {
+    command: TypeFetchCliCommand;
+    flags: Record<string, string | boolean | string[]>;
+    positionals: string[];
+    raw: string[];
+};
+type TypeFetchClientLike = {
+    init?: () => void;
+    modules: Record<string, Record<string, (input: any, options?: RequestOptions) => Promise<any>>>;
+};
+type TypeFetchCreateClientOptions = {
+    baseUrl?: string;
+    token?: string;
+};
+type TypeFetchReportConfig = {
+    /** Path base or full file path. Examples: ./typefetch-report/report or ./typefetch-report/report.md */
+    output?: string;
+    formats?: ApiTestReportFormat[];
+};
+type TypeFetchCliTestConfig<C extends Contracts = Contracts> = {
+    contracts: C;
+    /** Use client for simple projects. */
+    client?: TypeFetchClientLike;
+    /** Prefer createClient when you want CLI flags like --base-url and --token to work. */
+    createClient?: (options: TypeFetchCreateClientOptions) => TypeFetchClientLike | Promise<TypeFetchClientLike>;
+    options?: ApiTestRunnerOptions;
+    context?: Record<string, unknown>;
+    report?: TypeFetchReportConfig;
+};
+type CliResolvedOptions = {
+    mode?: ApiTestMode;
+    baseUrl?: string;
+    token?: string;
+    timeout?: number;
+    includeTags?: string[];
+    excludeTags?: string[];
+    includeDestructive?: boolean;
+    stopOnFail?: boolean;
+    output?: string;
+    formats?: ApiTestReportFormat[];
+    config?: string;
+};
+type InitCommandOptions = {
+    force?: boolean;
+    packageName?: string;
+    contractsPath?: string;
+    output?: string;
+};
+type ReleaseDocCommandOptions = {
+    force?: boolean;
+    version?: string;
+    outputDir?: string;
+    title?: string;
+};
+
+declare function defineTypeFetchTestConfig<C extends Contracts>(config: TypeFetchCliTestConfig<C>): TypeFetchCliTestConfig<C>;
+
+export { ApiClient, type ApiTestCaseMeta, type ApiTestError, type ApiTestMode, type ApiTestReport, type ApiTestReportFormat, type ApiTestReportSummary, type ApiTestResult, ApiTestRunner, type ApiTestRunnerConfig, type ApiTestRunnerOptions, type ApiTestStatus, type AuthOptions, type AutoInputOptions, type CacheOptions, type CliResolvedOptions, type Contracts, type DeepEncryptionMap, type EncryptionConfig, type EncryptionMethod, type EncryptionOptions, type EndpointDef, type EndpointDefZ, type EndpointMethods, type EndpointTestAssertion, type EndpointTestCase, type EndpointTestConfig, type EndpointTestContext, type EndpointTestInputFactory, type ErrorLike, type InitCommandOptions, type LoggingOptions, type Method, type Middleware, type MiddlewareContext, type MiddlewareNext, type ParsedCliArgs, type ReleaseDocCommandOptions, type RequestOptions, type RequestParts, type RequestSchema, type ResponseSchema, type RetryOptions, RichError, type TokenProvider, type TypeFetchCliCommand, type TypeFetchCliTestConfig, type TypeFetchClientLike, type TypeFetchCreateClientOptions, type TypeFetchReportConfig, TypeFetchTestContext, authMiddleware, cacheMiddleware, createApiTestRunner, createHtmlReport, createMarkdownReport, defineTypeFetchTestConfig, encryptionMiddleware, generateInput, loggingMiddleware, makeRequestSchema, processDeep, retryMiddleware };