JavaScript SDK

On this page

This guide walks you through using the DispatchedJS SDK, a TypeScript helper library for server-side Node.js applications. The SDK is compatible with Next.js, Express, Koa, Hapi, Fastify, and other Node.js frameworks. It supports TypeScript out of the box with full type definitions.

Installation

Install the SDK using npm:

npm install @dispatchedjs/sdk

Usage Guide

Creating a Client

Initialize the DispatchedJS client with your API key:

import { DispatchedClient } from "@dispatchedjs/sdk";

const client = new DispatchedClient({
    apiKey: process.env.DISPATCHED_API_KEY
});

Job Management

Dispatching Jobs

You can dispatch jobs for immediate execution or schedule them for later:

// Dispatch immediately
const immediatePayload = {
    action: "example-action",
    data: "example-data"
};

const immediateJob = await client.dispatchJob(immediatePayload, {
    maxRetries: 3,
});
console.log(immediateJob); // { jobId: 'job_1234567890abcdef', status: 'QUEUED' }

// Schedule for later
const scheduledPayload = {
    action: "example-action",
    data: "example-data"
};

const scheduledJob = await client.dispatchJob(scheduledPayload, {
    sheduleFor: new Date("2024-12-17T12:00:00Z"),
});
console.log(scheduledJob); // { jobId: 'job_1234567890abcdef', status: 'QUEUED' }

Note: Payload must be serializable.

Checking Job Status

Retrieve the current status of a previously dispatched job:

const jobId = "job_1234567890abcdef";
const job = await client.getJob(jobId);
console.log(job); // { jobId: 'job_1234567890abcdef', status: 'QUEUED' }

Cancelling Jobs

Cancel a queued job:

const jobId = "job_1234567890abcdef";
const job = await client.cancelJob(jobId);
console.log(job); // { jobId: 'job_1234567890abcdef', status: 'CANCELLED' }

Note: Only jobs in the QUEUED state can be cancelled.

Webhook Management

Handling Webhook Verification

Use the webhook client to verify incoming webhook requests:

interface MyPayloadType {
    action: string;
    data: string;
}

const webhookClient = new DispatchedWebhookClient({
    webhookSecret: process.env.DISPATCHED_WEBHOOK_SECRET
});

try {
    const payload = await webhookClient.getVerifiedPayload<MyPayloadType>(
        req.headers.get('Authorization'),
        req.body
    );
    // Process verified payload
} catch (error) {
    console.error(error);
}

Important Notes:

  • The Authorization parameter must be provided as a string from the request headers
  • The request body must be provided as a string (use JSON.stringify if needed)
  • The method supports generic types for strongly-typed payload handling

Debugging

Enable debug logging by passing the debug option to either client:

// For the main client
const client = new DispatchedClient({
    apiKey: process.env.DISPATCHED_API_KEY,
    debug: true
});

// For the webhook client
const webhookClient = new DispatchedWebhookClient({
    webhookSecret: process.env.DISPATCHED_WEBHOOK_SECRET,
    debug: true
});

Local Development Setup

Configuration

  1. Set up your environment variables:
# .env
DISPATCHED_API_BASE_URL=http://localhost:3100
  1. Configure the client with the local base URL:
const client = new DispatchedClient({
    apiKey: process.env.DISPATCHED_API_KEY,
    baseUrl: process.env.DISPATCHED_API_BASE_URL
});

Note: For production, you can leave DISPATCHED_API_BASE_URL unset to use the default production URL. The baseUrl configuration in your code can remain unchanged.

Using with CLI

For information about using the SDK with our local development CLI, please refer to our Local Development Guide.

API Reference

DispatchedClient

new DispatchedClient({
    apiKey: string;
    baseUrl?: string;
    debug?: boolean;
})

Methods:

  • dispatchJob(payload: any, options?: JobOptions)
  • getJob(jobId: string)
  • cancelJob(jobId: string)

DispatchedWebhookClient

new DispatchedWebhookClient({
    webhookSecret: string;
    debug?: boolean;
})

Methods:

  • getVerifiedPayload<T = any>(authorization: string | null | undefined, rawBody: any): Promise<WebhookPayload<T>>

Next Steps