Fund your balance and withdraw

# Reads the balance deliveries are paid from, then moves part of it to the bank
# account on file.
#
#   LISTO_API_KEY=lst_test_... ruby balance_and_withdrawal.rb
#
require "json"
require "net/http"
require "uri"

BASE_URL = ENV.fetch("LISTO_API_BASE_URL", "https://api.listo.delivery")
API_KEY = ENV.fetch("LISTO_API_KEY")

# The refusal envelope every Listo error carries, or a stand-in built from the
# status when the body is not that envelope at all. Something between you and
# Listo, a proxy or a load balancer, can answer with an HTML error page or with
# JSON of some other shape, and the code that handles a failure must not itself
# fail trying to read it.
def parse_error(response)
  stand_in = {"code" => "HTTP #{response.code}", "param" => nil}
  body = JSON.parse(response.body.to_s)
  error = body["error"] if body.is_a?(Hash)
  error.is_a?(Hash) ? error : stand_in
rescue JSON::ParserError
  stand_in
end

def request(verb, path, payload = nil)
  uri = URI("#{BASE_URL}#{path}")

  request = verb.new(uri)
  request["Authorization"] = "Bearer #{API_KEY}"

  if payload
    request["Content-Type"] = "application/json"
    request.body = JSON.generate(payload)
  end

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
    http.request(request)
  end

  # Check the status BEFORE parsing the body.
  abort("#{path} refused: #{parse_error(response)["code"]}") unless response.code.start_with?("2")

  JSON.parse(response.body)
end

# `balance_cents` is everything the account holds. `available_cents` is the part
# that can leave it today: cash a courier collected is on the balance from the
# moment it is delivered, but it is only withdrawable once it has been settled.
# Deliveries spend against the balance, withdrawals against the available part.
balance = request(Net::HTTP::Get, "/v1/balance")

puts "balance #{balance["balance_cents"]} #{balance["currency"]}"
puts "available #{balance["available_cents"]}"

# Asking for more than is available is refused with `insufficient_balance`, so
# ask for what the last read said was there.
withdrawal = request(
  Net::HTTP::Post,
  "/v1/withdrawals",
  {"amount_cents" => balance["available_cents"]}
)

# The money is reserved the moment this returns: it leaves `available_cents`
# straight away and the transfer follows. You learn the outcome from the
# `withdrawal.updated` event, or by reading the withdrawal back.
puts "withdrawal #{withdrawal["id"]} is #{withdrawal["status"]}"

# Walks every wasted-trip charge on your balance, so each one can be billed to
# the order that caused it. A cancellation once a courier was already working,
# or a return trip after a failed dropoff, is billed at the delivery fee for
# each leg that was driven and lands on the ledger as a `provider_charge`.
#
#   LISTO_API_KEY=lst_test_... ruby reconcile_charges.rb
#
require "json"
require "net/http"
require "uri"

BASE_URL = ENV.fetch("LISTO_API_BASE_URL", "https://api.listo.delivery")
API_KEY = ENV.fetch("LISTO_API_KEY")

# The refusal envelope every Listo error carries, or a stand-in built from the
# status when the body is not that envelope at all. Something between you and
# Listo, a proxy or a load balancer, can answer with an HTML error page or with
# JSON of some other shape, and the code that handles a failure must not itself
# fail trying to read it.
def parse_error(response)
  stand_in = {"code" => "HTTP #{response.code}", "param" => nil}
  body = JSON.parse(response.body.to_s)
  error = body["error"] if body.is_a?(Hash)
  error.is_a?(Hash) ? error : stand_in
rescue JSON::ParserError
  stand_in
end

def get(path, query)
  uri = URI("#{BASE_URL}#{path}")
  uri.query = URI.encode_www_form(query)

  request = Net::HTTP::Get.new(uri)
  request["Authorization"] = "Bearer #{API_KEY}"

  response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
    http.request(request)
  end

  # Check the status BEFORE parsing the body.
  abort("GET #{path} refused: #{parse_error(response)["code"]}") unless response.code == "200"

  JSON.parse(response.body)
end

# Reconcile from the ledger rather than from the events you received. Events are
# a notification that something happened, at least once and in no order; this is
# the money itself, once each and in order. It is also the only place a cost
# that posted after an order finished is guaranteed to be waiting for you.
#
# `type` narrows the ledger to those charges. Every other movement,
# your share of a delivery fee and its refund, cash earnings, top-ups and
# withdrawals, stays out of this walk.
cursor = nil
count = 0
total = 0

loop do
  query = {"type" => "provider_charge"}
  query["cursor"] = cursor if cursor

  page = get("/v1/ledger", query)

  page["data"].each do |entry|
    count += 1

    # SIGNED cents, so a charge is negative because it left your balance.
    # Adding the rows up is the whole sum; taking an absolute value here would
    # turn every charge into a credit.
    total += entry["amount_cents"]

    # The order to bill this to. Match it against the id you stored when you
    # created the delivery, or read the order back with
    # GET /v1/deliveries/<id> for your own `external_id`.
    #
    # Every wasted-trip charge names its order, including the orders your
    # stores dispatched from their own Listo console. Those carry no
    # `external_id`, because you never sent one, so read them back by their
    # `dlv_` id.
    #
    # Null means the movement belongs to no order at all: a top-up, a
    # withdrawal or an adjustment. It cannot reach this walk while the `type`
    # filter is on, and the fallback is here for when you widen it. Bill nobody
    # for such a row rather than attributing it to whichever order came next.
    order = entry["delivery_id"] || "(no order)"

    puts "#{order} #{entry["amount_cents"]}"
  end

  # Every list on this API answers the same shape: `data`, `has_more`, and an
  # opaque `cursor`. Keep passing the cursor back until `has_more` is false. A
  # walk that reads one page and stops would bill only your most recent orders.
  break unless page["has_more"]

  cursor = page["cursor"]
end

puts "charges #{count}"
puts "total #{total}"