Mews SDK

This is an unofficial TypeScript SDK for interacting with the Mews connector API, with dual ESM/CJS builds and type declarations.

Installation

npm install mews-sdk
# or
yarn add mews-sdk
# or
pnpm add mews-sdk

Basic usage example

import { ApiCall, AccountingCategories, type Api } from 'mews-sdk';

const tenant: Api.Tenant = {
  AccessToken: 'myAccessToken',
  ClientToken: 'myClientToken',
  Client: 'myClient',
  ApiUrl: 'https://mews.li/api/connector/v1',
};

const call = new ApiCall(tenant, 'getAllAccountingCategories', {});
const categories = await AccountingCategories.getAll(call);
console.log(categories);

Imports

Types and runtime services can both be imported from mews-sdk in ESM or CJS fashion. All runtime services are directly imported at the root level and all types are imported under the 'Api' namespace.

//Runtime services
import { ApiCall, AccountingCategories } from 'mews-sdk';
//Types
import { type Api } from 'mews-sdk';

Connection credentials

Mews connection credentials and URL must be stored in a Tenant object that you can extend from Api.Tenant.

import { type Api } from 'mews-sdk';

interface MyTenant extends Api.Tenant {
  mydata?: string;
  //more of your data...
}
const tenant: MyTenant = {
  AccessToken: 'put_your_access_token_here',
  ClientToken: 'put_your_client_token_here',
  Client: 'put_your_client_description_here',
  ApiUrl: 'put_your_mews_api_base_url_here',
  mydata: 'mydata',
  //more of your data....
};

Api configuration

You can define api configuration options if desired. All errors will be thrown as exceptions that can be caught by plugging in your own logger callbacks. This api configuration parameter is optional and defaults to the following values when omitted:

import { type Api } from 'mews-sdk';

const config: Api.Config = {
  timeoutMs: 30000,
  retryPolicy: {
    maxRetries: 3,
    baseDelayMs: 500,
    retryableStatusCodes: [429, 500, 502, 503, 504],
    retryOnNetworkErrors: true,
    jitter: true,
  },
  logger: null,
};

Defining the call

First you need to define your operation. The possible operations can easily be inferred from the Mews API documentation or by simple inspection of the Api.Ops type.

import { type Api } from 'mews-sdk';
const apiOp: Api.Ops = 'getAllAccountingCategories';

The easiest way to define your call is by using the ApiCall helper. This helper will inject your connection credentials and URLs from the provided Tenant, type the request according to the provided operation and also provide sensible defaults for omitted generic request fields whenever possible; for example in the case of pagination it will provide by default a null Cursor and a page Count of 100. Any request fields different from the credentials can be overriden in the third parameter.

import { ApiCall } from 'mews-sdk';
//Define an api call using ApiCall and overriding default page size.
const call = new ApiCall(tenant, apiOp, {
  Limitation: {
    Count: 30, // Cursor defaults to null
  },
});

Should you ever wish to you can also directly type your request body without using the helper but in that case you must provide all required fields.

import { ApiCall, type Api } from 'mews-sdk';
//Directly type a request
const request: Api.AccountingCategories.GetAllRequest = {
  // All required fields must be provided:
  AccessToken: 'accessToken',
  ClientToken: 'clientToken',
  Client: 'client',
  Limitation: {
    Cursor: null,
    Count: 30,
  },
};
//config is optional:
const call = new ApiCall(tenant, apiOp, request, config);

Calling the Api

There are two ways to call the Api: using the ApiCall object or using dedicated endpoint function helpers. The helper functions are slightly more ergonomic but use some predetermined settings: they will automatically return paginated aggregated results for all endpoints supporting pagination and they will also internally scope the result when the api response objects are simple. The ApiCall object is less opinionated: it always returns unscoped bare responses and allows you more control over pagination by calling send() for a single unpaginated result or sendAll() for a paginated aggregated result.

import { AccountingCategories, ApiCall } from 'mews-sdk';

const call = new ApiCall(tenant, apiOp, request);

// Helper function call:
const aggregatedCategories = await AccountingCategories.getAll(call);

//ApiCall Object call:
const unPaginatedResponse = await call.send();
const aggregatedCategories = (await call.sendAll()).AccountingCategories;