@quikturn/logos 0.2.0 → 0.2.1

package/README.md

@@ -5,7 +5,7 @@
 ## Features
 
 - **Zero-dependency URL builder** -- universal, works in any JavaScript runtime
-- **Browser client** -- blob URL management, retry/backoff, auto-scrape polling, event emission
+- **Browser client** -- blob URL management, retry/backoff, scrape polling, event emission
 - **Server client** -- Buffer output, ReadableStream streaming, concurrent batch operations
 - **Full TypeScript support** -- strict types, discriminated union error codes, generic response shapes
 - **Tree-shakeable** -- ESM and CJS dual builds; import only what you need
@@ -107,7 +107,7 @@ Readable.fromWeb(stream).pipe(createWriteStream("logo.png"));
 
 ### Universal (`@quikturn/logos`)
 
-The universal entry point exports the URL builder, types, constants, error classes, and header parser. No network calls are made from this module.
+The universal entry point exports the URL builder, types, constants, and error classes. No network calls are made from this module.
 
 #### `logoUrl(domain, options?)`
 
@@ -127,24 +127,17 @@ Constructs a fully-qualified Logos API URL. Pure function with no side effects.
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
 | `token` | `string` | -- | Publishable key (`qt_`/`pk_`) appended as a query parameter |
-| `size` | `number` | `128` | Output width in pixels, clamped to `1..800` (publishable) or `1..1200` (secret) |
+| `size` | `number` | `128` | Output width in pixels |
 | `width` | `number` | `128` | Alias for `size` |
 | `greyscale` | `boolean` | `false` | When `true`, applies saturation: 0 transformation |
-| `theme` | `"light" \| "dark"` | -- | Gamma curve adjustment (`"light"` = 0.9, `"dark"` = 1.12) |
+| `theme` | `"light" \| "dark"` | -- | Optimize logo for light or dark backgrounds |
 | `format` | `SupportedOutputFormat \| FormatShorthand` | `"image/png"` | Output image format |
-| `autoScrape` | `boolean` | `false` | Trigger background scrape if logo is not found |
 | `baseUrl` | `string` | `"https://logos.getquikturn.io"` | Override the API base URL |
 
 #### Types
 
 ```ts
 import type {
-  // Key & Auth
-  KeyType,           // "publishable" | "secret"
-  KeyPrefix,         // "qt_" | "pk_" | "sk_"
-  Tier,              // "free" | "launch" | "growth" | "enterprise"
-  TokenStatus,       // "active" | "suspended" | "revoked"
-
   // Request
   ThemeOption,           // "light" | "dark"
   SupportedOutputFormat, // "image/png" | "image/jpeg" | "image/webp" | "image/avif"
@@ -156,16 +149,9 @@ import type {
   BrowserLogoResponse,
   ServerLogoResponse,
 
-  // Auto-scrape
-  ScrapeJob,
-  ScrapePendingResponse,
-  ScrapeJobStatus,       // "pending" | "complete" | "failed"
+  // Scrape polling
   ScrapeProgressEvent,
 
-  // Attribution (free tier)
-  AttributionStatus,
-  AttributionInfo,
-
   // Error codes
   LogoErrorCode,
 } from "@quikturn/logos";
@@ -177,24 +163,9 @@ import type {
 |----------|-------|-------------|
 | `BASE_URL` | `"https://logos.getquikturn.io"` | Root API endpoint |
 | `DEFAULT_WIDTH` | `128` | Default logo width (px) |
-| `MAX_WIDTH` | `800` | Max width for publishable keys |
-| `MAX_WIDTH_SERVER` | `1200` | Max width for secret keys |
 | `DEFAULT_FORMAT` | `"image/png"` | Default output MIME type |
 | `SUPPORTED_FORMATS` | `Set<SupportedOutputFormat>` | All supported MIME types |
 | `FORMAT_ALIASES` | `Record<FormatShorthand, SupportedOutputFormat>` | Shorthand-to-MIME mapping |
-| `RATE_LIMITS` | `Record<Tier, { requests, windowSeconds }>` | Per-tier publishable rate limits |
-| `SERVER_RATE_LIMITS` | `Record<Tier, { requests, windowSeconds }>` | Per-tier server rate limits |
-| `MONTHLY_LIMITS` | `Record<Tier, number>` | Monthly request quotas |
-| `TIERS` | `readonly Tier[]` | All tiers as a runtime array |
-| `KEY_TYPES` | `readonly KeyType[]` | All key types as a runtime array |
-
-#### `parseLogoHeaders(headers)`
-
-Parses a `Headers` object from a fetch `Response` into a structured `LogoMetadata` object.
-
-#### `parseRetryAfter(headers)`
-
-Extracts the `Retry-After` header value in seconds. Returns `number | null`.
 
 ---
 
@@ -219,7 +190,6 @@ Fetches a logo and returns a `BrowserLogoResponse`.
 | `greyscale` | `boolean` | `false` | Greyscale transformation |
 | `theme` | `"light" \| "dark"` | -- | Gamma curve adjustment |
 | `format` | `SupportedOutputFormat \| FormatShorthand` | `"image/png"` | Output format |
-| `autoScrape` | `boolean` | `false` | Enable auto-scrape polling |
 | `scrapeTimeout` | `number` | -- | Max time (ms) to wait for scrape completion |
 | `onScrapeProgress` | `(event: ScrapeProgressEvent) => void` | -- | Callback for scrape progress |
 | `signal` | `AbortSignal` | -- | Cancel the request |
@@ -319,7 +289,7 @@ Accepts the same options as `get()`.
 
 #### `client.getUrl(domain, options?)`
 
-Returns a plain URL string with the secret key included as a token query parameter.
+Returns a plain URL string without making a network request. Does **not** include the secret key -- use the `Authorization: Bearer` header when fetching.
 
 **Returns:** `string`
 
@@ -438,60 +408,14 @@ client.get("github.com", { format: "webp" });
 
 ### Theme Options
 
-| Theme | Gamma | Use Case |
-|-------|-------|----------|
-| `"light"` | 0.9 | Light backgrounds |
-| `"dark"` | 1.12 | Dark backgrounds |
-
-## Auto-Scrape
-
-When a logo is not found in the database, the SDK can automatically trigger a background scrape and poll for completion.
-
-**Flow:** Request with `autoScrape: true` --> API returns `202 Accepted` with a scrape job --> SDK polls the job URL --> Logo becomes available --> SDK returns the final image.
-
-```ts
-const { url } = await client.get("brand-new-startup.com", {
-  autoScrape: true,
-  scrapeTimeout: 30_000, // wait up to 30 seconds
-  onScrapeProgress: (event) => {
-    console.log(`Scrape status: ${event.status}, progress: ${event.progress}%`);
-  },
-});
-```
-
-If the scrape does not complete within `scrapeTimeout`, a `ScrapeTimeoutError` is thrown.
+| Theme | Use Case |
+|-------|----------|
+| `"light"` | Optimized for light backgrounds |
+| `"dark"` | Optimized for dark backgrounds |
 
 ## Rate Limits & Quotas
 
-### Per-Minute Rate Limits (Publishable Keys)
-
-| Tier | Requests/min | Window |
-|------|-------------|--------|
-| Free | 100 | 60s |
-| Launch | 500 | 60s |
-| Growth | 5,000 | 60s |
-| Enterprise | 50,000 | 60s |
-
-### Per-Minute Rate Limits (Secret Keys)
-
-| Tier | Requests/min | Window |
-|------|-------------|--------|
-| Launch | 1,000 | 60s |
-| Growth | 10,000 | 60s |
-| Enterprise | 100,000 | 60s |
-
-> The free tier does not have server-side (secret key) access.
-
-### Monthly Quotas
-
-| Tier | Monthly Limit |
-|------|--------------|
-| Free | 500,000 |
-| Launch | 1,000,000 |
-| Growth | 5,000,000 |
-| Enterprise | 10,000,000 |
-
-Rate limits are enforced by the API server. The SDK reads `X-RateLimit-Remaining`, `X-Quota-Remaining`, and `Retry-After` headers to provide warnings via the event system and automatic retry with backoff.
+Rate limits and monthly quotas are enforced by the API server and vary by plan. The SDK automatically reads rate-limit headers to provide warnings via the event system and retries with backoff when limits are hit. See [Quikturn pricing](https://getquikturn.io/pricing) for details on your plan's limits.
 
 ## License
 

package/dist/client/index.cjs

@@ -183,7 +183,6 @@ function logoUrl(domain, options) {
     greyscale,
     theme,
     format,
-    autoScrape,
     baseUrl
   } = options ?? {};
   const maxWidth = token?.startsWith("sk_") ? MAX_WIDTH_SERVER : MAX_WIDTH;
@@ -210,9 +209,7 @@ function logoUrl(domain, options) {
   if (resolvedFormat !== void 0) {
     url.searchParams.set("format", resolvedFormat);
   }
-  if (autoScrape === true) {
-    url.searchParams.set("autoScrape", "true");
-  }
+  url.searchParams.set("autoScrape", "true");
   return url.toString();
 }
 
@@ -520,49 +517,6 @@ async function handleScrapeResponse(response, originalUrl, fetchFn, options) {
   }
 }
 
-// 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) {
@@ -606,7 +560,6 @@ var QuikturnLogos = class {
       greyscale: options?.greyscale,
       theme: options?.theme,
       format: options?.format,
-      autoScrape: options?.autoScrape,
       baseUrl: this.baseUrl
     });
     const format = options?.format;
@@ -618,14 +571,12 @@ var QuikturnLogos = class {
       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
-      });
-    }
+    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);
@@ -721,6 +672,3 @@ var QuikturnLogos = class {
 };
 
 exports.QuikturnLogos = QuikturnLogos;
-exports.browserFetch = browserFetch;
-exports.handleScrapeResponse = handleScrapeResponse;
-exports.parseAttributionStatus = parseAttributionStatus;

package/dist/client/index.d.cts

@@ -67,189 +67,6 @@ interface ScrapeProgressEvent {
     };
     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
@@ -291,7 +108,6 @@ interface BrowserClientOptions {
  * - `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.
@@ -302,7 +118,6 @@ interface GetOptions {
     greyscale?: boolean;
     theme?: ThemeOption;
     format?: SupportedOutputFormat | FormatShorthand;
-    autoScrape?: boolean;
     scrapeTimeout?: number;
     onScrapeProgress?: (event: ScrapeProgressEvent) => void;
     signal?: AbortSignal;
@@ -363,7 +178,7 @@ declare class QuikturnLogos {
      * // => "https://logos.getquikturn.io/github.com?token=qt_abc123&format=webp"
      * ```
      */
-    getUrl(domain: string, options?: Omit<GetOptions, "autoScrape" | "scrapeTimeout" | "onScrapeProgress" | "signal">): string;
+    getUrl(domain: string, options?: Omit<GetOptions, "scrapeTimeout" | "onScrapeProgress" | "signal">): string;
     /**
      * Registers an event listener for a client event.
      *
@@ -396,4 +211,4 @@ declare class QuikturnLogos {
     private emit;
 }
 
-export { type BrowserClientOptions, type ClientEvent, type EventHandler, type FetcherOptions, type GetOptions, QuikturnLogos, type ScrapePollerOptions, browserFetch, handleScrapeResponse, parseAttributionStatus };
+export { type BrowserClientOptions, type ClientEvent, type EventHandler, type GetOptions, QuikturnLogos };