@hogsend/cli 0.2.2 → 0.6.0

package/skills/hogsend-client-sdk/references/api-surface.md

@@ -0,0 +1,181 @@
+# `@hogsend/client` — full API surface
+
+Every method on the `Hogsend` instance, with its input and result shape and the
+data-plane route it maps to. All inputs that mutate require an **identity** —
+at least one of `email` or `userId` (both may be supplied), enforced by
+`assertIdentity` at runtime and the `Identity` union at compile time.
+
+## `hs.contacts`
+
+### `contacts.upsert(input) → { id, created, linked }`
+
+`PUT /v1/contacts`. Upsert a contact by identity; the server resolves/merges
+(including identity linking when both `email` and `userId` are given).
+
+```ts
+type UpsertContactInput = Identity & {
+  properties?: Record<string, unknown>;   // merged onto the contact
+  lists?: Record<string, boolean>;        // inline list membership flips
+};
+// → { id: string; created: boolean; linked: boolean }
+```
+
+- `created` — `true` when a brand-new contact row was inserted.
+- `linked` — `true` when the upsert merged two previously-separate identities
+  (an `email`-only and a `userId`-only contact) into one.
+
+### `contacts.find(input) → Contact[]`
+
+`GET /v1/contacts/find`. Look up non-deleted contacts by EXACTLY ONE of `email`
+or `userId` (the find input is `{ email } | { userId }`, not the general
+identity union). Returns an array (may be empty).
+
+```ts
+type FindContactsInput = { email: string } | { userId: string };
+
+interface Contact {
+  id: string;
+  externalId: string | null;
+  email: string | null;
+  properties: Record<string, unknown>;
+  firstSeenAt: string;   // ISO — always present
+  lastSeenAt: string;    // ISO
+  createdAt: string;     // ISO
+  updatedAt: string;     // ISO
+}
+```
+
+### `contacts.delete(input) → { deleted }`
+
+`DELETE /v1/contacts`. Soft-delete a contact by identity. `deleted` is `true`
+when a matching contact was found and marked deleted.
+
+## `hs.events`
+
+### `events.send(input) → { stored, exits, listsError? }` · alias `events.track`
+
+`POST /v1/events` → **202 Accepted**. Push an event through the full ingestion
+pipeline (store → route to Hatchet/journeys → evaluate `exitOn` → upsert contact).
+`events.track` is a literal alias of `events.send`.
+
+```ts
+type SendEventInput = Identity & {
+  name: string;
+  eventProperties?: Record<string, unknown>;   // stored ON the event → trigger.where / exitOn
+  contactProperties?: Record<string, unknown>; // merged onto the CONTACT
+  lists?: Record<string, boolean>;             // inline list membership
+  idempotencyKey?: string;                     // dedup
+};
+
+interface IngestResult {
+  stored: boolean;                 // false only on idempotency-key dedup
+  exits: { journeyId: string; stateId: string; exited: boolean }[];
+  listsError?: string;             // present only if the post-ingest lists write failed
+}
+```
+
+- See the main SKILL for the `eventProperties` vs `contactProperties` split and
+  the `listsError`-on-202 semantics.
+- **`idempotencyKey`** is sent BOTH as the `Idempotency-Key` HTTP header (which
+  wins server-side) AND in the body, matching the route. Reuse the same key to
+  make a retried `events.send` a no-op (`stored: false`).
+
+## `hs.emails`
+
+### `emails.send(input) → { emailSendId, status, reason? }`
+
+`POST /v1/emails`. Send a transactional email by template through the full
+preferences + tracking pipeline (link-click + open rewriting applied
+automatically). Recipient is `to` (raw address) OR `userId` (resolved to the
+contact's email server-side).
+
+```ts
+type SendEmailInput = SendEmailEnvelope & ( typed-or-untyped template variant );
+
+type SendEmailEnvelope = {
+  to?: string;
+  userId?: string;
+  from?: string;
+  subject?: string;
+  replyTo?: string;
+  category?: string;            // a LIST id to gate the send on (see hogsend-authoring-lists)
+  skipPreferenceCheck?: boolean;// bypass unsub/suppression — needs full-admin
+  idempotencyKey?: string;
+};
+
+interface SendEmailResult {
+  emailSendId: string;
+  status: string;               // queued | sent | suppressed | unsubscribed | skipped
+  reason?: string;
+}
+```
+
+**Typed templates.** When `@hogsend/email` is installed (a TYPE-ONLY optional
+peer) and you augment its `TemplateRegistryMap`, `template` and `props` are
+fully type-checked per known template key. Without it, the shape degrades to
+`{ template: string; props?: Record<string, unknown> }`.
+
+> tsconfig caveat: the shipped `.d.ts` references `@hogsend/email` by module
+> name. If you do NOT install that optional peer, keep `skipLibCheck: true` (the
+> scaffold default) or `tsc` emits `TS2307: Cannot find module '@hogsend/email'`
+> from this package's declarations. Installing the peer (even type-only) removes
+> the caveat. The runtime JS has no dependency on `@hogsend/email`.
+
+- `category` gates the send on a code-defined list's opt-in/opt-out polarity —
+  see the hogsend-authoring-lists skill.
+- `skipPreferenceCheck: true` bypasses the unsubscribe/suppression gate and
+  requires a `full-admin` key, not a plain `ingest` key.
+
+## `hs.lists`
+
+### `lists.list() → ListSummary[]`
+
+`GET /v1/lists`. Every code-defined list in the app.
+
+```ts
+interface ListSummary {
+  id: string;
+  name: string;
+  description?: string;
+  defaultOptIn: boolean;
+}
+```
+
+### `lists.subscribe(input) → { subscribed: true }`
+
+`POST /v1/lists/:id/subscribe`. Sets `categories[id] = true` for the identity.
+
+### `lists.unsubscribe(input) → { unsubscribed: true }`
+
+`POST /v1/lists/:id/unsubscribe`. Sets `categories[id] = false` for the identity.
+
+```ts
+type SubscribeInput = Identity & { list: string };
+```
+
+For how `subscribe`/`unsubscribe` interact with a list's `defaultOptIn` polarity
+(opt-in needs an exact `true`, opt-out is blocked only on an exact `false`), see
+the hogsend-authoring-lists skill.
+
+## Construction options (recap)
+
+```ts
+interface HogsendOptions {
+  baseUrl: string;                     // required — e.g. https://api.example.com
+  apiKey: string;                      // required — hsk_… key with the `ingest` scope
+  fetch?: typeof fetch;                // default: global fetch
+  timeoutMs?: number;                  // default: 30000 (aborts the request)
+  headers?: Record<string, string>;   // merged onto every request
+}
+```
+
+## Errors (recap)
+
+- `HogsendAPIError` — `{ status, body }`. `status === 0` = transport failure
+  (DNS/connect/timeout); `body` is parsed JSON or raw text.
+- `RateLimitError extends HogsendAPIError` — `status === 429`, with `retryAfter`
+  (seconds) from the `Retry-After` header when present.
+
+Both are exported from `@hogsend/client` and are real classes, so
+`err instanceof RateLimitError` / `err instanceof HogsendAPIError` narrows
+correctly (check `RateLimitError` first — it is the subclass).

package/src/bin.ts

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 import { commands } from "./commands/index.js";
 import type { Command } from "./commands/types.js";
 import { parseGlobalFlags, resolveConfig } from "./lib/config.js";
-import { createAdminClient } from "./lib/http.js";
+import { createAdminClient, createDataPlaneClient } from "./lib/http.js";
 import { color, createOutput } from "./lib/output.js";
 
 function version(): string {
@@ -31,6 +31,7 @@ ${list}
 ${color.dim("Global options:")}
   --url <baseUrl>     Target instance (default HOGSEND_API_URL or http://localhost:3002)
   --admin-key <key>   Admin bearer token (default HOGSEND_ADMIN_KEY / ADMIN_API_KEY)
+  --data-key <key>    Ingest bearer token for writes (default HOGSEND_DATA_KEY / HOGSEND_API_KEY)
   --json              Emit machine-readable JSON only (for agents)
   -h, --help          Show help (use after a command for command help)
   -v, --version       Show version
@@ -80,11 +81,13 @@ async function main(): Promise<void> {
 
   const cfg = resolveConfig(flags);
   const http = createAdminClient(cfg);
+  const dataHttp = createDataPlaneClient(cfg);
 
   await command.run({
     argv: flags.rest,
     cfg,
     http,
+    dataHttp,
     out,
     json: flags.json,
   });

package/src/commands/campaigns.ts

@@ -0,0 +1,309 @@
+import { parseArgs } from "node:util";
+import { isHttpError } from "../lib/http.js";
+import { color } from "../lib/output.js";
+import type { Command, CommandContext } from "./types.js";
+
+const usage = `hogsend campaigns <subcommand> [options]
+
+Queue and inspect broadcasts: durably send one email template to every
+subscribed member of a list (or every active member of a bucket). Wraps the
+data-plane campaigns routes (POST /v1/campaigns, GET /v1/campaigns/{id}).
+
+Subcommands:
+  send                  Queue a campaign. Sends run async in the worker.
+  status <id>           Show a campaign's status + send counts.
+
+send options (exactly one of --list / --bucket, plus --template, required):
+  --list <id>           Target every subscribed member of this list.
+  --bucket <id>         Target every active member of this bucket.
+  --template <key>      Email template to send.
+  --prop <key=value>    Template prop; repeatable. Value parsed as JSON, falling
+                        back to a string.
+  --props <json>        Template props as one JSON object (merged with --prop).
+  --name <text>         Human label for the campaign.
+  --from <addr>         Override the default From address.
+  --subject <text>      Override the rendered subject.
+
+Global options (handled by the router): --url, --admin-key, --data-key, --json,
+-h/--help.
+
+Examples:
+  hogsend campaigns send --list newsletter --template june-update --name "June"
+  hogsend campaigns send --bucket power-users --template feature-launch --json
+  hogsend campaigns status cmp_123 --json`;
+
+const badge = `${color.bgMagenta(color.black(" hogsend "))} campaigns`;
+
+/** Shape returned by POST /v1/campaigns (202 enqueue ack). */
+interface SendResponse {
+  campaignId: string;
+  status: "queued" | "sending" | "sent" | "failed";
+}
+
+/** Shape returned by GET /v1/campaigns/{id}. */
+interface StatusResponse {
+  id: string;
+  name: string;
+  status: "queued" | "sending" | "sent" | "failed";
+  audienceKind: "list" | "bucket";
+  audienceId: string;
+  templateKey: string;
+  totalRecipients: number;
+  sentCount: number;
+  skippedCount: number;
+  failedCount: number;
+  startedAt: string | null;
+  completedAt: string | null;
+  createdAt: string;
+}
+
+/**
+ * Parse `--prop key=value` (repeatable) + an optional `--props <json>` object
+ * into a single props record. Each `--prop` value is JSON-parsed when valid
+ * JSON, else kept as a string. The `--props` object is applied first, so later
+ * `--prop` flags win.
+ */
+function parseProps(
+  ctx: CommandContext,
+  propsJson: string | undefined,
+  propPairs: string[] | undefined,
+): Record<string, unknown> | undefined {
+  const out: Record<string, unknown> = {};
+  let any = false;
+
+  if (propsJson !== undefined) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(propsJson);
+    } catch {
+      ctx.out.fail(`--props must be valid JSON, got: ${propsJson}`);
+    }
+    if (
+      parsed === null ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed)
+    ) {
+      ctx.out.fail("--props must be a JSON object");
+    }
+    Object.assign(out, parsed as Record<string, unknown>);
+    any = true;
+  }
+
+  for (const pair of propPairs ?? []) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) {
+      ctx.out.fail(`--prop must be key=value, got: ${pair}`);
+    }
+    const key = pair.slice(0, eq).trim();
+    if (key === "") {
+      ctx.out.fail(`--prop key cannot be empty, got: ${pair}`);
+    }
+    out[key] = coerceValue(pair.slice(eq + 1));
+    any = true;
+  }
+
+  return any ? out : undefined;
+}
+
+/** JSON-parse a flag value, falling back to the raw string. */
+function coerceValue(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function statusColor(status: SendResponse["status"]): string {
+  switch (status) {
+    case "sent":
+      return color.green(status);
+    case "queued":
+    case "sending":
+      return color.cyan(status);
+    default:
+      // failed
+      return color.red(status);
+  }
+}
+
+async function runSend(ctx: CommandContext, argv: string[]): Promise<void> {
+  const { values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      list: { type: "string" },
+      bucket: { type: "string" },
+      template: { type: "string" },
+      prop: { type: "string", multiple: true },
+      props: { type: "string" },
+      name: { type: "string" },
+      from: { type: "string" },
+      subject: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  const list = values.list;
+  const bucket = values.bucket;
+  if ((list && bucket) || (!list && !bucket)) {
+    ctx.out.fail("campaigns send requires exactly one of --list or --bucket");
+  }
+
+  const template = values.template;
+  if (!template) {
+    ctx.out.fail(
+      "campaigns send requires --template, e.g. hogsend campaigns send --list newsletter --template welcome",
+    );
+  }
+
+  const props = parseProps(ctx, values.props, values.prop);
+
+  const body: {
+    template: string;
+    list?: string;
+    bucket?: string;
+    props?: Record<string, unknown>;
+    name?: string;
+    from?: string;
+    subject?: string;
+  } = { template };
+  if (list) body.list = list;
+  if (bucket) body.bucket = bucket;
+  if (props) body.props = props;
+  if (values.name) body.name = values.name;
+  if (values.from) body.from = values.from;
+  if (values.subject) body.subject = values.subject;
+
+  let res: SendResponse;
+  try {
+    res = await ctx.out.step(`Queuing campaign ${template}`, () =>
+      ctx.dataHttp.post<SendResponse>("/v1/campaigns", body),
+    );
+  } catch (error) {
+    if (isHttpError(error)) {
+      ctx.out.fail(error.message);
+    }
+    throw error;
+  }
+
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+
+  ctx.out.intro(`${badge} send`);
+  ctx.out.kv(
+    {
+      campaignId: res.campaignId,
+      template,
+      audience: list ? `list:${list}` : `bucket:${bucket}`,
+      status: statusColor(res.status),
+    },
+    "Campaign queued",
+  );
+  ctx.out.outro(
+    `${color.green("Queued")} — poll ${color.cyan(`hogsend campaigns status ${res.campaignId}`)} for progress.`,
+  );
+}
+
+async function runStatus(ctx: CommandContext, argv: string[]): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  const id = positionals[0];
+  if (!id) {
+    ctx.out.fail(
+      "campaigns status requires a campaign id, e.g. hogsend campaigns status cmp_123",
+    );
+  }
+
+  let res: StatusResponse;
+  try {
+    res = await ctx.out.step(`Fetching campaign ${id}`, () =>
+      ctx.dataHttp.get<StatusResponse>(
+        `/v1/campaigns/${encodeURIComponent(id)}`,
+      ),
+    );
+  } catch (error) {
+    if (isHttpError(error)) {
+      ctx.out.fail(error.message);
+    }
+    throw error;
+  }
+
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+
+  ctx.out.intro(`${badge} status`);
+  ctx.out.kv(
+    {
+      id: res.id,
+      name: res.name,
+      status: statusColor(res.status),
+      audience: `${res.audienceKind}:${res.audienceId}`,
+      template: res.templateKey,
+      recipients: res.totalRecipients,
+      sent: color.green(String(res.sentCount)),
+      skipped: color.yellow(String(res.skippedCount)),
+      failed:
+        res.failedCount > 0
+          ? color.red(String(res.failedCount))
+          : String(res.failedCount),
+      startedAt: res.startedAt ?? "",
+      completedAt: res.completedAt ?? "",
+    },
+    "Campaign",
+  );
+  ctx.out.outro(
+    `${res.name} → ${statusColor(res.status)} ` +
+      color.dim(
+        `(${res.sentCount}/${res.totalRecipients} sent, ${res.skippedCount} skipped, ${res.failedCount} failed)`,
+      ),
+  );
+}
+
+async function run(ctx: CommandContext): Promise<void> {
+  const sub = ctx.argv[0];
+
+  switch (sub) {
+    case "send":
+      // Strip the leading "send" token; the rest is send's own args.
+      return runSend(ctx, ctx.argv.slice(1));
+    case "status":
+      return runStatus(ctx, ctx.argv.slice(1));
+    case undefined:
+      ctx.out.fail(
+        "campaigns requires a subcommand: send | status (see hogsend campaigns --help)",
+      );
+      break;
+    default:
+      ctx.out.fail(
+        `unknown campaigns subcommand "${sub}" — expected send or status`,
+      );
+  }
+}
+
+export const campaignsCommand: Command = {
+  name: "campaigns",
+  summary: "Queue a broadcast to a list/bucket, or check its status",
+  usage,
+  run,
+};