@carddb/client 0.3.15 → 0.4.0

package/README.md

@@ -11,7 +11,7 @@ This package provides the core client implementation shared between browser and
 - **CardDBClient**: Main client class with resource accessors
 - **Connection**: HTTP/GraphQL connection handling
 - **Configuration**: Client configuration management
-- **Resources**: Publisher, Game, Dataset, Record, Import Format, Import, Export, File, Deck, and Rule resource classes
+- **Resources**: Publisher, Game, Dataset, Record, Import Format, Import, Export, File, Scan, Scan Template, Deck, and Rule resource classes
 - **Cache utilities**: Cache key generation and read/write helpers
 
 ## Usage

package/dist/index.cjs

@@ -680,6 +680,25 @@ var GamesResource = class extends BaseResource {
     const result = await this.connection.execute(query, core.QueryBuilder.gameUpdateVariables(id, input));
     return result["gameUpdate"];
   }
+  /**
+   * Get publisher-defined game region metadata for scan-capable clients.
+   */
+  async getRegions(options = {}) {
+    const publisherSlug = this.resolvePublisher(options.publisherSlug);
+    const gameKey = this.resolveGame(options.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    const variables = core.QueryBuilder.gameScanRegionsVariables(
+      publisherSlug,
+      gameKey,
+      options.includeInactive
+    );
+    const key = this.cacheKey("games", "getRegions", variables);
+    return this.withCache(key, "games", options, async () => {
+      const { query } = core.QueryBuilder.gameScanRegions();
+      const result = await this.connection.execute(query, variables);
+      return result["gameScanRegions"] ?? [];
+    });
+  }
   /**
    * Search for games
    *
@@ -2524,6 +2543,27 @@ var FilesResource = class extends BaseResource {
     const result = await this.connection.execute(query, { id });
     return result["fileUploadConfirm"];
   }
+  /**
+   * Request a presigned upload URL, PUT bytes directly to storage, then confirm the file.
+   */
+  async upload(input) {
+    const size = input.size ?? inferUploadSize(input.body);
+    if (!size || size <= 0) {
+      throw new Error("files.upload requires a positive size or a body with an inferable size");
+    }
+    const upload = await this.requestUpload({
+      filename: input.filename,
+      contentType: input.contentType,
+      size,
+      isPublic: input.isPublic ?? false,
+      entityType: input.entityType ?? entityTypeForPurpose(input.purpose),
+      entityId: input.entityId,
+      publisherId: input.publisherId,
+      datasetId: input.datasetId
+    });
+    await putUpload(upload.uploadUrl, input.contentType, input.body);
+    return this.confirmUpload(upload.file.id);
+  }
   /**
    * Delete a file. Requires a server-side secret credential.
    */
@@ -2534,6 +2574,294 @@ var FilesResource = class extends BaseResource {
     return Boolean(result["fileDelete"]);
   }
 };
+async function putUpload(uploadUrl, contentType, body) {
+  const uploadFetch = globalThis.fetch;
+  if (!uploadFetch) throw new Error("files.upload requires a runtime with fetch support");
+  const response = await uploadFetch(uploadUrl, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    body
+  });
+  if (!response.ok) {
+    const responseBody = await response.text().catch(() => "");
+    throw new Error(
+      `File upload failed with ${response.status} ${response.statusText}${responseBody ? `: ${responseBody}` : ""}`
+    );
+  }
+}
+function inferUploadSize(body) {
+  if (typeof body === "string") return new TextEncoder().encode(body).byteLength;
+  if (body instanceof ArrayBuffer) return body.byteLength;
+  if (ArrayBuffer.isView(body)) return body.byteLength;
+  const sized = body;
+  if (typeof sized?.size === "number") return sized.size;
+  if (typeof sized?.byteLength === "number") return sized.byteLength;
+  if (typeof sized?.length === "number") return sized.length;
+  return void 0;
+}
+function entityTypeForPurpose(purpose) {
+  if (!purpose || purpose === "scan_image") return void 0;
+  if (purpose === "import") return "import";
+  if (purpose === "scan_template_example") return "scan_template_example";
+  return purpose;
+}
+var ScansResource = class extends BaseResource {
+  constructor(connection, config) {
+    super(connection, config);
+  }
+  /**
+   * Create a scan job for an already uploaded image file.
+   */
+  async createJob(input) {
+    const scopedInput = this.resolveCreateJobInput(input);
+    const { query } = core.QueryBuilder.createScanJob();
+    const result = await this.connection.execute(
+      query,
+      core.QueryBuilder.createScanJobVariables(scopedInput)
+    );
+    return result["createScanJob"];
+  }
+  /**
+   * Get a scan job and its latest processing result.
+   */
+  async getJob(id, options = {}) {
+    const key = this.cacheKey("scans", "getJob", { id });
+    return this.withCache(key, "scans", options, async () => {
+      const { query } = core.QueryBuilder.scanJob();
+      const result = await this.connection.execute(query, { id });
+      return result["scanJob"] ?? null;
+    });
+  }
+  /**
+   * Poll a scan job until it reaches a terminal status.
+   */
+  async pollJob(id, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 3e5;
+    const backoffFactor = Math.max(options.backoffFactor ?? 1.5, 1);
+    const maxIntervalMs = options.maxIntervalMs ?? 1e4;
+    const startedAt = Date.now();
+    let intervalMs = Math.max(options.intervalMs ?? 1e3, 1);
+    while (true) {
+      throwIfAborted(options.signal);
+      const job = await this.getJob(id, { cache: false });
+      if (!job) throw new Error(`Scan job '${id}' was not found`);
+      if (isTerminalScanStatus(job.status)) return job;
+      const elapsedMs = Date.now() - startedAt;
+      const remainingMs = timeoutMs - elapsedMs;
+      if (remainingMs <= 0) {
+        throw new Error(`Timed out waiting for scan job '${id}'`);
+      }
+      await sleep(Math.min(intervalMs, remainingMs));
+      intervalMs = Math.min(Math.ceil(intervalMs * backoffFactor), maxIntervalMs);
+    }
+  }
+  /**
+   * Submit correctness feedback for a completed scan job.
+   */
+  async submitFeedback(input) {
+    const { query } = core.QueryBuilder.submitScanFeedback();
+    const result = await this.connection.execute(
+      query,
+      core.QueryBuilder.submitScanFeedbackVariables(input)
+    );
+    return result["submitScanFeedback"];
+  }
+  /**
+   * Aggregate scan metrics for a publisher/game/dataset scope.
+   */
+  async metrics(input) {
+    const scopedInput = this.resolveMetricsInput(input);
+    const { query } = core.QueryBuilder.scanMetrics();
+    const result = await this.connection.execute(
+      query,
+      core.QueryBuilder.scanMetricsVariables(scopedInput)
+    );
+    return result["scanMetrics"];
+  }
+  /**
+   * Verify an `X-CardDB-Signature` value for a webhook body.
+   */
+  async verifyWebhookSignature(input) {
+    const subtle = getSubtleCrypto();
+    const key = await subtle.importKey(
+      "raw",
+      encodeUtf8(input.secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    );
+    const digest = await subtle.sign("HMAC", key, bodyToBytes(input.body));
+    const expected = `sha256=${toHex(new Uint8Array(digest))}`;
+    return constantTimeEqual(input.signature.trim().toLowerCase(), expected);
+  }
+  resolveCreateJobInput(input) {
+    const publisherSlug = this.resolvePublisher(input.publisherSlug);
+    const gameKey = this.resolveGame(input.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    return { ...input, publisherSlug, gameKey };
+  }
+  resolveMetricsInput(input) {
+    const publisherSlug = this.resolvePublisher(input.publisherSlug);
+    const gameKey = this.resolveGame(input.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    return { ...input, publisherSlug, gameKey };
+  }
+};
+function isTerminalScanStatus(status) {
+  const normalized = status.toLowerCase();
+  return normalized === "completed" || normalized === "failed" || normalized === "cancelled";
+}
+async function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function throwIfAborted(signal) {
+  if (!signal) return;
+  if (signal.throwIfAborted) signal.throwIfAborted();
+  if (signal.aborted) throw new Error("Scan job polling aborted");
+}
+function getSubtleCrypto() {
+  const cryptoLike = globalThis;
+  const subtle = cryptoLike.crypto?.subtle;
+  if (!subtle) {
+    throw new Error("Web Crypto HMAC support is not available in this runtime");
+  }
+  return subtle;
+}
+function bodyToBytes(body) {
+  if (typeof body === "string") return encodeUtf8(body);
+  if (body instanceof ArrayBuffer) return new Uint8Array(body);
+  return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+}
+function encodeUtf8(value) {
+  return new TextEncoder().encode(value);
+}
+function toHex(bytes) {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(left, right) {
+  const maxLength = Math.max(left.length, right.length);
+  let diff = left.length ^ right.length;
+  for (let index = 0; index < maxLength; index++) {
+    diff |= (left.charCodeAt(index) || 0) ^ (right.charCodeAt(index) || 0);
+  }
+  return diff === 0;
+}
+var ScanTemplatesResource = class extends BaseResource {
+  constructor(connection, config) {
+    super(connection, config);
+  }
+  /**
+   * Resolve the active scan template for a game or dataset scope.
+   */
+  async resolve(input) {
+    const scopedInput = this.resolveTemplateScope(input);
+    const key = this.cacheKey("scanTemplates", "resolve", { ...scopedInput });
+    return this.withCache(key, "scanTemplates", input, async () => {
+      const { query } = core.QueryBuilder.resolveScanTemplate();
+      const result = await this.connection.execute(
+        query,
+        core.QueryBuilder.resolveScanTemplateVariables(scopedInput)
+      );
+      return result["resolveScanTemplate"];
+    });
+  }
+  /**
+   * List publisher-managed scan templates for a game or dataset scope.
+   */
+  async list(input) {
+    const scopedInput = this.resolveListScope(input);
+    const key = this.cacheKey("scanTemplates", "list", { ...scopedInput });
+    return this.withCache(key, "scanTemplates", input, async () => {
+      const { query } = core.QueryBuilder.scanTemplates();
+      const result = await this.connection.execute(
+        query,
+        core.QueryBuilder.scanTemplatesVariables(scopedInput)
+      );
+      const payload = result["scanTemplates"];
+      return payload?.templates ?? [];
+    });
+  }
+  /**
+   * Create a publisher-managed scan template. Requires a server-side secret credential.
+   */
+  async create(input) {
+    this.config.requireSecretCredential("scanTemplates.create");
+    const scopedInput = this.resolveSaveInput(input);
+    const { query } = core.QueryBuilder.createScanTemplate();
+    const result = await this.connection.execute(
+      query,
+      core.QueryBuilder.createScanTemplateVariables(scopedInput)
+    );
+    return result["createScanTemplate"];
+  }
+  /**
+   * Replace a publisher-managed scan template. Requires a server-side secret credential.
+   */
+  async update(idOrInput, input) {
+    this.config.requireSecretCredential("scanTemplates.update");
+    const id = typeof idOrInput === "string" ? idOrInput : idOrInput.id;
+    const templateInput = typeof idOrInput === "string" ? input : withoutId(idOrInput);
+    if (!templateInput) throw new Error("scan template input is required");
+    const scopedInput = this.resolveSaveInput(templateInput);
+    const { query } = core.QueryBuilder.updateScanTemplate();
+    const result = await this.connection.execute(
+      query,
+      core.QueryBuilder.updateScanTemplateVariables(id, scopedInput)
+    );
+    return result["updateScanTemplate"];
+  }
+  /**
+   * Validate a draft scan template and normalize provided region OCR hints.
+   */
+  async preview(input) {
+    const scopedInput = this.resolvePreviewInput(input);
+    const { query } = core.QueryBuilder.previewScanTemplate();
+    const result = await this.connection.execute(
+      query,
+      core.QueryBuilder.previewScanTemplateVariables(scopedInput)
+    );
+    return result["previewScanTemplate"];
+  }
+  resolveTemplateScope(input) {
+    const publisherSlug = this.resolvePublisher(input.publisherSlug);
+    const gameKey = this.resolveGame(input.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    return {
+      publisherSlug,
+      gameKey,
+      datasetKey: input.datasetKey,
+      templateId: input.templateId
+    };
+  }
+  resolveListScope(input) {
+    const publisherSlug = this.resolvePublisher(input.publisherSlug);
+    const gameKey = this.resolveGame(input.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    return {
+      publisherSlug,
+      gameKey,
+      datasetKey: input.datasetKey,
+      includeArchived: input.includeArchived
+    };
+  }
+  resolveSaveInput(input) {
+    const publisherSlug = this.resolvePublisher(input.publisherSlug);
+    const gameKey = this.resolveGame(input.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    return { ...input, publisherSlug, gameKey };
+  }
+  resolvePreviewInput(input) {
+    const publisherSlug = this.resolvePublisher(input.publisherSlug);
+    const gameKey = this.resolveGame(input.gameKey);
+    this.validateAccess(publisherSlug, gameKey);
+    return { ...input, publisherSlug, gameKey };
+  }
+};
+function withoutId(input) {
+  const templateInput = { ...input };
+  delete templateInput.id;
+  return templateInput;
+}
 
 // src/client.ts
 var CardDBClient = class _CardDBClient {
@@ -2559,6 +2887,10 @@ var CardDBClient = class _CardDBClient {
   exports;
   /** File upload helper resource */
   files;
+  /** Scan job helper resource */
+  scans;
+  /** Scan template helper resource */
+  scanTemplates;
   /**
    * Create a new CardDB client
    *
@@ -2577,6 +2909,8 @@ var CardDBClient = class _CardDBClient {
     this.imports = new ImportsResource(this.connection, this.config);
     this.exports = new ExportsResource(this.connection, this.config);
     this.files = new FilesResource(this.connection, this.config);
+    this.scans = new ScansResource(this.connection, this.config);
+    this.scanTemplates = new ScanTemplatesResource(this.connection, this.config);
   }
   /**
    * Get information about the current API key
@@ -2672,6 +3006,8 @@ exports.ImportsResource = ImportsResource;
 exports.PublishersResource = PublishersResource;
 exports.RecordsResource = RecordsResource;
 exports.RulesResource = RulesResource;
+exports.ScanTemplatesResource = ScanTemplatesResource;
+exports.ScansResource = ScansResource;
 exports.cacheKey = cacheKey;
 exports.getRateLimitInfo = getRateLimitInfo;
 exports.getSDKVersion = getSDKVersion;