Return policy generator

#!/usr/bin/env bash
# Sets up this return policy in Flint and stops at the first error.
# Flint won't activate two policies at the same priority, so it first
# checks that no active policy already holds the ones it uses.
# Needs bash, jq, and curl 7.76 or later.
set -euo pipefail

: "${FLINT_API_KEY:?Set FLINT_API_KEY to a sandbox API key}"
: "${RETURNS_LOCATION_ID:?Set RETURNS_LOCATION_ID to an active Location with a postal address}"
API="${FLINT_BASE_URL:-https://api.withflintpay.com}"
RUN="$(date +%s)"

# If a step fails after a policy was activated, says which to retire
# so the next run's check doesn't stop on it.
ACTIVATED=""
trap 'status=$?; [ "$status" -eq 0 ] || [ -z "$ACTIVATED" ] || echo "Recover: this run already activated$ACTIVATED. Retire each with DELETE /v1/return-policies/{id}, then run again." >&2' EXIT

# Prints the response body. On an HTTP error, prints it and stops.
flint() {
  local body
  if ! body=$(curl -sS --fail-with-body \
    -H "Authorization: Bearer $FLINT_API_KEY" \
    -H "Content-Type: application/json" "$@"); then
    echo "Flint returned an error: $body" >&2
    return 1
  fi
  printf '%s\n' "$body"
}

# Prints a field from a response, or stops if it's missing.
field() {
  local value
  value=$(jq -r "$2 // empty" <<<"$1")
  if [ -z "$value" ]; then
    echo "Stopped: $2 is missing from the response" >&2
    return 1
  fi
  printf '%s\n' "$value"
}

# 1. Stop before creating anything if activation would fail: an active
#    policy already has priority 200 or 100 (deactivate it, or change
#    "priority" below), or the returns Location isn't usable.
LOCATION=$(flint "$API/v1/locations/$RETURNS_LOCATION_ID")
if [ "$(jq -r '.data.status' <<<"$LOCATION")" != active ] || [ -z "$(jq -r '.data.address.line1 // empty' <<<"$LOCATION")" ]; then
  echo "Stopped: Location $RETURNS_LOCATION_ID must be active and have a postal address." >&2
  exit 1
fi
PAGE=""
while :; do
  ACTIVE=$(flint "$API/v1/return-policies?status=active&page_size=100${PAGE:+&page_token=$PAGE}")
  for ID in $(jq -r '.data[].return_policy_id' <<<"$ACTIVE"); do
    PRIORITY=$(flint "$API/v1/return-policies/$ID?expand=current_revision" | jq -r '.data.current_revision.priority')
    case "$PRIORITY" in
      200|100)
        echo "Stopped: active policy $ID already has priority $PRIORITY." >&2
        exit 1 ;;
    esac
  done
  PAGE=$(jq -r '.next_page_token // empty' <<<"$ACTIVE")
  [ -n "$PAGE" ] || break
done

# 2. The final-sale category, reused if you already have it. The
#    "Final sale" policy refuses products whose category_handles include it.
FOUND=$(flint "$API/v1/categories?handle=final-sale")
CATEGORY_ID=$(jq -r '.data[0].category_id // empty' <<<"$FOUND")
if [ -z "$CATEGORY_ID" ]; then
  CREATED=$(flint -X POST "$API/v1/categories" \
    -H "Idempotency-Key: final-sale-category-$RUN" \
    -d '{ "name": "Final sale", "handle": "final-sale" }')
  CATEGORY_ID=$(field "$CREATED" .data.category_id)
fi
echo "Category final-sale: $CATEGORY_ID"

# 3. Create "Final sale". New policies start inactive.
FINAL_SALE=$(flint -X POST "$API/v1/return-policies" \
  -H "Idempotency-Key: final-sale-$RUN" \
  -d @- <<JSON
{
  "name": "Final sale",
  "revision": {
    "priority": 200,
    "scope": {
      "match_type": "include",
      "category_handles": ["final-sale"]
    },
    "eligibility_result": "ineligible",
    "ineligibility_reason": "final_sale",
    "approval_mode": "manual",
    "is_merchandise_return_required": false
  }
}
JSON
)
FINAL_SALE_ID=$(field "$FINAL_SALE" .data.return_policy_id)
FINAL_SALE_VERSION=$(field "$FINAL_SALE" .data.version)

# Activate it so new Returns are matched against it.
flint -X PATCH "$API/v1/return-policies/$FINAL_SALE_ID" \
  -d "{ \"status\": \"active\", \"expected_version\": $FINAL_SALE_VERSION }" >/dev/null
echo "Activated Final sale: $FINAL_SALE_ID"
ACTIVATED="$ACTIVATED $FINAL_SALE_ID"

# 4. Create "Standard returns". New policies start inactive.
STANDARD_RETURNS=$(flint -X POST "$API/v1/return-policies" \
  -H "Idempotency-Key: standard-returns-$RUN" \
  -d @- <<JSON
{
  "name": "Standard returns",
  "revision": {
    "priority": 100,
    "scope": { "match_type": "all" },
    "eligibility_result": "eligible",
    "return_window": {
      "duration_seconds": 2592000,
      "starts_at_event": "delivered"
    },
    "allowed_resolution_types": ["refund", "exchange"],
    "approval_mode": "automatic",
    "resolution_mode": "manual",
    "completion_mode": "automatic",
    "release_timing": "after_receipt",
    "is_merchandise_return_required": true,
    "is_inspection_required": false,
    "receiving_location_id": "$RETURNS_LOCATION_ID",
    "return_shipping": { "payer": "buyer" }
  }
}
JSON
)
STANDARD_RETURNS_ID=$(field "$STANDARD_RETURNS" .data.return_policy_id)
STANDARD_RETURNS_VERSION=$(field "$STANDARD_RETURNS" .data.version)

# Activate it so new Returns are matched against it.
flint -X PATCH "$API/v1/return-policies/$STANDARD_RETURNS_ID" \
  -d "{ \"status\": \"active\", \"expected_version\": $STANDARD_RETURNS_VERSION }" >/dev/null
echo "Activated Standard returns: $STANDARD_RETURNS_ID"
ACTIVATED="$ACTIVATED $STANDARD_RETURNS_ID"