SuperOffice WebAPI TypeScript client

Provides a strongly-typed API to the SuperOffice Agents (web services).

You can either set up a WebApi connection object, and use it as a factory to get agents:

import { WebApi } from "@superoffice/webapi";

let webapi = new WebApi("http://example.com/SuperOffice");
let agent = webapi.getWebhookAgent();
let hook = await agent.createDefaultWebhookAsync();
hook.Name = "My hook";
hook.Events = ["contact.created"];
hook.TargetUrl = "https://www.requestbin.com";
let hook = await agent.saveWebhookAsync(hook);

or you can configure the WebApi using a static method, and let the agents re-use the global configuration:

import { WebApi, WebhookAgent } from "@superoffice/webapi";

WebApi.configure("http://example.com/SuperOffice");
WebApi.authenticateWithPassword("username", "password");
let agent = new WebhookAgent();
let hook = await agent.createDefaultWebhookAsync();

or you can configure the agents directly

import { WebhookAgent } from "@superoffice/webapi";

let config: AxiosRequestConfig = { auth: { username: "username", password: "password" } };
let agent = new WebhookAgent("http://example.com/SuperOffice", config);
let hook = await agent.createDefaultWebhookAsync();

Request parameters are also typed, so you can define objects like this:

import { WebApi, Webhook, WebhookAgent } from "@superoffice/webapi";

let webhook: Webhook = {
  name: "My hook",
  events: ["contact.created"],
  type: "webhook",
  targetUrl: "https://www.requestbin.com"
};
WebApi.configure("http://example.com/SuperOffice");
let agent = new WebhookAgent();
let hook = await agent.saveWebhookAsync(webhook);

The hook object is typed, and its properties are all marked as optional, so that you don't have to fill in everything.

The agent methods return promises, so these are all thenable/awaitable.

let agent = new WebhookAgent();
agent.saveWebhookAsync(webhook).then(webhook => console.log(webhook.WebhookId));
const temp = await agent.saveWebhookAsync(webhook);

Agents API

Each agent corresponds to a service, with methods on the agent exposing service endpoints. Agents POST arguments to the service, and return the result wihtout implementing HTTP semantics.

import { WebApi, Webhook, WebhookAgent } from "@superoffice/webapi";

WebApi.configure("http://example.com/SuperOffice");
let agent = new WebhookAgent();
let hook = await agent.getWebhookAsync(123);
// hook == null

Typical methods on the Agents API:

• createDefaultXxxEntityAsync
• getXxxAsync
• getXxxEntityAsync
• saveXxxEntityAsync
• deleteXxxEntityAsync

REST API

The RestApi endpoints DO implement HTTP semantics, so trying to get a non-existent item will return a HTTP 404 rather than NULL.

import { WebApi, Webhook, WebhookRestApi } from "@superoffice/webapi";

WebApi.configure("http://example.com/SuperOffice");
let restApi = new WebhookRestApi();
let hook = await restApi.getByIdAsync(123);
// throws exception on 404 unless 

The REST API also supports conditional-get or conditional-put.

import { WebApi, Webhook, WebhookRestApi } from "@superoffice/webapi";

WebApi.configure("http://example.com/SuperOffice");
let restApi = new WebhookRestApi();
let hook = await restApi.getByIdAsync(123), { ifModifiedSince: new Date() };
// returns null when not modified

Typical methods on the REST API:

• getDefaultAsync
• getByIdAsync
• putByIdAsync
• postAsync
• patchByIdAsync
• deleteByIdAsync

Language parsing

This request will add SO-Language and SO-Culture headers to the HTTP request, so that the WebAPI will return strings that match the requested language (by using the resource strings and multi-language string parsing.

import { WebApi, WebhookAgent } from "@superoffice/webapi";
WebApi.configure("http://example.com/SuperOffice", "en-us");

let agent = new WebhookAgent();
let hook = await agent.CreateDefaultWebhook();

// HTTP request:
// POST http://example.com/SuperOffice/api/v1/Webhook/CreateDefaultWebhook
// SO-Language: en-us

You can disable string substitution for an agent instance by passing in an enum value:

WebApi.configure("http://example.com/SuperOffice", "en");

let agent = new WebhookAgent(ResourceParsing.DoNotParse);
let hook = await agent.CreateDefaultWebhook();

// HTTP request:
// POST http://example.com/SuperOffice/api/v1/Webhook/CreateDefaultWebhook
// SO-Language: -

Request Cancellation

You can cancel a request by providing an AbortController.

let agent = new WebhookAgent();
let aborter = agent.MakeAbortController();
let options: WebApiRequestOptions = { abortController: aborter };
agent
  .CreateDefaultWebhook(options)
  .then(response => console.log(response))
  .catch(err => {
    if (options.requestStatus === WebApiStatus.Cancelled) {
      console.error("Request was cancelled");
    }
  });

// Abort the request
aborter.abort();

Misc Types

• DateTime is converted to JS/TS date using Dayjs
• TimeSpan is converted to a Dayjs.Duration using Dayjs
• Blobs are converted to ArrayBuffers.

License

ISC

Copyright (c) 2023, SuperOffice AS