@quikturn/logos 0.2.0

package/dist/client/index.cjs

@@ -0,0 +1,726 @@
+'use strict';
+
+// src/constants.ts
+var BASE_URL = "https://logos.getquikturn.io";
+var DEFAULT_WIDTH = 128;
+var MAX_WIDTH = 800;
+var MAX_WIDTH_SERVER = 1200;
+var SUPPORTED_FORMATS = /* @__PURE__ */ new Set([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/avif"
+]);
+var FORMAT_ALIASES = {
+  png: "image/png",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+  avif: "image/avif"
+};
+var MAX_RETRY_AFTER_SECONDS = 300;
+var MAX_RESPONSE_BODY_BYTES = 10485760;
+
+// src/errors.ts
+var LogoError = class extends Error {
+  constructor(message, code, status) {
+    super(message);
+    this.name = "LogoError";
+    this.code = code;
+    this.status = status;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var DomainValidationError = class extends LogoError {
+  constructor(message, domain) {
+    super(message, "DOMAIN_VALIDATION_ERROR");
+    this.name = "DomainValidationError";
+    this.domain = domain;
+  }
+};
+var RateLimitError = class extends LogoError {
+  constructor(message, retryAfter, remaining, resetAt) {
+    super(message, "RATE_LIMIT_ERROR", 429);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+    this.remaining = remaining;
+    this.resetAt = resetAt;
+  }
+};
+var QuotaExceededError = class extends LogoError {
+  constructor(message, retryAfter, limit, used) {
+    super(message, "QUOTA_EXCEEDED_ERROR", 429);
+    this.name = "QuotaExceededError";
+    this.retryAfter = retryAfter;
+    this.limit = limit;
+    this.used = used;
+  }
+};
+var AuthenticationError = class extends LogoError {
+  constructor(message) {
+    super(message, "AUTHENTICATION_ERROR", 401);
+    this.name = "AuthenticationError";
+  }
+};
+var ForbiddenError = class extends LogoError {
+  constructor(message, reason) {
+    super(message, "FORBIDDEN_ERROR", 403);
+    this.name = "ForbiddenError";
+    this.reason = reason;
+  }
+};
+var NotFoundError = class extends LogoError {
+  constructor(message, domain) {
+    super(message, "NOT_FOUND_ERROR", 404);
+    this.name = "NotFoundError";
+    this.domain = domain;
+  }
+};
+var ScrapeTimeoutError = class extends LogoError {
+  constructor(message, jobId, elapsed) {
+    super(message, "SCRAPE_TIMEOUT_ERROR");
+    this.name = "ScrapeTimeoutError";
+    this.jobId = jobId;
+    this.elapsed = elapsed;
+  }
+};
+var BadRequestError = class extends LogoError {
+  constructor(message) {
+    super(message, "BAD_REQUEST_ERROR", 400);
+    this.name = "BadRequestError";
+  }
+};
+
+// src/url-builder.ts
+var IP_ADDRESS_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
+var LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+function validateDomain(domain) {
+  const normalized = domain.trim().toLowerCase();
+  const clean = normalized.endsWith(".") ? normalized.slice(0, -1) : normalized;
+  if (clean.length === 0) {
+    throw new DomainValidationError("Domain must not be empty", domain);
+  }
+  if (clean.includes("://")) {
+    throw new DomainValidationError(
+      'Domain must not include a protocol scheme (e.g. remove "https://")',
+      domain
+    );
+  }
+  if (clean.includes("/")) {
+    throw new DomainValidationError(
+      "Domain must not include a path \u2014 provide only the hostname",
+      domain
+    );
+  }
+  if (IP_ADDRESS_RE.test(clean)) {
+    throw new DomainValidationError(
+      "IP addresses are not supported \u2014 provide a domain name",
+      domain
+    );
+  }
+  if (clean === "localhost") {
+    throw new DomainValidationError(
+      '"localhost" is not a valid domain',
+      domain
+    );
+  }
+  if (clean.length > 253) {
+    throw new DomainValidationError(
+      `Domain exceeds maximum length of 253 characters (got ${clean.length})`,
+      domain
+    );
+  }
+  const labels = clean.split(".");
+  if (labels.length < 2) {
+    throw new DomainValidationError(
+      'Domain must contain at least two labels (e.g. "example.com")',
+      domain
+    );
+  }
+  for (const label of labels) {
+    if (label.length === 0) {
+      throw new DomainValidationError(
+        "Domain contains an empty label (consecutive dots)",
+        domain
+      );
+    }
+    if (label.length > 63) {
+      throw new DomainValidationError(
+        `Label "${label}" exceeds maximum length of 63 characters (got ${label.length})`,
+        domain
+      );
+    }
+    if (!LABEL_RE.test(label)) {
+      throw new DomainValidationError(
+        `Label "${label}" contains invalid characters \u2014 only letters, digits, and hyphens are allowed, and labels must not start or end with a hyphen`,
+        domain
+      );
+    }
+  }
+  return clean;
+}
+function resolveFormat(format) {
+  let candidate = format;
+  if (candidate.startsWith("image/")) {
+    candidate = candidate.slice(6);
+  }
+  if (candidate in FORMAT_ALIASES) {
+    return candidate;
+  }
+  if (SUPPORTED_FORMATS.has(format)) {
+    const shorthand = format.slice(6);
+    if (shorthand in FORMAT_ALIASES) {
+      return shorthand;
+    }
+  }
+  return void 0;
+}
+function logoUrl(domain, options) {
+  const validDomain = validateDomain(domain);
+  const {
+    token,
+    size,
+    width,
+    greyscale,
+    theme,
+    format,
+    autoScrape,
+    baseUrl
+  } = options ?? {};
+  const maxWidth = token?.startsWith("sk_") ? MAX_WIDTH_SERVER : MAX_WIDTH;
+  let resolvedSize = size ?? width ?? DEFAULT_WIDTH;
+  if (resolvedSize <= 0) {
+    resolvedSize = DEFAULT_WIDTH;
+  }
+  resolvedSize = Math.max(1, Math.min(resolvedSize, maxWidth));
+  const resolvedFormat = format ? resolveFormat(format) : void 0;
+  const effectiveBaseUrl = baseUrl ?? BASE_URL;
+  const url = new URL(`${effectiveBaseUrl}/${validDomain}`);
+  if (token !== void 0) {
+    url.searchParams.set("token", token);
+  }
+  if (resolvedSize !== DEFAULT_WIDTH) {
+    url.searchParams.set("size", String(resolvedSize));
+  }
+  if (greyscale === true) {
+    url.searchParams.set("greyscale", "1");
+  }
+  if (theme === "light" || theme === "dark") {
+    url.searchParams.set("theme", theme);
+  }
+  if (resolvedFormat !== void 0) {
+    url.searchParams.set("format", resolvedFormat);
+  }
+  if (autoScrape === true) {
+    url.searchParams.set("autoScrape", "true");
+  }
+  return url.toString();
+}
+
+// src/headers.ts
+function safeParseInt(value, fallback) {
+  if (value === null) return fallback;
+  const parsed = parseInt(value, 10);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+function safeParseFloat(value, fallback) {
+  if (value === null) return fallback;
+  const parsed = parseFloat(value);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+function parseLogoHeaders(headers) {
+  const cacheStatus = headers.get("X-Cache-Status");
+  const rateLimitRemaining = safeParseInt(headers.get("X-RateLimit-Remaining"), 0);
+  const rateLimitReset = safeParseInt(headers.get("X-RateLimit-Reset"), 0);
+  const quotaRemaining = safeParseInt(headers.get("X-Quota-Remaining"), 0);
+  const quotaLimit = safeParseInt(headers.get("X-Quota-Limit"), 0);
+  const tokenPrefix = headers.get("X-Quikturn-Token") ?? void 0;
+  const transformApplied = headers.get("X-Transformation-Applied") === "true";
+  const VALID_TRANSFORM_STATUSES = /* @__PURE__ */ new Set([
+    "not-requested",
+    "unsupported-format",
+    "transformation-error"
+  ]);
+  const rawTransformStatus = headers.get("X-Transformation-Status");
+  const transformStatus = rawTransformStatus && VALID_TRANSFORM_STATUSES.has(rawTransformStatus) ? rawTransformStatus : void 0;
+  const rawTransformMethod = headers.get("X-Transformation-Method");
+  const transformMethod = rawTransformMethod === "images-binding" ? "images-binding" : void 0;
+  const transformWidth = safeParseInt(headers.get("X-Transformation-Width"), void 0);
+  const transformGreyscale = headers.get("X-Transformation-Greyscale") === "true" ? true : void 0;
+  const transformGamma = safeParseFloat(headers.get("X-Transformation-Gamma"), void 0);
+  return {
+    cache: { status: cacheStatus === "HIT" ? "HIT" : "MISS" },
+    rateLimit: {
+      remaining: rateLimitRemaining,
+      reset: new Date(rateLimitReset * 1e3)
+    },
+    quota: {
+      remaining: quotaRemaining,
+      limit: quotaLimit
+    },
+    transformation: {
+      applied: transformApplied,
+      ...transformStatus ? { status: transformStatus } : {},
+      ...transformMethod ? { method: transformMethod } : {},
+      ...transformWidth !== void 0 ? { width: transformWidth } : {},
+      ...transformGreyscale !== void 0 ? { greyscale: transformGreyscale } : {},
+      ...transformGamma !== void 0 ? { gamma: transformGamma } : {}
+    },
+    ...tokenPrefix !== void 0 ? { tokenPrefix } : {}
+  };
+}
+function parseRetryAfter(headers) {
+  const value = headers.get("Retry-After");
+  if (value === null) return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+// src/internal/delay.ts
+function delay(ms, signal) {
+  if (signal?.aborted) {
+    return Promise.reject(new LogoError("Aborted", "ABORT_ERROR"));
+  }
+  return new Promise((resolve, reject) => {
+    let onAbort;
+    const timer = setTimeout(() => {
+      if (onAbort && signal) {
+        signal.removeEventListener("abort", onAbort);
+      }
+      resolve();
+    }, ms);
+    if (signal) {
+      onAbort = () => {
+        clearTimeout(timer);
+        reject(new LogoError("Aborted", "ABORT_ERROR"));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+
+// src/client/fetcher.ts
+var DEFAULT_MAX_RETRIES = 2;
+var DEFAULT_RETRY_AFTER_SECONDS = 60;
+var SERVER_ERROR_RETRY_DELAY_MS = 1e3;
+var WARNING_THRESHOLD = 0.1;
+function extractDomainFromUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const path = parsed.pathname.slice(1);
+    return path || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function isAbortError(err) {
+  return err instanceof Error && err.name === "AbortError";
+}
+function emitWarnings(headers, onRateLimitWarning, onQuotaWarning) {
+  if (onRateLimitWarning) {
+    const remaining = parseInt(headers.get("X-RateLimit-Remaining") ?? "", 10);
+    const limit = parseInt(headers.get("X-RateLimit-Limit") ?? "", 10);
+    if (!Number.isNaN(remaining) && !Number.isNaN(limit) && limit > 0) {
+      if (remaining < limit * WARNING_THRESHOLD) {
+        onRateLimitWarning(remaining, limit);
+      }
+    }
+  }
+  if (onQuotaWarning) {
+    const remaining = parseInt(headers.get("X-Quota-Remaining") ?? "", 10);
+    const limit = parseInt(headers.get("X-Quota-Limit") ?? "", 10);
+    if (!Number.isNaN(remaining) && !Number.isNaN(limit) && limit > 0) {
+      if (remaining < limit * WARNING_THRESHOLD) {
+        onQuotaWarning(remaining, limit);
+      }
+    }
+  }
+}
+async function browserFetch(url, options) {
+  const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const signal = options?.signal;
+  const format = options?.format;
+  const onRateLimitWarning = options?.onRateLimitWarning;
+  const onQuotaWarning = options?.onQuotaWarning;
+  const requestHeaders = {};
+  if (format) {
+    requestHeaders["Accept"] = format;
+  }
+  let retryCount = 0;
+  let serverErrorRetried = false;
+  while (true) {
+    let response;
+    try {
+      response = await globalThis.fetch(url, {
+        headers: requestHeaders,
+        signal
+      });
+    } catch (err) {
+      if (isAbortError(err)) {
+        throw new LogoError("Request aborted", "ABORT_ERROR");
+      }
+      const message = err instanceof Error ? err.message : "Unknown network error";
+      throw new LogoError(`Network error: ${message}`, "NETWORK_ERROR");
+    }
+    if (response.ok) {
+      emitWarnings(response.headers, onRateLimitWarning, onQuotaWarning);
+      return response;
+    }
+    if (response.status === 401) {
+      throw new AuthenticationError("Authentication failed");
+    }
+    if (response.status === 403) {
+      const body2 = await response.text();
+      const reason = body2.slice(0, 256) || "unknown";
+      throw new ForbiddenError("Access forbidden", reason);
+    }
+    if (response.status === 404) {
+      const domain = extractDomainFromUrl(url);
+      throw new NotFoundError("Logo not found", domain);
+    }
+    if (response.status === 429) {
+      const retryAfter = parseRetryAfter(response.headers) ?? DEFAULT_RETRY_AFTER_SECONDS;
+      const quotaLimitHeader = response.headers.get("X-Quota-Limit");
+      if (quotaLimitHeader !== null) {
+        const quotaLimit = parseInt(quotaLimitHeader, 10) || 0;
+        const quotaRemaining = parseInt(response.headers.get("X-Quota-Remaining") ?? "0", 10) || 0;
+        const used = quotaLimit - quotaRemaining;
+        throw new QuotaExceededError(
+          "Monthly quota exceeded",
+          retryAfter,
+          quotaLimit,
+          used
+        );
+      }
+      if (retryCount < maxRetries) {
+        retryCount++;
+        const retryDelay = Math.min(Math.max(1, retryAfter), MAX_RETRY_AFTER_SECONDS) * 1e3;
+        await delay(retryDelay);
+        continue;
+      }
+      const remaining = parseInt(
+        response.headers.get("X-RateLimit-Remaining") ?? "0",
+        10
+      ) || 0;
+      const resetEpoch = parseInt(response.headers.get("X-RateLimit-Reset") ?? "0", 10) || 0;
+      throw new RateLimitError(
+        "Rate limit exceeded",
+        retryAfter,
+        remaining,
+        new Date(resetEpoch * 1e3)
+      );
+    }
+    if (response.status === 400) {
+      const body2 = await response.text();
+      throw new BadRequestError(body2.slice(0, 256) || "Bad request");
+    }
+    if (response.status === 500) {
+      if (!serverErrorRetried) {
+        serverErrorRetried = true;
+        await delay(SERVER_ERROR_RETRY_DELAY_MS);
+        continue;
+      }
+      const body2 = await response.text();
+      throw new LogoError(
+        body2.slice(0, 256) || "Internal server error",
+        "SERVER_ERROR",
+        500
+      );
+    }
+    await response.text();
+    throw new LogoError(
+      `Unexpected response: ${response.status}`,
+      "UNEXPECTED_ERROR",
+      response.status
+    );
+  }
+}
+
+// src/client/scrape-poller.ts
+var DEFAULT_SCRAPE_TIMEOUT_MS = 3e4;
+var MAX_BACKOFF_MS = 5e3;
+var MAX_POLL_RETRIES = 3;
+function appendToken(url, token) {
+  const parsed = new URL(url);
+  parsed.searchParams.set("token", token);
+  return parsed.toString();
+}
+async function handleScrapeResponse(response, originalUrl, fetchFn, options) {
+  if (response.status !== 202) {
+    return response;
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new LogoError("Failed to parse scrape response", "SCRAPE_PARSE_ERROR");
+  }
+  const { scrapeJob } = body;
+  const { jobId, pollUrl, estimatedWaitMs } = scrapeJob;
+  try {
+    const originalOrigin = new URL(originalUrl).origin;
+    const pollOrigin = new URL(pollUrl).origin;
+    if (pollOrigin !== originalOrigin) {
+      throw new LogoError(
+        "Poll URL origin does not match API origin",
+        "SCRAPE_PARSE_ERROR"
+      );
+    }
+  } catch (err) {
+    if (err instanceof LogoError) throw err;
+    throw new LogoError("Invalid poll URL", "SCRAPE_PARSE_ERROR");
+  }
+  const scrapeTimeout = options?.scrapeTimeout ?? DEFAULT_SCRAPE_TIMEOUT_MS;
+  const onScrapeProgress = options?.onScrapeProgress;
+  const signal = options?.signal;
+  const token = options?.token;
+  const MIN_BACKOFF_MS = 500;
+  let backoff = Math.min(Math.max(MIN_BACKOFF_MS, estimatedWaitMs), MAX_BACKOFF_MS);
+  const startTime = Date.now();
+  while (true) {
+    const elapsed = Date.now() - startTime;
+    const remaining = scrapeTimeout - elapsed;
+    if (remaining <= 0) {
+      throw new ScrapeTimeoutError("Scrape timed out", jobId, elapsed);
+    }
+    await delay(Math.min(backoff, remaining), signal);
+    let pollResponse;
+    let retries = 0;
+    while (true) {
+      try {
+        pollResponse = await fetchFn(pollUrl);
+        break;
+      } catch (err) {
+        retries++;
+        if (retries >= MAX_POLL_RETRIES) {
+          throw err;
+        }
+        await delay(backoff, signal);
+      }
+    }
+    let event;
+    try {
+      event = await pollResponse.json();
+    } catch {
+      throw new LogoError("Failed to parse poll response", "SCRAPE_PARSE_ERROR");
+    }
+    if (onScrapeProgress) {
+      onScrapeProgress(event);
+    }
+    if (event.status === "complete") {
+      const finalUrl = token ? appendToken(originalUrl, token) : originalUrl;
+      return fetchFn(finalUrl);
+    }
+    if (event.status === "failed") {
+      throw new LogoError(
+        event.error ?? "Scrape failed",
+        "SCRAPE_FAILED"
+      );
+    }
+    backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+  }
+}
+
+// src/client/attribution.ts
+var VALID_ATTRIBUTION_STATUSES = /* @__PURE__ */ new Set([
+  "verified",
+  "pending",
+  "unverified",
+  "failed",
+  "grace-period",
+  "error"
+]);
+var ALWAYS_VALID_STATUSES = /* @__PURE__ */ new Set([
+  "verified",
+  "pending"
+]);
+function safeParseDate(value) {
+  if (value === null) return void 0;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? void 0 : date;
+}
+function computeIsValid(status, graceDeadline) {
+  if (ALWAYS_VALID_STATUSES.has(status)) return true;
+  if (status === "grace-period") {
+    return graceDeadline !== void 0 && graceDeadline.getTime() > Date.now();
+  }
+  return false;
+}
+function parseAttributionStatus(headers) {
+  const rawStatus = headers.get("X-Attribution-Status");
+  if (rawStatus === null) return null;
+  if (!VALID_ATTRIBUTION_STATUSES.has(rawStatus)) {
+    return { status: "error", isValid: false };
+  }
+  const status = rawStatus;
+  const graceDeadline = safeParseDate(headers.get("X-Attribution-Grace-Deadline"));
+  const verifiedAt = safeParseDate(headers.get("X-Attribution-Verified-At"));
+  const isValid = computeIsValid(status, graceDeadline);
+  return {
+    status,
+    isValid,
+    ...graceDeadline !== void 0 ? { graceDeadline } : {},
+    ...verifiedAt !== void 0 ? { verifiedAt } : {}
+  };
+}
+
+// src/client/index.ts
+var QuikturnLogos = class {
+  constructor(options) {
+    const token = options.token?.trim() ?? "";
+    if (!token) {
+      throw new AuthenticationError("Token is required");
+    }
+    if (token.startsWith("sk_")) {
+      throw new AuthenticationError(
+        "Server keys (sk_) are not allowed in the browser client"
+      );
+    }
+    this.token = token;
+    this.baseUrl = options.baseUrl;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.listeners = /* @__PURE__ */ new Map();
+    this.objectUrls = /* @__PURE__ */ new Set();
+  }
+  /**
+   * Fetches a logo for the given domain and returns a {@link BrowserLogoResponse}.
+   *
+   * The returned `url` is a `blob:` object URL suitable for `<img src>`.
+   * The client tracks these URLs and revokes them on {@link destroy}.
+   *
+   * @param domain  - The domain to fetch a logo for (e.g. "github.com").
+   * @param options - Optional request configuration.
+   * @returns A BrowserLogoResponse containing the blob URL, raw Blob, content type, and metadata.
+   *
+   * @example
+   * ```ts
+   * const client = new QuikturnLogos({ token: "qt_abc123" });
+   * const { url, metadata } = await client.get("github.com", { size: 256 });
+   * document.querySelector("img")!.src = url;
+   * ```
+   */
+  async get(domain, options) {
+    const url = logoUrl(domain, {
+      token: this.token,
+      size: options?.size,
+      width: options?.width,
+      greyscale: options?.greyscale,
+      theme: options?.theme,
+      format: options?.format,
+      autoScrape: options?.autoScrape,
+      baseUrl: this.baseUrl
+    });
+    const format = options?.format;
+    const acceptHeader = format ? format.startsWith("image/") ? format : `image/${format}` : void 0;
+    let response = await browserFetch(url, {
+      maxRetries: this.maxRetries,
+      signal: options?.signal,
+      format: acceptHeader,
+      onRateLimitWarning: (remaining, limit) => this.emit("rateLimitWarning", remaining, limit),
+      onQuotaWarning: (remaining, limit) => this.emit("quotaWarning", remaining, limit)
+    });
+    if (options?.autoScrape) {
+      response = await handleScrapeResponse(response, url, browserFetch, {
+        scrapeTimeout: options?.scrapeTimeout,
+        onScrapeProgress: options?.onScrapeProgress,
+        signal: options?.signal,
+        token: this.token
+      });
+    }
+    const contentLength = response.headers.get("Content-Length");
+    if (contentLength) {
+      const size = parseInt(contentLength, 10);
+      if (!Number.isNaN(size) && size > MAX_RESPONSE_BODY_BYTES) {
+        throw new LogoError(
+          `Response body (${size} bytes) exceeds maximum allowed size`,
+          "UNEXPECTED_ERROR"
+        );
+      }
+    }
+    const blob = await response.blob();
+    const contentType = response.headers.get("Content-Type") || "image/png";
+    const metadata = parseLogoHeaders(response.headers);
+    const objectUrl = URL.createObjectURL(blob);
+    this.objectUrls.add(objectUrl);
+    return { url: objectUrl, blob, contentType, metadata };
+  }
+  /**
+   * Returns a plain URL string for the given domain without making a network request.
+   *
+   * Useful for `<img>` tags, CSS `background-image`, or preloading hints where
+   * a direct URL is needed rather than a blob.
+   *
+   * @param domain  - The domain to build a URL for.
+   * @param options - Optional request parameters (size, format, etc.).
+   * @returns A fully-qualified Logos API URL string.
+   *
+   * @example
+   * ```ts
+   * const client = new QuikturnLogos({ token: "qt_abc123" });
+   * const url = client.getUrl("github.com", { size: 128, format: "webp" });
+   * // => "https://logos.getquikturn.io/github.com?token=qt_abc123&format=webp"
+   * ```
+   */
+  getUrl(domain, options) {
+    return logoUrl(domain, {
+      token: this.token,
+      size: options?.size,
+      width: options?.width,
+      greyscale: options?.greyscale,
+      theme: options?.theme,
+      format: options?.format,
+      baseUrl: this.baseUrl
+    });
+  }
+  /**
+   * Registers an event listener for a client event.
+   *
+   * @param event   - The event name ("rateLimitWarning" or "quotaWarning").
+   * @param handler - Callback invoked with (remaining, limit) when the event fires.
+   */
+  on(event, handler) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(handler);
+  }
+  /**
+   * Removes a previously registered event listener.
+   *
+   * @param event   - The event name.
+   * @param handler - The handler to remove.
+   */
+  off(event, handler) {
+    this.listeners.get(event)?.delete(handler);
+  }
+  /**
+   * Cleans up client resources.
+   *
+   * Revokes all tracked `blob:` object URLs to free memory, and removes
+   * all registered event listeners. The client instance can still be used
+   * after destroy, but previously created blob URLs will no longer work.
+   */
+  destroy() {
+    for (const url of this.objectUrls) {
+      URL.revokeObjectURL(url);
+    }
+    this.objectUrls.clear();
+    this.listeners.clear();
+  }
+  /**
+   * Emits an event to all registered listeners.
+   *
+   * @param event     - The event name to emit.
+   * @param remaining - The remaining count.
+   * @param limit     - The tier limit.
+   */
+  emit(event, remaining, limit) {
+    for (const handler of this.listeners.get(event) ?? []) {
+      handler(remaining, limit);
+    }
+  }
+};
+
+exports.QuikturnLogos = QuikturnLogos;
+exports.browserFetch = browserFetch;
+exports.handleScrapeResponse = handleScrapeResponse;
+exports.parseAttributionStatus = parseAttributionStatus;