raggle-js

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 and match methods for data extraction and analysis
• 🔒 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
• 🔍 Search Integration: Built-in web search capabilities
• 📊 Flexible Matching: Custom AI instructions for data analysis

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);

// Use the match method for flexible data analysis
const matchResult = await raggle.match({
  instructions: "Analyze the sentiment of these headlines",
  input_data: [{
    description: "news headlines",
    metadata: result.top_stories
  }],
  fields: {
    sentiment: "positive/negative/neutral",
    summary: "brief analysis"
  }
});

console.log(matchResult);

// Search for information
const searchResults = await raggle.search({
  query: "Hacker News alternatives",
  max_results: 5
});

// Get the best result
const bestResult = await raggle.luckySearch({
  query: "What is Hacker News?"
});

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' }
        ]
      }}
      onSuccess={(data) => console.log('Extracted:', data)}
    />
  );
}

API Documentation

Core Methods

Extract Data (fetch)

Extract structured data from URLs using AI-powered schemas:

// Direct extraction (recommended)
const result = await raggle.fetch({
  url: 'https://example.com',
  schema: {
    id: 'product-extractor',
    name: 'Product Extractor',
    description: 'Extract product information',
    fields: [
      {
        name: 'title',
        extractionType: 'ai',
        description: 'Product title'
      },
      {
        name: 'price',
        extractionType: 'ai',
        description: 'Product price'
      }
    ]
  }
});

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

// Extract with content instead of URL
const result = await raggle.fetch({
  content: 'extract data from this url https://example.com',
  schema_id: 'existing-schema-id'
});

Match Data (match)

Flexible data matching and extraction with custom instructions:

// Match and analyze data
const result = await raggle.match({
  instructions: "You're an analyst of news items and trends",
  input_data: [
    {
      description: "list of trends to match against",
      metadata: [
        { id: 1, headline: "AI continues to transform industries" },
        { id: 2, headline: "Climate tech investment surges" }
      ]
    }
  ],
  fields: {
    trends: [{ id: "trend ID", confidence: "high/medium/low" }],
    reasoning: "explanation of why these trends match"
  },
  url: "https://news.example.com" // Optional URL to fetch additional data
});

Search API

// Search - returns multiple results
const results = await raggle.search({
  query: "machine learning tutorials",
  max_results: 10
});

// Lucky search - returns single best result
const result = await raggle.luckySearch({
  query: "latest AI news"
});

Jobs API

Manage long-running extraction jobs:

// Create extraction job
const job = await raggle.jobs.create({
  url: 'https://example.com',
  schema_id: 'schema-id'
});

// List all jobs
const jobs = await raggle.jobs.list({
  skip: 0,
  limit: 10
});

// Get job status
const jobDetails = await raggle.jobs.get(job.id);

// Cancel a job
await raggle.jobs.cancel(job.id);

Extractions API (Schema Management)

Create and manage reusable extraction schemas:

// Create new schema
const schema = await raggle.extractions.create({
  name: 'E-commerce Product Schema',
  description: 'Extract product information from e-commerce sites',
  fields: [
    {
      name: 'title',
      extractionType: 'ai',
      description: 'Product title'
    },
    {
      name: 'price',
      extractionType: 'ai',
      description: 'Current price'
    },
    {
      name: 'availability',
      extractionType: 'ai',
      description: 'Stock availability'
    }
  ],
  system_message: 'Extract product information accurately'
});

// List all schemas
const schemas = await raggle.extractions.list({
  skip: 0,
  limit: 10
});

// Get schema details
const schemaDetails = await raggle.extractions.get(schema.id);

// Update schema
const updated = await raggle.extractions.update(schema.id, {
  name: 'Updated Product Schema',
  fields: [/* updated fields */]
});

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

// List public template schemas
const templates = await raggle.extractions.listPublic();

Forms API

Create and manage forms for data collection:

// Get a public form
const form = await raggle.getPublicForm('contact-form');

// Submit data to a form
const submission = await raggle.submitForm('contact-form', {
  input_data: {
    name: 'John Doe',
    email: '[e-mail]',
    message: 'Hello!'
  },
  submitter_email: '[e-mail]',
  submitter_name: 'John Doe'
});

// Advanced form management (requires authentication)
const forms = await raggle.forms.list();
const newForm = await raggle.forms.create({
  name: 'Contact Form',
  description: 'Contact us form',
  fields: [
    { name: 'name', type: 'text', required: true },
    { name: 'email', type: 'email', required: true },
    { name: 'message', type: 'textarea', required: true }
  ],
  require_auth: false
});

React Components

Raggle includes pre-built React components for rapid UI development:

FormClient Component

A flexible form component with built-in Cloudflare Turnstile human verification:

import { FormClient } from 'raggle/react';

function ContactForm() {
  const form = {
    id: 'contact-form',
    name: 'Contact Form',
    fields: [
      { name: 'name', type: 'text', label: 'Name', required: true },
      { name: 'email', type: 'email', label: 'Email', required: true },
      { name: 'message', type: 'textarea', label: 'Message', rows: 4 }
    ],
    require_auth: false
  };

  return (
    <FormClient
      form={form}
      onSubmit={async (submission) => {
        console.log('Form submitted:', submission);
      }}
      submitButtonText="Send Message"
      // Enable human verification (bot protection)
      useHumanCheck={true}
      turnstileSiteKey="your-cloudflare-turnstile-site-key"
    />
  );
}

FormClient Props:

• form: Form configuration object
• onSubmit: Callback when form is submitted
• useHumanCheck: Enable Cloudflare Turnstile verification
• turnstileSiteKey: Your Turnstile site key (required when useHumanCheck is true)
• compact: Use compact layout
• showDescriptions: Show field descriptions
• submitButtonText: Custom submit button text
• initialValues: Pre-fill form values
• errors: Display validation errors

See examples/form-with-turnstile.tsx for more usage examples.

Sites API

Manage site configurations and data:

// Get site data by subdomain
const siteData = await raggle.getSiteData('mysite');
// Returns full site configuration including forms, FAQs, assistants, etc.

// Advanced site management (requires authentication)
const sites = await raggle.sites.list();
const site = await raggle.sites.create({
  name: 'My Site',
  slug: 'mysite',
  subdomain: 'mysite',
  description: 'My awesome site'
});

Health API

Monitor API status and health:

// Basic health check
const health = await raggle.health.check();

// Detailed health status
const detailed = await raggle.health.detailed();

Complete API Reference

All methods are available directly on the Raggle instance:

const raggle = new Raggle('api-key');

// Direct methods (simplified API)
raggle.fetch(options)         // Extract data from URL
raggle.match(options)         // Match data with custom instructions
raggle.search(options)         // Search with multiple results
raggle.luckySearch(options)   // Search single best result
raggle.getSiteData(subdomain) // Get site configuration and data
raggle.getPublicForm(slug)    // Get public form by slug
raggle.submitForm(slug, data) // Submit data to a form

// Resource APIs (for advanced use)
raggle.extract.fetch(options) // Same as raggle.fetch()
raggle.jobs.create(params)    // Create extraction job
raggle.jobs.list(params)      // List jobs
raggle.jobs.get(id)          // Get job details
raggle.jobs.cancel(id)       // Cancel job

raggle.extractions.create(schema)     // Create schema
raggle.extractions.list(params)       // List schemas
raggle.extractions.get(id)           // Get schema
raggle.extractions.update(id, data)  // Update schema
raggle.extractions.delete(id)        // Delete schema
raggle.extractions.listPublic()      // List public templates

raggle.search.lucky(params)   // Same as raggle.luckySearch()
raggle.search.query(params)   // Same as raggle.search()

raggle.health.check()         // Basic health check
raggle.health.detailed()      // Detailed status

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:

• Generate TypeScript types from your extraction schemas
• Create a raggle.config.ts file with your project configuration
• 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:

• Read your project ID from environment variables (RAGGLE_PROJECT_ID, VITE_RAGGLE_PROJECT_ID, or NEXT_PUBLIC_RAGGLE_PROJECT_ID)
• Fetch the project metadata from the Raggle API
• Generate TypeScript interfaces for all your extraction schemas
• 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 (for server-to-server communication)
const raggle = new Raggle('your-api-key');

// JWT Authentication (for user-facing applications)
const raggle = new Raggle();
const auth = await raggle.authenticate({
  username: '[e-mail]',  // or username
  password: 'password'
});
// Now all API calls will use the JWT token

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

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

JWT Authentication Example

JWT authentication is ideal for user-facing applications where users log in with credentials:

// Initialize without authentication
const raggle = new Raggle();

// Authenticate user
try {
  const authResponse = await raggle.authenticate({
    username: '[e-mail]',
    password: 'password123'
  });
  
  console.log('Authenticated successfully!');
  
  // All subsequent API calls will use the JWT token
  const result = await raggle.fetch({
    url: 'https://example.com',
    schema_id: 'my-schema'
  });
  
} catch (error) {
  console.error('Authentication failed:', error.message);
}

Configuration

const raggle = new Raggle('your-api-key', {
  baseUrl: 'https://api.raggle.co',
  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              # Development build
npm run build:prod         # Production build (uses production API endpoints)

# Run tests
npm run test

# Start development mode
npm run dev

Local Development

During local development, the package will use environment variables from .env:

RAGGLE_API_BASE_DOMAIN=http://localhost:8899

Publishing

The package is automatically built with production configuration when publishing:

# Publish a patch version (e.g., 1.0.0 → 1.0.1)
npm run publish:patch

# Publish a minor version (e.g., 1.0.0 → 1.1.0)
npm run publish:minor

# Publish a major version (e.g., 1.0.0 → 2.0.0)
npm run publish:major

# Dry run to see what would be published
npm run publish:dry-run

The publish process:

• Bumps the version number
• Runs type checking
• Builds with production configuration (uses https://api.raggle.co)
• Publishes to npm registry

Note: The published package will always use production API endpoints, regardless of local .env settings.

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