swaggerizer 0.0.0-stage → 1.0.0

package/dist/spec.d.ts

@@ -0,0 +1,36 @@
+import { type Contract } from "./contract";
+import type { CatalogueOperation } from "./types";
+export declare const SPEC_FILE_PATTERN: RegExp;
+export interface LoadedSpec {
+    file: string;
+    /** "2.0" for Swagger, otherwise the `openapi` version. */
+    specVersion?: string;
+    /** Bundled OpenAPI 3 document (Swagger 2 is converted). */
+    doc: any;
+    /** The bundled document as published (before any Swagger 2 conversion); what orval is given for URL specs. */
+    raw?: any;
+    warnings: string[];
+}
+export interface LoadSpecOptions {
+    /** Request headers for spec URLs, e.g. `{ Authorization: "Bearer …" }` for a protected api-docs endpoint. */
+    headers?: Record<string, string>;
+    /** Give up on a spec URL after this many ms (default 30000). */
+    timeout?: number;
+}
+/** Quick check used when scanning folders: is this YAML/JSON file an OpenAPI or Swagger document? */
+export declare function looksLikeSpec(file: string): Promise<boolean>;
+export declare function listSpecFiles(folder: string): Promise<string[]>;
+export declare function loadSpecFile(file: string, options?: LoadSpecOptions): Promise<LoadedSpec>;
+/** Stable id for a spec file: its basename without extensions (`users.swagger.json` → `users`). */
+export declare function specIdFor(file: string): string;
+export interface AnalysedSpec extends LoadedSpec {
+    id: string;
+    operations: CatalogueOperation[];
+    contract: Contract;
+    basePaths: string[];
+    serverUrl?: string;
+}
+export declare function analyseSpecFile(file: string, id?: string, options?: LoadSpecOptions): Promise<AnalysedSpec>;
+/** Accepts a mix of spec files and folders and returns every spec file, folder contents sorted. */
+export declare function resolveSpecInputs(inputs: string[]): Promise<string[]>;
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAKA,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE1D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,eAAO,MAAM,iBAAiB,QAAqB,CAAC;AAEpD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,GAAG,EAAE,GAAG,CAAC;IACT,8GAA8G;IAC9G,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,6GAA6G;IAC7G,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAmED,qGAAqG;AACrG,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOlE;AAED,wBAAsB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUrE;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,UAAU,CAAC,CAoCnG;AAED,mGAAmG;AACnG,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAkB,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,CAU9H;AAED,mGAAmG;AACnG,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAa3E"}

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+export type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+export declare const HTTP_METHODS: HttpMethod[];
+/** Variant name used for a response that has a body but no explicit examples in the spec. */
+export declare const GENERATED = "generated";
+/** Variant name used for a response that declares no body at all. */
+export declare const EMPTY = "empty";
+/** How an operation is answered. */
+export type ScenarioMode = 
+/** Serve one of the responses declared in the spec (named example or generated sample). */
+"mock"
+/** Serve a response typed in by hand in the admin page / debug menu. */
+ | "custom"
+/** Forward the request to the real API (proxy on the server, `passthrough()` in MSW). */
+ | "proxy";
+export interface CustomResponse {
+    status: number;
+    body?: unknown;
+    contentType?: string;
+    headers?: Record<string, string>;
+}
+/** What the admin has chosen for one method + route. Every field is optional: unset means default. */
+export interface Scenario {
+    code?: string;
+    example?: string;
+    mode?: ScenarioMode;
+    custom?: CustomResponse;
+    /** Artificial latency in milliseconds. */
+    delay?: number;
+}
+export type ScenarioMap = Record<string, Scenario>;
+/** A single named example (or synthesised payload) that a response can serve. */
+export interface CatalogueExample {
+    name: string;
+    summary?: string;
+    value: unknown;
+    /** Overrides the response's content type for this example (scenario overlays). */
+    contentType?: string;
+    headers?: Record<string, string>;
+    /** True when the example came from a scenario overlay rather than the spec. */
+    overlay?: boolean;
+}
+/** One response code declared for an operation. */
+export interface CatalogueResponse {
+    /** As written in the spec: "200", "404", "2XX" or "default". */
+    code: string;
+    /** The HTTP status actually sent for this response. */
+    status: number;
+    description?: string;
+    contentTypes: string[];
+    hasBody: boolean;
+    examples: CatalogueExample[];
+    /** Deterministic sample synthesised from the schema; present when there are no explicit examples. */
+    generated?: unknown;
+}
+/** One HTTP method on one route, as declared by a single spec file. */
+export interface CatalogueOperation {
+    /** `${method}:${route}` – the key used by the scenario planner. */
+    key: string;
+    method: HttpMethod;
+    /** OpenAPI path template, e.g. `/pets/{petId}`. */
+    route: string;
+    specId: string;
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    deprecated?: boolean;
+    responses: CatalogueResponse[];
+    defaultCode: string;
+    defaultExample: string;
+}
+export interface OperationState extends CatalogueOperation {
+    mode: ScenarioMode;
+    selectedCode: string;
+    /** The variant that will actually be served (falls back to the first variant of the code). */
+    selectedExample: string;
+    delay: number;
+    custom?: CustomResponse;
+    modified: boolean;
+    /** False when the spec is disabled or another enabled spec already serves this method + route. */
+    active: boolean;
+    shadowedBy?: string;
+}
+/** The parts of a loaded spec the scenario planner needs. */
+export interface PlannerSpec {
+    id: string;
+    enabled: boolean;
+    error?: string;
+    operations: CatalogueOperation[];
+}
+/** Everything the MSW runtime needs to know about one spec, embedded in generated code. */
+export interface SwaggerizerManifest {
+    specId: string;
+    title?: string;
+    version?: string;
+    /** Path prefixes taken from `servers` (e.g. `/v1`); requests may arrive with or without them. */
+    basePaths: string[];
+    operations: CatalogueOperation[];
+    /** Scenario defaults saved from the admin page when the code was generated. */
+    scenarios?: ScenarioMap;
+    /** Request path prefixes that are rewritten before matching, e.g. `{ "/bff/v4/": "/v4/" }`. */
+    aliases?: Record<string, string>;
+}
+export interface SpecSummary {
+    id: string;
+    file: string;
+    name: string;
+    title?: string;
+    version?: string;
+    /** "2.0", "3.0.3", "3.1.0"… */
+    specVersion?: string;
+    enabled: boolean;
+    loadedAt: string;
+    error?: string;
+    warnings: string[];
+    basePaths: string[];
+    aliases?: Record<string, string>;
+    /** Where the spec was loaded from when it is not a local file. */
+    source?: string;
+    proxyTarget?: string;
+    operationCount: number;
+}
+export interface SwaggerizerState {
+    endpoint: string;
+    defaultDelay?: number;
+    fallback?: string;
+    specs: SpecSummary[];
+    operations: OperationState[];
+    lastReload?: string;
+    changes: ChangeReport[];
+}
+export interface ScenarioSelection extends Scenario {
+    method: string;
+    route: string;
+}
+export interface RequestLogEntry {
+    id: number;
+    time: string;
+    method: string;
+    path: string;
+    route?: string;
+    status: number;
+    /** Variant served, or "custom" / "proxy" / "unmatched". */
+    example: string;
+    specId?: string;
+    contentType?: string;
+    /** "server" for the Node mock server, "msw" for requests reported by the MSW runtime. */
+    source: "server" | "msw";
+    ms?: number;
+}
+export type ChangeSeverity = "breaking" | "warning" | "info";
+export type ChangeKind = "operation-added" | "operation-removed" | "operation-renamed" | "operation-deprecated" | "parameter-added" | "parameter-removed" | "parameter-changed" | "request-body-added" | "request-body-removed" | "request-body-changed" | "response-added" | "response-removed" | "response-changed";
+export interface ContractChange {
+    severity: ChangeSeverity;
+    kind: ChangeKind;
+    /** e.g. `GET /pets/{petId}` */
+    operation: string;
+    /** e.g. `response 200 body.items[].name` */
+    location?: string;
+    message: string;
+}
+export interface ChangeReport {
+    specId: string;
+    title?: string;
+    /** What the spec was compared against. */
+    baseline: "snapshot" | "previous-load";
+    fromVersion?: string;
+    toVersion?: string;
+    added: string[];
+    removed: string[];
+    changed: string[];
+    changes: ContractChange[];
+    counts: Record<ChangeSeverity, number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}