@buun_group/gunspec-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,2307 @@
+// src/core/auth.ts
+function readEnvKey() {
+  try {
+    if (typeof process !== "undefined" && process.env) {
+      return process.env.GUNSPEC_API_KEY;
+    }
+  } catch {
+  }
+  try {
+    const g = globalThis;
+    if (typeof g.Deno !== "undefined" && g.Deno.env) {
+      return g.Deno.env.get("GUNSPEC_API_KEY");
+    }
+  } catch {
+  }
+  return void 0;
+}
+function resolveApiKey(config) {
+  if (config.apiKey !== void 0 && config.apiKey !== "") {
+    return config.apiKey;
+  }
+  return readEnvKey();
+}
+function buildAuthHeaders(apiKey) {
+  const headers = {};
+  if (apiKey !== void 0 && apiKey !== "") {
+    headers["X-API-Key"] = apiKey;
+  }
+  return headers;
+}
+
+// src/core/errors.ts
+var GunSpecError = class extends Error {
+  name = "GunSpecError";
+  constructor(message) {
+    super(message);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var APIError = class extends GunSpecError {
+  name = "APIError";
+  /** HTTP status code returned by the API. */
+  status;
+  /** Machine-readable error code from the response body (e.g. `"NOT_FOUND"`). */
+  code;
+  /** The `X-Request-Id` header value, useful for support requests. */
+  requestId;
+  /** Raw response headers for further inspection. */
+  headers;
+  constructor(status, code, message, requestId, headers) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.headers = headers;
+  }
+};
+var AuthenticationError = class extends APIError {
+  name = "AuthenticationError";
+  constructor(code, message, requestId, headers) {
+    super(401, code, message, requestId, headers);
+  }
+};
+var PermissionError = class extends APIError {
+  name = "PermissionError";
+  constructor(code, message, requestId, headers) {
+    super(403, code, message, requestId, headers);
+  }
+};
+var NotFoundError = class extends APIError {
+  name = "NotFoundError";
+  constructor(code, message, requestId, headers) {
+    super(404, code, message, requestId, headers);
+  }
+};
+var BadRequestError = class extends APIError {
+  name = "BadRequestError";
+  constructor(code, message, requestId, headers) {
+    super(400, code, message, requestId, headers);
+  }
+};
+var RateLimitError = class extends APIError {
+  name = "RateLimitError";
+  /**
+   * Number of seconds the client should wait before retrying, or `null` if
+   * the server did not provide a `Retry-After` header.
+   */
+  retryAfter;
+  constructor(code, message, requestId, headers, retryAfter) {
+    super(429, code, message, requestId, headers);
+    this.retryAfter = retryAfter;
+  }
+};
+var InternalServerError = class extends APIError {
+  name = "InternalServerError";
+  constructor(code, message, requestId, headers) {
+    super(500, code, message, requestId, headers);
+  }
+};
+var ConnectionError = class extends GunSpecError {
+  name = "ConnectionError";
+  /** The original error thrown by `fetch`. */
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+  }
+};
+var TimeoutError = class extends GunSpecError {
+  name = "TimeoutError";
+  /** The timeout duration in milliseconds that was exceeded. */
+  timeoutMs;
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms`);
+    this.timeoutMs = timeoutMs;
+  }
+};
+function parseRetryAfter(headers) {
+  const raw = headers.get("Retry-After");
+  if (raw === null) return null;
+  const seconds = Number(raw);
+  if (!Number.isNaN(seconds) && seconds >= 0) return seconds;
+  const date = Date.parse(raw);
+  if (!Number.isNaN(date)) {
+    const delta = Math.ceil((date - Date.now()) / 1e3);
+    return delta > 0 ? delta : 0;
+  }
+  return null;
+}
+function createAPIError(status, body, requestId, headers) {
+  const code = body?.error?.code ?? `HTTP_${status}`;
+  const message = body?.error?.message ?? `Request failed with status ${status}`;
+  switch (status) {
+    case 400:
+      return new BadRequestError(code, message, requestId, headers);
+    case 401:
+      return new AuthenticationError(code, message, requestId, headers);
+    case 403:
+      return new PermissionError(code, message, requestId, headers);
+    case 404:
+      return new NotFoundError(code, message, requestId, headers);
+    case 429:
+      return new RateLimitError(code, message, requestId, headers, parseRetryAfter(headers));
+    case 500:
+      return new InternalServerError(code, message, requestId, headers);
+    default:
+      return new APIError(status, code, message, requestId, headers);
+  }
+}
+
+// src/core/retry.ts
+var DEFAULTS = {
+  maxRetries: 2,
+  initialDelayMs: 500,
+  maxDelayMs: 8e3,
+  multiplier: 2
+};
+var IDEMPOTENT_METHODS = /* @__PURE__ */ new Set(["GET", "PUT", "DELETE"]);
+var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+function resolveRetryConfig(config) {
+  return {
+    maxRetries: config?.maxRetries ?? DEFAULTS.maxRetries,
+    initialDelayMs: config?.initialDelayMs ?? DEFAULTS.initialDelayMs,
+    maxDelayMs: config?.maxDelayMs ?? DEFAULTS.maxDelayMs,
+    multiplier: config?.multiplier ?? DEFAULTS.multiplier
+  };
+}
+function isRetryable(error, method) {
+  if (!IDEMPOTENT_METHODS.has(method.toUpperCase())) {
+    return false;
+  }
+  if (error instanceof ConnectionError || error instanceof TimeoutError) {
+    return true;
+  }
+  if (error instanceof APIError) {
+    return RETRYABLE_STATUS_CODES.has(error.status);
+  }
+  return false;
+}
+function computeDelay(attempt, config, error) {
+  const base = config.initialDelayMs * Math.pow(config.multiplier, attempt);
+  const jitter = 1 + (Math.random() * 0.4 - 0.2);
+  let delay = Math.min(base * jitter, config.maxDelayMs);
+  if (error instanceof RateLimitError && error.retryAfter !== null) {
+    const retryAfterMs = error.retryAfter * 1e3;
+    delay = Math.max(delay, retryAfterMs);
+  }
+  return Math.round(delay);
+}
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
+      },
+      { once: true }
+    );
+  });
+}
+async function withRetry(fn, method, config, signal) {
+  let lastError;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      const isLastAttempt = attempt === config.maxRetries;
+      if (isLastAttempt || !isRetryable(error, method)) {
+        throw error;
+      }
+      const delay = computeDelay(attempt, config, error);
+      await sleep(delay, signal);
+    }
+  }
+  throw lastError;
+}
+
+// src/core/http-client.ts
+var DEFAULT_BASE_URL = "https://api.gunspec.io";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var SDK_USER_AGENT = "@gunspec/sdk";
+function serialiseQuery(params) {
+  const parts = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(item)}`);
+      }
+    } else {
+      parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+    }
+  }
+  return parts.length > 0 ? `?${parts.join("&")}` : "";
+}
+function parseRateLimitHeaders(headers) {
+  const parse = (name) => {
+    const raw = headers.get(name);
+    if (raw === null) return null;
+    const num = Number(raw);
+    return Number.isNaN(num) ? null : num;
+  };
+  return {
+    limit: parse("X-RateLimit-Limit"),
+    remaining: parse("X-RateLimit-Remaining"),
+    reset: parse("X-RateLimit-Reset")
+  };
+}
+function extractRequestId(headers) {
+  return headers.get("X-Request-Id") ?? "";
+}
+function composeSignals(timeoutMs, externalSignal) {
+  const timeoutController = new AbortController();
+  const timer = setTimeout(() => timeoutController.abort(new TimeoutError(timeoutMs)), timeoutMs);
+  if (typeof AbortSignal !== "undefined" && "any" in AbortSignal) {
+    const signals = [timeoutController.signal];
+    if (externalSignal) signals.push(externalSignal);
+    const composed2 = AbortSignal.any(signals);
+    return {
+      signal: composed2,
+      cleanup: () => clearTimeout(timer)
+    };
+  }
+  const composed = new AbortController();
+  const onTimeoutAbort = () => composed.abort(timeoutController.signal.reason);
+  const onExternalAbort = () => {
+    if (externalSignal) composed.abort(externalSignal.reason);
+  };
+  timeoutController.signal.addEventListener("abort", onTimeoutAbort, { once: true });
+  externalSignal?.addEventListener("abort", onExternalAbort, { once: true });
+  return {
+    signal: composed.signal,
+    cleanup: () => {
+      clearTimeout(timer);
+      timeoutController.signal.removeEventListener("abort", onTimeoutAbort);
+      externalSignal?.removeEventListener("abort", onExternalAbort);
+    }
+  };
+}
+var HttpClient = class {
+  baseUrl;
+  defaultTimeout;
+  defaultHeaders;
+  apiKey;
+  retryConfig;
+  constructor(config = {}) {
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.defaultTimeout = config.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.apiKey = resolveApiKey(config.auth ?? {});
+    this.retryConfig = resolveRetryConfig(config.retry);
+    this.defaultHeaders = {
+      "Accept": "application/json",
+      "User-Agent": SDK_USER_AGENT,
+      ...config.headers
+    };
+  }
+  /**
+   * 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.
+   */
+  async request(config) {
+    return withRetry(
+      () => this.executeRequest(config),
+      config.method,
+      this.retryConfig,
+      config.signal
+    );
+  }
+  /**
+   * 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.
+   */
+  async requestPaginated(config) {
+    return withRetry(
+      () => this.executePaginatedRequest(config),
+      config.method,
+      this.retryConfig,
+      config.signal
+    );
+  }
+  /**
+   * Convenience wrapper for a GET request returning a single resource.
+   */
+  async get(path, query) {
+    return this.request({ method: "GET", path, query });
+  }
+  /**
+   * Convenience wrapper for a GET request returning a paginated list.
+   */
+  async getPaginated(path, query) {
+    return this.requestPaginated({ method: "GET", path, query });
+  }
+  /**
+   * Convenience wrapper for a POST request.
+   */
+  async post(path, body, query) {
+    return this.request({ method: "POST", path, body, query });
+  }
+  /**
+   * Convenience wrapper for a PUT request.
+   */
+  async put(path, body, query) {
+    return this.request({ method: "PUT", path, body, query });
+  }
+  /**
+   * Convenience wrapper for a DELETE request.
+   */
+  async delete(path, query) {
+    return this.request({ method: "DELETE", path, query });
+  }
+  // -----------------------------------------------------------------------
+  // Internal execution
+  // -----------------------------------------------------------------------
+  async executeRequest(config) {
+    const response = await this.doFetch(config);
+    const requestId = extractRequestId(response.headers);
+    const rateLimit = parseRateLimitHeaders(response.headers);
+    if (!response.ok) {
+      await this.throwAPIError(response, requestId);
+    }
+    const json = await response.json();
+    return {
+      data: json.data,
+      status: response.status,
+      headers: response.headers,
+      requestId,
+      rateLimit
+    };
+  }
+  async executePaginatedRequest(config) {
+    const response = await this.doFetch(config);
+    const requestId = extractRequestId(response.headers);
+    const rateLimit = parseRateLimitHeaders(response.headers);
+    if (!response.ok) {
+      await this.throwAPIError(response, requestId);
+    }
+    const json = await response.json();
+    return {
+      data: json.data,
+      pagination: json.pagination,
+      status: response.status,
+      headers: response.headers,
+      requestId,
+      rateLimit
+    };
+  }
+  /**
+   * Perform the raw `fetch` call with merged headers, query string, timeout,
+   * and body serialisation.
+   */
+  async doFetch(config) {
+    const url = this.buildUrl(config.path, config.query);
+    const timeoutMs = config.timeout ?? this.defaultTimeout;
+    const { signal, cleanup } = composeSignals(timeoutMs, config.signal);
+    const headers = {
+      ...this.defaultHeaders,
+      ...buildAuthHeaders(this.apiKey),
+      ...config.headers
+    };
+    if (config.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    try {
+      const response = await fetch(url, {
+        method: config.method,
+        headers,
+        body: config.body !== void 0 ? JSON.stringify(config.body) : void 0,
+        signal
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof TimeoutError) {
+        throw error;
+      }
+      if (error instanceof DOMException && error.name === "AbortError") {
+        if (config.signal?.aborted) {
+          throw error;
+        }
+        throw new TimeoutError(timeoutMs);
+      }
+      throw new ConnectionError(
+        error instanceof Error ? error.message : "Network request failed",
+        error
+      );
+    } finally {
+      cleanup();
+    }
+  }
+  /**
+   * Build the full URL from base URL, path, and query parameters.
+   */
+  buildUrl(path, query) {
+    const qs = query ? serialiseQuery(query) : "";
+    return `${this.baseUrl}${path}${qs}`;
+  }
+  /**
+   * Parse an error response body and throw the appropriate {@link APIError}.
+   */
+  async throwAPIError(response, requestId) {
+    let body = null;
+    try {
+      body = await response.json();
+    } catch {
+    }
+    throw createAPIError(response.status, body, requestId, response.headers);
+  }
+};
+
+// src/resources/firearms.ts
+var FirearmsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  // ---------------------------------------------------------------------------
+  // Collection endpoints
+  // ---------------------------------------------------------------------------
+  /**
+   * 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);
+   * ```
+   */
+  async list(params) {
+    return this.client.getPaginated("/v1/firearms", params);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async *listAutoPaging(params) {
+    let page = params?.page ?? 1;
+    while (true) {
+      const result = await this.list({ ...params, page });
+      for (const item of result.data) {
+        yield item;
+      }
+      if (!result.pagination.totalPages || page >= result.pagination.totalPages) break;
+      page++;
+    }
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async search(params) {
+    return this.client.getPaginated("/v1/firearms/search", params);
+  }
+  /**
+   * 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
+   * ```
+   */
+  async compare(params) {
+    return this.client.get("/v1/firearms/compare", params);
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async gameMeta(params) {
+    return this.client.get("/v1/firearms/game-meta", params);
+  }
+  /**
+   * 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', ...]
+   * ```
+   */
+  async actionTypes() {
+    return this.client.get("/v1/firearms/action-types");
+  }
+  /**
+   * 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', ...]
+   * ```
+   */
+  async filterOptions() {
+    return this.client.get("/v1/firearms/filter-options");
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async random(params) {
+    return this.client.get("/v1/firearms/random", params);
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async top(params) {
+    return this.client.get("/v1/firearms/top", params);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async headToHead(params) {
+    return this.client.get("/v1/firearms/head-to-head", params);
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async byFeature(params) {
+    return this.client.getPaginated("/v1/firearms/by-feature", params);
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async byAction(params) {
+    return this.client.getPaginated("/v1/firearms/by-action", params);
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async byMaterial(params) {
+    return this.client.getPaginated("/v1/firearms/by-material", params);
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async byDesigner(params) {
+    return this.client.getPaginated("/v1/firearms/by-designer", params);
+  }
+  /**
+   * 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}`);
+   * }
+   * ```
+   */
+  async powerRating(params) {
+    return this.client.getPaginated("/v1/firearms/power-rating", params);
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  async timeline(params) {
+    return this.client.getPaginated("/v1/firearms/timeline", params);
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async byConflict(params) {
+    return this.client.getPaginated("/v1/firearms/by-conflict", params);
+  }
+  // ---------------------------------------------------------------------------
+  // Single-resource endpoints
+  // ---------------------------------------------------------------------------
+  /**
+   * 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"
+   * ```
+   */
+  async get(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}`);
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async getVariants(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}/variants`);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async getImages(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}/images`);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getGameStats(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}/game-stats`);
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async getDimensions(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}/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);
+   * }
+   * ```
+   */
+  async getUsers(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}/users`);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getFamilyTree(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}/family-tree`);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async getSimilar(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}/similar`);
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async getAdoptionMap(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}/adoption-map`);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getGameProfile(id) {
+    return this.client.get(`/v1/firearms/${encodeURIComponent(id)}/game-profile`);
+  }
+  /**
+   * 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
+   * ```
+   */
+  async getSilhouette(id, params) {
+    return this.client.get(
+      `/v1/firearms/${encodeURIComponent(id)}/silhouette`,
+      params
+    );
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async calculate(id, params) {
+    return this.client.get(
+      `/v1/firearms/${encodeURIComponent(id)}/calculate`,
+      params
+    );
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async load(id, params) {
+    return this.client.get(
+      `/v1/firearms/${encodeURIComponent(id)}/load`,
+      params
+    );
+  }
+};
+
+// src/resources/manufacturers.ts
+var ManufacturersResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async list(params) {
+    return this.client.getPaginated("/v1/manufacturers", params);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async *listAutoPaging(params) {
+    let page = params?.page ?? 1;
+    while (true) {
+      const result = await this.list({ ...params, page });
+      for (const item of result.data) {
+        yield item;
+      }
+      if (!result.pagination.totalPages || page >= result.pagination.totalPages) break;
+      page++;
+    }
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async get(id) {
+    return this.client.get(`/v1/manufacturers/${encodeURIComponent(id)}`);
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async getFirearms(id, params) {
+    return this.client.getPaginated(
+      `/v1/manufacturers/${encodeURIComponent(id)}/firearms`,
+      params
+    );
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async getTimeline(id) {
+    return this.client.get(`/v1/manufacturers/${encodeURIComponent(id)}/timeline`);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getStats(id) {
+    return this.client.get(`/v1/manufacturers/${encodeURIComponent(id)}/stats`);
+  }
+};
+
+// src/resources/calibers.ts
+var CalibersResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async list(params) {
+    return this.client.getPaginated("/v1/calibers", params);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async *listAutoPaging(params) {
+    let page = params?.page ?? 1;
+    while (true) {
+      const result = await this.list({ ...params, page });
+      for (const item of result.data) {
+        yield item;
+      }
+      if (!result.pagination.totalPages || page >= result.pagination.totalPages) break;
+      page++;
+    }
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async compare(params) {
+    return this.client.get("/v1/calibers/compare", params);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async ballistics(params) {
+    return this.client.get("/v1/calibers/ballistics", params);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async get(id) {
+    return this.client.get(`/v1/calibers/${encodeURIComponent(id)}`);
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async getFirearms(id, params) {
+    return this.client.getPaginated(
+      `/v1/calibers/${encodeURIComponent(id)}/firearms`,
+      params
+    );
+  }
+  /**
+   * 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, ...]
+   * ```
+   */
+  async getParentChain(id) {
+    return this.client.get(`/v1/calibers/${encodeURIComponent(id)}/parent-chain`);
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async getFamily(id) {
+    return this.client.get(`/v1/calibers/${encodeURIComponent(id)}/family`);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async getAmmunition(id, params) {
+    return this.client.getPaginated(
+      `/v1/calibers/${encodeURIComponent(id)}/ammunition`,
+      params
+    );
+  }
+};
+
+// src/resources/categories.ts
+var CategoriesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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' }, ...]
+   * ```
+   */
+  async list() {
+    return this.client.get("/v1/categories");
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async getFirearms(slug, params) {
+    return this.client.getPaginated(
+      `/v1/categories/${encodeURIComponent(slug)}/firearms`,
+      params
+    );
+  }
+};
+
+// src/resources/stats.ts
+var StatsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async summary() {
+    return this.client.get("/v1/stats/summary");
+  }
+  /**
+   * 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 }
+   * ```
+   */
+  async productionStatus() {
+    return this.client.get("/v1/stats/production-status");
+  }
+  /**
+   * 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`);
+   * ```
+   */
+  async fieldCoverage() {
+    return this.client.get("/v1/stats/field-coverage");
+  }
+  /**
+   * 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`);
+   * }
+   * ```
+   */
+  async popularCalibers(params) {
+    return this.client.get("/v1/stats/calibers/popular", params);
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async prolificManufacturers(params) {
+    return this.client.get("/v1/stats/manufacturers/prolific", params);
+  }
+  /**
+   * 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 }, ...]
+   * ```
+   */
+  async byCategory() {
+    return this.client.get("/v1/stats/by-category");
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async byEra(params) {
+    return this.client.get("/v1/stats/by-era", params);
+  }
+  /**
+   * 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();
+   * ```
+   */
+  async materials() {
+    return this.client.get("/v1/stats/materials");
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async adoptionByCountry(params) {
+    return this.client.get("/v1/stats/adoption/by-country", params);
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async adoptionByType(params) {
+    return this.client.get("/v1/stats/adoption/by-type", params);
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async actionTypes(params) {
+    return this.client.get("/v1/stats/action-types", params);
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async featureFrequency(params) {
+    return this.client.get("/v1/stats/feature-frequency", params);
+  }
+  /**
+   * 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',
+   * });
+   * ```
+   */
+  async caliberPopularityByEra(params) {
+    return this.client.get("/v1/stats/caliber-popularity-by-era", params);
+  }
+};
+
+// src/resources/game.ts
+var GameResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async balanceReport(params) {
+    return this.client.get("/v1/game/balance-report", params);
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async tierList(params) {
+    return this.client.get("/v1/game/tier-list", params);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async matchups(params) {
+    return this.client.get("/v1/game/matchups", params);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async roleRoster(params) {
+    return this.client.get("/v1/game/role-roster", params);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async statDistribution(params) {
+    return this.client.get("/v1/game/stat-distribution", params);
+  }
+};
+
+// src/resources/game-stats.ts
+var GameStatsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async listVersions() {
+    return this.client.get("/v1/game-stats/versions");
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async listFirearms(version, params) {
+    return this.client.getPaginated(
+      `/v1/game-stats/versions/${encodeURIComponent(version)}/firearms`,
+      params
+    );
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getFirearm(version, id) {
+    return this.client.get(
+      `/v1/game-stats/versions/${encodeURIComponent(version)}/firearms/${encodeURIComponent(id)}`
+    );
+  }
+};
+
+// src/resources/ammunition.ts
+var AmmunitionResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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,
+   * });
+   * ```
+   */
+  async list(params) {
+    return this.client.getPaginated("/v1/ammunition", params);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async *listAutoPaging(params) {
+    let page = params?.page ?? 1;
+    while (true) {
+      const result = await this.list({ ...params, page });
+      for (const item of result.data) {
+        yield item;
+      }
+      if (!result.pagination.totalPages || page >= result.pagination.totalPages) break;
+      page++;
+    }
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async get(id) {
+    return this.client.get(`/v1/ammunition/${encodeURIComponent(id)}`);
+  }
+  /**
+   * 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;
+   * ```
+   */
+  async getBulletSvg(id) {
+    const response = await this.client.get(
+      `/v1/ammunition/${encodeURIComponent(id)}/bullet.svg`
+    );
+    return response.data;
+  }
+  /**
+   * 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`);
+   * }
+   * ```
+   */
+  async ballistics(id, params) {
+    return this.client.get(
+      `/v1/ammunition/${encodeURIComponent(id)}/ballistics`,
+      params
+    );
+  }
+};
+
+// src/resources/countries.ts
+var CountriesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async list() {
+    return this.client.get("/v1/countries");
+  }
+  /**
+   * 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`);
+   * }
+   * ```
+   */
+  async getArsenal(code) {
+    return this.client.get(`/v1/countries/${encodeURIComponent(code)}/arsenal`);
+  }
+};
+
+// src/resources/conflicts.ts
+var ConflictsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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' });
+   * ```
+   */
+  async list() {
+    return this.client.get("/v1/conflicts");
+  }
+};
+
+// src/resources/data-quality.ts
+var DataQualityResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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}%`);
+   * }
+   * ```
+   */
+  async coverage() {
+    return this.client.get("/v1/data/coverage");
+  }
+  /**
+   * 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}`);
+   * }
+   * ```
+   */
+  async confidence(params) {
+    return this.client.getPaginated("/v1/data/confidence", params);
+  }
+};
+
+// src/resources/favorites.ts
+var FavoritesResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async list(params) {
+    return this.client.getPaginated("/v1/me/favorites", params);
+  }
+  async add(firearmId) {
+    return this.client.post(`/v1/me/favorites/${encodeURIComponent(firearmId)}`);
+  }
+  async remove(firearmId) {
+    return this.client.delete(`/v1/me/favorites/${encodeURIComponent(firearmId)}`);
+  }
+};
+
+// src/resources/reports.ts
+var ReportsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async create(params) {
+    return this.client.post("/v1/me/reports", params);
+  }
+  async list(params) {
+    return this.client.getPaginated("/v1/me/reports", params);
+  }
+};
+
+// src/resources/support.ts
+var SupportResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async create(params) {
+    return this.client.post("/v1/me/support", params);
+  }
+  async list(params) {
+    return this.client.getPaginated("/v1/me/support", params);
+  }
+  async get(ticketId) {
+    return this.client.get(`/v1/me/support/${encodeURIComponent(ticketId)}`);
+  }
+  async reply(ticketId, params) {
+    return this.client.post(`/v1/me/support/${encodeURIComponent(ticketId)}/replies`, params);
+  }
+};
+
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async list(params) {
+    return this.client.getPaginated("/v1/me/webhooks", params);
+  }
+  async create(params) {
+    return this.client.post("/v1/me/webhooks", params);
+  }
+  async get(id) {
+    return this.client.get(`/v1/me/webhooks/${encodeURIComponent(id)}`);
+  }
+  async update(id, params) {
+    return this.client.put(`/v1/me/webhooks/${encodeURIComponent(id)}`, params);
+  }
+  async delete(id) {
+    return this.client.delete(`/v1/me/webhooks/${encodeURIComponent(id)}`);
+  }
+  async test(id) {
+    return this.client.post(`/v1/me/webhooks/${encodeURIComponent(id)}/test`);
+  }
+};
+
+// src/resources/usage.ts
+var UsageResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async get(params) {
+    return this.client.get("/v1/me/usage", params);
+  }
+};
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/client.ts
+var GunSpec = class {
+  /** Firearms specifications, search, comparison, and related data */
+  firearms;
+  /** Firearm manufacturers and their products */
+  manufacturers;
+  /** Ammunition calibers and cartridge specifications */
+  calibers;
+  /** Firearm categories (pistol, rifle, shotgun, etc.) */
+  categories;
+  /** Aggregate statistics across the database */
+  stats;
+  /** Game development tools — balance reports, tier lists, matchups */
+  game;
+  /** Versioned game stats snapshots for pinning game builds */
+  gameStats;
+  /** Ammunition loads, ballistics, and bullet data */
+  ammunition;
+  /** Countries and their military/law enforcement arsenals */
+  countries;
+  /** Armed conflicts and the firearms used in them */
+  conflicts;
+  /** Data quality metrics (Enterprise tier) */
+  dataQuality;
+  /** User's favorited firearms */
+  favorites;
+  /** Data quality reports */
+  reports;
+  /** Support tickets (paid tiers) */
+  support;
+  /** Webhook endpoint management (studio+ tier) */
+  webhooks;
+  /** API usage statistics */
+  usage;
+  /** The underlying HTTP client (for advanced use) */
+  _client;
+  constructor(options = {}) {
+    this._client = new HttpClient({
+      baseUrl: options.baseURL ?? "https://api.gunspec.io",
+      timeout: options.timeout ?? 3e4,
+      auth: {
+        apiKey: options.apiKey
+      },
+      retry: options.retry,
+      headers: {
+        ...options.defaultHeaders,
+        "User-Agent": `gunspec-sdk/typescript/${VERSION}`,
+        "X-SDK-Version": VERSION,
+        "X-SDK-Language": "typescript"
+      }
+    });
+    this.firearms = new FirearmsResource(this._client);
+    this.manufacturers = new ManufacturersResource(this._client);
+    this.calibers = new CalibersResource(this._client);
+    this.categories = new CategoriesResource(this._client);
+    this.stats = new StatsResource(this._client);
+    this.game = new GameResource(this._client);
+    this.gameStats = new GameStatsResource(this._client);
+    this.ammunition = new AmmunitionResource(this._client);
+    this.countries = new CountriesResource(this._client);
+    this.conflicts = new ConflictsResource(this._client);
+    this.dataQuality = new DataQualityResource(this._client);
+    this.favorites = new FavoritesResource(this._client);
+    this.reports = new ReportsResource(this._client);
+    this.support = new SupportResource(this._client);
+    this.webhooks = new WebhooksResource(this._client);
+    this.usage = new UsageResource(this._client);
+  }
+};
+
+// src/core/pagination.ts
+var Page = class _Page {
+  /** The items on this page. */
+  data;
+  /** Pagination metadata returned by the server. */
+  pagination;
+  /** The request ID for this page's HTTP response. */
+  requestId;
+  /** The base query parameters used to fetch this page (without `page`). */
+  baseQuery;
+  /** The fetcher function used to retrieve subsequent pages. */
+  fetcher;
+  /**
+   * @internal
+   * Consumers should not construct `Page` instances directly.  Use the
+   * resource methods on the high-level client instead.
+   */
+  constructor(response, baseQuery, fetcher) {
+    this.data = response.data;
+    this.pagination = response.pagination;
+    this.requestId = response.requestId;
+    this.baseQuery = baseQuery;
+    this.fetcher = fetcher;
+  }
+  /**
+   * 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() {
+    if (this.pagination.totalPages !== void 0) {
+      return this.pagination.page < this.pagination.totalPages;
+    }
+    return this.data.length >= this.pagination.limit;
+  }
+  /**
+   * 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.
+   */
+  async getNextPage() {
+    if (!this.hasNextPage()) {
+      throw new Error("No more pages available. Check hasNextPage() before calling getNextPage().");
+    }
+    const nextQuery = {
+      ...this.baseQuery,
+      page: this.pagination.page + 1
+    };
+    const response = await this.fetcher(nextQuery);
+    return new _Page(response, this.baseQuery, this.fetcher);
+  }
+  /**
+   * 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.
+   */
+  async getPreviousPage() {
+    if (this.pagination.page <= 1) {
+      throw new Error("Already on the first page. Cannot navigate to a previous page.");
+    }
+    const prevQuery = {
+      ...this.baseQuery,
+      page: this.pagination.page - 1
+    };
+    const response = await this.fetcher(prevQuery);
+    return new _Page(response, this.baseQuery, this.fetcher);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async *[Symbol.asyncIterator]() {
+    let current = this;
+    while (true) {
+      for (const item of current.data) {
+        yield item;
+      }
+      if (!current.hasNextPage()) {
+        break;
+      }
+      current = await current.getNextPage();
+    }
+  }
+};
+function createPage(response, baseQuery, fetcher) {
+  return new Page(response, baseQuery, fetcher);
+}
+
+export { APIError, AmmunitionResource, AuthenticationError, BadRequestError, CalibersResource, CategoriesResource, ConflictsResource, ConnectionError, CountriesResource, DataQualityResource, FavoritesResource, FirearmsResource, GameResource, GameStatsResource, GunSpec, GunSpecError, HttpClient, InternalServerError, ManufacturersResource, NotFoundError, Page, PermissionError, RateLimitError, ReportsResource, StatsResource, SupportResource, TimeoutError, UsageResource, VERSION, WebhooksResource, buildAuthHeaders, createAPIError, createPage, resolveApiKey };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map