@konso/dispatch

TypeScript wrapper for the Konso Dispatch POST API.

Installation

npm install @konso/dispatch

pnpm add @konso/dispatch

If you use Corepack, enable it once and then install with pnpm:

corepack enable
pnpm add @konso/dispatch

Usage

import { KonsoDispatchClient, MessageType } from '@konso/dispatch';
import type { CreateDispatchRequest } from '@konso/dispatch';

const client = new KonsoDispatchClient({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
});

const payload: CreateDispatchRequest = {
  subject: 'Order confirmed',
  messageType: MessageType.Email,
  recipients: ['[email protected]'],
  plainBase64Body: Buffer.from('Your order is confirmed.').toString('base64'),
};

const response = await client.dispatch.create(payload);

if (response.succeeded) {
  console.log('Dispatched:', response.result);
} else {
  console.error('Dispatch failed:', response.errors, response.validationErrors);
}

Configuration

| Option | Type | Description | |---|---|---| | projectId | string | Your Konso project ID (required) | | apiKey | string | API key. Falls back to KONSO_API_KEY env var | | baseUrl | string | Custom API host. Falls back to KONSO_BASE_URL env var, then https://apis-spb.konso.io |

API

Exports

| Name | Kind | Description | |---|---|---| | KonsoDispatchClient | class | Main client — instantiate with new KonsoDispatchClient(config) | | KonsoHttpError | class | Thrown on non-2xx responses; has .status and .body | | MessageType | enum | Email = 1, SMS = 2, Push = 3, Messenger = 4 | | KonsoClientConfig | type | Constructor options | | CreateDispatchRequest | type | Payload for client.dispatch.create() | | ApiResponse<T> | type | Response envelope — check .succeeded, .result, .errors, .validationErrors | | ApiErrorItem | type | Shape of items in ApiResponse.errors | | ApiValidationErrorItem | type | Shape of items in ApiResponse.validationErrors | | PagedList<T> | type | Paginated result with .total and .list | | MessageTypeValue | type | Union of the MessageType enum values |

CreateDispatchRequest fields

| Field | Type | Required | Description | |---|---|---|---| | subject | string | yes | Message subject | | messageType | MessageTypeValue | yes | Channel (MessageType.Email, etc.) | | recipients | string[] | yes | Recipient addresses | | htmlBase64Body | string | no | Base64-encoded HTML body | | plainBase64Body | string | no | Base64-encoded plain-text body | | providerId | string | no | Override the default provider | | delay | number | no | Delivery delay in seconds | | env | string | no | Deployment environment tag | | correlationId | string | no | Correlation ID for tracing | | tags | string[] | no | Arbitrary tags |

Error handling

Non-2xx responses throw a KonsoHttpError:

import { KonsoHttpError } from '@konso/dispatch';

try {
  const response = await client.dispatch.create(payload);
} catch (err) {
  if (err instanceof KonsoHttpError) {
    console.error(err.status, err.body);
  }
}

Notes

• Requires a runtime with fetch available (Node 18+ or modern browsers).
• null fields in the request payload are stripped before sending.