Cookbook

#!/bin/sh
set -e
JAR=./flowfinds.jar
ff() {
  method=$1; path=$2; body=${3:-}
  if [ -n "$body" ]; then
    curl -s -c "$JAR" -b "$JAR" -X "$method" \
      -H 'Content-Type: application/json' -d "$body" "$FLOWFINDS_ORIGIN$path"
  else
    curl -s -c "$JAR" -b "$JAR" -X "$method" "$FLOWFINDS_ORIGIN$path"
  fi
}

ff GET /api/find
ff GET /api/offer

import json, urllib.request, http.cookiejar

jar = http.cookiejar.CookieJar()
http_client = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(jar))

def get(path):
    with http_client.open(ORIGIN + path) as r:
        return r.status, json.load(r)

status, body = get("/api/offer")

if isinstance(body, dict) and body.get("status") == "refused":
    # failed_leg says which leg failed: "research" or "pricing".
    print(body["failed_leg"], body["reason"], body["explanation"])
elif body.get("status") == "offer":
    print(body["offer"]["our_price_usd"], body["freshness"])

TERMINAL = {"ready", "failed", "not_started", "not_claimed"}

def wait_for_store(get, sleep, timeout_s=600):
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        _, body = get("/api/store")
        if body.get("status") in TERMINAL:
            return body
        sleep(5)
    raise TimeoutError("store build did not reach a terminal state")

store = wait_for_store(get, time.sleep)
if store["status"] == "failed":
    # The generator's own words, not a generic apology.
    print(store["failed_stage"], store["reason"], store.get("diagnostic"))

proposal = post("/api/intent", {
    "surface": surface,
    "requested": "Lead with the delivery guarantee",
})

if proposal.get("status") == "refused":
    # no_row_justifies_this means the engine has no dated row to stand on.
    raise SystemExit(proposal["reason"])

applied = post("/api/intent/apply", {
    "surface": surface,
    "requested": "Lead with the delivery guarantee",
    "proposed": proposal,
    # Only needed when the engine says the change cannot be undone.
    # "confirm_irreversible": True,
})

if applied.get("reason") == "stale_proposal":
    # Re-propose and show the founder what changed before retrying.
    ...
elif applied["status"] == "applied":
    print(applied["because"], applied["source_row"], applied["reversible"])

started = post("/api/store/checkout", {"product_id": product_id})
# charged_yet is False. Opening a session is not a payment.
assert started["charged_yet"] is False
reference = started["reference"]
send_customer_to(started["pay_url"])

# Later — after the provider's redirect, or on a schedule.
_, confirmed = get(f"/api/store/confirm?ref={reference}")

metrics = get(f"/api/editor/metrics?product_id={pid}&days=14")[1]

sessions, cart = metrics["sessions"], metrics["cart"]
checkout, paid = metrics["checkout"], metrics["paid"]

# Compute a rate only when the stages are internally consistent.
consistent = sessions >= cart >= checkout >= paid
cart_rate = round(cart / sessions * 100, 2) if consistent and sessions else None

# Under a hundred sessions, treat it as a small sample and investigate
# before claiming a cause. This is the same threshold the commerce
# agent's store_funnel tool applies to its own output.

const res = await fetch(`${ORIGIN}/api/intent`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "What is my break-even CPA?", surface: "home" }),
  credentials: "include",
});

const body = await res.json();

if (res.status === 401) throw new Error("No commerce identity for this session.");

// degraded means the model path failed and the deterministic fallback answered.
// The answer is still honest; it is not reasoned, and it says so.
if (body.degraded) markAsFallback(body.message);

// evidence lists only the tool results the answer actually cited.
for (const item of body.evidence ?? []) {
  console.log(item.source, item.status, item.observed_at);
}

// uncertainties is what the agent could not establish. Show it.
for (const u of body.uncertainties ?? []) console.log("unresolved:", u);

reasons = get("/api/reasons")[1]      # {"reasons": {...}, "count": n}
controls = get("/api/controls")[1]    # {"controls": {"POST /api/select": ...}}

# Render a refusal using the engine's own sentence rather than your copy.
def explain(body):
    return body.get("explanation") or reasons["reasons"].get(body.get("reason"), "")

# Discover which endpoint sits behind a control, rather than inferring
# it from a button label.
method, path = "POST /api/intent/apply".split(" ", 1)