@carddb/client 0.1.0

package/dist/index.js

@@ -0,0 +1,1219 @@
+import { RestrictedError, RateLimitError, ServerError, ConnectionError, TimeoutError, CardDBError, AuthenticationError, GraphQLError, ValidationError, QueryBuilder, Collection, resolveFilter } from '@carddb/core';
+export * from '@carddb/core';
+
+// src/client.ts
+var DEFAULT_ENDPOINT = "https://carddb.xtda.org/query";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_OPEN_TIMEOUT = 1e4;
+var DEFAULT_CACHE_TTL = 300;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_MAX_NETWORK_RETRIES = 2;
+var DEFAULT_RETRY_BASE_DELAY = 1e3;
+var DEFAULT_RETRY_MAX_DELAY = 3e4;
+var Configuration = class _Configuration {
+  apiKey;
+  endpoint;
+  timeout;
+  openTimeout;
+  defaultPublisher;
+  defaultGame;
+  allowedPublishers;
+  allowedGames;
+  logger;
+  logLevel;
+  retryOnRateLimit;
+  maxRetries;
+  retryOnNetworkError;
+  maxNetworkRetries;
+  retryBaseDelay;
+  retryMaxDelay;
+  cache;
+  cacheTtl;
+  cacheTtls;
+  constructor(config = {}) {
+    this.apiKey = config.apiKey;
+    this.endpoint = config.endpoint ?? DEFAULT_ENDPOINT;
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.openTimeout = config.openTimeout ?? DEFAULT_OPEN_TIMEOUT;
+    this.defaultPublisher = config.defaultPublisher;
+    this.defaultGame = config.defaultGame;
+    this.allowedPublishers = config.allowedPublishers;
+    this.allowedGames = config.allowedGames;
+    this.logger = config.logger;
+    this.logLevel = config.logLevel ?? "info";
+    this.retryOnRateLimit = config.retryOnRateLimit ?? false;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.retryOnNetworkError = config.retryOnNetworkError ?? true;
+    this.maxNetworkRetries = config.maxNetworkRetries ?? DEFAULT_MAX_NETWORK_RETRIES;
+    this.retryBaseDelay = config.retryBaseDelay ?? DEFAULT_RETRY_BASE_DELAY;
+    this.retryMaxDelay = config.retryMaxDelay ?? DEFAULT_RETRY_MAX_DELAY;
+    this.cache = config.cache;
+    this.cacheTtl = config.cacheTtl ?? DEFAULT_CACHE_TTL;
+    this.cacheTtls = config.cacheTtls ?? {};
+  }
+  /**
+   * Calculate delay for exponential backoff
+   * @param attempt - The attempt number (0-indexed)
+   * @returns Delay in milliseconds with jitter
+   */
+  calculateRetryDelay(attempt) {
+    const exponentialDelay = this.retryBaseDelay * Math.pow(2, attempt);
+    const cappedDelay = Math.min(exponentialDelay, this.retryMaxDelay);
+    const jitter = cappedDelay * 0.25 * (Math.random() * 2 - 1);
+    return Math.round(cappedDelay + jitter);
+  }
+  /**
+   * Get the cache TTL for a specific resource type
+   */
+  cacheTtlFor(resource) {
+    return this.cacheTtls[resource] ?? this.cacheTtl;
+  }
+  /**
+   * Resolve publisher slug, using default if not provided
+   */
+  resolvePublisher(publisherSlug) {
+    return publisherSlug ?? this.defaultPublisher;
+  }
+  /**
+   * Resolve game key, using default if not provided
+   */
+  resolveGame(gameKey) {
+    return gameKey ?? this.defaultGame;
+  }
+  /**
+   * Validate that a publisher is allowed by the configuration
+   */
+  validatePublisher(publisherSlug) {
+    if (!this.allowedPublishers) return;
+    if (this.allowedPublishers.includes(publisherSlug)) return;
+    throw new RestrictedError(
+      `Publisher '${publisherSlug}' is not in the allowed publishers list`
+    );
+  }
+  /**
+   * Validate that a game is allowed by the configuration
+   */
+  validateGame(publisherSlug, gameKey) {
+    if (!this.allowedGames) return;
+    const allowedForPublisher = this.allowedGames[publisherSlug];
+    if (!allowedForPublisher) return;
+    if (allowedForPublisher.includes(gameKey)) return;
+    throw new RestrictedError(
+      `Game '${gameKey}' is not allowed for publisher '${publisherSlug}'`
+    );
+  }
+  /**
+   * Validate both publisher and game access
+   */
+  validateAccess(publisherSlug, gameKey) {
+    if (publisherSlug) {
+      this.validatePublisher(publisherSlug);
+      if (gameKey) {
+        this.validateGame(publisherSlug, gameKey);
+      }
+    }
+  }
+  /**
+   * Check if a log level should be logged
+   */
+  shouldLog(level) {
+    const levels = {
+      debug: 0,
+      info: 1,
+      warn: 2,
+      error: 3
+    };
+    return levels[level] >= levels[this.logLevel];
+  }
+  /**
+   * Create a copy of this configuration with overrides
+   */
+  merge(overrides) {
+    return new _Configuration({
+      apiKey: overrides.apiKey ?? this.apiKey,
+      endpoint: overrides.endpoint ?? this.endpoint,
+      timeout: overrides.timeout ?? this.timeout,
+      openTimeout: overrides.openTimeout ?? this.openTimeout,
+      defaultPublisher: overrides.defaultPublisher ?? this.defaultPublisher,
+      defaultGame: overrides.defaultGame ?? this.defaultGame,
+      allowedPublishers: overrides.allowedPublishers ?? this.allowedPublishers,
+      allowedGames: overrides.allowedGames ?? this.allowedGames,
+      logger: overrides.logger ?? this.logger,
+      logLevel: overrides.logLevel ?? this.logLevel,
+      retryOnRateLimit: overrides.retryOnRateLimit ?? this.retryOnRateLimit,
+      maxRetries: overrides.maxRetries ?? this.maxRetries,
+      retryOnNetworkError: overrides.retryOnNetworkError ?? this.retryOnNetworkError,
+      maxNetworkRetries: overrides.maxNetworkRetries ?? this.maxNetworkRetries,
+      retryBaseDelay: overrides.retryBaseDelay ?? this.retryBaseDelay,
+      retryMaxDelay: overrides.retryMaxDelay ?? this.retryMaxDelay,
+      cache: overrides.cache ?? this.cache,
+      cacheTtl: overrides.cacheTtl ?? this.cacheTtl,
+      cacheTtls: overrides.cacheTtls ?? this.cacheTtls
+    });
+  }
+};
+
+// src/user-agent.ts
+var SDK_VERSION = "0.1.0";
+function detectRuntime() {
+  if (typeof globalThis !== "undefined" && "Bun" in globalThis) {
+    const bunVersion = globalThis.Bun && typeof globalThis.Bun === "object" && globalThis.Bun.version;
+    return {
+      name: "bun",
+      version: typeof bunVersion === "string" ? bunVersion : "unknown"
+    };
+  }
+  if (typeof globalThis !== "undefined" && "Deno" in globalThis) {
+    const denoVersion = globalThis.Deno && typeof globalThis.Deno === "object" && globalThis.Deno.version && typeof globalThis.Deno.version === "object" && globalThis.Deno.version.deno;
+    return {
+      name: "deno",
+      version: typeof denoVersion === "string" ? denoVersion : "unknown"
+    };
+  }
+  if (typeof process !== "undefined" && process.versions && process.versions.node) {
+    return {
+      name: "node",
+      version: process.versions.node
+    };
+  }
+  if (typeof navigator !== "undefined" && navigator.userAgent) {
+    return detectBrowser(navigator.userAgent);
+  }
+  return { name: "unknown", version: "unknown" };
+}
+function detectBrowser(userAgent) {
+  const edgeMatch = userAgent.match(/Edg\/(\d+(?:\.\d+)*)/);
+  if (edgeMatch) {
+    return { name: "edge", version: edgeMatch[1] };
+  }
+  const chromeMatch = userAgent.match(/Chrome\/(\d+(?:\.\d+)*)/);
+  if (chromeMatch && !userAgent.includes("Edg/")) {
+    return { name: "chrome", version: chromeMatch[1] };
+  }
+  const firefoxMatch = userAgent.match(/Firefox\/(\d+(?:\.\d+)*)/);
+  if (firefoxMatch) {
+    return { name: "firefox", version: firefoxMatch[1] };
+  }
+  const safariMatch = userAgent.match(/Version\/(\d+(?:\.\d+)*).*Safari/);
+  if (safariMatch) {
+    return { name: "safari", version: safariMatch[1] };
+  }
+  return { name: "browser", version: "unknown" };
+}
+function getUserAgent() {
+  const runtime = detectRuntime();
+  return `CardDB-SDK/js/${SDK_VERSION} (${runtime.name}/${runtime.version})`;
+}
+function getSDKVersion() {
+  return SDK_VERSION;
+}
+
+// src/connection.ts
+var lastRateLimitInfo = null;
+function getRateLimitInfo() {
+  return lastRateLimitInfo;
+}
+var Connection = class {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Execute a GraphQL query
+   */
+  async execute(query, variables = {}) {
+    const operationName = this.extractOperationName(query);
+    let rateLimitRetries = 0;
+    let networkRetries = 0;
+    while (true) {
+      try {
+        const startTime = Date.now();
+        this.logRequest(operationName, variables);
+        const response = await this.fetch(query, variables);
+        const duration = Date.now() - startTime;
+        const result = await this.handleResponse(response);
+        this.logResponse(operationName, duration);
+        return result;
+      } catch (error) {
+        if (error instanceof RateLimitError) {
+          if (this.config.retryOnRateLimit && rateLimitRetries < this.config.maxRetries) {
+            rateLimitRetries++;
+            const sleepTime = error.retryAfter ?? 60;
+            this.logRateLimitRetry(operationName, rateLimitRetries, sleepTime);
+            await this.sleep(sleepTime * 1e3);
+            continue;
+          }
+        }
+        if (this.isRetryableNetworkError(error)) {
+          if (this.config.retryOnNetworkError && networkRetries < this.config.maxNetworkRetries) {
+            const delay = this.config.calculateRetryDelay(networkRetries);
+            this.logNetworkRetry(operationName, networkRetries + 1, delay, error);
+            networkRetries++;
+            await this.sleep(delay);
+            continue;
+          }
+        }
+        if (error instanceof ServerError) {
+          if (this.config.retryOnNetworkError && networkRetries < this.config.maxNetworkRetries) {
+            const delay = this.config.calculateRetryDelay(networkRetries);
+            this.logNetworkRetry(operationName, networkRetries + 1, delay, error);
+            networkRetries++;
+            await this.sleep(delay);
+            continue;
+          }
+        }
+        throw error;
+      }
+    }
+  }
+  /**
+   * Check if an error is a retryable network error
+   */
+  isRetryableNetworkError(error) {
+    return error instanceof ConnectionError || error instanceof TimeoutError;
+  }
+  async fetch(query, variables) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+    try {
+      const response = await fetch(this.config.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          "User-Agent": getUserAgent(),
+          ...this.config.apiKey ? { "X-API-Key": this.config.apiKey } : {}
+        },
+        body: JSON.stringify({ query, variables }),
+        signal: controller.signal
+      });
+      return response;
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error.name === "AbortError") {
+          this.logError("Request timed out");
+          throw new TimeoutError("Request timed out");
+        }
+        this.logError(`Connection failed: ${error.message}`);
+        throw new ConnectionError(`Connection failed: ${error.message}`);
+      }
+      throw new ConnectionError("Connection failed");
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  async handleResponse(response) {
+    this.extractRateLimitInfo(response);
+    switch (response.status) {
+      case 200:
+        return this.handleSuccessResponse(response);
+      case 401:
+        throw new AuthenticationError("Invalid or missing API key");
+      case 429:
+        return this.handleRateLimitResponse(response);
+      default:
+        if (response.status >= 400 && response.status < 500) {
+          return this.handleClientError(response);
+        }
+        if (response.status >= 500) {
+          const body = await this.parseBody(response);
+          throw new ServerError(`Server error (${response.status})`, {
+            status: response.status,
+            response: body
+          });
+        }
+        throw new CardDBError(`Unexpected response status: ${response.status}`);
+    }
+  }
+  async handleSuccessResponse(response) {
+    const body = await this.parseBody(response);
+    if (body.errors && body.errors.length > 0) {
+      this.handleGraphQLErrors(body.errors, body);
+    }
+    return body.data ?? {};
+  }
+  handleGraphQLErrors(errors, body) {
+    const firstError = errors[0];
+    const message = firstError.message || "GraphQL error";
+    const code = firstError.extensions?.["code"];
+    switch (code) {
+      case "UNAUTHENTICATED":
+        throw new AuthenticationError(message, body);
+      case "RATE_LIMITED":
+        throw new RateLimitError(message, { response: body });
+      case "NOT_FOUND":
+        throw new CardDBError(message, body);
+      case "VALIDATION_ERROR":
+      case "BAD_USER_INPUT":
+        throw new ValidationError(message, { errors, response: body });
+      default:
+        throw new GraphQLError(message, { errors, response: body });
+    }
+  }
+  async handleRateLimitResponse(response) {
+    const retryAfter = parseInt(response.headers.get("Retry-After") ?? "60", 10);
+    const limit = parseInt(response.headers.get("X-RateLimit-Limit") ?? "", 10) || null;
+    const remaining = parseInt(response.headers.get("X-RateLimit-Remaining") ?? "", 10) || null;
+    const reset = parseInt(response.headers.get("X-RateLimit-Reset") ?? "", 10) || null;
+    const resetAt = reset ? new Date(reset * 1e3) : null;
+    const body = await this.parseBody(response);
+    throw new RateLimitError("Rate limit exceeded", {
+      retryAfter,
+      limit,
+      remaining,
+      resetAt,
+      response: body
+    });
+  }
+  async handleClientError(response) {
+    const body = await this.parseBody(response);
+    const message = body.errors?.[0]?.message ?? `Client error (${response.status})`;
+    throw new ValidationError(message, { response: body });
+  }
+  async parseBody(response) {
+    try {
+      return await response.json();
+    } catch {
+      return { raw: await response.text() };
+    }
+  }
+  extractRateLimitInfo(response) {
+    const limit = parseInt(response.headers.get("X-RateLimit-Limit") ?? "", 10) || null;
+    const remaining = parseInt(response.headers.get("X-RateLimit-Remaining") ?? "", 10) || null;
+    const reset = parseInt(response.headers.get("X-RateLimit-Reset") ?? "", 10) || null;
+    lastRateLimitInfo = { limit, remaining, reset };
+  }
+  extractOperationName(query) {
+    const match = query.match(/(?:query|mutation)\s+(\w+)/);
+    return match ? match[1] : "Unknown";
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  // Logging helpers
+  logRequest(operationName, variables) {
+    if (!this.config.logger || !this.config.shouldLog("debug")) return;
+    this.config.logger.debug(`[CardDB] Executing ${operationName}`, { variables });
+  }
+  logResponse(operationName, duration) {
+    if (!this.config.logger || !this.config.shouldLog("info")) return;
+    this.config.logger.info(`[CardDB] ${operationName} completed in ${duration}ms`);
+  }
+  logRateLimitRetry(operationName, retry, sleepTime) {
+    if (!this.config.logger || !this.config.shouldLog("warn")) return;
+    this.config.logger.warn(
+      `[CardDB] Rate limited on ${operationName}, retry ${retry}/${this.config.maxRetries} after ${sleepTime}s`
+    );
+  }
+  logNetworkRetry(operationName, retry, delay, error) {
+    if (!this.config.logger || !this.config.shouldLog("warn")) return;
+    const errorType = error instanceof Error ? error.name : "Unknown";
+    this.config.logger.warn(
+      `[CardDB] ${errorType} on ${operationName}, retry ${retry}/${this.config.maxNetworkRetries} after ${delay}ms`
+    );
+  }
+  logError(message) {
+    if (!this.config.logger || !this.config.shouldLog("error")) return;
+    this.config.logger.error(`[CardDB] ${message}`);
+  }
+};
+
+// src/cache.ts
+function cacheKey(resource, method, params) {
+  const sortedParams = Object.entries(params).filter(([, v]) => v !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${JSON.stringify(v)}`).join("&");
+  return `carddb:${resource}:${method}:${sortedParams}`;
+}
+async function readCache(cache, key) {
+  const result = cache.get(key);
+  if (result instanceof Promise) {
+    return result;
+  }
+  return result;
+}
+async function writeCache(cache, key, value, ttl) {
+  const result = cache.set(key, value, ttl);
+  if (result instanceof Promise) {
+    await result;
+  }
+}
+
+// src/resources/base.ts
+var BaseResource = class {
+  connection;
+  config;
+  constructor(connection, config) {
+    this.connection = connection;
+    this.config = config;
+  }
+  /**
+   * Resolve publisher slug, using default if not provided
+   */
+  resolvePublisher(publisherSlug) {
+    const resolved = this.config.resolvePublisher(publisherSlug);
+    if (!resolved) {
+      throw new Error("publisher_slug is required (no default configured)");
+    }
+    return resolved;
+  }
+  /**
+   * Resolve game key, using default if not provided
+   */
+  resolveGame(gameKey) {
+    const resolved = this.config.resolveGame(gameKey);
+    if (!resolved) {
+      throw new Error("game_key is required (no default configured)");
+    }
+    return resolved;
+  }
+  /**
+   * Validate access to publisher/game
+   */
+  validateAccess(publisherSlug, gameKey) {
+    this.config.validateAccess(publisherSlug, gameKey);
+  }
+  /**
+   * Execute a query with optional caching
+   */
+  async withCache(key, resource, options, fn) {
+    const useCache = options.cache ?? !!this.config.cache;
+    const cache = this.config.cache;
+    if (!useCache || !cache) {
+      return fn();
+    }
+    const cached = await readCache(cache, key);
+    if (cached !== null) {
+      return cached;
+    }
+    const result = await fn();
+    if (result !== null && result !== void 0) {
+      const ttl = this.config.cacheTtlFor(resource);
+      await writeCache(cache, key, result, ttl);
+    }
+    return result;
+  }
+  /**
+   * Generate a cache key
+   */
+  cacheKey(resource, method, params) {
+    return cacheKey(resource, method, params);
+  }
+};
+
+// src/resources/publishers.ts
+var PublishersResource = class extends BaseResource {
+  constructor(connection, config) {
+    super(connection, config);
+  }
+  /**
+   * Search for publishers
+   *
+   * @example
+   * const publishers = await client.publishers.search({ search: 'pokemon' })
+   * for await (const publisher of publishers) {
+   *   console.log(publisher.name)
+   * }
+   */
+  async search(options = {}) {
+    const { query, variables } = QueryBuilder.searchPublishers({
+      search: options.search,
+      first: options.first,
+      after: options.after
+    });
+    const key = this.cacheKey("publishers", "search", variables);
+    const data = await this.withCache(key, "publishers", options, async () => {
+      const result = await this.connection.execute(query, variables);
+      return result["searchPublishers"];
+    });
+    return new Collection(data, {
+      nextPageLoader: async (cursor) => {
+        return this.search({ ...options, after: cursor });
+      }
+    });
+  }
+  /**
+   * Get a single publisher by slug or ID
+   *
+   * @example
+   * const publisher = await client.publishers.get('pokemon')
+   * const publisher = await client.publishers.get('550e8400-e29b-41d4-a716-446655440000')
+   */
+  async get(slugOrId, options = {}) {
+    const isUUID = this.isUUID(slugOrId);
+    const key = this.cacheKey("publishers", "get", { [isUUID ? "id" : "slug"]: slugOrId });
+    return this.withCache(key, "publishers", options, async () => {
+      if (isUUID) {
+        const { query } = QueryBuilder.fetchPublisherById();
+        const result = await this.connection.execute(query, { id: slugOrId });
+        return result["fetchPublisher"] ?? null;
+      } else {
+        const { query } = QueryBuilder.fetchPublisherBySlug();
+        const result = await this.connection.execute(query, { slug: slugOrId });
+        return result["fetchPublisher"] ?? null;
+      }
+    });
+  }
+  /**
+   * Get multiple publishers by slug
+   *
+   * @example
+   * const publishers = await client.publishers.getMany(['pokemon', 'wizards'])
+   */
+  async getMany(slugs, options = {}) {
+    if (slugs.length === 0) return [];
+    const key = this.cacheKey("publishers", "getMany", { slugs });
+    return this.withCache(key, "publishers", options, async () => {
+      const { query } = QueryBuilder.fetchPublishers();
+      const result = await this.connection.execute(query, { slugs });
+      return result["fetchPublishers"] ?? [];
+    });
+  }
+  /**
+   * Check if a string is a valid UUID
+   */
+  isUUID(value) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(value);
+  }
+};
+var GamesResource = class extends BaseResource {
+  constructor(connection, config) {
+    super(connection, config);
+  }
+  /**
+   * Search for games
+   *
+   * @example
+   * // Search all games
+   * const games = await client.games.search({ search: 'trading card' })
+   *
+   * // Search games from a specific publisher
+   * const games = await client.games.search({ publisherSlug: 'pokemon' })
+   */
+  async search(options = {}) {
+    const publisherSlug = this.config.resolvePublisher(options.publisherSlug);
+    if (publisherSlug) {
+      this.validateAccess(publisherSlug);
+    }
+    const { query, variables } = QueryBuilder.searchGames({
+      publisherSlug,
+      search: options.search,
+      first: options.first,
+      after: options.after
+    });
+    const key = this.cacheKey("games", "search", variables);
+    const data = await this.withCache(key, "games", options, async () => {
+      const result = await this.connection.execute(query, variables);
+      return result["searchGames"];
+    });
+    return new Collection(data, {
+      nextPageLoader: async (cursor) => {
+        return this.search({ ...options, after: cursor });
+      }
+    });
+  }
+  async get(idOrPublisherSlug, gameKeyOrOptions, options) {
+    if (typeof gameKeyOrOptions === "string") {
+      const publisherSlug = idOrPublisherSlug;
+      const gameKey = gameKeyOrOptions;
+      const opts = options ?? {};
+      this.validateAccess(publisherSlug, gameKey);
+      const key = this.cacheKey("games", "getByKeys", { publisherSlug, gameKey });
+      return this.withCache(key, "games", opts, async () => {
+        const { query } = QueryBuilder.fetchGameByKeys();
+        const result = await this.connection.execute(query, { publisherSlug, gameKey });
+        return result["fetchGame"] ?? null;
+      });
+    } else {
+      const id = idOrPublisherSlug;
+      const opts = gameKeyOrOptions ?? {};
+      const key = this.cacheKey("games", "get", { id });
+      return this.withCache(key, "games", opts, async () => {
+        const { query } = QueryBuilder.fetchGameById();
+        const result = await this.connection.execute(query, { id });
+        return result["fetchGame"] ?? null;
+      });
+    }
+  }
+  /**
+   * Get multiple games by ID
+   *
+   * @example
+   * const games = await client.games.getMany(['id1', 'id2', 'id3'])
+   */
+  async getMany(ids, options = {}) {
+    if (ids.length === 0) return [];
+    const key = this.cacheKey("games", "getMany", { ids });
+    return this.withCache(key, "games", options, async () => {
+      const { query } = QueryBuilder.fetchGames();
+      const result = await this.connection.execute(query, { ids });
+      return result["fetchGames"] ?? [];
+    });
+  }
+};
+var DatasetsResource = class extends BaseResource {
+  constructor(connection, config) {
+    super(connection, config);
+  }
+  /**
+   * Search for datasets
+   *
+   * @example
+   * // Search all datasets
+   * const datasets = await client.datasets.search({ search: 'cards' })
+   *
+   * // Search datasets from a specific publisher and game
+   * const datasets = await client.datasets.search({
+   *   publisherSlug: 'pokemon',
+   *   gameKey: 'tcg'
+   * })
+   */
+  async search(options = {}) {
+    const publisherSlug = this.config.resolvePublisher(options.publisherSlug);
+    const gameKey = this.config.resolveGame(options.gameKey);
+    if (publisherSlug) {
+      this.validateAccess(publisherSlug, gameKey);
+    }
+    const { query, variables } = QueryBuilder.searchDatasets({
+      publisherSlug,
+      gameKey,
+      search: options.search,
+      purpose: options.purpose,
+      first: options.first,
+      after: options.after
+    });
+    const key = this.cacheKey("datasets", "search", variables);
+    const data = await this.withCache(key, "datasets", options, async () => {
+      const result = await this.connection.execute(query, variables);
+      return result["searchDatasets"];
+    });
+    return new Collection(data, {
+      nextPageLoader: async (cursor) => {
+        return this.search({ ...options, after: cursor });
+      }
+    });
+  }
+  async get(idOrPublisherSlug, gameKeyOrOptions, datasetKey, options) {
+    if (typeof gameKeyOrOptions === "string" && typeof datasetKey === "string") {
+      const publisherSlug = idOrPublisherSlug;
+      const gameKey = gameKeyOrOptions;
+      const opts = options ?? {};
+      this.validateAccess(publisherSlug, gameKey);
+      const key = this.cacheKey("datasets", "getByKeys", { publisherSlug, gameKey, datasetKey });
+      return this.withCache(key, "datasets", opts, async () => {
+        const { query } = QueryBuilder.fetchDatasetByKeys();
+        const result = await this.connection.execute(query, { publisherSlug, gameKey, datasetKey });
+        return result["fetchDataset"] ?? null;
+      });
+    } else {
+      const id = idOrPublisherSlug;
+      const opts = gameKeyOrOptions ?? {};
+      const key = this.cacheKey("datasets", "get", { id });
+      return this.withCache(key, "datasets", opts, async () => {
+        const { query } = QueryBuilder.fetchDatasetById();
+        const result = await this.connection.execute(query, { id });
+        return result["fetchDataset"] ?? null;
+      });
+    }
+  }
+  /**
+   * Get multiple datasets by ID
+   *
+   * @example
+   * const datasets = await client.datasets.getMany(['id1', 'id2', 'id3'])
+   */
+  async getMany(ids, options = {}) {
+    if (ids.length === 0) return [];
+    const key = this.cacheKey("datasets", "getMany", { ids });
+    return this.withCache(key, "datasets", options, async () => {
+      const { query } = QueryBuilder.fetchDatasets();
+      const result = await this.connection.execute(query, { ids });
+      return result["fetchDatasets"] ?? [];
+    });
+  }
+};
+var DecksResource = class extends BaseResource {
+  constructor(connection, config) {
+    super(connection, config);
+  }
+  /**
+   * Fetch a hosted deck by CardDB UUID.
+   */
+  async fetch(id, options = {}) {
+    const key = this.cacheKey("decks", "fetch", { id });
+    return this.withCache(key, "decks", options, async () => {
+      const { query } = QueryBuilder.fetchDeckById();
+      const result = await this.connection.execute(query, { id });
+      return result["fetchDeck"] ?? null;
+    });
+  }
+  /**
+   * Fetch a hosted deck by external reference for the current API application.
+   */
+  async fetchByExternalRef(externalRef, options = {}) {
+    const key = this.cacheKey("decks", "fetchByExternalRef", { externalRef });
+    return this.withCache(key, "decks", options, async () => {
+      const { query } = QueryBuilder.fetchDeckByExternalRef();
+      const result = await this.connection.execute(query, { externalRef });
+      return result["fetchDeckByExternalRef"] ?? null;
+    });
+  }
+  /**
+   * List decks owned by the current account or API application.
+   */
+  async listMine(options = {}) {
+    const { query, variables } = QueryBuilder.listMyDecks({
+      first: options.first,
+      after: options.after
+    });
+    const key = this.cacheKey("decks", "listMine", variables);
+    const data = await this.withCache(key, "decks", options, async () => {
+      const result = await this.connection.execute(query, variables);
+      return result["myDecks"];
+    });
+    return new Collection(data, {
+      nextPageLoader: async (cursor) => this.listMine({ ...options, after: cursor })
+    });
+  }
+  /**
+   * Create a hosted deck.
+   */
+  async create(input) {
+    const { query } = QueryBuilder.createDeck();
+    const variables = QueryBuilder.deckCreateVariables(input);
+    const result = await this.connection.execute(query, variables);
+    return result["deckCreate"];
+  }
+  /**
+   * Update a hosted deck.
+   */
+  async update(id, input) {
+    const { query } = QueryBuilder.updateDeck();
+    const variables = QueryBuilder.deckUpdateVariables(id, input);
+    const result = await this.connection.execute(query, variables);
+    return result["deckUpdate"];
+  }
+  /**
+   * Delete a hosted deck.
+   */
+  async delete(id) {
+    const { query } = QueryBuilder.deleteDeck();
+    const result = await this.connection.execute(query, { id });
+    return Boolean(result["deckDelete"]);
+  }
+  /**
+   * Hydrate third-party-owned deck entries without storing them in CardDB.
+   */
+  async hydrateEntries(options) {
+    if (options.entries.length === 0) return [];
+    const publisherSlug = this.resolvePublisher(options.publisherSlug);
+    const gameKey = this.resolveGame(options.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    const identifiers = options.entries.map((entry) => entry.identifier);
+    const key = this.cacheKey("decks", "hydrateEntries", {
+      publisherSlug,
+      gameKey,
+      datasetKey: options.datasetKey,
+      identifiers
+    });
+    const records = await this.withCache(key, "decks", options, async () => {
+      const { query } = QueryBuilder.fetchRecordsByIdentifier();
+      const result = await this.connection.execute(query, {
+        publisherSlug,
+        gameKey,
+        datasetKey: options.datasetKey,
+        identifiers
+      });
+      return result["fetchRecordsByIdentifier"];
+    });
+    const recordsByIdentifier = recordsByDeckIdentifier(records, identifiers, options.identifierField);
+    return options.entries.map((entry) => ({
+      ...entry,
+      record: recordsByIdentifier.get(entry.identifier) ?? null
+    }));
+  }
+};
+function recordsByDeckIdentifier(records, identifiers, identifierField) {
+  const remaining = new Set(identifiers);
+  const recordsByIdentifier = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    const identifier = identifierField ? record.data[identifierField] : Object.values(record.data).find((value) => remaining.has(String(value)));
+    if (identifier === void 0 || identifier === null) continue;
+    const key = String(identifier);
+    if (!remaining.has(key)) continue;
+    recordsByIdentifier.set(key, record);
+    remaining.delete(key);
+  }
+  return recordsByIdentifier;
+}
+var RecordsResource = class extends BaseResource {
+  constructor(connection, config) {
+    super(connection, config);
+  }
+  /**
+   * Search for records in a dataset with filtering, search, and pagination
+   *
+   * @example Basic search
+   * const records = await client.records.search({
+   *   publisherSlug: 'pokemon',
+   *   gameKey: 'tcg',
+   *   datasetKey: 'cards',
+   * })
+   *
+   * @example With defaults configured
+   * // If client has defaultPublisher: 'pokemon', defaultGame: 'tcg'
+   * const records = await client.records.search({ datasetKey: 'cards' })
+   *
+   * @example With filtering (object literal)
+   * const records = await client.records.search({
+   *   datasetKey: 'cards',
+   *   filter: {
+   *     hp: { gte: 100 },
+   *     types: { contains: 'Fire' }
+   *   }
+   * })
+   *
+   * @example With filtering (builder function)
+   * const records = await client.records.search({
+   *   datasetKey: 'cards',
+   *   filter: f => f
+   *     .where('hp', gte(100))
+   *     .where('types', contains('Fire'))
+   *     .any(or => or
+   *       .where('rarity', 'Rare')
+   *       .where('rarity', 'Rare Holo')
+   *     )
+   * })
+   *
+   * @example With link resolution
+   * const records = await client.records.search({
+   *   datasetKey: 'cards',
+   *   resolveLinks: ['set_id'],
+   *   filter: f => f.whereLink('set_id', { code: 'BASE' })
+   * })
+   *
+   * @example Iterate through all results
+   * const records = await client.records.search({ datasetKey: 'cards' })
+   * for await (const record of records) {
+   *   console.log(record.data.name)
+   * }
+   */
+  async search(options) {
+    const publisherSlug = this.resolvePublisher(options.publisherSlug);
+    const gameKey = this.resolveGame(options.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    const filter = resolveFilter(options.filter);
+    const { query, variables } = QueryBuilder.searchRecords({
+      publisherSlug,
+      gameKey,
+      datasetKey: options.datasetKey,
+      filter,
+      search: options.search,
+      orderBy: options.orderBy,
+      resolveLinks: options.resolveLinks,
+      first: options.first,
+      after: options.after,
+      validateSchema: options.validateSchema
+    });
+    const key = this.cacheKey("records", "search", variables);
+    const data = await this.withCache(key, "records", options, async () => {
+      const result = await this.connection.execute(query, variables);
+      return result["searchRecords"];
+    });
+    return new Collection(data, {
+      nextPageLoader: async (cursor) => {
+        return this.search({ ...options, after: cursor });
+      }
+    });
+  }
+  /**
+   * Get a single record by ID
+   *
+   * @example
+   * const record = await client.records.get('550e8400-e29b-41d4-a716-446655440000')
+   */
+  async get(id, options = {}) {
+    const key = this.cacheKey("records", "get", { id });
+    return this.withCache(key, "records", options, async () => {
+      const { query } = QueryBuilder.fetchRecordById();
+      const result = await this.connection.execute(query, { id });
+      return result["fetchRecord"] ?? null;
+    });
+  }
+  /**
+   * Get a record by its identifier field value
+   *
+   * The identifier field is defined in the dataset schema (the field marked as isIdentifier)
+   *
+   * @example
+   * const record = await client.records.getByIdentifier({
+   *   publisherSlug: 'pokemon',
+   *   gameKey: 'tcg',
+   *   datasetKey: 'cards',
+   *   identifier: 'base1-4'
+   * })
+   *
+   * @example With defaults configured
+   * const record = await client.records.getByIdentifier({
+   *   datasetKey: 'cards',
+   *   identifier: 'base1-4'
+   * })
+   */
+  async getByIdentifier(options) {
+    const publisherSlug = this.resolvePublisher(options.publisherSlug);
+    const gameKey = this.resolveGame(options.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    const key = this.cacheKey("records", "getByIdentifier", {
+      publisherSlug,
+      gameKey,
+      datasetKey: options.datasetKey,
+      identifier: options.identifier
+    });
+    return this.withCache(key, "records", options, async () => {
+      const { query } = QueryBuilder.fetchRecordByIdentifier();
+      const result = await this.connection.execute(query, {
+        publisherSlug,
+        gameKey,
+        datasetKey: options.datasetKey,
+        identifier: options.identifier
+      });
+      return result["fetchRecordByIdentifier"] ?? null;
+    });
+  }
+  /**
+   * Get multiple records by their identifier field values
+   *
+   * Missing identifiers are omitted from the result.
+   *
+   * @example
+   * const records = await client.records.getManyByIdentifier({
+   *   publisherSlug: 'pokemon',
+   *   gameKey: 'tcg',
+   *   datasetKey: 'cards',
+   *   identifiers: ['base1-4', 'base1-5']
+   * })
+   *
+   * @example With defaults configured
+   * const records = await client.records.getManyByIdentifier({
+   *   datasetKey: 'cards',
+   *   identifiers: ['base1-4', 'base1-5']
+   * })
+   */
+  async getManyByIdentifier(options) {
+    if (options.identifiers.length === 0) return [];
+    const publisherSlug = this.resolvePublisher(options.publisherSlug);
+    const gameKey = this.resolveGame(options.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    const key = this.cacheKey("records", "getManyByIdentifier", {
+      publisherSlug,
+      gameKey,
+      datasetKey: options.datasetKey,
+      identifiers: options.identifiers
+    });
+    return this.withCache(key, "records", options, async () => {
+      const { query } = QueryBuilder.fetchRecordsByIdentifier();
+      const result = await this.connection.execute(query, {
+        publisherSlug,
+        gameKey,
+        datasetKey: options.datasetKey,
+        identifiers: options.identifiers
+      });
+      return result["fetchRecordsByIdentifier"] ?? [];
+    });
+  }
+  /**
+   * Get multiple records by ID
+   *
+   * @example
+   * const records = await client.records.getMany(['id1', 'id2', 'id3'])
+   */
+  async getMany(ids, options = {}) {
+    if (ids.length === 0) return [];
+    const key = this.cacheKey("records", "getMany", { ids });
+    return this.withCache(key, "records", options, async () => {
+      const { query } = QueryBuilder.fetchRecords();
+      const result = await this.connection.execute(query, { ids });
+      return result["fetchRecords"] ?? [];
+    });
+  }
+};
+var RulesResource = class extends BaseResource {
+  constructor(connection, config) {
+    super(connection, config);
+  }
+  /**
+   * List rule-related datasets for a game.
+   *
+   * @example
+   * const datasets = await client.rules.datasets({ publisherSlug: 'wotc', gameKey: 'magic' })
+   */
+  async datasets(options = {}) {
+    const publisherSlug = this.resolvePublisher(options.publisherSlug);
+    const gameKey = this.resolveGame(options.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    const { query, variables } = QueryBuilder.searchDatasets({
+      publisherSlug,
+      gameKey,
+      search: options.search,
+      purpose: "RULES",
+      first: options.first,
+      after: options.after
+    });
+    const key = this.cacheKey("rules", "datasets", variables);
+    const data = await this.withCache(key, "datasets", options, async () => {
+      const result = await this.connection.execute(query, variables);
+      return result["searchDatasets"];
+    });
+    return new Collection(data, {
+      nextPageLoader: async (cursor) => this.datasets({ ...options, after: cursor })
+    });
+  }
+  /**
+   * List rules from the game's rules dataset.
+   *
+   * @example
+   * const rules = await client.rules.list({ first: 100 })
+   */
+  async list(options = {}) {
+    return this.searchRuleRecords("rules", options);
+  }
+  /**
+   * List deck/game formats from the game's formats dataset.
+   *
+   * @example
+   * const formats = await client.rules.formats({ first: 100 })
+   * const names = formats.items.map(format => format.data.name)
+   */
+  async formats(options = {}) {
+    return this.searchRuleRecords(options.datasetKey ?? "formats", options);
+  }
+  async searchRuleRecords(defaultDatasetKey, options) {
+    const publisherSlug = this.resolvePublisher(options.publisherSlug);
+    const gameKey = this.resolveGame(options.gameKey);
+    const datasetKey = options.datasetKey ?? defaultDatasetKey;
+    this.validateAccess(publisherSlug, gameKey);
+    const filter = resolveFilter(options.filter);
+    const { query, variables } = QueryBuilder.searchRecords({
+      publisherSlug,
+      gameKey,
+      datasetKey,
+      filter,
+      search: options.search,
+      orderBy: options.orderBy,
+      resolveLinks: options.resolveLinks,
+      first: options.first,
+      after: options.after,
+      validateSchema: options.validateSchema
+    });
+    const key = this.cacheKey("rules", "records", variables);
+    const data = await this.withCache(key, "records", options, async () => {
+      const result = await this.connection.execute(query, variables);
+      return result["searchRecords"];
+    });
+    return new Collection(data, {
+      nextPageLoader: async (cursor) => this.searchRuleRecords(defaultDatasetKey, { ...options, after: cursor })
+    });
+  }
+};
+
+// src/client.ts
+var CardDBClient = class _CardDBClient {
+  config;
+  connection;
+  /** Publishers resource for searching and fetching publishers */
+  publishers;
+  /** Games resource for searching and fetching games */
+  games;
+  /** Datasets resource for searching and fetching datasets */
+  datasets;
+  /** Records resource for searching and fetching records */
+  records;
+  /** Decks resource for hosted decks and external deck hydration */
+  decks;
+  /** Rules resource for game rules and deck formats */
+  rules;
+  /**
+   * Create a new CardDB client
+   *
+   * @param config - Client configuration options
+   */
+  constructor(config = {}) {
+    this.config = new Configuration(config);
+    this.connection = new Connection(this.config);
+    this.publishers = new PublishersResource(this.connection, this.config);
+    this.games = new GamesResource(this.connection, this.config);
+    this.datasets = new DatasetsResource(this.connection, this.config);
+    this.records = new RecordsResource(this.connection, this.config);
+    this.decks = new DecksResource(this.connection, this.config);
+    this.rules = new RulesResource(this.connection, this.config);
+  }
+  /**
+   * Get information about the current API key
+   *
+   * Returns null if no API key is configured or the key is invalid.
+   *
+   * @example
+   * const info = await client.me()
+   * if (info) {
+   *   console.log(`Logged in as: ${info.account.displayName}`)
+   *   console.log(`Application: ${info.application.name}`)
+   * }
+   */
+  async me() {
+    const { query } = QueryBuilder.fetchMe();
+    const result = await this.connection.execute(query);
+    return result["fetchMe"] ?? null;
+  }
+  /**
+   * Get rate limit information from the last request
+   *
+   * @example
+   * await client.publishers.search()
+   * const rateLimit = client.getRateLimitInfo()
+   * console.log(`Remaining: ${rateLimit?.remaining}/${rateLimit?.limit}`)
+   */
+  getRateLimitInfo() {
+    return getRateLimitInfo();
+  }
+  /**
+   * Create a new client with configuration overrides
+   *
+   * Useful for creating scoped clients with different defaults.
+   *
+   * @example
+   * const pokemonClient = client.withConfig({
+   *   defaultPublisher: 'pokemon',
+   *   defaultGame: 'tcg'
+   * })
+   *
+   * // Now all queries use these defaults
+   * const cards = await pokemonClient.records.search({ datasetKey: 'cards' })
+   */
+  withConfig(overrides) {
+    const mergedConfig = this.config.merge(overrides);
+    return new _CardDBClient({
+      apiKey: mergedConfig.apiKey,
+      endpoint: mergedConfig.endpoint,
+      timeout: mergedConfig.timeout,
+      openTimeout: mergedConfig.openTimeout,
+      defaultPublisher: mergedConfig.defaultPublisher,
+      defaultGame: mergedConfig.defaultGame,
+      allowedPublishers: mergedConfig.allowedPublishers,
+      allowedGames: mergedConfig.allowedGames,
+      logger: mergedConfig.logger,
+      logLevel: mergedConfig.logLevel,
+      retryOnRateLimit: mergedConfig.retryOnRateLimit,
+      maxRetries: mergedConfig.maxRetries,
+      retryOnNetworkError: mergedConfig.retryOnNetworkError,
+      maxNetworkRetries: mergedConfig.maxNetworkRetries,
+      retryBaseDelay: mergedConfig.retryBaseDelay,
+      retryMaxDelay: mergedConfig.retryMaxDelay,
+      cache: mergedConfig.cache,
+      cacheTtl: mergedConfig.cacheTtl,
+      cacheTtls: mergedConfig.cacheTtls
+    });
+  }
+};
+
+export { BaseResource, CardDBClient, Configuration, Connection, DEFAULT_CACHE_TTL, DEFAULT_ENDPOINT, DEFAULT_MAX_NETWORK_RETRIES, DEFAULT_MAX_RETRIES, DEFAULT_OPEN_TIMEOUT, DEFAULT_RETRY_BASE_DELAY, DEFAULT_RETRY_MAX_DELAY, DEFAULT_TIMEOUT, DatasetsResource, DecksResource, GamesResource, PublishersResource, RecordsResource, RulesResource, cacheKey, getRateLimitInfo, getSDKVersion, getUserAgent, readCache, writeCache };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map