katsaus

Katsaus SDK

Official TypeScript/JavaScript SDK for the Katsaus API.

Katsaus (Finnish): Preview, Overview

Installation

npm install katsaus
# or
yarn add katsaus
# or
pnpm add katsaus

Quick Start

import { Katsaus } from 'katsaus';

const api = new Katsaus('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 Katsaus('ks_live_xxx');

// With options
const api = new Katsaus({
  apiKey: 'ks_live_xxx',
  baseUrl: 'https://api.katsaus.dev',  // 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 Katsaus 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 { Katsaus, KatsausError } from 'katsaus';

try {
  const data = await api.extract('https://invalid-url');
} catch (error) {
  if (error instanceof KatsausError) {
    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 {
  Katsaus,
  KatsausConfig,
  ExtractData,
  ValidateData,
  TechData,
  ClassifyData,
  PreviewData,
  FaviconData,
  KatsausError,
} from 'katsaus';

License

MIT