katsau Docs

katsau SDK

Official TypeScript/JavaScript SDK for the katsau API.

katsau (Finnish): Preview, Overview

Installation

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

Configuration

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

Available Methods

extract(url)

Extract metadata from a URL

validate(url)

Validate OG tags and get quality score

tech(url)

Detect technologies used

classify(url, opts)

Classify content and extract topics

preview(url, opts)

Generate multi-platform previews

favicon(url, opts)

Get favicon for a URL

screenshot(url, opts)

Get screenshot URL

screenshotPresets()

Get available viewport presets

Method Examples

extract(url)

const data = await api.extract('https://github.com');
// Returns: { url, title, description, image, open_graph, twitter, meta, icons }

validate(url)

const validation = await api.validate('https://example.com');
// Returns: { url, valid, score, grade, checks, warnings, recommendations }

tech(url)

const tech = await api.tech('https://vercel.com');
// Returns: { url, technologies, categories, summary }

classify(url, options)

const classified = await api.classify('https://techcrunch.com', {
  includeEntities: true,
  includeSentiment: true,
});
// Returns: { url, content_type, classification, topics, language, reading_time, publish_info }

preview(url, options)

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

screenshot(url, options)

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

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

TypeScript Support

Full TypeScript support with all types exported:

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

REST API (No SDK)

You can also use the API directly with any HTTP client:

curl "https://api.katsau.com/v1/extract?url=https://github.com" \
  -H "Authorization: Bearer ks_live_your_api_key"

Resources

npm PackageGitHub Repo