settld 0.1.2 → 0.2.0

package/scripts/dev/billing-doctor.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+# shellcheck source=/dev/null
+source "$ROOT_DIR/scripts/dev/env.sh"
+
+for bin in curl jq; do
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    echo "Missing required tool: $bin"
+    exit 1
+  fi
+done
+
+if ! curl -fsS "$SETTLD_BASE_URL/healthz" >/dev/null 2>&1; then
+  cat <<EOF
+API is not reachable at $SETTLD_BASE_URL.
+Start it in another shell:
+  npm run dev:start
+EOF
+  exit 1
+fi
+
+if [[ -z "${SETTLD_API_KEY:-}" ]]; then
+  SETTLD_API_KEY="$(bash "$ROOT_DIR/scripts/dev/new-sdk-key.sh" --print-only)"
+  export SETTLD_API_KEY
+fi
+
+API_AUTH_HEADER="authorization: Bearer $SETTLD_API_KEY"
+PERIOD="$(date -u +%Y-%m)"
+
+api_post_json() {
+  local path="$1"
+  local payload="$2"
+  local response
+  local body
+  local status
+
+  response="$(curl -sS -X POST "$SETTLD_BASE_URL$path" \
+    -H "$API_AUTH_HEADER" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -H "content-type: application/json" \
+    -d "$payload" \
+    -w $'\n%{http_code}')"
+  body="$(printf "%s" "$response" | sed '$d')"
+  status="$(printf "%s" "$response" | tail -n1)"
+  if [[ ! "$status" =~ ^2 ]]; then
+    echo "Request failed: POST $path (HTTP $status)"
+    echo "$body" | jq . 2>/dev/null || echo "$body"
+    exit 1
+  fi
+  printf "%s" "$body"
+}
+
+echo "[1/5] Running first verified settlement..."
+RUN_JSON="$(cd "$ROOT_DIR" && SETTLD_SDK_DISPUTE_WINDOW_DAYS=3 npm run -s sdk:first-run)"
+echo "$RUN_JSON" | jq .
+
+RUN_ID="$(echo "$RUN_JSON" | jq -r '.runId')"
+PAYER_AGENT_ID="$(echo "$RUN_JSON" | jq -r '.payerAgentId')"
+if [[ -z "$RUN_ID" || "$RUN_ID" == "null" ]]; then
+  echo "Could not parse runId from sdk:first-run output."
+  exit 1
+fi
+if [[ -z "$PAYER_AGENT_ID" || "$PAYER_AGENT_ID" == "null" ]]; then
+  echo "Could not parse payerAgentId from sdk:first-run output."
+  exit 1
+fi
+
+SUFFIX="$(date +%s%N | cut -c1-16)"
+DISPUTE_ID="dispute_doctor_${SUFFIX}"
+CASE_ID="arb_case_doctor_${SUFFIX}"
+
+echo "[2/5] Opening dispute..."
+DISPUTE_JSON="$(api_post_json "/runs/$RUN_ID/dispute/open" "{\"disputeId\":\"$DISPUTE_ID\",\"reason\":\"billing doctor validation\",\"openedByAgentId\":\"$PAYER_AGENT_ID\"}")"
+echo "$DISPUTE_JSON" | jq .
+
+echo "[3/5] Opening arbitration case..."
+ARBITRATION_JSON="$(api_post_json "/runs/$RUN_ID/arbitration/open" "{\"caseId\":\"$CASE_ID\",\"disputeId\":\"$DISPUTE_ID\",\"arbiterAgentId\":\"$PAYER_AGENT_ID\"}")"
+echo "$ARBITRATION_JSON" | jq .
+
+echo "[4/5] Reading billable events..."
+EVENTS_JSON="$(curl -sS "$SETTLD_BASE_URL/ops/finance/billable-events?period=$PERIOD" \
+  -H "authorization: Bearer $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID")"
+
+SCOPED_EVENTS_JSON="$(echo "$EVENTS_JSON" | jq --arg runId "$RUN_ID" --arg caseId "$CASE_ID" '
+  [.events[] | select((.runId == $runId) or (.arbitrationCaseId == $caseId))]
+')"
+echo "$SCOPED_EVENTS_JSON" | jq --arg tenantId "$SETTLD_TENANT_ID" --arg runId "$RUN_ID" --arg caseId "$CASE_ID" --arg period "$PERIOD" '
+{
+  tenantId: $tenantId,
+  period: $period,
+  runId: $runId,
+  arbitrationCaseId: $caseId,
+  count: length,
+  eventTypeCounts: (reduce .[] as $event ({verified_run: 0, settled_volume: 0, arbitration_usage: 0};
+    if ($event.eventType == "verified_run") then .verified_run += 1
+    elif ($event.eventType == "settled_volume") then .settled_volume += 1
+    elif ($event.eventType == "arbitration_usage") then .arbitration_usage += 1
+    else .
+    end)),
+  events: .
+}'
+
+RUN_VERIFIED_EVENTS="$(echo "$SCOPED_EVENTS_JSON" | jq --arg runId "$RUN_ID" '[.[] | select(.eventType=="verified_run" and .runId==$runId)] | length')"
+RUN_SETTLED_EVENTS="$(echo "$SCOPED_EVENTS_JSON" | jq --arg runId "$RUN_ID" '[.[] | select(.eventType=="settled_volume" and .runId==$runId)] | length')"
+ARBITRATION_EVENTS_FOR_CASE="$(echo "$SCOPED_EVENTS_JSON" | jq --arg caseId "$CASE_ID" '[.[] | select(.eventType=="arbitration_usage" and .arbitrationCaseId==$caseId)] | length')"
+
+if [[ "$RUN_VERIFIED_EVENTS" -lt 1 ]]; then
+  echo "Expected at least one verified_run event for run $RUN_ID, found $RUN_VERIFIED_EVENTS."
+  exit 1
+fi
+if [[ "$RUN_SETTLED_EVENTS" -lt 1 ]]; then
+  echo "Expected at least one settled_volume event for run $RUN_ID, found $RUN_SETTLED_EVENTS."
+  exit 1
+fi
+if [[ "$ARBITRATION_EVENTS_FOR_CASE" -lt 1 ]]; then
+  echo "Expected at least one arbitration_usage event for case $CASE_ID, found $ARBITRATION_EVENTS_FOR_CASE."
+  exit 1
+fi
+
+echo "[5/5] Reading billing summary..."
+SUMMARY_JSON="$(curl -sS "$SETTLD_BASE_URL/ops/finance/billing/summary?period=$PERIOD" \
+  -H "authorization: Bearer $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID")"
+echo "$SUMMARY_JSON" | jq '{
+  tenantId,
+  period,
+  plan: { planId: .plan.planId },
+  usage: .usage,
+  enforcement: .enforcement
+}'
+
+ARBITRATION_CASES="$(echo "$SUMMARY_JSON" | jq -r '.usage.arbitrationCases // 0')"
+if [[ "$ARBITRATION_CASES" -lt 1 ]]; then
+  echo "Expected arbitrationCases >= 1 in billing summary, got $ARBITRATION_CASES."
+  exit 1
+fi
+
+echo
+echo "Billing doctor passed."
+echo "Run: $RUN_ID"
+echo "Dispute: $DISPUTE_ID"
+echo "Arbitration case: $CASE_ID"

package/scripts/dev/billing-smoke-prod.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Load local env defaults automatically (same behavior as other dev scripts).
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+if [[ -f "$ROOT_DIR/scripts/dev/env.sh" ]]; then
+  # shellcheck source=/dev/null
+  source "$ROOT_DIR/scripts/dev/env.sh"
+fi
+
+for bin in curl jq; do
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    echo "Missing required tool: $bin"
+    exit 1
+  fi
+done
+
+: "${SETTLD_BASE_URL:?SETTLD_BASE_URL is required (example: https://<your-api-domain>)}"
+: "${PROXY_OPS_TOKEN:?PROXY_OPS_TOKEN is required}"
+
+# Default to an isolated smoke tenant to avoid stale billing/subscription state
+# in long-lived tenants (for example tenant_default).
+if [[ -z "${SETTLD_TENANT_ID:-}" || "${SETTLD_TENANT_ID}" == "tenant_default" ]]; then
+  SETTLD_TENANT_ID="tenant_smoke_$(date +%s)"
+fi
+export SETTLD_TENANT_ID
+
+if [[ "$SETTLD_BASE_URL" == "http://127.0.0.1:3000" || "$SETTLD_BASE_URL" == "http://localhost:3000" ]]; then
+  cat <<EOF
+This is the production smoke script, but SETTLD_BASE_URL is still local ($SETTLD_BASE_URL).
+Set your deployed API URL once:
+  echo 'SETTLD_BASE_URL=https://api.settld.work' >> .env.dev.runtime
+EOF
+  exit 1
+fi
+
+if [[ "$PROXY_OPS_TOKEN" == "dev_ops_token" ]]; then
+  cat <<EOF
+PROXY_OPS_TOKEN is still the local default (dev_ops_token), which will fail in production.
+Set your real prod token once:
+  echo 'PROXY_OPS_TOKEN=<your_prod_ops_token>' >> .env.dev.runtime
+EOF
+  exit 1
+fi
+
+api_get() {
+  local path="$1"
+  local response body status
+  response="$(curl -sS "$SETTLD_BASE_URL$path" \
+    -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -w $'\n%{http_code}')"
+  body="$(printf "%s" "$response" | sed '$d')"
+  status="$(printf "%s" "$response" | tail -n1)"
+  if [[ ! "$status" =~ ^2 ]]; then
+    echo "GET $path failed (HTTP $status)" >&2
+    echo "$body" | jq . 2>/dev/null >&2 || echo "$body" >&2
+    exit 1
+  fi
+  printf "%s" "$body"
+}
+
+api_post_json() {
+  local path="$1"
+  local payload="$2"
+  local response body status
+  response="$(curl -sS -X POST "$SETTLD_BASE_URL$path" \
+    -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -H "content-type: application/json" \
+    -d "$payload" \
+    -w $'\n%{http_code}')"
+  body="$(printf "%s" "$response" | sed '$d')"
+  status="$(printf "%s" "$response" | tail -n1)"
+  if [[ ! "$status" =~ ^2 ]]; then
+    echo "POST $path failed (HTTP $status)" >&2
+    echo "$body" | jq . 2>/dev/null >&2 || echo "$body" >&2
+    exit 1
+  fi
+  printf "%s" "$body"
+}
+
+api_post_json_with_status() {
+  local path="$1"
+  local payload="$2"
+  local response body status
+  response="$(curl -sS -X POST "$SETTLD_BASE_URL$path" \
+    -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -H "content-type: application/json" \
+    -d "$payload" \
+    -w $'\n%{http_code}')"
+  body="$(printf "%s" "$response" | sed '$d')"
+  status="$(printf "%s" "$response" | tail -n1)"
+  printf "%s\n%s" "$status" "$body"
+}
+
+echo "[1/5] Health check..."
+HEALTH_RAW="$(curl -sS "$SETTLD_BASE_URL/healthz" || true)"
+if ! echo "$HEALTH_RAW" | jq -e . >/dev/null 2>&1; then
+  echo "Health endpoint did not return JSON."
+  echo "This usually means SETTLD_BASE_URL points to the frontend (for example Vercel) instead of the API service."
+  echo
+  echo "First 240 chars returned:"
+  echo "$HEALTH_RAW" | head -c 240
+  echo
+  echo
+  echo "Expected something like: {\"ok\":true,\"dbOk\":true,...}"
+  exit 1
+fi
+HEALTH_JSON="$HEALTH_RAW"
+echo "$HEALTH_JSON" | jq '{ok,dbOk,dbLatencyMs}'
+if [[ "$(echo "$HEALTH_JSON" | jq -r '.ok // false')" != "true" ]]; then
+  echo "Health check failed."
+  exit 1
+fi
+
+STRIPE_CUSTOMER_ID=""
+if [[ -n "${PROXY_BILLING_STRIPE_SECRET_KEY:-}" ]]; then
+  STRIPE_CUSTOMER_ID="$(
+    curl -sS https://api.stripe.com/v1/customers \
+      -u "$PROXY_BILLING_STRIPE_SECRET_KEY:" \
+      -d "name=Settld Smoke Customer $(date +%s)" | jq -r '.id'
+  )"
+  if [[ -z "$STRIPE_CUSTOMER_ID" || "$STRIPE_CUSTOMER_ID" == "null" ]]; then
+    echo "Failed to create Stripe customer for smoke run." >&2
+    exit 1
+  fi
+fi
+
+echo "[2/5] Billing checkout session..."
+CHECKOUT_PAYLOAD="$(jq -n \
+  --arg plan "builder" \
+  --arg customerId "$STRIPE_CUSTOMER_ID" \
+  --arg successUrl "${SETTLD_BASE_URL%/}/billing/success" \
+  --arg cancelUrl "${SETTLD_BASE_URL%/}/billing/cancel" \
+  '{
+    plan: $plan,
+    successUrl: $successUrl,
+    cancelUrl: $cancelUrl
+  } + (if ($customerId | length) > 0 then { customerId: $customerId } else {} end)'
+)"
+CHECKOUT_JSON="$(api_post_json "/ops/finance/billing/providers/stripe/checkout" "$CHECKOUT_PAYLOAD")"
+echo "$CHECKOUT_JSON" | jq '{tenantId, mode: .checkoutSession.mode, plan: .checkoutSession.plan, sessionId: .checkoutSession.sessionId, sessionUrl: .checkoutSession.sessionUrl}'
+CHECKOUT_MODE="$(echo "$CHECKOUT_JSON" | jq -r '.checkoutSession.mode // ""')"
+if [[ "$CHECKOUT_MODE" != "live" && "$CHECKOUT_MODE" != "stub" ]]; then
+  echo "Unexpected checkout mode: $CHECKOUT_MODE"
+  exit 1
+fi
+
+echo "[3/5] Billing customer portal session..."
+CUSTOMER_ID="$STRIPE_CUSTOMER_ID"
+if [[ -z "$CUSTOMER_ID" || "$CUSTOMER_ID" == "null" ]]; then
+  CUSTOMER_ID="cus_smoke_$(date +%s)"
+fi
+
+PORTAL_RESPONSE="$(api_post_json_with_status "/ops/finance/billing/providers/stripe/portal" "{\"customerId\":\"$CUSTOMER_ID\"}")"
+PORTAL_STATUS="$(printf "%s" "$PORTAL_RESPONSE" | head -n1)"
+PORTAL_JSON="$(printf "%s" "$PORTAL_RESPONSE" | sed '1d')"
+if [[ "$PORTAL_STATUS" =~ ^2 ]] && [[ "$(echo "$PORTAL_JSON" | jq -r '.portalSession.sessionUrl // ""')" != "" ]]; then
+  echo "$PORTAL_JSON" | jq '{tenantId, mode: .portalSession.mode, customerId: .portalSession.customerId, sessionId: .portalSession.sessionId, sessionUrl: .portalSession.sessionUrl}'
+else
+  # In live mode with a synthetic customer id, Stripe returns upstream "No such customer".
+  echo "$PORTAL_JSON" | jq '{tenantId,error,code,details}' 2>/dev/null || echo "$PORTAL_JSON"
+  if [[ "$PORTAL_STATUS" != "502" || "$(echo "$PORTAL_JSON" | jq -r '.code // ""' 2>/dev/null)" != "BILLING_PROVIDER_UPSTREAM_ERROR" ]]; then
+    echo "Unexpected portal response (HTTP $PORTAL_STATUS)."
+    exit 1
+  fi
+fi
+
+echo "[4/5] Provider reconcile subscription mapping..."
+TS="$(date +%s)"
+GROWTH_PRICE_ID="${PROXY_BILLING_STRIPE_PRICE_ID_GROWTH:-}"
+if [[ -z "$GROWTH_PRICE_ID" ]]; then
+  GROWTH_CHECKOUT_JSON="$(api_post_json "/ops/finance/billing/providers/stripe/checkout" '{"plan":"growth"}')"
+  GROWTH_PRICE_ID="$(echo "$GROWTH_CHECKOUT_JSON" | jq -r '.checkoutSession.priceId // ""')"
+fi
+if [[ -z "$GROWTH_PRICE_ID" ]]; then
+  # In stub mode we still need a deterministic value in event payloads; plan mapping
+  # is derived from metadata and does not require a live provider price id.
+  GROWTH_PRICE_ID="price_stub_growth"
+fi
+
+RECON_PAYLOAD="$(jq -n \
+  --arg eventId "evt_smoke_price_map_${TS}" \
+  --arg subId "sub_smoke_price_map_${TS}" \
+  --arg customerId "$CUSTOMER_ID" \
+  --arg price "$GROWTH_PRICE_ID" \
+  --arg plan "growth" \
+  --argjson created "$TS" \
+  '{events:[{id:$eventId,type:"customer.subscription.updated",created:$created,data:{object:{id:$subId,customer:$customerId,status:"active",items:{data:[{price:{id:$price,metadata:{settldPlan:$plan}}}]},metadata:{settldPlan:$plan}}}}]}'
+)"
+RECON_JSON="$(api_post_json "/ops/finance/billing/providers/stripe/reconcile" "$RECON_PAYLOAD")"
+echo "$RECON_JSON" | jq '{tenantId,summary}'
+if [[ "$(echo "$RECON_JSON" | jq -r '.summary.applied // 0')" -lt 1 ]]; then
+  echo "Reconcile did not apply events."
+  exit 1
+fi
+
+PLAN_JSON="$(api_get "/ops/finance/billing/plan")"
+echo "$PLAN_JSON" | jq '{tenantId,billing,resolvedPlan}'
+if [[ "$(echo "$PLAN_JSON" | jq -r '.billing.plan // ""')" != "growth" ]]; then
+  echo "Expected billing.plan=growth after reconcile mapping."
+  exit 1
+fi
+
+echo "[5/5] Billing summary..."
+PERIOD="$(date -u +%Y-%m)"
+SUMMARY_JSON="$(api_get "/ops/finance/billing/summary?period=$PERIOD")"
+echo "$SUMMARY_JSON" | jq '{tenantId,period,usage,enforcement}'
+if [[ "$(echo "$SUMMARY_JSON" | jq -r '.usage.eventCount // 0')" -lt 0 ]]; then
+  echo "Unexpected summary payload."
+  exit 1
+fi
+
+echo
+echo "Production billing smoke passed."
+echo "Base URL: $SETTLD_BASE_URL"
+echo "Tenant:   $SETTLD_TENANT_ID"

package/scripts/dev/billing-webhook-replay.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+if [[ -f "$ROOT_DIR/scripts/dev/env.sh" ]]; then
+  # shellcheck source=/dev/null
+  source "$ROOT_DIR/scripts/dev/env.sh"
+fi
+
+for bin in curl jq; do
+  if ! command -v "$bin" >/dev/null 2>&1; then
+    echo "Missing required tool: $bin" >&2
+    exit 1
+  fi
+done
+
+: "${SETTLD_BASE_URL:?SETTLD_BASE_URL is required}"
+: "${PROXY_OPS_TOKEN:?PROXY_OPS_TOKEN is required}"
+: "${SETTLD_TENANT_ID:?SETTLD_TENANT_ID is required}"
+
+LIMIT="${LIMIT:-200}"
+OFFSET="${OFFSET:-0}"
+REASON="${REASON:-}"
+EVENT_TYPE="${EVENT_TYPE:-}"
+AUDIT_IDS="${AUDIT_IDS:-}"
+DRY_RUN="${DRY_RUN:-1}"
+
+if [[ "$DRY_RUN" == "1" || "${DRY_RUN,,}" == "true" ]]; then
+  DRY_RUN_JSON="true"
+else
+  DRY_RUN_JSON="false"
+fi
+
+urlencode() {
+  local input="${1:-}"
+  jq -rn --arg v "$input" '$v|@uri'
+}
+
+api_get() {
+  local path="$1"
+  local response body status
+  response="$(curl -sS "$SETTLD_BASE_URL$path" \
+    -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -w $'\n%{http_code}')"
+  body="$(printf "%s" "$response" | sed '$d')"
+  status="$(printf "%s" "$response" | tail -n1)"
+  if [[ ! "$status" =~ ^2 ]]; then
+    echo "GET $path failed (HTTP $status)" >&2
+    echo "$body" | jq . 2>/dev/null >&2 || echo "$body" >&2
+    exit 1
+  fi
+  printf "%s" "$body"
+}
+
+api_post_json() {
+  local path="$1"
+  local payload="$2"
+  local response body status
+  response="$(curl -sS -X POST "$SETTLD_BASE_URL$path" \
+    -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -H "content-type: application/json" \
+    -d "$payload" \
+    -w $'\n%{http_code}')"
+  body="$(printf "%s" "$response" | sed '$d')"
+  status="$(printf "%s" "$response" | tail -n1)"
+  if [[ ! "$status" =~ ^2 ]]; then
+    echo "POST $path failed (HTTP $status)" >&2
+    echo "$body" | jq . 2>/dev/null >&2 || echo "$body" >&2
+    exit 1
+  fi
+  printf "%s" "$body"
+}
+
+echo "[1/4] Stripe reconcile report snapshot"
+REPORT_JSON="$(api_get "/ops/finance/billing/providers/stripe/reconcile/report?limit=${LIMIT}&offset=${OFFSET}")"
+echo "$REPORT_JSON" | jq '{
+  tenantId,
+  provider,
+  counts,
+  ingestBreakdown,
+  rejectedReasonCounts,
+  replayableRejectedCount
+}'
+
+echo "[2/4] Dead-letter candidate snapshot"
+DEAD_LETTER_PATH="/ops/finance/billing/providers/stripe/dead-letter?limit=${LIMIT}&offset=${OFFSET}"
+if [[ -n "$REASON" ]]; then
+  DEAD_LETTER_PATH="${DEAD_LETTER_PATH}&reason=$(urlencode "$REASON")"
+fi
+if [[ -n "$EVENT_TYPE" ]]; then
+  DEAD_LETTER_PATH="${DEAD_LETTER_PATH}&eventType=$(urlencode "$EVENT_TYPE")"
+fi
+
+DEAD_JSON="$(api_get "$DEAD_LETTER_PATH")"
+echo "$DEAD_JSON" | jq '{
+  tenantId,
+  provider,
+  count,
+  limit,
+  offset,
+  sample: (.events[:5] | map({auditId, eventId, eventType, reason, source, replayable}))
+}'
+
+if [[ "$(echo "$DEAD_JSON" | jq -r '.count // 0')" == "0" ]]; then
+  echo "No replayable dead-letter events found."
+  exit 0
+fi
+
+echo "[3/4] Replay request"
+AUDIT_IDS_JSON="[]"
+if [[ -n "$AUDIT_IDS" ]]; then
+  AUDIT_IDS_JSON="$(printf "%s" "$AUDIT_IDS" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | jq -Rn '[inputs | select(length>0) | tonumber]')"
+fi
+
+REPLAY_PAYLOAD="$(
+  jq -n \
+    --argjson dryRun "$DRY_RUN_JSON" \
+    --arg reason "$REASON" \
+    --arg eventType "$EVENT_TYPE" \
+    --argjson limit "$LIMIT" \
+    --argjson offset "$OFFSET" \
+    --argjson auditIds "$AUDIT_IDS_JSON" \
+    '{
+      dryRun: $dryRun,
+      limit: $limit,
+      offset: $offset
+    }
+    + (if ($reason|length)>0 then {reason:$reason} else {} end)
+    + (if ($eventType|length)>0 then {eventType:$eventType} else {} end)
+    + (if ($auditIds|length)>0 then {auditIds:$auditIds} else {} end)'
+)"
+
+REPLAY_JSON="$(api_post_json "/ops/finance/billing/providers/stripe/dead-letter/replay" "$REPLAY_PAYLOAD")"
+echo "$REPLAY_JSON" | jq '{
+  tenantId,
+  provider,
+  dryRun,
+  summary,
+  sample: (.results[:10])
+}'
+
+echo "[4/4] Post-replay report snapshot"
+POST_REPORT_JSON="$(api_get "/ops/finance/billing/providers/stripe/reconcile/report?limit=${LIMIT}&offset=${OFFSET}")"
+echo "$POST_REPORT_JSON" | jq '{
+  tenantId,
+  provider,
+  counts,
+  ingestBreakdown,
+  rejectedReasonCounts,
+  replayableRejectedCount
+}'
+
+FAILED_COUNT="$(echo "$REPLAY_JSON" | jq -r '.summary.failed // 0')"
+if [[ "$DRY_RUN_JSON" == "false" && "$FAILED_COUNT" != "0" ]]; then
+  echo "Replay completed with failed events: $FAILED_COUNT" >&2
+  exit 2
+fi
+
+echo "Billing webhook replay guardrail flow completed."

package/scripts/dev/env.dev.example

@@ -0,0 +1,29 @@
+# Copy to .env.dev at repo root:
+#   cp scripts/dev/env.dev.example .env.dev
+
+# Core dev URLs
+SETTLD_BASE_URL=http://127.0.0.1:3000
+SETTLD_TENANT_ID=tenant_default
+PROXY_OPS_TOKEN=dev_ops_token
+
+# PG runtime
+STORE=pg
+PROXY_PG_SCHEMA=public
+PROXY_MIGRATE_ON_STARTUP=1
+DATABASE_URL=postgresql://neondb_owner:replace_me@host/neondb?sslmode=verify-full&channel_binding=require
+
+# Stripe billing (test mode first)
+# Free-first growth default: keep billing usage metering on but disable hard-limit blocking.
+# Set to 1 when you intentionally want billing-plan hard limits to enforce 402 blocks.
+PROXY_BILLING_PLAN_ENFORCEMENT_ENABLED=0
+
+# Backend uses secret key + price IDs.
+# Publishable key is for frontend Stripe.js usage and is optional for backend-only local flows.
+STRIPE_PUBLISHABLE_KEY=pk_test_replace_me
+PROXY_BILLING_STRIPE_SECRET_KEY=sk_test_replace_me
+PROXY_BILLING_STRIPE_PRICE_ID_BUILDER=price_replace_me_builder
+PROXY_BILLING_STRIPE_PRICE_ID_GROWTH=price_replace_me_growth
+PROXY_BILLING_STRIPE_PRICE_ID_ENTERPRISE=price_replace_me_enterprise
+PROXY_BILLING_STRIPE_CHECKOUT_SUCCESS_URL=http://127.0.0.1:3000/billing/success
+PROXY_BILLING_STRIPE_CHECKOUT_CANCEL_URL=http://127.0.0.1:3000/billing/cancel
+PROXY_BILLING_STRIPE_PORTAL_RETURN_URL=http://127.0.0.1:3000/settings/billing

package/scripts/dev/env.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  echo "source scripts/dev/env.sh"
+  echo "This file must be sourced so exports are applied to your shell."
+  exit 1
+fi
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+ENV_FILE="${SETTLD_ENV_FILE:-$ROOT_DIR/.env.dev}"
+RUNTIME_ENV_FILE="${SETTLD_RUNTIME_ENV_FILE:-$ROOT_DIR/.env.dev.runtime}"
+
+if [[ -f "$ENV_FILE" ]]; then
+  set -a
+  # shellcheck source=/dev/null
+  . "$ENV_FILE"
+  set +a
+fi
+
+if [[ -f "$RUNTIME_ENV_FILE" ]]; then
+  set -a
+  # shellcheck source=/dev/null
+  . "$RUNTIME_ENV_FILE"
+  set +a
+fi
+
+: "${SETTLD_BASE_URL:=http://127.0.0.1:3000}"
+: "${SETTLD_TENANT_ID:=tenant_default}"
+: "${PROXY_OPS_TOKEN:=dev_ops_token}"
+
+export SETTLD_BASE_URL
+export SETTLD_TENANT_ID
+export PROXY_OPS_TOKEN
+export SETTLD_ENV_FILE="$ENV_FILE"
+export SETTLD_RUNTIME_ENV_FILE="$RUNTIME_ENV_FILE"
+

package/scripts/dev/new-sdk-key.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+# shellcheck source=/dev/null
+source "$ROOT_DIR/scripts/dev/env.sh"
+
+PRINT_ONLY=0
+OPS_TOKEN_OVERRIDE=""
+if [[ "${1:-}" == "--help" ]]; then
+  cat <<'EOF'
+Usage:
+  bash scripts/dev/new-sdk-key.sh
+  bash scripts/dev/new-sdk-key.sh --print-only
+  bash scripts/dev/new-sdk-key.sh --ops-token <tok> [--print-only]
+
+Behavior:
+  - mints a new API key via /ops/api-keys
+  - writes SETTLD_API_KEY into .env.dev.runtime
+  - prints export command for current shell
+EOF
+  exit 0
+fi
+
+# Parse flags (source'd env files may override shell exports; we support explicit override).
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --print-only)
+      PRINT_ONLY=1
+      shift
+      ;;
+    --ops-token)
+      OPS_TOKEN_OVERRIDE="${2:-}"
+      if [[ -z "${OPS_TOKEN_OVERRIDE:-}" ]]; then
+        echo "--ops-token requires a value" >&2
+        exit 2
+      fi
+      shift 2
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -n "${OPS_TOKEN_OVERRIDE:-}" ]]; then
+  export PROXY_OPS_TOKEN="$OPS_TOKEN_OVERRIDE"
+fi
+
+# Prefer x-proxy-ops-token for hosted deployments that may not forward Authorization.
+RESPONSE="$(
+  curl -sS -X POST "$SETTLD_BASE_URL/ops/api-keys" \
+    -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+    -H "authorization: Bearer $PROXY_OPS_TOKEN" \
+    -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+    -H "content-type: application/json" \
+    -d '{"scopes":["ops_read","ops_write","finance_read","finance_write","audit_read"],"description":"sdk quickstart"}'
+)"
+
+KEY_ID="$(echo "$RESPONSE" | jq -r '.keyId // empty')"
+SECRET="$(echo "$RESPONSE" | jq -r '.secret // empty')"
+
+if [[ -z "$KEY_ID" || -z "$SECRET" ]]; then
+  echo "Failed to mint SDK key."
+  echo "$RESPONSE" | jq .
+  exit 1
+fi
+
+SETTLD_API_KEY_VALUE="${KEY_ID}.${SECRET}"
+
+if [[ "$PRINT_ONLY" == "1" ]]; then
+  echo "$SETTLD_API_KEY_VALUE"
+  exit 0
+fi
+
+printf "SETTLD_API_KEY=%s\n" "$SETTLD_API_KEY_VALUE" >"$SETTLD_RUNTIME_ENV_FILE"
+chmod 600 "$SETTLD_RUNTIME_ENV_FILE" || true
+
+echo "Wrote $SETTLD_RUNTIME_ENV_FILE"
+echo "export SETTLD_API_KEY='$SETTLD_API_KEY_VALUE'"