chartsplat

Official TypeScript/JavaScript client for Chart Splat - Generate beautiful charts via API.

Installation

npm install chartsplat

Quick Start

import { ChartSplat } from 'chartsplat';

const client = new ChartSplat('YOUR_API_KEY');

// Generate a bar chart
const chart = await client.generateChart({
  type: 'bar',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr'],
    datasets: [{
      label: 'Revenue',
      data: [12, 19, 3, 5],
      backgroundColor: '#8b5cf6'
    }]
  }
});

// Use the base64 image
console.log(chart.image); // data:image/png;base64,...

// Use in HTML
const img = document.createElement('img');
img.src = chart.image;

Features

• Full TypeScript support
• Works in Node.js (18+) and browsers
• Convenience methods for all chart types
• Rate limit tracking
• Timeout handling
• Custom fetch support for older Node.js versions

Usage

Basic Example

import { ChartSplat } from 'chartsplat';

const client = new ChartSplat('cs_your_api_key');

const chart = await client.generateChart({
  type: 'line',
  data: {
    labels: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
    datasets: [{
      label: 'Visitors',
      data: [100, 200, 150, 300, 250],
      borderColor: '#3b82f6',
      fill: false
    }]
  },
  options: {
    width: 1200,
    height: 800
  }
});

Convenience Methods

// Line chart
const lineChart = await client.lineChart({
  labels: ['A', 'B', 'C'],
  datasets: [{ data: [1, 2, 3], borderColor: '#3b82f6' }]
});

// Bar chart
const barChart = await client.barChart({
  labels: ['A', 'B', 'C'],
  datasets: [{ data: [1, 2, 3], backgroundColor: '#8b5cf6' }]
});

// Pie chart
const pieChart = await client.pieChart({
  labels: ['Red', 'Blue', 'Yellow'],
  datasets: [{ data: [30, 50, 20], backgroundColor: ['#ef4444', '#3b82f6', '#eab308'] }]
});

// Doughnut chart
const doughnutChart = await client.doughnutChart({
  labels: ['Desktop', 'Mobile'],
  datasets: [{ data: [60, 40], backgroundColor: ['#8b5cf6', '#ec4899'] }]
});

// Radar chart
const radarChart = await client.radarChart({
  labels: ['Speed', 'Power', 'Range'],
  datasets: [{ label: 'Player', data: [65, 59, 90], borderColor: '#f59e0b' }]
});

// Polar area chart
const polarChart = await client.polarAreaChart({
  labels: ['Red', 'Green', 'Blue'],
  datasets: [{ data: [11, 16, 7], backgroundColor: ['#ef4444', '#10b981', '#3b82f6'] }]
});

Save to File (Node.js)

import fs from 'fs';
import { ChartSplat } from 'chartsplat';

const client = new ChartSplat('cs_your_api_key');

const chart = await client.generateChart({
  type: 'bar',
  data: {
    labels: ['A', 'B', 'C'],
    datasets: [{ data: [1, 2, 3] }]
  }
});

// Remove the data URI prefix and decode
const base64Data = chart.image.replace(/^data:image\/png;base64,/, '');
fs.writeFileSync('chart.png', Buffer.from(base64Data, 'base64'));

React Example

import { ChartSplat } from 'chartsplat';
import { useState, useEffect } from 'react';

const client = new ChartSplat('cs_your_api_key');

function MyChart() {
  const [chartUrl, setChartUrl] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    async function loadChart() {
      try {
        const chart = await client.generateChart({
          type: 'line',
          data: {
            labels: ['Jan', 'Feb', 'Mar'],
            datasets: [{
              label: 'Sales',
              data: [100, 200, 150],
              borderColor: '#ec4899'
            }]
          }
        });
        setChartUrl(chart.image);
      } catch (err) {
        setError(err.message);
      }
    }
    loadChart();
  }, []);

  if (error) return <div>Error: {error}</div>;
  if (!chartUrl) return <div>Loading...</div>;
  return <img src={chartUrl} alt="Chart" />;
}

Rate Limit Handling

import { ChartSplat, ChartSplatAPIError } from 'chartsplat';

const client = new ChartSplat('cs_your_api_key');

try {
  const chart = await client.generateChart({ /* ... */ });

  // Check rate limit after request
  const rateLimit = client.getRateLimit();
  console.log(`${rateLimit.remaining}/${rateLimit.limit} requests remaining`);
  console.log(`Resets at: ${rateLimit.reset}`);
} catch (error) {
  if (error instanceof ChartSplatAPIError && error.status === 429) {
    console.log('Rate limited!');
    console.log(`Limit: ${error.rateLimit?.limit}`);
    console.log(`Resets at: ${error.rateLimit?.reset}`);
  }
}

Custom Configuration

import { ChartSplat } from 'chartsplat';

const client = new ChartSplat('cs_your_api_key', {
  // Custom base URL (for local development)
  baseUrl: 'http://localhost:3001',

  // Request timeout in milliseconds
  timeout: 60000,

  // Custom fetch (for Node.js < 18)
  fetch: require('node-fetch'),
});

API Reference

ChartSplat Class

Constructor

new ChartSplat(apiKey: string, options?: ChartSplatOptions)

• apiKey - Your Chart Splat API key (starts with cs_)
• options.baseUrl - Base URL for the API (default: https://api.chartsplat.com)
• options.timeout - Request timeout in ms (default: 30000)
• options.fetch - Custom fetch implementation

Methods

• generateChart(request: ChartRequest): Promise<ChartResponse> - Generate any chart type
• lineChart(data: ChartData, options?: ChartOptions): Promise<ChartResponse> - Generate a line chart
• barChart(data: ChartData, options?: ChartOptions): Promise<ChartResponse> - Generate a bar chart
• pieChart(data: ChartData, options?: ChartOptions): Promise<ChartResponse> - Generate a pie chart
• doughnutChart(data: ChartData, options?: ChartOptions): Promise<ChartResponse> - Generate a doughnut chart
• radarChart(data: ChartData, options?: ChartOptions): Promise<ChartResponse> - Generate a radar chart
• polarAreaChart(data: ChartData, options?: ChartOptions): Promise<ChartResponse> - Generate a polar area chart
• getRateLimit(): RateLimitInfo | undefined - Get rate limit info from last request

Types

interface ChartRequest {
  type?: 'line' | 'bar' | 'pie' | 'doughnut' | 'radar' | 'polarArea';
  data: ChartData;
  options?: ChartOptions;
}

interface ChartData {
  labels: string[];
  datasets: Dataset[];
}

interface Dataset {
  label?: string;
  data: number[];
  backgroundColor?: string | string[];
  borderColor?: string | string[];
  borderWidth?: number;
  fill?: boolean;
}

interface ChartOptions {
  width?: number;  // Default: 800
  height?: number; // Default: 600
  plugins?: Record<string, unknown>;
  scales?: Record<string, unknown>;
}

interface ChartResponse {
  image: string;   // Base64 PNG with data URI prefix
  format: 'png';
  width: number;
  height: number;
}

Error Handling

The client throws typed errors for different failure scenarios:

import { ChartSplat, ChartSplatAPIError, ChartSplatTimeoutError } from 'chartsplat';

try {
  const chart = await client.generateChart({ /* ... */ });
} catch (error) {
  if (error instanceof ChartSplatAPIError) {
    console.log('API Error:', error.message);
    console.log('Status:', error.status);
    console.log('Code:', error.code);
  } else if (error instanceof ChartSplatTimeoutError) {
    console.log('Request timed out');
  } else {
    console.log('Unknown error:', error);
  }
}

License

MIT - see LICENSE for details.

Links

• Website
• Documentation
• Pricing
• OpenAPI Spec