TypeScript SDK · v0.1.0

@songforgeai/client

Dependency-free TypeScript client for the SongForgeAI Lyric Scoring API. Native fetch, full type definitions including the reproducibility seal, MIT- licensed.

Install

npm install @songforgeai/client

Quick start

import { SongForgeAI } from '@songforgeai/client';

const sf = new SongForgeAI({ apiKey: process.env.SFAI_API_KEY! });

const result = await sf.score({
  lyrics: '...',
  genre: 'country',
});

console.info(result.compositeScore, result.grade, result.percentile);
console.info('rubric:', result.seal.rubricVersion, 'model:', result.seal.model);

Per-metric scoring

When you want a single signal — e.g. surface a Specificity score next to a draft — use scoreMetric():

const out = await sf.scoreMetric('specificity', { lyrics: '...' });
console.info(out.score, out.band);  // 88, "Top 8%"

Slugs: prosody · structure · rhyme · economy · specificity · voice · narrative · truth · transcendence · arc · stickiness · genre-fit

Errors

All API failures throw SongForgeAIError with structured fields:

import { SongForgeAIError } from '@songforgeai/client';

try {
  await sf.score({ lyrics: 'short' });
} catch (e) {
  if (e instanceof SongForgeAIError) {
    console.error(e.status, e.code, e.detail);
    // 400 invalid_lyrics 'Min 50 characters.'
  }
}

The reproducibility seal travels with every response

Every score() and scoreMetric() result includes a seal field with the rubric version, model id, temperature, and deploy SHA so you can pin which engine produced any given score.

Read the model card →

Source

Source lives at packages/sdk. The README covers full API surface; this page is the marketing lift.