@buun_group/gunspec-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,4554 @@
+/**
+ * Retry logic with exponential backoff for the GunSpec SDK.
+ *
+ * Only **idempotent** HTTP methods (`GET`, `PUT`, `DELETE`) are retried
+ * automatically.  Transient failures (timeouts, 429, 5xx) trigger a retry
+ * after an exponentially increasing delay with +-20 % jitter.
+ *
+ * @module
+ */
+/**
+ * Configuration for the retry behaviour.
+ *
+ * All fields are optional and fall back to sensible defaults.
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts (excluding the initial request).
+     *
+     * Set to `0` to disable retries entirely.
+     *
+     * @defaultValue `2`
+     */
+    maxRetries?: number;
+    /**
+     * Initial delay in milliseconds before the first retry.
+     *
+     * @defaultValue `500`
+     */
+    initialDelayMs?: number;
+    /**
+     * Upper-bound delay in milliseconds.  The computed delay is capped at this
+     * value regardless of how many retries have occurred.
+     *
+     * @defaultValue `8000`
+     */
+    maxDelayMs?: number;
+    /**
+     * Multiplier applied to the delay after each retry.
+     *
+     * @defaultValue `2`
+     */
+    multiplier?: number;
+}
+/** Fully resolved retry configuration with all defaults applied. */
+interface ResolvedRetryConfig {
+    readonly maxRetries: number;
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+    readonly multiplier: number;
+}
+
+/**
+ * Authentication handler for the GunSpec SDK.
+ *
+ * Resolves an API key from an explicit option or the `GUNSPEC_API_KEY`
+ * environment variable, and produces the header map needed for every
+ * authenticated request.
+ *
+ * @module
+ */
+/**
+ * Options accepted by the authentication handler.
+ */
+interface AuthConfig {
+    /**
+     * An explicit API key to use for all requests.
+     *
+     * When omitted the handler falls back to the `GUNSPEC_API_KEY` environment
+     * variable (Node.js / Deno / Bun `process.env`).  If neither is available
+     * the SDK operates in anonymous mode (no auth header is sent).
+     */
+    apiKey?: string;
+}
+/**
+ * Resolve the API key to use for authentication.
+ *
+ * Resolution order:
+ * 1. Explicit `apiKey` option passed to the constructor.
+ * 2. `GUNSPEC_API_KEY` environment variable.
+ * 3. `undefined` (anonymous / unauthenticated).
+ *
+ * @param config - Authentication configuration.
+ * @returns The resolved API key, or `undefined` if none is available.
+ */
+declare function resolveApiKey(config: AuthConfig): string | undefined;
+/**
+ * Build the authentication headers for a request.
+ *
+ * If an API key is available it is sent via the `X-API-Key` header.
+ * Returns an empty object when no key is available so the request proceeds
+ * in anonymous mode.
+ *
+ * @remarks
+ * The key value is **never** logged or serialised to avoid accidental
+ * credential leakage.
+ *
+ * @param apiKey - The resolved API key (may be `undefined`).
+ * @returns A header record to merge into the outgoing request.
+ */
+declare function buildAuthHeaders(apiKey: string | undefined): Record<string, string>;
+
+/**
+ * HTTP transport layer for the GunSpec SDK.
+ *
+ * Uses the native `fetch` API (available in Node 18+, Deno, Bun, Cloudflare
+ * Workers, and modern browsers) with zero external dependencies.
+ *
+ * @module
+ */
+
+/**
+ * Configuration accepted by the {@link HttpClient} constructor.
+ */
+interface HttpClientConfig {
+    /**
+     * Base URL for all API requests.
+     *
+     * Trailing slashes are stripped automatically.
+     *
+     * @defaultValue `"https://api.gunspec.io"`
+     */
+    baseUrl?: string;
+    /**
+     * Default request timeout in milliseconds.
+     *
+     * Individual requests can override this via {@link RequestConfig.timeout}.
+     *
+     * @defaultValue `30_000` (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Extra headers merged into every outgoing request.
+     *
+     * Useful for setting a custom `User-Agent` or forwarding correlation IDs.
+     */
+    headers?: Record<string, string>;
+    /** Authentication options. */
+    auth?: AuthConfig;
+    /** Retry / backoff options. */
+    retry?: RetryConfig;
+}
+/**
+ * Describes a single HTTP request to be executed by the client.
+ */
+interface RequestConfig {
+    /** HTTP method. */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /**
+     * URL path **relative to the base URL**.
+     *
+     * Must start with `/` (e.g. `/v1/firearms`).
+     */
+    path: string;
+    /**
+     * Query string parameters.
+     *
+     * - `undefined` values are silently omitted.
+     * - Arrays are serialised as repeated keys (`caliber=9mm&caliber=.45`).
+     * - Booleans are stringified (`"true"` / `"false"`).
+     */
+    query?: Record<string, string | number | boolean | string[] | undefined>;
+    /** JSON request body (automatically stringified). */
+    body?: unknown;
+    /** Per-request header overrides. */
+    headers?: Record<string, string>;
+    /**
+     * Per-request timeout in milliseconds.
+     *
+     * Overrides the client-level default.
+     */
+    timeout?: number;
+    /**
+     * An external `AbortSignal` that the caller can use to cancel the request.
+     *
+     * This signal is composed with the internal timeout signal so that either
+     * mechanism can abort the request.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Unwrapped API response for endpoints that return a single resource.
+ *
+ * The SDK strips the `{ success, data }` envelope and hoists `data` to the
+ * top level.
+ */
+interface APIResponse<T> {
+    /** The unwrapped response payload. */
+    readonly data: T;
+    /** HTTP status code. */
+    readonly status: number;
+    /** Raw response headers. */
+    readonly headers: Headers;
+    /** The `X-Request-Id` response header. */
+    readonly requestId: string;
+    /** Parsed rate limit headers. */
+    readonly rateLimit: RateLimitInfo;
+}
+/**
+ * Unwrapped API response for endpoints that return a paginated list.
+ */
+interface PaginatedResponse<T> {
+    /** Array of resource objects. */
+    readonly data: T[];
+    /** Pagination metadata returned by the server. */
+    readonly pagination: PaginationMeta;
+    /** HTTP status code. */
+    readonly status: number;
+    /** Raw response headers. */
+    readonly headers: Headers;
+    /** The `X-Request-Id` response header. */
+    readonly requestId: string;
+    /** Parsed rate limit headers. */
+    readonly rateLimit: RateLimitInfo;
+}
+/**
+ * Pagination metadata included in list responses.
+ */
+interface PaginationMeta {
+    /** Current page number (1-indexed). */
+    readonly page: number;
+    /** Maximum number of items per page. */
+    readonly limit: number;
+    /** Total number of matching items (omitted for anonymous/free tiers). */
+    readonly total?: number;
+    /** Total number of pages (omitted when `total` is omitted). */
+    readonly totalPages?: number;
+}
+/**
+ * Rate limit information parsed from response headers.
+ */
+interface RateLimitInfo {
+    /** Maximum requests allowed per window, or `null` if the header is absent. */
+    readonly limit: number | null;
+    /** Requests remaining in the current window, or `null`. */
+    readonly remaining: number | null;
+    /** Unix timestamp (seconds) when the window resets, or `null`. */
+    readonly reset: number | null;
+}
+/**
+ * Low-level HTTP client for the GunSpec API.
+ *
+ * Handles URL construction, query string serialisation, authentication
+ * headers, timeout management, response envelope unwrapping, error mapping,
+ * and automatic retries with exponential backoff.
+ *
+ * Most consumers should use the high-level `GunSpec` client class instead,
+ * which delegates to an `HttpClient` instance internally.
+ *
+ * @example
+ * ```ts
+ * const http = new HttpClient({ auth: { apiKey: process.env.GUNSPEC_API_KEY } });
+ * const res = await http.request<Firearm>({
+ *   method: 'GET',
+ *   path: '/v1/firearms/glock-g17',
+ * });
+ * console.log(res.data.name); // "Glock G17"
+ * ```
+ */
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly defaultTimeout;
+    private readonly defaultHeaders;
+    private readonly apiKey;
+    private readonly retryConfig;
+    constructor(config?: HttpClientConfig);
+    /**
+     * Execute an HTTP request and return the unwrapped response.
+     *
+     * The API's `{ success: true, data: T }` envelope is stripped so that
+     * callers receive `T` directly via {@link APIResponse.data}.
+     *
+     * @typeParam T - The expected type of the `data` field in the response.
+     * @param config - Request configuration.
+     * @returns The unwrapped API response.
+     * @throws {@link APIError} on non-2xx responses.
+     * @throws {@link ConnectionError} on network failures.
+     * @throws {@link TimeoutError} when the request exceeds the timeout.
+     */
+    request<T>(config: RequestConfig): Promise<APIResponse<T>>;
+    /**
+     * Execute an HTTP request and return a paginated response.
+     *
+     * The API's `{ success: true, data: T[], pagination }` envelope is
+     * unwrapped into a {@link PaginatedResponse}.
+     *
+     * @typeParam T - The element type of the paginated list.
+     * @param config - Request configuration.
+     * @returns The unwrapped paginated response.
+     * @throws {@link APIError} on non-2xx responses.
+     * @throws {@link ConnectionError} on network failures.
+     * @throws {@link TimeoutError} when the request exceeds the timeout.
+     */
+    requestPaginated<T>(config: RequestConfig): Promise<PaginatedResponse<T>>;
+    /**
+     * Convenience wrapper for a GET request returning a single resource.
+     */
+    get<T>(path: string, query?: Record<string, any>): Promise<APIResponse<T>>;
+    /**
+     * Convenience wrapper for a GET request returning a paginated list.
+     */
+    getPaginated<T>(path: string, query?: Record<string, any>): Promise<PaginatedResponse<T>>;
+    /**
+     * Convenience wrapper for a POST request.
+     */
+    post<T>(path: string, body?: unknown, query?: Record<string, any>): Promise<APIResponse<T>>;
+    /**
+     * Convenience wrapper for a PUT request.
+     */
+    put<T>(path: string, body?: unknown, query?: Record<string, any>): Promise<APIResponse<T>>;
+    /**
+     * Convenience wrapper for a DELETE request.
+     */
+    delete<T>(path: string, query?: Record<string, any>): Promise<APIResponse<T>>;
+    private executeRequest;
+    private executePaginatedRequest;
+    /**
+     * Perform the raw `fetch` call with merged headers, query string, timeout,
+     * and body serialisation.
+     */
+    private doFetch;
+    /**
+     * Build the full URL from base URL, path, and query parameters.
+     */
+    private buildUrl;
+    /**
+     * Parse an error response body and throw the appropriate {@link APIError}.
+     */
+    private throwAPIError;
+}
+
+/**
+ * Pagination utilities for the GunSpec SDK.
+ *
+ * Provides a {@link Page} wrapper around paginated API responses with
+ * convenience methods for navigating between pages and an async iterator
+ * for automatic consumption of all pages.
+ *
+ * @module
+ */
+
+/**
+ * A function that fetches a specific page of results.
+ *
+ * Used internally by {@link Page} to implement {@link Page.getNextPage} and
+ * the async iterator without exposing the full `HttpClient` to consumers.
+ *
+ * @typeParam T - The element type of the paginated list.
+ */
+type PageFetcher<T> = (query: Record<string, string | number | boolean | string[] | undefined>) => Promise<PaginatedResponse<T>>;
+/**
+ * A single page of results from a paginated API endpoint.
+ *
+ * Wraps the raw {@link PaginatedResponse} and adds navigation helpers:
+ *
+ * - {@link hasNextPage} — check if more pages are available.
+ * - {@link getNextPage} — fetch the next page.
+ * - `Symbol.asyncIterator` — iterate over **all** items across all pages.
+ *
+ * @typeParam T - The type of each item in the page.
+ *
+ * @example
+ * ```ts
+ * const page = await client.firearms.list({ page: 1, limit: 25 });
+ *
+ * // Manual navigation
+ * console.log(page.data);          // Firearm[]
+ * console.log(page.pagination);    // { page: 1, limit: 25, total: 400, totalPages: 16 }
+ *
+ * if (page.hasNextPage()) {
+ *   const next = await page.getNextPage();
+ * }
+ *
+ * // Automatic iteration over all items
+ * for await (const firearm of page) {
+ *   console.log(firearm.name);
+ * }
+ * ```
+ */
+declare class Page<T> {
+    /** The items on this page. */
+    readonly data: T[];
+    /** Pagination metadata returned by the server. */
+    readonly pagination: PaginationMeta;
+    /** The request ID for this page's HTTP response. */
+    readonly requestId: string;
+    /** The base query parameters used to fetch this page (without `page`). */
+    private readonly baseQuery;
+    /** The fetcher function used to retrieve subsequent pages. */
+    private readonly fetcher;
+    /**
+     * @internal
+     * Consumers should not construct `Page` instances directly.  Use the
+     * resource methods on the high-level client instead.
+     */
+    constructor(response: PaginatedResponse<T>, baseQuery: Record<string, string | number | boolean | string[] | undefined>, fetcher: PageFetcher<T>);
+    /**
+     * Whether there is a next page of results.
+     *
+     * When `totalPages` is available (pro/enterprise tiers) the check is exact.
+     * Otherwise the heuristic is: if the current page returned a full page of
+     * results (i.e. `data.length === limit`), there is likely another page.
+     */
+    hasNextPage(): boolean;
+    /**
+     * Fetch the next page of results.
+     *
+     * @returns A new {@link Page} instance for the next page.
+     * @throws {Error} If there is no next page.  Always check
+     *         {@link hasNextPage} first.
+     */
+    getNextPage(): Promise<Page<T>>;
+    /**
+     * Fetch the previous page of results.
+     *
+     * @returns A new {@link Page} instance for the previous page.
+     * @throws {Error} If this is already the first page.
+     */
+    getPreviousPage(): Promise<Page<T>>;
+    /**
+     * Async iterator that yields every item across **all** pages, starting
+     * from the current page.
+     *
+     * Fetches subsequent pages on demand (lazily) so memory usage stays
+     * constant regardless of the total result set size.
+     *
+     * @example
+     * ```ts
+     * const firstPage = await client.firearms.list({ limit: 50 });
+     * for await (const firearm of firstPage) {
+     *   // Iterates page 1, then auto-fetches page 2, 3, ... until exhausted.
+     *   console.log(firearm.name);
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+/**
+ * Create a {@link Page} from a raw paginated HTTP response.
+ *
+ * This is the primary factory used by resource classes to wrap their list
+ * endpoints.
+ *
+ * @typeParam T - The element type.
+ * @param response  - The raw paginated response from {@link HttpClient.requestPaginated}.
+ * @param baseQuery - The query parameters used for the request (the `page`
+ *                    key is managed automatically).
+ * @param fetcher   - A function that fetches a specific page given query
+ *                    parameters.
+ * @returns A new {@link Page} instance.
+ */
+declare function createPage<T>(response: PaginatedResponse<T>, baseQuery: Record<string, string | number | boolean | string[] | undefined>, fetcher: PageFetcher<T>): Page<T>;
+
+/**
+ * Error hierarchy for the GunSpec SDK.
+ *
+ * All SDK errors extend {@link GunSpecError} so consumers can catch them
+ * uniformly with a single `catch (e) { if (e instanceof GunSpecError) … }`.
+ *
+ * HTTP errors returned by the API are mapped to specific subclasses of
+ * {@link APIError} via the {@link createAPIError} factory function.
+ *
+ * @module
+ */
+/**
+ * Base error class for every error thrown by the GunSpec SDK.
+ *
+ * @remarks
+ * Restores the prototype chain so `instanceof` checks work correctly even
+ * when transpiled to ES5.
+ */
+declare class GunSpecError extends Error {
+    readonly name: string;
+    constructor(message: string);
+}
+/**
+ * An error returned by the GunSpec API with an HTTP status code.
+ *
+ * Subclasses are created for well-known status codes (401, 403, 404, …).
+ * For any other status code the base `APIError` is thrown directly.
+ */
+declare class APIError extends GunSpecError {
+    readonly name: string;
+    /** HTTP status code returned by the API. */
+    readonly status: number;
+    /** Machine-readable error code from the response body (e.g. `"NOT_FOUND"`). */
+    readonly code: string;
+    /** The `X-Request-Id` header value, useful for support requests. */
+    readonly requestId: string;
+    /** Raw response headers for further inspection. */
+    readonly headers: Headers;
+    constructor(status: number, code: string, message: string, requestId: string, headers: Headers);
+}
+/**
+ * Thrown when the API returns **401 Unauthorized**.
+ *
+ * Usually means the API key is missing, invalid, or expired.
+ */
+declare class AuthenticationError extends APIError {
+    readonly name: string;
+    constructor(code: string, message: string, requestId: string, headers: Headers);
+}
+/**
+ * Thrown when the API returns **403 Forbidden**.
+ *
+ * The API key is valid but the associated tier does not have access to the
+ * requested resource or action.
+ */
+declare class PermissionError extends APIError {
+    readonly name: string;
+    constructor(code: string, message: string, requestId: string, headers: Headers);
+}
+/**
+ * Thrown when the API returns **404 Not Found**.
+ */
+declare class NotFoundError extends APIError {
+    readonly name: string;
+    constructor(code: string, message: string, requestId: string, headers: Headers);
+}
+/**
+ * Thrown when the API returns **400 Bad Request**.
+ *
+ * Typically caused by invalid query parameters or a malformed request body.
+ */
+declare class BadRequestError extends APIError {
+    readonly name: string;
+    constructor(code: string, message: string, requestId: string, headers: Headers);
+}
+/**
+ * Thrown when the API returns **429 Too Many Requests**.
+ *
+ * The {@link retryAfter} property contains the number of seconds to wait
+ * before retrying, parsed from the `Retry-After` response header.
+ */
+declare class RateLimitError extends APIError {
+    readonly name: string;
+    /**
+     * Number of seconds the client should wait before retrying, or `null` if
+     * the server did not provide a `Retry-After` header.
+     */
+    readonly retryAfter: number | null;
+    constructor(code: string, message: string, requestId: string, headers: Headers, retryAfter: number | null);
+}
+/**
+ * Thrown when the API returns **500 Internal Server Error**.
+ */
+declare class InternalServerError extends APIError {
+    readonly name: string;
+    constructor(code: string, message: string, requestId: string, headers: Headers);
+}
+/**
+ * Thrown when a network-level failure prevents the request from completing.
+ *
+ * This covers DNS resolution errors, connection resets, and any other
+ * `TypeError` thrown by the native `fetch` implementation.
+ */
+declare class ConnectionError extends GunSpecError {
+    readonly name: string;
+    /** The original error thrown by `fetch`. */
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+/**
+ * Thrown when a request exceeds the configured timeout.
+ *
+ * The timeout is implemented via `AbortController` and fires when the
+ * elapsed time exceeds `HttpClientConfig.timeout`.
+ */
+declare class TimeoutError extends GunSpecError {
+    readonly name: string;
+    /** The timeout duration in milliseconds that was exceeded. */
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Error envelope returned by the GunSpec API on non-2xx responses.
+ */
+interface ErrorBody$1 {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+    };
+}
+/**
+ * Create the appropriate {@link APIError} subclass for the given HTTP status
+ * code and response body.
+ *
+ * @param status    - HTTP status code.
+ * @param body      - Parsed JSON body (may be `null` if the body was empty or
+ *                    unparseable).
+ * @param requestId - Value of the `X-Request-Id` response header.
+ * @param headers   - Raw response headers.
+ * @returns A concrete {@link APIError} subclass instance.
+ */
+declare function createAPIError(status: number, body: ErrorBody$1 | null, requestId: string, headers: Headers): APIError;
+
+/**
+ * A firearm specification record.
+ *
+ * The full detail shape is returned by `GET /v1/firearms/:id`.
+ * List endpoints return a subset of these fields.
+ *
+ * @example
+ * ```ts
+ * const glock: Firearm = {
+ *   id: 'glock-g17',
+ *   name: 'Glock G17',
+ *   manufacturerId: 'glock',
+ *   categoryId: 'semi-automatic-pistol',
+ *   status: 'in_production',
+ *   yearIntroduced: 1982,
+ *   countryOfOrigin: 'AT',
+ *   actionType: 'short_recoil',
+ * };
+ * ```
+ */
+interface Firearm {
+    /** URL-safe slug identifier (e.g. `"glock-g17"`). */
+    readonly id: string;
+    /** Display name of the firearm. */
+    name: string;
+    /** Slug of the manufacturer (FK to {@link Manufacturer.id}). */
+    manufacturerId: string;
+    /** Slug of the category (FK to {@link Category.id}). */
+    categoryId: string;
+    /** Slug of the parent firearm when this is a variant. */
+    parentFirearmId?: string | null;
+    /** Free-text label describing the variant relationship (e.g. `"compact"`, `"tactical"`). */
+    variantType?: string | null;
+    /** Year the firearm was first produced. */
+    yearIntroduced?: number | null;
+    /** Year production ended, if applicable. */
+    yearDiscontinued?: number | null;
+    /** Current production status. */
+    status?: 'in_production' | 'discontinued' | 'prototype' | null;
+    /** ISO 3166-1 alpha-2 country code of origin (e.g. `"US"`, `"AT"`). */
+    countryOfOrigin?: string | null;
+    /** Empty weight in grams. */
+    weightEmptyG?: number | null;
+    /** Loaded weight in grams. */
+    weightLoadedG?: number | null;
+    /** Overall length in millimetres. */
+    overallLengthMm?: number | null;
+    /** Barrel length in millimetres. */
+    barrelLengthMm?: number | null;
+    /** Height in millimetres. */
+    heightMm?: number | null;
+    /** Width in millimetres. */
+    widthMm?: number | null;
+    /** Sight radius in millimetres. */
+    sightRadiusMm?: number | null;
+    /** Folded/collapsed length in millimetres, if applicable. */
+    foldedLengthMm?: number | null;
+    /** Action type slug (e.g. `"short_recoil"`, `"gas_operated"`). */
+    actionType?: string | null;
+    /** Firing mechanism description. */
+    firingMechanism?: string | null;
+    /** Trigger type (e.g. `"single_action"`, `"double_action"`). */
+    triggerType?: string | null;
+    /** Trigger pull force in newtons. */
+    triggerPullN?: number | null;
+    /** Standard magazine capacity in rounds. */
+    magazineCapacity?: number | null;
+    /** Magazine type description. */
+    magazineType?: string | null;
+    /** Muzzle velocity in metres per second. */
+    muzzleVelocityMps?: number | null;
+    /** Muzzle energy in joules. */
+    muzzleEnergyJ?: number | null;
+    /** Effective range in metres. */
+    effectiveRangeM?: number | null;
+    /** Maximum range in metres. */
+    maxRangeM?: number | null;
+    /** Cyclic rate of fire in rounds per minute. */
+    rateOfFireRpm?: number | null;
+    /** Barrel rifling description (e.g. `"polygonal"`, `"conventional"`). */
+    barrelRifling?: string | null;
+    /** Rifling twist rate in millimetres per revolution. */
+    riflingTwistMm?: number | null;
+    /** Number of rifling grooves. */
+    numberOfGrooves?: number | null;
+    /** Frame/receiver material. */
+    frameMaterial?: string | null;
+    /** Slide material. */
+    slideMaterial?: string | null;
+    /** Barrel material. */
+    barrelMaterial?: string | null;
+    /** Stock material. */
+    stockMaterial?: string | null;
+    /** Surface finish description. */
+    finish?: string | null;
+    /** Safety mechanism descriptions. */
+    safetyMechanisms?: string | null;
+    /** Notable features. */
+    features?: string | null;
+    /** Feed system descriptions. */
+    feedSystems?: string | null;
+    /** Alternative names / designations. */
+    alternateNames?: string | null;
+    /** Available firing modes (e.g. `["semi-automatic","full-automatic"]`). */
+    firingModes?: string | null;
+    /** Conflicts this firearm was used in (JSON array of objects). */
+    conflicts?: string | null;
+    /** Production numbers (JSON object). */
+    productionNumbers?: string | null;
+    /** Sources / references (JSON array). */
+    sources?: string | null;
+    /** Game damage rating (0-100). */
+    gameDamage?: number | null;
+    /** Game accuracy rating (0-100). */
+    gameAccuracy?: number | null;
+    /** Game range rating (0-100). */
+    gameRange?: number | null;
+    /** Game fire rate rating (0-100). */
+    gameFireRate?: number | null;
+    /** Game mobility rating (0-100). */
+    gameMobility?: number | null;
+    /** Game recoil control rating (0-100). */
+    gameRecoilControl?: number | null;
+    /** Game reload speed rating (0-100). */
+    gameReloadSpeed?: number | null;
+    /** Game concealment rating (0-100). */
+    gameConcealment?: number | null;
+    /** Long-form description / history. */
+    description?: string | null;
+    /** Editorial notes. */
+    notes?: string | null;
+    /** Firearm designer(s). */
+    designer?: string | null;
+    /** Historical lore / trivia text. */
+    lore?: string | null;
+    /** Source-reported muzzle velocity in m/s. */
+    sourceMuzzleVelocityMps?: number | null;
+    /** Source-reported muzzle energy in joules. */
+    sourceMuzzleEnergyJ?: number | null;
+    /** Source-reported effective range in metres. */
+    sourceEffectiveRangeM?: number | null;
+    /** Source-reported maximum range in metres. */
+    sourceMaxRangeM?: number | null;
+    /** Ballistics data source name. */
+    ballisticsSource?: string | null;
+    /** URL for ballistics data source. */
+    ballisticsSourceUrl?: string | null;
+    /** Default ammunition load slug. */
+    defaultAmmoId?: string | null;
+    /** Whether a 3-D model is available (`0` or `1`). */
+    has3dModel?: number | null;
+    /** URL to the SVG line-art silhouette. */
+    svgLineArtUrl?: string | null;
+    /** URL to the 3-D model asset (glTF / GLB). */
+    model3dUrl?: string | null;
+    /** Confidence score for the data (0.0 - 1.0). */
+    dataConfidence?: number | null;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    readonly updatedAt: string;
+}
+/**
+ * Full firearm detail including related entities.
+ *
+ * Returned by `GET /v1/firearms/:id`.
+ */
+interface FirearmDetail extends Firearm {
+    /** The manufacturer record. */
+    manufacturer: Manufacturer | null;
+    /** The category record. */
+    category: Category | null;
+    /** Calibers this firearm chambers. */
+    calibers: FirearmCaliberEntry[];
+    /** Associated images. */
+    images: FirearmImage[];
+    /** Known military / law-enforcement users. */
+    users: FirearmUser[];
+}
+/**
+ * A caliber entry on a firearm detail, joined from the junction table.
+ */
+interface FirearmCaliberEntry {
+    /** Caliber slug. */
+    caliberId: string;
+    /** Whether this is the primary chambering (`1`) or alternate (`0`). */
+    isPrimary: number;
+    /** Caliber display name. */
+    name: string;
+    /** NATO designation, if any. */
+    natoDesignation?: string | null;
+    /** Bullet diameter in mm. */
+    bulletDiameterMm?: number | null;
+    /** Case length in mm. */
+    caseLengthMm?: number | null;
+}
+/**
+ * A firearms manufacturer.
+ *
+ * @example
+ * ```ts
+ * const glock: Manufacturer = {
+ *   id: 'glock',
+ *   name: 'Glock',
+ *   countryCode: 'AT',
+ *   foundedYear: 1963,
+ *   createdAt: '2024-01-01T00:00:00',
+ *   updatedAt: '2024-01-01T00:00:00',
+ * };
+ * ```
+ */
+interface Manufacturer {
+    /** URL-safe slug identifier. */
+    readonly id: string;
+    /** Display name. */
+    name: string;
+    /** ISO 3166-1 alpha-2 country code. */
+    countryCode?: string | null;
+    /** Year the company was founded. */
+    foundedYear?: number | null;
+    /** Company website URL. */
+    website?: string | null;
+    /** URL to the company logo. */
+    logoUrl?: string | null;
+    /** Long-form description. */
+    description?: string | null;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    readonly updatedAt: string;
+}
+/**
+ * Per-manufacturer aggregate statistics.
+ *
+ * Returned by `GET /v1/manufacturers/:id/stats`.
+ */
+interface ManufacturerStats {
+    /** The manufacturer summary. */
+    manufacturer: {
+        id: string;
+        name: string;
+    };
+    /** Aggregate statistics. */
+    stats: {
+        total_firearms: number;
+        avg_weight_g: number | null;
+        avg_range_m: number | null;
+        avg_capacity: number | null;
+        active_count: number;
+        discontinued_count: number;
+        earliest_year: number | null;
+        latest_year: number | null;
+    } | null;
+    /** Breakdown by category. */
+    categories: Array<{
+        id: string;
+        name: string;
+        count: number;
+    }>;
+    /** The most common caliber among this manufacturer's firearms. */
+    mostCommonCaliber: {
+        id: string;
+        name: string;
+        count: number;
+    } | null;
+}
+/**
+ * Manufacturer timeline grouping firearms by year introduced.
+ *
+ * Returned by `GET /v1/manufacturers/:id/timeline`.
+ */
+interface ManufacturerTimeline {
+    /** The manufacturer summary. */
+    manufacturer: {
+        id: string;
+        name: string;
+    };
+    /** Firearms grouped by year. */
+    timeline: Array<{
+        year: number | null;
+        firearms: Array<{
+            id: string;
+            name: string;
+            yearIntroduced: number | null;
+            categoryId: string;
+            status: string | null;
+        }>;
+    }>;
+}
+/**
+ * A cartridge / caliber specification.
+ *
+ * @example
+ * ```ts
+ * const nato556: Caliber = {
+ *   id: '5-56x45mm-nato',
+ *   name: '5.56x45mm NATO',
+ *   cartridgeType: 'centerfire_rifle',
+ *   bulletDiameterMm: 5.70,
+ *   createdAt: '2024-01-01T00:00:00',
+ *   updatedAt: '2024-01-01T00:00:00',
+ * };
+ * ```
+ */
+interface Caliber {
+    /** URL-safe slug identifier. */
+    readonly id: string;
+    /** Display name. */
+    name: string;
+    /** JSON array of alternative names (stored as text). */
+    aliases?: string | null;
+    /** NATO designation (e.g. `"5.56x45mm NATO"`). */
+    natoDesignation?: string | null;
+    /** Bullet diameter in millimetres. */
+    bulletDiameterMm?: number | null;
+    /** Neck diameter in millimetres. */
+    neckDiameterMm?: number | null;
+    /** Base diameter in millimetres. */
+    baseDiameterMm?: number | null;
+    /** Case length in millimetres. */
+    caseLengthMm?: number | null;
+    /** Overall cartridge length in millimetres. */
+    overallLengthMm?: number | null;
+    /** Maximum chamber pressure in megapascals. */
+    maxPressureMpa?: number | null;
+    /** Maximum chamber pressure in PSI. */
+    maxPressurePsi?: number | null;
+    /** Typical bullet weight in grams. */
+    typicalBulletWeightG?: number | null;
+    /** Typical muzzle velocity in m/s. */
+    typicalMuzzleVelocityMps?: number | null;
+    /** Typical muzzle energy in joules. */
+    typicalMuzzleEnergyJ?: number | null;
+    /** Primer type (e.g. `"Boxer"`, `"Berdan"`). */
+    primerType?: string | null;
+    /** Cartridge type (e.g. `"centerfire_rifle"`, `"rimfire"`). */
+    cartridgeType?: string | null;
+    /** Slug of the parent cartridge, if this is a derivative. */
+    parentCartridgeId?: string | null;
+    /** Year the cartridge was introduced. */
+    yearIntroduced?: number | null;
+    /** Cartridge designer. */
+    designer?: string | null;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    readonly updatedAt: string;
+}
+/**
+ * A specific ammunition load for a caliber.
+ *
+ * @example
+ * ```ts
+ * const m855: Ammunition = {
+ *   id: 'm855-62gr-fmj',
+ *   caliberId: '5-56x45mm-nato',
+ *   name: 'M855 62gr FMJ',
+ *   bulletWeightG: 4.02,
+ *   bulletType: 'FMJ',
+ *   referenceVelocityMps: 940,
+ *   referenceBarrelLengthMm: 508,
+ *   isCommon: 1,
+ *   createdAt: '2024-01-01T00:00:00',
+ *   updatedAt: '2024-01-01T00:00:00',
+ * };
+ * ```
+ */
+interface Ammunition {
+    /** URL-safe slug identifier. */
+    readonly id: string;
+    /** Caliber slug (FK to {@link Caliber.id}). */
+    caliberId: string;
+    /** Display name. */
+    name: string;
+    /** Military / NATO designation. */
+    designation?: string | null;
+    /** Ammunition manufacturer name. */
+    manufacturer?: string | null;
+    /** Country of origin ISO code. */
+    countryOfOrigin?: string | null;
+    /** Bullet weight in grams. */
+    bulletWeightG: number;
+    /** Bullet construction type (e.g. `"FMJ"`, `"JHP"`, `"AP"`). */
+    bulletType: string;
+    /** G1 ballistic coefficient (imperial). */
+    ballisticCoefficientG1?: number | null;
+    /** G7 ballistic coefficient (imperial). */
+    ballisticCoefficientG7?: number | null;
+    /** Reference muzzle velocity in m/s (measured from the reference barrel). */
+    referenceVelocityMps: number;
+    /** Barrel length in mm at which the reference velocity was measured. */
+    referenceBarrelLengthMm: number;
+    /** Exponent for velocity-vs-barrel-length power-law model. */
+    velocityRetentionExponent?: number | null;
+    /** Sectional density (lb/in^2). */
+    sectionalDensity?: number | null;
+    /** Long-form description. */
+    description?: string | null;
+    /** Year the load was introduced. */
+    yearIntroduced?: number | null;
+    /** Whether this is a common / widely-available load (`0` or `1`). */
+    isCommon: number;
+    /** Whether this is a military load (`0` or `1`). */
+    isMilitary: number;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    readonly updatedAt: string;
+}
+/**
+ * A single point along a ballistic trajectory.
+ *
+ * Computed by the ammunition ballistics engine.
+ */
+interface TrajectoryPoint {
+    /** Distance from the muzzle in metres. */
+    distanceM: number;
+    /** Velocity at this distance in m/s. */
+    velocityMps: number;
+    /** Kinetic energy at this distance in joules. */
+    energyJ: number;
+    /** Bullet drop at this distance in centimetres. */
+    dropCm: number;
+    /** Time of flight to this distance in seconds. */
+    timeOfFlightS: number;
+    /** Mach number at this distance. */
+    machNumber: number;
+    /** Momentum at this distance in kg*m/s. */
+    momentumKgMs: number;
+    /** Taylor Knock-Out factor at this distance. */
+    tkoFactor: number;
+    /** Energy density at this distance in J/cm^2. */
+    energyDensityJCm2: number;
+}
+/**
+ * Muzzle-level terminal ballistics summary.
+ */
+interface TerminalBallistics {
+    /** Taylor Knock-Out factor. */
+    tkoFactor: number;
+    /** Momentum in kg*m/s. */
+    momentumKgMs: number;
+    /** Sectional density (lb/in^2). */
+    sectionalDensity: number;
+    /** Hatcher Relative Stopping Power. */
+    hatcherRSP: number;
+    /** Energy density in J/cm^2. */
+    energyDensityJCm2: number;
+}
+/**
+ * Full ballistic profile for an ammunition load.
+ *
+ * Returned by `GET /v1/ammunition/:id/ballistics`.
+ */
+interface BallisticProfile {
+    /** Ammunition summary. */
+    ammunition: {
+        id: string;
+        name: string;
+        caliberId: string;
+    };
+    /** Barrel length used for calculations in mm. */
+    barrelLengthMm: number;
+    /** Calculated muzzle velocity in m/s. */
+    muzzleVelocityMps: number;
+    /** Calculated muzzle energy in joules. */
+    muzzleEnergyJ: number;
+    /** Calculated effective range in metres. */
+    effectiveRangeM: number;
+    /** Terminal ballistics at the muzzle. */
+    terminalBallistics: TerminalBallistics;
+    /** Trajectory drop table at specified distances. */
+    trajectory: TrajectoryPoint[];
+}
+/**
+ * Firearm ballistic calculation result.
+ *
+ * Returned by `GET /v1/firearms/:id/calculate`.
+ */
+interface FirearmCalculation {
+    /** Firearm summary. */
+    firearm: {
+        id: string;
+        name: string;
+        barrelLengthMm?: number | null;
+    };
+    /** Ammunition summary (absent when barrel length is unavailable). */
+    ammunition?: {
+        id: string;
+        name: string;
+    };
+    /** Calculated values. */
+    calculated?: {
+        muzzleVelocityMps: number;
+        muzzleEnergyJ: number;
+        terminalBallistics: TerminalBallistics;
+    };
+    /** Source-reported values from the firearm record. */
+    sourceReported?: {
+        muzzleVelocityMps: number | null;
+        muzzleEnergyJ: number | null;
+    };
+    /** Delta between calculated and source-reported values. */
+    delta?: {
+        velocityMps: number | null;
+        energyJ: number | null;
+    };
+    /** Error message when calculation cannot be performed. */
+    error?: string;
+}
+/**
+ * Firearm load profile including full trajectory.
+ *
+ * Returned by `GET /v1/firearms/:id/load`.
+ */
+interface FirearmLoadProfile {
+    /** Firearm summary. */
+    firearm: {
+        id: string;
+        name: string;
+        barrelLengthMm?: number | null;
+    };
+    /** Ammunition details (absent on error). */
+    ammunition?: {
+        id: string;
+        name: string;
+        caliberId: string;
+        bulletWeightG: number;
+        bulletType: string;
+    };
+    /** Calculated ballistic values. */
+    calculated?: {
+        muzzleVelocityMps: number;
+        muzzleEnergyJ: number;
+        effectiveRangeM: number;
+        terminalBallistics: TerminalBallistics;
+    };
+    /** Source-reported values from the firearm record. */
+    sourceReported?: {
+        muzzleVelocityMps: number | null;
+        muzzleEnergyJ: number | null;
+        effectiveRangeM: number | null;
+    };
+    /** Trajectory drop table. */
+    trajectory?: TrajectoryPoint[];
+    /** Error message when calculation cannot be performed. */
+    error?: string;
+}
+/**
+ * A firearm category (e.g. "semi-automatic-pistol", "bolt-action-rifle").
+ */
+interface Category {
+    /** URL-safe slug identifier. */
+    readonly id: string;
+    /** Display name. */
+    name: string;
+    /** Long-form description. */
+    description?: string | null;
+}
+/**
+ * An image associated with a firearm.
+ */
+interface FirearmImage {
+    /** Auto-increment integer ID. */
+    readonly id: number;
+    /** Firearm slug (FK to {@link Firearm.id}). */
+    firearmId: string;
+    /** Image URL. */
+    url: string;
+    /** Image type (e.g. `"gallery"`). */
+    type?: string | null;
+    /** Image source attribution. */
+    source?: string | null;
+    /** Image license. */
+    license?: string | null;
+}
+/**
+ * A military, law-enforcement, or other institutional user of a firearm.
+ */
+interface FirearmUser {
+    /** Auto-increment integer ID. */
+    readonly id: number;
+    /** Firearm slug (FK to {@link Firearm.id}). */
+    firearmId: string;
+    /** User / organisation name (e.g. `"U.S. Army"`). */
+    userName: string;
+    /** User type (e.g. `"military"`, `"law_enforcement"`). */
+    userType?: string | null;
+    /** ISO 3166-1 alpha-2 country code. */
+    countryCode?: string | null;
+    /** Year the firearm was adopted. */
+    adoptedYear?: number | null;
+    /** Service designation (e.g. `"M9"`, `"P226"`). */
+    designation?: string | null;
+}
+/**
+ * Extracted game statistics for a firearm (0-100 scale per stat).
+ *
+ * Used in game-related endpoints.
+ */
+interface GameStats {
+    /** Damage rating (0-100). */
+    damage: number | null;
+    /** Accuracy rating (0-100). */
+    accuracy: number | null;
+    /** Range rating (0-100). */
+    range: number | null;
+    /** Fire rate rating (0-100). */
+    fireRate: number | null;
+    /** Mobility rating (0-100). */
+    mobility: number | null;
+    /** Recoil control rating (0-100). */
+    recoilControl: number | null;
+    /** Reload speed rating (0-100). */
+    reloadSpeed: number | null;
+    /** Concealment rating (0-100). */
+    concealment: number | null;
+}
+/**
+ * Firearm game profile including archetype classification.
+ *
+ * Returned by `GET /v1/firearms/:id/game/profile`.
+ */
+interface GameProfile {
+    /** Firearm slug. */
+    id: string;
+    /** Firearm name. */
+    name: string;
+    /** Damage rating (0-100). */
+    gameDamage: number | null;
+    /** Accuracy rating (0-100). */
+    gameAccuracy: number | null;
+    /** Range rating (0-100). */
+    gameRange: number | null;
+    /** Fire rate rating (0-100). */
+    gameFireRate: number | null;
+    /** Mobility rating (0-100). */
+    gameMobility: number | null;
+    /** Recoil control rating (0-100). */
+    gameRecoilControl: number | null;
+    /** Reload speed rating (0-100). */
+    gameReloadSpeed: number | null;
+    /** Concealment rating (0-100). */
+    gameConcealment: number | null;
+    /** Computed archetype classification. */
+    archetype: string;
+    /** List of stat-based strengths. */
+    strengths: string[];
+    /** List of stat-based weaknesses. */
+    weaknesses: string[];
+}
+/**
+ * A firearm in the game meta listing.
+ *
+ * Returned by `GET /v1/firearms/:id/game/meta`.
+ */
+interface GameMetaItem {
+    /** Firearm slug. */
+    id: string;
+    /** Firearm name. */
+    name: string;
+    /** Computed archetype. */
+    archetype: string;
+    gameDamage: number | null;
+    gameAccuracy: number | null;
+    gameRange: number | null;
+    gameFireRate: number | null;
+    gameMobility: number | null;
+    gameRecoilControl: number | null;
+    gameReloadSpeed: number | null;
+    gameConcealment: number | null;
+}
+/**
+ * Balance report entry flagging statistical outliers.
+ *
+ * Returned by `GET /v1/game/balance`.
+ */
+interface BalanceEntry {
+    /** Firearm slug. */
+    firearmId: string;
+    /** Firearm name. */
+    firearmName: string;
+    /** Stat deviations that exceeded the threshold. */
+    deviations: BalanceDeviation[];
+}
+/**
+ * A single stat deviation in a balance report.
+ */
+interface BalanceDeviation {
+    /** Stat key (e.g. `"damage"`, `"accuracy"`). */
+    stat: string;
+    /** The firearm's value for this stat. */
+    value: number;
+    /** Population mean for this stat. */
+    mean: number;
+    /** Population standard deviation for this stat. */
+    stdDev: number;
+    /** Z-score (how many std devs from the mean). */
+    zScore: number;
+}
+/**
+ * Tier list grouping for a single game stat.
+ *
+ * Returned by `GET /v1/game/tier-list`.
+ */
+interface TierList {
+    /** The stat used for ranking. */
+    stat: string;
+    /** Firearms grouped into S/A/B/C/D tiers. */
+    tiers: {
+        S: TierItem[];
+        A: TierItem[];
+        B: TierItem[];
+        C: TierItem[];
+        D: TierItem[];
+    };
+}
+/**
+ * An item within a tier.
+ */
+interface TierItem {
+    /** Firearm slug. */
+    id: string;
+    /** Firearm name. */
+    name: string;
+    /** Category slug. */
+    categoryId: string | null;
+    /** Stat value. */
+    value: number;
+}
+/**
+ * Game matchup result comparing two firearms' game stats.
+ *
+ * Returned by `GET /v1/game/matchups`.
+ */
+interface MatchupResult {
+    /** Firearm A summary with stats. */
+    a: {
+        id: string;
+        name: string;
+        stats: GameStats;
+    };
+    /** Firearm B summary with stats. */
+    b: {
+        id: string;
+        name: string;
+        stats: GameStats;
+    };
+    /** Per-stat verdict: which firearm wins each category. */
+    verdicts: Record<string, 'a' | 'b' | 'draw'>;
+    /** Number of stats won by A. */
+    aWins: number;
+    /** Number of stats won by B. */
+    bWins: number;
+    /** Number of drawn stats. */
+    draws: number;
+}
+/**
+ * A firearm in a role roster.
+ *
+ * Returned by `GET /v1/game/role-roster`.
+ */
+interface RoleRosterItem {
+    /** Firearm slug. */
+    id: string;
+    /** Firearm name. */
+    name: string;
+    /** Weighted score for the requested role. */
+    roleScore: number;
+    /** Full game stats. */
+    stats: GameStats;
+}
+/**
+ * Stat distribution / histogram for a single game stat.
+ *
+ * Returned by `GET /v1/game/stat-distribution`.
+ */
+interface StatDistribution {
+    /** The stat analysed. */
+    stat: string;
+    /** Number of firearms with this stat. */
+    count: number;
+    /** Arithmetic mean. */
+    mean: number;
+    /** Median value. */
+    median: number;
+    /** Standard deviation. */
+    stdDev: number;
+    /** Minimum value. */
+    min: number;
+    /** Maximum value. */
+    max: number;
+    /** Key percentiles. */
+    percentiles: {
+        p10: number;
+        p25: number;
+        p50: number;
+        p75: number;
+        p90: number;
+    };
+    /** 10-bucket histogram (0-10, 10-20, ..., 90-100). */
+    histogram: Array<{
+        bucket: string;
+        count: number;
+    }>;
+}
+/**
+ * A versioned snapshot of game stats for all firearms.
+ *
+ * Returned by `GET /v1/game-stats/versions`.
+ */
+interface GameStatsVersion {
+    /** Auto-increment ID. */
+    readonly id: number;
+    /** Version identifier (e.g. `"1.0.0"`). */
+    version: string;
+    /** Description of the snapshot. */
+    description?: string | null;
+    /** Number of firearms in this snapshot. */
+    firearmCount: number;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+}
+/**
+ * A single entry in a game-stats snapshot.
+ */
+interface GameStatsSnapshotEntry {
+    /** Auto-increment ID. */
+    readonly id: number;
+    /** Snapshot ID. */
+    snapshotId: number;
+    /** Firearm slug. */
+    firearmId: string;
+    /** Firearm name at time of snapshot. */
+    firearmName: string;
+    gameDamage: number | null;
+    gameAccuracy: number | null;
+    gameRange: number | null;
+    gameFireRate: number | null;
+    gameMobility: number | null;
+    gameRecoilControl: number | null;
+    gameReloadSpeed: number | null;
+    gameConcealment: number | null;
+}
+/**
+ * Comparison result for multiple firearms.
+ *
+ * Returned by `GET /v1/firearms/compare`.
+ */
+interface FirearmComparison {
+    /** Full detail records for each compared firearm. */
+    items: FirearmDetail[];
+    /** Per-field deltas between the compared firearms. */
+    deltas: Record<string, unknown>;
+}
+/**
+ * Head-to-head comparison of two firearms on numeric specs.
+ *
+ * Returned by `GET /v1/firearms/head-to-head`.
+ */
+interface HeadToHead {
+    /** Firearm A raw data (snake_case keys from D1). */
+    a: Record<string, unknown>;
+    /** Firearm B raw data (snake_case keys from D1). */
+    b: Record<string, unknown>;
+    /** Per-field verdicts indicating which firearm is superior. */
+    verdicts: Record<string, {
+        /** Which firearm wins for this field. */
+        winner: 'a' | 'b' | 'draw';
+        /** Value for firearm A. */
+        a: number | null;
+        /** Value for firearm B. */
+        b: number | null;
+        /** Human-readable description of why the winner is better. */
+        better: string;
+    }>;
+}
+/**
+ * Firearm family tree (ancestors + current + descendants).
+ *
+ * Returned by `GET /v1/firearms/:id/family`.
+ */
+interface FamilyTree {
+    /** Ancestor firearms (oldest first). */
+    ancestors: Record<string, unknown>[];
+    /** The requested firearm (full record). */
+    current: Firearm;
+    /** Descendant / variant firearms. */
+    descendants: Record<string, unknown>[];
+}
+/**
+ * A similar firearm with a computed similarity score.
+ *
+ * Returned by `GET /v1/firearms/:id/similar`.
+ */
+interface SimilarFirearm {
+    /** Firearm slug. */
+    id: string;
+    /** Firearm name. */
+    name: string;
+    /** Similarity score (higher is more similar). */
+    score: number;
+}
+/**
+ * Adoption map for a firearm, grouped by country.
+ *
+ * Returned by `GET /v1/firearms/:id/adoption`.
+ */
+interface AdoptionMap {
+    /** Firearm slug. */
+    firearmId: string;
+    /** Firearm name. */
+    firearmName: string;
+    /** Users grouped by country. */
+    countries: Array<{
+        /** ISO country code (may be `null` for unknown). */
+        code: string | null;
+        /** Institutional users in this country. */
+        users: Array<{
+            name: string;
+            type: string | null;
+            year: number | null;
+            designation: string | null;
+        }>;
+    }>;
+}
+/**
+ * A firearm's computed power rating with breakdown.
+ *
+ * Returned by `GET /v1/firearms/power-rating`.
+ */
+interface PowerRating {
+    /** Firearm slug. */
+    id: string;
+    /** Firearm name. */
+    name: string;
+    /** Manufacturer slug. */
+    manufacturerId: string;
+    /** Category slug. */
+    categoryId: string;
+    /** Composite power rating (0-100 scale). */
+    powerRating: number;
+    /** Per-component breakdown of the power rating. */
+    breakdown: {
+        /** Energy component (max 30). */
+        energy: number;
+        /** Range component (max 25). */
+        range: number;
+        /** Fire rate component (max 20). */
+        fireRate: number;
+        /** Capacity component (max 15). */
+        capacity: number;
+        /** Mobility component (max 10). */
+        mobility: number;
+    };
+}
+/**
+ * Firearm dimensions in both metric and imperial units.
+ *
+ * Returned by `GET /v1/firearms/:id/dimensions`.
+ */
+interface Dimensions {
+    /** Firearm slug. */
+    id: string;
+    /** Firearm name. */
+    name: string;
+    /** Metric measurements. */
+    metric: {
+        weightEmptyG: number | null;
+        weightLoadedG: number | null;
+        overallLengthMm: number | null;
+        barrelLengthMm: number | null;
+        heightMm: number | null;
+        widthMm: number | null;
+        foldedLengthMm: number | null;
+    };
+    /** Imperial measurements (converted from metric). */
+    imperial: {
+        weightEmptyLbs: number | null;
+        weightLoadedLbs: number | null;
+        overallLengthIn: number | null;
+        barrelLengthIn: number | null;
+        heightIn: number | null;
+        widthIn: number | null;
+        foldedLengthIn: number | null;
+    };
+}
+/**
+ * Available filter dropdown options.
+ *
+ * Returned by `GET /v1/firearms/filters`.
+ */
+interface FilterOptions {
+    /** Available categories. */
+    categories: Array<{
+        slug: string;
+        name: string;
+    }>;
+    /** Available manufacturers. */
+    manufacturers: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Available calibers. */
+    calibers: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Available action types. */
+    actionTypes: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/**
+ * Database summary statistics.
+ *
+ * Returned by `GET /v1/stats/summary`.
+ */
+interface StatsSummary {
+    /** Total number of firearms. */
+    total_firearms: number;
+    /** Total number of manufacturers. */
+    total_manufacturers: number;
+    /** Total number of calibers. */
+    total_calibers: number;
+    /** Number of distinct countries of origin. */
+    countries_of_origin: number;
+    /** Average data confidence percentage. */
+    avg_confidence: number | null;
+    /** Total number of firearm variants. */
+    total_variants: number;
+}
+/**
+ * Production status breakdown.
+ *
+ * Returned by `GET /v1/stats/production-status`.
+ */
+interface ProductionStatusItem {
+    /** Status value. */
+    status: string;
+    /** Number of firearms with this status. */
+    count: number;
+}
+/**
+ * Field coverage percentage for a single field.
+ *
+ * Returned by `GET /v1/stats/field-coverage`.
+ */
+interface FieldCoverage {
+    /** Field name (snake_case column name). */
+    field: string;
+    /** Percentage of firearms with a non-null value (0-100). */
+    percentage: number;
+}
+/**
+ * Popular caliber with firearm count.
+ *
+ * Returned by `GET /v1/stats/popular-calibers`.
+ */
+interface PopularCaliber {
+    /** Caliber slug. */
+    id: string;
+    /** Caliber display name. */
+    name: string;
+    /** NATO designation. */
+    nato_designation: string | null;
+    /** Number of firearms chambered in this caliber. */
+    firearm_count: number;
+}
+/**
+ * Prolific manufacturer with firearm count.
+ *
+ * Returned by `GET /v1/stats/prolific-manufacturers`.
+ */
+interface ProlificManufacturer {
+    /** Manufacturer slug. */
+    id: string;
+    /** Manufacturer name. */
+    name: string;
+    /** Country code. */
+    country_code: string | null;
+    /** Number of firearms produced. */
+    firearm_count: number;
+}
+/**
+ * Category statistics with averages.
+ *
+ * Returned by `GET /v1/stats/by-category`.
+ */
+interface CategoryStats {
+    /** Category slug. */
+    id: string;
+    /** Category name. */
+    name: string;
+    /** Number of firearms in this category. */
+    firearm_count: number;
+    /** Average weight in grams. */
+    avg_weight_g: number | null;
+    /** Average magazine capacity. */
+    avg_magazine_capacity: number | null;
+    /** Average barrel length in mm. */
+    avg_barrel_length_mm: number | null;
+}
+/**
+ * Era (decade) statistics.
+ *
+ * Returned by `GET /v1/stats/by-era`.
+ */
+interface EraStats {
+    /** Number of firearms introduced in this decade. */
+    firearm_count: number;
+    /** Average weight in grams. */
+    avg_weight_g: number | null;
+    /** Average magazine capacity. */
+    avg_magazine_capacity: number | null;
+    /** Average barrel length in mm. */
+    avg_barrel_length_mm: number | null;
+    /** Earliest year in the decade with data. */
+    earliest_year: number | null;
+    /** Latest year in the decade with data. */
+    latest_year: number | null;
+}
+/**
+ * Material usage breakdown per component.
+ *
+ * Returned by `GET /v1/stats/materials`.
+ */
+interface MaterialStats {
+    /** Frame materials. */
+    frame: Array<{
+        material: string;
+        count: number;
+    }>;
+    /** Slide materials. */
+    slide: Array<{
+        material: string;
+        count: number;
+    }>;
+    /** Barrel materials. */
+    barrel: Array<{
+        material: string;
+        count: number;
+    }>;
+    /** Stock materials. */
+    stock: Array<{
+        material: string;
+        count: number;
+    }>;
+}
+/**
+ * Adoption record by country.
+ *
+ * Returned by `GET /v1/stats/adoption/country`.
+ */
+interface AdoptionByCountryItem {
+    /** Firearm user record ID. */
+    id: number;
+    /** User / organisation name. */
+    user_name: string;
+    /** User type. */
+    user_type: string | null;
+    /** Year adopted. */
+    adopted_year: number | null;
+    /** Service designation. */
+    designation: string | null;
+    /** Firearm slug. */
+    firearm_id: string;
+    /** Firearm name. */
+    firearm_name: string;
+}
+/**
+ * Adoption record by user type.
+ *
+ * Returned by `GET /v1/stats/adoption/type`.
+ */
+interface AdoptionByTypeItem {
+    /** Firearm slug. */
+    firearm_id: string;
+    /** Firearm name. */
+    firearm_name: string;
+    /** Number of countries that adopted this firearm for this role. */
+    adoption_count: number;
+    /** List of country codes. */
+    countries: string[];
+}
+/**
+ * Action type frequency.
+ *
+ * Returned by `GET /v1/stats/action-types`.
+ */
+interface ActionTypeStats {
+    /** Action type slug. */
+    action_type: string;
+    /** Number of firearms with this action type. */
+    count: number;
+}
+/**
+ * Feature frequency item.
+ *
+ * Returned by `GET /v1/stats/feature-frequency`.
+ */
+interface FeatureFrequency {
+    /** Feature name. */
+    feature: string;
+    /** Number of firearms with this feature. */
+    count: number;
+}
+/**
+ * Caliber popularity within a decade.
+ *
+ * Returned by `GET /v1/stats/caliber-popularity-by-era`.
+ */
+interface CaliberPopularityByEra {
+    /** Decade label (e.g. `"1990s"`). */
+    decade: string;
+    /** Calibers ranked by popularity within this decade. */
+    calibers: Array<{
+        caliberId: string;
+        caliberName: string;
+        firearmCount: number;
+    }>;
+}
+/**
+ * A country with its firearm count.
+ *
+ * Returned by `GET /v1/countries`.
+ */
+interface Country {
+    /** ISO 3166-1 alpha-2 country code. */
+    code: string;
+    /** Number of firearms originating from this country. */
+    firearmCount: number;
+}
+/**
+ * A conflict with associated firearms.
+ *
+ * Returned by `GET /v1/conflicts`.
+ */
+interface Conflict {
+    /** Conflict name. */
+    name: string;
+    /** Number of firearms used in this conflict. */
+    firearmCount: number;
+    /** Firearms used in this conflict. */
+    firearms: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+/**
+ * Data coverage summary.
+ *
+ * Returned by `GET /v1/data/coverage`.
+ */
+interface DataCoverage {
+    /** Field name. */
+    field: string;
+    /** Percentage of records with non-null values (0-100). */
+    percentage: number;
+}
+/**
+ * A firearm record with its computed data confidence score.
+ *
+ * Returned by the data quality confidence endpoint.
+ */
+interface ConfidenceEntry {
+    /** Firearm slug. */
+    slug: string;
+    /** Firearm display name. */
+    name: string;
+    /** Confidence score (0-1). */
+    confidenceScore: number;
+    /** Number of non-null specification fields. */
+    filledFields: number;
+    /** Total number of specification fields. */
+    totalFields: number;
+}
+/**
+ * A country's firearm arsenal — military and law enforcement holdings.
+ */
+interface CountryArsenal {
+    /** The country record. */
+    country: Country;
+    /** Total number of adopted firearms. */
+    totalFirearms: number;
+    /** Firearms grouped by usage type. */
+    groups: {
+        /** Usage type (e.g. "military", "law_enforcement"). */
+        type: string;
+        /** Firearms in this usage group. */
+        firearms: Firearm[];
+    }[];
+}
+/**
+ * Ballistics data for a caliber at a given distance.
+ */
+interface BallisticsResult {
+    /** Caliber slug or ID. */
+    caliberId: string;
+    /** Distance in meters. */
+    distanceM: number;
+    /** Bullet velocity at the given distance (fps). */
+    velocityFps: number;
+    /** Bullet energy at the given distance (ft-lbs). */
+    energyFtLbs: number;
+    /** Bullet drop at the given distance (inches). */
+    dropInches: number;
+    /** Wind drift at the given distance (inches). */
+    driftInches?: number;
+    /** Time of flight in seconds. */
+    timeOfFlightS?: number;
+}
+/**
+ * SVG silhouette data for a firearm.
+ */
+interface Silhouette {
+    /** The firearm slug. */
+    slug: string;
+    /** Raw SVG string (when format is "svg"). */
+    svg?: string;
+    /** Base64 data URI (when format is "datauri"). */
+    dataUri?: string;
+    /** Stroke width used. */
+    strokeWidth?: number;
+    /** Stroke color used. */
+    strokeColor?: string;
+    /** Original image width in pixels. */
+    width?: number;
+    /** Original image height in pixels. */
+    height?: number;
+}
+/**
+ * Game balance report identifying outlier firearms.
+ */
+interface BalanceReport {
+    /** Threshold percentage used for outlier detection. */
+    threshold: number;
+    /** Total firearms analyzed. */
+    totalAnalyzed: number;
+    /** Firearms flagged as overpowered. */
+    overpowered: BalanceEntry[];
+    /** Firearms flagged as underpowered. */
+    underpowered: BalanceEntry[];
+    /** Deviations by stat. */
+    deviations?: BalanceDeviation[];
+}
+/**
+ * A roster of firearms suited for a specific game role.
+ */
+interface RoleRoster {
+    /** The role that was queried. */
+    role: string;
+    /** Total firearms considered. */
+    totalConsidered: number;
+    /** Firearms ranked by suitability for the role. */
+    firearms: RoleRosterItem[];
+}
+/**
+ * A user's favorited firearm.
+ *
+ * Returned by `GET /v1/me/favorites`.
+ */
+interface Favorite {
+    /** Firearm slug. */
+    firearmId: string;
+    /** ISO-8601 timestamp when the favorite was added. */
+    createdAt: string;
+}
+/**
+ * Result of toggling a favorite.
+ *
+ * Returned by `POST /v1/me/favorites/:firearmId` and `DELETE /v1/me/favorites/:firearmId`.
+ */
+interface FavoriteToggle {
+    /** Firearm slug. */
+    firearmId: string;
+    /** Whether the firearm is now favorited. */
+    favorited: boolean;
+}
+/**
+ * A user-submitted data quality report.
+ *
+ * Returned by `GET /v1/me/reports` and `POST /v1/me/reports`.
+ */
+interface DataReport {
+    /** Unique report ID. */
+    readonly id: string;
+    /** Firearm slug the report pertains to. */
+    firearmId: string;
+    /** Section of the firearm page (e.g. `"specs"`, `"game-stats"`). */
+    section: string;
+    /** Type of issue reported. */
+    issueType: 'incorrect' | 'missing' | 'outdated';
+    /** User-provided description of the issue. */
+    description: string;
+    /** Optional reference URLs supporting the report. */
+    references?: string[];
+    /** Optional suggested correction. */
+    suggestedValue?: string;
+    /** Current review status. */
+    status: 'pending' | 'reviewed' | 'resolved' | 'dismissed';
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    readonly updatedAt: string;
+}
+/**
+ * A support ticket summary.
+ *
+ * Returned by `GET /v1/me/support`.
+ */
+interface SupportTicket {
+    /** Unique ticket ID. */
+    readonly id: string;
+    /** Ticket subject line. */
+    subject: string;
+    /** Ticket description / body. */
+    description: string;
+    /** Ticket category. */
+    category?: 'billing' | 'technical' | 'data_quality' | 'feature_request' | 'other';
+    /** Priority level. */
+    priority: 'low' | 'normal' | 'high' | 'urgent';
+    /** Current status. */
+    status: 'open' | 'in_progress' | 'waiting' | 'resolved' | 'closed';
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    readonly updatedAt: string;
+}
+/**
+ * A support ticket with its reply thread.
+ *
+ * Returned by `GET /v1/me/support/:ticketId`.
+ */
+interface SupportTicketDetail extends SupportTicket {
+    /** Reply thread ordered chronologically. */
+    replies: SupportTicketReply[];
+}
+/**
+ * A single reply in a support ticket thread.
+ */
+interface SupportTicketReply {
+    /** Auto-increment reply ID. */
+    readonly id: number;
+    /** Parent ticket ID. */
+    ticketId: string;
+    /** Reply message body. */
+    message: string;
+    /** Whether this reply was from staff. */
+    isStaff: boolean;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+}
+/**
+ * A webhook endpoint configuration.
+ *
+ * Returned by `GET /v1/me/webhooks` and related endpoints.
+ */
+interface WebhookEndpoint {
+    /** Unique endpoint ID. */
+    readonly id: string;
+    /** Delivery URL. */
+    url: string;
+    /** Optional human-readable description. */
+    description?: string | null;
+    /** Event types this endpoint subscribes to. */
+    events: string[];
+    /** Whether the endpoint is active. */
+    active: boolean;
+    /** HMAC signing secret for verifying payloads. */
+    secret: string;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    readonly updatedAt: string;
+}
+/**
+ * Result of sending a test event to a webhook endpoint.
+ *
+ * Returned by `POST /v1/me/webhooks/:id/test`.
+ */
+interface WebhookTestResult {
+    /** Whether the test delivery was successful. */
+    success: boolean;
+    /** HTTP status code returned by the endpoint. */
+    statusCode: number;
+    /** Round-trip delivery time in milliseconds. */
+    responseTimeMs: number;
+    /** Error message if delivery failed. */
+    error?: string;
+}
+/**
+ * API usage statistics for the authenticated user.
+ *
+ * Returned by `GET /v1/me/usage`.
+ */
+interface UsageStats {
+    /** Current billing month usage. */
+    currentMonth: {
+        /** Requests used this month. */
+        used: number;
+        /** Monthly request limit. */
+        limit: number;
+        /** Usage as a percentage (0-100). */
+        percentage: number;
+        /** ISO-8601 timestamp when usage resets. */
+        resetsAt: string;
+    };
+    /** Daily request counts for the requested period. */
+    dailyBreakdown: Array<{
+        date: string;
+        count: number;
+    }>;
+    /** Per-API-key usage breakdown. */
+    perKey: Array<{
+        keyId: string;
+        keyName: string;
+        count: number;
+    }>;
+    /** Total number of API keys. */
+    keyCount: number;
+    /** Current subscription tier details. */
+    tier: {
+        /** Tier display name. */
+        name: string;
+        /** Monthly request allowance. */
+        requestsPerMonth: number;
+        /** Requests per minute limit. */
+        rateLimit: number;
+    };
+}
+
+/**
+ * Common pagination parameters accepted by all list endpoints.
+ *
+ * @example
+ * ```ts
+ * const params: PaginationParams = { page: 2, per_page: 50, order: 'desc' };
+ * ```
+ */
+interface PaginationParams {
+    /**
+     * Page number (1-based).
+     * @defaultValue `1`
+     */
+    page?: number;
+    /**
+     * Number of items per page (1-100).
+     * @defaultValue `20`
+     */
+    per_page?: number;
+    /** Column to sort by. Allowed values depend on the endpoint. */
+    sort?: string;
+    /**
+     * Sort direction.
+     * @defaultValue `"asc"`
+     */
+    order?: 'asc' | 'desc';
+}
+/**
+ * Parameters for `GET /v1/firearms`.
+ *
+ * @example
+ * ```ts
+ * const params: ListFirearmsParams = {
+ *   manufacturer: 'glock',
+ *   category: 'semi-automatic-pistol',
+ *   sort: 'name',
+ *   page: 1,
+ *   per_page: 20,
+ * };
+ * ```
+ */
+interface ListFirearmsParams extends PaginationParams {
+    /** Filter by manufacturer slug. */
+    manufacturer?: string;
+    /** Filter by caliber slug (matched via junction table). */
+    caliber?: string;
+    /** Filter by category slug. */
+    category?: string;
+    /** Filter by action type slug. */
+    action_type?: string;
+    /** Filter by country of origin ISO code. */
+    country_of_origin?: string;
+    /** Minimum year introduced (inclusive). */
+    year_introduced_min?: number;
+    /** Maximum year introduced (inclusive). */
+    year_introduced_max?: number;
+    /** Minimum empty weight in grams. */
+    weight_min?: number;
+    /** Maximum empty weight in grams. */
+    weight_max?: number;
+    /** Minimum barrel length in mm. */
+    barrel_length_min?: number;
+    /** Filter by production status. */
+    status?: 'in_production' | 'discontinued' | 'prototype';
+    /** Filter for firearms with/without a 3-D model. */
+    has_3d_model?: 'true' | 'false';
+    /** Comma-separated list of fields to include in the response (sparse fieldset). */
+    fields?: string;
+    /**
+     * Sort column.
+     * @defaultValue `"name"`
+     */
+    sort?: 'name' | 'weight' | 'year' | 'caliber' | 'created_at' | 'favorites';
+}
+/**
+ * Parameters for `GET /v1/firearms/search`.
+ */
+interface SearchFirearmsParams extends PaginationParams {
+    /** Full-text search query (1-200 characters). */
+    q: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/compare`.
+ */
+interface CompareFirearmsParams {
+    /**
+     * Comma-separated firearm slugs to compare (maximum 5).
+     *
+     * @example `"glock-g17,beretta-92fs,sig-sauer-p226"`
+     */
+    ids: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/:id/game/meta`.
+ */
+interface GameMetaParams {
+    /** Filter by computed archetype. */
+    archetype?: 'sniper' | 'assault' | 'tank' | 'glass-cannon' | 'all-rounder' | 'support' | 'stealth' | 'speedster';
+}
+/**
+ * Parameters for `GET /v1/firearms/random`.
+ */
+interface RandomFirearmParams {
+    /** Filter by category slug. */
+    category?: string;
+    /** Filter by country of origin ISO code. */
+    country?: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/top`.
+ *
+ * @example
+ * ```ts
+ * const params: TopFirearmsParams = { stat: 'lightest', category: 'semi-automatic-pistol', limit: 5 };
+ * ```
+ */
+interface TopFirearmsParams {
+    /** The stat to rank by. */
+    stat: 'lightest' | 'heaviest' | 'longest-range' | 'highest-rof' | 'most-compact' | 'highest-capacity' | 'most-powerful';
+    /** Filter by category slug. */
+    category?: string;
+    /**
+     * Maximum number of results (1-25).
+     * @defaultValue `10`
+     */
+    limit?: number;
+}
+/**
+ * Parameters for `GET /v1/firearms/head-to-head`.
+ */
+interface HeadToHeadParams {
+    /** Slug of firearm A. */
+    a: string;
+    /** Slug of firearm B. */
+    b: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/by-feature`.
+ */
+interface ByFeatureParams extends PaginationParams {
+    /** Feature name to search for (matched via JSON LIKE). */
+    feature: string;
+    /** Optional category filter. */
+    category?: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/by-action`.
+ */
+interface ByActionParams extends PaginationParams {
+    /** Action type to filter by (exact match). */
+    action: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/by-material`.
+ */
+interface ByMaterialParams extends PaginationParams {
+    /** Material name to search for (substring match). */
+    material: string;
+    /** Which firearm component to search. */
+    component: 'frame' | 'barrel' | 'stock' | 'slide';
+}
+/**
+ * Parameters for `GET /v1/firearms/by-designer`.
+ */
+interface ByDesignerParams extends PaginationParams {
+    /** Designer name to search for (substring match). */
+    designer: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/power-rating`.
+ */
+interface PowerRatingParams extends PaginationParams {
+    /** Optional category filter. */
+    category?: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/timeline`.
+ */
+interface TimelineParams {
+    /**
+     * Page number (1-based).
+     * @defaultValue `1`
+     */
+    page?: number;
+    /**
+     * Items per page (1-100).
+     * @defaultValue `50`
+     */
+    per_page?: number;
+    /** Sort column. */
+    sort?: string;
+    /**
+     * Sort direction.
+     * @defaultValue `"asc"`
+     */
+    order?: 'asc' | 'desc';
+    /** Earliest year to include (inclusive). */
+    from?: number;
+    /** Latest year to include (inclusive). */
+    to?: number;
+    /** Optional category filter. */
+    category?: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/by-conflict`.
+ */
+interface ByConflictParams extends PaginationParams {
+    /** Conflict name to search for (substring match). */
+    conflict: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/:id/calculate`.
+ */
+interface CalculateBallisticsParams {
+    /** Ammunition slug to calculate with. */
+    ammo_id: string;
+}
+/**
+ * Parameters for `GET /v1/firearms/:id/load`.
+ */
+interface LoadFirearmParams {
+    /**
+     * Ammunition slug.
+     * If omitted, uses the firearm's default ammo or the most common ammo
+     * for the primary caliber.
+     */
+    ammo_id?: string;
+}
+/**
+ * Parameters for `GET /v1/manufacturers`.
+ */
+interface ListManufacturersParams extends PaginationParams {
+    /** Filter by country ISO code. */
+    country?: string;
+}
+/**
+ * Parameters for `GET /v1/calibers`.
+ */
+interface ListCalibersParams extends PaginationParams {
+    /** Filter by cartridge type (e.g. `"centerfire_rifle"`). */
+    cartridge_type?: string;
+    /** Filter by primer type (e.g. `"Boxer"`). */
+    primer_type?: string;
+}
+/**
+ * Parameters for `GET /v1/calibers/compare`.
+ */
+interface CompareCalibersParams {
+    /**
+     * Comma-separated caliber slugs to compare (maximum 5).
+     *
+     * @example `"9x19mm-parabellum,45-acp,40-s-w"`
+     */
+    ids: string;
+}
+/**
+ * Parameters for `GET /v1/calibers/:id/ballistics`.
+ */
+interface CaliberBallisticsParams {
+    /**
+     * Distance in metres for the ballistic calculation (1-5000).
+     * @defaultValue `100`
+     */
+    distance?: number;
+}
+/**
+ * Parameters for `GET /v1/ammunition`.
+ */
+interface ListAmmunitionParams extends PaginationParams {
+    /** Filter by caliber slug. */
+    caliber_id?: string;
+    /** Filter by bullet type (e.g. `"FMJ"`, `"JHP"`). */
+    bullet_type?: string;
+    /** Filter by common status (`0` = uncommon, `1` = common). */
+    is_common?: 0 | 1;
+}
+/**
+ * Parameters for `GET /v1/ammunition/:id/ballistics`.
+ */
+interface AmmunitionBallisticsParams {
+    /**
+     * Barrel length in mm to use for the calculation (50-2000).
+     * If omitted, uses the ammunition's reference barrel length.
+     */
+    barrel_length_mm?: number;
+    /**
+     * Comma-separated distances in metres for the trajectory table.
+     * If omitted, uses the default set: 0, 50, 100, 200, 300, 400, 500, 600, 800, 1000.
+     *
+     * @example `"0,100,200,300,500"`
+     */
+    distances?: string;
+}
+/**
+ * Parameters for `GET /v1/stats/popular-calibers`.
+ */
+interface PopularCalibersParams {
+    /**
+     * Maximum number of results (1-100).
+     * @defaultValue `20`
+     */
+    limit?: number;
+}
+/**
+ * Parameters for `GET /v1/stats/prolific-manufacturers`.
+ */
+interface ProlificManufacturersParams {
+    /**
+     * Maximum number of results (1-100).
+     * @defaultValue `20`
+     */
+    limit?: number;
+    /** Optional category filter. */
+    category?: string;
+}
+/**
+ * Parameters for `GET /v1/stats/by-era`.
+ *
+ * @example
+ * ```ts
+ * const params: ByEraParams = { decade: '1990s' };
+ * ```
+ */
+interface ByEraParams {
+    /** Decade string in format `"1990s"`, `"2000s"`, etc. */
+    decade: string;
+}
+/**
+ * Parameters for `GET /v1/stats/adoption/country`.
+ */
+interface AdoptionByCountryParams {
+    /** ISO 3166-1 country code. */
+    code: string;
+}
+/**
+ * Parameters for `GET /v1/stats/adoption/type`.
+ */
+interface AdoptionByTypeParams {
+    /** User type to query. */
+    type: 'military' | 'law_enforcement' | 'civilian' | 'paramilitary' | 'special_forces' | 'private_security' | 'training';
+}
+/**
+ * Parameters for `GET /v1/stats/action-types`.
+ */
+interface ActionTypesParams {
+    /** Optional category filter. */
+    category?: string;
+}
+/**
+ * Parameters for `GET /v1/stats/feature-frequency`.
+ */
+interface FeatureFrequencyParams {
+    /** Optional category filter. */
+    category?: string;
+    /**
+     * Maximum number of results (1-100).
+     * @defaultValue `50`
+     */
+    limit?: number;
+}
+/**
+ * Parameters for `GET /v1/stats/caliber-popularity-by-era`.
+ */
+interface CaliberPopularityByEraParams {
+    /** Starting decade (inclusive, e.g. `"1950s"`). */
+    from_decade?: string;
+    /** Ending decade (inclusive, e.g. `"2020s"`). */
+    to_decade?: string;
+}
+/**
+ * Parameters for `GET /v1/game/balance`.
+ */
+interface BalanceReportParams {
+    /**
+     * Z-score threshold for flagging outliers (0-100).
+     * @defaultValue `20`
+     */
+    threshold?: number;
+}
+/**
+ * Parameters for `GET /v1/game/tier-list`.
+ */
+interface TierListParams {
+    /** Optional category filter. */
+    category?: string;
+    /**
+     * Stat to rank by.
+     * @defaultValue `"damage"`
+     */
+    stat?: 'damage' | 'accuracy' | 'range' | 'fireRate' | 'mobility' | 'recoilControl' | 'reloadSpeed' | 'concealment';
+}
+/**
+ * Parameters for `GET /v1/game/matchups`.
+ */
+interface MatchupsParams {
+    /** Slug of firearm A. */
+    a: string;
+    /** Slug of firearm B. */
+    b: string;
+}
+/**
+ * Parameters for `GET /v1/game/role-roster`.
+ */
+interface RoleRosterParams {
+    /** The role to build a roster for. */
+    role: 'sniper' | 'assault' | 'tank' | 'support' | 'stealth' | 'speedster';
+    /**
+     * Number of firearms to return (1-25).
+     * @defaultValue `5`
+     */
+    count?: number;
+}
+/**
+ * Parameters for `GET /v1/game/stat-distribution`.
+ */
+interface StatDistributionParams {
+    /** The game stat to analyse. */
+    stat: 'damage' | 'accuracy' | 'range' | 'fireRate' | 'mobility' | 'recoilControl' | 'reloadSpeed' | 'concealment';
+}
+/**
+ * Parameters for `GET /v1/game-stats/:version/firearms`.
+ */
+interface ListSnapshotFirearmsParams extends PaginationParams {
+}
+/**
+ * Parameters for `GET /v1/data/confidence`.
+ */
+interface ConfidenceParams extends PaginationParams {
+    /**
+     * Return firearms with confidence below this threshold (0.0-1.0).
+     * @defaultValue `0.5`
+     */
+    below?: number;
+}
+/**
+ * Parameters for `GET /v1/firearms/:id/silhouette`.
+ */
+interface SilhouetteParams {
+    /** Output format: `"svg"` (raw), `"datauri"` (base64), or `"json"` (metadata). */
+    format?: 'svg' | 'datauri' | 'json';
+    /** Stroke width in pixels. */
+    stroke_width?: number;
+    /** Stroke color (CSS color string). */
+    stroke_color?: string;
+}
+/**
+ * Parameters for `GET /v1/me/favorites`.
+ */
+interface ListFavoritesParams {
+    /** Page number (1-based). */
+    page?: number;
+    /** Items per page (1-100). */
+    limit?: number;
+}
+/**
+ * Body for `POST /v1/me/reports`.
+ */
+interface CreateReportParams {
+    /** Firearm slug to report on. */
+    firearmId: string;
+    /** Section of the firearm data. */
+    section: 'game-stats' | 'specs' | 'ballistics' | 'barrel' | 'materials' | 'operating' | 'calibers' | 'users' | 'description';
+    /** Type of data issue. */
+    issueType: 'incorrect' | 'missing' | 'outdated';
+    /** Description of the issue (10-2000 chars). */
+    description: string;
+    /** Optional reference URLs (max 5). */
+    references?: string[];
+    /** Optional suggested correction (max 1000 chars). */
+    suggestedValue?: string;
+}
+/**
+ * Parameters for `GET /v1/me/reports`.
+ */
+interface ListReportsParams {
+    /** Page number (1-based). */
+    page?: number;
+    /** Items per page (1-100). */
+    per_page?: number;
+}
+/**
+ * Body for `POST /v1/me/support`.
+ */
+interface CreateTicketParams {
+    /** Ticket subject (1-200 chars). */
+    subject: string;
+    /** Ticket description (1-5000 chars). */
+    description: string;
+    /** Ticket category. */
+    category?: 'billing' | 'technical' | 'data_quality' | 'feature_request' | 'other';
+    /** Priority level. */
+    priority?: 'low' | 'normal' | 'high' | 'urgent';
+}
+/**
+ * Parameters for `GET /v1/me/support`.
+ */
+interface ListTicketsParams {
+    /** Page number (1-based). */
+    page?: number;
+    /** Items per page (1-100). */
+    per_page?: number;
+    /** Filter by status. */
+    status?: 'open' | 'in_progress' | 'waiting' | 'resolved' | 'closed';
+    /** Sort column. */
+    sort?: 'created_at' | 'updated_at' | 'status' | 'priority';
+    /** Sort direction. */
+    order?: 'asc' | 'desc';
+}
+/**
+ * Body for `POST /v1/me/support/:ticketId/replies`.
+ */
+interface CreateReplyParams {
+    /** Reply message (1-5000 chars). */
+    message: string;
+}
+/**
+ * Body for `POST /v1/me/webhooks`.
+ */
+interface CreateWebhookEndpointParams {
+    /** Delivery URL. */
+    url: string;
+    /** Optional description. */
+    description?: string;
+    /** Event types to subscribe to (at least one). */
+    events: string[];
+}
+/**
+ * Body for `PUT /v1/me/webhooks/:id`.
+ */
+interface UpdateWebhookEndpointParams {
+    /** New delivery URL. */
+    url?: string;
+    /** Updated description. */
+    description?: string | null;
+    /** Updated event subscriptions. */
+    events?: string[];
+    /** Whether the endpoint is active. */
+    active?: boolean;
+}
+/**
+ * Parameters for `GET /v1/me/webhooks`.
+ */
+interface ListWebhookEndpointsParams {
+    /** Page number (1-based). */
+    page?: number;
+    /** Items per page (1-100). */
+    per_page?: number;
+}
+/**
+ * Parameters for `GET /v1/me/usage`.
+ */
+interface UsageParams {
+    /** Month in YYYY-MM format. */
+    month?: string;
+    /** Number of days for daily breakdown (1-90). */
+    days?: number;
+}
+
+/**
+ * The error object nested inside an {@link APIErrorResponse}.
+ *
+ * @example
+ * ```ts
+ * const body: ErrorBody = {
+ *   code: 'NOT_FOUND',
+ *   message: "Firearm 'nonexistent-slug' not found",
+ * };
+ * ```
+ */
+interface ErrorBody {
+    /**
+     * Machine-readable error code.
+     *
+     * Known codes:
+     * - `"NOT_FOUND"` -- Resource does not exist (HTTP 404).
+     * - `"UNAUTHORIZED"` -- Authentication required (HTTP 401).
+     * - `"FORBIDDEN"` -- Insufficient permissions (HTTP 403).
+     * - `"RATE_LIMITED"` -- Too many requests (HTTP 429).
+     * - `"VALIDATION_ERROR"` -- Request parameters failed validation (HTTP 400).
+     */
+    code: string;
+    /** Human-readable error message. */
+    message: string;
+    /**
+     * Optional validation details.
+     *
+     * Present on `VALIDATION_ERROR` responses; shape varies by endpoint.
+     */
+    details?: Record<string, unknown>;
+}
+/**
+ * Standard API error response envelope.
+ *
+ * All non-2xx responses from the GunSpec.io API return this shape.
+ *
+ * @example
+ * ```ts
+ * // 404 response body
+ * const response: APIErrorResponse = {
+ *   success: false,
+ *   error: {
+ *     code: 'NOT_FOUND',
+ *     message: "Firearm 'nonexistent-slug' not found",
+ *   },
+ * };
+ * ```
+ */
+interface APIErrorResponse {
+    /** Always `false` for error responses. */
+    success: false;
+    /** The error details. */
+    error: ErrorBody;
+}
+
+/**
+ * Firearms resource for the GunSpec SDK.
+ *
+ * Provides access to all `/v1/firearms` endpoints including listing,
+ * searching, comparing, filtering, and retrieving individual firearm
+ * details with sub-resources (images, variants, game stats, etc.).
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Firearms API.
+ *
+ * Wraps all `/v1/firearms` endpoints. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.firearms`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * // List firearms with filters
+ * const { data, pagination } = await client.firearms.list({
+ *   manufacturer: 'glock',
+ *   category: 'pistol',
+ *   per_page: 10,
+ * });
+ *
+ * // Get a single firearm by slug
+ * const { data: firearm } = await client.firearms.get('glock-g17');
+ * ```
+ */
+declare class FirearmsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * List firearms with optional filters and pagination.
+     *
+     * @param params - Optional query parameters for filtering, sorting, and pagination.
+     * @returns A paginated list of firearms matching the given filters.
+     * @throws {BadRequestError} If any filter value is invalid.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firearms.list({
+     *   manufacturer: 'beretta',
+     *   status: 'in_production',
+     *   sort: 'name',
+     *   order: 'asc',
+     *   page: 1,
+     *   per_page: 25,
+     * });
+     * console.log(result.data); // Firearm[]
+     * console.log(result.pagination.totalPages);
+     * ```
+     */
+    list(params?: ListFirearmsParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Auto-paginate through all firearms matching the given filters.
+     *
+     * Returns an async iterator that fetches pages on demand, yielding
+     * individual {@link Firearm} objects. Useful for processing large
+     * result sets without managing pagination manually.
+     *
+     * @param params - Optional query parameters for filtering and sorting.
+     * @returns An async iterable iterator yielding individual firearms.
+     *
+     * @example
+     * ```typescript
+     * for await (const firearm of client.firearms.listAutoPaging({ manufacturer: 'colt' })) {
+     *   console.log(firearm.name);
+     * }
+     * ```
+     */
+    listAutoPaging(params?: ListFirearmsParams): AsyncIterableIterator<Firearm>;
+    /**
+     * Full-text search across firearms.
+     *
+     * @param params - Search query and pagination parameters.
+     * @returns A paginated list of firearms matching the search query.
+     * @throws {BadRequestError} If the search query is empty or too long.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firearms.search({ q: '9mm compact' });
+     * console.log(result.data.length);
+     * ```
+     */
+    search(params: SearchFirearmsParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Compare up to 5 firearms side by side.
+     *
+     * @param params - Object containing comma-separated firearm IDs.
+     * @returns An array of firearms with full details for comparison.
+     * @throws {BadRequestError} If more than 5 IDs are provided or any ID is invalid.
+     * @throws {NotFoundError} If any of the specified firearms do not exist.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.compare({ ids: 'glock-g17,sig-sauer-p320,beretta-92fs' });
+     * console.log(data.items.length); // 3
+     * ```
+     */
+    compare(params: CompareFirearmsParams): Promise<APIResponse<FirearmComparison>>;
+    /**
+     * Retrieve game metadata for firearms (archetypes, stat ranges, etc.).
+     *
+     * @param params - Optional archetype filter.
+     * @returns Game metadata including archetype definitions and stat ranges.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.gameMeta({ archetype: 'sniper' });
+     * ```
+     */
+    gameMeta(params?: GameMetaParams): Promise<APIResponse<GameMetaItem[]>>;
+    /**
+     * List all known action types across the database.
+     *
+     * @returns An array of distinct action type strings.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.actionTypes();
+     * // ['Semi-automatic', 'Bolt action', 'Lever action', ...]
+     * ```
+     */
+    actionTypes(): Promise<APIResponse<ActionTypeStats[]>>;
+    /**
+     * Get available filter options for the firearms list endpoint.
+     *
+     * Returns distinct values for manufacturers, calibers, categories,
+     * action types, countries, and statuses that can be used as filter values.
+     *
+     * @returns An object mapping filter fields to their available values.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.filterOptions();
+     * console.log(data.manufacturers); // ['beretta', 'colt', ...]
+     * console.log(data.categories);    // ['pistol', 'rifle', ...]
+     * ```
+     */
+    filterOptions(): Promise<APIResponse<FilterOptions>>;
+    /**
+     * Get a random firearm, optionally filtered by category or country.
+     *
+     * @param params - Optional category and country filters.
+     * @returns A single randomly selected firearm.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.random({ category: 'pistol' });
+     * console.log(data.name);
+     * ```
+     */
+    random(params?: RandomFirearmParams): Promise<APIResponse<Firearm>>;
+    /**
+     * Get top firearms ranked by a specific statistic.
+     *
+     * @param params - The stat to rank by and optional category/limit filters.
+     * @returns An ordered array of firearms ranked by the specified stat.
+     * @throws {BadRequestError} If the stat value is not a recognized ranking metric.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.top({
+     *   stat: 'lightest',
+     *   category: 'pistol',
+     *   limit: 5,
+     * });
+     * ```
+     */
+    top(params: TopFirearmsParams): Promise<APIResponse<Firearm[]>>;
+    /**
+     * Compare two firearms in a head-to-head matchup.
+     *
+     * @param params - The slugs of the two firearms to compare.
+     * @returns A detailed head-to-head comparison with per-stat breakdowns.
+     * @throws {NotFoundError} If either firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.headToHead({ a: 'glock-g17', b: 'sig-sauer-p320' });
+     * console.log(data.winner);
+     * ```
+     */
+    headToHead(params: HeadToHeadParams): Promise<APIResponse<HeadToHead>>;
+    /**
+     * Filter firearms by a specific feature.
+     *
+     * @param params - The feature name and optional category filter with pagination.
+     * @returns A paginated list of firearms that have the specified feature.
+     * @throws {BadRequestError} If the feature name is empty.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firearms.byFeature({ feature: 'threaded-barrel' });
+     * ```
+     */
+    byFeature(params: ByFeatureParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Filter firearms by action type.
+     *
+     * @param params - The action type string with pagination.
+     * @returns A paginated list of firearms with the specified action type.
+     * @throws {BadRequestError} If the action type is empty.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firearms.byAction({ action: 'semi-automatic' });
+     * ```
+     */
+    byAction(params: ByActionParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Filter firearms by frame/component material.
+     *
+     * @param params - The material name, component type, and pagination.
+     * @returns A paginated list of firearms using the specified material.
+     * @throws {BadRequestError} If the material or component is invalid.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firearms.byMaterial({
+     *   material: 'polymer',
+     *   component: 'frame',
+     * });
+     * ```
+     */
+    byMaterial(params: ByMaterialParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Filter firearms by designer name.
+     *
+     * @param params - The designer name string with pagination.
+     * @returns A paginated list of firearms designed by the specified person.
+     * @throws {BadRequestError} If the designer name is empty.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firearms.byDesigner({ designer: 'John Browning' });
+     * ```
+     */
+    byDesigner(params: ByDesignerParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Get firearms ranked by computed power rating.
+     *
+     * @param params - Optional category filter with pagination.
+     * @returns A paginated list of firearms with their power ratings.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firearms.powerRating({ category: 'rifle' });
+     * for (const item of result.data) {
+     *   console.log(`${item.name}: ${item.rating}`);
+     * }
+     * ```
+     */
+    powerRating(params?: PowerRatingParams): Promise<PaginatedResponse<PowerRating>>;
+    /**
+     * Get firearms arranged in a chronological timeline.
+     *
+     * @param params - Optional year range, category filter, and pagination.
+     * @returns A paginated list of firearms ordered by introduction date.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firearms.timeline({ from: 1900, to: 1950 });
+     * ```
+     */
+    timeline(params?: TimelineParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Filter firearms by military conflict.
+     *
+     * @param params - The conflict identifier string with pagination.
+     * @returns A paginated list of firearms used in the specified conflict.
+     * @throws {BadRequestError} If the conflict name is empty.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.firearms.byConflict({ conflict: 'world-war-ii' });
+     * ```
+     */
+    byConflict(params: ByConflictParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Get a single firearm by its slug or ID.
+     *
+     * @param id - The firearm slug (e.g. `"glock-g17"`) or numeric ID.
+     * @returns The full firearm record with all available fields.
+     * @throws {NotFoundError} If no firearm matches the given identifier.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.get('beretta-92fs');
+     * console.log(data.name);            // "Beretta 92FS"
+     * console.log(data.manufacturerId);  // "beretta"
+     * ```
+     */
+    get(id: string): Promise<APIResponse<Firearm>>;
+    /**
+     * Get all variants of a firearm.
+     *
+     * @param id - The parent firearm slug or ID.
+     * @returns An array of variant firearms derived from the parent.
+     * @throws {NotFoundError} If the parent firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getVariants('colt-1911');
+     * console.log(data.map(v => v.name));
+     * ```
+     */
+    getVariants(id: string): Promise<APIResponse<Firearm[]>>;
+    /**
+     * Get images for a firearm.
+     *
+     * @param id - The firearm slug or ID.
+     * @returns An array of image records with URLs, dimensions, and metadata.
+     * @throws {NotFoundError} If the firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getImages('sig-sauer-p226');
+     * for (const img of data) {
+     *   console.log(img.url, img.width, img.height);
+     * }
+     * ```
+     */
+    getImages(id: string): Promise<APIResponse<FirearmImage[]>>;
+    /**
+     * Get computed game statistics for a firearm.
+     *
+     * @param id - The firearm slug or ID.
+     * @returns Game-balanced stats including damage, accuracy, range, etc.
+     * @throws {NotFoundError} If the firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getGameStats('ak-47');
+     * console.log(data.damage, data.accuracy, data.range);
+     * ```
+     */
+    getGameStats(id: string): Promise<APIResponse<GameStats>>;
+    /**
+     * Get physical dimensions for a firearm.
+     *
+     * @param id - The firearm slug or ID.
+     * @returns Detailed dimension data (length, height, width, barrel length, weight).
+     * @throws {NotFoundError} If the firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getDimensions('glock-g19');
+     * console.log(`${data.overallLengthMm}mm overall`);
+     * ```
+     */
+    getDimensions(id: string): Promise<APIResponse<Dimensions>>;
+    /**
+     * Get known military/law-enforcement adopters of a firearm.
+     *
+     * @param id - The firearm slug or ID.
+     * @returns An array of users/adopters with country and organization data.
+     * @throws {NotFoundError} If the firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getUsers('beretta-m9');
+     * for (const user of data) {
+     *   console.log(user.country, user.organization);
+     * }
+     * ```
+     */
+    getUsers(id: string): Promise<APIResponse<FirearmUser[]>>;
+    /**
+     * Get the family tree (lineage) of a firearm.
+     *
+     * @param id - The firearm slug or ID.
+     * @returns A tree structure showing predecessors, descendants, and related models.
+     * @throws {NotFoundError} If the firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getFamilyTree('m16a2');
+     * console.log(data.ancestors, data.descendants);
+     * ```
+     */
+    getFamilyTree(id: string): Promise<APIResponse<FamilyTree>>;
+    /**
+     * Get firearms similar to a given firearm.
+     *
+     * @param id - The firearm slug or ID.
+     * @returns An array of similar firearms ranked by similarity score.
+     * @throws {NotFoundError} If the firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getSimilar('glock-g17');
+     * for (const match of data) {
+     *   console.log(match.name, match.similarityScore);
+     * }
+     * ```
+     */
+    getSimilar(id: string): Promise<APIResponse<SimilarFirearm[]>>;
+    /**
+     * Get the worldwide adoption map for a firearm.
+     *
+     * @param id - The firearm slug or ID.
+     * @returns Adoption data by country with usage type and date ranges.
+     * @throws {NotFoundError} If the firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getAdoptionMap('fn-fal');
+     * console.log(data.countries.length, 'countries adopted this firearm');
+     * ```
+     */
+    getAdoptionMap(id: string): Promise<APIResponse<AdoptionMap>>;
+    /**
+     * Get the full game profile for a firearm.
+     *
+     * @param id - The firearm slug or ID.
+     * @returns Game-specific profile including archetype, tier, and stat breakdown.
+     * @throws {NotFoundError} If the firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getGameProfile('mp5');
+     * console.log(data.archetype, data.tier);
+     * ```
+     */
+    getGameProfile(id: string): Promise<APIResponse<GameProfile>>;
+    /**
+     * Get an SVG silhouette (line art) of a firearm.
+     *
+     * @param id - The firearm slug or ID.
+     * @param params - Optional format and stroke customization parameters.
+     * @returns Silhouette data in the requested format (raw SVG, data URI, or JSON).
+     * @throws {NotFoundError} If the firearm does not exist or has no silhouette.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.getSilhouette('ak-47', {
+     *   format: 'datauri',
+     *   stroke_width: 2,
+     *   stroke_color: '#333',
+     * });
+     * // Use data.dataUri in an <img> tag
+     * ```
+     */
+    getSilhouette(id: string, params?: SilhouetteParams): Promise<APIResponse<Silhouette>>;
+    /**
+     * Calculate ballistics for a firearm with specific ammunition.
+     *
+     * @param id - The firearm slug or ID.
+     * @param params - Ammunition ID and optional ballistic parameters.
+     * @returns Calculated ballistic data including velocity, energy, and trajectory.
+     * @throws {NotFoundError} If the firearm or ammunition does not exist.
+     * @throws {BadRequestError} If the ammunition is incompatible with the firearm.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.calculate('glock-g17', {
+     *   ammo_id: '9mm-federal-hst-124gr',
+     * });
+     * console.log(data.muzzleVelocity, data.muzzleEnergy);
+     * ```
+     */
+    calculate(id: string, params: CalculateBallisticsParams): Promise<APIResponse<FirearmCalculation>>;
+    /**
+     * Load a firearm with ammunition and get combined performance data.
+     *
+     * @param id - The firearm slug or ID.
+     * @param params - Optional ammunition ID to load.
+     * @returns Combined firearm + ammunition data with computed performance metrics.
+     * @throws {NotFoundError} If the firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.firearms.load('sig-sauer-p226', {
+     *   ammo_id: '9mm-winchester-ranger-147gr',
+     * });
+     * ```
+     */
+    load(id: string, params?: LoadFirearmParams): Promise<APIResponse<FirearmLoadProfile>>;
+}
+
+/**
+ * Manufacturers resource for the GunSpec SDK.
+ *
+ * Provides access to all `/v1/manufacturers` endpoints including listing,
+ * retrieving details, and exploring a manufacturer's firearms catalog,
+ * timeline, and statistics.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Manufacturers API.
+ *
+ * Wraps all `/v1/manufacturers` endpoints. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.manufacturers`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * // List manufacturers
+ * const { data } = await client.manufacturers.list({ country: 'US' });
+ *
+ * // Get manufacturer details
+ * const { data: mfr } = await client.manufacturers.get('beretta');
+ * ```
+ */
+declare class ManufacturersResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * List manufacturers with optional filters and pagination.
+     *
+     * @param params - Optional query parameters for filtering by country, sorting, and pagination.
+     * @returns A paginated list of manufacturers.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.manufacturers.list({
+     *   country: 'DE',
+     *   sort: 'name',
+     *   order: 'asc',
+     *   per_page: 50,
+     * });
+     * ```
+     */
+    list(params?: ListManufacturersParams): Promise<PaginatedResponse<Manufacturer>>;
+    /**
+     * Auto-paginate through all manufacturers matching the given filters.
+     *
+     * Returns an async iterator that fetches pages on demand, yielding
+     * individual {@link Manufacturer} objects.
+     *
+     * @param params - Optional query parameters for filtering and sorting.
+     * @returns An async iterable iterator yielding individual manufacturers.
+     *
+     * @example
+     * ```typescript
+     * for await (const mfr of client.manufacturers.listAutoPaging()) {
+     *   console.log(mfr.name, mfr.country);
+     * }
+     * ```
+     */
+    listAutoPaging(params?: ListManufacturersParams): AsyncIterableIterator<Manufacturer>;
+    /**
+     * Get a single manufacturer by its slug or ID.
+     *
+     * @param id - The manufacturer slug (e.g. `"beretta"`) or numeric ID.
+     * @returns The full manufacturer record.
+     * @throws {NotFoundError} If no manufacturer matches the given identifier.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.manufacturers.get('sig-sauer');
+     * console.log(data.name, data.foundedYear, data.country);
+     * ```
+     */
+    get(id: string): Promise<APIResponse<Manufacturer>>;
+    /**
+     * Get all firearms produced by a manufacturer.
+     *
+     * @param id - The manufacturer slug or ID.
+     * @param params - Optional pagination parameters.
+     * @returns A paginated list of firearms from the specified manufacturer.
+     * @throws {NotFoundError} If the manufacturer does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.manufacturers.getFirearms('colt', { per_page: 50 });
+     * console.log(`Colt makes ${result.pagination.total} firearms`);
+     * ```
+     */
+    getFirearms(id: string, params?: PaginationParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Get a chronological timeline for a manufacturer.
+     *
+     * @param id - The manufacturer slug or ID.
+     * @returns Timeline data with key events, product launches, and milestones.
+     * @throws {NotFoundError} If the manufacturer does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.manufacturers.getTimeline('browning');
+     * for (const event of data.events) {
+     *   console.log(event.year, event.description);
+     * }
+     * ```
+     */
+    getTimeline(id: string): Promise<APIResponse<ManufacturerTimeline>>;
+    /**
+     * Get aggregate statistics for a manufacturer.
+     *
+     * @param id - The manufacturer slug or ID.
+     * @returns Statistical summary including firearm counts, caliber distribution, and more.
+     * @throws {NotFoundError} If the manufacturer does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.manufacturers.getStats('glock');
+     * console.log(data.totalFirearms, data.caliberBreakdown);
+     * ```
+     */
+    getStats(id: string): Promise<APIResponse<ManufacturerStats>>;
+}
+
+/**
+ * Calibers resource for the GunSpec SDK.
+ *
+ * Provides access to all `/v1/calibers` endpoints including listing,
+ * comparing, ballistics calculations, and exploring caliber families
+ * and associated ammunition.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Calibers API.
+ *
+ * Wraps all `/v1/calibers` endpoints. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.calibers`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * // List calibers
+ * const { data } = await client.calibers.list({ cartridge_type: 'centerfire' });
+ *
+ * // Compare calibers
+ * const { data: comparison } = await client.calibers.compare({
+ *   ids: '9x19mm-parabellum,45-acp',
+ * });
+ * ```
+ */
+declare class CalibersResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * List calibers with optional filters and pagination.
+     *
+     * @param params - Optional query parameters for filtering by cartridge type, primer type, etc.
+     * @returns A paginated list of calibers.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.calibers.list({
+     *   cartridge_type: 'centerfire',
+     *   primer_type: 'boxer',
+     *   per_page: 50,
+     * });
+     * ```
+     */
+    list(params?: ListCalibersParams): Promise<PaginatedResponse<Caliber>>;
+    /**
+     * Auto-paginate through all calibers matching the given filters.
+     *
+     * Returns an async iterator that fetches pages on demand, yielding
+     * individual {@link Caliber} objects.
+     *
+     * @param params - Optional query parameters for filtering and sorting.
+     * @returns An async iterable iterator yielding individual calibers.
+     *
+     * @example
+     * ```typescript
+     * for await (const caliber of client.calibers.listAutoPaging()) {
+     *   console.log(caliber.name, caliber.bulletDiameterMm);
+     * }
+     * ```
+     */
+    listAutoPaging(params?: ListCalibersParams): AsyncIterableIterator<Caliber>;
+    /**
+     * Compare up to 5 calibers side by side.
+     *
+     * @param params - Object containing comma-separated caliber IDs.
+     * @returns An array of calibers with full details for comparison.
+     * @throws {BadRequestError} If more than 5 IDs are provided.
+     * @throws {NotFoundError} If any of the specified calibers do not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.calibers.compare({
+     *   ids: '9x19mm-parabellum,45-acp,40-s-w',
+     * });
+     * ```
+     */
+    compare(params: CompareCalibersParams): Promise<APIResponse<Caliber[]>>;
+    /**
+     * Get ballistics data for a caliber at a specified distance.
+     *
+     * @param params - Caliber ID and distance in meters.
+     * @returns Ballistic data including velocity, energy, and drop at the specified distance.
+     * @throws {NotFoundError} If the caliber does not exist.
+     * @throws {BadRequestError} If the distance is out of range.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.calibers.ballistics({
+     *   id: '9x19mm-parabellum',
+     *   distance: 100,
+     * });
+     * console.log(data.velocity, data.energy, data.drop);
+     * ```
+     */
+    ballistics(params: CaliberBallisticsParams): Promise<APIResponse<BallisticsResult>>;
+    /**
+     * Get a single caliber by its slug or ID.
+     *
+     * @param id - The caliber slug (e.g. `"9x19mm-parabellum"`) or numeric ID.
+     * @returns The full caliber record with all specifications.
+     * @throws {NotFoundError} If no caliber matches the given identifier.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.calibers.get('45-acp');
+     * console.log(data.name, data.bulletDiameterMm, data.caseLengthMm);
+     * ```
+     */
+    get(id: string): Promise<APIResponse<Caliber>>;
+    /**
+     * Get all firearms that use a specific caliber.
+     *
+     * @param id - The caliber slug or ID.
+     * @param params - Optional pagination parameters.
+     * @returns A paginated list of firearms chambered in the specified caliber.
+     * @throws {NotFoundError} If the caliber does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.calibers.getFirearms('9x19mm-parabellum', { per_page: 50 });
+     * console.log(`${result.pagination.total} firearms use 9mm`);
+     * ```
+     */
+    getFirearms(id: string, params?: PaginationParams): Promise<PaginatedResponse<Firearm>>;
+    /**
+     * Get the parent caliber chain (ancestry) for a caliber.
+     *
+     * @param id - The caliber slug or ID.
+     * @returns An ordered array of calibers from the given caliber up to the root ancestor.
+     * @throws {NotFoundError} If the caliber does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.calibers.getParentChain('300-blackout');
+     * // [300 Blackout, 5.56x45mm NATO, .223 Remington, ...]
+     * ```
+     */
+    getParentChain(id: string): Promise<APIResponse<Caliber[]>>;
+    /**
+     * Get the full family tree of related calibers.
+     *
+     * @param id - The caliber slug or ID.
+     * @returns An array of calibers in the same family (parent, siblings, children).
+     * @throws {NotFoundError} If the caliber does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.calibers.getFamily('9x19mm-parabellum');
+     * console.log(data.map(c => c.name));
+     * ```
+     */
+    getFamily(id: string): Promise<APIResponse<Caliber[]>>;
+    /**
+     * Get ammunition loads available for a caliber.
+     *
+     * @param id - The caliber slug or ID.
+     * @param params - Optional pagination parameters.
+     * @returns A paginated list of ammunition loads for the specified caliber.
+     * @throws {NotFoundError} If the caliber does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.calibers.getAmmunition('9x19mm-parabellum', { per_page: 25 });
+     * for (const ammo of result.data) {
+     *   console.log(ammo.name, ammo.bulletWeightGrains);
+     * }
+     * ```
+     */
+    getAmmunition(id: string, params?: PaginationParams): Promise<PaginatedResponse<Ammunition>>;
+}
+
+/**
+ * Categories resource for the GunSpec SDK.
+ *
+ * Provides access to `/v1/categories` endpoints for listing firearm
+ * categories and retrieving firearms within a specific category.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Categories API.
+ *
+ * Wraps all `/v1/categories` endpoints. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.categories`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * // List all categories
+ * const { data } = await client.categories.list();
+ * console.log(data.map(c => c.name));
+ *
+ * // Get firearms in a category
+ * const pistols = await client.categories.getFirearms('pistol');
+ * ```
+ */
+declare class CategoriesResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * List all firearm categories.
+     *
+     * @returns An array of all category records.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.categories.list();
+     * // [{ slug: 'pistol', name: 'Pistol' }, { slug: 'rifle', name: 'Rifle' }, ...]
+     * ```
+     */
+    list(): Promise<APIResponse<Category[]>>;
+    /**
+     * Get all firearms within a specific category.
+     *
+     * @param slug - The category slug (e.g. `"pistol"`, `"rifle"`, `"shotgun"`).
+     * @param params - Optional pagination parameters.
+     * @returns A paginated list of firearms in the specified category.
+     * @throws {NotFoundError} If the category slug does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.categories.getFirearms('shotgun', {
+     *   per_page: 25,
+     *   sort: 'name',
+     *   order: 'asc',
+     * });
+     * console.log(`${result.pagination.total} shotguns in database`);
+     * ```
+     */
+    getFirearms(slug: string, params?: PaginationParams): Promise<PaginatedResponse<Firearm>>;
+}
+
+/**
+ * Statistics resource for the GunSpec SDK.
+ *
+ * Provides access to all `/v1/stats` endpoints for retrieving aggregate
+ * statistics about the firearms database including production status,
+ * field coverage, caliber popularity, and more.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Statistics API.
+ *
+ * Wraps all `/v1/stats` endpoints. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.stats`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * const { data } = await client.stats.summary();
+ * console.log(data.totalFirearms, data.totalManufacturers);
+ * ```
+ */
+declare class StatsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Get a high-level summary of the database.
+     *
+     * @returns Summary counts for firearms, manufacturers, calibers, and categories.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.summary();
+     * console.log(`Database has ${data.totalFirearms} firearms`);
+     * ```
+     */
+    summary(): Promise<APIResponse<StatsSummary>>;
+    /**
+     * Get firearm counts grouped by production status.
+     *
+     * @returns Counts for in-production, discontinued, and prototype firearms.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.productionStatus();
+     * // { in_production: 342, discontinued: 891, prototype: 12 }
+     * ```
+     */
+    productionStatus(): Promise<APIResponse<ProductionStatusItem[]>>;
+    /**
+     * Get field coverage statistics across the database.
+     *
+     * Shows the percentage of firearms that have data for each field,
+     * useful for assessing data completeness.
+     *
+     * @returns Per-field coverage percentages.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.fieldCoverage();
+     * console.log(`Weight field: ${data.weight}% coverage`);
+     * ```
+     */
+    fieldCoverage(): Promise<APIResponse<FieldCoverage>>;
+    /**
+     * Get the most popular calibers by firearm count.
+     *
+     * @param params - Optional limit parameter.
+     * @returns An ordered list of calibers ranked by the number of firearms using them.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.popularCalibers({ limit: 10 });
+     * for (const entry of data) {
+     *   console.log(`${entry.name}: ${entry.count} firearms`);
+     * }
+     * ```
+     */
+    popularCalibers(params?: PopularCalibersParams): Promise<APIResponse<PopularCaliber[]>>;
+    /**
+     * Get the most prolific manufacturers by firearm count.
+     *
+     * @param params - Optional limit and category filter.
+     * @returns An ordered list of manufacturers ranked by the number of firearms produced.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.prolificManufacturers({
+     *   limit: 10,
+     *   category: 'pistol',
+     * });
+     * ```
+     */
+    prolificManufacturers(params?: ProlificManufacturersParams): Promise<APIResponse<ProlificManufacturer[]>>;
+    /**
+     * Get firearm counts grouped by category.
+     *
+     * @returns Counts per category (pistol, rifle, shotgun, etc.).
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.byCategory();
+     * // [{ category: 'pistol', count: 512 }, { category: 'rifle', count: 234 }, ...]
+     * ```
+     */
+    byCategory(): Promise<APIResponse<CategoryStats[]>>;
+    /**
+     * Get firearm statistics for a specific decade/era.
+     *
+     * @param params - The decade string (e.g. `"1990s"`).
+     * @returns Statistics for firearms introduced during the specified decade.
+     * @throws {BadRequestError} If the decade format is invalid (must be like `"1990s"`).
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.byEra({ decade: '1940s' });
+     * ```
+     */
+    byEra(params: ByEraParams): Promise<APIResponse<EraStats>>;
+    /**
+     * Get statistics about materials used across all firearms.
+     *
+     * @returns Material usage counts and percentages by component type.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.materials();
+     * ```
+     */
+    materials(): Promise<APIResponse<MaterialStats>>;
+    /**
+     * Get firearm adoption statistics for a specific country.
+     *
+     * @param params - The country code (e.g. `"US"`, `"GB"`).
+     * @returns Adoption data for the specified country.
+     * @throws {BadRequestError} If the country code is invalid.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.adoptionByCountry({ code: 'US' });
+     * ```
+     */
+    adoptionByCountry(params: AdoptionByCountryParams): Promise<APIResponse<AdoptionByCountryItem[]>>;
+    /**
+     * Get firearm adoption statistics by usage type.
+     *
+     * @param params - The usage type (e.g. `"military"`, `"law_enforcement"`, `"civilian"`).
+     * @returns Adoption data for the specified usage type.
+     * @throws {BadRequestError} If the type is not a recognized usage category.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.adoptionByType({ type: 'military' });
+     * ```
+     */
+    adoptionByType(params: AdoptionByTypeParams): Promise<APIResponse<AdoptionByTypeItem[]>>;
+    /**
+     * Get firearm counts grouped by action type.
+     *
+     * @param params - Optional category filter.
+     * @returns Counts per action type, optionally filtered by category.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.actionTypes({ category: 'rifle' });
+     * ```
+     */
+    actionTypes(params?: ActionTypesParams): Promise<APIResponse<ActionTypeStats[]>>;
+    /**
+     * Get feature frequency statistics across the database.
+     *
+     * @param params - Optional category filter and result limit.
+     * @returns An ordered list of features ranked by frequency of occurrence.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.featureFrequency({
+     *   category: 'pistol',
+     *   limit: 20,
+     * });
+     * ```
+     */
+    featureFrequency(params?: FeatureFrequencyParams): Promise<APIResponse<FeatureFrequency[]>>;
+    /**
+     * Get caliber popularity trends across historical eras.
+     *
+     * @param params - Optional from/to decade range (e.g. `"1940s"` to `"2020s"`).
+     * @returns Caliber popularity data broken down by decade.
+     * @throws {BadRequestError} If the decade format is invalid.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.stats.caliberPopularityByEra({
+     *   from_decade: '1940s',
+     *   to_decade: '2020s',
+     * });
+     * ```
+     */
+    caliberPopularityByEra(params?: CaliberPopularityByEraParams): Promise<APIResponse<CaliberPopularityByEra[]>>;
+}
+
+/**
+ * Game resource for the GunSpec SDK.
+ *
+ * Provides access to all `/v1/game` endpoints for game-balanced
+ * firearm data including balance reports, tier lists, matchups,
+ * role rosters, and stat distributions.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Game API.
+ *
+ * Wraps all `/v1/game` endpoints. These endpoints provide game-balanced
+ * firearm data suitable for game development, including normalized stats,
+ * tier rankings, and balance analysis.
+ *
+ * Instantiated internally by the {@link GunSpec} client and exposed as
+ * `client.game`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * const { data } = await client.game.tierList({ stat: 'damage' });
+ * console.log(data.tiers);
+ * ```
+ */
+declare class GameResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Get a balance report showing outlier firearms.
+     *
+     * Identifies firearms whose game stats deviate significantly from
+     * the average, useful for game balancing.
+     *
+     * @param params - Optional threshold for outlier detection (0-100).
+     * @returns A balance report with overpowered and underpowered firearms.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.game.balanceReport({ threshold: 15 });
+     * console.log(data.length, 'firearms flagged as outliers');
+     * ```
+     */
+    balanceReport(params?: BalanceReportParams): Promise<APIResponse<BalanceEntry[]>>;
+    /**
+     * Get a tier list of firearms ranked by a specific stat.
+     *
+     * @param params - Optional category filter and stat to rank by.
+     * @returns A tier list with firearms grouped into S/A/B/C/D/F tiers.
+     * @throws {BadRequestError} If the stat is not a valid game stat.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.game.tierList({
+     *   stat: 'accuracy',
+     *   category: 'rifle',
+     * });
+     * console.log('S-tier:', data.tiers.S.map(f => f.name));
+     * ```
+     */
+    tierList(params?: TierListParams): Promise<APIResponse<TierList>>;
+    /**
+     * Get a game-balanced matchup between two firearms.
+     *
+     * @param params - The slugs of the two firearms to compare.
+     * @returns A detailed matchup result with per-stat comparisons and a winner.
+     * @throws {NotFoundError} If either firearm does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.game.matchups({ a: 'ak-47', b: 'm4-carbine' });
+     * console.log(data.winner, data.statComparisons);
+     * ```
+     */
+    matchups(params: MatchupsParams): Promise<APIResponse<MatchupResult>>;
+    /**
+     * Get a roster of firearms best suited for a specific game role.
+     *
+     * @param params - The role to query and optional count limit.
+     * @returns A roster of firearms ranked by suitability for the given role.
+     * @throws {BadRequestError} If the role is not a recognized game role.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.game.roleRoster({
+     *   role: 'sniper',
+     *   count: 10,
+     * });
+     * for (const firearm of data) {
+     *   console.log(firearm.name, firearm.roleScore);
+     * }
+     * ```
+     */
+    roleRoster(params: RoleRosterParams): Promise<APIResponse<RoleRosterItem[]>>;
+    /**
+     * Get the statistical distribution for a specific game stat.
+     *
+     * Shows how firearms are distributed across value ranges for a given
+     * stat, useful for understanding the spread and identifying balance issues.
+     *
+     * @param params - The stat to analyze (e.g. `"damage"`, `"accuracy"`).
+     * @returns Distribution data including histogram buckets and summary statistics.
+     * @throws {BadRequestError} If the stat is not a valid game stat.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.game.statDistribution({ stat: 'damage' });
+     * console.log(data.mean, data.median, data.buckets);
+     * ```
+     */
+    statDistribution(params: StatDistributionParams): Promise<APIResponse<StatDistribution>>;
+}
+
+/**
+ * Game Stats Snapshots resource for the GunSpec SDK.
+ *
+ * Provides access to `/v1/game-stats` endpoints for retrieving versioned
+ * snapshots of game-balanced firearm statistics. Each snapshot captures
+ * the game stats at a specific point in time, enabling version tracking
+ * and historical comparisons.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Game Stats Snapshots API.
+ *
+ * Wraps all `/v1/game-stats` endpoints. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.gameStats`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * // List all snapshot versions
+ * const { data: versions } = await client.gameStats.listVersions();
+ *
+ * // Get firearms from a specific version
+ * const result = await client.gameStats.listFirearms('1.0.0');
+ * ```
+ */
+declare class GameStatsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * List all available game stats snapshot versions.
+     *
+     * @returns An array of version records with metadata about each snapshot.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.gameStats.listVersions();
+     * for (const version of data) {
+     *   console.log(version.version, version.createdAt, version.description);
+     * }
+     * ```
+     */
+    listVersions(): Promise<APIResponse<GameStatsVersion[]>>;
+    /**
+     * List all firearms in a specific game stats snapshot version.
+     *
+     * @param version - The snapshot version string (e.g. `"1.0.0"`).
+     * @param params - Optional pagination parameters.
+     * @returns A paginated list of firearms with their game stats for the given version.
+     * @throws {NotFoundError} If the specified version does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.gameStats.listFirearms('1.0.0', { per_page: 50 });
+     * for (const firearm of result.data) {
+     *   console.log(firearm.name, firearm.damage);
+     * }
+     * ```
+     */
+    listFirearms(version: string, params?: ListSnapshotFirearmsParams): Promise<PaginatedResponse<GameStatsSnapshotEntry>>;
+    /**
+     * Get a single firearm's game stats from a specific snapshot version.
+     *
+     * @param version - The snapshot version string (e.g. `"1.0.0"`).
+     * @param id - The firearm slug or ID.
+     * @returns The firearm's game stats as captured in the specified version.
+     * @throws {NotFoundError} If the version or firearm does not exist in the snapshot.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.gameStats.getFirearm('1.0.0', 'glock-g17');
+     * console.log(data.damage, data.accuracy, data.range);
+     * ```
+     */
+    getFirearm(version: string, id: string): Promise<APIResponse<GameStatsSnapshotEntry>>;
+}
+
+/**
+ * Ammunition resource for the GunSpec SDK.
+ *
+ * Provides access to all `/v1/ammunition` endpoints including listing,
+ * retrieving details, bullet SVG generation, and ballistic calculations.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Ammunition API.
+ *
+ * Wraps all `/v1/ammunition` endpoints. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.ammunition`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * // List ammunition
+ * const { data } = await client.ammunition.list({ caliber_id: '9x19mm-parabellum' });
+ *
+ * // Get ballistics for a specific load
+ * const { data: ballistics } = await client.ammunition.ballistics(
+ *   '9mm-federal-hst-124gr',
+ *   { distances: '0,25,50,100' },
+ * );
+ * ```
+ */
+declare class AmmunitionResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * List ammunition with optional filters and pagination.
+     *
+     * @param params - Optional query parameters for filtering by caliber, bullet type, etc.
+     * @returns A paginated list of ammunition loads.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.ammunition.list({
+     *   caliber_id: '9x19mm-parabellum',
+     *   bullet_type: 'hollow-point',
+     *   per_page: 25,
+     * });
+     * ```
+     */
+    list(params?: ListAmmunitionParams): Promise<PaginatedResponse<Ammunition>>;
+    /**
+     * Auto-paginate through all ammunition matching the given filters.
+     *
+     * Returns an async iterator that fetches pages on demand, yielding
+     * individual {@link Ammunition} objects.
+     *
+     * @param params - Optional query parameters for filtering and sorting.
+     * @returns An async iterable iterator yielding individual ammunition loads.
+     *
+     * @example
+     * ```typescript
+     * for await (const ammo of client.ammunition.listAutoPaging({ caliber_id: '45-acp' })) {
+     *   console.log(ammo.name, ammo.bulletWeightGrains);
+     * }
+     * ```
+     */
+    listAutoPaging(params?: ListAmmunitionParams): AsyncIterableIterator<Ammunition>;
+    /**
+     * Get a single ammunition load by its slug or ID.
+     *
+     * @param id - The ammunition slug (e.g. `"9mm-federal-hst-124gr"`) or numeric ID.
+     * @returns The full ammunition record with specifications.
+     * @throws {NotFoundError} If no ammunition matches the given identifier.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.ammunition.get('9mm-federal-hst-124gr');
+     * console.log(data.name, data.muzzleVelocityFps, data.bulletWeightGrains);
+     * ```
+     */
+    get(id: string): Promise<APIResponse<Ammunition>>;
+    /**
+     * Get a bullet profile SVG image for an ammunition load.
+     *
+     * Returns a raw SVG string representing the bullet projectile shape.
+     * This endpoint returns raw SVG content, not the standard JSON envelope.
+     *
+     * @param id - The ammunition slug or ID.
+     * @returns The raw SVG string of the bullet profile.
+     * @throws {NotFoundError} If the ammunition does not exist.
+     *
+     * @example
+     * ```typescript
+     * const svg = await client.ammunition.getBulletSvg('9mm-federal-hst-124gr');
+     * // Insert into DOM: element.innerHTML = svg;
+     * ```
+     */
+    getBulletSvg(id: string): Promise<string>;
+    /**
+     * Get ballistic trajectory data for an ammunition load.
+     *
+     * @param id - The ammunition slug or ID.
+     * @param params - Optional barrel length and distance parameters.
+     * @returns Ballistic trajectory data at specified distances.
+     * @throws {NotFoundError} If the ammunition does not exist.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.ammunition.ballistics('9mm-federal-hst-124gr', {
+     *   barrel_length_mm: 102,
+     *   distances: '0,25,50,100,200',
+     * });
+     * for (const point of data.trajectory) {
+     *   console.log(`${point.distanceM}m: ${point.velocityFps} fps, ${point.energyFtLbs} ft-lbs`);
+     * }
+     * ```
+     */
+    ballistics(id: string, params?: AmmunitionBallisticsParams): Promise<APIResponse<BallisticProfile>>;
+}
+
+/**
+ * Countries resource for the GunSpec SDK.
+ *
+ * Provides access to `/v1/countries` endpoints for listing countries
+ * and retrieving a country's full firearm arsenal.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Countries API.
+ *
+ * Wraps all `/v1/countries` endpoints. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.countries`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * // List all countries
+ * const { data } = await client.countries.list();
+ *
+ * // Get a country's full arsenal
+ * const { data: arsenal } = await client.countries.getArsenal('US');
+ * ```
+ */
+declare class CountriesResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * List all countries that have adopted at least one firearm.
+     *
+     * @returns An array of country records with codes and names.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.countries.list();
+     * for (const country of data) {
+     *   console.log(country.code, country.name);
+     * }
+     * ```
+     */
+    list(): Promise<APIResponse<Country[]>>;
+    /**
+     * Get the full firearm arsenal for a specific country.
+     *
+     * Returns all firearms adopted by the country, grouped by usage type
+     * (military, law enforcement, etc.).
+     *
+     * @param code - The country code (e.g. `"US"`, `"GB"`, `"DE"`).
+     * @returns The country's arsenal data with firearms grouped by adoption type.
+     * @throws {NotFoundError} If the country code is not found in the database.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.countries.getArsenal('US');
+     * console.log(`${data.country.name} has ${data.totalFirearms} firearms`);
+     * for (const group of data.groups) {
+     *   console.log(`${group.type}: ${group.firearms.length} firearms`);
+     * }
+     * ```
+     */
+    getArsenal(code: string): Promise<APIResponse<CountryArsenal>>;
+}
+
+/**
+ * Conflicts resource for the GunSpec SDK.
+ *
+ * Provides access to the `/v1/conflicts` endpoint for listing military
+ * conflicts and their associated firearms.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Conflicts API.
+ *
+ * Wraps the `/v1/conflicts` endpoint. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.conflicts`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * const { data } = await client.conflicts.list();
+ * for (const conflict of data) {
+ *   console.log(conflict.name, conflict.startYear, conflict.endYear);
+ * }
+ * ```
+ */
+declare class ConflictsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * List all military conflicts in the database.
+     *
+     * Returns conflicts with metadata including name, date range, and
+     * participating nations. Use the conflict identifiers with
+     * `client.firearms.byConflict()` to find firearms used in a specific conflict.
+     *
+     * @returns An array of all conflict records.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.conflicts.list();
+     * for (const conflict of data) {
+     *   console.log(`${conflict.name} (${conflict.startYear}-${conflict.endYear})`);
+     * }
+     *
+     * // Then find firearms used in a conflict:
+     * const wwii = await client.firearms.byConflict({ conflict: 'world-war-ii' });
+     * ```
+     */
+    list(): Promise<APIResponse<Conflict[]>>;
+}
+
+/**
+ * Data Quality resource for the GunSpec SDK.
+ *
+ * Provides access to `/v1/data` endpoints for assessing database
+ * coverage and per-record confidence scores.
+ *
+ * @module
+ */
+
+/**
+ * Resource class for interacting with the GunSpec Data Quality API.
+ *
+ * Wraps all `/v1/data` endpoints. Instantiated internally by the
+ * {@link GunSpec} client and exposed as `client.dataQuality`.
+ *
+ * @example
+ * ```typescript
+ * import GunSpec from '@gunspec/sdk';
+ *
+ * const client = new GunSpec();
+ *
+ * // Check overall data coverage
+ * const { data } = await client.dataQuality.coverage();
+ * console.log(`${data.overallCoverage}% overall field coverage`);
+ *
+ * // Find low-confidence records
+ * const lowConf = await client.dataQuality.confidence({ below: 0.3 });
+ * ```
+ */
+declare class DataQualityResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    /**
+     * Get overall data coverage statistics for the database.
+     *
+     * Returns per-field and aggregate coverage metrics showing what
+     * percentage of records have data for each field.
+     *
+     * @returns Data coverage statistics including per-field percentages.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const { data } = await client.dataQuality.coverage();
+     * console.log(`Overall: ${data.overallCoverage}%`);
+     * for (const field of data.fields) {
+     *   console.log(`${field.name}: ${field.coverage}%`);
+     * }
+     * ```
+     */
+    coverage(): Promise<APIResponse<DataCoverage>>;
+    /**
+     * Get firearms with confidence scores below a specified threshold.
+     *
+     * Useful for identifying records that may need additional data
+     * verification or enrichment.
+     *
+     * @param params - Optional threshold and pagination parameters.
+     * @returns A paginated list of firearms with their confidence scores.
+     * @throws {BadRequestError} If the threshold is outside the 0-1 range.
+     * @throws {AuthenticationError} If the API key is missing or invalid.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.dataQuality.confidence({
+     *   below: 0.5,
+     *   per_page: 25,
+     * });
+     * for (const item of result.data) {
+     *   console.log(`${item.name}: confidence ${item.confidenceScore}`);
+     * }
+     * ```
+     */
+    confidence(params?: ConfidenceParams): Promise<PaginatedResponse<ConfidenceEntry>>;
+}
+
+declare class FavoritesResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(params?: ListFavoritesParams): Promise<PaginatedResponse<Favorite>>;
+    add(firearmId: string): Promise<APIResponse<FavoriteToggle>>;
+    remove(firearmId: string): Promise<APIResponse<FavoriteToggle>>;
+}
+
+declare class ReportsResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(params: CreateReportParams): Promise<APIResponse<DataReport>>;
+    list(params?: ListReportsParams): Promise<PaginatedResponse<DataReport>>;
+}
+
+declare class SupportResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    create(params: CreateTicketParams): Promise<APIResponse<SupportTicket>>;
+    list(params?: ListTicketsParams): Promise<PaginatedResponse<SupportTicket>>;
+    get(ticketId: string): Promise<APIResponse<SupportTicketDetail>>;
+    reply(ticketId: string, params: CreateReplyParams): Promise<APIResponse<SupportTicketReply>>;
+}
+
+declare class WebhooksResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    list(params?: ListWebhookEndpointsParams): Promise<PaginatedResponse<WebhookEndpoint>>;
+    create(params: CreateWebhookEndpointParams): Promise<APIResponse<WebhookEndpoint>>;
+    get(id: string): Promise<APIResponse<WebhookEndpoint>>;
+    update(id: string, params: UpdateWebhookEndpointParams): Promise<APIResponse<WebhookEndpoint>>;
+    delete(id: string): Promise<APIResponse<{
+        deleted: boolean;
+    }>>;
+    test(id: string): Promise<APIResponse<WebhookTestResult>>;
+}
+
+declare class UsageResource {
+    private readonly client;
+    constructor(client: HttpClient);
+    get(params?: UsageParams): Promise<APIResponse<UsageStats>>;
+}
+
+/**
+ * Configuration options for the GunSpec client.
+ *
+ * @example
+ * ```typescript
+ * // Reads GUNSPEC_API_KEY from process.env automatically
+ * const client = new GunSpec();
+ *
+ * // Or pass via environment variable explicitly
+ * const client = new GunSpec({
+ *   apiKey: process.env.GUNSPEC_API_KEY,
+ * });
+ * ```
+ */
+interface ClientOptions {
+    /**
+     * API key for authentication. If not provided, reads from
+     * the `GUNSPEC_API_KEY` environment variable.
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the API. Defaults to `https://api.gunspec.io`.
+     */
+    baseURL?: string;
+    /**
+     * Request timeout in milliseconds. Defaults to 30000 (30s).
+     */
+    timeout?: number;
+    /**
+     * Retry configuration for failed requests.
+     */
+    retry?: RetryConfig;
+    /**
+     * Custom default headers to include with every request.
+     */
+    defaultHeaders?: Record<string, string>;
+}
+/**
+ * GunSpec.io API client — the main entry point for the SDK.
+ *
+ * Provides typed access to the firearms specification database API
+ * through resource-oriented properties that mirror the API structure.
+ *
+ * @example
+ * ```typescript
+ * import { GunSpec } from '@gunspec/sdk';
+ *
+ * // Auto-reads GUNSPEC_API_KEY from environment
+ * const client = new GunSpec();
+ *
+ * // List firearms with filters
+ * const { data, pagination } = await client.firearms.list({
+ *   category: 'pistol',
+ *   status: 'in_production',
+ *   per_page: 50,
+ * });
+ *
+ * // Get a specific firearm by slug
+ * const { data: glock } = await client.firearms.get('glock-g17');
+ *
+ * // Search firearms
+ * const results = await client.firearms.search({ q: 'beretta 92' });
+ *
+ * // Compare firearms side by side
+ * const { data: comparison } = await client.firearms.compare({
+ *   ids: 'glock-g17,beretta-92fs,sig-sauer-p226',
+ * });
+ *
+ * // Auto-paginate through all results
+ * for await (const firearm of client.firearms.listAutoPaging({ category: 'rifle' })) {
+ *   console.log(firearm.name);
+ * }
+ *
+ * // Game development features
+ * const { data: tierList } = await client.game.tierList({ stat: 'damage' });
+ * const { data: matchup } = await client.game.matchups({ a: 'ak-47', b: 'm16a4' });
+ *
+ * // Statistics
+ * const { data: summary } = await client.stats.summary();
+ * ```
+ */
+declare class GunSpec {
+    /** Firearms specifications, search, comparison, and related data */
+    readonly firearms: FirearmsResource;
+    /** Firearm manufacturers and their products */
+    readonly manufacturers: ManufacturersResource;
+    /** Ammunition calibers and cartridge specifications */
+    readonly calibers: CalibersResource;
+    /** Firearm categories (pistol, rifle, shotgun, etc.) */
+    readonly categories: CategoriesResource;
+    /** Aggregate statistics across the database */
+    readonly stats: StatsResource;
+    /** Game development tools — balance reports, tier lists, matchups */
+    readonly game: GameResource;
+    /** Versioned game stats snapshots for pinning game builds */
+    readonly gameStats: GameStatsResource;
+    /** Ammunition loads, ballistics, and bullet data */
+    readonly ammunition: AmmunitionResource;
+    /** Countries and their military/law enforcement arsenals */
+    readonly countries: CountriesResource;
+    /** Armed conflicts and the firearms used in them */
+    readonly conflicts: ConflictsResource;
+    /** Data quality metrics (Enterprise tier) */
+    readonly dataQuality: DataQualityResource;
+    /** User's favorited firearms */
+    readonly favorites: FavoritesResource;
+    /** Data quality reports */
+    readonly reports: ReportsResource;
+    /** Support tickets (paid tiers) */
+    readonly support: SupportResource;
+    /** Webhook endpoint management (studio+ tier) */
+    readonly webhooks: WebhooksResource;
+    /** API usage statistics */
+    readonly usage: UsageResource;
+    /** The underlying HTTP client (for advanced use) */
+    private readonly _client;
+    constructor(options?: ClientOptions);
+}
+
+/** Current SDK version */
+declare const VERSION = "0.1.0";
+
+export { APIError, type APIErrorResponse, type APIResponse, type ActionTypesParams, type AdoptionByCountryParams, type AdoptionByTypeParams, type AdoptionMap, type Ammunition, type AmmunitionBallisticsParams, AmmunitionResource, type AuthConfig, AuthenticationError, BadRequestError, type BalanceReport, type BalanceReportParams, type BallisticsResult, type ByActionParams, type ByConflictParams, type ByDesignerParams, type ByEraParams, type ByFeatureParams, type ByMaterialParams, type CalculateBallisticsParams, type Caliber, type CaliberBallisticsParams, type CaliberPopularityByEraParams, CalibersResource, CategoriesResource, type Category, type ClientOptions, type CompareCalibersParams, type CompareFirearmsParams, type ConfidenceParams, type Conflict, ConflictsResource, ConnectionError, CountriesResource, type Country, type CountryArsenal, type CreateReplyParams, type CreateReportParams, type CreateTicketParams, type CreateWebhookEndpointParams, type DataCoverage, DataQualityResource, type DataReport, type Dimensions, type ErrorBody, type FamilyTree, type Favorite, type FavoriteToggle, FavoritesResource, type FeatureFrequencyParams, type FilterOptions, type Firearm, type FirearmImage, type FirearmUser, FirearmsResource, type GameMetaParams, type GameProfile, GameResource, type GameStats, GameStatsResource, type GameStatsVersion, GunSpec, GunSpecError, type HeadToHead, type HeadToHeadParams, HttpClient, type HttpClientConfig, InternalServerError, type ListAmmunitionParams, type ListCalibersParams, type ListFavoritesParams, type ListFirearmsParams, type ListManufacturersParams, type ListReportsParams, type ListSnapshotFirearmsParams, type ListTicketsParams, type ListWebhookEndpointsParams, type LoadFirearmParams, type Manufacturer, type ManufacturerStats, type ManufacturerTimeline, ManufacturersResource, type MatchupResult, type MatchupsParams, NotFoundError, Page, type PageFetcher, type PaginatedResponse, type PaginationMeta, type PaginationParams, PermissionError, type PopularCalibersParams, type PowerRating, type PowerRatingParams, type ProlificManufacturersParams, type RandomFirearmParams, RateLimitError, type RateLimitInfo, ReportsResource, type RequestConfig, type ResolvedRetryConfig, type RetryConfig, type RoleRoster, type RoleRosterItem, type RoleRosterParams, type SearchFirearmsParams, type Silhouette, type SilhouetteParams, type SimilarFirearm, type StatDistribution, type StatDistributionParams, StatsResource, type StatsSummary, SupportResource, type SupportTicket, type SupportTicketDetail, type SupportTicketReply, type TierList, type TierListParams, type TimelineParams, TimeoutError, type TopFirearmsParams, type UpdateWebhookEndpointParams, type UsageParams, UsageResource, type UsageStats, VERSION, type WebhookEndpoint, type WebhookTestResult, WebhooksResource, buildAuthHeaders, createAPIError, createPage, resolveApiKey };