@quikturn/logos 0.2.0

package/dist/server/index.d.cts

@@ -0,0 +1,423 @@
+/** Theme adjusts the gamma curve applied during image transformation. */
+type ThemeOption = "light" | "dark";
+/** Full MIME-type output formats supported by the worker's image pipeline. */
+type SupportedOutputFormat = "image/png" | "image/jpeg" | "image/webp" | "image/avif";
+/** Shorthand aliases accepted in query parameters and SDK options. */
+type FormatShorthand = "png" | "jpeg" | "webp" | "avif";
+/**
+ * Structured metadata parsed from the worker's response headers.
+ *
+ * Every successful response includes cache, rate-limit, and quota information.
+ * Transformation metadata is present when the image pipeline processes the request.
+ */
+interface LogoMetadata {
+    cache: {
+        status: "HIT" | "MISS";
+    };
+    rateLimit: {
+        remaining: number;
+        reset: Date;
+    };
+    quota: {
+        remaining: number;
+        limit: number;
+    };
+    transformation: {
+        applied: boolean;
+        status?: "not-requested" | "unsupported-format" | "transformation-error";
+        method?: "images-binding";
+        width?: number;
+        greyscale?: boolean;
+        gamma?: number;
+    };
+    tokenPrefix?: string;
+}
+/**
+ * Response shape returned by the server client's `get()` method.
+ *
+ * - `buffer`      — Raw image bytes as a Node.js Buffer.
+ * - `contentType` — MIME type of the image (e.g. "image/png").
+ * - `metadata`    — Parsed response headers (cache, rate-limit, quota, transformation).
+ */
+interface ServerLogoResponse {
+    buffer: Buffer;
+    contentType: string;
+    metadata: LogoMetadata;
+}
+/** Lifecycle status of a background scrape job. */
+type ScrapeJobStatus = "pending" | "complete" | "failed";
+/**
+ * Event emitted during scrape polling to report progress.
+ *
+ * - `status`   — Current job status.
+ * - `progress` — Optional progress percentage (0-100).
+ * - `logo`     — Present when status is "complete"; contains the scraped logo details.
+ * - `error`    — Present when status is "failed"; contains the error message.
+ */
+interface ScrapeProgressEvent {
+    status: ScrapeJobStatus;
+    progress?: number;
+    logo?: {
+        id: number;
+        url: string;
+        companyId: number;
+        companyName: string;
+    };
+    error?: string;
+}
+/**
+ * Discriminated union of all machine-readable error codes used by the SDK.
+ *
+ * Each code maps to a specific error class or error condition:
+ * - `DOMAIN_VALIDATION_ERROR` — {@link DomainValidationError}
+ * - `RATE_LIMIT_ERROR`        — {@link RateLimitError}
+ * - `QUOTA_EXCEEDED_ERROR`    — {@link QuotaExceededError}
+ * - `AUTHENTICATION_ERROR`    — {@link AuthenticationError}
+ * - `FORBIDDEN_ERROR`         — {@link ForbiddenError}
+ * - `NOT_FOUND_ERROR`         — {@link NotFoundError}
+ * - `SCRAPE_TIMEOUT_ERROR`    — {@link ScrapeTimeoutError}
+ * - `ABORT_ERROR`             — Abort signal triggered
+ * - `NETWORK_ERROR`           — Network failure
+ * - `SERVER_ERROR`            — HTTP 5xx response
+ * - `UNEXPECTED_ERROR`        — Unhandled HTTP status
+ * - `SCRAPE_FAILED`           — Scrape job failed
+ * - `SCRAPE_PARSE_ERROR`      — Scrape response parsing failure
+ * - `BAD_REQUEST_ERROR`       — {@link BadRequestError}
+ */
+type LogoErrorCode = "DOMAIN_VALIDATION_ERROR" | "RATE_LIMIT_ERROR" | "QUOTA_EXCEEDED_ERROR" | "AUTHENTICATION_ERROR" | "FORBIDDEN_ERROR" | "NOT_FOUND_ERROR" | "SCRAPE_TIMEOUT_ERROR" | "ABORT_ERROR" | "NETWORK_ERROR" | "SERVER_ERROR" | "UNEXPECTED_ERROR" | "SCRAPE_FAILED" | "SCRAPE_PARSE_ERROR" | "BAD_REQUEST_ERROR";
+
+/**
+ * @quikturn/logos SDK — Error Classes
+ *
+ * Structured error hierarchy for the Logos SDK. All errors extend LogoError,
+ * which itself extends the native Error class with a machine-readable `code`
+ * and an optional HTTP `status`.
+ *
+ * The Object.setPrototypeOf pattern is required to restore the prototype chain
+ * when extending built-in classes (Error) under ES5 downlevel emit, ensuring
+ * `instanceof` checks work correctly in all environments.
+ */
+
+/**
+ * Base error class for all Logos SDK errors.
+ *
+ * Every error carries a human-readable `message`, a machine-readable `code`
+ * (a {@link LogoErrorCode} discriminated union), and an optional HTTP `status` code.
+ */
+declare class LogoError extends Error {
+    code: LogoErrorCode;
+    status?: number;
+    constructor(message: string, code: LogoErrorCode, status?: number);
+}
+
+/**
+ * @quikturn/logos SDK -- Server Batch Operations
+ *
+ * Fetches logos for multiple domains with concurrency control, order
+ * preservation, partial failure handling, rate-limit backoff, and
+ * AbortSignal support.
+ *
+ * The module is decoupled from the server fetcher via a `fetchFn`
+ * parameter, making it easy to test and compose with different fetch
+ * implementations.
+ */
+
+/**
+ * Options for batch logo fetching.
+ *
+ * - `concurrency`     -- Maximum parallel fetches. Default: 5.
+ * - `size`            -- Output width in pixels.
+ * - `greyscale`       -- When true, applies saturation: 0 transformation.
+ * - `theme`           -- "light" or "dark" gamma curve.
+ * - `format`          -- Output image format (MIME type or shorthand).
+ * - `signal`          -- AbortSignal to cancel remaining batch items.
+ * - `continueOnError` -- When true (default), errors are captured per-domain
+ *                        rather than aborting the entire batch.
+ */
+interface BatchOptions {
+    concurrency?: number;
+    size?: number;
+    greyscale?: boolean;
+    theme?: ThemeOption;
+    format?: SupportedOutputFormat | FormatShorthand;
+    signal?: AbortSignal;
+    continueOnError?: boolean;
+}
+/**
+ * A single result from a batch fetch operation.
+ *
+ * On success: `success` is true, `buffer`, `contentType`, and `metadata` are set.
+ * On failure: `success` is false, `error` is set.
+ */
+interface BatchResult {
+    domain: string;
+    success: boolean;
+    buffer?: Buffer;
+    contentType?: string;
+    metadata?: LogoMetadata;
+    error?: LogoError;
+}
+/**
+ * Fetches logos for multiple domains with concurrency control.
+ * Yields results in the same order as the input domains array.
+ *
+ * The `fetchFn` parameter is a function that takes a domain and returns
+ * a result object with buffer, contentType, metadata. This decouples
+ * the batch module from the server fetcher implementation.
+ *
+ * Rate limit handling: when fetchFn throws a {@link RateLimitError},
+ * the batch pauses ALL pending work for `retryAfter` seconds before
+ * retrying the failed domain.
+ *
+ * @param domains  - Array of domain strings to fetch logos for.
+ * @param fetchFn  - Async function that fetches a single logo by domain.
+ * @param options  - Optional batch configuration.
+ * @yields {BatchResult} Results in the same order as the input domains.
+ */
+declare function getMany(domains: string[], fetchFn: (domain: string) => Promise<{
+    buffer: Buffer;
+    contentType: string;
+    metadata: LogoMetadata;
+}>, options?: BatchOptions): AsyncGenerator<BatchResult>;
+
+/**
+ * @quikturn/logos SDK — Server Fetch Wrapper
+ *
+ * Low-level fetch wrapper for the server entry point. Handles HTTP error
+ * mapping, retry logic for rate-limited and server-error responses,
+ * AbortSignal propagation, and proactive warning callbacks when rate-limit
+ * or quota headroom drops below 10%.
+ *
+ * Unlike the browser fetcher, this module sends the secret key as an
+ * `Authorization: Bearer` header — tokens are NEVER appended as query
+ * parameters.
+ */
+/**
+ * Options accepted by {@link serverFetch}.
+ *
+ * - `token`              — Required: secret key (`sk_` prefix) sent as Bearer token.
+ * - `maxRetries`         — Maximum number of retry attempts for 429/500 responses. Default: 2.
+ * - `signal`             — An `AbortSignal` to cancel the in-flight request.
+ * - `format`             — MIME type string used as the `Accept` request header.
+ * - `onRateLimitWarning` — Called when `X-RateLimit-Remaining` drops below 10% of the limit.
+ * - `onQuotaWarning`     — Called when `X-Quota-Remaining` drops below 10% of the limit.
+ */
+interface ServerFetcherOptions {
+    token: string;
+    maxRetries?: number;
+    signal?: AbortSignal;
+    format?: string;
+    onRateLimitWarning?: (remaining: number, limit: number) => void;
+    onQuotaWarning?: (remaining: number, limit: number) => void;
+}
+/**
+ * Performs a fetch request to the Logos API with Bearer token authentication,
+ * error mapping, and retry logic.
+ *
+ * **Key difference from browser fetcher:**
+ * The secret key is sent as an `Authorization: Bearer {token}` header and is
+ * NEVER included in the URL query string.
+ *
+ * **Error mapping:**
+ * | Status | Error Class           | Notes                                      |
+ * |--------|-----------------------|--------------------------------------------|
+ * | 401    | AuthenticationError   | Invalid or missing API token               |
+ * | 403    | ForbiddenError        | Body text used as `reason`                 |
+ * | 404    | NotFoundError         | Domain extracted from URL path             |
+ * | 429    | QuotaExceededError    | When `X-Quota-Limit` header is present     |
+ * | 429    | RateLimitError        | After retries are exhausted                |
+ * | 500    | LogoError             | After a single retry attempt               |
+ *
+ * **Retry behavior:**
+ * - 429: Waits `Retry-After` seconds (default 60s), retries up to `maxRetries`.
+ *        If `X-Quota-Limit` is present, throws `QuotaExceededError` immediately.
+ * - 500: Retries once after a 1-second delay, then throws.
+ * - AbortError: Never retried; throws immediately.
+ * - Network errors: Never retried; throws immediately.
+ *
+ * @param url     - Fully-qualified Logos API URL (built by `logoUrl`).
+ * @param options - Fetch configuration including the required `token`.
+ * @returns The raw `Response` object on success (2xx).
+ *
+ * @throws {AuthenticationError} On 401.
+ * @throws {ForbiddenError} On 403.
+ * @throws {NotFoundError} On 404.
+ * @throws {RateLimitError} On 429 after retries exhausted (no quota header).
+ * @throws {QuotaExceededError} On 429 with `X-Quota-Limit` header.
+ * @throws {LogoError} On 500, network error, or abort.
+ */
+declare function serverFetch(url: string, options: ServerFetcherOptions): Promise<Response>;
+
+/**
+ * @quikturn/logos SDK — Server Client Class
+ *
+ * High-level API for fetching logos on the server (Node.js). Integrates the
+ * URL builder, server fetcher, batch module, scrape poller, and header parser
+ * into a single ergonomic class with event emission.
+ *
+ * Unlike the browser client, the server client:
+ * - Requires a secret key (sk_ prefix) instead of publishable keys.
+ * - Sends authentication via Authorization: Bearer header, not query params.
+ * - Returns raw Buffers instead of Blobs.
+ * - Provides getStream() for streaming responses.
+ * - Provides getMany() for concurrent batch fetching.
+ *
+ * Usage:
+ * ```ts
+ * import { QuikturnLogos } from "@quikturn/logos/server";
+ *
+ * const client = new QuikturnLogos({ secretKey: "sk_your_key" });
+ * const { buffer, contentType, metadata } = await client.get("github.com", { size: 256 });
+ * ```
+ */
+
+/**
+ * Configuration options for the server client constructor.
+ *
+ * - `secretKey`  — Required secret key (sk_ prefix). Publishable keys (qt_/pk_) are rejected.
+ * - `baseUrl`    — Override the default API base URL. Useful for testing or proxied environments.
+ * - `maxRetries` — Maximum number of retry attempts for rate-limited/server-error responses. Default: 2.
+ */
+interface ServerClientOptions {
+    secretKey: string;
+    baseUrl?: string;
+    maxRetries?: number;
+}
+/**
+ * Options accepted by {@link QuikturnLogos.get} and {@link QuikturnLogos.getStream}.
+ *
+ * - `size`            — Output width in pixels.
+ * - `width`           — Alias for `size`.
+ * - `greyscale`       — When true, returns a greyscale image.
+ * - `theme`           — "light" or "dark" gamma adjustment.
+ * - `format`          — Output image format (MIME type or shorthand).
+ * - `autoScrape`      — When true, triggers background scrape if logo is not found.
+ * - `scrapeTimeout`   — Maximum time (ms) to wait for a scrape to complete.
+ * - `onScrapeProgress`— Callback fired on each scrape poll.
+ * - `signal`          — AbortSignal to cancel the request.
+ */
+interface ServerGetOptions {
+    size?: number;
+    width?: number;
+    greyscale?: boolean;
+    theme?: ThemeOption;
+    format?: SupportedOutputFormat | FormatShorthand;
+    autoScrape?: boolean;
+    scrapeTimeout?: number;
+    onScrapeProgress?: (event: ScrapeProgressEvent) => void;
+    signal?: AbortSignal;
+}
+/** Events emitted by the client via the on()/off() interface. */
+type ClientEvent = "rateLimitWarning" | "quotaWarning";
+/** Handler signature for client events. Receives the remaining count and tier limit. */
+type EventHandler = (remaining: number, limit: number) => void;
+/**
+ * Server client for the Quikturn Logos API.
+ *
+ * Manages the full lifecycle of logo requests including URL construction,
+ * network fetching with Bearer token authentication and retries, scrape
+ * polling, response parsing, batch fetching, and streaming.
+ */
+declare class QuikturnLogos {
+    private readonly secretKey;
+    private readonly baseUrl?;
+    private readonly maxRetries;
+    private readonly listeners;
+    constructor(options: ServerClientOptions);
+    /**
+     * 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);
+     * ```
+     */
+    get(domain: string, options?: ServerGetOptions): Promise<ServerLogoResponse>;
+    /**
+     * 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!);
+     *   }
+     * }
+     * ```
+     */
+    getMany(domains: string[], options?: Omit<BatchOptions, "signal"> & {
+        signal?: AbortSignal;
+    }): AsyncGenerator<BatchResult>;
+    /**
+     * 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);
+     * ```
+     */
+    getStream(domain: string, options?: ServerGetOptions): Promise<ReadableStream>;
+    /**
+     * 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: string, options?: Omit<ServerGetOptions, "autoScrape" | "scrapeTimeout" | "onScrapeProgress" | "signal">): string;
+    /**
+     * 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: ClientEvent, handler: EventHandler): void;
+    /**
+     * Removes a previously registered event listener.
+     *
+     * @param event   - The event name.
+     * @param handler - The handler to remove.
+     */
+    off(event: ClientEvent, handler: EventHandler): void;
+    /**
+     * Emits an event to all registered listeners.
+     *
+     * @param event     - The event name to emit.
+     * @param remaining - The remaining count.
+     * @param limit     - The tier limit.
+     */
+    private emit;
+}
+
+export { type BatchOptions, type BatchResult, type ClientEvent, type EventHandler, QuikturnLogos, type ServerClientOptions, type ServerFetcherOptions, type ServerGetOptions, getMany, serverFetch };