openhub-bo-core 0.1.0

data/ext/openhub_bo_core/vendor/openhub-bo-core/src/http.rs

@@ -0,0 +1,40 @@
+use std::collections::BTreeMap;
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "UPPERCASE")]
+pub enum Method {
+    Get,
+    Post,
+    Patch,
+}
+
+/// A request the host must send verbatim.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct HttpRequest {
+    pub method: Method,
+    pub url: String,
+    pub headers: BTreeMap<String, String>,
+    pub body: Option<String>,
+}
+
+/// What the host got back. Only status and body matter to the core.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct HttpResponse {
+    pub status: u16,
+    pub body: String,
+}
+
+impl HttpResponse {
+    pub fn new(status: u16, body: impl Into<String>) -> Self {
+        Self {
+            status,
+            body: body.into(),
+        }
+    }
+
+    pub fn is_success(&self) -> bool {
+        (200..300).contains(&self.status)
+    }
+}

data/ext/openhub_bo_core/vendor/openhub-bo-core/src/lib.rs

@@ -0,0 +1,33 @@
+//! Sans-IO core for the Red Enlace (ATC) OpenHub payment APIs.
+//!
+//! This crate never performs network I/O. Each endpoint is an [`Operation`]
+//! that builds an [`HttpRequest`] and parses an [`HttpResponse`]; the host
+//! language executes the HTTP call with its own client. Bindings reach the
+//! operations through a [`Registry`] and the JSON boundary in [`ffi`].
+
+pub mod amount;
+mod config;
+pub mod envelope;
+mod error;
+pub mod ffi;
+mod http;
+mod operation;
+pub mod status;
+mod token;
+pub mod validate;
+pub mod webhook;
+
+pub use config::{Config, Environment};
+pub use error::{ApiFieldError, Error, Result};
+pub use http::{HttpRequest, HttpResponse, Method};
+pub use operation::{Chain, Ctx, Handler, OpInfo, Operation, Registry};
+pub use status::PaymentStatus;
+pub use token::{AccessToken, EXPIRY_SKEW_SECS, Token, TokenInput};
+pub use webhook::{WebhookCall, WebhookTarget};
+
+// Operations shared by every product package. Product crates declare their
+// own registry and bindings combine them with [`Chain`].
+registry!(pub CoreOps {
+    operations: [Token],
+    handlers: [],
+});

data/ext/openhub_bo_core/vendor/openhub-bo-core/src/operation.rs

@@ -0,0 +1,190 @@
+//! One type per endpoint ([`Operation`]) or pure function ([`Handler`]), and
+//! a [`registry!`](crate::registry) macro that exposes them over the FFI.
+//!
+//! Adding an endpoint means writing one `Operation` impl and listing it in a
+//! registry; bindings pick it up through `call(op, payload)` without changes.
+
+use std::collections::BTreeMap;
+
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+
+use crate::config::Config;
+use crate::error::{Error, Result};
+use crate::ffi::JsonValue;
+use crate::http::{HttpRequest, HttpResponse};
+use crate::token::AccessToken;
+
+/// What an operation needs to build its request.
+#[derive(Debug, Clone, Copy)]
+pub struct Ctx<'a> {
+    pub config: &'a Config,
+    pub token: Option<&'a AccessToken>,
+}
+
+impl<'a> Ctx<'a> {
+    pub fn new(config: &'a Config, token: Option<&'a AccessToken>) -> Self {
+        Self { config, token }
+    }
+
+    pub fn token(&self) -> Result<&'a AccessToken> {
+        self.token.ok_or_else(|| {
+            Error::validation("token", "an access token is required for this operation")
+        })
+    }
+
+    /// Headers for business calls. The gateway (Sensedia) reads the token from
+    /// `access_token` (verified in the sandbox: `Authorization: Bearer` alone
+    /// gets a 401); the Bearer header is what the docs' tables describe, so
+    /// both are sent.
+    /// [`Ctx::api_headers`] plus product-specific headers (e.g. `branchCode`).
+    pub fn api_headers_with(&self, extra: &[(&str, &str)]) -> Result<BTreeMap<String, String>> {
+        let mut headers = self.api_headers()?;
+        headers.extend(
+            extra
+                .iter()
+                .map(|(k, v)| ((*k).to_owned(), (*v).to_owned())),
+        );
+        Ok(headers)
+    }
+
+    pub fn api_headers(&self) -> Result<BTreeMap<String, String>> {
+        let token = self.token()?;
+        Ok(BTreeMap::from([
+            ("Authorization".to_owned(), token.authorization()),
+            ("access_token".to_owned(), token.access_token.clone()),
+            ("client_id".to_owned(), self.config.client_id.clone()),
+            ("Content-Type".to_owned(), "application/json".to_owned()),
+            ("Accept".to_owned(), "application/json".to_owned()),
+        ]))
+    }
+}
+
+/// An HTTP endpoint: builds the request and parses the response.
+pub trait Operation {
+    /// FFI name, e.g. `qr.generate`. Stages are `<NAME>.build` / `<NAME>.parse`.
+    const NAME: &'static str;
+    /// Safe to repeat. When false, a lost response leaves the outcome unknown
+    /// (e.g. a QR may have been created).
+    const IDEMPOTENT: bool;
+    /// Client timeout recommended by ATC for this endpoint, if any.
+    const TIMEOUT_SECS: Option<u32> = None;
+
+    type Input: DeserializeOwned;
+    type Output: Serialize;
+
+    fn request(ctx: &Ctx<'_>, input: &Self::Input) -> Result<HttpRequest>;
+    fn response(response: &HttpResponse, input: &Self::Input) -> Result<Self::Output>;
+}
+
+/// A pure function without HTTP, e.g. webhook parsing.
+pub trait Handler {
+    const NAME: &'static str;
+
+    type Input: DeserializeOwned;
+    type Output: Serialize;
+
+    fn handle(input: Self::Input) -> Result<Self::Output>;
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum OpInfo {
+    Operation {
+        name: &'static str,
+        idempotent: bool,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        timeout_secs: Option<u32>,
+    },
+    Handler {
+        name: &'static str,
+    },
+}
+
+impl OpInfo {
+    pub fn operation<O: Operation>() -> Self {
+        OpInfo::Operation {
+            name: O::NAME,
+            idempotent: O::IDEMPOTENT,
+            timeout_secs: O::TIMEOUT_SECS,
+        }
+    }
+
+    pub fn handler<H: Handler>() -> Self {
+        OpInfo::Handler { name: H::NAME }
+    }
+}
+
+/// A set of operations exposed over the FFI. Implement it with
+/// [`registry!`](crate::registry).
+pub trait Registry {
+    fn dispatch(&self, op: &str, payload: &str) -> Option<Result<JsonValue>>;
+    fn operations(&self) -> Vec<OpInfo>;
+}
+
+/// Two registries exposed as one; `a` wins on name clashes.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct Chain<A, B>(pub A, pub B);
+
+impl<A: Registry, B: Registry> Registry for Chain<A, B> {
+    fn dispatch(&self, op: &str, payload: &str) -> Option<Result<JsonValue>> {
+        self.0
+            .dispatch(op, payload)
+            .or_else(|| self.1.dispatch(op, payload))
+    }
+
+    fn operations(&self) -> Vec<OpInfo> {
+        let mut ops = self.0.operations();
+        ops.extend(self.1.operations());
+        ops
+    }
+}
+
+/// Declares a unit struct implementing [`Registry`]:
+///
+/// ```ignore
+/// openhub_bo_core::registry!(pub OpenHub {
+///     operations: [Token, qr::Generate, qr::Verify],
+///     handlers: [qr::ParseWebhook],
+/// });
+/// ```
+#[macro_export]
+macro_rules! registry {
+    ($vis:vis $name:ident {
+        operations: [$($op:ty),* $(,)?],
+        handlers: [$($handler:ty),* $(,)?] $(,)?
+    }) => {
+        #[derive(Debug, Clone, Copy, Default)]
+        $vis struct $name;
+
+        impl $crate::Registry for $name {
+            fn dispatch(
+                &self,
+                op: &str,
+                payload: &str,
+            ) -> ::core::option::Option<$crate::Result<$crate::ffi::JsonValue>> {
+                $(
+                    if let ::core::option::Option::Some(stage) = op
+                        .strip_prefix(<$op as $crate::Operation>::NAME)
+                        .and_then(|rest| rest.strip_prefix('.'))
+                    {
+                        return ::core::option::Option::Some($crate::ffi::run::<$op>(stage, payload));
+                    }
+                )*
+                $(
+                    if op == <$handler as $crate::Handler>::NAME {
+                        return ::core::option::Option::Some($crate::ffi::run_handler::<$handler>(payload));
+                    }
+                )*
+                ::core::option::Option::None
+            }
+
+            fn operations(&self) -> ::std::vec::Vec<$crate::OpInfo> {
+                ::std::vec![
+                    $($crate::OpInfo::operation::<$op>(),)*
+                    $($crate::OpInfo::handler::<$handler>(),)*
+                ]
+            }
+        }
+    };
+}

data/ext/openhub_bo_core/vendor/openhub-bo-core/src/status.rs

@@ -0,0 +1,117 @@
+//! Payment status shared by every product family. Each family maps its own
+//! wire vocabulary through a [`StatusVocabulary`]; callers keep the original
+//! value in `raw_status` for auditing.
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum PaymentStatus {
+    Pending,
+    Processing,
+    Paid,
+    Cancelled,
+    Expired,
+    Rejected,
+    Reversed,
+    Error,
+    /// Not in any documented vocabulary; see `raw_status`.
+    Unknown,
+}
+
+impl PaymentStatus {
+    /// No further transitions are expected from this state.
+    pub fn is_final(self) -> bool {
+        !matches!(
+            self,
+            PaymentStatus::Pending | PaymentStatus::Processing | PaymentStatus::Unknown
+        )
+    }
+}
+
+/// Maps a product family's raw status strings to [`PaymentStatus`].
+pub trait StatusVocabulary {
+    fn map(raw: &str) -> PaymentStatus;
+}
+
+/// QR Simple / MLD-BCB `estado`.
+pub struct SpanishQr;
+
+/// PIX / virtual assets / Binance `codigoRespuesta`.
+pub struct EnglishCodes;
+
+/// Synchronous and asynchronous payouts `estado`.
+pub struct Payout;
+
+fn normalize(raw: &str) -> String {
+    raw.trim().to_ascii_uppercase()
+}
+
+impl StatusVocabulary for SpanishQr {
+    fn map(raw: &str) -> PaymentStatus {
+        match normalize(raw).as_str() {
+            "PENDIENTE" => PaymentStatus::Pending,
+            "PAGADO" => PaymentStatus::Paid,
+            "CANCELADO" => PaymentStatus::Cancelled,
+            "EXPIRADO" => PaymentStatus::Expired,
+            "ERROR" => PaymentStatus::Error,
+            _ => PaymentStatus::Unknown,
+        }
+    }
+}
+
+impl StatusVocabulary for EnglishCodes {
+    fn map(raw: &str) -> PaymentStatus {
+        match normalize(raw).as_str() {
+            "PENDING" => PaymentStatus::Pending,
+            "PAID" | "SUCCESS" => PaymentStatus::Paid,
+            "CANCELLED" => PaymentStatus::Cancelled,
+            "EXPIRED" => PaymentStatus::Expired,
+            "ERROR" => PaymentStatus::Error,
+            _ => PaymentStatus::Unknown,
+        }
+    }
+}
+
+impl StatusVocabulary for Payout {
+    fn map(raw: &str) -> PaymentStatus {
+        match normalize(raw).as_str() {
+            "PENDIENTE" | "PENDIENTE_PAGO" | "INICIALIZADO" => PaymentStatus::Pending,
+            "EN_PROCESO" | "PROCESO" | "ENVIADO" | "TRANSITO" | "PENDIENTE_CONFIRMACION" => {
+                PaymentStatus::Processing
+            }
+            "APROBADA" | "PAGADO" | "COMPLETADO" => PaymentStatus::Paid,
+            "RECHAZADA" | "RECHAZADO" => PaymentStatus::Rejected,
+            "REVERTIDO" => PaymentStatus::Reversed,
+            "CANCELADO" => PaymentStatus::Cancelled,
+            "ERROR" => PaymentStatus::Error,
+            _ => PaymentStatus::Unknown,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn maps_each_vocabulary() {
+        assert_eq!(SpanishQr::map(" pagado "), PaymentStatus::Paid);
+        assert_eq!(SpanishQr::map("NUEVO"), PaymentStatus::Unknown);
+        assert_eq!(EnglishCodes::map("SUCCESS"), PaymentStatus::Paid);
+        assert_eq!(EnglishCodes::map("CANCELLED"), PaymentStatus::Cancelled);
+        assert_eq!(
+            Payout::map("PENDIENTE_CONFIRMACION"),
+            PaymentStatus::Processing
+        );
+        assert_eq!(Payout::map("APROBADA"), PaymentStatus::Paid);
+        assert_eq!(Payout::map("REVERTIDO"), PaymentStatus::Reversed);
+    }
+
+    #[test]
+    fn finality() {
+        assert!(PaymentStatus::Paid.is_final());
+        assert!(!PaymentStatus::Processing.is_final());
+        assert!(!PaymentStatus::Unknown.is_final());
+    }
+}

data/ext/openhub_bo_core/vendor/openhub-bo-core/src/token.rs

@@ -0,0 +1,170 @@
+use std::collections::BTreeMap;
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+use crate::config::Config;
+use crate::envelope::message_from_body;
+use crate::error::{Error, Result};
+use crate::http::{HttpRequest, HttpResponse, Method};
+use crate::operation::{Ctx, Operation};
+
+/// Tokens are treated as expired this many seconds early to absorb clock
+/// skew and request latency.
+pub const EXPIRY_SKEW_SECS: i64 = 60;
+
+const TOKEN_PATH: &str = "oauth-client-credentials/access-token?grant_type=client_credentials";
+
+#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct AccessToken {
+    pub access_token: String,
+    pub token_type: String,
+    /// Unix timestamp (seconds) after which the token must be refreshed.
+    pub expires_at: i64,
+    pub scope: Option<String>,
+}
+
+impl AccessToken {
+    pub fn is_valid(&self, now: i64) -> bool {
+        now < self.expires_at
+    }
+
+    pub(crate) fn authorization(&self) -> String {
+        format!("Bearer {}", self.access_token)
+    }
+}
+
+impl fmt::Debug for AccessToken {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("AccessToken")
+            .field("access_token", &"***")
+            .field("token_type", &self.token_type)
+            .field("expires_at", &self.expires_at)
+            .field("scope", &self.scope)
+            .finish()
+    }
+}
+
+#[derive(Deserialize)]
+struct TokenResponse {
+    access_token: String,
+    #[serde(default = "default_token_type")]
+    token_type: String,
+    #[serde(default = "default_expires_in")]
+    expires_in: i64,
+    #[serde(default)]
+    scope: Option<String>,
+}
+
+fn default_token_type() -> String {
+    "Bearer".to_owned()
+}
+
+fn default_expires_in() -> i64 {
+    3600
+}
+
+/// OAuth 2.0 client-credentials request.
+fn build_token_request(config: &Config) -> Result<HttpRequest> {
+    let headers = BTreeMap::from([
+        ("Authorization".to_owned(), config.basic_authorization()?),
+        (
+            "Content-Type".to_owned(),
+            "application/x-www-form-urlencoded".to_owned(),
+        ),
+        ("Accept".to_owned(), "application/json".to_owned()),
+    ]);
+    Ok(HttpRequest {
+        method: Method::Post,
+        url: config.url(TOKEN_PATH),
+        headers,
+        body: None,
+    })
+}
+
+fn parse_token_response(response: &HttpResponse, now: i64) -> Result<AccessToken> {
+    if !response.is_success() {
+        return Err(Error::Authentication {
+            status: response.status,
+            message: message_from_body(&response.body),
+        });
+    }
+    let parsed: TokenResponse = serde_json::from_str(&response.body)
+        .map_err(|e| Error::decode(format!("invalid token response: {e}")))?;
+    if parsed.access_token.is_empty() {
+        return Err(Error::decode("token response has an empty access_token"));
+    }
+    let lifetime = (parsed.expires_in - EXPIRY_SKEW_SECS).max(0);
+    Ok(AccessToken {
+        access_token: parsed.access_token,
+        token_type: parsed.token_type,
+        expires_at: now + lifetime,
+        scope: parsed.scope,
+    })
+}
+
+/// OAuth 2.0 client credentials. Sandbox answers HTTP 201 with
+/// `token_type: "access_token"` and no `scope`.
+pub struct Token;
+
+#[derive(Debug, Clone, Deserialize)]
+pub struct TokenInput {
+    /// Current Unix time in seconds, supplied by the host (the core has no clock).
+    pub now: i64,
+}
+
+impl Operation for Token {
+    const NAME: &'static str = "token";
+    const IDEMPOTENT: bool = true;
+
+    type Input = TokenInput;
+    type Output = AccessToken;
+
+    fn request(ctx: &Ctx<'_>, _input: &TokenInput) -> Result<HttpRequest> {
+        build_token_request(ctx.config)
+    }
+
+    fn response(response: &HttpResponse, input: &TokenInput) -> Result<AccessToken> {
+        parse_token_response(response, input.now)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const FIXTURE: &str = include_str!("../../../fixtures/openhub/token_response.json");
+
+    #[test]
+    fn builds_client_credentials_request() {
+        let request = build_token_request(&Config::new("id", "secret")).unwrap();
+        assert_eq!(request.method, Method::Post);
+        assert_eq!(
+            request.url,
+            "https://atcgwapitest.redenlace.com.bo/sandbox/oauth-client-credentials/access-token?grant_type=client_credentials"
+        );
+        assert_eq!(request.headers["Authorization"], "Basic aWQ6c2VjcmV0");
+    }
+
+    #[test]
+    fn parses_token_with_skew() {
+        let token = parse_token_response(&HttpResponse::new(200, FIXTURE), 1_000).unwrap();
+        assert_eq!(token.expires_at, 1_000 + 3600 - EXPIRY_SKEW_SECS);
+        assert_eq!(token.scope.as_deref(), Some("api.qr"));
+        assert!(token.is_valid(1_000));
+        assert!(!token.is_valid(token.expires_at));
+    }
+
+    #[test]
+    fn rejected_credentials_are_authentication_errors() {
+        let body = r#"{"error":"invalid_client","error_description":"Bad credentials"}"#;
+        let err = parse_token_response(&HttpResponse::new(401, body), 0).unwrap_err();
+        assert_eq!(
+            err,
+            Error::Authentication {
+                status: 401,
+                message: "Bad credentials".into()
+            }
+        );
+    }
+}

data/ext/openhub_bo_core/vendor/openhub-bo-core/src/validate.rs

@@ -0,0 +1,87 @@
+//! Input checks shared by product families.
+
+use crate::error::{Error, Result};
+
+pub fn require_text(field: &str, value: &str) -> Result<()> {
+    if value.trim().is_empty() {
+        return Err(Error::validation(field, "must not be empty"));
+    }
+    Ok(())
+}
+
+/// OpenHub rejects non-numeric references (`INVALID_FORMAT`), and ATC's own
+/// references are numeric; this also keeps URL paths safe.
+pub fn numeric_reference(field: &str, value: &str) -> Result<()> {
+    require_text(field, value)?;
+    if !value.chars().all(|c| c.is_ascii_digit()) {
+        return Err(Error::validation(field, "must contain only digits"));
+    }
+    Ok(())
+}
+
+pub fn positive(field: &str, value: u64) -> Result<()> {
+    if value == 0 {
+        return Err(Error::validation(field, "must be greater than zero"));
+    }
+    Ok(())
+}
+
+/// Days since 1970-01-01 for a strict `yyyy-mm-dd` date.
+pub fn iso_date_days(field: &str, value: &str) -> Result<i64> {
+    let invalid = || Error::validation(field, "must be a date as yyyy-mm-dd");
+    let bytes = value.as_bytes();
+    if bytes.len() != 10 || bytes[4] != b'-' || bytes[7] != b'-' {
+        return Err(invalid());
+    }
+    let num = |range: std::ops::Range<usize>| value[range].parse::<i64>().map_err(|_| invalid());
+    let (y, m, d) = (num(0..4)?, num(5..7)?, num(8..10)?);
+    let leap = (y % 4 == 0 && y % 100 != 0) || y % 400 == 0;
+    let month_days = [
+        31,
+        if leap { 29 } else { 28 },
+        31,
+        30,
+        31,
+        30,
+        31,
+        31,
+        30,
+        31,
+        30,
+        31,
+    ];
+    if !(1..=12).contains(&m) || d < 1 || d > month_days[(m - 1) as usize] {
+        return Err(invalid());
+    }
+    // Howard Hinnant's days_from_civil.
+    let y = if m <= 2 { y - 1 } else { y };
+    let era = y.div_euclid(400);
+    let yoe = y - era * 400;
+    let mp = (m + 9) % 12;
+    let doy = (153 * mp + 2) / 5 + d - 1;
+    let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
+    Ok(era * 146_097 + doe - 719_468)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn strict_dates() {
+        assert_eq!(iso_date_days("d", "1970-01-01").unwrap(), 0);
+        assert_eq!(
+            iso_date_days("d", "2024-03-01").unwrap() - iso_date_days("d", "2024-02-28").unwrap(),
+            2
+        );
+        for bad in [
+            "2026-02-30",
+            "2026-13-01",
+            "2026/10/06",
+            "06-10-2026",
+            "2026-1-6",
+        ] {
+            assert!(iso_date_days("d", bad).is_err(), "{bad}");
+        }
+    }
+}