strale-fallback

When your agent's primary API fails, Strale picks up the call.

strale-fallback wraps any async function in your agent pipeline. When the primary call fails (timeout, 429, 503, malformed response), it automatically finds a matching Strale capability and executes it — returning structured JSON with a quality score.

Install

npm install strale-fallback

Usage

import { withFallback } from 'strale-fallback';

const validateIban = withFallback(
  async (iban: string) => myPrimaryApi.validateIban(iban),
  {
    taskDescription: 'validate IBAN number',
    straleApiKey: process.env.STRALE_API_KEY,
  }
);

const result = await validateIban('SE3550000000054910000003');
console.log(result.source);          // "primary" or "strale_fallback"
console.log(result.data);            // structured JSON either way
console.log(result.capabilityUsed);  // e.g. "iban-validate"

How it works

1. Your primary function is called normally
2. If it throws (any HTTP error, timeout, or exception), strale-fallback calls POST /v1/suggest with your taskDescription to find the best matching Strale capability
3. It executes that capability with your function's arguments as inputs
4. Returns a FallbackResult with source: "strale_fallback" so you know which path was taken

FallbackResult

| Field | Type | Description | |---|---|---| | success | boolean | Whether a result was obtained | | data | T or null | The result data | | source | string | "primary" or "strale_fallback" | | capabilityUsed | string? | Strale capability slug if fallback used | | straleSqs | number? | Quality score (0-100) if fallback used | | error | string? | Error message if both paths failed |

Quality threshold

const checkSanctions = withFallback(
  async (name: string) => primaryApi.checkSanctions(name),
  {
    taskDescription: 'check company sanctions',
    minSqs: 80,  // only use Strale if quality score >= 80
  }
);

Environment

Set STRALE_API_KEY — or pass it directly via straleApiKey. Get a free key with trial credits: https://strale.dev/signup

Free capabilities (no key needed)

iban-validate, email-validate, dns-lookup, json-repair, url-to-markdown — these work even without an API key.

Full capability catalog: https://strale.dev/capabilities

License

MIT