Home /Modules/advantage/SLMoneyConnector.sleela

SLMoneyConnector.sleela

lib/advantage/connect/SLMoneyConnector.sleela · 233 line(s) · sleela

<< lib/advantage/connect/SLMoneyConnector.sleela
   SLeeLa Standard Library Definition.
   Definition: The money-source connector of the CONNECT medium -- banks and
   card networks. It models a payment lifecycle (authorize -> capture ->
   refund / void) against a funding source, validating amounts and state in the
   VM and deferring the live settlement to a host adapter (slbank_*). Declines
   are a first-class, non-retryable outcome. >>
#sleela 3.0
material;
artifact;
pure;
gasoline;
<< NATIVE BRIDGE (documented, not dialed).
   open      -> slbank_open(sourceKind, sourceRef, keystoreAlias) : handle
   authorize -> slbank_authorize(handle, amountCents, currency) : authRef
   capture   -> slbank_capture(handle, authRef, amountCents) : settleRef
   refund    -> slbank_refund(handle, settleRef, amountCents) : refundRef
   void      -> slbank_void(handle, authRef)
   close     -> slbank_close(handle)
   SAFETY. Amounts are integer CENTS to avoid floating error on money. No PAN,
   no CVV, no secret ever lives here -- only a keystore ALIAS the native adapter
   resolves. A DECLINED authorization is marked non-retryable on the fault so no
   caller loops on a refusal. This is bookkeeping and lifecycle modelling, not
   payment processing and not financial advice. No apostrophes in comments. >>
class SLMoneyConnector {
  < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
  String metaVersion = "1.0.0";
  int metaId = 10645;
  String metaAuthor = "Kiro Agent";
  String metaDate = "2026-11-08";
  String metaCopyright = "SLeeLa project";
  String metaTrademark = "Advantage";
  String metaCorporation = "SLeeLa project";
  < metaOrigin: National | <nation> | International | Galactic >
  String metaOrigin = "International";
  String metaBirthDate = "2026-11-08";
  int metaScienceRating = 7;
  << metaNationalSchedule: card data handling is governed by PCI DSS; this class
     holds NO cardholder data, only a keystore alias, so it stays out of scope by
     construction. >>
  String metaNationalSchedule = "PCI DSS (by exclusion: no cardholder data held)";

  String getMetaVersion() { return metaVersion; }
  void setMetaVersion(String v) { metaVersion = v; }
  int getMetaId() { return metaId; }
  void setMetaId(int v) { metaId = v; }
  String getAuthor() { return metaAuthor; }
  void setAuthor(String v) { metaAuthor = v; }
  String getDate() { return metaDate; }
  void setDate(String v) { metaDate = v; }
  String getCopyright() { return metaCopyright; }
  void setCopyright(String v) { metaCopyright = v; }
  String getTrademark() { return metaTrademark; }
  void setTrademark(String v) { metaTrademark = v; }
  String getCorporation() { return metaCorporation; }
  void setCorporation(String v) { metaCorporation = v; }
  String getOrigin() { return metaOrigin; }
  void setOrigin(String v) { metaOrigin = v; }
  String getBirthDate() { return metaBirthDate; }
  void setBirthDate(String v) { metaBirthDate = v; }
  int getScienceRating() { return metaScienceRating; }
  void setScienceRating(int v) { metaScienceRating = v; }
  String getNationalSchedule() { return metaNationalSchedule; }
  void setNationalSchedule(String v) { metaNationalSchedule = v; }

  < ---- Shared medium plumbing ---- >
  SLConnectStatus vocab;
  SLConnectFault fault;

  < ---- Funding-source + payment state ---- >
  < sourceKind: "bank" | "card" | "wallet" >
  String sourceKind = "";
  String keystoreAlias = "";
  String currency = "USD";
  boolean configured = false;
  boolean open = false;
  int authorizedCents = 0;
  int capturedCents = 0;
  int refundedCents = 0;
  boolean lastDeclined = false;

  void init() {
    vocab = new SLConnectStatus();
    fault = new SLConnectFault();
  }

  int configure(String kind, String alias, String cur) {
    if (vocab == null) { init(); }
    fault.clear();
    if (kind == null || alias == null || alias == "" || cur == null) {
      fault.raise(vocab, vocab.invalidArgument(), "money", "configure", "bad source");
      return vocab.invalidArgument();
    }
    boolean kindOk = false;
    if (kind == "bank") { kindOk = true; }
    if (kind == "card") { kindOk = true; }
    if (kind == "wallet") { kindOk = true; }
    if (!kindOk) {
      fault.raise(vocab, vocab.invalidArgument(), "money", "configure", "unknown source kind");
      return vocab.invalidArgument();
    }
    sourceKind = kind; keystoreAlias = alias; currency = cur;
    configured = true;
    return vocab.ok();
  }

  int openLink() {
    if (vocab == null) { init(); }
    fault.clear();
    if (!configured) {
      fault.raise(vocab, vocab.notConfigured(), "money", "openLink", "configure first");
      return vocab.notConfigured();
    }
    open = true;
    return vocab.ok();
  }

  << Authorize a hold (native: slbank_authorize). Under run the authorization
     cannot actually reach the card network, so it defers to the adapter and
     returns NATIVE_ADAPTER_REQUIRED. A host adapter calls acceptAuthorization()
     on approval or declineAuthorization() on refusal. >>
  int authorize(int amountCents) {
    if (vocab == null) { init(); }
    fault.clear();
    if (!open) {
      fault.raise(vocab, vocab.invalidState(), "money", "authorize", "link not open");
      return vocab.invalidState();
    }
    if (amountCents <= 0) {
      fault.raise(vocab, vocab.invalidArgument(), "money", "authorize", "non-positive amount");
      return vocab.invalidArgument();
    }
    lastDeclined = false;
    fault.raise(vocab, vocab.nativeAdapterRequired(), "money", "authorize", "adapter runs slbank_authorize");
    return vocab.nativeAdapterRequired();
  }

  < Host-adapter callback: approval. Records the authorized hold. >
  int acceptAuthorization(int amountCents) {
    if (vocab == null) { init(); }
    fault.clear();
    if (amountCents <= 0) {
      fault.raise(vocab, vocab.invalidArgument(), "money", "acceptAuthorization", "non-positive amount");
      return vocab.invalidArgument();
    }
    authorizedCents = amountCents;
    lastDeclined = false;
    return vocab.ok();
  }

  < Host-adapter callback: refusal. A decline is NOT retryable. >
  int declineAuthorization(String why) {
    if (vocab == null) { init(); }
    fault.clear();
    lastDeclined = true;
    fault.raise(vocab, vocab.declined(), "money", "authorize", why);
    fault.setRetryable(false);
    return vocab.declined();
  }

  < Capture against a prior authorization (native: slbank_capture). Cannot >
  < capture more than was authorized. >
  int capture(int amountCents) {
    if (vocab == null) { init(); }
    fault.clear();
    if (!open) {
      fault.raise(vocab, vocab.invalidState(), "money", "capture", "link not open");
      return vocab.invalidState();
    }
    if (authorizedCents <= 0) {
      fault.raise(vocab, vocab.invalidState(), "money", "capture", "nothing authorized");
      return vocab.invalidState();
    }
    if (amountCents <= 0 || amountCents > authorizedCents) {
      fault.raise(vocab, vocab.invalidArgument(), "money", "capture", "amount exceeds authorization");
      return vocab.invalidArgument();
    }
    capturedCents = capturedCents + amountCents;
    return vocab.ok();
  }

  < Refund part or all of what was captured (native: slbank_refund). >
  int refund(int amountCents) {
    if (vocab == null) { init(); }
    fault.clear();
    if (!open) {
      fault.raise(vocab, vocab.invalidState(), "money", "refund", "link not open");
      return vocab.invalidState();
    }
    int net = capturedCents - refundedCents;
    if (amountCents <= 0 || amountCents > net) {
      fault.raise(vocab, vocab.invalidArgument(), "money", "refund", "amount exceeds captured net");
      return vocab.invalidArgument();
    }
    refundedCents = refundedCents + amountCents;
    return vocab.ok();
  }

  < Net settled amount after refunds, in cents. >
  int settledCents() { return capturedCents - refundedCents; }

  int closeLink() {
    if (vocab == null) { init(); }
    fault.clear();
    open = false;
    return vocab.ok();
  }

  boolean active() { return open; }
  boolean wasDeclined() { return lastDeclined; }
  int getAuthorizedCents() { return authorizedCents; }
  int getCapturedCents() { return capturedCents; }
  int getRefundedCents() { return refundedCents; }
  boolean isNativeReady() { return false; }
  SLConnectFault lastFault() { if (vocab == null) { init(); } return fault; }

  < A log-safe settlement receipt -- alias only, never a card number. >
  String receipt() {
    return "SETTLE[" + sourceKind + ":" + keystoreAlias + "]"
         + " authorized=" + authorizedCents
         + " captured=" + capturedCents
         + " refunded=" + refundedCents
         + " net=" + settledCents()
         + " " + currency;
  }

  String describe() {
    return "MoneyConnector[" + sourceKind + "] open=" + open
         + " net=" + settledCents() + " " + currency
         + " declined=" + lastDeclined;
  }
}