@quikturn/logos 0.2.0

package/dist/server/index.cjs

@@ -0,0 +1,858 @@
+'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/server/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 serverFetch(url, options) {
+  const { token } = 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 = {
+    Authorization: `Bearer ${token}`
+  };
+  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/server/batch.ts
+var MAX_RATE_LIMIT_RETRIES = 3;
+async function* getMany(domains, fetchFn, options) {
+  if (domains.length === 0) return;
+  const concurrency = options?.concurrency ?? 5;
+  const continueOnError = options?.continueOnError ?? true;
+  const signal = options?.signal;
+  const results = new Array(domains.length);
+  const settled = /* @__PURE__ */ new Set();
+  let nextYieldIndex = 0;
+  let notifyReady = null;
+  let workersFinished = false;
+  function waitForNext() {
+    if (settled.has(nextYieldIndex) || workersFinished) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      notifyReady = resolve;
+    });
+  }
+  function wakeGenerator() {
+    if (notifyReady) {
+      const fn = notifyReady;
+      notifyReady = null;
+      fn();
+    }
+  }
+  function markSettled(index) {
+    settled.add(index);
+    if (index === nextYieldIndex) {
+      wakeGenerator();
+    }
+  }
+  async function processDomain(index, domain) {
+    let rateLimitRetries = 0;
+    while (true) {
+      try {
+        const { buffer, contentType, metadata } = await fetchFn(domain);
+        results[index] = {
+          domain,
+          success: true,
+          buffer,
+          contentType,
+          metadata
+        };
+        markSettled(index);
+        return;
+      } catch (err) {
+        if (err instanceof RateLimitError) {
+          rateLimitRetries++;
+          if (rateLimitRetries > MAX_RATE_LIMIT_RETRIES) {
+            if (continueOnError) {
+              results[index] = { domain, success: false, error: err };
+              markSettled(index);
+              return;
+            }
+            throw err;
+          }
+          const waitMs = Math.max(1, err.retryAfter) * 1e3;
+          await delay(waitMs, signal);
+          continue;
+        }
+        if (continueOnError) {
+          const logoError = err instanceof LogoError ? err : new LogoError(
+            err instanceof Error ? err.message : "Unknown error",
+            "UNEXPECTED_ERROR"
+          );
+          results[index] = {
+            domain,
+            success: false,
+            error: logoError
+          };
+          markSettled(index);
+          return;
+        }
+        throw err;
+      }
+    }
+  }
+  let queueIndex = 0;
+  async function worker() {
+    while (queueIndex < domains.length) {
+      if (signal?.aborted) return;
+      const idx = queueIndex++;
+      const domain = domains[idx];
+      await processDomain(idx, domain);
+    }
+  }
+  const workerCount = Math.min(concurrency, domains.length);
+  const workers = [];
+  for (let i = 0; i < workerCount; i++) {
+    workers.push(worker());
+  }
+  void Promise.allSettled(workers).then(() => {
+    workersFinished = true;
+    wakeGenerator();
+  });
+  while (nextYieldIndex < domains.length) {
+    await waitForNext();
+    if (!settled.has(nextYieldIndex)) {
+      break;
+    }
+    while (nextYieldIndex < domains.length && settled.has(nextYieldIndex)) {
+      yield results[nextYieldIndex];
+      nextYieldIndex++;
+    }
+  }
+}
+
+// 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/server/index.ts
+var QuikturnLogos = class {
+  constructor(options) {
+    const key = options.secretKey?.trim() ?? "";
+    if (!key) {
+      throw new AuthenticationError("Secret key is required");
+    }
+    if (!key.startsWith("sk_")) {
+      throw new AuthenticationError(
+        "Server client requires a secret key (sk_ prefix)"
+      );
+    }
+    this.secretKey = key;
+    this.baseUrl = options.baseUrl;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.listeners = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Fetches a logo for the given domain and returns a {@link ServerLogoResponse}.
+   *
+   * The returned `buffer` is a Node.js Buffer containing the raw image bytes.
+   *
+   * @param domain  - The domain to fetch a logo for (e.g. "github.com").
+   * @param options - Optional request configuration.
+   * @returns A ServerLogoResponse containing the Buffer, content type, and metadata.
+   *
+   * @example
+   * ```ts
+   * const client = new QuikturnLogos({ secretKey: "sk_your_key" });
+   * const { buffer, contentType } = await client.get("github.com", { size: 256 });
+   * fs.writeFileSync("logo.png", buffer);
+   * ```
+   */
+  async get(domain, options) {
+    const url = logoUrl(domain, {
+      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 serverFetch(url, {
+      token: this.secretKey,
+      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) {
+      const fetchForPoller = (fetchUrl) => serverFetch(fetchUrl, {
+        token: this.secretKey,
+        maxRetries: this.maxRetries,
+        signal: options?.signal
+      });
+      response = await handleScrapeResponse(
+        response,
+        url,
+        fetchForPoller,
+        {
+          scrapeTimeout: options?.scrapeTimeout,
+          onScrapeProgress: options?.onScrapeProgress,
+          signal: options?.signal
+        }
+      );
+    }
+    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 arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    const contentType = response.headers.get("Content-Type") || "image/png";
+    const metadata = parseLogoHeaders(response.headers);
+    return { buffer, contentType, metadata };
+  }
+  /**
+   * Fetches logos for multiple domains with concurrency control.
+   *
+   * Yields {@link BatchResult} items in the same order as the input domains.
+   * Delegates to the batch module's `getMany` with a fetch function that
+   * calls `this.get()` internally.
+   *
+   * @param domains - Array of domain strings to fetch logos for.
+   * @param options - Optional batch configuration (concurrency, format, etc.).
+   * @yields BatchResult items for each domain.
+   *
+   * @example
+   * ```ts
+   * const client = new QuikturnLogos({ secretKey: "sk_your_key" });
+   * for await (const result of client.getMany(["github.com", "gitlab.com"])) {
+   *   if (result.success) {
+   *     fs.writeFileSync(`${result.domain}.png`, result.buffer!);
+   *   }
+   * }
+   * ```
+   */
+  async *getMany(domains, options) {
+    const fetchForBatch = async (domain) => {
+      const result = await this.get(domain, {
+        size: options?.size,
+        greyscale: options?.greyscale,
+        theme: options?.theme,
+        format: options?.format,
+        signal: options?.signal
+      });
+      return result;
+    };
+    yield* getMany(domains, fetchForBatch, {
+      concurrency: options?.concurrency,
+      signal: options?.signal,
+      continueOnError: options?.continueOnError
+    });
+  }
+  /**
+   * Fetches a logo and returns the raw Response body as a ReadableStream.
+   *
+   * Useful for piping to a file or HTTP response without buffering the
+   * entire image in memory.
+   *
+   * @param domain  - The domain to fetch a logo for.
+   * @param options - Optional request configuration.
+   * @returns A ReadableStream of the response body.
+   * @throws {Error} If the response body is null (streaming not available).
+   *
+   * @example
+   * ```ts
+   * const client = new QuikturnLogos({ secretKey: "sk_your_key" });
+   * const stream = await client.getStream("github.com");
+   * const writable = fs.createWriteStream("logo.png");
+   * Readable.fromWeb(stream).pipe(writable);
+   * ```
+   */
+  async getStream(domain, options) {
+    const url = logoUrl(domain, {
+      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;
+    const response = await serverFetch(url, {
+      token: this.secretKey,
+      maxRetries: this.maxRetries,
+      signal: options?.signal,
+      format: acceptHeader
+    });
+    if (!response.body) {
+      throw new Error("Response body is null \u2014 streaming not available");
+    }
+    return response.body;
+  }
+  /**
+   * Returns a plain URL string for the given domain without making a network request.
+   *
+   * The URL does not include authentication — use Authorization: Bearer header
+   * when fetching. Secret keys (sk_) must never appear in URLs.
+   *
+   * @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 (without token).
+   */
+  getUrl(domain, options) {
+    return logoUrl(domain, {
+      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);
+  }
+  /**
+   * 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.getMany = getMany;
+exports.serverFetch = serverFetch;