v4

Client

View as markdown

Create and configure the client, and read the metadata of every API response.

A Synthient client performs no network I/O until a method is called. Create one and reuse it for every request. It has no close method.

Constructor

Creates a client.

constructor(options?: ClientOptions);

import { Synthient } from "@synthient/synthient";

export const client = new Synthient({
  maxRetries: 4,
  timeout: 30_000,
  userAgent: "my-app/1.0",
});
  • Auth: The API key is options.apiKey, or the SYNTHIENT_API_KEY environment variable when apiKey is omitted or undefined. Surrounding whitespace is trimmed.
  • Input: A missing or empty key, or a key with characters other than printable ASCII, throws a TypeError. An invalid option also throws: a bad baseURL or userAgent throws a TypeError, and a maxRetries or timeout out of range throws a RangeError.

ClientOptions

  • Name
    apiKey?
    Type
    string | undefined
    Description

    The API key. Defaults to the SYNTHIENT_API_KEY environment variable. An explicit empty string does not fall back to the variable.

  • Name
    baseURL?
    Type
    string | undefined
    Description

    The API base URL, including the version path. Defaults to DEFAULT_BASE_URL. It must be an http or https URL without credentials, a query, or a fragment.

  • Name
    maxRetries?
    Type
    number | undefined
    Description

    How many times a failed request is retried. Defaults to 2, and 0 disables retries. It must be a non-negative integer. See Retries and timeouts.

  • Name
    timeout?
    Type
    number | undefined
    Description

    The longest time in milliseconds to wait for response headers or for the next part of a body, including streams and downloads. Defaults to 60_000. It must be an integer from 1 to 2147483647. It does not limit a whole call; pass AbortSignal.timeout(ms) as a call's signal for that.

  • Name
    fetch?
    Type
    Fetch | undefined
    Description

    The fetch implementation. Defaults to the global fetch. A custom fetch must not follow redirects or replay requests itself, because the client relies on seeing each redirect to keep the API key away from other hosts, and on sending each billed lookup once. It must honor init.signal, which carries both the timeout and a call's signal. It also downloads exports from the storage host, without the API key.

  • Name
    userAgent?
    Type
    string | undefined
    Description

    Appended to the User-Agent header, such as "my-app/1.2". The header starts with synthient-node/ followed by the SDK version, VERSION.

  • Name
    onResponse?
    Type
    ((metadata: ResponseMetadata) => void) | undefined
    Description

    Called synchronously when each API response's headers arrive. See Response metadata.

RequestOptions

Every Synthient and Feed method takes an optional last argument that is a RequestOptions or extends it.

  • Name
    signal?
    Type
    AbortSignal | undefined
    Description

    Cancels the call. The call rejects with the signal's reason, as fetch does. Use AbortSignal.timeout(ms) to bound a whole call, including retries.

Fetch

The subset of fetch the client uses, for the fetch option.

type Fetch = (input: string, init: RequestInit) => Promise<Response>;

Constants

DEFAULT_BASE_URL is the base URL of the Synthient HTTP API. VERSION is the SDK version, such as "2.0.0", which is sent in the User-Agent header.

const DEFAULT_BASE_URL = "https://api.synthient.com/api/v4";
declare const VERSION: string;

Response metadata

onResponse is called synchronously when each API response's headers arrive, including retries, pages, stream handshakes, and responses that fail to decode.

import { Synthient } from "@synthient/synthient";

export const client = new Synthient({
  onResponse: (metadata) => {
    const remaining = metadata.headers.get("ratelimit-remaining");
    console.log(metadata.status, metadata.requestID, remaining);
  },
});
  • Coverage: Storage download responses are excluded.
  • Async: It must not be async.
  • Errors: If it throws, the error is reported with process.emitWarning and the call continues.
  • Rate limits: The SDK has no rate limit type. Read the RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers from headers instead. See Rate Limits.

ResponseMetadata

  • Name
    status
    Type
    number
    Description

    The HTTP status code.

  • Name
    requestID
    Type
    string
    Description

    The X-Request-ID header, or "".

  • Name
    headers
    Type
    Headers
    Description

    A copy of the response headers, including RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset when present. Changing it does not affect the client. Headers can contain sensitive data, such as presigned download URLs.

Previous
Next