TypeScript SDK

The TypeScript SDK works in Node.js 18 or newer and in the browser, on top of fetch. It ships its own type definitions. The source is at github.com/yggy-tech/yggy-sdk-js.

Install

The npm release of @yggy-tech/sdk is coming soon. Until then, install the tagged release from GitHub:

npm install github:yggy-tech/yggy-sdk-js#v0.1.0

npm builds the package on install. Bun skips that build unless you list @yggy-tech/sdk under trustedDependencies in your package.json.

Authenticate

Create an API key in yggy under Developers → API keys and keep it in the YGGY_API_KEY environment variable. A key that belongs to one organization needs nothing else. A personal key can see several organizations, so name the one you want in the x-yggy-organization-id header, by id or slug, as the examples do. See Authentication for key types and permissions.

Make your first call

List the projects your key can see:

import { Configuration, ProjectsApi } from "@yggy-tech/sdk";

const config = new Configuration({
  basePath: "https://api.yggy.tech",
  apiKey: process.env.YGGY_API_KEY,
  headers: { "x-yggy-organization-id": "acme-corp" },
});

const { projects } = await new ProjectsApi(config).listProjects();
for (const project of projects) console.log(project.name);

Each group of operations has its own class, for example ProjectsApi, DocumentsApi and QueryApi. Methods take one object with the path, query and body parameters.

Upload, wait and read the facts

This sample uploads Q4-report.pdf to project 0xproject, waits until extraction finishes, prints the extracted facts and asks a question. See Upload and extract for what each step returns.

import { openAsBlob } from "node:fs";
import { Configuration, DocumentsApi, QueryApi } from "@yggy-tech/sdk";

const config = new Configuration({
  basePath: "https://api.yggy.tech",
  apiKey: process.env.YGGY_API_KEY,
  headers: { "x-yggy-organization-id": "acme-corp" },
});
const documents = new DocumentsApi(config);
const projectId = "0xproject";

const { documentId } = await documents.uploadDocument({
  projectId,
  file: await openAsBlob("Q4-report.pdf"),
  title: "Q4 report.pdf",
});

let status = await documents.getDocumentStatus({ projectId, id: documentId });
while (!status.completed && !status.failed) {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  status = await documents.getDocumentStatus({ projectId, id: documentId });
}
if (status.failed) throw new Error(status.error ?? "Extraction failed");

const { triples } = await documents.listDocumentTriples({ projectId, id: documentId });
for (const t of triples) console.log(t.subject, t.predicate, t.object);

const answer = await new QueryApi(config).queryProject({
  projectId,
  queryProjectRequest: { question: "Which contracts renew in Q1?" },
});
console.log(answer.answer);

openAsBlob needs Node.js 19.8 or newer. In a browser, pass a File or Blob as file.

Handle errors

A call that gets an error status throws a ResponseError. Its response is the standard Response, so read response.status first and the JSON body for the error code. A network failure throws a FetchError.

import { ResponseError } from "@yggy-tech/sdk";

try {
  await new ProjectsApi(config).listProjects();
} catch (error) {
  if (error instanceof ResponseError) {
    console.error(error.response.status, await error.response.json());
  }
  throw error;
}

See Errors and rate limits for the codes and for 429 handling. Honour the Retry-After header before you retry.

Next steps

• Reference for every operation and field.
• Authentication for key types and permissions.
• Webhooks to react to events instead of polling.