@hogsend/cli 0.2.3 → 0.7.0

package/src/commands/events.ts

@@ -4,26 +4,51 @@ import { color } from "../lib/output.js";
 import type { Command, CommandContext } from "./types.js";
 
 const usage = `hogsend events <userId> [options]
+hogsend events send <name> [options]
 
-Stream the event history for a single user, newest first. Wraps
-GET /v1/admin/events?userId=<userId>.
+Read a single user's event history (admin API), or send an event into the data
+plane to drive journeys/buckets.
 
-Arguments:
-  <userId>            The user (distinct) id to fetch events for. Required.
+Read mode — hogsend events <userId>:
+  Stream the event history for a single user, newest first. Wraps
+  GET /v1/admin/events?userId=<userId>.
 
-Options:
-  --event <name>      Filter to a single event name.
-  --from <iso>        Only events at/after this ISO-8601 timestamp.
-  --to <iso>          Only events at/before this ISO-8601 timestamp.
-  --limit <n>         Max events to return (1-100, default 50).
-  --offset <n>        Pagination offset (default 0).
-  --json              Emit machine-readable JSON only.
-  -h, --help          Show this help.
+  Arguments:
+    <userId>          The user (distinct) id to fetch events for. Required.
+
+  Options:
+    --event <name>    Filter to a single event name.
+    --from <iso>      Only events at/after this ISO-8601 timestamp.
+    --to <iso>        Only events at/before this ISO-8601 timestamp.
+    --limit <n>       Max events to return (1-100, default 50).
+    --offset <n>      Pagination offset (default 0).
+
+Send mode — hogsend events send <name>:
+  Push an event into POST /v1/events (data plane, ingest key). At least one of
+  --email / --user-id is required.
+
+  Options:
+    --email <addr>          Recipient/identity email.
+    --user-id <id>          External (distinct) id.
+    --prop <key=value>      Event property; repeatable. Value parsed as JSON,
+                            falling back to a string.
+    --props <json>          Event properties as one JSON object.
+    --contact-prop <k=v>    Contact property to merge onto the contact; repeatable.
+    --contact-props <json>  Contact properties as one JSON object.
+    --list <id>             Subscribe to a list; repeatable.
+    --unlist <id>           Unsubscribe from a list; repeatable.
+    --idempotency-key <k>   Dedup key (sent as the Idempotency-Key header).
+    --timestamp <iso>       Override the event timestamp.
+
+Global options (handled by the router): --url, --admin-key, --data-key, --json,
+-h/--help.
 
 Examples:
   hogsend events user_123
   hogsend events user_123 --event signup --limit 10
-  hogsend events user_123 --from 2026-01-01T00:00:00Z --json`;
+  hogsend events user_123 --from 2026-01-01T00:00:00Z --json
+  hogsend events send signup --user-id user_123 --prop plan=pro
+  hogsend events send purchase --email a@b.com --props '{"amount":49}' --json`;
 
 interface UserEvent {
   id: string;
@@ -40,9 +65,31 @@ interface EventsResponse {
   offset: number;
 }
 
+/** Shape returned by POST /v1/events. */
+interface ExitResult {
+  journeyId: string;
+  stateId: string;
+  exited: boolean;
+}
+
+interface SendResponse {
+  stored: boolean;
+  exits: ExitResult[];
+}
+
 async function run(ctx: CommandContext): Promise<void> {
+  // `events send <name>` is the write path; everything else is the read path
+  // (bare `events <userId>`). Dispatch on the first positional WITHOUT a global
+  // --help short-circuit here, so `events send --help` still shows usage.
+  if (ctx.argv[0] === "send") {
+    return runSend(ctx, ctx.argv.slice(1));
+  }
+  return runRead(ctx, ctx.argv);
+}
+
+async function runRead(ctx: CommandContext, argv: string[]): Promise<void> {
   const { values, positionals } = parseArgs({
-    args: ctx.argv,
+    args: argv,
     allowPositionals: true,
     options: {
       event: { type: "string" },
@@ -120,6 +167,197 @@ async function run(ctx: CommandContext): Promise<void> {
   );
 }
 
+async function runSend(ctx: CommandContext, argv: string[]): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      email: { type: "string" },
+      "user-id": { type: "string" },
+      prop: { type: "string", multiple: true },
+      props: { type: "string" },
+      "contact-prop": { type: "string", multiple: true },
+      "contact-props": { type: "string" },
+      list: { type: "string", multiple: true },
+      unlist: { type: "string", multiple: true },
+      "idempotency-key": { type: "string" },
+      timestamp: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  // positionals[0] is the event name (the "send" token was already stripped).
+  const name = positionals[0];
+  if (!name) {
+    ctx.out.fail(
+      "events send requires an event name, e.g. hogsend events send signup --user-id user_123",
+    );
+  }
+
+  const email = values.email;
+  const userId = values["user-id"];
+  if (!email && !userId) {
+    ctx.out.fail("events send requires at least one of --email or --user-id");
+  }
+
+  const eventProperties = parseProps(ctx, values.props, values.prop, "prop");
+  const contactProperties = parseProps(
+    ctx,
+    values["contact-props"],
+    values["contact-prop"],
+    "contact-prop",
+  );
+  const lists = parseLists(values.list, values.unlist);
+
+  const body: {
+    name: string;
+    email?: string;
+    userId?: string;
+    eventProperties?: Record<string, unknown>;
+    contactProperties?: Record<string, unknown>;
+    lists?: Record<string, boolean>;
+    idempotencyKey?: string;
+    timestamp?: string;
+  } = { name };
+  if (email) body.email = email;
+  if (userId) body.userId = userId;
+  if (eventProperties) body.eventProperties = eventProperties;
+  if (contactProperties) body.contactProperties = contactProperties;
+  if (lists) body.lists = lists;
+  if (values["idempotency-key"]) {
+    body.idempotencyKey = values["idempotency-key"];
+  }
+  if (values.timestamp) body.timestamp = values.timestamp;
+
+  let res: SendResponse;
+  try {
+    res = await ctx.out.step(`Sending event ${name}`, () =>
+      ctx.dataHttp.post<SendResponse>("/v1/events", body),
+    );
+  } catch (error) {
+    if (isHttpError(error)) {
+      ctx.out.fail(error.message);
+    }
+    throw error;
+  }
+
+  if (ctx.json) {
+    ctx.out.json(res);
+    return;
+  }
+
+  ctx.out.intro(`${color.bgMagenta(color.black(" hogsend "))} events send`);
+
+  const exited = res.exits.filter((e) => e.exited);
+  ctx.out.kv(
+    {
+      event: name,
+      stored: res.stored,
+      identity: email ?? userId ?? "",
+      exits: res.exits.length,
+      "journeys exited": exited.length,
+    },
+    "Event sent",
+  );
+
+  if (exited.length > 0) {
+    ctx.out.table(
+      exited.map((e) => ({ journeyId: e.journeyId, stateId: e.stateId })),
+      ["journeyId", "stateId"],
+    );
+  }
+
+  ctx.out.outro(
+    res.stored
+      ? `${color.green("Stored")} ${name}.`
+      : color.dim(`${name} was deduped (not stored).`),
+  );
+}
+
+/**
+ * Parse `--<flag> key=value` (repeatable) + an optional `--<flag>s <json>`
+ * object into a single properties record. Each value is JSON-parsed when valid
+ * JSON, else kept as a string. The JSON object is applied first so later
+ * key=value flags win. `flagName` is used only for error messages.
+ */
+function parseProps(
+  ctx: CommandContext,
+  json: string | undefined,
+  pairs: string[] | undefined,
+  flagName: string,
+): Record<string, unknown> | undefined {
+  const out: Record<string, unknown> = {};
+  let any = false;
+
+  if (json !== undefined) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(json);
+    } catch {
+      ctx.out.fail(`--${flagName}s must be valid JSON, got: ${json}`);
+    }
+    if (
+      parsed === null ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed)
+    ) {
+      ctx.out.fail(`--${flagName}s must be a JSON object`);
+    }
+    Object.assign(out, parsed as Record<string, unknown>);
+    any = true;
+  }
+
+  for (const pair of pairs ?? []) {
+    const eq = pair.indexOf("=");
+    if (eq === -1) {
+      ctx.out.fail(`--${flagName} must be key=value, got: ${pair}`);
+    }
+    const key = pair.slice(0, eq).trim();
+    if (key === "") {
+      ctx.out.fail(`--${flagName} 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;
+  }
+}
+
+/**
+ * Build a `lists` map from repeatable `--list <id>` (true) / `--unlist <id>`
+ * (false) flags. Returns undefined when neither was passed.
+ */
+function parseLists(
+  subscribe: string[] | undefined,
+  unsubscribe: string[] | undefined,
+): Record<string, boolean> | undefined {
+  const out: Record<string, boolean> = {};
+  let any = false;
+  for (const id of subscribe ?? []) {
+    out[id] = true;
+    any = true;
+  }
+  for (const id of unsubscribe ?? []) {
+    out[id] = false;
+    any = true;
+  }
+  return any ? out : undefined;
+}
+
 /**
  * Parse an optional numeric flag. Returns undefined when absent (lets the
  * server apply its default); fails on a non-numeric value.
@@ -148,7 +386,7 @@ function summarizeProps(props: Record<string, unknown> | null): string {
 
 export const eventsCommand: Command = {
   name: "events",
-  summary: "Stream a single user's event history",
+  summary: "Stream a user's event history, or send an event",
   usage,
   run,
 };

package/src/commands/index.ts

@@ -1,6 +1,8 @@
+import { campaignsCommand } from "./campaigns.js";
 import { contactsCommand } from "./contacts.js";
 import { doctorCommand } from "./doctor.js";
 import { ejectCommand } from "./eject.js";
+import { emailsCommand } from "./emails.js";
 import { eventsCommand } from "./events.js";
 import { journeysCommand } from "./journeys.js";
 import { patchCommand } from "./patch.js";
@@ -25,6 +27,8 @@ export const commands: Command[] = [
   contactsCommand,
   statsCommand,
   eventsCommand,
+  emailsCommand,
+  campaignsCommand,
   studioCommand,
   setupCommand,
   skillsCommand,

package/src/commands/types.ts

@@ -1,5 +1,5 @@
 import type { ResolvedConfig } from "../lib/config.js";
-import type { AdminClient } from "../lib/http.js";
+import type { AdminClient, DataPlaneClient } from "../lib/http.js";
 import type { Output } from "../lib/output.js";
 
 /**
@@ -17,8 +17,14 @@ export interface CommandContext {
   argv: string[];
   /** Base URL + admin key, already resolved via flags > env > .env. */
   cfg: ResolvedConfig;
-  /** Pre-built admin HTTP client, bound to `cfg`. */
+  /** Pre-built admin HTTP client, bound to `cfg` (admin key). */
   http: AdminClient;
+  /**
+   * Pre-built data-plane HTTP client, bound to `cfg.dataKey` (ingest key). Used
+   * by the write commands (`contacts upsert`, `events send`, `emails send`)
+   * that hit the authed `/v1/contacts`, `/v1/events`, `/v1/emails` routes.
+   */
+  dataHttp: DataPlaneClient;
   /** Output sink — human (TTY clack) vs json, already mode-selected. */
   out: Output;
   /** True when the global `--json` flag was passed. Mirrors `out.isJson`. */

package/src/lib/config.ts

@@ -8,12 +8,19 @@ export interface ResolvedConfig {
   baseUrl: string;
   /** Admin bearer token, if resolvable. `doctor`/health works without it. */
   adminKey: string | undefined;
+  /**
+   * Data-plane bearer token (an `ingest`-scoped key), if resolvable. Used by the
+   * write commands (`contacts upsert`, `events send`, `emails send`). Falls back
+   * to the admin key since `full-admin` implies `ingest`.
+   */
+  dataKey: string | undefined;
 }
 
 /** Global flags parsed off the front of any command's argv. */
 export interface GlobalFlags {
   url?: string;
   adminKey?: string;
+  dataKey?: string;
   json: boolean;
   help: boolean;
   /** The remaining args after global flags are stripped. */
@@ -39,6 +46,7 @@ export function parseGlobalFlags(argv: string[]): GlobalFlags {
     options: {
       url: { type: "string" },
       "admin-key": { type: "string" },
+      "data-key": { type: "string" },
       json: { type: "boolean", default: false },
       help: { type: "boolean", short: "h", default: false },
     },
@@ -47,7 +55,7 @@ export function parseGlobalFlags(argv: string[]): GlobalFlags {
   // Rebuild `rest` from the token stream, dropping only the global flags we
   // own (and their values). Everything else — positionals and unknown option
   // tokens — is preserved verbatim for the command's own parser.
-  const owned = new Set(["url", "admin-key", "json", "help", "h"]);
+  const owned = new Set(["url", "admin-key", "data-key", "json", "help", "h"]);
   const rest: string[] = [];
   for (const token of tokens) {
     if (token.kind === "positional") {
@@ -68,6 +76,8 @@ export function parseGlobalFlags(argv: string[]): GlobalFlags {
     url: typeof values.url === "string" ? values.url : undefined,
     adminKey:
       typeof values["admin-key"] === "string" ? values["admin-key"] : undefined,
+    dataKey:
+      typeof values["data-key"] === "string" ? values["data-key"] : undefined,
     json: values.json === true,
     help: values.help === true,
     rest,
@@ -120,6 +130,7 @@ export function loadDotEnv(
  *
  *   baseUrl: --url > HOGSEND_API_URL (env) > HOGSEND_API_URL (.env) > localhost:3002
  *   adminKey: --admin-key > HOGSEND_ADMIN_KEY|ADMIN_API_KEY (env) > (.env equiv)
+ *   dataKey: --data-key > HOGSEND_DATA_KEY > HOGSEND_API_KEY (env then .env)
  */
 export function resolveConfig(
   flags: GlobalFlags,
@@ -140,8 +151,19 @@ export function resolveConfig(
     dotenv.HOGSEND_ADMIN_KEY ??
     dotenv.ADMIN_API_KEY;
 
+  // Data-plane (ingest-scoped) key. Precedence is independent of adminKey:
+  // explicit data key first, then a dedicated env/.env var, then the generic
+  // HOGSEND_API_KEY (which a fresh scaffold mints as an ingest key).
+  const dataKey =
+    flags.dataKey ??
+    process.env.HOGSEND_DATA_KEY ??
+    process.env.HOGSEND_API_KEY ??
+    dotenv.HOGSEND_DATA_KEY ??
+    dotenv.HOGSEND_API_KEY;
+
   return {
     baseUrl: baseUrlRaw.replace(/\/+$/, ""),
     adminKey: adminKey && adminKey.length > 0 ? adminKey : undefined,
+    dataKey: dataKey && dataKey.length > 0 ? dataKey : undefined,
   };
 }

package/src/lib/http.ts

@@ -77,68 +77,141 @@ function bodyMessage(status: number, body: unknown): string {
   return `request failed with status ${status}`;
 }
 
-/** Build an {@link AdminClient} bound to the given resolved config. */
-export function createAdminClient(cfg: ResolvedConfig): AdminClient {
-  async function request<T>(
-    method: string,
-    path: string,
-    opts: { query?: Query; body?: unknown; auth: boolean },
-  ): Promise<T> {
-    if (opts.auth && !cfg.adminKey) {
-      throw makeHttpError(
-        "no admin key configured — pass --admin-key, or set HOGSEND_ADMIN_KEY / ADMIN_API_KEY",
-        0,
-        undefined,
-      );
-    }
-
-    const headers: Record<string, string> = { Accept: "application/json" };
-    if (opts.auth && cfg.adminKey) {
-      headers.Authorization = `Bearer ${cfg.adminKey}`;
-    }
-    if (opts.body !== undefined) {
-      headers["Content-Type"] = "application/json";
-    }
+/** Internal options accepted by the shared {@link request} core. */
+interface RequestOpts {
+  query?: Query;
+  body?: unknown;
+  /** When false, no Authorization header is sent (e.g. /v1/health). */
+  auth: boolean;
+}
 
-    const url = buildUrl(cfg.baseUrl, path, opts.query);
+/**
+ * The single HTTP core, shared by the admin client and the data-plane client.
+ * Bound to a `baseUrl` + a bearer `key`; the only difference between the two
+ * clients is which key (and which "missing key" message) they carry. Sends
+ * `Authorization: Bearer <key>` when `auth` is set, parses JSON, and throws an
+ * {@link HttpError} on any non-2xx response (or transport failure).
+ */
+async function request<T>(
+  baseUrl: string,
+  key: string | undefined,
+  missingKeyMessage: string,
+  method: string,
+  path: string,
+  opts: RequestOpts,
+): Promise<T> {
+  if (opts.auth && !key) {
+    throw makeHttpError(missingKeyMessage, 0, undefined);
+  }
 
-    let res: Response;
-    try {
-      res = await fetch(url, {
-        method,
-        headers,
-        body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-      });
-    } catch (cause) {
-      const msg = cause instanceof Error ? cause.message : String(cause);
-      throw makeHttpError(`cannot reach ${cfg.baseUrl} (${msg})`, 0, undefined);
-    }
+  const headers: Record<string, string> = { Accept: "application/json" };
+  if (opts.auth && key) {
+    headers.Authorization = `Bearer ${key}`;
+  }
+  if (opts.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+  }
 
-    const text = await res.text();
-    let parsed: unknown;
-    if (text.length > 0) {
-      try {
-        parsed = JSON.parse(text);
-      } catch {
-        parsed = text;
-      }
-    }
+  const url = buildUrl(baseUrl, path, opts.query);
+
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method,
+      headers,
+      body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+    });
+  } catch (cause) {
+    const msg = cause instanceof Error ? cause.message : String(cause);
+    throw makeHttpError(`cannot reach ${baseUrl} (${msg})`, 0, undefined);
+  }
 
-    if (!res.ok) {
-      throw makeHttpError(bodyMessage(res.status, parsed), res.status, parsed);
+  const text = await res.text();
+  let parsed: unknown;
+  if (text.length > 0) {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      parsed = text;
     }
+  }
 
-    return parsed as T;
+  if (!res.ok) {
+    throw makeHttpError(bodyMessage(res.status, parsed), res.status, parsed);
   }
 
+  return parsed as T;
+}
+
+/** Build an {@link AdminClient} bound to the given resolved config. */
+export function createAdminClient(cfg: ResolvedConfig): AdminClient {
+  const missing =
+    "no admin key configured — pass --admin-key, or set HOGSEND_ADMIN_KEY / ADMIN_API_KEY";
   return {
     cfg,
     get: <T>(path: string, query?: Query, extras?: RequestExtras) =>
-      request<T>("GET", path, { query, auth: extras?.auth ?? true }),
+      request<T>(cfg.baseUrl, cfg.adminKey, missing, "GET", path, {
+        query,
+        auth: extras?.auth ?? true,
+      }),
     patch: <T>(path: string, body: unknown) =>
-      request<T>("PATCH", path, { body, auth: true }),
+      request<T>(cfg.baseUrl, cfg.adminKey, missing, "PATCH", path, {
+        body,
+        auth: true,
+      }),
+    post: <T>(path: string, body: unknown) =>
+      request<T>(cfg.baseUrl, cfg.adminKey, missing, "POST", path, {
+        body,
+        auth: true,
+      }),
+  };
+}
+
+/**
+ * Thin data-plane HTTP client over the same core as {@link createAdminClient},
+ * but bound to `cfg.dataKey` (an `ingest`-scoped key). Used by the write
+ * commands (`contacts upsert`, `events send`, `emails send`) which hit the
+ * authed `/v1/contacts`, `/v1/events`, and `/v1/emails` data-plane routes.
+ *
+ * Exposes the full read/write verb set the data plane needs: `get`/`post`/
+ * `put`/`del`. Every call is authenticated (there is no unauthenticated
+ * data-plane route), so there is no `{ auth: false }` escape hatch here.
+ */
+export interface DataPlaneClient {
+  get<T = unknown>(path: string, query?: Query): Promise<T>;
+  post<T = unknown>(path: string, body: unknown): Promise<T>;
+  put<T = unknown>(path: string, body: unknown): Promise<T>;
+  del<T = unknown>(path: string, body?: unknown): Promise<T>;
+  /** The resolved config this client is bound to (for messages/JSON output). */
+  readonly cfg: ResolvedConfig;
+}
+
+/** Build a {@link DataPlaneClient} bound to `cfg.dataKey`. */
+export function createDataPlaneClient(cfg: ResolvedConfig): DataPlaneClient {
+  const missing =
+    "no data key configured — pass --data-key, or set HOGSEND_DATA_KEY / HOGSEND_API_KEY";
+  return {
+    cfg,
+    get: <T>(path: string, query?: Query) =>
+      request<T>(cfg.baseUrl, cfg.dataKey, missing, "GET", path, {
+        query,
+        auth: true,
+      }),
     post: <T>(path: string, body: unknown) =>
-      request<T>("POST", path, { body, auth: true }),
+      request<T>(cfg.baseUrl, cfg.dataKey, missing, "POST", path, {
+        body,
+        auth: true,
+      }),
+    put: <T>(path: string, body: unknown) =>
+      request<T>(cfg.baseUrl, cfg.dataKey, missing, "PUT", path, {
+        body,
+        auth: true,
+      }),
+    del: <T>(path: string, body?: unknown) =>
+      request<T>(cfg.baseUrl, cfg.dataKey, missing, "DELETE", path, {
+        body,
+        auth: true,
+      }),
   };
 }