Inspect, quote, authorize, receive

Discover the merchant and inspect the catalog

stripe directory search "GroundSignal" --format json
curl --fail --silent --show-error \
  https://cookcountyrecords.com/api/agent/offers | jq .

Validate the requested property or list before payment

# Run these commands in one shell. Requires curl, jq, OpenSSL and uuidgen.
umask 077
ORIGIN=https://cookcountyrecords.com
PURCHASE_ROOT="$HOME/.local/share/groundsignal/purchases"
mkdir -p "$PURCHASE_ROOT"
PURCHASE_DIR=$(mktemp -d "$PURCHASE_ROOT/purchase.XXXXXX")
openssl rand -hex 32 > "$PURCHASE_DIR/access-token"
uuidgen > "$PURCHASE_DIR/request-key"

printf 'SKU (appeal_brief, trade_list, season_pass): '
read -r SKU
printf 'Town slug from the available catalog: '
read -r CITY
PIN=
if [ "$SKU" = appeal_brief ]; then
  printf 'Property PIN (14 digits, no separators): '
  read -r PIN
fi
printf 'US billing street address: '
read -r BILLING_LINE1
printf 'Billing city: '
read -r BILLING_CITY
printf 'Billing state (two uppercase letters): '
read -r BILLING_STATE
printf 'Billing ZIP code: '
read -r BILLING_POSTAL

jq -n --arg sku "$SKU" --arg city "$CITY" --arg pin "$PIN" \
  --arg line1 "$BILLING_LINE1" --arg billingCity "$BILLING_CITY" \
  --arg state "$BILLING_STATE" --arg postal "$BILLING_POSTAL" \
  '{sku:$sku, city:$city, billing_address:{country:"US", line1:$line1,
    city:$billingCity, state:$state, postal_code:$postal}}
    + (if $sku == "appeal_brief" then {pin:$pin} else {} end)' \
  > "$PURCHASE_DIR/request.json"

curl --fail-with-body --silent --show-error \
  "$ORIGIN/api/agent/quotes" \
  --header "Authorization: Bearer $(cat "$PURCHASE_DIR/access-token")" \
  --header "Idempotency-Key: $(cat "$PURCHASE_DIR/request-key")" \
  --header 'Content-Type: application/json' \
  --data-binary @"$PURCHASE_DIR/request.json" \
  --output "$PURCHASE_DIR/quote.json"

# Review all amounts in cents, coverage, record dates, delivery and expiry.
# Keep the access token and secure status link out of shared logs.
jq 'del(.secure_status_link)' "$PURCHASE_DIR/quote.json"
printf 'Recovery files saved in %s\n' "$PURCHASE_DIR"

Buyer-authorized product purchase

# Install Link CLI first if needed: npm install --global @stripe/link-cli
# Use a current Node.js LTS such as 22.22 or 24 with the npm package.
# If your wallet login uses LINK_AUTH_FILE, export that same path here.
# Keep it set for login, status, payment, polling and resume commands.
link-cli auth login
# Open Link's login URL and approve its displayed phrase when prompted.
# Continue only after authenticated is true; this does not approve a purchase.
link-cli auth status --format json
PAYMENT_URL=$(jq -er '.payment_url' "$PURCHASE_DIR/quote.json")
QUOTE_ID=$(jq -er '.id' "$PURCHASE_DIR/quote.json")
TOTAL_CENTS=$(jq -er '.totals.total' "$PURCHASE_DIR/quote.json")

# An agent must ask its buyer to approve the complete quoted total first.
printf 'After reviewing the complete total and scope, type PAY to authorize: '
read -r APPROVAL
if [ "$APPROVAL" = PAY ]; then
  link-cli mpp pay "$PAYMENT_URL" \
    --method POST --data '{}' --amount "$TOTAL_CENTS" \
    --header "Authorization: Bearer $(cat "$PURCHASE_DIR/access-token")" \
    --context "Purchase reviewed property-research quote $QUOTE_ID for a complete total of $TOTAL_CENTS USD cents including applicable tax. The buyer approved the town coverage, source dates, deliverable, license, and limitations." \
    --format json > "$PURCHASE_DIR/payment.json"
  # Show approval details privately to the buyer; never print continuation args.
  jq '(if type == "object" and has("data") then .data else . end)
    | (if type == "array" then .[-1] else . end)
    | {spend_request_id:.id, status, approval_url,
       action:(.status_details.requires_action.next_action
         | if . == null then null else {type,resolution,display_message,action_url} end)}' \
    "$PURCHASE_DIR/payment.json"
fi

If Link requests approval, poll and resume the original purchase

# Run only when Link returns an approval URL. Keep LINK_AUTH_FILE unchanged.
# The buyer opens that URL and approves the displayed purchase in Link.
python3 - "$PURCHASE_DIR" <<'PY'
import json, subprocess, sys
from datetime import datetime, timezone
from pathlib import Path

directory = Path(sys.argv[1])
def read_result(filename):
    value = json.loads((directory / filename).read_text())
    if isinstance(value, dict) and "data" in value:
        value = value["data"]
    return value[-1] if isinstance(value, list) else value

def run_link(command, args, filename):
    with (directory / filename).open("w") as output, (directory / "link-errors.log").open("a") as errors:
        code = subprocess.run(["link-cli", command, *args, "--format", "json"],
                              stdout=output, stderr=errors).returncode
    if code:
        sys.exit("Link did not complete. Recover this order and inspect its private response.")
    return read_result(filename)

pending = read_result("payment.json")
quote = read_result("quote.json")
steps = pending.get("_next", {})
poll = steps.get("poll_argv", {})
pay = steps.get("pay_argv", {})
spend_id = pending.get("id")
if not spend_id or poll.get("command") != "spend-request" or poll.get("args", [])[:2] != ["retrieve", spend_id]:
    sys.exit("No matching approval request. Check the existing order status.")
args = pay.get("args", [])
if (pay.get("command") != "mpp" or args[:2] != ["pay", quote["payment_url"]]
        or "--spend-request-id" not in args or "--approved-challenge" not in args
        or args[args.index("--spend-request-id") + 1 :][:1] != [spend_id]):
    sys.exit("The continuation does not match this quote and approval request.")
approved = run_link("spend-request", poll["args"], "approval.json")
if approved.get("id") != spend_id or approved.get("status") != "approved":
    sys.exit("Link has not confirmed approval. Keep the quote and check its status.")
if datetime.fromisoformat(quote["expires_at"].replace("Z", "+00:00")) <= datetime.now(timezone.utc):
    sys.exit("The quote expired. Recover the existing order before requesting a new quote.")
run_link("mpp", args, "payment-resumed.json")
print("Link returned. Recover the same order below to verify payment and delivery.")
PY

Check the saved order, then download only when ready

# In a new shell, set PURCHASE_DIR to the directory saved above.
STATUS_URL=$(jq -er '.status_url' "$PURCHASE_DIR/quote.json")
curl --fail-with-body --silent --show-error "$STATUS_URL" \
  --header "Authorization: Bearer $(cat "$PURCHASE_DIR/access-token")" \
  --output "$PURCHASE_DIR/status.json"
jq 'del(.secure_status_link)' "$PURCHASE_DIR/status.json"

# A quote's download_url is null until the order is ready.
if jq -e '.state == "ready" and .paid == true and .completed == true' \
  "$PURCHASE_DIR/status.json" > /dev/null; then
  DOWNLOAD_URL=$(jq -er '.download_url' "$PURCHASE_DIR/status.json")
  if [ "$(jq -r '.sku' "$PURCHASE_DIR/request.json")" = appeal_brief ]; then
    RESULT_FILE=report.html
  else
    RESULT_FILE=list.csv
  fi
  curl --fail --silent --show-error "$DOWNLOAD_URL" \
    --header "Authorization: Bearer $(cat "$PURCHASE_DIR/access-token")" \
    --output "$PURCHASE_DIR/$RESULT_FILE"
else
  printf 'Order is not ready. Keep its recovery files and check this order again.\n'
fi

Rebuild from current records without another charge

# Included with the same paid order; no payment command is needed.
# Check status as above, then use its refresh_url.
REFRESH_URL=$(jq -er '.refresh_url' "$PURCHASE_DIR/status.json")
curl --fail-with-body --silent --show-error "$REFRESH_URL" \
  --header "Authorization: Bearer $(cat "$PURCHASE_DIR/access-token")" \
  --dump-header "$PURCHASE_DIR/rebuild-headers.txt" \
  --output "$PURCHASE_DIR/current-$RESULT_FILE"