@bokimo/sdk

Official TypeScript / JavaScript SDK for the Bokimo email & events API.

Installation

npm install @bokimo/sdk
# or
pnpm add @bokimo/sdk
# or
yarn add @bokimo/sdk

Requirements: Node.js ≥ 18 (uses the built-in fetch API).

Quick Start

import { BokimoClient } from "@bokimo/sdk";

const bokimo = new BokimoClient({
  baseUrl: "https://app.smler.in",  // or your self-hosted URL
  apiKey: process.env.BOKIMO_API_KEY!, // key from the Bokimo dashboard
});

Events

bokimo.events.emit(options)

Emit a named event that can trigger email workflows or other automations.

const result = await bokimo.events.emit({
  eventKey: "user.signup",
  payload: {
    userId: "abc123",
    plan: "pro",
  },
  userDetails: {
    email: "[email protected]",
    name: "Alice",
  },
  senderEmail: "[email protected]",
});

console.log(result.data.timestamp); // ISO timestamp

Options

| Property | Type | Required | Description | | ------------- | ----------------------------- | -------- | -------------------------------------------- | | eventKey | string | ✅ | Identifies which workflow(s) to trigger | | payload | Record<string, unknown> | ❌ | Arbitrary data forwarded to the workflow | | userDetails | { email: string; name?: string } | ✅ | Recipient details used by event-triggered emails | | senderEmail | string | ✅ | Verified sender address for triggered emails | | saveUser | boolean | ❌ | Reserved for future contact upsert support |

Emails

bokimo.emails.send(options)

Send a one-off email directly — no template required.

await bokimo.emails.send({
  from: "Acme <[email protected]>",
  to: "[email protected]",
  html: "<h1>Welcome to Acme!</h1><p>Thanks for signing up.</p>",
});

With multiple recipients, CC/BCC, and an attachment:

await bokimo.emails.send({
  from: "Acme <[email protected]>",
  to: ["[email protected]", "[email protected]"],
  cc: "[email protected]",
  html: "<p>Please find the invoice attached.</p>",
  attachments: [
    {
      filename: "invoice.pdf",
      content: "<base64-encoded-content>",
      encoding: "base64",
      contentType: "application/pdf",
    },
  ],
});

Options

| Property | Type | Required | Description | | ------------- | -------------------------------------- | -------- | ---------------------------------------- | | from | string | ✅ | Sender address / display name | | to | string \| string[] | ✅ | One or more recipient addresses | | html | string | ✅* | HTML body (html or text is required) | | text | string | ✅* | Plain-text body | | replyTo | string | ❌ | Reply-To address | | cc | string \| string[] | ❌ | CC recipients | | bcc | string \| string[] | ❌ | BCC recipients | | attachments | Attachment[] | ❌ | File attachments |

bokimo.emails.sendTemplate(options)

Send an email using a template saved in the Bokimo dashboard.

await bokimo.emails.sendTemplate({
  templateName: "welcome-email",
  from: "Acme <[email protected]>",
  to: "[email protected]",
  params: {
    firstName: "Alice",
    planName: "Pro",
    activationUrl: "https://acme.com/activate?token=xyz",
  },
});

Options

| Property | Type | Required | Description | | -------------- | ------------------------- | -------- | --------------------------------------------- | | templateName | string | ✅* | Name of the saved template (name or id) | | templateId | string | ✅* | Numeric ID of the saved template | | from | string | ✅ | Sender address / display name | | to | string \| string[] | ✅ | One or more recipient addresses | | replyTo | string | ❌ | Reply-To address | | cc | string \| string[] | ❌ | CC recipients | | bcc | string \| string[] | ❌ | BCC recipients | | params | Record<string, unknown> | ❌ | Variables interpolated into the template |

Error Handling

All methods throw a BokimoApiError on non-2xx responses.

import { BokimoClient, BokimoApiError } from "@bokimo/sdk";

try {
  await bokimo.events.emit({
    eventKey: "user.signup",
    userDetails: { email: "[email protected]" },
    senderEmail: "Acme <[email protected]>",
  });
} catch (err) {
  if (err instanceof BokimoApiError) {
    console.error(`API error ${err.status}:`, err.body);
  }
}

BokimoApiError properties

| Property | Type | Description | | -------- | -------------- | ------------------------- | | status | number | HTTP status code | | body | ApiErrorBody | Parsed JSON error payload | | message| string | Human-readable message |

Building from Source

cd sdk
pnpm install
pnpm build        # compiles to dist/
pnpm typecheck    # type-check without emitting

License

MIT