zeno-cli 0.3.4__py3-none-any.whl

zeno_cli/interview_invites.py

@@ -0,0 +1,342 @@
+"""Waitlist-driven interview-invite outreach.
+
+Placeholder waitlist source: a CSV with the same shape the
+/api/waitlist Vercel function sends to the Zeno API (email, role,
+intent, why, plus an optional first_name and signed_up_at column the
+operator may have hand-edited). The CSV path is passed on the CLI -
+when a real waitlist DB lands, this module gains a `load_signups_db`
+function and the CLI gets a `--source db` switch; the renderer + send
+loop stay unchanged.
+
+Architectural notes:
+
+* Sibling of `outreach.py` (rolodex sends) not a merge: rolodex
+  contacts are *outbound prospects* with a relationship score and
+  tags, waitlist signups are *inbound leads* with an intent and an
+  optional why. The selection criteria differ; keeping the modules
+  separate means changes to one do not regress the other.
+
+* The bunmail wire format and the safety contract (confirmed=True
+  required, dry-run prints first-mail preview) match outreach.py so
+  the operator's muscle memory carries between commands.
+
+* `render_signup_context` is the personal-hook analogue here: it
+  turns the `intent` + `why` fields into one sentence that justifies
+  the cold-but-not-really invite mail. When neither field is present
+  we fall back to a generic but honest line.
+"""
+
+from __future__ import annotations
+
+import csv
+import time
+import urllib.error
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta
+from pathlib import Path
+
+from .outreach import (
+    DEFAULT_SEND_PAUSE_SECS,
+    OutreachError,
+    SendOutcome,
+    send_one,
+)
+from .outreach import (
+    Contact as RolodexContact,
+)
+
+# Hard ceiling on a single run. The CLI default --max is 10 (per the
+# product spec) and this is the absolute backstop against an
+# accidentally-large blast.
+HARD_MAX_INVITES = 50
+
+
+@dataclass(frozen=True)
+class WaitlistSignup:
+    """One row of the waitlist export CSV, narrowed to fields the
+    invite renderer uses.
+
+    `first_name` is optional - the rolodex carries it but the waitlist
+    form on /index.html does not collect it yet, so the renderer falls
+    back to "there" when blank. `signed_up_at` is parsed as a date
+    when present; missing means "no recency filter applied".
+    """
+
+    email: str
+    first_name: str
+    role: str
+    intent: str  # pro_trial / research_updates / both
+    why: str
+    signed_up_at: date | None
+
+
+# ---------------------------------------------------------------------------
+# CSV ingestion
+# ---------------------------------------------------------------------------
+
+
+def load_signups_csv(path: str | Path) -> list[WaitlistSignup]:
+    """Load + normalize a waitlist export CSV.
+
+    Expected columns (extra columns ignored, missing columns treated
+    as blank):
+      - email         REQUIRED. Row dropped if missing or empty.
+      - first_name    optional. Falls back to "" -> "there" at render.
+      - role          optional. Pass-through for the operator's notes.
+      - intent        optional. One of pro_trial / research_updates /
+                      both; renderer accepts any value but recognised
+                      intents trigger a more specific signup_context.
+      - why           optional. Free-text from the signup form.
+      - signed_up_at  optional. YYYY-MM-DD. Enables --only-since N.
+    """
+    path = Path(path)
+    out: list[WaitlistSignup] = []
+    with path.open("r", encoding="utf-8", newline="") as fh:
+        reader = csv.DictReader(fh)
+        for row in reader:
+            email = (row.get("email") or "").strip()
+            if not email:
+                continue
+            out.append(
+                WaitlistSignup(
+                    email=email,
+                    first_name=(row.get("first_name") or "").strip(),
+                    role=(row.get("role") or "").strip(),
+                    intent=(row.get("intent") or "").strip().lower(),
+                    why=(row.get("why") or "").strip(),
+                    signed_up_at=_parse_date(row.get("signed_up_at")),
+                )
+            )
+    return out
+
+
+def _parse_date(raw: str | None) -> date | None:
+    if not raw:
+        return None
+    raw = raw.strip()
+    if not raw:
+        return None
+    try:
+        return datetime.strptime(raw, "%Y-%m-%d").date()
+    except ValueError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Filtering
+# ---------------------------------------------------------------------------
+
+
+def filter_signups(
+    signups: list[WaitlistSignup],
+    *,
+    suppression: set[str] | None = None,
+    only_since_days: int | None = None,
+    today: date | None = None,
+) -> list[WaitlistSignup]:
+    """Drop suppressed emails + (optionally) signups older than N days.
+
+    Suppression list is shared with rolodex outreach: a unified
+    opt-out registry. The `only_since_days` filter is opt-in because
+    older signups are valid interview candidates - the founder may
+    have a backlog they want to clear.
+
+    Sort order: most recent signup first when dates are present,
+    email A-Z as the tiebreaker. Recency-first means the operator's
+    --max takes the freshest signups, who are most likely to remember
+    why they signed up.
+    """
+    today = today or date.today()
+    suppression = suppression or set()
+
+    out: list[WaitlistSignup] = []
+    for s in signups:
+        if s.email.lower() in suppression:
+            continue
+        if only_since_days is not None and s.signed_up_at is not None:
+            cutoff = today - timedelta(days=only_since_days)
+            if s.signed_up_at < cutoff:
+                continue
+        out.append(s)
+
+    def sort_key(s: WaitlistSignup) -> tuple[int, str]:
+        # Date.max so "no date" sorts AFTER recent dates (less priority).
+        d = s.signed_up_at or date.min
+        # Negate via toordinal() so newer dates rank lower (sort ASC).
+        return (-d.toordinal(), s.email.lower())
+
+    out.sort(key=sort_key)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Personal-context rendering
+# ---------------------------------------------------------------------------
+
+
+def first_name_or_default(signup: WaitlistSignup) -> str:
+    """Return the signup's first name, or "there" as a friendly fallback."""
+    name = signup.first_name.strip()
+    if not name:
+        return "there"
+    return name.split()[0]
+
+
+def render_signup_context(signup: WaitlistSignup) -> str:
+    """One-sentence "why I am mailing you" line for the invite body.
+
+    Priority order:
+      1. They wrote a `why` -> echo their own framing back so they know
+         this is not a form letter.
+      2. They asked for `pro_trial` -> the trial is the closest thing
+         to a yes-prospect we have at the waitlist stage.
+      3. They asked for `research_updates` -> they want depth, not a
+         trial; the call is a fair trade.
+      4. `both` -> the strongest signal of intent on the form.
+      5. Fallback: a generic but honest line - we know you signed up,
+         we want 30 minutes.
+    """
+    why = signup.why.strip()
+    if why:
+        # Quote a truncated form of their `why` back at them. Cap to
+        # the first ~80 chars so the sentence stays mail-friendly even
+        # if they pasted a paragraph in.
+        quoted = why if len(why) <= 80 else why[:77].rstrip() + "..."
+        return (
+            f'You signed up for the Zeno waitlist and wrote: "{quoted}". '
+            "That is exactly the kind of detail I want to dig into."
+        )
+
+    intent = signup.intent.lower()
+    if intent == "pro_trial":
+        return (
+            "You signed up for a Pro trial, which means you have a "
+            "specific use case in mind - I want to hear what it is "
+            "before we ship the next round of invites."
+        )
+    if intent == "research_updates":
+        return (
+            "You opted in for research updates, which puts you in the "
+            "thin slice of people who care how this measurement "
+            "actually works, not just whether the demo looks good."
+        )
+    if intent == "both":
+        return (
+            "You signed up for both the Pro trial and research "
+            "updates, which is the strongest signal on the form - I "
+            "want to make sure what we ship next matches what got you "
+            "to click."
+        )
+
+    return (
+        "You signed up for the Zeno waitlist, and 30 minutes of your "
+        "perspective is more useful than another week of me guessing "
+        "what to build next."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Adapter: WaitlistSignup -> RolodexContact (for reuse of send_one)
+# ---------------------------------------------------------------------------
+
+
+def _signup_to_contact(signup: WaitlistSignup) -> RolodexContact:
+    """Wrap a waitlist signup in a Contact so we can hand it to
+    outreach.send_one() unchanged.
+
+    The Contact carries fields the bunmail send does not need
+    (relationship_score, tier, tags) so we set sensible defaults. The
+    `notes` field carries the original `why` so the run-log audit
+    trail captures intent.
+    """
+    return RolodexContact(
+        person_id=f"waitlist:{signup.email}",
+        full_name=signup.first_name or signup.email,
+        primary_email=signup.email,
+        organization="",
+        role=signup.role,
+        tags=("waitlist",),
+        city="",
+        tier="waitlist",
+        relationship_score=0,
+        last_contact_date=None,
+        notes=signup.why,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Send loop
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class InviteSendConfig:
+    """All the knobs the CLI passes to the send loop, frozen so the
+    function signature stays stable when we add new options.
+    """
+
+    bunmail_base_url: str
+    bunmail_api_key: str
+    sender: str
+    pause_secs: float = DEFAULT_SEND_PAUSE_SECS
+
+
+def send_invites(
+    signups: list[WaitlistSignup],
+    *,
+    render: callable,
+    config: InviteSendConfig,
+) -> tuple[list[SendOutcome], bool]:
+    """Iterate signups, render the invite, send through bunmail.
+
+    Returns (outcomes, aborted). `aborted` is True if bunmail returned
+    a 4xx mid-run (we stop on 4xx because it usually means the API
+    key or sender is wrong and continuing would just rack up failures).
+
+    `render(signup)` is the renderer the caller supplies - decoupled
+    so test code can swap in a stub. The default in the CLI is the
+    customer_interview_invite template registry entry.
+    """
+    outcomes: list[SendOutcome] = []
+    aborted = False
+    n = len(signups)
+    for i, signup in enumerate(signups, start=1):
+        rendered = render(signup)
+        contact = _signup_to_contact(signup)
+        try:
+            outcome = send_one(
+                bunmail_base_url=config.bunmail_base_url,
+                bunmail_api_key=config.bunmail_api_key,
+                sender=config.sender,
+                contact=contact,
+                subject=rendered["subject"],
+                text=rendered["text"],
+                html=rendered.get("html"),
+                confirmed=True,
+            )
+        except OutreachError:
+            # send_one already encodes the bunmail body in the error;
+            # re-raise so the CLI can format it consistently with
+            # rolodex outreach error handling.
+            aborted = True
+            raise
+        except urllib.error.URLError as exc:
+            # Transport-level failures degrade to a logged error row
+            # so the run-log audit trail still records the attempt.
+            outcomes.append(
+                SendOutcome(
+                    email=contact.primary_email,
+                    person_id=contact.person_id,
+                    full_name=contact.full_name,
+                    status="error",
+                    email_id="",
+                    detail=f"transport: {exc.reason}",
+                    sent_at=datetime.now().isoformat(timespec="seconds"),
+                )
+            )
+            continue
+        outcomes.append(outcome)
+        if i < n:
+            time.sleep(config.pause_secs)
+
+    return outcomes, aborted

zeno_cli/login.py

@@ -0,0 +1,241 @@
+"""`zeno login` - browser + loopback authentication for the CLI.
+
+Stdlib only (no extra CLI deps). The flow mirrors the OAuth "loopback
+redirect" pattern that gh / gcloud / fly use for headless-friendly CLI auth:
+
+  1. Bind an ephemeral HTTP server on 127.0.0.1:0 (localhost only).
+  2. Open the browser at the dashboard's `/cli/authorize` bridge page with the
+     loopback port and a CSRF `state` token.
+  3. The bridge runs the Clerk sign-in, mints a `zeno-api`-audience JWT via a
+     Clerk JWT template, and redirects the browser back to
+     `http://127.0.0.1:<port>/callback?state=<state>&token=<clerk_jwt>`.
+  4. The loopback server validates `state`, captures the token, and the CLI
+     stores it in the OS keyring (`zeno_sdk.auth`).
+
+The CLI then sends that JWT as `Authorization: Bearer ...` on API calls, so the
+API attributes requests per Clerk user (RS256 + JWKS verification, see
+apps/api/src/zeno_api/auth.py).
+
+The security control on the callback today is the CSRF `state` token (browser +
+loopback, state-CSRF) - NOT PKCE. The bridge returns the token directly in the
+redirect; there is no authorization-code-for-token exchange, so a PKCE verifier
+would be unused theater. TODO: when the dashboard `/cli/authorize` bridge ships,
+implement a real OAuth code-for-token exchange (PKCE S256: send a code_challenge,
+receive a short-lived auth code on the callback, then POST code + code_verifier
+to the bridge to redeem the JWT) instead of receiving the token in the URL.
+
+OUT OF SCOPE / FOLLOW-UP: the dashboard `/cli/authorize` bridge page and the
+Clerk `zeno-api` JWT template do NOT exist yet. They are the only missing
+pieces for an end-to-end login. This module is fully unit-testable without them
+because `authorize_url` is injectable (env `ZENO_LOGIN_AUTHORIZE_URL`, flag
+`--authorize-url`) and the loopback leg is driven by a fake "browser" in tests.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import secrets
+import time
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlencode, urlparse
+
+from zeno_sdk import auth
+
+# Canonical default for the dashboard CLI-authorize bridge. Injectable so the
+# CLI ships + unit-tests before the bridge page exists. main.py mirrors this
+# default for the argparse default (so the hot `zeno status` path does not
+# import this module just to build the parser).
+DEFAULT_AUTHORIZE_URL = os.environ.get(
+    "ZENO_LOGIN_AUTHORIZE_URL", "https://app.zeno.center/cli/authorize"
+)
+
+
+class LoginError(Exception):
+    """Raised when the loopback login flow fails (timeout, CSRF, no token)."""
+
+
+def _new_state() -> str:
+    """Fresh CSRF state token. Split out so tests can pin it deterministically."""
+    return secrets.token_urlsafe(32)
+
+
+def _decode_jwt_unverified(jwt: str) -> dict:
+    """Decode a JWT's payload WITHOUT verifying the signature - display only.
+
+    NEVER trust this for authorization; the API verifies the RS256 signature
+    against Clerk's JWKS. This is purely so `zeno login` can echo "logged in as
+    <email>" offline. Returns {} on any malformed input.
+    """
+    try:
+        parts = jwt.split(".")
+        if len(parts) != 3:
+            return {}
+        payload_b64 = parts[1]
+        padding = "=" * (-len(payload_b64) % 4)
+        decoded = base64.urlsafe_b64decode(payload_b64 + padding)
+        data = json.loads(decoded)
+    except (ValueError, TypeError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+# --------------------------------------------------------------------------- #
+# Thin wrappers over zeno_sdk.auth (keyring). Kept here so callers import one
+# module for the whole login surface.
+# --------------------------------------------------------------------------- #
+def store_token(token: str) -> None:
+    """Persist the Clerk JWT to the OS keyring."""
+    auth.set_token(token)
+
+
+def load_token() -> str | None:
+    """Read the stored Clerk JWT from the OS keyring, or None."""
+    return auth.get_token()
+
+
+def clear_token() -> None:
+    """Remove the stored Clerk JWT from the OS keyring (idempotent)."""
+    auth.clear_token()
+
+
+_SUCCESS_HTML = (
+    "<!doctype html><html><head><meta charset='utf-8'><title>zeno</title></head>"
+    "<body style='font-family:system-ui;max-width:32rem;margin:4rem auto;text-align:center'>"
+    "<h1>{heading}</h1><p>{message}</p></body></html>"
+)
+
+
+def _html_page(ok: bool, message: str) -> str:
+    heading = "You are signed in to zeno" if ok else "zeno login failed"
+    return _SUCCESS_HTML.format(heading=heading, message=message)
+
+
+class _LoopbackServer(HTTPServer):
+    """Single-shot loopback server that captures the /callback result."""
+
+    expected_state: str = ""
+    login_token: str | None = None
+    login_error: str | None = None
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """Handle the single GET /callback?state=&token= the bridge redirects to."""
+
+    def do_GET(self) -> None:  # noqa: N802 (stdlib handler contract)
+        server: _LoopbackServer = self.server  # type: ignore[assignment]
+        parsed = urlparse(self.path)
+        if parsed.path != "/callback":
+            self._respond(404, False, "Unexpected path. Close this tab and retry 'zeno login'.")
+            return
+        params = parse_qs(parsed.query)
+        error = (params.get("error") or [""])[0]
+        state = (params.get("state") or [""])[0]
+        token = (params.get("token") or [""])[0]
+        if error:
+            server.login_error = f"bridge returned error: {error}"
+            self._respond(400, False, f"Login failed: {error}")
+            return
+        if not state or not secrets.compare_digest(state, server.expected_state):
+            server.login_error = "state mismatch (possible CSRF); login aborted"
+            self._respond(400, False, "State mismatch. Close this tab and retry 'zeno login'.")
+            return
+        if not token:
+            server.login_error = "no token in callback"
+            self._respond(400, False, "No token returned. Close this tab and retry 'zeno login'.")
+            return
+        server.login_token = token
+        self._respond(
+            200, True, "Login complete. Return to your terminal - you can close this tab."
+        )
+
+    def _respond(self, code: int, ok: bool, message: str) -> None:
+        body = _html_page(ok, message).encode("utf-8")
+        try:
+            self.send_response(code)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+        except OSError:
+            # Browser closed the socket early; the result is already recorded.
+            pass
+
+    def log_message(self, *args: object) -> None:  # noqa: D401 (silence stderr noise)
+        return
+
+
+def _announce_url(url: str, *, open_browser: bool) -> None:
+    """Open the browser, or print the URL for SSH / headless use.
+
+    Split into its own function so tests can monkeypatch it to act as the
+    browser (hitting the loopback /callback) without a real browser, and so
+    --no-browser users get a copy-paste line.
+    """
+    if open_browser:
+        opened = False
+        try:
+            opened = webbrowser.open(url)
+        except Exception:  # webbrowser can raise a grab-bag of OS/runtime errors
+            opened = False
+        if opened:
+            print("Opened your browser to finish login. Waiting for the callback...")
+            return
+    print("Open this URL in a browser to finish login:")
+    print(f"  {url}")
+    print("Waiting for the callback...")
+
+
+def run_loopback_login(
+    authorize_url: str,
+    *,
+    open_browser: bool = True,
+    timeout: float = 180.0,
+) -> str:
+    """Run the browser + loopback leg of login and return the Clerk JWT.
+
+    Binds 127.0.0.1:0 (ephemeral port, localhost only), opens the browser to
+    `<authorize_url>?port=&state=&redirect_uri=`, then blocks until the bridge
+    redirects back to `/callback` with a matching `state` and a `token`, or
+    `timeout` elapses. The CSRF `state` token is the callback's only integrity
+    check today (no PKCE: the bridge returns the token directly, so there is no
+    code-for-token exchange a verifier could protect - see the module docstring
+    TODO for the real exchange to add when the bridge ships).
+
+    Raises LoginError on state mismatch, a missing token, a bridge error, or
+    timeout. Raises OSError if the loopback port cannot be bound.
+    """
+    state = _new_state()
+    server = _LoopbackServer(("127.0.0.1", 0), _CallbackHandler)
+    server.expected_state = state
+    server.timeout = 1.0  # poll cadence so the deadline check stays responsive
+    port = server.server_address[1]
+    redirect_uri = f"http://127.0.0.1:{port}/callback"
+    query = urlencode(
+        {
+            "port": str(port),
+            "state": state,
+            "redirect_uri": redirect_uri,
+        }
+    )
+    url = f"{authorize_url}?{query}"
+
+    deadline = time.monotonic() + timeout
+    try:
+        _announce_url(url, open_browser=open_browser)
+        while server.login_token is None and server.login_error is None:
+            if time.monotonic() >= deadline:
+                raise LoginError(
+                    f"timed out after {int(timeout)}s waiting for the browser callback"
+                )
+            server.handle_request()
+    finally:
+        server.server_close()
+
+    if server.login_error is not None:
+        raise LoginError(server.login_error)
+    if server.login_token is None:  # defensive; loop only exits on token or error
+        raise LoginError("login did not complete")
+    return server.login_token