Raggle JavaScript Client

Official JavaScript/TypeScript client library for the Raggle API - Extract structured data from any website with ease.

Features

• 🚀 Simple API: Direct fetch method for quick data extraction
• 🔒 Multiple Authentication Methods: API Key, Bearer Token, OAuth2
• 📦 Browser & Node.js: Works in both environments
• 🎯 TypeScript Support: Full type definitions included
• ⚡ React Components: Pre-built UI components for rapid integration
• 🔄 Retry Logic: Automatic retries for improved reliability
• 🛠️ CLI Tools: Generate TypeScript types from your extraction schemas

Installation

npm install raggle
# or
yarn add raggle
# or
pnpm add raggle

Quick Start

import Raggle from 'raggle';

// Initialize the client
const raggle = new Raggle('your-api-key');

// Extract structured data from a URL
const result = await raggle.fetch({
  url: 'https://news.ycombinator.com/',
  schema: {
    id: 'hn-extractor',
    name: 'Hacker News Extractor',
    description: 'Extract top stories from Hacker News',
    fields: [
      {
        name: 'top_stories',
        extractionType: 'ai',
        description: 'List the top 5 stories with their titles and points'
      }
    ],
    system_message: 'Extract information from the Hacker News homepage'
  }
});

console.log(result);

React Component Example

import { LinkExtractor } from 'raggle/components';

function App() {
  return (
    <LinkExtractor
      apiKey="your-api-key"
      schema={{
        fields: [
          { name: 'title', extractionType: 'ai', description: 'Article title' },
          { name: 'author', extractionType: 'ai', description: 'Article author' },
          { name: 'summary', extractionType: 'ai', description: 'Brief summary' }
        ]
      }}
      onFetchSuccess={(data) => console.log('Extracted:', data)}
    />
  );
}

API Documentation

Extraction

// Direct extraction (recommended)
const result = await raggle.fetch({
  url: 'https://example.com',
  schema: { /* ... */ }
});

// Use existing schema by ID
const result = await raggle.fetch({
  url: 'https://example.com',
  schema_id: 'existing-schema-id'
});

Jobs Management

// Create extraction job
const job = await raggle.jobs.create(url, schemaId);

// List jobs
const jobs = await raggle.jobs.list(page, pageSize);

// Get job details
const jobDetails = await raggle.jobs.get(jobId);

Schema Management

// Create new schema
const schema = await raggle.extractions.create({
  name: 'My Schema',
  fields: [/* ... */]
});

// List schemas
const schemas = await raggle.extractions.list(page, pageSize);

// Update schema
const updated = await raggle.extractions.update(schemaId, updates);

// Delete schema
await raggle.extractions.delete(schemaId);

CLI Usage

The raggle-js package includes a CLI for project initialization, generating TypeScript types, and documentation.

Available Commands

# Initialize a project with config and docs
raggle-js init

# Generate just the documentation
raggle-js docs

# Generate TypeScript types (formerly generate-types)
raggle-js pull

Initialize a Raggle Project

Quickly set up your project with Raggle:

# Using npx
npx raggle-js init

# Using npm script in package.json
npm run cli:init

# With environment variables
RAGGLE_PROJECT_ID=your-project-id RAGGLE_API_KEY=your-api-key npx raggle-js init

The init command will:

1. Generate TypeScript types from your extraction schemas
2. Create a raggle.config.ts file with your project configuration
3. Create comprehensive documentation in your project's /docs directory (RAGGLE.md)

Generate Documentation

Generate comprehensive documentation for your Raggle integration:

# Using npx
npx raggle-js docs

# Using npm script
npm run cli:docs

Pull Schema Types

Generate TypeScript types from your extraction schemas:

# Using npx
npx raggle-js pull

# Using npm script
npm run cli:pull

The pull command will:

1. Read your project ID from environment variables (RAGGLE_PROJECT_ID, VITE_RAGGLE_PROJECT_ID, or NEXT_PUBLIC_RAGGLE_PROJECT_ID)
2. Fetch the project metadata from the Raggle API
3. Generate TypeScript interfaces for all your extraction schemas
4. Save the types to raggle.config.ts in your current directory

Example generated types:

// Generated by raggle CLI
// Project: My Project
// Generated at: 2025-05-19T18:00:00.000Z

export interface ProductExtraction {
  /** Product title or name */
  title: string;
  /** Current price */
  price?: string;
  /** Product description */
  description?: string;
  /** Available or out of stock */
  availability?: "available" | "out of stock" | "limited";
  /** Product rating out of 5 */
  rating?: number;
}

Environment Variables

The CLI will automatically load environment variables from a .env file in your current directory. Supported variables:

• RAGGLE_PROJECT_ID - Your Raggle project ID
• RAGGLE_API_KEY - Your Raggle API key
• VITE_RAGGLE_PROJECT_ID - For Vite projects
• NEXT_PUBLIC_RAGGLE_PROJECT_ID - For Next.js projects

Authentication Options

// API Key
const raggle = new Raggle('your-api-key');

// Bearer Token
const raggle = new Raggle({
  type: 'bearer',
  token: 'your-bearer-token'
});

// OAuth2
const raggle = new Raggle({
  type: 'oauth2',
  accessToken: 'your-access-token'
});

Configuration

const raggle = new Raggle('your-api-key', {
  baseUrl: 'https://api.raggle.dev',
  timeout: 60000,
  maxRetries: 3,
  debug: true
});

Examples

Check out the /examples directory for complete working examples:

• Next.js Integration
• Vite React App
• WordPress Plugin

CDN Usage

For quick prototyping or WordPress sites:

<script src="https://js.raggle.co/index.js"></script>
<script>
  const raggle = new Raggle('your-api-key');
  // Use the client...
</script>

Development

# Install dependencies
npm install

# Build the package
npm run build

# Run tests
npm run test

# Start development mode
npm run dev

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting PRs.

License

MIT License - see LICENSE file for details.

Support

• 📖 Full Documentation
• 💬 Discord Community
• 🐛 Report Issues
• 📧 Email Support

Made with ❤️ by the Raggle team