@vagarylabs/sdk

The Vagary Labs platform SDK: a typed client for the product face of api.vagarylabs.com.

One package, one capability per subpath. Import the whole client or import only the capability you use — a subpath import links that capability and nothing else, so a build that calls speech-to-text does not carry the ad-serving or compliance route tables.

MIT licensed. Trademarks are not included in that grant — see LICENSE.

Install

npm install @vagarylabs/sdk

No dependencies. It runs anywhere fetch and URL exist: browsers, Node 18+, and edge runtimes. There is no React in this package and no stylesheet.

Use

Everything on one client:

import { createVagary } from '@vagarylabs/sdk';

const vagary = createVagary({ apiKey: process.env.VAGARY_API_KEY });
const hits = await vagary.retrieval.postSearch({ query: 'quarterly report' });

Or one capability, and only that capability:

import { createStt } from '@vagarylabs/sdk/stt';
import { createTransport } from '@vagarylabs/sdk/core';

const stt = createStt(createTransport({ apiKey: process.env.VAGARY_API_KEY }));
const text = await stt.postSpeechTranscriptions({ audio_url: 'https://example.com/call.wav' });

baseUrl defaults to https://api.vagarylabs.com; pass your own to target another environment. Supply fetch when the runtime has none on the global, or to instrument calls.

What is in the box

@vagarylabs/sdk/capabilities describes the package to itself — no credential required:

import { CAPABILITIES, ROUTES, CATALOG_VERSION, fetchCatalog } from '@vagarylabs/sdk/capabilities';

CAPABILITIES;       // every capability, its subpath, and how many routes it has
ROUTES;             // the compiled-in route table, with method, path, metric and scope
CATALOG_VERSION;    // the catalog version this build was generated from

await fetchCatalog(); // the table the server is serving right now — unauthenticated

fetchCatalog() is the honest way to check that a deployment has not moved ahead of the version you pinned: ROUTES is a snapshot compiled into the package, and that call is the live table.

Errors

A non-2xx response raises VagaryError, carrying the server's own answer unwrapped:

import { VagaryError } from '@vagarylabs/sdk';

try {
  await vagary.tts.postGenerate({ text: 'hello' });
} catch (err) {
  if (err instanceof VagaryError) {
    console.error(err.status, err.body);
  }
}

A 403 is usually entitlement rather than authentication: a key scoped to one product gets capability_not_in_product on another product's route.

Versioning

Pre-1.0. The surface is generated from the published route catalog, so it grows when the platform does; a minor release may add capabilities and methods. Pin an exact version if you need the surface to hold still.

Generated, not hand-written

Every method here corresponds to a route the gateway actually serves — the client is generated from the same catalog the server enforces entitlement against, and a drift gate fails the build if the committed client and that catalog disagree. A method that exists is a route that exists.