hcbv4 0.1.0

data/lib/hcbv4/models/ach_transfer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # ACH bank transfer details.
+  # @attr_reader recipient_name [String, nil]
+  # @attr_reader recipient_email [String, nil]
+  # @attr_reader bank_name [String, nil]
+  # @attr_reader account_number_last4 [String, nil] last 4 digits (requires permission)
+  # @attr_reader routing_number [String, nil] (requires permission)
+  # @attr_reader payment_for [String, nil] payment memo
+  # @attr_reader sender [User, nil] user who initiated the transfer
+  class ACHTransfer < BaseTransactionDetail
+    attr_reader :recipient_name, :recipient_email, :bank_name, :account_number_last4, :routing_number, :payment_for,
+                :sender
+
+    def initialize(id:, amount_cents: nil, memo: nil, status: nil, recipient_name: nil, recipient_email: nil,
+                   bank_name: nil, account_number_last4: nil, routing_number: nil, payment_for: nil, sender: nil)
+      super(id:, amount_cents:, memo:, status:)
+      @recipient_name = recipient_name
+      @recipient_email = recipient_email
+      @bank_name = bank_name
+      @account_number_last4 = account_number_last4
+      @routing_number = routing_number
+      @payment_for = payment_for
+      @sender = sender
+    end
+
+    # @param hash [Hash] API response
+    # @return [ACHTransfer]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        amount_cents: hash["amount_cents"],
+        memo: hash["memo"],
+        status: hash["status"],
+        recipient_name: hash["recipient_name"],
+        recipient_email: hash["recipient_email"],
+        bank_name: hash["bank_name"],
+        account_number_last4: hash["account_number_last4"],
+        routing_number: hash["routing_number"],
+        payment_for: hash["payment_for"],
+        sender: hash["sender"] ? User.from_hash(hash["sender"]) : nil
+      )
+    end
+  end
+
+  AchTransferDetails = ACHTransfer
+end

data/lib/hcbv4/models/base_transaction_detail.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Base class for transaction detail types (Transfer, AchTransfer, Check, etc.).
+  class BaseTransactionDetail
+    include TransactionType
+
+    attr_reader :id, :amount_cents, :memo, :status
+
+    def initialize(id:, amount_cents: nil, memo: nil, status: nil)
+      @id = id
+      @amount_cents = amount_cents
+      @memo = memo
+      @status = status
+    end
+
+    # @param hash [Hash] API response
+    # @return [BaseTransactionDetail]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        amount_cents: hash["amount_cents"],
+        memo: hash["memo"],
+        status: hash["status"]
+      )
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && id == other.id
+    end
+    alias eql? ==
+
+    def hash
+      id.hash
+    end
+  end
+end

data/lib/hcbv4/models/card_charge.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Card purchase details for a transaction.
+  # @attr_reader merchant [Merchant, nil] merchant info
+  # @attr_reader charge_method [String, nil] "chip", "swipe", "contactless", etc.
+  # @attr_reader spent_at [String, nil] ISO timestamp
+  # @attr_reader wallet [String, nil] "apple_pay", "google_pay", etc.
+  # @attr_reader card [StripeCard, nil] the card used
+  CardCharge = Data.define(:merchant, :charge_method, :spent_at, :wallet, :card) do
+    include TransactionType
+
+    # @param hash [Hash] API response
+    # @return [CardCharge]
+    def self.from_hash(hash)
+      new(
+        merchant: hash["merchant"] ? Merchant.from_hash(hash["merchant"]) : nil,
+        charge_method: hash["charge_method"],
+        spent_at: hash["spent_at"],
+        wallet: hash["wallet"],
+        card: hash["card"] ? StripeCard.from_hash(hash["card"]) : nil
+      )
+    end
+  end
+end

data/lib/hcbv4/models/card_design.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # A physical card design for personalization.
+  CardDesign = Data.define(:id, :name, :color, :status, :unlisted, :common, :logo_url) do
+    # @param hash [Hash] API response
+    # @return [CardDesign]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"], name: hash["name"], color: hash["color"], status: hash["status"],
+        unlisted: hash["unlisted"], common: hash["common"], logo_url: hash["logo_url"]
+      )
+    end
+
+    # @return [Boolean] true if not shown in public picker
+    def unlisted? = !!unlisted
+
+    # @return [Boolean] true if available to all orgs
+    def common? = !!common
+  end
+end

data/lib/hcbv4/models/card_grant.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # A virtual card grant with optional spending restrictions.
+  # Can be topped up, withdrawn, activated, or cancelled.
+  CardGrant = Data.define(
+    :id, :amount_cents, :balance_cents, :email, :status, :merchant_lock, :category_lock,
+    :keyword_lock, :allowed_merchants, :allowed_categories, :purpose, :one_time_use,
+    :pre_authorization_required, :card_id, :user, :organization, :disbursements, :_client
+  ) do
+    include Resource
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil]
+    # @return [CardGrant]
+    def self.from_hash(hash, client: nil)
+      organization = hash["organization"] ? Organization.from_hash(hash["organization"]) : nil
+
+      new(
+        id: hash["id"],
+        amount_cents: hash["amount_cents"],
+        balance_cents: hash["balance_cents"],
+        email: hash["email"],
+        status: hash["status"],
+        merchant_lock: hash["merchant_lock"],
+        category_lock: hash["category_lock"],
+        keyword_lock: hash["keyword_lock"],
+        allowed_merchants: hash["allowed_merchants"],
+        allowed_categories: hash["allowed_categories"],
+        purpose: hash["purpose"],
+        one_time_use: hash["one_time_use"],
+        pre_authorization_required: hash["pre_authorization_required"],
+        card_id: hash["card_id"],
+        user: hash["user"] ? User.from_hash(hash["user"]) : nil,
+        organization:,
+        disbursements: hash["disbursements"]&.map { |d| Transfer.from_hash(d, client:, organization:) },
+        _client: client
+      )
+    end
+
+    # Adds funds to this grant.
+    # @param amount_cents [Integer]
+    # @return [CardGrant]
+    def topup!(amount_cents:)
+      require_client!
+      _client.topup_card_grant(id, amount_cents:)
+    end
+
+    # Withdraws funds back to the organization.
+    # @param amount_cents [Integer]
+    # @return [CardGrant]
+    def withdraw!(amount_cents:)
+      require_client!
+      _client.withdraw_card_grant(id, amount_cents:)
+    end
+
+    # Cancels this grant, returning remaining funds.
+    # @return [CardGrant]
+    def cancel!
+      require_client!
+      _client.cancel_card_grant(id)
+    end
+
+    # Activates a pending grant.
+    # @return [CardGrant]
+    def activate!
+      require_client!
+      _client.activate_card_grant(id)
+    end
+
+    # Refreshes grant data from the API.
+    # @return [CardGrant]
+    def reload!
+      require_client!
+      _client.card_grant(id)
+    end
+
+    # Updates grant attributes.
+    # @return [CardGrant]
+    def update!(**attrs)
+      require_client!
+      _client.update_card_grant(id, **attrs)
+    end
+
+    # @return [Boolean]
+    def merchant_lock? = !!merchant_lock
+
+    # @return [Boolean]
+    def category_lock? = !!category_lock
+
+    # @return [Boolean]
+    def keyword_lock? = !!keyword_lock
+
+    # @return [Boolean]
+    def one_time_use? = !!one_time_use
+
+    # @return [Boolean]
+    def pre_authorization_required? = !!pre_authorization_required
+  end
+end

data/lib/hcbv4/models/check.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Mailed check payment details.
+  class Check < BaseTransactionDetail
+    attr_reader :address_city, :address_line1, :address_line2, :address_state, :address_zip,
+                :recipient_email, :check_number, :recipient_name, :payment_for, :sender
+
+    def initialize(id:, amount_cents: nil, memo: nil, status: nil, address_city: nil, address_line1: nil,
+                   address_line2: nil, address_state: nil, address_zip: nil, recipient_email: nil,
+                   check_number: nil, recipient_name: nil, payment_for: nil, sender: nil)
+      super(id:, amount_cents:, memo:, status:)
+      @address_city = address_city
+      @address_line1 = address_line1
+      @address_line2 = address_line2
+      @address_state = address_state
+      @address_zip = address_zip
+      @recipient_email = recipient_email
+      @check_number = check_number
+      @recipient_name = recipient_name
+      @payment_for = payment_for
+      @sender = sender
+    end
+
+    # @param hash [Hash] API response
+    # @return [Check]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        amount_cents: hash["amount_cents"],
+        memo: hash["memo"],
+        status: hash["status"],
+        address_city: hash["address_city"],
+        address_line1: hash["address_line1"],
+        address_line2: hash["address_line2"],
+        address_state: hash["address_state"],
+        address_zip: hash["address_zip"],
+        recipient_email: hash["recipient_email"],
+        check_number: hash["check_number"],
+        recipient_name: hash["recipient_name"],
+        payment_for: hash["payment_for"],
+        sender: hash["sender"] ? User.from_hash(hash["sender"]) : nil
+      )
+    end
+  end
+
+  # Deposited check details.
+  class CheckDeposit < BaseTransactionDetail
+    attr_reader :front_url, :back_url, :submitter
+
+    def initialize(id:, amount_cents: nil, memo: nil, status: nil, front_url: nil, back_url: nil, submitter: nil)
+      super(id:, amount_cents:, memo:, status:)
+      @front_url = front_url
+      @back_url = back_url
+      @submitter = submitter
+    end
+
+    # @param hash [Hash] API response
+    # @return [CheckDeposit]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        amount_cents: hash["amount_cents"],
+        memo: hash["memo"],
+        status: hash["status"],
+        front_url: hash["front_url"],
+        back_url: hash["back_url"],
+        submitter: hash["submitter"] ? User.from_hash(hash["submitter"]) : nil
+      )
+    end
+  end
+end

data/lib/hcbv4/models/comment.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # A comment on a transaction.
+  Comment = Data.define(:id, :created_at, :content, :file, :admin_only, :user) do
+    # @param hash [Hash] API response
+    # @return [Comment]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"], created_at: hash["created_at"], content: hash["content"],
+        file: hash["file"], admin_only: hash["admin_only"],
+        user: hash["user"] ? User.from_hash(hash["user"]) : nil
+      )
+    end
+
+    # @return [Boolean] true if only visible to HCB emails
+    def admin_only? = !!admin_only
+  end
+end

data/lib/hcbv4/models/donation.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # A created donation record. Only contains the id.
+  # Full donation details are available via DonationTransaction on transactions.
+  Donation = Data.define(:id) do
+    # @param hash [Hash] API response
+    # @return [Donation]
+    def self.from_hash(hash) = new(id: hash["id"])
+  end
+end

data/lib/hcbv4/models/donation_transaction.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Donor info for a donation.
+  DonationDonor = Data.define(:name, :email, :recurring_donor_id) do
+    def self.from_hash(hash)
+      return nil unless hash
+
+      new(
+        name: hash["name"],
+        email: hash["email"],
+        recurring_donor_id: hash["recurring_donor_id"]
+      )
+    end
+  end
+
+  # UTM attribution info for tracking donation sources.
+  DonationAttribution = Data.define(:referrer, :utm_source, :utm_medium, :utm_campaign, :utm_term, :utm_content) do
+    def self.from_hash(hash)
+      return nil unless hash
+
+      new(
+        referrer: hash["referrer"],
+        utm_source: hash["utm_source"],
+        utm_medium: hash["utm_medium"],
+        utm_campaign: hash["utm_campaign"],
+        utm_term: hash["utm_term"],
+        utm_content: hash["utm_content"]
+      )
+    end
+  end
+
+  # Donation details on a transaction.
+  # @attr_reader recurring [Boolean, nil] true if recurring donation
+  # @attr_reader donor [DonationDonor, nil] donor info
+  # @attr_reader attribution [DonationAttribution, nil] UTM tracking
+  # @attr_reader message [String, nil] donor message
+  # @attr_reader donated_at [String, nil] ISO timestamp
+  # @attr_reader refunded [Boolean, nil]
+  class DonationTransaction < BaseTransactionDetail
+    attr_reader :recurring, :donor, :attribution, :message, :donated_at, :refunded
+
+    def initialize(id: nil, amount_cents: nil, memo: nil, status: nil, recurring: nil, donor: nil,
+                   attribution: nil, message: nil, donated_at: nil, refunded: nil)
+      super(id:, amount_cents:, memo:, status:)
+      @recurring = recurring
+      @donor = donor
+      @attribution = attribution
+      @message = message
+      @donated_at = donated_at
+      @refunded = refunded
+    end
+
+    # @param hash [Hash] API response
+    # @return [DonationTransaction]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        amount_cents: hash["amount_cents"],
+        memo: hash["memo"],
+        status: hash["status"],
+        recurring: hash["recurring"],
+        donor: DonationDonor.from_hash(hash["donor"]),
+        attribution: DonationAttribution.from_hash(hash["attribution"]),
+        message: hash["message"],
+        donated_at: hash["donated_at"],
+        refunded: hash["refunded"]
+      )
+    end
+
+    # @return [Boolean]
+    def recurring? = !!recurring
+
+    # @return [Boolean]
+    def refunded? = !!refunded
+  end
+end

data/lib/hcbv4/models/expense_payout.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Expense reimbursement payout details.
+  class ExpensePayout < BaseTransactionDetail
+    attr_reader :report_id
+
+    def initialize(id: nil, amount_cents: nil, memo: nil, status: nil, report_id: nil)
+      super(id:, amount_cents:, memo:, status:)
+      @report_id = report_id
+    end
+
+    # @param hash [Hash] API response
+    # @return [ExpensePayout]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        amount_cents: hash["amount_cents"],
+        memo: hash["memo"],
+        status: hash["status"],
+        report_id: hash["report_id"]
+      )
+    end
+  end
+end

data/lib/hcbv4/models/invitation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # An invitation to join an organization.
+  Invitation = Data.define(:id, :created_at, :accepted, :role, :sender, :organization, :_client) do
+    include Resource
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil]
+    # @return [Invitation]
+    def self.from_hash(hash, client: nil)
+      new(
+        id: hash["id"],
+        created_at: hash["created_at"],
+        accepted: hash["accepted"],
+        role: hash["role"],
+        sender: hash["sender"] ? User.from_hash(hash["sender"]) : nil,
+        organization: hash["organization"] ? Organization.from_hash(hash["organization"]) : nil,
+        _client: client
+      )
+    end
+
+    # Accepts this invitation.
+    # @return [Invitation]
+    def accept!
+      require_client!
+      _client.accept_invitation(id)
+    end
+
+    # Rejects this invitation.
+    # @return [Invitation]
+    def reject!
+      require_client!
+      _client.reject_invitation(id)
+    end
+
+    # Refreshes invitation data from the API.
+    # @return [Invitation]
+    def reload!
+      require_client!
+      _client.invitation(id)
+    end
+
+    # @return [Boolean]
+    def accepted? = !!accepted
+  end
+end

data/lib/hcbv4/models/invoice.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # An invoice sent to a sponsor.
+  Invoice = Data.define(
+    :id, :status, :created_at, :to, :amount_due, :memo, :due_date,
+    :item_amount, :item_description, :sponsor_id, :_client
+  ) do
+    include Resource
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil]
+    # @return [Invoice]
+    def self.from_hash(hash, client: nil)
+      new(
+        id: hash["id"], status: hash["status"], created_at: hash["created_at"], to: hash["to"],
+        amount_due: hash["amount_due"], memo: hash["memo"], due_date: hash["due_date"],
+        item_amount: hash["item_amount"], item_description: hash["item_description"], sponsor_id: hash["sponsor_id"],
+        _client: client
+      )
+    end
+
+    # Refreshes invoice data from the API.
+    # @return [Invoice]
+    def reload!
+      require_client!
+      _client.invoice(id)
+    end
+  end
+end

data/lib/hcbv4/models/invoice_transaction.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Sponsor info embedded in invoice transactions.
+  InvoiceSponsor = Data.define(:id, :name, :email) do
+    def self.from_hash(hash)
+      return nil unless hash
+
+      new(
+        id: hash["id"],
+        name: hash["name"],
+        email: hash["email"]
+      )
+    end
+  end
+
+  # Invoice payment details on a transaction.
+  class InvoiceTransaction < BaseTransactionDetail
+    attr_reader :sent_at, :paid_at, :description, :due_date, :sponsor
+
+    def initialize(id: nil, amount_cents: nil, memo: nil, status: nil, sent_at: nil, paid_at: nil,
+                   description: nil, due_date: nil, sponsor: nil)
+      super(id:, amount_cents:, memo:, status:)
+      @sent_at = sent_at
+      @paid_at = paid_at
+      @description = description
+      @due_date = due_date
+      @sponsor = sponsor
+    end
+
+    # @param hash [Hash] API response
+    # @return [InvoiceTransaction]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        amount_cents: hash["amount_cents"],
+        memo: hash["memo"],
+        status: hash["status"],
+        sent_at: hash["sent_at"],
+        paid_at: hash["paid_at"],
+        description: hash["description"],
+        due_date: hash["due_date"],
+        sponsor: InvoiceSponsor.from_hash(hash["sponsor"])
+      )
+    end
+  end
+end

data/lib/hcbv4/models/merchant.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Merchant info for card transactions.
+  # @attr_reader name [String, nil] raw merchant name from Stripe
+  # @attr_reader smart_name [String, nil] cleaned up merchant name
+  # @attr_reader country [String, nil] two-letter country code
+  # @attr_reader network_id [String, nil] merchant category code
+  Merchant = Data.define(:name, :smart_name, :country, :network_id) do
+    # @param hash [Hash] API response
+    # @return [Merchant]
+    def self.from_hash(hash)
+      new(name: hash["name"], smart_name: hash["smart_name"], country: hash["country"], network_id: hash["network_id"])
+    end
+  end
+end