DispatchedJS - SDK

This is a TypeScript helper library for node.js server side to integrate https://dispatched.dev into your application. Perfect fot Next.js, Express, Koa, Hapi, Fastify, etc.

Installation

npm install @dispatchedjs/sdk

Usage

Dispatching a job

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

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

// dispatch a job immediately
const myPayload1 = { action: "example-action", data: "example-data" }; // must be serializable
const job1 = await client.dispatchJob(myPayload1, {
    maxRetries: 3,
});
console.log(job1); // { jobId: 'job_1234567890abcdef', status: 'QUEUED' }

// schedule for later
const myPayload2 = { action: "example-action", data: "example-data" }; // must be serializable
const job2 = await client.dispatchJob(myPayload1, {
    sheduleFor: new Date("2024-12-17T12:00:00Z"),
});
console.log(job2); // { jobId: 'job_1234567890abcdef', status: 'QUEUED' }

Checking job status

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

const jobId = "job_1234567890abcdef"; // from a job that was previously dispatched

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

Cancelling a job

// NOTE: Only jobs that are in the QUEUED state can be cancelled.

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

const jobId = "job_1234567890abcdef"; // from a job that was previously dispatched

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

Handle Webhook Verification

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

try {
    const payload = await webhookClient.getVerifiedPayload(req.headers.get('Authorization'), req.body);
    // TODO: do something with your payload
} catch (error) {
    console.error(error);
}

Debugging

Pass the debug option as true to the clients.

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

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

Local Development

When developing locally, you can use the Dispatched CLI to start a local server that will receive webhook callbacks.

1. Install the CLI globally:

npm install -g @dispatchedjs/cli

2. Start the local server (this would run the local sever at http://localhost:3100):

dispatchedjs listen --secret="any-webhook-secret-for-local-dev" --forward="http://localhost:3000/path/to/webhook/endpoint" --port=3100 --scheduledDelay=60

Options:

• --secret is the secret you want to use to verify the webhook requests. For security reasons, it is recommended to use a different secret than the one you use in production (you can use something simple like "abc123" for local development).
• --forward is the URL that Dispatched will send the webhook requests to.
• --port (optional) is the port you want the server to listen on. It defaults to 3100.
• --scheduledDelay in seconds: any jobs scheduled for in the future will be dispatched after this time. This helps with not having to wait for hours during development.

NOTE: Scheduled jobs will be processed immediately when using the local server.

3. Override the baseUrl to point to the local server in your code:

# .env
DISPATCHED_API_BASE_URL=http://localhost:3100

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

NOTE: You can pass an empty string to DISPATCHED_API_BASE_URL to use the default (production) Dispatched API URL. Simply leave the baseUrl: process.env.DISPATCHED_API_BASE_URL in the source code and not set the env variable in production.

License

MIT