Package Exports
- raggle-js
- raggle-js/RaggleProvider
- raggle-js/components
- raggle-js/src/components
Readme
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
andmatch
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:
- 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
, orNEXT_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 IDRAGGLE_API_KEY
- Your Raggle API keyVITE_RAGGLE_PROJECT_ID
- For Vite projectsNEXT_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:
- 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
Made with ❤️ by the Raggle team