Credal Typescript Library

The Credal TypeScript library provides convenient access to the Credal API from TypeScript/JavaScript.

Documentation

Docs for the API endpoints available through the SDK can be found here.

Reference

A full reference of the SDK is available here.

Installation

npm install @credal/sdk

Usage

import { CredalClient } from "@credal/sdk";

const credal = new CredalClient({
  apiKey: process.env.CREDAL_API_KEY,
});

await credal.copilots.sendMessage({
    message: "Is Credal SOC 2 compliant?",
    userEmail: "[email protected]"
});

Docs for the API endpoints available through the SDK can be found here.

Self Hosted

If you're on a self-hosted Credal instance, then you can customize the base url of the SDK.

const credal = new CredalClient({
    apiKey: process.env.CREDAL_API_KEY,
    environment: "https://<custom-domain>/api",
  });

Request and Response Types

The SDK exports all request and response types as TypeScript interfaces. Simply import them under the Credal namespace:

import { Credal } from "@credal/sdk"; 

const metadata: Credal.DocumentMetadataPatch = {
  resourceIdentifier: "..."
};

Exception Handling

When the API returns a non-success status code (4xx or 5xx response), a subclass of CredalError will be thrown:

import { CredalError } from "@credal/sdk";

try {
  await credal.copilots.sendMessage(...);
} catch (err) {
  if (err instanceof CredalError) {
    console.log(err.statusCode); 
    console.log(err.message);
    console.log(err.body); 
  }
}

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retriable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retriable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the maxRetries request option to configure this behavior.

const response = await credal.copilots.sendMessage(..., {
  maxRetries: 0 // override maxRetries at the request level
});

Timeouts

The SDK defaults to a 60 second timout. Use the timeoutInSeconds option to configure this behavior.

const response = await credal.copilots.sendMessage(..., {
  timeoutInSeconds: 30 // override timeout to 30s
});

Aborting Requests

The SDK allows users to abort requests at any point by passing in an abort signal.

const controller = new AbortController();
const response = await credal.copilots.sendMessage(..., {
  abortSignal: controller.signal,
});
controller.abort(); // aborts the request

Runtime compatiblity

The SDK defaults to node-fetch but will use the global fetch client if present. The SDK works in the following runtimes:

The following runtimes are supported:

• Node.js 18+
• Vercel
• Cloudflare Workers
• Deno v1.25+
• Bun 1.0+
• React Native

Customizing Fetch client

The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an unsupported environment, this provides a way for you to break the glass and ensure the SDK works.

import { CredalClient } from "@credal/sdk";

const credal = new CredalClient({
  apiKey: "...",
  fetcher: // provide your implementation here
});