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:

``

ts

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:

ts

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

ts

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:

ts

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/await

able.

ts

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.

ts

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.

js

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.

js

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.

ts

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:

ts

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.

ts

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

ArrayBuffer`s.

License

ISC

Copyright (c) 2023, SuperOffice AS