StripFeed TypeScript SDK

https://github.com/stripfeed/stripfeed-js
Admin
StripFeed is a TypeScript SDK that converts any URL to clean, token-efficient Markdown for AI...
Tokens:8,489
Snippets:52
Trust Score:7.5
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### StripFeed SDK Installation

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Install the StripFeed SDK using npm.

```APIDOC
## Install

```bash
npm install stripfeed
```
```

--------------------------------

### Install StripFeed SDK

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Installs the StripFeed SDK using npm. This is the first step to using the SDK in your project.

```bash
npm install stripfeed
```

--------------------------------

### StripFeed SDK Quick Start

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Initialize the StripFeed client and fetch a URL as Markdown.

```APIDOC
## Quick Start

```typescript
import StripFeed from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

// Fetch a URL as Markdown
const result = await sf.fetch("https://docs.anthropic.com");
console.log(result.markdown);
console.log(`Tokens: ${result.tokens} (saved ${result.savingsPercent}%)`);
```
```

--------------------------------

### Quick Start: Fetch URL as Markdown with StripFeed SDK

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Demonstrates how to initialize the StripFeed client with an API key and fetch a URL, logging the resulting Markdown and token information. Requires the 'stripfeed' package.

```typescript
import StripFeed from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

// Fetch a URL as Markdown
const result = await sf.fetch("https://docs.anthropic.com");
console.log(result.markdown);
console.log(`Tokens: ${result.tokens} (saved ${result.savingsPercent}%)`);
```

--------------------------------

### StripFeed SDK Usage: Get just the Markdown

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

A shorthand method to fetch only the Markdown content from a URL.

```APIDOC
### Get just the Markdown

```typescript
const markdown = await sf.fetchMarkdown("https://example.com");
```
```

--------------------------------

### Configure StripFeed Client

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Shows how to create a new StripFeed client instance with configuration options, including API key, custom base URL, and request timeout. Requires the 'stripfeed' package.

```typescript
const sf = new StripFeed({
  apiKey: "sf_live_your_api_key",
  baseUrl: "https://custom.api/v1",  // optional
  timeout: 10_000,                    // optional, default 30s
});
```

--------------------------------

### Build and Test Commands for StripFeed SDK

Source: https://github.com/stripfeed/stripfeed-js/blob/main/CLAUDE.md

Provides common npm commands for building, testing, and running the StripFeed TypeScript SDK. These commands are essential for development and maintenance.

```bash
npm run build    # Compile TypeScript to dist/
npm run dev      # Watch mode
npm test         # Run tests
npm run test:watch  # Watch mode tests
```

--------------------------------

### Initialize StripFeed Client (TypeScript)

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

Demonstrates how to initialize the StripFeed client using either a simple API key string or a configuration object for advanced settings like custom base URLs and timeouts. Requires Node.js 18+.

```typescript
import StripFeed from "stripfeed";

// Simple initialization with API key
const sf = new StripFeed("sf_live_your_api_key");

// Advanced initialization with config object
const sfAdvanced = new StripFeed({
  apiKey: "sf_live_your_api_key",
  baseUrl: "https://custom.api/v1",  // Optional custom endpoint
  timeout: 10_000,                    // Optional timeout in ms (default: 30000)
});

// The client is now ready to use
console.log("StripFeed client initialized");
```

--------------------------------

### StripFeed API Reference: Constructor

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Create a new StripFeed client instance. Accepts either a string API key or a configuration object.

```APIDOC
## API Reference

### `new StripFeed(apiKey)` or `new StripFeed(config)`

Create a new client. Pass a string API key or a config object.
```

--------------------------------

### Fetch Single URL with Options

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Shows how to fetch a single URL with various options like CSS selector, output format, model for cost tracking, cache control, custom TTL, and token limits. Requires the 'stripfeed' package.

```typescript
const result = await sf.fetch("https://example.com", {
  selector: "article",           // CSS selector (Pro)
  format: "json",                // json, text, html (Pro)
  model: "claude-sonnet-4-6",    // cost tracking
  cache: false,                  // bypass cache
  ttl: 7200,                     // custom cache TTL in seconds
  maxTokens: 5000,               // truncate to token budget
});
```

--------------------------------

### Batch Fetch URLs

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Demonstrates how to fetch multiple URLs in parallel using the batch method. This feature requires a Pro plan and allows specifying options for each URL. Requires the 'stripfeed' package.

```typescript
const result = await sf.batch(
  [
    "https://example.com",
    { url: "https://docs.anthropic.com", selector: "article" },
  ],
  { model: "claude-sonnet-4-6" },
);

for (const item of result.results) {
  console.log(`${item.url}: ${item.tokens} tokens`);
}
```

--------------------------------

### Fetch URL as Markdown with Metadata (TypeScript)

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

Shows how to fetch content from a URL, convert it to Markdown, and retrieve detailed metadata. Supports advanced options like CSS selectors, output formats, caching control, and token limits. Returns a structured object.

```typescript
import StripFeed from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

// Basic fetch
const result = await sf.fetch("https://docs.anthropic.com");

console.log(result.markdown);           // Clean Markdown content
console.log(result.title);              // Page title
console.log(result.tokens);             // Token count of clean output
console.log(result.originalTokens);     // Token count of original HTML
console.log(result.savingsPercent);     // Percentage of tokens saved (e.g., 91.2)
console.log(result.cached);             // Whether result was from cache
console.log(result.fetchMs);            // Processing time in ms

// Advanced fetch with options
const advancedResult = await sf.fetch("https://example.com/docs", {
  selector: "article",           // CSS selector to extract specific elements (Pro)
  format: "json",                // Output format: markdown, json, text, html (Pro)
  model: "claude-sonnet-4-6",    // AI model ID for cost tracking
  cache: false,                  // Bypass cache and force fresh fetch
  ttl: 7200,                     // Custom cache TTL in seconds (max: 86400)
  maxTokens: 5000,               // Truncate output to fit token budget
});

// Expected output:
// {
//   markdown: "# Documentation\n\nContent here...",
//   title: "Documentation",
//   tokens: 1250,
//   originalTokens: 14200,
//   savingsPercent: 91.2,
//   cached: false,
//   fetchMs: 847,
//   format: "json",
//   model: "claude-sonnet-4-6",
//   url: "https://example.com/docs",
//   truncated: false
// }
```

--------------------------------

### StripFeed API Reference: batch

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Fetch up to 10 URLs in parallel. Requires a Pro plan subscription.

```APIDOC
### `sf.batch(urls, options?): Promise<BatchResult>`

Fetch up to 10 URLs in parallel. Pro plan required.
```

--------------------------------

### StripFeed API Reference: usage

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Check your current monthly API usage against your plan limits.

```APIDOC
### `sf.usage(): Promise<UsageResult>`

Check current monthly API usage and plan limits.
```

--------------------------------

### StripFeed SDK Configuration

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Configure the StripFeed client with an API key, optional base URL, and timeout.

```APIDOC
### Configuration

```typescript
const sf = new StripFeed({
  apiKey: "sf_live_your_api_key",
  baseUrl: "https://custom.api/v1",  // optional
  timeout: 10_000,                    // optional, default 30s
});
```
```

--------------------------------

### StripFeed API Reference: fetch

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Fetch a URL and return a structured result containing Markdown, token count, and metadata.

```APIDOC
### `sf.fetch(url, options?): Promise<FetchResult>`

Fetch a URL and return structured result with markdown, tokens, metadata.
```

--------------------------------

### Checking API Usage

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

The `usage` method provides information about your current monthly API usage, including your plan type, requests used, and remaining quota.

```APIDOC
## GET /usage

### Description
Retrieves your current monthly API usage statistics, plan details, and rate limits.

### Method
GET

### Endpoint
/usage

### Parameters
None

### Request Example
```typescript
import StripFeed from "stripfeed";
const sf = new StripFeed("sf_live_your_api_key");
const usage = await sf.usage();
```

### Response
#### Success Response (200)
- **plan** (string) - Your current plan ('free', 'pro', or 'enterprise').
- **usage** (number) - The number of requests used this month.
- **limit** (number | null) - Your monthly request limit (null if unlimited).
- **remaining** (number | null) - The number of requests remaining this month (null if unlimited).
- **resetsAt** (string) - An ISO 8601 timestamp indicating when your usage resets.

#### Response Example
```json
{
  "plan": "pro",
  "usage": 1250,
  "limit": 100000,
  "remaining": 98750,
  "resetsAt": "2026-04-01T00:00:00.000Z"
}
```
```

--------------------------------

### StripFeed SDK Usage: Batch fetch (Pro)

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Fetch multiple URLs in parallel. This feature requires a Pro plan.

```APIDOC
### Batch fetch (Pro)

```typescript
const result = await sf.batch(
  [
    "https://example.com",
    { url: "https://docs.anthropic.com", selector: "article" },
  ],
  { model: "claude-sonnet-4-6" },
);

for (const item of result.results) {
  console.log(`${item.url}: ${item.tokens} tokens`);
}
```
```

--------------------------------

### Batch Processing Multiple URLs

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

The `batch` method allows you to process up to 10 URLs in parallel. It returns individual success or failure statuses for each URL. This feature is available for Pro plan users.

```APIDOC
## POST /batch

### Description
Processes multiple URLs concurrently, returning detailed results for each.

### Method
POST

### Endpoint
/batch

### Parameters
#### Query Parameters
- **model** (string) - Optional - Specifies the model to use for processing, useful for tracking costs.

#### Request Body
- **urls** (array) - Required - An array of URLs or objects containing `url` and optional `selector`.
  - **url** (string) - Required - The URL to process.
  - **selector** (string) - Optional - A CSS selector to extract specific content.

### Request Example
```json
[
  "https://example.com",
  "https://docs.anthropic.com",
  { "url": "https://blog.example.com", "selector": "article" }
]
```

### Response
#### Success Response (200)
- **total** (number) - Total number of URLs processed.
- **success** (number) - Number of URLs processed successfully.
- **failed** (number) - Number of URLs that failed to process.
- **results** (array) - An array of objects, each containing the result for a processed URL.
  - **url** (string) - The URL that was processed.
  - **status** (number) - The HTTP status code of the result (200 for success).
  - **tokens** (number) - The number of tokens used for the successful request.
  - **savingsPercent** (number) - The percentage of savings achieved.
  - **markdown** (string) - The extracted content in markdown format.
  - **error** (string) - An error message if the processing failed.

#### Response Example
```json
{
  "total": 3,
  "success": 2,
  "failed": 1,
  "results": [
    {
      "url": "https://example.com",
      "status": 200,
      "tokens": 150,
      "savingsPercent": 85,
      "markdown": "# Example Domain\n..."
    },
    {
      "url": "https://docs.anthropic.com",
      "status": 200,
      "tokens": 2500,
      "savingsPercent": 92,
      "markdown": "# Anthropic Docs\n..."
    },
    {
      "url": "https://blog.example.com",
      "status": 502,
      "error": "Unreachable"
    }
  ]
}
```
```

--------------------------------

### Error Handling with StripFeed SDK

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Demonstrates how to catch and handle potential errors when using the StripFeed SDK, specifically checking for `StripFeedError` instances to log API status codes and messages. Requires the 'stripfeed' package.

```typescript
import { StripFeed, StripFeedError } from "stripfeed";

try {
  const result = await sf.fetch("https://example.com");
} catch (err) {
  if (err instanceof StripFeedError) {
    console.error(`API error ${err.status}: ${err.message}`);
  }
}
```

--------------------------------

### Fetch Only Markdown from URL

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

A shorthand method to fetch only the Markdown content from a given URL. Requires the 'stripfeed' package.

```typescript
const markdown = await sf.fetchMarkdown("https://example.com");
```

--------------------------------

### Implement CSS Selector Fallback with StripFeed (TypeScript)

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

This TypeScript code snippet demonstrates how to implement a fallback strategy for CSS selectors when fetching web content using the StripFeed SDK. It iterates through a predefined list of selectors, attempting to extract content with each one. If a selector fails or returns minimal content, it proceeds to the next. The function includes error handling for specific StripFeed errors and a final fallback to auto-extraction if all selectors fail. It requires the 'stripfeed' package.

```typescript
import { StripFeed, StripFeedError } from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

// Selectors ordered from most specific to broadest
const selectors = [
  "article.post-content",
  "article",
  "main",
  ".content",
  "#main"
];

async function fetchWithFallback(url: string): Promise<string> {
  for (const selector of selectors) {
    try {
      const result = await sf.fetch(url, { selector });
      // Check if we got meaningful content (not just a header/footer)
      if (result.markdown.length > 100) {
        console.log(`Success with selector: ${selector}`);
        return result.markdown;
      }
    } catch (err) {
      // 422 means selector matched nothing - try next one
      if (err instanceof StripFeedError && err.status === 422) {
        console.log(`Selector "${selector}" not found, trying next...`);
        continue;
      }
      throw err; // Re-throw auth, rate limit, and other errors
    }
  }

  // Last resort: fetch without selector (uses Readability auto-extraction)
  console.log("All selectors failed, using auto-extraction");
  const result = await sf.fetch(url);
  return result.markdown;
}

// Usage
// const content = await fetchWithFallback("https://blog.example.com/post");
// console.log(content);
```

--------------------------------

### Robust URL Fetching with Fallback Selectors

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Implements a strategy for fetching content from URLs that may have frequently changing website structures. It uses a chain of CSS selectors, falling back to broader ones or a no-selector fetch if specific ones fail. Includes error handling for specific StripFeed errors. Requires the 'stripfeed' package.

```typescript
import { StripFeed, StripFeedError } from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

// Define a list of selectors from most specific to least specific.
// If the site redesigns, the first selector may break but broader ones still work.
const selectors = ["article.post-content", "article", "main", ".content", "#main"];

async function fetchWithFallback(url: string): Promise<string> {
  for (const selector of selectors) {
    try {
      const result = await sf.fetch(url, { selector });
      // If content is too short, the selector probably matched a wrong element
      if (result.markdown.length > 100) {
        return result.markdown;
      }
    } catch (err) {
      // 422 means selector matched nothing on the page, try the next one
      if (err instanceof StripFeedError && err.status === 422) {
        continue;
      }
      throw err; // Re-throw non-selector errors (401, 429, 502, etc.)
    }
  }
  // If no selector worked, fetch without selector (gets full page content)
  const result = await sf.fetch(url);
  return result.markdown;
}
```

--------------------------------

### StripFeed SDK Usage: Fetch a single URL

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Fetch a single URL with various options like selector, format, model, cache, ttl, and maxTokens.

```APIDOC
### Fetch a single URL

```typescript
const result = await sf.fetch("https://example.com", {
  selector: "article",           // CSS selector (Pro)
  format: "json",                // json, text, html (Pro)
  model: "claude-sonnet-4-6",    // cost tracking
  cache: false,                  // bypass cache
  ttl: 7200,                     // custom cache TTL in seconds
  maxTokens: 5000,               // truncate to token budget
});
```
```

--------------------------------

### StripFeed SDK Usage: Robust selector strategy

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Implement a fallback chain of CSS selectors for resilient content extraction from websites with frequently changing structures.

```APIDOC
### Robust selector strategy for changing websites

When a website's content structure changes frequently, use a fallback chain of selectors to extract content without manual intervention:

```typescript
import { StripFeed, StripFeedError } from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

// Define a list of selectors from most specific to least specific.
// If the site redesigns, the first selector may break but broader ones still work.
const selectors = ["article.post-content", "article", "main", ".content", "#main"];

async function fetchWithFallback(url: string): Promise<string> {
  for (const selector of selectors) {
    try {
      const result = await sf.fetch(url, { selector });
      // If content is too short, the selector probably matched a wrong element
      if (result.markdown.length > 100) {
        return result.markdown;
      }
    } catch (err) {
      // 422 means selector matched nothing on the page, try the next one
      if (err instanceof StripFeedError && err.status === 422) {
        continue;
      }
      throw err; // Re-throw non-selector errors (401, 429, 502, etc.)
    }
  }
  // If no selector worked, fetch without selector (gets full page content)
  const result = await sf.fetch(url);
  return result.markdown;
}
```

**Tips for resilient extraction:**
- Order selectors from most specific (`article.post-body`) to broadest (`main`)
- Use semantic HTML tags (`article`, `main`) over class names, as they survive redesigns
- Check `result.markdown.length` or `result.tokens` to detect selector mismatches
- Fall back to a no-selector fetch as a last resort (StripFeed's Readability engine auto-extracts the main content)
- Use `cache: false` for monitoring scenarios where freshness matters
- Combine with `maxTokens` to cap output size regardless of what the selector captures
```

--------------------------------

### Check API Usage with StripFeed JS

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

The `usage` method returns your current monthly API usage, plan information, and rate limits. It provides details on requests used, the monthly limit, remaining requests, and when the usage resets.

```typescript
import StripFeed from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

const usage = await sf.usage();

console.log(`Plan: ${usage.plan}`);           // "free", "pro", or "enterprise"
console.log(`Usage: ${usage.usage}`);         // Requests used this month
console.log(`Limit: ${usage.limit}`);         // Monthly limit (null for unlimited)
console.log(`Remaining: ${usage.remaining}`); // Requests remaining (null for unlimited)
console.log(`Resets: ${usage.resetsAt}`);     // ISO timestamp of reset date

// Expected output:
// Plan: pro
// Usage: 1250
// Limit: 100000
// Remaining: 98750
// Resets: 2026-04-01T00:00:00.000Z
```

--------------------------------

### StripFeed API Reference: fetchMarkdown

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

A convenience method that returns only the Markdown string from a fetched URL.

```APIDOC
### `sf.fetchMarkdown(url, options?): Promise<string>`

Shorthand that returns only the markdown string.
```

--------------------------------

### Fetch Markdown Content Only (TypeScript)

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

Provides a convenience method `fetchMarkdown` to retrieve only the Markdown string from a URL, omitting metadata. It can also accept fetch options like CSS selectors and token limits.

```typescript
import StripFeed from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

// Get just the markdown content
const markdown = await sf.fetchMarkdown("https://example.com");

console.log(markdown);
// Output: "# Example Domain\n\nThis domain is for use in illustrative examples..."

// With options (format is automatically set to json internally)
const articleMarkdown = await sf.fetchMarkdown("https://blog.example.com/post", {
  selector: "article.post-content",
  maxTokens: 2000,
});
```

--------------------------------

### Committing with Specific Author in Git

Source: https://github.com/stripfeed/stripfeed-js/blob/main/CLAUDE.md

Demonstrates how to set a specific committer name and email for Git commits, ensuring all contributions are attributed to 'Claude'. This is a project-specific Git rule.

```bash
GIT_COMMITTER_NAME="Claude" GIT_COMMITTER_EMAIL="noreply@anthropic.com" git commit --author="Claude <noreply@anthropic.com>" -m "message"
```

--------------------------------

### Batch Process Multiple URLs with StripFeed JS

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

The `batch` method processes up to 10 URLs in parallel, returning individual results for each URL with success/failure status. This feature requires a Pro plan and accepts optional model tracking for costs.

```typescript
import StripFeed from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

// Batch fetch with mixed URL formats
const batchResult = await sf.batch(
  [
    "https://example.com",
    "https://docs.anthropic.com",
    { url: "https://blog.example.com", selector: "article" },
  ],
  { model: "claude-sonnet-4-6" }  // Optional: track costs per model
);

console.log(`Total: ${batchResult.total}`);
console.log(`Success: ${batchResult.success}`);
console.log(`Failed: ${batchResult.failed}`);

// Process individual results
for (const item of batchResult.results) {
  if (item.status === 200) {
    console.log(`${item.url}: ${item.tokens} tokens (saved ${item.savingsPercent}%)`);
    console.log(item.markdown);
  } else {
    console.error(`${item.url}: Error ${item.status} - ${item.error}`);
  }
}

// Expected output:
// Total: 3
// Success: 2
// Failed: 1
// https://example.com: 150 tokens (saved 85%)
// https://docs.anthropic.com: 2500 tokens (saved 92%)
// https://blog.example.com: Error 502 - Unreachable
```

--------------------------------

### Error Handling

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

Details on how the StripFeed SDK handles API errors using `StripFeedError`, including common error codes and their meanings.

```APIDOC
## Error Handling with StripFeedError

### Description
Explains how to catch and interpret `StripFeedError` exceptions thrown by the SDK for API-related issues.

### Method
Exception Handling

### Endpoint
N/A

### Parameters
None

### Request Example
```typescript
import { StripFeed, StripFeedError } from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

try {
  const result = await sf.fetch("https://example.com", { selector: "article" });
  console.log(result.markdown);
} catch (err) {
  if (err instanceof StripFeedError) {
    // Handle specific StripFeed errors
  } else {
    throw err; // Re-throw non-StripFeed errors
  }
}
```

### Response
#### Error Response (StripFeedError)
- **status** (number) - The HTTP status code of the error.
- **message** (string) - A descriptive error message from the API.
- **name** (string) - Always "StripFeedError".

Common Status Codes:
- **401**: Authentication failure (invalid API key).
- **403**: Plan restriction (feature requires a higher plan).
- **422**: CSS selector did not match any elements on the page.
- **429**: Rate limit exceeded.
- **502**: The target URL was unreachable or returned an error.

#### Response Example (within catch block)
```javascript
if (err instanceof StripFeedError) {
  switch (err.status) {
    case 401:
      console.error("Invalid API key");
      break;
    case 403:
      console.error("Feature requires Pro plan:", err.message);
      break;
    case 422:
      console.error("CSS selector matched nothing on page");
      break;
    case 429:
      console.error("Rate limit exceeded, retry later");
      break;
    case 502:
      console.error("Target URL unreachable:", err.message);
      break;
    default:
      console.error(`API error ${err.status}: ${err.message}`);
  }
}
```
```

--------------------------------

### StripFeed API Reference: parseHeaders

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Parse StripFeed response headers into a typed object.

```APIDOC
### `StripFeed.parseHeaders(headers): ResponseMeta`

Parse StripFeed response headers into a typed object.
```

--------------------------------

### StripFeed SDK Usage: Error handling

Source: https://github.com/stripfeed/stripfeed-js/blob/main/README.md

Implement error handling for API requests made using the StripFeed SDK.

```APIDOC
### Error handling

```typescript
import { StripFeed, StripFeedError } from "stripfeed";

try {
  const result = await sf.fetch("https://example.com");
} catch (err) {
  if (err instanceof StripFeedError) {
    console.error(`API error ${err.status}: ${err.message}`);
  }
}
```
```

--------------------------------

### Handle API Errors with StripFeed JS

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

The SDK throws `StripFeedError` for API errors, including HTTP status codes and error messages. This snippet demonstrates how to catch these errors and handle common issues like authentication failures, plan restrictions, rate limiting, and upstream errors.

```typescript
import { StripFeed, StripFeedError } from "stripfeed";

const sf = new StripFeed("sf_live_your_api_key");

try {
  const result = await sf.fetch("https://example.com", { selector: "article" });
  console.log(result.markdown);
} catch (err) {
  if (err instanceof StripFeedError) {
    switch (err.status) {
      case 401:
        console.error("Invalid API key");
        break;
      case 403:
        console.error("Feature requires Pro plan:", err.message);
        break;
      case 422:
        console.error("CSS selector matched nothing on page");
        break;
      case 429:
        console.error("Rate limit exceeded, retry later");
        break;
      case 502:
        console.error("Target URL unreachable:", err.message);
        break;
      default:
        console.error(`API error ${err.status}: ${err.message}`);
    }
  } else {
    throw err; // Re-throw non-StripFeed errors
  }
}

// StripFeedError properties:
// err.status  - HTTP status code (number)
// err.message - Error message from API (string)
// err.name    - "StripFeedError"
```

--------------------------------

### Parsing Response Headers

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

The static `parseHeaders` method helps extract metadata like rate limits and cache status directly from the response headers of a StripFeed API call.

```APIDOC
## Static Method: parseHeaders

### Description
Parses the `Headers` object from an HTTP response to extract StripFeed-specific metadata.

### Method
Static

### Endpoint
N/A (Method of the `StripFeed` class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```typescript
import StripFeed from "stripfeed";

const response = await fetch("https://www.stripfeed.dev/api/v1/fetch?url=https://example.com", {
  headers: { Authorization: "Bearer sf_live_your_api_key" }
});

const meta = StripFeed.parseHeaders(response.headers);
```

### Response
#### Success Response (200)
- **tokens** (number) - Tokens consumed by the request.
- **originalTokens** (number) - Original token count before any optimizations.
- **savingsPercent** (number) - Percentage of tokens saved.
- **cached** (boolean) - Indicates if the response was served from cache.
- **fetchMs** (number) - Time taken in milliseconds to fetch and process the content.
- **format** (string) - The format of the returned content (e.g., 'markdown', 'json').
- **model** (string | null) - The ID of the model used, or null.
- **truncated** (boolean) - Indicates if the content was truncated.
- **selector** (string | null) - The CSS selector used, if any.
- **rateLimit** (object) - An object containing rate limit details.
  - **limit** (number) - The rate limit ceiling.
  - **remaining** (number) - The number of requests remaining.
  - **reset** (number) - The reset timestamp in epoch milliseconds.

#### Response Example
```json
{
  "tokens": 1250,
  "originalTokens": 14200,
  "savingsPercent": 91.2,
  "cached": true,
  "fetchMs": 500,
  "format": "markdown",
  "model": "claude-sonnet-4-6",
  "truncated": false,
  "selector": "article",
  "rateLimit": {
    "limit": 10000,
    "remaining": 9900,
    "reset": 1678886400000
  }
}
```
```

--------------------------------

### Parse Response Headers with StripFeed JS

Source: https://context7.com/stripfeed/stripfeed-js/llms.txt

The static `parseHeaders` method extracts metadata from StripFeed response headers into a typed object. This is useful for accessing rate limit information, cache status, and processing time without parsing the response body.

```typescript
import StripFeed from "stripfeed";

// Example: Custom fetch with header parsing
const response = await fetch("https://www.stripfeed.dev/api/v1/fetch?url=https://example.com", {
  headers: { Authorization: "Bearer sf_live_your_api_key" }
});

const meta = StripFeed.parseHeaders(response.headers);

console.log(meta.tokens);              // 1250
console.log(meta.originalTokens);      // 14200
console.log(meta.savingsPercent);      // 91.2
console.log(meta.cached);              // true/false
console.log(meta.fetchMs);             // Processing time
console.log(meta.format);              // "markdown", "json", etc.
console.log(meta.model);               // Model ID or null
console.log(meta.truncated);           // Whether content was truncated
console.log(meta.selector);            // CSS selector used or null
console.log(meta.rateLimit.limit);     // Rate limit ceiling
console.log(meta.rateLimit.remaining); // Requests remaining
console.log(meta.rateLimit.reset);     // Reset timestamp (epoch)
```
Tokens:
Raw