callman-core 1.38.0 → 1.40.0

package/dist/mock-engine/types.d.ts

@@ -0,0 +1,684 @@
+export type MockHttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ANY";
+export type ConditionOperator = "exists" | "not-exists" | "equals" | "not-equals" | "contains" | "starts-with" | "matches";
+export interface VariantConditionRule {
+    /** `headers.x`, `params.x`, `query.x`, `body.a.b`, `auth.sub`, `auth.claims.role`, `session.id`. */
+    field: string;
+    operator: ConditionOperator;
+    value?: string;
+}
+export interface VariantCondition {
+    type: "all" | "any";
+    rules: VariantConditionRule[];
+}
+export type MockDelayConfig = {
+    mode: "none";
+} | {
+    mode: "fixed";
+    ms: number;
+} | {
+    mode: "random";
+    minMs: number;
+    maxMs: number;
+};
+export interface MockRequestValidationConfig {
+    mode: "any" | "schema";
+    /** JSON Schema draft-07. */
+    schema?: unknown;
+}
+export type BuilderPreset = "list" | "detail" | "create" | "update" | "delete" | "echo" | "custom";
+export type LegacyMockSource = {
+    kind: "static";
+    data: unknown[];
+} | {
+    kind: "state";
+    stateKey: string;
+};
+export interface ListBuilderConfig {
+    preset: "list";
+    source: LegacyMockSource;
+    filtering: {
+        enabled: boolean;
+        rules: {
+            queryParam: string;
+            field: string;
+            operator: "equals" | "contains" | "startsWith" | "in";
+        }[];
+    };
+    sorting: {
+        enabled: boolean;
+        sortByParam: string;
+        orderParam: string;
+        allowedFields: string[];
+    };
+    pagination: {
+        enabled: boolean;
+        strategy: "page" | "offset" | "cursor";
+        defaultPageSize: number;
+        maxPageSize: number;
+        envelope: "standard" | "data-meta" | "raw";
+    };
+    statusCode: number;
+    headers: Record<string, string>;
+}
+export interface DetailBuilderConfig {
+    preset: "detail";
+    source: LegacyMockSource;
+    paramName: string;
+    lookupField: string;
+    notFoundBehavior: {
+        statusCode: number;
+        body?: unknown;
+    };
+    statusCode: number;
+    headers: Record<string, string>;
+}
+export interface CreateBuilderConfig {
+    preset: "create";
+    stateKey: string;
+    autoGenerate: {
+        id?: "uuid" | "incremental";
+        createdAt?: boolean;
+        updatedAt?: boolean;
+    };
+    requiredFields: string[];
+    responseBehavior: "return-created" | "return-id" | "status-only";
+    statusCode: number;
+    headers: Record<string, string>;
+}
+export interface UpdateBuilderConfig {
+    preset: "update";
+    stateKey: string;
+    paramName: string;
+    lookupField: string;
+    mergeStrategy: "partial" | "full";
+    autoUpdateUpdatedAt: boolean;
+    notFoundBehavior: {
+        statusCode: number;
+        body?: unknown;
+    };
+    statusCode: number;
+    headers: Record<string, string>;
+}
+export interface DeleteBuilderConfig {
+    preset: "delete";
+    stateKey: string;
+    paramName: string;
+    lookupField: string;
+    notFoundBehavior: {
+        statusCode: number;
+        body?: unknown;
+    };
+    responseBehavior: "204" | "return-deleted" | "success-message";
+    statusCode: number;
+    headers: Record<string, string>;
+}
+export interface EchoBuilderConfig {
+    preset: "echo";
+    statusCode: number;
+    headers: Record<string, string>;
+}
+export interface CustomBuilderConfig {
+    preset: "custom";
+    statusCode: number;
+    headers: Record<string, string>;
+    body?: unknown;
+}
+export type BuilderConfig = ListBuilderConfig | DetailBuilderConfig | CreateBuilderConfig | UpdateBuilderConfig | DeleteBuilderConfig | EchoBuilderConfig | CustomBuilderConfig;
+export type MockResponseConfig = {
+    type: "static";
+    statusCode: number;
+    headers: Record<string, string>;
+    body?: unknown;
+} | {
+    type: "template";
+    statusCode: number;
+    headers: Record<string, string>;
+    body?: unknown;
+} | {
+    type: "builder";
+    preset: BuilderPreset;
+    config: BuilderConfig;
+};
+export interface MockResponseVariant {
+    variantId: string;
+    /** Ascending: the lowest number is checked first. */
+    priority: number;
+    condition: VariantCondition;
+    response: MockResponseConfig;
+}
+export type MockOutcome = "success" | "created" | "notFound" | "conflict" | "validationError" | "unauthorized" | "forbidden" | "limitExceeded" | "payloadTooLarge";
+/** A per-outcome response. `body` and header values are always template-resolved. */
+export interface MockOutcomeResponse {
+    statusCode?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+export type MockOutcomeResponses = Partial<Record<MockOutcome, MockOutcomeResponse>>;
+/** `none` = public, `user` = any signed-in user, `{roles}` = user with one of these roles. */
+export type MockAuthRequirement = "none" | "user" | {
+    roles: string[];
+};
+export interface MockUserAuthConfig {
+    enabled: boolean;
+    /** Resource name holding the users. */
+    usersResource: string;
+    identityField: string;
+    passwordField: string;
+    /** HMAC secret (hex). Generated by the host when absent; never returned unmasked by default. */
+    secret?: string;
+    tokenTtlSeconds: number;
+    issuer?: string;
+    audience?: string;
+    /** User field copied into the `role` claim and checked by `{roles}` requirements. */
+    roleClaim?: string;
+    /** Extra claims: claim name ← user field. */
+    claims?: Record<string, string>;
+    /** Default requirement: nothing, every resource endpoint, or every route. */
+    protect: "none" | "resources" | "all";
+    endpoints: {
+        login: {
+            enabled: boolean;
+            path: string;
+        };
+        register: {
+            enabled: boolean;
+            path: string;
+        };
+        me: {
+            enabled: boolean;
+            path: string;
+        };
+    };
+    responses?: Partial<Record<"loginSuccess" | "loginFailure" | "unauthorized" | "forbidden", MockOutcomeResponse>>;
+}
+export interface MockFaultRule {
+    id: string;
+    enabled: boolean;
+    kind: "error" | "delay" | "timeout" | "drop";
+    /** 0..1, default 1. */
+    probability?: number;
+    when?: {
+        callCount?: {
+            lte?: number;
+            gte?: number;
+            every?: number;
+            in?: number[];
+        };
+        condition?: VariantCondition;
+    };
+    /** `before` short-circuits the handler; `after` runs it, then loses or delays the answer. */
+    phase?: "before" | "after";
+    error?: MockOutcomeResponse;
+    delay?: {
+        minMs: number;
+        maxMs: number;
+    };
+    timeout?: {
+        afterMs?: number;
+    };
+    drop?: {
+        mode: "reset" | "partial";
+    };
+}
+export interface MockFaultSequenceStep {
+    times: number;
+    outcome: "pass" | Omit<MockFaultRule, "id" | "enabled" | "when" | "probability">;
+}
+export interface MockFaultConfig {
+    /** Route/endpoint faults also apply the mock-level ones unless false. */
+    inherit?: boolean;
+    rules: MockFaultRule[];
+    sequence?: {
+        steps: MockFaultSequenceStep[];
+        loop: boolean;
+    };
+}
+/** The flat form the UI and the MCP edit; converted with `faultsFromSimple` / `toSimpleFaults`. */
+export interface MockSimpleFaults {
+    /** % of requests answered with `errorStatus`. */
+    errorRate?: number;
+    errorStatus?: number;
+    errorBody?: unknown;
+    delay?: MockDelayConfig;
+    /** % of requests held unanswered. */
+    timeoutRate?: number;
+    /** % of requests whose connection is closed without a response. */
+    dropRate?: number;
+    /** The first N requests (per session) fail with `errorStatus`, then recover. */
+    failFirst?: number;
+}
+export interface MockSessionConfig {
+    enabled: boolean;
+    idleTtlMinutes: number;
+    /** Lets a caller reset its own session through `POST /__callman/session/reset`. */
+    allowPublicReset: boolean;
+}
+export type MockFieldType = "string" | "number" | "integer" | "boolean" | "object" | "array" | "date" | "datetime" | "email" | "uuid" | "password";
+export type MockIdStrategy = "uuid" | "incremental" | "objectId" | "nanoid" | "client";
+export interface MockFieldRef {
+    /** Target resource name. */
+    resource: string;
+    onDelete: "restrict" | "cascade" | "nullify" | "none";
+    /** Check the target exists on create/update (default true). */
+    check?: boolean;
+    /** Name of the expanded object for `_expand` (default: field name minus `Id`/`_id`). */
+    as?: string;
+    /** Generate `GET/POST /<parent>/:<field>/<child>` nested routes (default true). */
+    nested?: boolean;
+}
+export interface MockField {
+    /** `^[A-Za-z_][A-Za-z0-9_]{0,63}$` */
+    name: string;
+    type: MockFieldType;
+    required?: boolean;
+    nullable?: boolean;
+    unique?: boolean;
+    uniqueCaseInsensitive?: boolean;
+    /** A literal, or a template such as `"{{now}}"` / `"{{auth.sub}}"`. */
+    default?: unknown;
+    enum?: (string | number)[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    items?: {
+        type: Exclude<MockFieldType, "password" | "array">;
+    };
+    /** Client writes are ignored. */
+    readOnly?: boolean;
+    /** Never returned. `password` fields are always write-only and stored hashed. */
+    writeOnly?: boolean;
+    ref?: MockFieldRef;
+    /** `$randomEmail`, `faker.email`, or a template like `"{{$randomFirstName}} {{$randomLastName}}"`. */
+    fakerHint?: string;
+}
+export type MockResourceEndpointName = "list" | "get" | "create" | "replace" | "patch" | "delete";
+export interface MockResourceEndpointConfig {
+    enabled: boolean;
+    auth?: MockAuthRequirement;
+    faults?: MockFaultConfig;
+    delay?: MockDelayConfig;
+    responses?: MockOutcomeResponses;
+    requestValidation?: MockRequestValidationConfig;
+}
+export interface MockResourceListConfig {
+    envelope: "array" | "data-meta" | "items" | "custom";
+    /** Template with `{{records}} {{total}} {{page}} {{limit}} {{totalPages}}` (envelope `custom`). */
+    customBody?: unknown;
+    /** Page size when the client sends none; null = everything up to `maxLimit`. */
+    defaultLimit: number | null;
+    maxLimit: number;
+    totalCountHeader: boolean;
+    linkHeader: boolean;
+    /** `declared` ignores query params that are not fields; `any` filters on every param. */
+    filterMode: "declared" | "any";
+    searchable: boolean;
+    /** e.g. `-createdAt,name` */
+    defaultSort?: string;
+}
+export interface MockResourceSeed {
+    records?: Record<string, unknown>[];
+    /** Generate N records from the field definitions (after `records`). */
+    generate?: number;
+    salt?: string;
+}
+export interface MockResource {
+    /** Stable id: records are keyed by it, so renaming never touches data. */
+    resourceId: string;
+    /** `^[a-z][a-zA-Z0-9_-]{0,39}$`, unique per mock. */
+    name: string;
+    basePath: string;
+    idField: string;
+    idStrategy: MockIdStrategy;
+    /** Field the `/:id` endpoints look up by (default `idField`, e.g. `slug`). */
+    lookupField?: string;
+    /** Accept a client-sent id on create (default true). */
+    allowClientId?: boolean;
+    /** Empty = schemaless (json-server style). */
+    fields: MockField[];
+    additionalFields: "allow" | "strip" | "reject";
+    timestamps: {
+        createdAt: string | null;
+        updatedAt: string | null;
+    };
+    /** Records belong to the signed-in user through this field (needs userAuth). */
+    ownerField?: string;
+    auth?: MockAuthRequirement;
+    endpoints: Record<MockResourceEndpointName, MockResourceEndpointConfig>;
+    list: MockResourceListConfig;
+    seed?: MockResourceSeed;
+}
+export type MockDataOperation = "insert" | "find" | "findOne" | "update" | "delete" | "count" | "upsert";
+export interface MockActionMatchRule {
+    field: string;
+    op?: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "contains" | "like";
+    /** Template or literal: `"{{request.params.id}}"`, `"{{auth.sub}}"`, `"active"`. */
+    value: string;
+    /** Skip this rule when the value resolves to empty (optional filters). */
+    skipIfEmpty?: boolean;
+}
+export interface MockActionWrite {
+    /** Template for the written object; default `"{{request.body}}"`. */
+    source?: string;
+    pick?: string[];
+    omit?: string[];
+    /** Applied last; values are type-preserving templates. */
+    set?: Record<string, unknown>;
+}
+export interface MockDataAction {
+    operation: MockDataOperation;
+    /** Resource name. */
+    resource: string;
+    match?: MockActionMatchRule[];
+    write?: MockActionWrite;
+    /** update: merge (default) or replace. */
+    mode?: "merge" | "replace";
+    /** update/delete every match instead of the first. */
+    many?: boolean;
+    find?: {
+        useRequestQuery?: boolean;
+        sort?: string;
+        limit?: number;
+    };
+    responses?: MockOutcomeResponses;
+}
+export interface MockRoute {
+    routeId: string;
+    method: MockHttpMethod;
+    path: string;
+    name?: string;
+    /** With `action`: the default success response. */
+    response: MockResponseConfig;
+    variants: MockResponseVariant[];
+    behavior: {
+        delay: MockDelayConfig;
+    };
+    requestValidation?: MockRequestValidationConfig;
+    /** Disabled routes never match (default enabled). */
+    enabled?: boolean;
+    /** Extra match condition (query/headers): when false the next route is tried. */
+    match?: VariantCondition;
+    action?: MockDataAction;
+    auth?: MockAuthRequirement;
+    faults?: MockFaultConfig;
+}
+export interface MockDefinition {
+    schemaVersion: 2;
+    name?: string;
+    description?: string;
+    routes: MockRoute[];
+    resources: MockResource[];
+    userAuth?: MockUserAuthConfig | null;
+    faults?: MockFaultConfig | null;
+    sessions?: MockSessionConfig;
+    /** The pre-v2 state bucket read by legacy builder routes and `{{state.*}}`. */
+    legacy?: {
+        state?: Record<string, unknown>;
+        initialState?: Record<string, unknown>;
+    };
+}
+type DeepPartial<T> = T extends (infer U)[] ? DeepPartial<U>[] : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/** What importers and editors produce: ids and defaults are filled in by `normalizeMockDefinition`. */
+export type MockDefinitionDraft = DeepPartial<MockDefinition>;
+export interface MockRequest {
+    method: string;
+    /** Path after the mount point, with a leading `/`. */
+    path: string;
+    /** `/mock/<id>` on the server, `""` on the desktop — used for Location/Link headers. */
+    mountPath: string;
+    /** Parsed query (Express `qs` shape) for templates and conditions. */
+    query: Record<string, unknown>;
+    /** Raw query pairs — the input of the list query language. */
+    rawQuery: Array<[string, string]>;
+    /** Lower-cased header names. */
+    headers: Record<string, string>;
+    body?: unknown;
+    receivedAt: number;
+}
+export interface MockRenderedResponse {
+    statusCode: number;
+    headers: Record<string, string>;
+    body: string;
+    /** The structured body before serialisation (logs). */
+    rawBody: unknown;
+    bodyTruncated: boolean;
+}
+export type MockTransport = {
+    kind: "respond";
+} | {
+    kind: "hang";
+    ms: number;
+} | {
+    kind: "drop";
+    mode: "reset" | "partial";
+};
+export interface MockEngineTrace {
+    routeId?: string;
+    virtual?: {
+        kind: "resource" | "auth" | "control";
+        resource?: string;
+        endpoint?: string;
+    };
+    variantId?: string;
+    session?: string;
+    authSubject?: string;
+    action?: {
+        operation: string;
+        resource: string;
+        outcome: string;
+        affected: number;
+    };
+    faults: {
+        ruleId: string;
+        kind: string;
+    }[];
+    failureReason?: string;
+    storeOps: number;
+    /** Set when the legacy state bucket changed (hosts invalidate their cache). */
+    legacyStateChanged?: boolean;
+}
+export interface MockExecutionResult {
+    response: MockRenderedResponse;
+    /** Already clamped to `limits.maxDelayMs`. */
+    delayMs: number;
+    transport: MockTransport;
+    trace: MockEngineTrace;
+}
+export interface MockInvalidField {
+    field: string;
+    message: string;
+}
+export interface MockRandomSource {
+    /** A number in [0, 1). */
+    next(): number;
+}
+export interface MockClock {
+    now(): number;
+}
+export interface MockCallCounters {
+    /** Increments and returns the call count of `key` inside the namespace. */
+    incr(scope: MockStoreScope, key: string): Promise<number>;
+    reset(scope: MockStoreScope): Promise<void>;
+}
+export interface MockRegexRunner {
+    test(pattern: string, subject: string): boolean;
+}
+export type MockBodyValidator = (schema: unknown, body: unknown) => MockInvalidField[] | null;
+export interface MockCryptoPort {
+    hmacSha256(key: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
+    sha256(data: Uint8Array): Promise<Uint8Array>;
+    randomBytes(length: number): Uint8Array;
+}
+export interface MockLegacyStatePort {
+    snapshot(): Record<string, unknown>;
+    apply(mutations: LegacyStateMutation[]): Promise<void>;
+}
+export type LegacyStateMutation = {
+    kind: "append";
+    stateKey: string;
+    value: unknown;
+} | {
+    kind: "updateAtIndex";
+    stateKey: string;
+    index: number;
+    value: unknown;
+} | {
+    kind: "removeAtIndex";
+    stateKey: string;
+    index: number;
+};
+export interface MockEngineLogger {
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+}
+export interface MockEngineLimits {
+    maxRecordsPerResource: number;
+    maxRecordsPerNamespace: number;
+    maxRecordBytes: number;
+    maxSessions: number;
+    sessionIdleTtlMs: number;
+    maxDataOpsPerRequest: number;
+    maxResponseBodyBytes: number;
+    maxDelayMs: number;
+    maxPageSize: number;
+    maxFilterClauses: number;
+    maxInValues: number;
+    maxExpand: number;
+    maxEmbedPerParent: number;
+    maxCascadeDepth: number;
+    maxCascadeRecords: number;
+    maxSeedGenerate: number;
+}
+export interface MockEngineContext {
+    mockId: string;
+    mockName?: string;
+    store?: MockDataStore;
+    clock: MockClock;
+    random: MockRandomSource;
+    counters: MockCallCounters;
+    regex: MockRegexRunner;
+    /** Node hosts pass the Ajv validator; without one `requestValidation` is skipped. */
+    bodyValidator?: MockBodyValidator;
+    crypto: MockCryptoPort;
+    legacyState?: MockLegacyStatePort;
+    logger?: MockEngineLogger;
+    limits: MockEngineLimits;
+}
+export interface MockStoreScope {
+    mockId: string;
+    /** `_` = shared data, `s:<id>` = a test session. */
+    ns: string;
+}
+export interface MockRecordDoc {
+    resource: string;
+    /** Canonical id: `n:<int>` or `s:<string>`. */
+    key: string;
+    data: Record<string, unknown>;
+    /** PK + unique-field tokens (one compound unique index). */
+    uniq: string[];
+    /** `<field>\u001f<target key>` tokens for relations. */
+    refs: string[];
+    /** Lower-cased searchable text for `q`. */
+    text: string;
+    rev: number;
+    /** Insertion order (stores assign it; the default sort). */
+    ordinal?: number;
+}
+export type MockFilterOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "nin" | "exists" | "contains" | "like";
+export type MockFilterNode = {
+    and: MockFilterNode[];
+} | {
+    or: MockFilterNode[];
+} | {
+    field: string;
+    op: MockFilterOp;
+    value: unknown;
+} | {
+    text: string;
+} | {
+    keys: string[];
+} | {
+    ref: string;
+    keys: string[];
+};
+export interface MockSortSpec {
+    field: string;
+    dir: 1 | -1;
+}
+export interface MockFindOptions {
+    filter?: MockFilterNode;
+    sort?: MockSortSpec[];
+    skip?: number;
+    limit?: number;
+    /** Skip the total count (expand/embed lookups). */
+    noTotal?: boolean;
+}
+export type MockWriteOutcome = {
+    ok: true;
+    doc: MockRecordDoc;
+} | {
+    ok: false;
+    reason: "conflict";
+    field: string;
+} | {
+    ok: false;
+    reason: "stale";
+} | {
+    ok: false;
+    reason: "notFound";
+};
+export interface MockSeedPlan {
+    docs: MockRecordDoc[];
+    /** Highest numeric id per resource, so incremental ids continue after the seed. */
+    sequences: Record<string, number>;
+}
+export interface MockNamespaceInfo {
+    ns: string;
+    kind: "default" | "session";
+    sessionId?: string;
+    createdAt?: string;
+    lastSeenAt?: string;
+    idleExpiresAt?: string | null;
+    recordCount?: number;
+}
+export interface MockEnsureNamespaceOptions {
+    isSession: boolean;
+    maxSessions: number;
+    idleTtlMs: number;
+    now: number;
+}
+export interface MockDataStore {
+    /** Create the namespace on first use and seed it once; sessions are capped. */
+    ensureNamespace(scope: MockStoreScope, seed: () => Promise<MockSeedPlan>, options: MockEnsureNamespaceOptions): Promise<{
+        ok: true;
+        created: boolean;
+    } | {
+        ok: false;
+        reason: "session-limit";
+    }>;
+    /** Drop every record of the namespace and seed it again. */
+    resetNamespace(scope: MockStoreScope, seed: MockSeedPlan, now: number): Promise<void>;
+    dropNamespace(scope: MockStoreScope): Promise<void>;
+    listNamespaces(mockId: string): Promise<MockNamespaceInfo[]>;
+    insert(scope: MockStoreScope, doc: MockRecordDoc): Promise<MockWriteOutcome>;
+    get(scope: MockStoreScope, resource: string, key: string): Promise<MockRecordDoc | null>;
+    getMany(scope: MockStoreScope, resource: string, keys: string[]): Promise<MockRecordDoc[]>;
+    find(scope: MockStoreScope, resource: string, options: MockFindOptions): Promise<{
+        docs: MockRecordDoc[];
+        total: number;
+    }>;
+    count(scope: MockStoreScope, resource: string, filter?: MockFilterNode, limit?: number): Promise<number>;
+    countNamespace(scope: MockStoreScope, limit?: number): Promise<number>;
+    /** Replace a record if its `rev` still matches. */
+    replace(scope: MockStoreScope, resource: string, key: string, expectedRev: number, doc: MockRecordDoc): Promise<MockWriteOutcome>;
+    delete(scope: MockStoreScope, resource: string, keys: string[]): Promise<number>;
+    /** Delete every record of a resource in the namespace. */
+    clearResource(scope: MockStoreScope, resource: string): Promise<number>;
+    nextSequence(scope: MockStoreScope, resource: string): Promise<number>;
+    bumpSequence(scope: MockStoreScope, resource: string, value: number): Promise<void>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map