@events-hub/sdk

Official TypeScript/JavaScript client for sending events to an Events Hub deployment. It wraps the HTTP API exposed by the NestJS backend so any application can trigger events with type safety and consistent headers.

Installation

npm install @events-hub/sdk
# or
yarn add @events-hub/sdk

Quick start

import { EventsHubClient } from "@events-hub/sdk";

const client = new EventsHubClient({
  baseUrl: "https://events.mycompany.com",
  apiKey: process.env.EVENTS_HUB_KEY,
});

await client.trigger("user.signed_up", {
  userId: "123",
  email: "[email protected]",
});

Options

await client.trigger("order.created", orderPayload, {
  userId: "user-42",
  metadata: { source: "checkout" },
});

await client.triggerDelayed("invoice.send", invoicePayload, 10_000);

await client.triggerScheduled(
  "reports.daily",
  { workspaceId: "acme" },
  "0 8 * * *",
);

await client.triggerBatch([
  { name: "user.signup", data: { email: "[email protected]" } },
  { name: "user.signup", data: { email: "[email protected]" } },
]);

Handler metadata

Need to introspect a handler’s schema? Fetch it through the admin API:

const handler = await client.getHandler("user-signup");
console.log(handler.expectedPayloadSchema);

Configuration

| Option | Description | | --------------- | --------------------------------------------------------------- | | baseUrl | Base URL to your deployed backend (required). | | apiKey | Optional API key. Sent using the x-api-key header by default. | | apiKeyHeader | Override header name if your backend expects a custom header. | | timeoutMs | Axios request timeout (defaults to 10s). | | defaultHeaders| Any extra headers to include in every request. |

Publishing

Use the provided script:

npm run build --workspace=@events-hub/sdk
npm publish --workspace=@events-hub/sdk --access public

Remember to update the version in package.json before publishing. Since this package depends on @events-hub/types, publish the types package first if you make changes to shared definitions.