@quikturn/logos 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,437 @@
+/**
+ * @quikturn/logos SDK — Public Type Definitions
+ *
+ * All types mirror the Cloudflare Worker's type system exactly.
+ * This file contains only type-level constructs (no runtime code).
+ *
+ * Source of truth: cf-worker-logos/src/types.ts, options.ts, rateLimit.ts, monthlyQuota.ts
+ */
+/** Distinguishes between publishable (browser-safe) and secret (server-only) keys. */
+type KeyType = "publishable" | "secret";
+/** Valid key prefixes used to identify key type from the token string. */
+type KeyPrefix = "qt_" | "pk_" | "sk_";
+/** Subscription tier determining rate limits, monthly quotas, and max image width. */
+type Tier = "free" | "launch" | "growth" | "enterprise";
+/** Current lifecycle status of an API token. */
+type TokenStatus = "active" | "suspended" | "revoked";
+/** 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";
+/**
+ * Options accepted by the URL builder and both client classes.
+ *
+ * - `token`      — Publishable key (qt_/pk_) appended as a query parameter.
+ * - `size`       — Output width in pixels. Clamped to 1..800 (publishable) or 1..1200 (secret). Default: 128.
+ * - `width`      — Alias for `size`.
+ * - `greyscale`  — When true, applies saturation: 0 transformation. Default: false.
+ * - `theme`      — "light" (gamma 0.9) or "dark" (gamma 1.12).
+ * - `format`     — Output image format. Accepts full MIME type or shorthand. Default: "image/png".
+ * - `autoScrape` — When true, triggers a background scrape if the logo is not found. Default: false.
+ * - `baseUrl`    — Override the default API base URL. Useful for testing or proxied environments.
+ */
+interface LogoRequestOptions {
+    token?: string;
+    size?: number;
+    width?: number;
+    greyscale?: boolean;
+    theme?: ThemeOption;
+    format?: SupportedOutputFormat | FormatShorthand;
+    autoScrape?: boolean;
+    baseUrl?: string;
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * Describes a background scrape job returned in a 202 response.
+ *
+ * - `jobId`           — Unique identifier for the scrape job.
+ * - `pollUrl`         — URL to poll for scrape progress.
+ * - `estimatedWaitMs` — Estimated time in milliseconds before the scrape completes.
+ */
+interface ScrapeJob {
+    jobId: string;
+    pollUrl: string;
+    estimatedWaitMs: number;
+}
+/**
+ * The JSON body returned by the worker when a 202 (scrape pending) response is issued.
+ *
+ * - `status`      — Always "scrape_pending".
+ * - `message`     — Human-readable status message.
+ * - `companyId`   — Optional identifier of the matched company.
+ * - `companyName` — Optional name of the matched company.
+ * - `scrapeJob`   — Details for polling the scrape job.
+ */
+interface ScrapePendingResponse {
+    status: "scrape_pending";
+    message: string;
+    companyId?: number;
+    companyName?: string;
+    scrapeJob: ScrapeJob;
+}
+/** 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;
+}
+/**
+ * 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";
+
+/** Root endpoint for the Quikturn Logos API. */
+declare const BASE_URL: "https://logos.getquikturn.io";
+/** Default logo width in pixels when no size/width is provided. */
+declare const DEFAULT_WIDTH: 128;
+/** Maximum width (px) for requests using publishable keys (qt_/pk_). */
+declare const MAX_WIDTH: 800;
+/** Maximum width (px) for requests using secret keys (sk_). */
+declare const MAX_WIDTH_SERVER: 1200;
+/** Default MIME type returned when no format is specified. */
+declare const DEFAULT_FORMAT: SupportedOutputFormat;
+/** All MIME types the Logos API can produce. */
+declare const SUPPORTED_FORMATS: ReadonlySet<SupportedOutputFormat>;
+/** Maps shorthand format strings to their full MIME types. */
+declare const FORMAT_ALIASES: Readonly<Record<FormatShorthand, SupportedOutputFormat>>;
+/**
+ * Per-tier rate limits for publishable-key (browser) requests.
+ * All tiers share a 60-second sliding window.
+ */
+declare const RATE_LIMITS: Readonly<Record<Tier, {
+    requests: number;
+    windowSeconds: number;
+}>>;
+/**
+ * Per-tier rate limits for secret-key (server) requests.
+ * The free tier does not have server-side access.
+ */
+declare const SERVER_RATE_LIMITS: Readonly<Record<Exclude<Tier, "free">, {
+    requests: number;
+    windowSeconds: number;
+}>>;
+/** All subscription tiers as a runtime-iterable tuple. */
+declare const TIERS: readonly Tier[];
+/** All key types as a runtime-iterable tuple. */
+declare const KEY_TYPES: readonly KeyType[];
+/** Maximum logo requests per calendar month for each tier. */
+declare const MONTHLY_LIMITS: Readonly<Record<Tier, number>>;
+
+/**
+ * @quikturn/logos SDK — URL Builder
+ *
+ * Pure function that constructs a fully-qualified Logos API URL from a domain
+ * string and optional request parameters. No network calls are made.
+ *
+ * The URL builder performs strict domain validation (RFC 1035/1123), resolves
+ * size/format options, and appends only non-default query parameters to keep
+ * generated URLs concise.
+ */
+
+/**
+ * Constructs a fully-qualified Logos API URL for the given domain.
+ *
+ * This is a pure function with no side effects. It validates the domain,
+ * resolves size and format options, and builds a URL with only the
+ * non-default query parameters appended.
+ *
+ * @param domain  - The domain to fetch a logo for (e.g. "github.com").
+ * @param options - Optional request parameters (token, size, format, etc.).
+ * @returns A fully-qualified URL string.
+ *
+ * @throws {DomainValidationError} If the domain fails RFC 1035/1123 validation.
+ *
+ * @example
+ * ```ts
+ * logoUrl("github.com");
+ * // => "https://logos.getquikturn.io/github.com"
+ *
+ * logoUrl("github.com", { size: 256, greyscale: true, token: "qt_abc123" });
+ * // => "https://logos.getquikturn.io/github.com?token=qt_abc123&size=256&greyscale=1"
+ * ```
+ */
+declare function logoUrl(domain: string, options?: LogoRequestOptions): string;
+
+/**
+ * @quikturn/logos SDK — Response Header Parser
+ *
+ * Parses structured metadata from Cloudflare Worker response headers into
+ * strongly-typed SDK objects. The worker attaches cache status, rate-limit
+ * counters, monthly quota info, and image transformation details as custom
+ * `X-` headers on every successful response.
+ *
+ * Two public functions are exported:
+ * - `parseLogoHeaders` — extracts a full `LogoMetadata` object.
+ * - `parseRetryAfter`  — extracts the `Retry-After` value for 429 handling.
+ */
+
+/**
+ * Parses Cloudflare Worker response headers into a `LogoMetadata` object.
+ *
+ * Extracts and normalizes the following header families:
+ *
+ * | Header                      | Field                           |
+ * |-----------------------------|---------------------------------|
+ * | `X-Cache-Status`            | `cache.status`                  |
+ * | `X-RateLimit-Remaining`     | `rateLimit.remaining`           |
+ * | `X-RateLimit-Reset`         | `rateLimit.reset` (as `Date`)   |
+ * | `X-Quota-Remaining`         | `quota.remaining`               |
+ * | `X-Quota-Limit`             | `quota.limit`                   |
+ * | `X-Quikturn-Token`          | `tokenPrefix`                   |
+ * | `X-Transformation-Applied`  | `transformation.applied`        |
+ * | `X-Transformation-Status`   | `transformation.status`         |
+ * | `X-Transformation-Method`   | `transformation.method`         |
+ * | `X-Transformation-Width`    | `transformation.width`          |
+ * | `X-Transformation-Greyscale`| `transformation.greyscale`      |
+ * | `X-Transformation-Gamma`    | `transformation.gamma`          |
+ *
+ * Missing or unparseable numeric headers fall back to `0` for required fields
+ * and `undefined` for optional fields. The cache status defaults to `"MISS"`
+ * unless the header value is exactly `"HIT"`.
+ *
+ * @param headers - The `Headers` object from a fetch `Response`.
+ * @returns A fully-populated `LogoMetadata` object.
+ *
+ * @example
+ * ```ts
+ * const response = await fetch(logoUrl("github.com"));
+ * const metadata = parseLogoHeaders(response.headers);
+ * console.log(metadata.cache.status); // "HIT" or "MISS"
+ * ```
+ */
+declare function parseLogoHeaders(headers: Headers): LogoMetadata;
+/**
+ * Parses the `Retry-After` response header into a numeric value (seconds).
+ *
+ * The Logos API always sends `Retry-After` as an integer number of seconds
+ * (not an HTTP-date). Returns `null` when the header is absent or its value
+ * cannot be parsed as a finite number.
+ *
+ * @param headers - The `Headers` object from a fetch `Response`.
+ * @returns The retry delay in seconds, or `null` if not present.
+ *
+ * @example
+ * ```ts
+ * const retryAfter = parseRetryAfter(response.headers);
+ * if (retryAfter !== null) {
+ *   await new Promise((r) => setTimeout(r, retryAfter * 1000));
+ * }
+ * ```
+ */
+declare function parseRetryAfter(headers: Headers): number | null;
+
+/**
+ * @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);
+}
+/**
+ * Thrown when a domain string fails RFC 1035/1123 validation.
+ *
+ * Includes the invalid `domain` for diagnostic purposes.
+ */
+declare class DomainValidationError extends LogoError {
+    domain: string;
+    constructor(message: string, domain: string);
+}
+/**
+ * Thrown when a per-minute rate limit is exceeded (HTTP 429).
+ *
+ * - `retryAfter` — seconds until the next request will be accepted.
+ * - `remaining`  — requests remaining in the current window (always 0).
+ * - `resetAt`    — Date when the rate-limit window resets.
+ */
+declare class RateLimitError extends LogoError {
+    retryAfter: number;
+    remaining: number;
+    resetAt: Date;
+    constructor(message: string, retryAfter: number, remaining: number, resetAt: Date);
+}
+/**
+ * Thrown when the monthly request quota is exhausted (HTTP 429).
+ *
+ * - `retryAfter` — seconds until the quota resets (beginning of next month).
+ * - `limit`      — total monthly quota for the current tier.
+ * - `used`       — number of requests consumed so far this month.
+ */
+declare class QuotaExceededError extends LogoError {
+    retryAfter: number;
+    limit: number;
+    used: number;
+    constructor(message: string, retryAfter: number, limit: number, used: number);
+}
+/**
+ * Thrown when the API token is missing, malformed, or expired (HTTP 401).
+ */
+declare class AuthenticationError extends LogoError {
+    constructor(message: string);
+}
+/**
+ * Thrown when the API token is valid but lacks permission for the
+ * requested operation (HTTP 403).
+ *
+ * - `reason` — machine-readable explanation (e.g. "tier_too_low").
+ */
+declare class ForbiddenError extends LogoError {
+    reason: string;
+    constructor(message: string, reason: string);
+}
+/**
+ * Thrown when no logo exists for the requested domain and auto-scrape
+ * is not enabled (HTTP 404).
+ *
+ * - `domain` — the domain that was looked up.
+ */
+declare class NotFoundError extends LogoError {
+    domain: string;
+    constructor(message: string, domain: string);
+}
+/**
+ * Thrown when a background scrape job exceeds the configured polling timeout.
+ *
+ * - `jobId`   — the unique identifier of the timed-out scrape job.
+ * - `elapsed` — milliseconds elapsed before the timeout was triggered.
+ */
+declare class ScrapeTimeoutError extends LogoError {
+    jobId: string;
+    elapsed: number;
+    constructor(message: string, jobId: string, elapsed: number);
+}
+/**
+ * Thrown when the request is malformed or contains invalid parameters (HTTP 400).
+ */
+declare class BadRequestError extends LogoError {
+    constructor(message: string);
+}
+
+export { type AttributionInfo, type AttributionStatus, AuthenticationError, BASE_URL, BadRequestError, type BrowserLogoResponse, DEFAULT_FORMAT, DEFAULT_WIDTH, DomainValidationError, FORMAT_ALIASES, ForbiddenError, type FormatShorthand, KEY_TYPES, type KeyPrefix, type KeyType, LogoError, type LogoErrorCode, type LogoMetadata, type LogoRequestOptions, MAX_WIDTH, MAX_WIDTH_SERVER, MONTHLY_LIMITS, NotFoundError, QuotaExceededError, RATE_LIMITS, RateLimitError, SERVER_RATE_LIMITS, SUPPORTED_FORMATS, type ScrapeJob, type ScrapeJobStatus, type ScrapePendingResponse, type ScrapeProgressEvent, ScrapeTimeoutError, type ServerLogoResponse, type SupportedOutputFormat, TIERS, type ThemeOption, type Tier, type TokenStatus, logoUrl, parseLogoHeaders, parseRetryAfter };