Integrate Fluveo with an AI agent

// Node 18 or later: fetch is built in.
const API = "https://api.fluveo.com/v1";
const KEY = process.env.FLUVEO_SECRET_KEY; // sk_test_...

async function fluveo(method, path, params, idempotencyKey) {
  const headers = { Authorization: `Bearer ${KEY}` };
  if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
  const query = method === "GET" && params ? "?" + new URLSearchParams(params) : "";
  const body = method === "POST" ? new URLSearchParams(params || {}) : undefined;
  const res = await fetch(API + path + query, { method, headers, body });
  const json = await res.json();
  if (!res.ok) throw Object.assign(new Error(json.error.message), { status: res.status, error: json.error, headers: res.headers });
  return json;
}

const account = await fluveo("GET", "/account");
console.log(account.id, account.default_currency);

import os
import requests

API = "https://api.fluveo.com/v1"
KEY = os.environ["FLUVEO_SECRET_KEY"]  # sk_test_...

class FluveoError(Exception):
    def __init__(self, status, error, retry_after=None, replayed=None):
        super().__init__(f"{status} {error}")
        self.status = status
        self.error = error
        self.retry_after = retry_after
        self.replayed = replayed

def fluveo(method, path, params=None, idempotency_key=None):
    headers = {"Authorization": f"Bearer {KEY}"}
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    response = requests.request(
        method,
        API + path,
        headers=headers,
        params=params if method == "GET" else None,
        data=params if method == "POST" else None,
        timeout=30,
    )
    body = response.json()
    if response.status_code >= 400:
        raise FluveoError(
            response.status_code,
            body["error"],
            response.headers.get("Retry-After"),
            response.headers.get("Idempotent-Replayed"),
        )
    return body

account = fluveo("GET", "/account")
print(account["id"], account["default_currency"])

<?php
class FluveoException extends RuntimeException
{
    public function __construct(
        public int $status,
        public ?array $error,
        public ?int $retryAfter = null,
        public ?string $replayed = null,
    )
    {
        parent::__construct($status . ' ' . json_encode($error), $status);
    }
}

function fluveo(string $method, string $path, array $params = [], ?string $idempotencyKey = null): array
{
    $url = 'https://api.fluveo.com/v1' . $path;
    $headers = ['Authorization: Bearer ' . getenv('FLUVEO_SECRET_KEY')];
    if ($idempotencyKey !== null) {
        $headers[] = 'Idempotency-Key: ' . $idempotencyKey;
    }
    $ch = curl_init();
    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
    } elseif ($params) {
        $url .= '?' . http_build_query($params);
    }
    $retryAfter = null;
    $replayed = null;
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_HEADERFUNCTION => function ($ch, string $line) use (&$retryAfter, &$replayed): int {
            if (preg_match('/^Retry-After:\s*(\d+)/i', $line, $m)) {
                $retryAfter = (int) $m[1];
            }
            if (preg_match('/^Idempotent-Replayed:\s*(\w+)/i', $line, $m)) {
                $replayed = strtolower($m[1]);
            }
            return strlen($line);
        },
    ]);
    $raw = curl_exec($ch);
    if ($raw === false) {
        throw new FluveoException(0, ['message' => curl_error($ch)]);
    }
    $body = json_decode($raw, true);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    if ($status >= 400) {
        throw new FluveoException($status, $body['error'], $retryAfter, $replayed);
    }
    return $body;
}

$account = fluveo('GET', '/account');
echo $account['id'], ' ', $account['default_currency'], "\n";

const METHODS = {
  card: {
    currency: "usd",
    "payment_method_types[]": "card",
    payment_method: "pm_card_visa",
  },
  pix: {
    currency: "brl",
    "payment_method_types[]": "pix",
    "payment_method_data[type]": "pix",
    "payment_method_data[billing_details][name]": "Ada Lima",
    "payment_method_data[billing_details][email]": "ada@example.com",
    "payment_method_data[billing_details][phone]": "+5511999999999",
    "payment_method_data[billing_details][tax_id]": "12345678909",
  },
};

async function pay(orderId, method) {
  const response = await fetch("https://api.fluveo.com/v1/payment_intents", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FLUVEO_SECRET_KEY}`,
      "Idempotency-Key": `order-${orderId}-pay`,
    },
    body: new URLSearchParams({
      amount: "2000",
      ...METHODS[method],
      confirm: "true",
      "metadata[order_id]": orderId,
    }),
  });
  return response.json();
}

const intent = await pay("1042", "card");
console.log(intent.id, intent.status); // pi_... succeeded; with "pix": requires_action

METHODS = {
    "card": {
        "currency": "usd",
        "payment_method_types[]": "card",
        "payment_method": "pm_card_visa",
    },
    "pix": {
        "currency": "brl",
        "payment_method_types[]": "pix",
        "payment_method_data[type]": "pix",
        "payment_method_data[billing_details][name]": "Ada Lima",
        "payment_method_data[billing_details][email]": "ada@example.com",
        "payment_method_data[billing_details][phone]": "+5511999999999",
        "payment_method_data[billing_details][tax_id]": "12345678909",
    },
}

intent = fluveo("POST", "/payment_intents", {
    "amount": 2000,
    **METHODS["card"],
    "confirm": "true",
    "metadata[order_id]": "1042",
}, idempotency_key="order-1042-pay")
print(intent["id"], intent["status"])  # pi_... succeeded; with "pix": requires_action

$methods = [
    'card' => [
        'currency' => 'usd',
        'payment_method_types[]' => 'card',
        'payment_method' => 'pm_card_visa',
    ],
    'pix' => [
        'currency' => 'brl',
        'payment_method_types[]' => 'pix',
        'payment_method_data[type]' => 'pix',
        'payment_method_data[billing_details][name]' => 'Ada Lima',
        'payment_method_data[billing_details][email]' => 'ada@example.com',
        'payment_method_data[billing_details][phone]' => '+5511999999999',
        'payment_method_data[billing_details][tax_id]' => '12345678909',
    ],
];

$intent = fluveo('POST', '/payment_intents', [
    'amount' => 2000,
    ...$methods['card'],
    'confirm' => 'true',
    'metadata[order_id]' => '1042',
], 'order-1042-pay');
echo $intent['id'], ' ', $intent['status'], "\n"; // pi_... succeeded; with 'pix': requires_action

const boleto = await fluveo("POST", "/payment_intents", {
  amount: "1500",
  currency: "brl",
  "payment_method_types[]": "boleto",
  confirm: "true",
  "payment_method_data[type]": "boleto",
  "payment_method_data[boleto][tax_id]": "12345678909",
  "payment_method_data[billing_details][name]": "Ada Lima",
  "payment_method_data[billing_details][email]": "ada@example.com",
  "payment_method_data[billing_details][address][line1]": "1000, Av. Paulista, Bela Vista",
  "payment_method_data[billing_details][address][line2]": "Bela Vista",
  "payment_method_data[billing_details][address][city]": "Sao Paulo",
  "payment_method_data[billing_details][address][state]": "SP",
  "payment_method_data[billing_details][address][postal_code]": "01310100",
  "payment_method_data[billing_details][address][country]": "BR",
  "payment_method_options[boleto][expires_after_days]": "3",
}, "order-2002-pay");
console.log(boleto.status, boleto.next_action.boleto_display_details.number);

boleto = fluveo("POST", "/payment_intents", {
    "amount": 1500,
    "currency": "brl",
    "payment_method_types[]": "boleto",
    "confirm": "true",
    "payment_method_data[type]": "boleto",
    "payment_method_data[boleto][tax_id]": "12345678909",
    "payment_method_data[billing_details][name]": "Ada Lima",
    "payment_method_data[billing_details][email]": "ada@example.com",
    "payment_method_data[billing_details][address][line1]": "1000, Av. Paulista, Bela Vista",
    "payment_method_data[billing_details][address][line2]": "Bela Vista",
    "payment_method_data[billing_details][address][city]": "Sao Paulo",
    "payment_method_data[billing_details][address][state]": "SP",
    "payment_method_data[billing_details][address][postal_code]": "01310100",
    "payment_method_data[billing_details][address][country]": "BR",
    "payment_method_options[boleto][expires_after_days]": 3,
}, idempotency_key="order-2002-pay")
print(boleto["status"], boleto["next_action"]["boleto_display_details"]["number"])

$boleto = fluveo('POST', '/payment_intents', [
    'amount' => 1500,
    'currency' => 'brl',
    'payment_method_types[]' => 'boleto',
    'confirm' => 'true',
    'payment_method_data[type]' => 'boleto',
    'payment_method_data[boleto][tax_id]' => '12345678909',
    'payment_method_data[billing_details][name]' => 'Ada Lima',
    'payment_method_data[billing_details][email]' => 'ada@example.com',
    'payment_method_data[billing_details][address][line1]' => '1000, Av. Paulista, Bela Vista',
    'payment_method_data[billing_details][address][line2]' => 'Bela Vista',
    'payment_method_data[billing_details][address][city]' => 'Sao Paulo',
    'payment_method_data[billing_details][address][state]' => 'SP',
    'payment_method_data[billing_details][address][postal_code]' => '01310100',
    'payment_method_data[billing_details][address][country]' => 'BR',
    'payment_method_options[boleto][expires_after_days]' => 3,
], 'order-2002-pay');
echo $boleto['status'], ' ', $boleto['next_action']['boleto_display_details']['number'], "\n";

const params = new URLSearchParams({ url: "https://example.com/webhooks/fluveo" });
for (const type of ["payment_intent.succeeded", "payment_intent.payment_failed", "charge.refunded", "refund.failed"]) {
  params.append("enabled_events[]", type);
}
const endpoint = await fluveo("POST", "/webhook_endpoints", params, "webhook-endpoint-production-v1");
console.log(endpoint.id); // we_...
// Store endpoint.secret (whsec_...) as FLUVEO_WEBHOOK_SECRET now.

endpoint = fluveo("POST", "/webhook_endpoints", [
    ("url", "https://example.com/webhooks/fluveo"),
    ("enabled_events[]", "payment_intent.succeeded"),
    ("enabled_events[]", "payment_intent.payment_failed"),
    ("enabled_events[]", "charge.refunded"),
    ("enabled_events[]", "refund.failed"),
], idempotency_key="webhook-endpoint-production-v1")
print(endpoint["id"])  # we_...
# Store endpoint["secret"] (whsec_...) as FLUVEO_WEBHOOK_SECRET now.

// http_build_query cannot repeat a key, so this call builds the body by hand.
$body = 'url=' . urlencode('https://example.com/webhooks/fluveo');
foreach (['payment_intent.succeeded', 'payment_intent.payment_failed', 'charge.refunded', 'refund.failed'] as $type) {
    $body .= '&' . urlencode('enabled_events[]') . '=' . urlencode($type);
}
$ch = curl_init('https://api.fluveo.com/v1/webhook_endpoints');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('FLUVEO_SECRET_KEY'),
        'Idempotency-Key: webhook-endpoint-production-v1',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$endpoint = json_decode(curl_exec($ch), true);
echo $endpoint['id'], "\n"; // we_...
// Store $endpoint['secret'] (whsec_...) as FLUVEO_WEBHOOK_SECRET now.

import hashlib
import hmac
import json
import os
import re
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET = os.environ["FLUVEO_WEBHOOK_SECRET"].encode()  # whsec_...
TOLERANCE_SECONDS = 300
# One file per handled evt_ id survives a restart. In production, use a table with a unique evt_ id instead,
# written in the same transaction as the order change.
HANDLED_DIR = os.environ.get("FLUVEO_HANDLED_DIR", "./fluveo-handled-events")
os.makedirs(HANDLED_DIR, exist_ok=True)


def claim(event_id: str) -> bool:
    if not re.fullmatch(r"evt_[A-Za-z0-9_]+", event_id):
        raise ValueError("not an event id")
    try:
        os.close(os.open(os.path.join(HANDLED_DIR, event_id), os.O_CREAT | os.O_EXCL | os.O_WRONLY))
        return True
    except FileExistsError:
        return False


def release(event_id: str) -> None:
    try:
        os.remove(os.path.join(HANDLED_DIR, event_id))
    except FileNotFoundError:
        pass


def handle_event(event: dict) -> None:
    obj = event["data"]["object"]
    if event["type"] == "payment_intent.succeeded":
        print("paid: mark the order paid and fulfil it", obj["metadata"].get("order_id"), obj["id"])
    elif event["type"] == "payment_intent.payment_failed":
        print("failed: tell the buyer to try again", obj["metadata"].get("order_id"), obj["id"])
    elif event["type"] == "charge.refunded":
        print("refunded: record the refund on the order", obj["payment_intent"], obj["id"])
    elif event["type"] == "refund.failed":
        print("refund failed: flag the order for a person", obj["payment_intent"], obj["id"])


def verify(raw_body: bytes, header: str, now: int = None) -> bool:
    t, signatures = None, []
    for part in (header or "").split(","):
        key, _, value = part.strip().partition("=")
        if key == "t":
            t = value
        elif key == "v1":
            signatures.append(value)
    if not t or not t.isdigit():
        return False
    now = int(time.time()) if now is None else now
    if abs(now - int(t)) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(SECRET, t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, signature) for signature in signatures)


class Webhook(BaseHTTPRequestHandler):
    def do_POST(self):
        if self.path != "/webhooks/fluveo":
            self.send_response(404)
            self.end_headers()
            return
        raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        if not verify(raw, self.headers.get("Fluveo-Signature")):
            self.send_response(400)
            self.end_headers()
            return
        event = json.loads(raw)
        if claim(event["id"]):
            try:
                handle_event(event)
            except Exception:
                release(event["id"])
                self.send_response(500)
                self.end_headers()
                return
        self.send_response(200)
        self.end_headers()


HTTPServer(("", 4242), Webhook).serve_forever()

<?php
// php -S 0.0.0.0:4242 webhook.php
if ($_SERVER['REQUEST_METHOD'] !== 'POST' || parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH) !== '/webhooks/fluveo') {
    http_response_code(404);
    exit;
}
$secret = getenv('FLUVEO_WEBHOOK_SECRET'); // whsec_...
$raw = file_get_contents('php://input');
$header = $_SERVER['HTTP_FLUVEO_SIGNATURE'] ?? '';

$t = null;
$signatures = [];
foreach (explode(',', $header) as $part) {
    [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
    if ($key === 't') {
        $t = $value;
    } elseif ($key === 'v1') {
        $signatures[] = $value;
    }
}

$valid = false;
if ($t !== null && ctype_digit($t) && abs(time() - (int) $t) <= 300) {
    $expected = hash_hmac('sha256', $t . '.' . $raw, $secret);
    foreach ($signatures as $signature) {
        if (hash_equals($expected, $signature)) {
            $valid = true;
        }
    }
}
if (!$valid) {
    http_response_code(400);
    exit('invalid signature');
}

$event = json_decode($raw, true);

// One file per handled evt_ id survives a restart. In production, use a table with a unique evt_ id instead,
// written in the same transaction as the order change.
$handledDir = getenv('FLUVEO_HANDLED_DIR') ?: __DIR__ . '/fluveo-handled-events';
if (!is_dir($handledDir)) {
    mkdir($handledDir, 0700, true);
}
if (!preg_match('/^evt_[A-Za-z0-9_]+$/', $event['id'] ?? '')) {
    http_response_code(400);
    exit('not an event id');
}
$claimFile = $handledDir . '/' . $event['id'];
$claim = @fopen($claimFile, 'x');
if ($claim === false) {
    http_response_code(file_exists($claimFile) ? 200 : 500);
    exit;
}
fclose($claim);

function handleEvent(array $event): void
{
    $object = $event['data']['object'];
    switch ($event['type']) {
        case 'payment_intent.succeeded':
            error_log('paid: mark the order paid and fulfil it ' . ($object['metadata']['order_id'] ?? '') . ' ' . $object['id']);
            break;
        case 'payment_intent.payment_failed':
            error_log('failed: tell the buyer to try again ' . ($object['metadata']['order_id'] ?? '') . ' ' . $object['id']);
            break;
        case 'charge.refunded':
            error_log('refunded: record the refund on the order ' . $object['payment_intent'] . ' ' . $object['id']);
            break;
        case 'refund.failed':
            error_log('refund failed: flag the order for a person ' . $object['payment_intent'] . ' ' . $object['id']);
            break;
    }
}

try {
    handleEvent($event);
} catch (Throwable $err) {
    unlink($claimFile);
    http_response_code(500);
    exit;
}
http_response_code(200);

const refund = await fluveo("POST", "/refunds", {
  payment_intent: intent.id,
  amount: "500",
}, "order-1042-refund-1");
console.log(refund.id, refund.status); // re_...

refund = fluveo("POST", "/refunds", {
    "payment_intent": intent["id"],
    "amount": 500,
}, idempotency_key="order-1042-refund-1")
print(refund["id"], refund["status"])  # re_...

$refund = fluveo('POST', '/refunds', [
    'payment_intent' => $intent['id'],
    'amount' => 500,
], 'order-1042-refund-1');
echo $refund['id'], ' ', $refund['status'], "\n"; // re_...

async function withRetries(method, path, params, idempotencyKey, tries = 4) {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fluveo(method, path, params, idempotencyKey);
    } catch (err) {
      const unknownResult = err.status === 500 && err.headers?.get("idempotent-replayed") === "true";
      const retryable = !unknownResult && (!err.status || err.status >= 500 || err.status === 409 || err.status === 429);
      if (!retryable || attempt === tries) throw err;
      const retryAfterMs = err.status === 429 ? Number(err.headers.get("retry-after")) * 1000 || 0 : 0;
      await new Promise((resolve) => setTimeout(resolve, Math.max(2 ** attempt * 500, retryAfterMs)));
    }
  }
}

import time

import requests


def with_retries(method, path, params, idempotency_key, tries=4):
    for attempt in range(1, tries + 1):
        wait = 2 ** attempt * 0.5
        try:
            return fluveo(method, path, params, idempotency_key)
        except (requests.ConnectionError, requests.Timeout):
            if attempt == tries:
                raise
        except FluveoError as err:
            unknown_result = err.status == 500 and (err.replayed or "").lower() == "true"
            retryable = not unknown_result and (err.status >= 500 or err.status in (409, 429))
            if not retryable or attempt == tries:
                raise
            if err.status == 429 and err.retry_after and err.retry_after.isdigit():
                wait = max(wait, int(err.retry_after))
        time.sleep(wait)

function withRetries(string $method, string $path, array $params, string $idempotencyKey, int $tries = 4): array
{
    for ($attempt = 1; ; $attempt++) {
        try {
            return fluveo($method, $path, $params, $idempotencyKey);
        } catch (FluveoException $err) {
            $unknownResult = $err->status === 500 && $err->replayed === 'true';
            $retryable = !$unknownResult
                && ($err->status === 0 || $err->status >= 500 || $err->status === 409 || $err->status === 429);
            if (!$retryable || $attempt === $tries) {
                throw $err;
            }
            $wait = (2 ** $attempt) * 0.5;
            if ($err->status === 429 && $err->retryAfter !== null) {
                $wait = max($wait, $err->retryAfter);
            }
            usleep((int) ($wait * 1000000));
        }
    }
}