katsau SDK

Official TypeScript/JavaScript SDK for the katsau API.

katsau (Finnish): Preview, Overview

Installation

npm install katsau
# or
yarn add katsau
# or
pnpm add katsau

Quick Start

import { katsau } from 'katsau';

const api = new katsau('ks_live_your_api_key');

// Extract metadata
const data = await api.extract('https://github.com');
console.log(data.title, data.image);

// Validate OG tags
const validation = await api.validate('https://example.com');
console.log(`Score: ${validation.score}/100, Grade: ${validation.grade}`);

// Detect technologies
const tech = await api.tech('https://vercel.com');
console.log(tech.technologies.map(t => t.name));

// Classify content
const classified = await api.classify('https://techcrunch.com');
console.log(classified.classification.primary_category);

API Reference

Constructor

// Simple initialization
const api = new katsau('ks_live_xxx');

// With options
const api = new katsau({
  apiKey: 'ks_live_xxx',
  baseUrl: 'https://api.katsau.com',  // optional
  timeout: 30000,                       // optional, default 30s
});

Methods

extract(url, options?)

Extract metadata from a URL.

const data = await api.extract('https://github.com');

// Returns:
{
  url: string;
  title: string | null;
  description: string | null;
  image: string | null;
  open_graph: { title, description, image, type, site_name, ... };
  twitter: { card, site, title, description, image, ... };
  meta: { author, keywords, theme_color, favicon, language, ... };
  icons: [{ url, type, sizes, source }];
}

validate(url, options?)

Validate katsau tags and get a quality score.

const validation = await api.validate('https://example.com');

// Returns:
{
  url: string;
  valid: boolean;
  score: number;        // 0-100
  grade: string;        // A, B, C, D, F
  checks: { ... };
  warnings: string[];
  recommendations: [{ priority, tag, message, suggested_value }];
}

tech(url, options?)

Detect technologies used by a website.

const tech = await api.tech('https://vercel.com');

// Returns:
{
  url: string;
  technologies: [{ name, category, confidence, version, icon }];
  categories: { 'JavaScript frameworks': ['React', 'Next.js'], ... };
  summary: {
    total_technologies: number;
    primary_framework: string;
    hosting: string;
    has_analytics: boolean;
  };
}

classify(url, options?)

Classify website content and extract topics.

const classified = await api.classify('https://techcrunch.com', {
  includeEntities: true,
  includeSentiment: true,
});

// Returns:
{
  url: string;
  content_type: string;
  classification: { primary_category, secondary_category, confidence };
  topics: [{ name, score }];
  language: { code, name, confidence };
  reading_time: { minutes, words };
  publish_info: { date, author, publisher };
}

preview(url, options?)

Generate multi-platform previews.

const previews = await api.preview('https://stripe.com', {
  platforms: ['twitter', 'facebook', 'linkedin'],
});

// Returns:
{
  url: string;
  previews: {
    twitter: { platform, card_type, dimensions, elements, warnings };
    facebook: { ... };
    linkedin: { ... };
  };
}

favicon(url, options?)

Get favicon for a URL.

const favicon = await api.favicon('https://spotify.com', { size: 32 });

// Returns:
{
  url: string;
  icons: [{ url, type, sizes, source }];
  best_match: { url, size };
}

screenshot(url, options?)

Get a screenshot URL.

const screenshot = await api.screenshot('https://github.com', {
  width: 1200,
  height: 630,
  format: 'png',
  darkMode: true,
});

// Returns:
{
  url: string;  // CDN URL of the screenshot
}

screenshotPresets()

Get available screenshot presets.

const { presets } = await api.screenshotPresets();

// Returns:
{
  presets: [
    { name: 'desktop', width: 1920, height: 1080 },
    { name: 'mobile', width: 375, height: 812 },
    { name: 'og-image', width: 1200, height: 630 },
    // ...
  ];
}

Error Handling

import { katsau, katsauError } from 'katsau';

try {
  const data = await api.extract('https://invalid-url');
} catch (error) {
  if (error instanceof katsauError) {
    console.error(`Error ${error.code}: ${error.message}`);
    console.error(`Request ID: ${error.requestId}`);
  }
}

Error Codes

| Code | Description | |------|-------------| | MISSING_API_KEY | API key not provided | | INVALID_API_KEY | API key is invalid | | RATE_LIMIT_EXCEEDED | Too many requests | | INVALID_URL | URL format is invalid | | FETCH_FAILED | Failed to fetch the URL | | TIMEOUT | Request timed out |

TypeScript

Full TypeScript support with all types exported:

import {
  katsau,
  katsauConfig,
  ExtractData,
  ValidateData,
  TechData,
  ClassifyData,
  PreviewData,
  FaviconData,
  katsauError,
} from 'katsau';

License

MIT