TypeScript SDK

@mestafi/sdk is the official TypeScript and JavaScript client for the Mesta API. It ships CommonJS and ES module builds with type definitions, and runs on Node.js 18+, Bun, Deno, Cloudflare Workers and Vercel. Source, issues and the full method reference are at mestafi/mesta-typescript.

npm install @mestafi/sdk

Client options

import { MestaClient, MestaEnvironment } from "@mestafi/sdk";

const client = new MestaClient({
  apiKey: process.env.MESTA_API_KEY!,
  apiSecret: process.env.MESTA_API_SECRET!,
  environment: MestaEnvironment.Production,
});

Option	Default	Purpose
`apiKey`, `apiSecret`	required	Sent as `x-api-key` and `x-api-secret` on every request. Each accepts a string or a function that returns one, so keys can be rotated without recreating the client.
`environment`	`MestaEnvironment.Production`	`MestaEnvironment.Staging` for the staging API.
`baseUrl`	unset	A full base URL, if you route through a proxy. Overrides `environment`.
`timeoutInSeconds`	`60`	Per-request timeout.
`maxRetries`	`2`	Retries on 408, 429 and 5xx, with exponential backoff. See Retries, timeouts and writes before relying on retries for writes.
`headers`	unset	Extra headers sent on every request.
`fetcher`	built-in `fetch`	Your own fetch implementation, for runtimes the built-in one does not cover.
`logging`	silent	See Logging.

Request options

Every method takes an optional last argument with options that apply to that call only. Methods without a request body or query parameters still take the request object first, so pass {} for it.

const controller = new AbortController();

const accounts = await client.merchants.accounts.list(
  {},
  {
    maxRetries: 0,
    timeoutInSeconds: 30,
    abortSignal: controller.signal,
    headers: { "X-Request-Source": "payroll-run-42" },
  },
);

Options: maxRetries, timeoutInSeconds, abortSignal, headers and queryParams.

Types

Every request and response is an exported interface, available under the Mesta namespace. Union members such as currencies and statuses are string literal types, so an invalid value fails at compile time.

import { Mesta } from "@mestafi/sdk";

const request: Mesta.CreateQuotesRequest = {
  sourceCurrency: "USDC_SOL",
  targetCurrency: "EUR",
  sourceAmount: 10,
};

Raw responses

Append .withRawResponse() to any call to get the parsed body together with the HTTP response, including headers.

const { data, rawResponse } = await client.quotes.list().withRawResponse();
console.log(rawResponse.status, rawResponse.headers);

Smaller bundles

Each resource client can be imported on its own, which lets bundlers drop the resources you do not use.

import { QuotesClient } from "@mestafi/sdk/quotes";

const quotes = new QuotesClient({ apiKey: "...", apiSecret: "..." });

Logging

Logging is off by default. Turn it on with the logging option; the client logs each request and response at debug level with the credentials and other sensitive headers redacted. Pass any object with debug, info, warn and error methods to route the output into your own logger.

import { MestaClient, logging } from "@mestafi/sdk";

const client = new MestaClient({
  apiKey: "...",
  apiSecret: "...",
  logging: { level: logging.LogLevel.Debug, silent: false },
});

Errors

Every error extends MestaError, which carries statusCode, message, body and rawResponse. The status-specific classes live on the Mesta namespace: Mesta.BadRequestError, Mesta.UnauthorizedError, Mesta.ForbiddenError, Mesta.NotFoundError, Mesta.ConflictError, Mesta.TooManyRequestsError and Mesta.InternalServerError. A timeout throws MestaTimeoutError.

Endpoints the library does not cover yet

client.fetch(path, init, options) sends a request to any path on the API with the client's authentication, retries, timeout and logging applied, for an endpoint that is newer than your installed version.

const response = await client.fetch("/v1/quotes", { method: "GET" }, { maxRetries: 0 });
const body = await response.json();