@compassdigital/sdk.typescript

Compass Digital Labs TypeScript SDK

Install

$ npm install --save @compassdigital/sdk.typescript@latest

Example Server Usage

import Provider from "@compassdigital/provider";
import { GetTaskRequest, GetTaskResponse } from "@compassdigital/sdk.typescript/interface/task";

const provider = new Provider({ type: "task" });

provider.on<GetTaskRequest, GetTaskResponse>("get_task", function (req, next): void {
    // ...
})

Example Client Usage

Instantiate Client:

import { ServiceClient } from "@compassdigital/sdk.typescript";

const api = new ServiceClient({ stage: "dev" });

Basic Request:

const task = await api.get_task(id);

Request Options:

These options may be passed to any request.

interface RequestOptions {
  // environment to make requests to
  stage?: string;
  // authentication token
  token?: string;
  // additional headers
  headers?: Record<string, string>;
  // log all requests and responses
  debug?: boolean;
  // the number of times to retry a request
  retry?: number;
  // timeout in milliseconds
  timeout?: number;
  // make requests against this base url.
  // per-service base urls are configured as an object
  // eg. { order: 'http://localhost:3000', shoppingcart: 'http://localhost:4000' }
  // note: the stage property is ignored if base_url is set
  base_url?: string;
  // intercept outgoing http requests
  intercept?: InterceptFn;
}

• The RequestOptions can be provided to the ServiceClient constructor or at the request call site.
• The options provided at the call site will overide options passed to the constructor.

const api = new ServiceClient({
    token: "<token>",
    retry: 2,
})

const location = await api.get_location(id, {
    token: "<token>",
    retry: 2,
})

The following environment variables may be used to set default options for debugging purposes:

• P2_SDK_STAGE
• P2_SDK_TOKEN
• P2_SDK_DEBUG
• P2_SDK_BASE_URL
  • can pass just a url to intercept all requests
  • eg. =http://localhost:3000
  • can pass a comma separated list to configure per-service base urls
  • eg. order=http://localhost:3000,shoppingcart=http://localhost:4000

Error Handling:

Non-200 responses are rejected with a ServiceError.

try {
    const shoppingcart = await api.get_shoppingcart(id);
} catch (err) {
    // Since the error type is `unknown` we must type assert before
    // accessing the properties.
    if (err instanceof ServiceError) {
        console.log(err.status, err.code, err.message);
    }

    // There are helpers for accessing the status and code
    if (ServiceError.code(err) === 400.31) {
        console.log("Failed to get menu");
    }
}

There is a ignore convenience method for ignoring specific status & error codes.

const issue: OrderIssue = { items: [] };
await api.post_order_issue(id, issue).ignore(400.18, 400.21);

There is a combine convenience method for returning an object which contains the response or error.

const res = await api.get_task(id).combine();

if (res.ok) {
  console.log("task", res.data);
} else {
  console.log("error", res.err);
}

Testing:

You can register an intercept function which will recieve all request.

import {
  ServiceClient,
  RequestData,
  ResponseData,
  FetchFn,
} from "@compassdigital/sdk.typescript";

async function intercept(req: RequestData, fetch: FetchFn): Promise<ResponseData> {
    expect(req.name).toBe("get_shoppingcart");
    return { ok: true, status: 200, body: JSON.stringify({}) }
}

const api = new ServiceClient({ intercept });

Code Gen

1. Add new services to manifest.json.
2. Run npm run gen.