hcbv4 0.1.0

data/lib/hcbv4/models/transfer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # An inter-organization fund transfer.
+  # @attr_reader transaction_id [String, nil] associated ledger entry
+  # @attr_reader from [Organization, nil] source organization
+  # @attr_reader to [Organization, nil] destination organization
+  # @attr_reader sender [User, nil] user who initiated the transfer
+  # @attr_reader card_grant_id [String, nil] associated card grant
+  # @attr_reader organization [Organization, nil] organization context for fetching transaction
+  class Transfer < BaseTransactionDetail
+    attr_reader :transaction_id, :from, :to, :sender, :card_grant_id, :organization, :_client
+
+    def initialize(id:, amount_cents: nil, memo: nil, status: nil, transaction_id: nil, from: nil, to: nil,
+                   sender: nil, card_grant_id: nil, organization: nil, client: nil)
+      super(id:, amount_cents:, memo:, status:)
+      @transaction_id = transaction_id
+      @from = from
+      @to = to
+      @sender = sender
+      @card_grant_id = card_grant_id
+      @organization = organization
+      @_client = client
+    end
+
+    # Fetches the associated transaction.
+    # @return [Transaction]
+    def transaction
+      raise Error, "No client attached to this Transfer" unless _client
+      raise Error, "No transaction_id on this Transfer" unless transaction_id
+
+      _client.transaction(transaction_id)
+    end
+
+    # Stubs a Transaction with the associated transaction ID and organization.
+    # @return [Transaction]
+    def transaction!
+      raise Error, "No client attached to this Transfer" unless _client
+      raise Error, "No transaction_id on this Transfer" unless transaction_id
+
+      Transaction.of_id(transaction_id, client: _client, organization:)
+    end
+
+    # @param hash [Hash] API response
+    # @param client [Client, nil]
+    # @param organization [Organization, nil] organization context
+    # @return [Transfer]
+    def self.from_hash(hash, client: nil, organization: nil)
+      new(
+        id: hash["id"],
+        amount_cents: hash["amount_cents"],
+        memo: hash["memo"],
+        status: hash["status"],
+        transaction_id: hash["transaction_id"],
+        from: hash["from"] ? Organization.from_hash(hash["from"]) : nil,
+        to: hash["to"] ? Organization.from_hash(hash["to"]) : nil,
+        sender: hash["sender"] ? User.from_hash(hash["sender"]) : nil,
+        card_grant_id: hash["card_grant_id"],
+        organization:,
+        client:
+      )
+    end
+  end
+
+  # Alias for Transfer.
+  Disbursement = Transfer
+end

data/lib/hcbv4/models/user.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module HCBV4
+  # Mailing address for physical card delivery.
+  ShippingAddress = Data.define(:address_line1, :address_line2, :city, :state, :country, :postal_code) do
+    def self.from_hash(hash)
+      return nil unless hash
+
+      new(
+        address_line1: hash["address_line1"],
+        address_line2: hash["address_line2"],
+        city: hash["city"],
+        state: hash["state"],
+        country: hash["country"],
+        postal_code: hash["postal_code"]
+      )
+    end
+  end
+
+  # An HCB user account.
+  # @attr_reader id [String] unique user id
+  # @attr_reader name [String, nil] display name
+  # @attr_reader email [String, nil] email address
+  # @attr_reader avatar [String, nil] avatar URL
+  # @attr_reader admin [Boolean, nil] HCB admin flag
+  # @attr_reader auditor [Boolean, nil] HCB auditor flag
+  # @attr_reader birthday [String, nil] ISO date
+  # @attr_reader shipping_address [ShippingAddress, nil] mailing address
+  class User
+    attr_reader :id, :name, :email, :avatar, :admin, :auditor, :birthday, :shipping_address, :_client
+
+    def initialize(id:, name: nil, email: nil, avatar: nil, admin: nil, auditor: nil, birthday: nil,
+                   shipping_address: nil, _client: nil)
+      @id = id
+      @name = name
+      @email = email
+      @avatar = avatar
+      @admin = admin
+      @auditor = auditor
+      @birthday = birthday
+      @shipping_address = shipping_address
+      @_client = _client
+    end
+
+    # @param hash [Hash] API response
+    # @return [User]
+    def self.from_hash(hash, client: nil)
+      new(
+        id: hash["id"],
+        name: hash["name"],
+        email: hash["email"],
+        avatar: hash["avatar"],
+        admin: hash["admin"],
+        auditor: hash["auditor"],
+        birthday: hash["birthday"],
+        shipping_address: ShippingAddress.from_hash(hash["shipping_address"]),
+        _client: client
+      )
+    end
+
+    # @return [Boolean] true if user is an HCB admin
+    def admin? = !!admin
+
+    # @return [Boolean] true if user is an HCB auditor
+    def auditor? = !!auditor
+
+    def ==(other)
+      other.is_a?(User) && id == other.id
+    end
+    alias eql? ==
+
+    def hash
+      id.hash
+    end
+  end
+end

data/lib/hcbv4/models.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Modules first
+require_relative "models/resource"
+require_relative "models/transaction_type"
+
+# Base classes (no dependencies)
+require_relative "models/user"
+require_relative "models/organization_user"
+require_relative "models/tag"
+require_relative "models/merchant"
+require_relative "models/card_design"
+require_relative "models/donation"
+
+# Transaction detail base and subtypes
+require_relative "models/base_transaction_detail"
+require_relative "models/check"
+require_relative "models/invoice_transaction"
+require_relative "models/donation_transaction"
+require_relative "models/expense_payout"
+
+# Models with Organization/User dependencies
+require_relative "models/organization"
+require_relative "models/transfer"
+require_relative "models/ach_transfer"
+require_relative "models/stripe_card"
+require_relative "models/card_charge"
+
+# Models with complex dependencies
+require_relative "models/card_grant"
+require_relative "models/transaction"
+require_relative "models/transaction_list"
+require_relative "models/invoice"
+require_relative "models/sponsor"
+require_relative "models/receipt"
+require_relative "models/comment"
+require_relative "models/invitation"

data/lib/hcbv4/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HCBV4
+  VERSION = "0.1.0"
+end

data/lib/hcbv4.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "hcbv4/version"
+require_relative "hcbv4/errors"
+require_relative "hcbv4/models"
+require_relative "hcbv4/client"
+
+module HCBV4
+  class Error < StandardError; end
+end

data/sig/hcbv4.rbs

@@ -0,0 +1,4 @@
+module Hcbv4
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: hcbv4
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- 24c02
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A Ruby SDK for interacting with the Hack Club Bank (HCB) API v4. Provides
+  access to organizations, transactions, cards, and financial operations.
+email:
+- 163450896+24c02@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- lib/hcbv4.rb
+- lib/hcbv4/client.rb
+- lib/hcbv4/errors.rb
+- lib/hcbv4/models.rb
+- lib/hcbv4/models/ach_transfer.rb
+- lib/hcbv4/models/base_transaction_detail.rb
+- lib/hcbv4/models/card_charge.rb
+- lib/hcbv4/models/card_design.rb
+- lib/hcbv4/models/card_grant.rb
+- lib/hcbv4/models/check.rb
+- lib/hcbv4/models/comment.rb
+- lib/hcbv4/models/donation.rb
+- lib/hcbv4/models/donation_transaction.rb
+- lib/hcbv4/models/expense_payout.rb
+- lib/hcbv4/models/invitation.rb
+- lib/hcbv4/models/invoice.rb
+- lib/hcbv4/models/invoice_transaction.rb
+- lib/hcbv4/models/merchant.rb
+- lib/hcbv4/models/organization.rb
+- lib/hcbv4/models/organization_user.rb
+- lib/hcbv4/models/receipt.rb
+- lib/hcbv4/models/resource.rb
+- lib/hcbv4/models/sponsor.rb
+- lib/hcbv4/models/stripe_card.rb
+- lib/hcbv4/models/tag.rb
+- lib/hcbv4/models/transaction.rb
+- lib/hcbv4/models/transaction_list.rb
+- lib/hcbv4/models/transaction_type.rb
+- lib/hcbv4/models/transfer.rb
+- lib/hcbv4/models/user.rb
+- lib/hcbv4/version.rb
+- sig/hcbv4.rbs
+homepage: https://github.com/hackclub/hcbv4
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/hackclub/hcbv4
+  source_code_uri: https://github.com/hackclub/hcbv4
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Ruby client for the HCB API v4.
+test_files: []