JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 57
  • Score
    100M100P100Q75566F

JavaScript client for Raggle API

Package Exports

  • raggle-js
  • raggle-js/provider
  • raggle-js/react

Readme

Raggle JavaScript Client

npm version License: MIT

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' }
        ]
      }}
      onFetchSuccess={(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();

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

// 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:

  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.co',
  timeout: 60000,
  maxRetries: 3,
  debug: true
});

Examples

Check out the /examples directory for complete working examples:

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:

  1. Bumps the version number
  2. Runs type checking
  3. Builds with production configuration (uses https://api.raggle.co)
  4. 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


Made with ❤️ by the Raggle team