Client SDK

pnpm add @hogsend/client

import { Hogsend } from "@hogsend/client";

const hs = new Hogsend({
  baseUrl: "https://api.example.com",
  apiKey: process.env.HOGSEND_DATA_KEY!, // hsk_… key with the `ingest` scope
});

await hs.contacts.upsert({
  email: "ada@example.com",
  userId: "u_1",
  properties: { plan: "pro" },
  lists: { newsletter: true },
}); // → { id, created, linked }

const found = await hs.contacts.find({ email: "ada@example.com" }); // → Contact[]

await hs.contacts.delete({ userId: "u_1" }); // → { deleted }

await hs.events.send({
  userId: "u_1",
  name: "signup",
  eventProperties: { source: "landing" }, // → trigger.where / exitOn
  contactProperties: { country: "GB" },   // → contact record
  idempotencyKey: "evt_abc",
}); // → { stored, exits: [{ journeyId, stateId, exited }] }

hs.events.track(/* … */); // alias of events.send

await hs.emails.send({
  to: "ada@example.com",
  template: "welcome",
  props: { name: "Ada" },
}); // → { emailSendId, status }

await hs.lists.list(); // → ListSummary[]
await hs.lists.subscribe({ list: "newsletter", email: "ada@example.com" });
await hs.lists.unsubscribe({ list: "newsletter", userId: "u_1" });

const admin = new Hogsend({
  baseUrl: "https://api.hogsend.com",
  apiKey: process.env.HOGSEND_ADMIN_KEY!, // a full-admin hsk_… key
});

// Create — returns the FULL signing secret. This is the only time (besides
// rotateSecret) the secret is returned. Store it now.
const endpoint = await admin.webhooks.create({
  url: "https://yourapp.com/webhooks/hogsend",
  eventTypes: ["contact.created", "email.delivered", "journey.completed"],
  description: "prod subscriber",
  disabled: false,
}); // → WebhookEndpoint & { secret: "whsec_…" }

await admin.webhooks.list({ limit: 50, offset: 0, includeDisabled: true }); // → WebhookEndpoint[]

await admin.webhooks.get(endpoint.id); // → WebhookEndpoint (no secret)

await admin.webhooks.update(endpoint.id, {
  eventTypes: ["email.delivered", "email.bounced"],
  description: null, // null clears the description
  disabled: true,
}); // → WebhookEndpoint

await admin.webhooks.delete(endpoint.id); // → { deleted: true }

// Rotate — hard cutover. The OLD secret is invalidated immediately; update
// every subscriber with the returned new secret (returned ONCE).
await admin.webhooks.rotateSecret(endpoint.id); // → { id, secret: "whsec_…", secretPrefix }

// Enqueue an out-of-band webhook.test delivery, sent regardless of eventTypes.
await admin.webhooks.sendTest(endpoint.id); // → { enqueued: true, eventType: "webhook.test" }

// A KEYED DESTINATION — fan the event stream out to PostHog/Segment/Slack instead
// of a signed POST. Credentials live in `config`; no signing secret is returned.
await admin.webhooks.create({
  kind: "posthog",
  eventTypes: ["email.delivered", "email.opened", "email.clicked", "email.bounced", "email.complained"],
  config: { apiKey: "phc_…", eventNames: { "email.clicked": "email.link_clicked" } },
}); // → WebhookEndpoint (kind="posthog", secretPrefix: null, no `secret`)

import { verifyHogsendWebhook } from "@hogsend/client";

const event = verifyHogsendWebhook({
  payload: rawBody,                          // RAW request body bytes (string)
  headers: req.headers,                      // the request headers
  secret: process.env.HOGSEND_WEBHOOK_SECRET!, // the endpoint's whsec_… secret
}); // → { id, type, timestamp, data }

import express from "express";
import { verifyHogsendWebhook } from "@hogsend/client";

const app = express();

app.post(
  "/webhooks/hogsend",
  express.raw({ type: "application/json" }), // keep the raw bytes
  (req, res) => {
    let event: { id: string; type: string; timestamp: string; data: unknown };
    try {
      event = verifyHogsendWebhook({
        payload: req.body.toString("utf8"),
        headers: req.headers as Record<string, string>,
        secret: process.env.HOGSEND_WEBHOOK_SECRET!,
      }) as typeof event;
    } catch {
      return res.sendStatus(401);
    }

    switch (event.type) {
      case "contact.created":
        // handle event.data …
        break;
      // …
    }

    res.sendStatus(200);
  },
);

type Identity =
  | { email: string; userId?: string }
  | { email?: string; userId: string };

import { HogsendAPIError, RateLimitError } from "@hogsend/client";

try {
  await hs.emails.send({ to: "x@y.com", template: "welcome", props: {} });
} catch (err) {
  if (err instanceof RateLimitError) {
    // 429 — back off for err.retryAfter seconds
  } else if (err instanceof HogsendAPIError) {
    // err.status (0 = transport failure), err.body (parsed JSON or raw text)
  }
}