@quikturn/logos 0.4.0 → 0.5.0

package/README.md

@@ -1,61 +1,57 @@
 # @quikturn/logos
 
-> TypeScript SDK for the Quikturn Logos API -- fetch company logos with type safety.
+TypeScript SDK for the [Quikturn Logos API](https://getquikturn.io) -- fetch any company's logo by domain name.
 
-## Packages
+**[Get your API key](https://getquikturn.io)** -- free tier available, no credit card required.
 
-| Package | Description | Install |
-|---------|-------------|---------|
+| Package | Description | |
+|---------|-------------|-|
 | [`@quikturn/logos`](https://www.npmjs.com/package/@quikturn/logos) | Core SDK -- URL builder, browser client, server client, web component | `pnpm add @quikturn/logos` |
-| [`@quikturn/logos-react`](https://www.npmjs.com/package/@quikturn/logos-react) | React components -- `<QuikturnLogo>`, `<QuikturnLogoCarousel>`, `<QuikturnLogoGrid>` | `pnpm add @quikturn/logos-react` |
+| [`@quikturn/logos-react`](https://www.npmjs.com/package/@quikturn/logos-react) | React components -- logo, carousel, grid | `pnpm add @quikturn/logos-react` |
 
-## Features
-
-- **Zero-dependency URL builder** -- universal, works in any JavaScript runtime
-- **Browser client** -- blob URL management, retry/backoff, scrape polling, event emission
-- **Server client** -- Buffer output, ReadableStream streaming, concurrent batch operations
-- **`<quikturn-logo>` web component** -- zero-effort attribution element with shadow DOM
-- **React components** -- see [`@quikturn/logos-react`](./packages/react/) for `<QuikturnLogo>`, `<QuikturnLogoCarousel>`, and `<QuikturnLogoGrid>`
-- **Full TypeScript support** -- strict types, discriminated union error codes, generic response shapes
-- **Tree-shakeable** -- ESM and CJS dual builds; import only what you need
+---
 
-## Installation
+## Install
 
 ```bash
-# pnpm (recommended)
 pnpm add @quikturn/logos
+```
 
-# npm
-npm install @quikturn/logos
+> Requires Node.js >= 18. Works with pnpm, npm, or yarn.
+>
+> Need an API key? **[Sign up at getquikturn.io](https://getquikturn.io)** -- takes 30 seconds.
 
-# yarn
-yarn add @quikturn/logos
-```
+## Pick Your Entry Point
+
+| Entry Point | Import | Use Case |
+|-------------|--------|----------|
+| **Universal** | `@quikturn/logos` | URL builder, types, constants -- zero dependencies, any runtime |
+| **Browser** | `@quikturn/logos/client` | Blob URLs, retry/backoff, scrape polling, events |
+| **Server** | `@quikturn/logos/server` | Buffer output, streaming, batch operations |
+| **Element** | `@quikturn/logos/element` | `<quikturn-logo>` web component with built-in attribution |
+| **React** | `@quikturn/logos-react` | `<QuikturnLogo>`, `<QuikturnLogoCarousel>`, `<QuikturnLogoGrid>` |
 
-**Requirements:** Node.js >= 18
+---
 
 ## Quick Start
 
-### URL Builder (Universal)
+### URL Builder
 
-The URL builder runs everywhere -- browsers, Node.js, edge runtimes -- with zero dependencies and no network calls.
+The simplest way to get a logo URL. Runs everywhere -- browsers, Node.js, edge runtimes -- with no network calls.
 
 ```ts
 import { logoUrl } from "@quikturn/logos";
 
-// Simple usage
 const url = logoUrl("github.com");
 // => "https://logos.getquikturn.io/github.com"
 
-// With options
-const customUrl = logoUrl("stripe.com", {
+const url = logoUrl("stripe.com", {
   token: "qt_abc123",
   size: 256,
   format: "webp",
   greyscale: true,
   theme: "dark",
 });
-// => "https://logos.getquikturn.io/stripe.com?token=qt_abc123&size=256&greyscale=1&theme=dark&format=webp"
 ```
 
 ### Browser Client
@@ -65,19 +61,13 @@ import { QuikturnLogos } from "@quikturn/logos/client";
 
 const client = new QuikturnLogos({ token: "qt_your_publishable_key" });
 
-// Fetch a logo as a blob URL (ready for <img src>)
-const { url, blob, contentType, metadata } = await client.get("github.com", {
+const { url, blob, contentType } = await client.get("github.com", {
   size: 256,
   format: "webp",
 });
 
 document.querySelector("img")!.src = url;
 
-// Listen for rate limit warnings
-client.on("rateLimitWarning", (remaining, limit) => {
-  console.warn(`Rate limit: ${remaining}/${limit} requests remaining`);
-});
-
 // Clean up blob URLs when done
 client.destroy();
 ```
@@ -89,22 +79,15 @@ import { QuikturnLogos } from "@quikturn/logos/server";
 
 const client = new QuikturnLogos({ secretKey: "sk_your_secret_key" });
 
-// Fetch a logo as a Buffer
-const { buffer, contentType, metadata } = await client.get("github.com", {
-  size: 512,
-  format: "png",
-});
+// Single logo
+const { buffer, contentType } = await client.get("github.com");
 
-// Batch fetch multiple logos
+// Batch fetch
 for await (const result of client.getMany(["github.com", "stripe.com", "vercel.com"])) {
-  if (result.success) {
-    console.log(`${result.domain}: ${result.buffer!.byteLength} bytes`);
-  } else {
-    console.error(`${result.domain}: ${result.error!.message}`);
-  }
+  if (result.success) console.log(`${result.domain}: ${result.buffer!.byteLength} bytes`);
 }
 
-// Stream a logo to a file
+// Stream to file
 import { createWriteStream } from "node:fs";
 import { Readable } from "node:stream";
 
@@ -114,36 +97,19 @@ Readable.fromWeb(stream).pipe(createWriteStream("logo.png"));
 
 ### Web Component
 
-The `<quikturn-logo>` custom element renders a logo with built-in attribution. It uses shadow DOM to protect the attribution badge and requires no framework.
+No framework needed. Import the element entry and use it in plain HTML:
 
 ```html
 <script type="module">
   import "@quikturn/logos/element";
 </script>
 
-<quikturn-logo
-  domain="github.com"
-  token="qt_abc123"
-  size="64"
-  format="webp"
-  theme="dark"
-></quikturn-logo>
+<quikturn-logo domain="github.com" token="qt_abc123" size="64"></quikturn-logo>
 ```
 
-| Attribute | Type | Description |
-|-----------|------|-------------|
-| `domain` | `string` | Domain to fetch logo for (required for rendering) |
-| `token` | `string` | Publishable API key |
-| `size` | `string` | Image width in pixels |
-| `format` | `string` | `"png"`, `"jpeg"`, `"webp"`, or `"avif"` |
-| `greyscale` | presence | When present, applies greyscale transformation |
-| `theme` | `string` | `"light"` or `"dark"` |
-
-The element automatically registers as `quikturn-logo` on import and fires an attribution beacon on first render. Attribution styling uses `!important` rules inside the shadow DOM to prevent accidental removal.
+Renders the logo with a "Powered by Quikturn" attribution badge protected by shadow DOM.
 
-### React Components
-
-For React applications, install the companion package:
+### React
 
 ```bash
 pnpm add @quikturn/logos-react
@@ -152,296 +118,228 @@ pnpm add @quikturn/logos-react
 ```tsx
 import { QuikturnProvider, QuikturnLogo, QuikturnLogoCarousel } from "@quikturn/logos-react";
 
-<QuikturnProvider token="qt_your_key">
-  <QuikturnLogo domain="github.com" size={64} />
-  <QuikturnLogoCarousel
-    domains={["github.com", "stripe.com", "vercel.com"]}
-    speed={120}
-    fadeOut
-    pauseOnHover
-  />
-</QuikturnProvider>
+function App() {
+  return (
+    <QuikturnProvider token="qt_your_key">
+      <QuikturnLogo domain="github.com" size={64} />
+
+      <QuikturnLogoCarousel
+        domains={["github.com", "stripe.com", "vercel.com", "figma.com"]}
+        speed={120}
+        fadeOut
+        pauseOnHover
+      />
+    </QuikturnProvider>
+  );
+}
 ```
 
-See the full API reference in [`@quikturn/logos-react` README](./packages/react/README.md).
+Full React API reference: [`@quikturn/logos-react` docs](./packages/react/README.md)
 
-## API Reference
-
-### Universal (`@quikturn/logos`)
-
-The universal entry point exports the URL builder, types, constants, and error classes. No network calls are made from this module.
-
-#### `logoUrl(domain, options?)`
-
-Constructs a fully-qualified Logos API URL. Pure function with no side effects.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `domain` | `string` | Domain to fetch a logo for (e.g. `"github.com"`) |
-| `options` | `LogoRequestOptions` | Optional request parameters |
-
-**Returns:** `string` -- fully-qualified URL
-
-**Throws:** `DomainValidationError` if the domain fails RFC 1035/1123 validation
+---
 
-##### `LogoRequestOptions`
+## Authentication
 
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `token` | `string` | -- | Publishable key (`qt_`/`pk_`) appended as a query parameter |
-| `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"` | -- | Optimize logo for light or dark backgrounds |
-| `format` | `SupportedOutputFormat \| FormatShorthand` | `"image/png"` | Output image format |
-| `baseUrl` | `string` | `"https://logos.getquikturn.io"` | Override the API base URL |
+| Key Type | Prefix | Environment | Auth Method |
+|----------|--------|-------------|-------------|
+| **Publishable** | `qt_` / `pk_` | Browser | Query parameter (`?token=...`) |
+| **Secret** | `sk_` | Server only | `Authorization: Bearer` header |
 
-#### Types
+Publishable keys are safe to expose in client-side code (max 800px). Secret keys must never reach the browser (max 1200px). Manage your keys in the [Quikturn dashboard](https://getquikturn.io/dashboard).
 
 ```ts
-import type {
-  // Request
-  ThemeOption,           // "light" | "dark"
-  SupportedOutputFormat, // "image/png" | "image/jpeg" | "image/webp" | "image/avif"
-  FormatShorthand,       // "png" | "jpeg" | "webp" | "avif"
-  LogoRequestOptions,
-
-  // Response
-  LogoMetadata,
-  BrowserLogoResponse,
-  ServerLogoResponse,
-
-  // Scrape polling
-  ScrapeProgressEvent,
+// Browser
+import { QuikturnLogos } from "@quikturn/logos/client";
+const client = new QuikturnLogos({ token: "qt_your_publishable_key" });
 
-  // Error codes
-  LogoErrorCode,
-} from "@quikturn/logos";
+// Server
+import { QuikturnLogos } from "@quikturn/logos/server";
+const client = new QuikturnLogos({ secretKey: "sk_your_secret_key" });
 ```
 
-#### Constants
-
-| Constant | Value | Description |
-|----------|-------|-------------|
-| `BASE_URL` | `"https://logos.getquikturn.io"` | Root API endpoint |
-| `DEFAULT_WIDTH` | `128` | Default logo width (px) |
-| `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 |
-
 ---
 
-### Browser Client (`@quikturn/logos/client`)
-
-#### `new QuikturnLogos(options)`
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `token` | `string` | **required** | Publishable key (`qt_`/`pk_` prefix). Server keys (`sk_`) are rejected. |
-| `baseUrl` | `string` | `"https://logos.getquikturn.io"` | Override the API base URL |
-| `maxRetries` | `number` | `2` | Max retry attempts for rate-limited/server-error responses |
-
-#### `client.get(domain, options?)`
-
-Fetches a logo and returns a `BrowserLogoResponse`.
+## API Reference
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `size` | `number` | `128` | Output width in pixels |
-| `width` | `number` | `128` | Alias for `size` |
-| `greyscale` | `boolean` | `false` | Greyscale transformation |
-| `theme` | `"light" \| "dark"` | -- | Gamma curve adjustment |
-| `format` | `SupportedOutputFormat \| FormatShorthand` | `"image/png"` | Output format |
-| `scrapeTimeout` | `number` | -- | Max time (ms) to wait for scrape completion |
-| `onScrapeProgress` | `(event: ScrapeProgressEvent) => void` | -- | Callback for scrape progress |
-| `signal` | `AbortSignal` | -- | Cancel the request |
+### `logoUrl(domain, options?)`
 
-**Returns:** `Promise<BrowserLogoResponse>`
+Pure URL builder. No network calls, no side effects.
 
 ```ts
-interface BrowserLogoResponse {
-  url: string;          // blob: object URL for <img src>
-  blob: Blob;           // Raw image Blob
-  contentType: string;  // e.g. "image/webp"
-  metadata: LogoMetadata;
-}
+import { logoUrl } from "@quikturn/logos";
 ```
 
-#### `client.getUrl(domain, options?)`
-
-Returns a plain URL string without making a network request. Useful for `<img>` tags, CSS `background-image`, or preloading hints.
-
-**Returns:** `string`
-
-#### `client.on(event, handler)` / `client.off(event, handler)`
-
-Register or remove event listeners.
-
-| Event | Handler Signature | Description |
-|-------|-------------------|-------------|
-| `"rateLimitWarning"` | `(remaining: number, limit: number) => void` | Fires when rate limit is approaching |
-| `"quotaWarning"` | `(remaining: number, limit: number) => void` | Fires when monthly quota is approaching |
+**Options:**
 
-#### `client.destroy()`
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `token` | `string` | -- | API key appended as query parameter |
+| `size` | `number` | `128` | Output width in pixels |
+| `width` | `number` | `128` | Alias for `size` |
+| `greyscale` | `boolean` | `false` | Desaturation filter |
+| `theme` | `"light" \| "dark"` | -- | Background-optimized rendering |
+| `format` | `string` | `"image/png"` | `"png"`, `"jpeg"`, `"webp"`, `"avif"` (or full MIME type) |
+| `baseUrl` | `string` | `"https://logos.getquikturn.io"` | API base URL override |
 
-Revokes all tracked `blob:` object URLs to free memory and removes all event listeners. Call this when the client is no longer needed to prevent memory leaks in long-lived browser sessions.
+**Returns:** `string` | **Throws:** `DomainValidationError`
 
 ---
 
-### Server Client (`@quikturn/logos/server`)
+### Browser Client
+
+```ts
+import { QuikturnLogos } from "@quikturn/logos/client";
+```
 
-#### `new QuikturnLogos(options)`
+#### Constructor
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `secretKey` | `string` | **required** | Secret key (`sk_` prefix). Publishable keys (`qt_`/`pk_`) are rejected. |
-| `baseUrl` | `string` | `"https://logos.getquikturn.io"` | Override the API base URL |
-| `maxRetries` | `number` | `2` | Max retry attempts for rate-limited/server-error responses |
+| `token` | `string` | **required** | Publishable key (`qt_`/`pk_` prefix) |
+| `baseUrl` | `string` | `"https://logos.getquikturn.io"` | API base URL override |
+| `maxRetries` | `number` | `2` | Max retries for 429/5xx responses |
 
-#### `client.get(domain, options?)`
+#### Methods
 
-Fetches a logo and returns a `ServerLogoResponse`.
+**`client.get(domain, options?)`** -- Fetches a logo and returns a blob URL.
 
-Accepts the same options as the browser client's `get()` method.
+| Option | Type | Default |
+|--------|------|---------|
+| `size` | `number` | `128` |
+| `format` | `string` | `"image/png"` |
+| `greyscale` | `boolean` | `false` |
+| `theme` | `"light" \| "dark"` | -- |
+| `scrapeTimeout` | `number` | -- |
+| `onScrapeProgress` | `(event) => void` | -- |
+| `signal` | `AbortSignal` | -- |
 
-**Returns:** `Promise<ServerLogoResponse>`
+Returns `Promise<{ url: string, blob: Blob, contentType: string, metadata: LogoMetadata }>`.
 
-```ts
-interface ServerLogoResponse {
-  buffer: Buffer;       // Raw image bytes
-  contentType: string;  // e.g. "image/png"
-  metadata: LogoMetadata;
-}
-```
+**`client.getUrl(domain, options?)`** -- Returns a plain URL string without a network request.
 
-#### `client.getMany(domains, options?)`
+**`client.on(event, handler)`** / **`client.off(event, handler)`** -- Listen for `"rateLimitWarning"` or `"quotaWarning"` events.
 
-Fetches logos for multiple domains with concurrency control. Yields results in the same order as the input array.
+**`client.destroy()`** -- Revokes all tracked blob URLs and removes event listeners. Call this to prevent memory leaks.
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `concurrency` | `number` | `5` | Maximum parallel fetches |
-| `size` | `number` | `128` | Output width in pixels |
-| `greyscale` | `boolean` | `false` | Greyscale transformation |
-| `theme` | `"light" \| "dark"` | -- | Gamma curve adjustment |
-| `format` | `SupportedOutputFormat \| FormatShorthand` | `"image/png"` | Output format |
-| `signal` | `AbortSignal` | -- | Cancel remaining batch items |
-| `continueOnError` | `boolean` | `true` | Capture errors per-domain instead of aborting the batch |
+---
 
-**Returns:** `AsyncGenerator<BatchResult>`
+### Server Client
 
 ```ts
-interface BatchResult {
-  domain: string;
-  success: boolean;
-  buffer?: Buffer;
-  contentType?: string;
-  metadata?: LogoMetadata;
-  error?: LogoError;
-}
+import { QuikturnLogos } from "@quikturn/logos/server";
 ```
 
-#### `client.getStream(domain, options?)`
+#### Constructor
 
-Returns the raw response body as a `ReadableStream`. Useful for piping to a file or HTTP response without buffering the entire image in memory.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `secretKey` | `string` | **required** | Secret key (`sk_` prefix) |
+| `baseUrl` | `string` | `"https://logos.getquikturn.io"` | API base URL override |
+| `maxRetries` | `number` | `2` | Max retries for 429/5xx responses |
 
-Accepts the same options as `get()`.
+#### Methods
 
-**Returns:** `Promise<ReadableStream>`
+**`client.get(domain, options?)`** -- Returns `Promise<{ buffer: Buffer, contentType: string, metadata: LogoMetadata }>`.
 
-#### `client.getUrl(domain, options?)`
+**`client.getMany(domains, options?)`** -- Batch fetch with concurrency control. Returns `AsyncGenerator<BatchResult>`.
 
-Returns a plain URL string without making a network request. Does **not** include the secret key -- use the `Authorization: Bearer` header when fetching.
+| Option | Type | Default |
+|--------|------|---------|
+| `concurrency` | `number` | `5` |
+| `continueOnError` | `boolean` | `true` |
+| `signal` | `AbortSignal` | -- |
 
-**Returns:** `string`
+**`client.getStream(domain, options?)`** -- Returns `Promise<ReadableStream>` for zero-copy streaming.
 
-#### `client.on(event, handler)` / `client.off(event, handler)`
+**`client.getUrl(domain, options?)`** -- Returns a URL string (secret key NOT included -- use `Authorization` header).
 
-Same event interface as the browser client. Supports `"rateLimitWarning"` and `"quotaWarning"` events.
+**`client.on(event, handler)`** / **`client.off(event, handler)`** -- Same events as the browser client.
 
 ---
 
-### Error Classes
-
-All SDK errors extend `LogoError`, which extends the native `Error` class with a machine-readable `code` and an optional HTTP `status`.
+### Web Component
 
 ```ts
-import {
-  LogoError,
-  DomainValidationError,
-  RateLimitError,
-  QuotaExceededError,
-  AuthenticationError,
-  ForbiddenError,
-  NotFoundError,
-  ScrapeTimeoutError,
-  BadRequestError,
-} from "@quikturn/logos";
+import "@quikturn/logos/element";
 ```
 
-| Error Class | Code | HTTP Status | Extra Properties |
-|-------------|------|-------------|------------------|
-| `LogoError` | varies | varies | `code: LogoErrorCode`, `status?: number` |
-| `DomainValidationError` | `DOMAIN_VALIDATION_ERROR` | -- | `domain: string` |
-| `AuthenticationError` | `AUTHENTICATION_ERROR` | 401 | -- |
-| `ForbiddenError` | `FORBIDDEN_ERROR` | 403 | `reason: string` |
-| `NotFoundError` | `NOT_FOUND_ERROR` | 404 | `domain: string` |
-| `BadRequestError` | `BAD_REQUEST_ERROR` | 400 | -- |
-| `RateLimitError` | `RATE_LIMIT_ERROR` | 429 | `retryAfter: number`, `remaining: number`, `resetAt: Date` |
-| `QuotaExceededError` | `QUOTA_EXCEEDED_ERROR` | 429 | `retryAfter: number`, `limit: number`, `used: number` |
-| `ScrapeTimeoutError` | `SCRAPE_TIMEOUT_ERROR` | -- | `jobId: string`, `elapsed: number` |
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `domain` | `string` | Domain to fetch logo for (required) |
+| `token` | `string` | Publishable API key |
+| `size` | `string` | Image width in pixels |
+| `format` | `string` | `"png"`, `"jpeg"`, `"webp"`, or `"avif"` |
+| `greyscale` | (presence) | Greyscale filter when attribute is present |
+| `theme` | `string` | `"light"` or `"dark"` |
+
+Auto-registers as `<quikturn-logo>` on import. Shadow DOM protects the attribution badge with `!important` CSS rules.
+
+---
+
+### Error Handling
 
-All error codes are typed via the `LogoErrorCode` discriminated union for exhaustive switch handling:
+All errors extend `LogoError` with a typed `code` property for exhaustive `switch` handling:
 
 ```ts
 import { LogoError } from "@quikturn/logos";
-import type { LogoErrorCode } from "@quikturn/logos";
 
 try {
   const { url } = await client.get("example.com");
 } catch (err) {
   if (err instanceof LogoError) {
     switch (err.code) {
-      case "RATE_LIMIT_ERROR":
-        // err is narrowed, handle backoff
-        break;
-      case "NOT_FOUND_ERROR":
-        // show placeholder
-        break;
-      // ... handle other cases
+      case "RATE_LIMIT_ERROR":   /* backoff */  break;
+      case "NOT_FOUND_ERROR":    /* fallback */  break;
+      case "AUTHENTICATION_ERROR": /* check key */ break;
+      // ...
     }
   }
 }
 ```
 
-## Authentication
-
-The Quikturn Logos API uses token-based authentication with two key types:
+| Error | Code | Status | Extra Properties |
+|-------|------|--------|------------------|
+| `DomainValidationError` | `DOMAIN_VALIDATION_ERROR` | -- | `domain` |
+| `AuthenticationError` | `AUTHENTICATION_ERROR` | 401 | -- |
+| `ForbiddenError` | `FORBIDDEN_ERROR` | 403 | `reason` |
+| `NotFoundError` | `NOT_FOUND_ERROR` | 404 | `domain` |
+| `BadRequestError` | `BAD_REQUEST_ERROR` | 400 | -- |
+| `RateLimitError` | `RATE_LIMIT_ERROR` | 429 | `retryAfter`, `remaining`, `resetAt` |
+| `QuotaExceededError` | `QUOTA_EXCEEDED_ERROR` | 429 | `retryAfter`, `limit`, `used` |
+| `ScrapeTimeoutError` | `SCRAPE_TIMEOUT_ERROR` | -- | `jobId`, `elapsed` |
 
-| Key Type | Prefix | Environment | Auth Method |
-|----------|--------|-------------|-------------|
-| **Publishable** | `qt_` or `pk_` | Browser | Query parameter (`?token=...`) |
-| **Secret** | `sk_` | Server only | `Authorization: Bearer` header |
+---
 
-- **Publishable keys** are safe to expose in client-side code. They are passed as query parameters and support a max image width of 800px.
-- **Secret keys** must never be exposed to the browser. They are sent via the `Authorization` header and support a max image width of 1200px.
+### Types & Constants
 
 ```ts
-// Browser -- publishable key
-import { QuikturnLogos } from "@quikturn/logos/client";
-const client = new QuikturnLogos({ token: "qt_your_publishable_key" });
-
-// Server -- secret key
-import { QuikturnLogos } from "@quikturn/logos/server";
-const client = new QuikturnLogos({ secretKey: "sk_your_secret_key" });
+import type {
+  ThemeOption,           // "light" | "dark"
+  SupportedOutputFormat, // "image/png" | "image/jpeg" | "image/webp" | "image/avif"
+  FormatShorthand,       // "png" | "jpeg" | "webp" | "avif"
+  LogoRequestOptions,
+  LogoMetadata,
+  BrowserLogoResponse,
+  ServerLogoResponse,
+  ScrapeProgressEvent,
+  LogoErrorCode,         // discriminated union of all error codes
+} from "@quikturn/logos";
 ```
 
+| Constant | Value |
+|----------|-------|
+| `BASE_URL` | `"https://logos.getquikturn.io"` |
+| `DEFAULT_WIDTH` | `128` |
+| `DEFAULT_FORMAT` | `"image/png"` |
+| `SUPPORTED_FORMATS` | `Set` of 4 MIME types |
+| `FORMAT_ALIASES` | `{ png, jpeg, webp, avif }` -> MIME mapping |
+
+---
+
 ## Configuration
 
 ### Custom Base URL
 
-Override the API endpoint for testing, proxied environments, or self-hosted deployments:
-
 ```ts
 const client = new QuikturnLogos({
   token: "qt_your_key",
@@ -449,48 +347,33 @@ const client = new QuikturnLogos({
 });
 ```
 
-### Format Options
+### Formats
 
-Four output formats are supported:
-
-| Format | MIME Type | Shorthand |
+| Format | Shorthand | MIME Type |
 |--------|-----------|-----------|
-| PNG | `image/png` | `"png"` |
-| JPEG | `image/jpeg` | `"jpeg"` |
-| WebP | `image/webp` | `"webp"` |
-| AVIF | `image/avif` | `"avif"` |
+| PNG | `"png"` | `image/png` |
+| JPEG | `"jpeg"` | `image/jpeg` |
+| WebP | `"webp"` | `image/webp` |
+| AVIF | `"avif"` | `image/avif` |
 
-Both the full MIME type and the shorthand alias are accepted:
+Both forms are accepted: `format: "webp"` and `format: "image/webp"` are equivalent.
 
-```ts
-// These are equivalent
-client.get("github.com", { format: "image/webp" });
-client.get("github.com", { format: "webp" });
-```
+### Themes
 
-### Theme Options
-
-| Theme | Use Case |
-|-------|----------|
-| `"light"` | Optimized for light backgrounds |
-| `"dark"` | Optimized for dark backgrounds |
+Use `"light"` for light backgrounds and `"dark"` for dark backgrounds. The API adjusts the logo's color profile to maximize contrast.
 
 ## Rate Limits & Quotas
 
-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.
-
-## Related Packages
+Rate limits and monthly quotas are enforced server-side and vary by plan. The SDK automatically retries with exponential backoff when limits are hit and emits `"rateLimitWarning"` / `"quotaWarning"` events so you can react in your UI. See [pricing & plan details](https://getquikturn.io/pricing).
 
-### [`@quikturn/logos-react`](https://www.npmjs.com/package/@quikturn/logos-react)
-
-Ready-made React components for displaying Quikturn logos. Includes an infinite scrolling carousel, responsive grid, single logo image, context provider for token propagation, and a `useLogoUrl()` hook. Zero CSS dependencies -- inline styles only.
-
-```bash
-pnpm add @quikturn/logos-react @quikturn/logos
-```
+## Resources
 
-See the full documentation at [`packages/react/README.md`](./packages/react/README.md).
+- **[Quikturn website](https://getquikturn.io)** -- sign up, manage keys, explore the API
+- **[Dashboard](https://getquikturn.io/dashboard)** -- usage analytics, key management, plan upgrades
+- **[Pricing](https://getquikturn.io/pricing)** -- free tier, pro, and enterprise plans
+- **[React components](./packages/react/README.md)** -- `@quikturn/logos-react` docs
+- **[GitHub](https://github.com/Quikturn-PowerPoint-Add-In/Logo-SDK)** -- source, issues, contributions
 
 ## License
 
-MIT
+MIT -- built by [Quikturn](https://getquikturn.io)

package/dist/client/index.cjs

@@ -366,8 +366,8 @@ async function browserFetch(url, options) {
       throw new AuthenticationError("Authentication failed");
     }
     if (response.status === 403) {
-      const body2 = await response.text();
-      const reason = body2.slice(0, 256) || "unknown";
+      const body = await response.text();
+      const reason = body.slice(0, 256) || "unknown";
       throw new ForbiddenError("Access forbidden", reason);
     }
     if (response.status === 404) {
@@ -407,8 +407,8 @@ async function browserFetch(url, options) {
       );
     }
     if (response.status === 400) {
-      const body2 = await response.text();
-      throw new BadRequestError(body2.slice(0, 256) || "Bad request");
+      const body = await response.text();
+      throw new BadRequestError(body.slice(0, 256) || "Bad request");
     }
     if (response.status === 500) {
       if (!serverErrorRetried) {
@@ -416,9 +416,9 @@ async function browserFetch(url, options) {
         await delay(SERVER_ERROR_RETRY_DELAY_MS);
         continue;
       }
-      const body2 = await response.text();
+      const body = await response.text();
       throw new LogoError(
-        body2.slice(0, 256) || "Internal server error",
+        body.slice(0, 256) || "Internal server error",
         "SERVER_ERROR",
         500
       );

package/dist/client/index.mjs

@@ -364,8 +364,8 @@ async function browserFetch(url, options) {
       throw new AuthenticationError("Authentication failed");
     }
     if (response.status === 403) {
-      const body2 = await response.text();
-      const reason = body2.slice(0, 256) || "unknown";
+      const body = await response.text();
+      const reason = body.slice(0, 256) || "unknown";
       throw new ForbiddenError("Access forbidden", reason);
     }
     if (response.status === 404) {
@@ -405,8 +405,8 @@ async function browserFetch(url, options) {
       );
     }
     if (response.status === 400) {
-      const body2 = await response.text();
-      throw new BadRequestError(body2.slice(0, 256) || "Bad request");
+      const body = await response.text();
+      throw new BadRequestError(body.slice(0, 256) || "Bad request");
     }
     if (response.status === 500) {
       if (!serverErrorRetried) {
@@ -414,9 +414,9 @@ async function browserFetch(url, options) {
         await delay(SERVER_ERROR_RETRY_DELAY_MS);
         continue;
       }
-      const body2 = await response.text();
+      const body = await response.text();
       throw new LogoError(
-        body2.slice(0, 256) || "Internal server error",
+        body.slice(0, 256) || "Internal server error",
         "SERVER_ERROR",
         500
       );

package/dist/server/index.cjs

@@ -369,8 +369,8 @@ async function serverFetch(url, options) {
       throw new AuthenticationError("Authentication failed");
     }
     if (response.status === 403) {
-      const body2 = await response.text();
-      const reason = body2.slice(0, 256) || "unknown";
+      const body = await response.text();
+      const reason = body.slice(0, 256) || "unknown";
       throw new ForbiddenError("Access forbidden", reason);
     }
     if (response.status === 404) {
@@ -410,8 +410,8 @@ async function serverFetch(url, options) {
       );
     }
     if (response.status === 400) {
-      const body2 = await response.text();
-      throw new BadRequestError(body2.slice(0, 256) || "Bad request");
+      const body = await response.text();
+      throw new BadRequestError(body.slice(0, 256) || "Bad request");
     }
     if (response.status === 500) {
       if (!serverErrorRetried) {
@@ -419,9 +419,9 @@ async function serverFetch(url, options) {
         await delay(SERVER_ERROR_RETRY_DELAY_MS);
         continue;
       }
-      const body2 = await response.text();
+      const body = await response.text();
       throw new LogoError(
-        body2.slice(0, 256) || "Internal server error",
+        body.slice(0, 256) || "Internal server error",
         "SERVER_ERROR",
         500
       );

package/dist/server/index.mjs

@@ -367,8 +367,8 @@ async function serverFetch(url, options) {
       throw new AuthenticationError("Authentication failed");
     }
     if (response.status === 403) {
-      const body2 = await response.text();
-      const reason = body2.slice(0, 256) || "unknown";
+      const body = await response.text();
+      const reason = body.slice(0, 256) || "unknown";
       throw new ForbiddenError("Access forbidden", reason);
     }
     if (response.status === 404) {
@@ -408,8 +408,8 @@ async function serverFetch(url, options) {
       );
     }
     if (response.status === 400) {
-      const body2 = await response.text();
-      throw new BadRequestError(body2.slice(0, 256) || "Bad request");
+      const body = await response.text();
+      throw new BadRequestError(body.slice(0, 256) || "Bad request");
     }
     if (response.status === 500) {
       if (!serverErrorRetried) {
@@ -417,9 +417,9 @@ async function serverFetch(url, options) {
         await delay(SERVER_ERROR_RETRY_DELAY_MS);
         continue;
       }
-      const body2 = await response.text();
+      const body = await response.text();
       throw new LogoError(
-        body2.slice(0, 256) || "Internal server error",
+        body.slice(0, 256) || "Internal server error",
         "SERVER_ERROR",
         500
       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quikturn/logos",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Quikturn Logo SDK — URL builder, browser client, and server client for the Quikturn Logos API",
   "license": "MIT",
   "author": "Quikturn",
@@ -30,7 +30,6 @@
   },
   "files": [
     "dist",
-    "package.json",
     "LICENSE",
     "README.md"
   ],
@@ -81,20 +80,29 @@
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "typecheck": "tsc --noEmit",
-    "lint": "tsc --noEmit",
-    "check": "pnpm lint && pnpm typecheck",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "check": "pnpm typecheck && pnpm lint",
     "prepublishOnly": "pnpm run build"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.2",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@types/jsdom": "^27.0.0",
     "@types/node": "^25.2.2",
     "@vitest/coverage-v8": "^4.0.18",
+    "angular-eslint": "^21.2.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-svelte": "^3.15.0",
+    "eslint-plugin-vue": "^10.7.0",
+    "globals": "^17.3.0",
     "jsdom": "^28.0.0",
     "semantic-release": "^25.0.3",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0",
     "vitest": "^4.0.18"
   }
 }