hcbv4 0.1.0

data/lib/hcbv4/models/organization.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # An HCB organization (also called an "event").
+  # Holds funds, issues cards, and manages transactions.
+  Organization = Data.define(
+    :id, :name, :slug, :country, :icon, :background_image, :created_at,
+    :parent_id, :donation_page_available, :playground_mode,
+    :playground_mode_meeting_requested, :transparent, :fee_percentage,
+    :balance_cents, :fee_balance_cents, :total_spent_cents, :total_raised_cents,
+    :account_number, :routing_number, :swift_bic_code, :users, :_client
+  ) do
+    include Resource
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil] for making subsequent requests
+    # @return [Organization]
+    def self.from_hash(hash, client: nil)
+      new(
+        id: hash["id"],
+        name: hash["name"],
+        slug: hash["slug"],
+        country: hash["country"],
+        icon: hash["icon"],
+        background_image: hash["background_image"],
+        created_at: hash["created_at"],
+        parent_id: hash["parent_id"],
+        donation_page_available: hash["donation_page_available"],
+        playground_mode: hash["playground_mode"],
+        playground_mode_meeting_requested: hash["playground_mode_meeting_requested"],
+        transparent: hash["transparent"],
+        fee_percentage: hash["fee_percentage"],
+        balance_cents: hash["balance_cents"],
+        fee_balance_cents: hash["fee_balance_cents"],
+        total_spent_cents: hash["total_spent_cents"],
+        total_raised_cents: hash["total_raised_cents"],
+        account_number: hash["account_number"],
+        routing_number: hash["routing_number"],
+        swift_bic_code: hash["swift_bic_code"],
+        users: hash["users"]&.map { |u| OrganizationUser.from_hash(u) },
+        _client: client
+      )
+    end
+
+    # Refreshes organization data from the API.
+    # @return [Organization]
+    def reload!
+      require_client!
+      _client.organization(id)
+    end
+
+    # @return [Array<CardGrant>]
+    def card_grants(expand: [])
+      require_client!
+      _client.organization_card_grants(id, expand:)
+    end
+
+    # @return [Array<StripeCard>]
+    def stripe_cards(expand: [])
+      require_client!
+      _client.organization_stripe_cards(id, expand:)
+    end
+
+    # @return [Array<Invoice>]
+    def invoices
+      require_client!
+      _client.invoices(event_id: id)
+    end
+
+    # @return [Array<Sponsor>]
+    def sponsors
+      require_client!
+      _client.sponsors(event_id: id)
+    end
+
+    # @return [Array<User>] users following this transparent org
+    def followers
+      require_client!
+      _client.organization_followers(id)
+    end
+
+    # Returns paginated transactions.
+    # @return [TransactionList]
+    def transactions(**opts)
+      require_client!
+      _client.transactions(id, **opts)
+    end
+
+    # @return [Array<Organization>] child organizations
+    def sub_organizations
+      require_client!
+      _client.sub_organizations(id)
+    end
+
+    # Creates a card grant for this organization.
+    # @return [CardGrant]
+    def create_card_grant(amount_cents:, email:, **opts)
+      require_client!
+      _client.create_card_grant(event_id: id, amount_cents:, email:, **opts)
+    end
+
+    # Creates an invoice for a sponsor.
+    # @return [Invoice]
+    def create_invoice(sponsor_id:, due_date:, item_description:, item_amount:)
+      require_client!
+      _client.create_invoice(event_id: id, sponsor_id:, due_date:, item_description:, item_amount:)
+    end
+
+    # Creates a sponsor record.
+    # @return [Sponsor]
+    def create_sponsor(name:, contact_email:, **address)
+      require_client!
+      _client.create_sponsor(event_id: id, name:, contact_email:, **address)
+    end
+
+    # Transfers funds to another organization.
+    # @return [Transfer]
+    def create_disbursement(to_organization_id:, amount_cents:, name:)
+      require_client!
+      _client.create_disbursement(event_id: id, to_organization_id:, amount_cents:, name:)
+    end
+
+    # Initiates an ACH bank transfer.
+    # @return [Hash]
+    def create_ach_transfer(routing_number:, account_number:, recipient_name:, amount_money:, payment_for:, **opts)
+      require_client!
+      _client.create_ach_transfer(event_id: id, routing_number:, account_number:, recipient_name:, amount_money:,
+                                  payment_for:, **opts)
+    end
+
+    # Records an in-person donation.
+    # @return [Donation]
+    def create_donation(amount_cents:, **opts)
+      require_client!
+      _client.create_donation(event_id: id, amount_cents:, **opts)
+    end
+
+    # Invites a user to this organization.
+    # @return [Invitation]
+    def create_invitation(email:, role: nil, **opts)
+      require_client!
+      _client.create_invitation(event_id: id, email:, role:, **opts)
+    end
+
+    # Creates a sub-organization under this one.
+    # @return [Organization]
+    def create_sub_organization(name:, email:, **opts)
+      require_client!
+      _client.create_sub_organization(id, name:, email:, **opts)
+    end
+
+    # @return [Boolean]
+    def donation_page_available? = !!donation_page_available
+
+    # @return [Boolean]
+    def playground_mode? = !!playground_mode
+
+    # @return [Boolean]
+    def playground_mode_meeting_requested? = !!playground_mode_meeting_requested
+
+    # @return [Boolean]
+    def transparent? = !!transparent
+  end
+end

data/lib/hcbv4/models/organization_user.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # A user with organization-specific membership info (role, join date).
+  # Returned when expanding :users on an organization.
+  # @attr_reader joined_at [String, nil] ISO timestamp when user joined the org
+  # @attr_reader role [String, nil] "member" or "manager"
+  class OrganizationUser < User
+    attr_reader :joined_at, :role
+
+    def initialize(id:, name: nil, email: nil, avatar: nil, admin: nil, auditor: nil, birthday: nil,
+                   shipping_address: nil, joined_at: nil, role: nil)
+      super(id:, name:, email:, avatar:, admin:, auditor:, birthday:, shipping_address:)
+      @joined_at = joined_at
+      @role = role
+    end
+
+    # @param hash [Hash] API response
+    # @return [OrganizationUser]
+    def self.from_hash(hash)
+      new(
+        id: hash["id"],
+        name: hash["name"],
+        email: hash["email"],
+        avatar: hash["avatar"],
+        admin: hash["admin"],
+        auditor: hash["auditor"],
+        joined_at: hash["joined_at"],
+        role: hash["role"]
+      )
+    end
+  end
+end

data/lib/hcbv4/models/receipt.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # An uploaded receipt image attached to a transaction.
+  Receipt = Data.define(:id, :created_at, :url, :preview_url, :filename, :uploader, :_client) do
+    include Resource
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil]
+    # @return [Receipt]
+    def self.from_hash(hash, client: nil)
+      new(
+        id: hash["id"],
+        created_at: hash["created_at"],
+        url: hash["url"],
+        preview_url: hash["preview_url"],
+        filename: hash["filename"],
+        uploader: hash["uploader"] ? User.from_hash(hash["uploader"]) : nil,
+        _client: client
+      )
+    end
+
+    # Deletes this receipt.
+    # @return [nil]
+    def delete!
+      require_client!
+      _client.delete_receipt(id)
+    end
+  end
+end

data/lib/hcbv4/models/resource.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module HCBV4
+  module Resource
+    def require_client!
+      raise Error, "No client attached to this #{self.class.name.split("::").last}" unless _client
+    end
+
+    module ClassMethods
+      def of_id(id, client:, **extra)
+        attrs = members.to_h { |m| [m, nil] }
+        attrs[:id] = id
+        attrs[:_client] = client
+        attrs.merge!(extra.slice(*members))
+        new(**attrs)
+      end
+    end
+
+    def self.included(base)
+      base.extend(ClassMethods) if base.respond_to?(:members)
+    end
+  end
+end

data/lib/hcbv4/models/sponsor.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # A sponsor or donor contact for invoicing.
+  Sponsor = Data.define(
+    :id, :name, :slug, :contact_email, :created_at, :event_id, :stripe_customer_id,
+    :address_line1, :address_line2, :address_city, :address_state,
+    :address_postal_code, :address_country, :_client
+  ) do
+    include Resource
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil]
+    # @return [Sponsor]
+    def self.from_hash(hash, client: nil)
+      new(
+        id: hash["id"], name: hash["name"], slug: hash["slug"], contact_email: hash["contact_email"],
+        created_at: hash["created_at"], event_id: hash["event_id"], stripe_customer_id: hash["stripe_customer_id"],
+        address_line1: hash["address_line1"], address_line2: hash["address_line2"], address_city: hash["address_city"],
+        address_state: hash["address_state"], address_postal_code: hash["address_postal_code"],
+        address_country: hash["address_country"],
+        _client: client
+      )
+    end
+
+    # Refreshes sponsor data from the API.
+    # @return [Sponsor]
+    def reload!
+      require_client!
+      _client.sponsor(id)
+    end
+
+    # Creates an invoice for this sponsor.
+    # @param due_date [String] ISO date (YYYY-MM-DD)
+    # @param item_description [String]
+    # @param item_amount [Integer] amount in cents
+    # @return [Invoice]
+    def create_invoice(due_date:, item_description:, item_amount:)
+      require_client!
+      _client.create_invoice(event_id:, sponsor_id: id, due_date:, item_description:, item_amount:)
+    end
+  end
+end

data/lib/hcbv4/models/stripe_card.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Physical card personalization (color, logo).
+  CardPersonalization = Data.define(:color, :logo_url) do
+    def self.from_hash(hash)
+      return nil unless hash
+
+      new(
+        color: hash["color"],
+        logo_url: hash["logo_url"]
+      )
+    end
+  end
+
+  # Shipping address for physical cards.
+  CardShippingAddress = Data.define(:line1, :line2, :city, :state, :country, :postal_code) do
+    def self.from_hash(hash)
+      return nil unless hash
+
+      new(
+        line1: hash["line1"],
+        line2: hash["line2"],
+        city: hash["city"],
+        state: hash["state"],
+        country: hash["country"],
+        postal_code: hash["postal_code"]
+      )
+    end
+  end
+
+  # Physical card shipping status and tracking.
+  CardShipping = Data.define(:status, :eta, :address) do
+    def self.from_hash(hash)
+      return nil unless hash
+
+      new(
+        status: hash["status"],
+        eta: hash["eta"],
+        address: CardShippingAddress.from_hash(hash["address"])
+      )
+    end
+  end
+
+  # A Stripe Issuing card (virtual or physical).
+  StripeCard = Data.define(
+    :id, :type, :status, :name, :last4, :exp_month, :exp_year, :created_at,
+    :total_spent_cents, :balance_available, :organization, :user,
+    :personalization, :shipping, :_client
+  ) do
+    include Resource
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil]
+    # @return [StripeCard]
+    def self.from_hash(hash, client: nil)
+      new(
+        id: hash["id"],
+        type: hash["type"],
+        status: hash["status"],
+        name: hash["name"],
+        last4: hash["last4"],
+        exp_month: hash["exp_month"],
+        exp_year: hash["exp_year"],
+        created_at: hash["created_at"],
+        total_spent_cents: hash["total_spent_cents"],
+        balance_available: hash["balance_available"],
+        organization: hash["organization"] ? Organization.from_hash(hash["organization"]) : nil,
+        user: hash["user"] ? User.from_hash(hash["user"]) : nil,
+        personalization: CardPersonalization.from_hash(hash["personalization"]),
+        shipping: CardShipping.from_hash(hash["shipping"]),
+        _client: client
+      )
+    end
+
+    # Freezes the card, blocking new transactions.
+    # @return [StripeCard]
+    def freeze!
+      require_client!
+      _client.update_stripe_card(id, status: "frozen")
+    end
+
+    # Unfreezes a frozen card.
+    # @return [StripeCard]
+    def defrost!
+      require_client!
+      _client.update_stripe_card(id, status: "active")
+    end
+
+    # Permanently cancels the card.
+    # @return [Hash]
+    def cancel!
+      require_client!
+      _client.cancel_stripe_card(id)
+    end
+
+    # Refreshes card data from the API.
+    # @return [StripeCard]
+    def reload!
+      require_client!
+      _client.stripe_card(id)
+    end
+
+    # Activates a physical card after receiving it.
+    # @param last4 [String] last 4 digits printed on the card
+    # @return [StripeCard]
+    def activate!(last4:)
+      require_client!
+      _client.update_stripe_card(id, status: "active", last4:)
+    end
+
+    # Returns paginated transactions for this card.
+    # @return [TransactionList]
+    def transactions(**opts)
+      require_client!
+      _client.stripe_card_transactions(id, **opts)
+    end
+
+    # Returns Stripe ephemeral keys for revealing sensitive card details.
+    # @param nonce [String] one-time nonce
+    # @param stripe_version [String, nil]
+    # @return [Hash]
+    def ephemeral_keys(nonce:, stripe_version: nil)
+      require_client!
+      _client.stripe_card_ephemeral_keys(id, nonce:, stripe_version:)
+    end
+
+    # @return [Boolean]
+    def virtual? = type == "virtual"
+
+    # @return [Boolean]
+    def physical? = type == "physical"
+  end
+end

data/lib/hcbv4/models/tag.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # A tag applied to a transaction.
+  Tag = Data.define(:id, :label, :color, :emoji) do
+    # @param hash [Hash] API response
+    # @return [Tag]
+    def self.from_hash(hash)
+      new(id: hash["id"], label: hash["label"], color: hash["color"], emoji: hash["emoji"])
+    end
+  end
+end

data/lib/hcbv4/models/transaction.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # A financial transaction on an organization's ledger.
+  # Contains type-specific details (card_charge, donation, transfer, etc.).
+  Transaction = Data.define(
+    :id, :date, :amount_cents, :memo, :has_custom_memo, :pending, :declined, :tags,
+    :code, :missing_receipt, :lost_receipt, :appearance,
+    :card_charge, :donation, :expense_payout, :invoice, :check, :transfer,
+    :ach_transfer, :check_deposit, :organization, :_client
+  ) do
+    include Resource
+    include TransactionType
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil]
+    # @return [Transaction]
+    def self.from_hash(hash, client: nil)
+      organization = hash["organization"] ? Organization.from_hash(hash["organization"]) : nil
+
+      new(
+        id: hash["id"],
+        date: hash["date"],
+        amount_cents: hash["amount_cents"],
+        memo: hash["memo"],
+        has_custom_memo: hash["has_custom_memo"],
+        pending: hash["pending"],
+        declined: hash["declined"],
+        tags: hash["tags"]&.map { |t| Tag.from_hash(t) },
+        code: hash["code"],
+        missing_receipt: hash["missing_receipt"],
+        lost_receipt: hash["lost_receipt"],
+        appearance: hash["appearance"],
+        card_charge: hash["card_charge"] ? CardCharge.from_hash(hash["card_charge"]) : nil,
+        donation: hash["donation"] ? DonationTransaction.from_hash(hash["donation"]) : nil,
+        expense_payout: hash["expense_payout"] ? ExpensePayout.from_hash(hash["expense_payout"]) : nil,
+        invoice: hash["invoice"] ? InvoiceTransaction.from_hash(hash["invoice"]) : nil,
+        check: hash["check"] ? Check.from_hash(hash["check"]) : nil,
+        transfer: hash["transfer"] ? Transfer.from_hash(hash["transfer"], client:, organization:) : nil,
+        ach_transfer: hash["ach_transfer"] ? ACHTransfer.from_hash(hash["ach_transfer"]) : nil,
+        check_deposit: hash["check_deposit"] ? CheckDeposit.from_hash(hash["check_deposit"]) : nil,
+        organization:,
+        _client: client
+      )
+    end
+
+    # Returns the transaction type as a symbol.
+    # @return [Symbol] :card_charge, :donation, :transfer, :ach_transfer, etc.
+    def type
+      return :card_charge if card_charge
+      return :donation if donation
+      return :expense_payout if expense_payout
+      return :invoice if invoice
+      return :check if check
+      return :transfer if transfer
+      return :ach_transfer if ach_transfer
+      return :check_deposit if check_deposit
+
+      :unknown
+    end
+
+    # Returns the type-specific detail object.
+    # @return [CardCharge, DonationTransaction, Transfer, ACHTransfer, Check, nil]
+    def details
+      card_charge || donation || expense_payout || invoice || check || transfer || ach_transfer || check_deposit
+    end
+
+    # @return [Array<Comment>]
+    def comments
+      require_client!
+      _client.comments(organization_id: organization&.id, transaction_id: id)
+    end
+
+    # @return [Array<Receipt>]
+    def receipts
+      require_client!
+      _client.receipts(transaction_id: id)
+    end
+
+    # Refreshes transaction data from the API.
+    # @return [Transaction]
+    def reload!
+      require_client!
+      _client.transaction(id)
+    end
+
+    # Updates the transaction memo.
+    # @param memo [String]
+    # @return [Transaction]
+    def update!(memo:)
+      require_client!
+      _client.update_transaction(id, event_id: organization&.id, memo:)
+    end
+
+    # Adds a comment to this transaction.
+    # @param content [String]
+    # @param admin_only [Boolean]
+    # @param file [File, nil]
+    # @return [Comment]
+    def add_comment(content:, admin_only: false, file: nil)
+      require_client!
+      _client.create_comment(organization_id: organization&.id, transaction_id: id, content:, admin_only:, file:)
+    end
+
+    # Uploads a receipt and attaches it to this transaction.
+    # @param file [File]
+    # @return [Receipt]
+    def add_receipt(file:)
+      require_client!
+      _client.create_receipt(file:, transaction_id: id)
+    end
+
+    # Returns memo autocomplete suggestions based on past transaction memos.
+    # @return [Array<String>] suggested memo strings
+    def memo_suggestions
+      require_client!
+      _client.memo_suggestions(event_id: organization&.id, transaction_id: id)
+    end
+
+    # @return [Boolean]
+    def has_custom_memo? = !!has_custom_memo
+
+    # @return [Boolean]
+    def missing_receipt? = !!missing_receipt
+
+    # @return [Boolean]
+    def lost_receipt? = !!lost_receipt
+  end
+end

data/lib/hcbv4/models/transaction_list.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Paginated list of transactions. Implements Enumerable.
+  TransactionList = Data.define(:data, :total_count, :has_more, :_client, :_pagination_context) do
+    include Resource
+    include Enumerable
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil]
+    # @param pagination_context [Hash, nil] internal pagination state
+    # @return [TransactionList]
+    def self.from_hash(hash, client: nil, pagination_context: nil)
+      new(
+        data: hash["data"]&.map { |t| Transaction.from_hash(t, client:) } || [],
+        total_count: hash["total_count"],
+        has_more: hash["has_more"],
+        _client: client,
+        _pagination_context: pagination_context
+      )
+    end
+
+    # Iterates over transactions in this page.
+    # @yield [Transaction]
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      data.each(&block)
+    end
+
+    # @return [Boolean] true if more pages are available
+    def has_more? = !!has_more
+
+    # Fetches the next page of transactions.
+    # @return [TransactionList, nil]
+    def next_page
+      return nil unless has_more? && _client && _pagination_context
+
+      case _pagination_context[:type]
+      when :organization_transactions
+        _client.transactions(
+          _pagination_context[:organization_id],
+          limit: _pagination_context[:limit],
+          after: data.last&.id,
+          type: _pagination_context[:tx_type],
+          filters: _pagination_context[:filters],
+          expand: _pagination_context[:expand] || []
+        )
+      when :missing_receipt
+        _client.missing_receipt_transactions(
+          limit: _pagination_context[:limit],
+          after: data.last&.id
+        )
+      when :stripe_card_transactions
+        _client.stripe_card_transactions(
+          _pagination_context[:card_id],
+          limit: _pagination_context[:limit],
+          after: data.last&.id,
+          missing_receipts: _pagination_context[:missing_receipts]
+        )
+      end
+    end
+
+    # Iterates through all pages.
+    # @yield [TransactionList] each page
+    def each_page
+      return enum_for(:each_page) unless block_given?
+
+      page = self
+      loop do
+        yield page
+        break unless page.has_more?
+
+        page = page.next_page
+        break if page.nil?
+      end
+    end
+
+    # Lazily iterates through all transactions across pages.
+    # @param max_pages [Integer, nil] limit number of pages fetched
+    # @yield [Transaction]
+    def auto_paginate(max_pages: nil, &block)
+      return enum_for(:auto_paginate, max_pages:) unless block_given?
+
+      pages = 0
+      each_page do |page|
+        page.each(&block)
+        pages += 1
+        break if max_pages && pages >= max_pages
+      end
+    end
+
+    # Collects all transactions into an array.
+    # @param max_pages [Integer] safety limit (default 100)
+    # @return [Array<Transaction>]
+    def all(max_pages: 100)
+      auto_paginate(max_pages:).to_a
+    end
+  end
+end

data/lib/hcbv4/models/transaction_type.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module HCBV4
+  module TransactionType
+    COMMON_FIELDS = %i[id amount_cents memo status].freeze
+
+    def transaction? = true
+    def pending? = respond_to?(:pending) && pending
+    def declined? = respond_to?(:declined) && declined
+  end
+end