@hogsend/cli 0.17.1 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/cli",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -34,7 +34,7 @@
     "tsup": "^8.5.1",
     "tsx": "^4.22.4",
     "vitest": "^4.1.7",
-    "@hogsend/studio": "^0.17.1",
+    "@hogsend/studio": "^0.19.0",
     "@repo/typescript-config": "0.0.0"
   },
   "engines": {
@@ -44,8 +44,8 @@
     "@clack/prompts": "^1.5.0",
     "better-auth": "^1.6.11",
     "picocolors": "^1.1.1",
-    "@hogsend/db": "^0.17.1",
-    "@hogsend/engine": "^0.17.1"
+    "@hogsend/db": "^0.19.0",
+    "@hogsend/engine": "^0.19.0"
   },
   "scripts": {
     "prebuild": "node scripts/bundle-studio.mjs",

package/skills/hogsend-authoring-journeys/references/journey-context.md

@@ -149,7 +149,10 @@ orchestration:
 - **`getPostHog()`** — `import { getPostHog } from "@hogsend/engine"` for the raw
   PostHog service (a fire-and-forget escape hatch). For fanning lifecycle data out
   to product/data tools, prefer an outbound DESTINATION (see above) — it delivers
-  durably and is vendor-neutral.
+  durably and is vendor-neutral. Note: capture and `$set` person WRITES use the
+  `phc_` project key; person READS (`getPersonProperties`) additionally need
+  `POSTHOG_PERSONAL_API_KEY` (the project key is write-only by PostHog's design)
+  and soft-fail to `{}` without it.
 - **SMS / push / Slack** — plain functions you import, never on `ctx`.
 - There is **no `ctx.db`, no `ctx.sendEmail`, no `ctx.hatchet`** surfaced to
   consumer journeys. If you reach for one of those, you are modelling it wrong —

package/skills/hogsend-client-sdk/SKILL.md

@@ -89,7 +89,7 @@ await hs.events.send({                          // POST /v1/events
   eventProperties: { source: "landing" },       // stored ON the event
   contactProperties: { country: "GB" },         // merged onto the CONTACT
   idempotencyKey: "evt_abc",
-});                                              // -> { stored, exits, listsError? }
+});                                              // -> { stored, exits, contactKey?, listsError? }
 hs.events.track(/* … */);                       // alias of events.send
 
 // Emails ------------------------------------------------------------------
@@ -185,13 +185,17 @@ same split is exposed by the CLI as `--prop` (event) vs `--contact-prop`
 ## The 202 + `listsError` warning
 
 `POST /v1/events` returns **202 Accepted** (the event is durably stored and
-queued for routing), NOT 200. The result is `{ stored, exits }` plus an optional
-`listsError`:
+queued for routing), NOT 200. The result is `{ stored, exits, contactKey }`
+plus an optional `listsError`:
 
 - `stored` — `true` once the event row is written (`false` only on a dedup via
   `idempotencyKey`).
 - `exits` — the `{ journeyId, stateId, exited }[]` from evaluating active
   journeys' `exitOn` rules for this user.
+- `contactKey` — the contact's canonical key (engine ≥0.18): the same key
+  outbound destinations emit as `userId` and `hs_t` identity tokens resolve
+  to. Hand it to your analytics `identify()` to join the session to the
+  contact's person — it carries no PII.
 - **`listsError?`** — present ONLY when the event was ingested fine but the
   (non-atomic, post-ingest) `lists` membership write failed. **The event itself
   is durably stored** — this is a soft warning surfaced on the 202, not a 400.

package/skills/hogsend-deploy/references/env-and-secrets.md

@@ -73,10 +73,19 @@ dashboard at `http://localhost:8888`, login `admin@example.com` / `Admin123!!`.)
 All commented-out in `.env.example` — add only what you use:
 
 ```bash
-# PostHog person properties + event capture (no-op if unset).
+# PostHog event capture + person property WRITES (no-op if unset).
 POSTHOG_API_KEY=phc_...
 POSTHOG_HOST=https://us.i.posthog.com
 
+# PostHog person property READS (timezone resolution, property conditions).
+# The phc_ key is write-only by PostHog's design — reads need a PERSONAL API
+# key scoped person:read. Without it reads soft-fail to contact properties.
+POSTHOG_PERSONAL_API_KEY=...
+# Project id for the private API — discovered automatically when unset.
+# POSTHOG_PROJECT_ID=12345
+# Private API host — derived (eu.i.posthog.com → eu.posthog.com) when unset.
+# POSTHOG_PRIVATE_HOST=https://us.posthog.com
+
 # Verify incoming PostHog webhooks (POST /v1/webhooks/posthog).
 POSTHOG_WEBHOOK_SECRET=...
 
@@ -92,6 +101,12 @@ Notes:
 
 - **PostHog is fully optional.** Without `POSTHOG_API_KEY`, person-property
   fetches and event captures are no-ops — journeys still run.
+- **Two PostHog credentials, by PostHog's design.** The `phc_` project key is
+  public (it ships in browser bundles) so PostHog makes it WRITE-only: capture
+  and `$set` person writes work, reads never will. Person READS (per-user
+  timezone resolution) need `POSTHOG_PERSONAL_API_KEY` — a personal API key
+  scoped `person:read`, created in PostHog → Settings → Personal API keys.
+  `hogsend doctor` warns when capture is configured without it.
 - **Webhook secrets are per-source.** Only set the secret for a webhook source
   you've actually registered (see the consumer's `src/webhook-sources`).
 - **`ADMIN_API_KEY` gates `/v1/admin/*`.** Set it in prod if you want to drive

package/src/commands/doctor.ts

@@ -1,4 +1,5 @@
 import { parseArgs } from "node:util";
+import { loadDotEnv } from "../lib/config.js";
 import { isHttpError } from "../lib/http.js";
 import { color } from "../lib/output.js";
 import { skillsStaleness } from "../lib/skills.js";
@@ -22,6 +23,34 @@ function skillsNudge(ctx: CommandContext): void {
   );
 }
 
+/**
+ * Best-effort nudge: PostHog capture configured (`POSTHOG_API_KEY` in the
+ * cwd's `.env` or process env) without `POSTHOG_PERSONAL_API_KEY` means
+ * person READS are silently disabled — the phc_ project key is write-only by
+ * PostHog's design, so timezone resolution falls back to contact properties.
+ * Warn-not-fail: capture and person writes still work.
+ */
+function analyticsNudge(ctx: CommandContext): void {
+  if (ctx.json) return;
+  const dotenv = loadDotEnv(process.cwd());
+  const captureKey = process.env.POSTHOG_API_KEY ?? dotenv.POSTHOG_API_KEY;
+  const personalKey =
+    process.env.POSTHOG_PERSONAL_API_KEY ?? dotenv.POSTHOG_PERSONAL_API_KEY;
+  if (!captureKey || personalKey) return;
+  ctx.out.note(
+    [
+      "POSTHOG_API_KEY is set without POSTHOG_PERSONAL_API_KEY — person",
+      "property READS are disabled (the phc_ project key is write-only by",
+      "PostHog's design), so per-user timezone resolution falls back to",
+      "contact properties. Capture and person WRITES are unaffected.",
+      "",
+      `Fix: create a personal API key scoped ${color.cyan("person:read")} and set ${color.cyan("POSTHOG_PERSONAL_API_KEY")}.`,
+      `Docs: ${color.cyan("https://hogsend.com/docs/guides/analytics-access")}`,
+    ].join("\n"),
+    "PostHog person reads disabled",
+  );
+}
+
 const usage = `hogsend doctor [--url <baseUrl>] [--admin-key <key>] [--json]
 
 Probe a running Hogsend instance via GET /v1/health and report its health:
@@ -221,6 +250,7 @@ async function run(ctx: CommandContext): Promise<void> {
   ctx.out.note(lines.join("\n"), "Doctor");
 
   skillsNudge(ctx);
+  analyticsNudge(ctx);
 
   if (ok) {
     ctx.out.outro(color.green("doctor: ok"));