@quikturn/logos 0.2.0

package/dist/client/index.d.ts

@@ -0,0 +1,399 @@
+/** 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 browser client's `get()` method.
+ *
+ * - `url`         — A `blob:` object URL suitable for `<img src>`.
+ * - `blob`        — The raw image Blob for further processing.
+ * - `contentType` — MIME type of the image (e.g. "image/webp").
+ * - `metadata`    — Parsed response headers (cache, rate-limit, quota, transformation).
+ */
+interface BrowserLogoResponse {
+    url: string;
+    blob: Blob;
+    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;
+}
+/**
+ * Possible attribution verification states for free-tier consumers.
+ *
+ * - "verified"     — Attribution confirmed and valid.
+ * - "pending"      — Verification in progress; treated as valid.
+ * - "unverified"   — Attribution not yet set up.
+ * - "failed"       — Verification attempted but failed.
+ * - "grace-period" — Temporary grace; validity depends on graceDeadline.
+ * - "error"        — An error occurred during verification.
+ */
+type AttributionStatus = "verified" | "pending" | "unverified" | "failed" | "grace-period" | "error";
+/**
+ * Structured attribution information parsed from response headers.
+ *
+ * - `status`        — Current attribution verification state.
+ * - `graceDeadline` — If in grace period, the deadline by which attribution must be verified.
+ * - `verifiedAt`    — Timestamp of when attribution was last verified.
+ * - `isValid`       — Derived boolean: true when status is "verified", "pending",
+ *                      or "grace-period" with a future graceDeadline.
+ */
+interface AttributionInfo {
+    status: AttributionStatus;
+    graceDeadline?: Date;
+    verifiedAt?: Date;
+    isValid: boolean;
+}
+
+/**
+ * @quikturn/logos SDK — Browser Fetch Wrapper
+ *
+ * Low-level fetch wrapper for the browser client 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%.
+ *
+ * This module NEVER sets an Authorization header. Publishable keys are
+ * passed as query parameters by the URL builder, not as bearer tokens.
+ */
+/**
+ * Options accepted by {@link browserFetch}.
+ *
+ * - `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 FetcherOptions {
+    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 error mapping and retry logic.
+ *
+ * **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 - Optional fetch configuration.
+ * @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 browserFetch(url: string, options?: FetcherOptions): Promise<Response>;
+
+/**
+ * @quikturn/logos SDK -- Scrape Poller
+ *
+ * Handles 202 (scrape_pending) responses from the Logos API. When the API
+ * returns a 202 with a {@link ScrapePendingResponse} body, this module polls
+ * the scrape job status URL with exponential backoff until the job completes,
+ * fails, or the configured timeout elapses.
+ *
+ * On completion, re-fetches the original logo URL (with optional token) and
+ * returns the final Response to the caller.
+ */
+
+/** A fetch function that takes a URL and returns a Response promise. */
+type FetchFn = (url: string) => Promise<Response>;
+/**
+ * Options accepted by {@link handleScrapeResponse}.
+ *
+ * - `scrapeTimeout`    -- Maximum time (ms) to wait for the scrape to complete. Default: 30_000.
+ * - `onScrapeProgress` -- Called after each poll with the latest progress event.
+ * - `signal`           -- An `AbortSignal` to cancel the polling loop.
+ * - `token`            -- API token appended to the final logo re-fetch URL.
+ */
+interface ScrapePollerOptions {
+    scrapeTimeout?: number;
+    onScrapeProgress?: (event: ScrapeProgressEvent) => void;
+    signal?: AbortSignal;
+    token?: string;
+}
+/**
+ * Inspects a response from the Logos API and, if it is a 202 (scrape pending),
+ * polls the scrape job until completion and re-fetches the logo.
+ *
+ * **Non-202 responses** are returned immediately as a passthrough.
+ *
+ * **202 responses** trigger the following lifecycle:
+ * 1. Parse the {@link ScrapePendingResponse} JSON body to extract `scrapeJob`.
+ * 2. Wait `estimatedWaitMs` (the initial backoff interval).
+ * 3. Poll `scrapeJob.pollUrl` via `fetchFn`, parse the {@link ScrapeProgressEvent}.
+ * 4. Call `onScrapeProgress` with the event.
+ * 5. If `status === "complete"`, re-fetch `originalUrl` (with token if provided).
+ * 6. If `status === "failed"`, throw `LogoError` with code `SCRAPE_FAILED`.
+ * 7. If `status === "pending"`, double the backoff (capped at 5 s) and repeat.
+ * 8. If `scrapeTimeout` elapses, throw {@link ScrapeTimeoutError}.
+ * 9. If `signal` is aborted, throw `LogoError` with code `ABORT_ERROR`.
+ *
+ * @param response    -- The raw Response from the initial logo fetch.
+ * @param originalUrl -- The original logo URL (re-fetched after scrape completes).
+ * @param fetchFn     -- The fetch function (typically `browserFetch`).
+ * @param options     -- Optional polling configuration.
+ * @returns The final logo Response on success.
+ *
+ * @throws {ScrapeTimeoutError} When polling exceeds `scrapeTimeout`.
+ * @throws {LogoError} When the scrape job fails, is aborted, or encounters a network error.
+ */
+declare function handleScrapeResponse(response: Response, originalUrl: string, fetchFn: FetchFn, options?: ScrapePollerOptions): Promise<Response>;
+
+/**
+ * @quikturn/logos SDK — Attribution Header Parser
+ *
+ * Parses attribution-related response headers returned by the Cloudflare Worker
+ * for free-tier consumers. The worker attaches these headers to indicate whether
+ * the consumer has properly attributed Quikturn on their site.
+ *
+ * | Header                           | Field           |
+ * |----------------------------------|-----------------|
+ * | `X-Attribution-Status`           | `status`        |
+ * | `X-Attribution-Grace-Deadline`   | `graceDeadline` |
+ * | `X-Attribution-Verified-At`      | `verifiedAt`    |
+ *
+ * The derived `isValid` field is computed from the status:
+ * - "verified"     -> true
+ * - "pending"      -> true
+ * - "grace-period" -> true only if graceDeadline exists and is in the future
+ * - "unverified"   -> false
+ * - "failed"       -> false
+ * - "error"        -> false
+ */
+
+/**
+ * Parses attribution response headers into a typed `AttributionInfo` object.
+ *
+ * Returns `null` when the `X-Attribution-Status` header is absent, indicating
+ * that the response is not from a free-tier request (attribution does not apply).
+ *
+ * @param headers - The `Headers` object from a fetch `Response`.
+ * @returns An `AttributionInfo` object, or `null` if no attribution header is present.
+ *
+ * @example
+ * ```ts
+ * const attribution = parseAttributionStatus(response.headers);
+ * if (attribution && !attribution.isValid) {
+ *   console.warn("Attribution required for free-tier usage");
+ * }
+ * ```
+ */
+declare function parseAttributionStatus(headers: Headers): AttributionInfo | null;
+
+/**
+ * @quikturn/logos SDK — Browser Client Class
+ *
+ * High-level API for fetching logos in the browser. Integrates the URL builder,
+ * browser fetcher, scrape poller, and header parser into a single ergonomic
+ * class with lifecycle management and event emission.
+ *
+ * Usage:
+ * ```ts
+ * import { QuikturnLogos } from "@quikturn/logos/client";
+ *
+ * const client = new QuikturnLogos({ token: "qt_your_key" });
+ * const { url, blob, metadata } = await client.get("github.com", { size: 256 });
+ * document.querySelector("img").src = url;
+ *
+ * // Clean up when done
+ * client.destroy();
+ * ```
+ */
+
+/**
+ * Configuration options for the browser client constructor.
+ *
+ * - `token`      — Required publishable key (qt_/pk_ prefix). Server keys (sk_) 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 BrowserClientOptions {
+    token: string;
+    baseUrl?: string;
+    maxRetries?: number;
+}
+/**
+ * Options accepted by {@link QuikturnLogos.get}.
+ *
+ * - `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 GetOptions {
+    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;
+/**
+ * Browser client for the Quikturn Logos API.
+ *
+ * Manages the full lifecycle of logo requests including URL construction,
+ * network fetching with retries, scrape polling, response parsing, and
+ * blob URL management.
+ *
+ * The client tracks all created `blob:` object URLs and revokes them on
+ * {@link destroy}, preventing memory leaks in long-lived browser sessions.
+ */
+declare class QuikturnLogos {
+    private readonly token;
+    private readonly baseUrl?;
+    private readonly maxRetries;
+    private readonly listeners;
+    private readonly objectUrls;
+    constructor(options: BrowserClientOptions);
+    /**
+     * 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;
+     * ```
+     */
+    get(domain: string, options?: GetOptions): Promise<BrowserLogoResponse>;
+    /**
+     * 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: string, options?: Omit<GetOptions, "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;
+    /**
+     * 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(): 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 BrowserClientOptions, type ClientEvent, type EventHandler, type FetcherOptions, type GetOptions, QuikturnLogos, type ScrapePollerOptions, browserFetch, handleScrapeResponse, parseAttributionStatus };