fastbound 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8219bcb38d03ea269bb7d9c4a16a7e062b6beb001f88f6763eecac18cec9a66
+  data.tar.gz: 01d7d0f70d77527d5e9d5fc12445493780ba10f539471360c84522820c164ddc
+SHA512:
+  metadata.gz: 3fe98da320c0330c51c7e51b36e6e98feb395174988033d1c067f60ddcff8a4f6f8da4d1b9024fe6c52f80ce4e6fafa520cf3722e75ed5b9b5b82b8f60af59a8
+  data.tar.gz: f8db9b2ef652c56350a71929751b1d06cfd69c259467fe54755c8ad52c1cf7f9f182aa8035eea73d749003b94b6f2a0b8303fe447d943602bb6a51af429f635a

data/README.md

@@ -0,0 +1,366 @@
+# Fastbound
+
+A Ruby gem for the [FastBound](https://fastbound.com) firearms compliance API.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "fastbound"
+```
+
+Or install directly:
+
+```bash
+gem install fastbound
+```
+
+## Configuration
+
+```ruby
+client = Fastbound::Client.new(
+  api_key:        "your_api_key",
+  account_number: "A001234",
+  audit_user:     "user@example.com"  # required for create/update/delete operations
+)
+```
+
+| Option | Required | Description |
+|---|---|---|
+| `api_key` | Yes | Your FastBound API key (used as HTTP Basic auth username) |
+| `account_number` | Yes | Your FastBound account number |
+| `audit_user` | No* | Email address recorded on write operations. Required by the API for POST/PUT/DELETE. |
+| `base_url` | No | Override the API base URL (default: `https://cloud.fastbound.com`) |
+
+## Resources
+
+### Account
+
+```ruby
+client.account.get
+```
+
+### Acquisitions
+
+```ruby
+# List acquisitions
+client.acquisitions.list(take: 25, skip: 0)
+client.acquisitions.list(type: "Purchase", acquired_from_contact_id: "uuid")
+
+# Find by ID or external ID
+client.acquisitions.find("uuid")
+client.acquisitions.find_by_external_id("my-ext-id")
+
+# Create
+client.acquisitions.create(
+  date: "2024-01-15",
+  type: "Purchase",
+  invoice_number: "INV-001",
+  external_id: "my-acq-001"
+)
+
+# Update
+client.acquisitions.update("uuid", invoice_number: "INV-002")
+
+# Delete
+client.acquisitions.destroy("uuid")
+
+# Attach a contact
+client.acquisitions.attach_contact("acquisition-uuid", "contact-uuid")
+
+# Commit
+client.acquisitions.commit("uuid")
+client.acquisitions.commit("uuid", list_acquired_items: true)
+
+# Create and commit in one request
+client.acquisitions.create_and_commit(
+  date: "2024-01-15",
+  type: "Purchase",
+  contact_id: "contact-uuid",
+  items: [{ manufacturer: "Glock", model: "19", serial: "ABC123", type: "Pistol", caliber: "9mm" }]
+)
+
+# Create as pending (does not commit)
+client.acquisitions.create_as_pending(
+  date: "2024-01-15",
+  type: "Purchase",
+  contact_id: "contact-uuid",
+  items: [{ manufacturer: "Glock", model: "19", serial: "ABC123", type: "Pistol", caliber: "9mm" }]
+)
+
+# Items
+client.acquisitions.get_item("acquisition-uuid", "item-uuid")
+client.acquisitions.add_item("acquisition-uuid", manufacturer: "Glock", model: "19", serial: "ABC123", type: "Pistol", caliber: "9mm")
+client.acquisitions.add_items("acquisition-uuid", [
+  { manufacturer: "Glock", model: "19", serial: "ABC123", type: "Pistol", caliber: "9mm" },
+  { manufacturer: "Glock", model: "17", serial: "DEF456", type: "Pistol", caliber: "9mm" }
+])
+client.acquisitions.update_item("acquisition-uuid", "item-uuid", location: "Safe A")
+client.acquisitions.delete_item("acquisition-uuid", "item-uuid")
+```
+
+### Attachments
+
+```ruby
+# Returns raw binary data
+pdf_bytes = client.attachments.download("attachment-uuid")
+File.binwrite("attachment.pdf", pdf_bytes)
+```
+
+### Contacts
+
+```ruby
+# List contacts
+client.contacts.list(take: 25, skip: 0)
+client.contacts.list(last_name: "Smith", ffl_number: "1-23-456-07-8A-12345")
+
+# Find by ID or external ID
+client.contacts.find("uuid")
+client.contacts.find_by_external_id("my-ext-id")
+
+# Create
+client.contacts.create(
+  first_name: "John",
+  last_name: "Smith",
+  ffl_number: "1-23-456-07-8A-12345",
+  ffl_expires: "2026-12-31",
+  premise_address1: "123 Main St",
+  premise_city: "Anytown",
+  premise_state: "TX",
+  premise_zip_code: "75001"
+)
+
+# Update
+client.contacts.update("uuid", email_address: "john@example.com")
+
+# Delete
+client.contacts.destroy("uuid")
+
+# Merge two contacts (winning contact receives all data from losing contact)
+client.contacts.merge(winning_contact_id: "uuid-1", losing_contact_id: "uuid-2")
+
+# Licenses
+client.contacts.get_license("contact-uuid", "license-uuid")
+client.contacts.create_license("contact-uuid", type: "FFL", number: "1-23-456-07-8A-12345", expiration: "2026-12-31")
+client.contacts.update_license("contact-uuid", "license-uuid", copy_on_file: true)
+client.contacts.delete_license("contact-uuid", "license-uuid")
+```
+
+### Dispositions
+
+```ruby
+# List dispositions
+client.dispositions.list(take: 25, skip: 0)
+client.dispositions.list(type: "SaleTo", disposed_to_contact_id: "uuid")
+client.dispositions.list(include_4473: true)
+
+# List Form 4473 dispositions
+client.dispositions.list_4473s(take: 25)
+client.dispositions.list_4473s(include_awaiting_completion: true)
+
+# Find by ID or external ID
+client.dispositions.find("uuid")
+client.dispositions.find_by_external_id("my-ext-id")
+
+# Create standard disposition
+client.dispositions.create(type: "SaleTo", date: "2024-01-15", generate_ttsn: true)
+
+# Create special disposition types
+client.dispositions.create_nfa(date: "2024-01-15", type: "SaleTo", submission_date: "2024-01-10")
+client.dispositions.create_theft_loss(date: "2024-01-15", theft_loss__type: "Theft")
+client.dispositions.create_destroyed(date: "2024-01-15", destroyed__description: "Destroyed per ATF")
+
+# Update
+client.dispositions.update("uuid", note: "Updated note")
+
+# Delete
+client.dispositions.destroy("uuid")
+
+# Attach a contact
+client.dispositions.attach_contact("disposition-uuid", "contact-uuid")
+
+# Lock
+client.dispositions.lock("uuid")
+client.dispositions.lock_by_external_id("my-ext-id")
+
+# Commit
+client.dispositions.commit("uuid")
+client.dispositions.commit("uuid", list_disposed_items: true)
+
+# Create and commit in one request
+client.dispositions.create_and_commit(
+  type: "SaleTo",
+  date: "2024-01-15",
+  contact_id: "contact-uuid",
+  items: [{ id: "item-uuid", price: 500.00 }]
+)
+
+# Create as pending (does not commit)
+client.dispositions.create_as_pending(
+  type: "SaleTo",
+  date: "2024-01-15",
+  contact_id: "contact-uuid",
+  items: [{ id: "item-uuid", price: 500.00 }]
+)
+
+# Items
+client.dispositions.list_items("disposition-uuid")
+client.dispositions.add_items("disposition-uuid", [{ id: "item-uuid", price: 500.00 }])
+client.dispositions.add_items_by_external_id("disp-ext-id", [{ external_id: "item-ext-id", price: 500.00 }])
+client.dispositions.add_items_by_search("disp-ext-id", manufacturer: "Glock", model: "19", caliber: "9mm")
+client.dispositions.edit_item_price("disposition-uuid", "item-uuid", price: 550.00)
+client.dispositions.remove_item("disposition-uuid", "item-uuid")
+client.dispositions.remove_item_by_external_id("disposition-uuid", "item-ext-id")
+```
+
+### Downloads
+
+```ruby
+# Download bound book as binary (PDF or CSV depending on API response)
+data = client.downloads.bound_book
+File.binwrite("bound_book.pdf", data)
+```
+
+### Form 4473s
+
+```ruby
+# Returns raw binary PDF data
+pdf_bytes = client.form4473s.download("form4473-uuid")
+File.binwrite("form4473.pdf", pdf_bytes)
+```
+
+### Inventory
+
+```ruby
+# Bulk verify inventory by serial number
+result = client.inventory.bulk_verify(
+  serials: ["ABC123", "DEF456", "GHI789"],
+  rollback_partial: true,
+  update_location: true,
+  location: "Safe A",
+  verified_utc: "2024-01-15T10:00:00Z"
+)
+```
+
+### Items
+
+```ruby
+# List items (extensive filtering available)
+client.items.list(take: 25, skip: 0)
+client.items.list(manufacturer: "Glock", caliber: "9mm", status: 1)
+client.items.list(serial: "ABC123")
+client.items.list(acquired_on_or_after: "2024-01-01", acquired_on_or_before: "2024-12-31")
+client.items.list(is_theft_loss: false, is_destroyed: false)
+
+# Find by ID or external ID
+client.items.find("uuid")
+client.items.find_by_external_id("my-ext-id")
+
+# Update
+client.items.update("uuid", location: "Safe B", note: "Cleaned and inspected")
+
+# Delete (logical delete with type)
+client.items.delete("uuid", delete_type: "Destroyed", delete_note: "Per ATF guidelines")
+
+# Set acquisition contact
+client.items.set_acquisition_contact("item-uuid", "contact-uuid")
+
+# Undispose
+client.items.undispose("uuid")
+client.items.undispose("uuid", note: "Returned by customer")
+
+# Set external IDs
+client.items.set_external_id("uuid", external_id: "my-item-001")
+client.items.set_external_ids([
+  { id: "uuid-1", external_id: "my-item-001" },
+  { id: "uuid-2", external_id: "my-item-002" }
+])
+```
+
+### Multiple Sale Reports
+
+```ruby
+# Returns raw binary PDF data
+pdf_bytes = client.multiple_sale_reports.download("report-uuid", "attachment-uuid")
+File.binwrite("multiple_sale_report.pdf", pdf_bytes)
+```
+
+### Smart Lists
+
+Smart lists return the allowed values for various fields in your account.
+
+```ruby
+client.smart_lists.acquire_types
+client.smart_lists.calibers
+client.smart_lists.conditions
+client.smart_lists.countries_of_manufacture
+client.smart_lists.delete_types
+client.smart_lists.dispose_types
+client.smart_lists.importers
+client.smart_lists.item_types
+client.smart_lists.license_types
+client.smart_lists.locations
+client.smart_lists.manufacturers
+client.smart_lists.theft_loss_types
+client.smart_lists.manufacturing_dispose_types
+client.smart_lists.manufacturing_acquire_types
+```
+
+### Users
+
+```ruby
+client.users.list
+client.users.list(include_disabled: true)
+```
+
+### Webhooks
+
+```ruby
+# List available webhook events
+client.webhooks.list_events
+
+# Find a webhook by name
+client.webhooks.find("my-webhook")
+
+# Create a webhook
+client.webhooks.create(
+  name: "my-webhook",
+  url: "https://example.com/webhooks/fastbound",
+  description: "Acquisition notifications",
+  events: ["acquisition.committed", "disposition.committed"]
+)
+
+# Update a webhook
+client.webhooks.update("my-webhook", url: "https://example.com/webhooks/v2")
+
+# Delete a webhook
+client.webhooks.destroy("my-webhook")
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.contacts.find("nonexistent-uuid")
+rescue Fastbound::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue Fastbound::UnprocessableEntityError => e
+  puts "Validation failed: #{e.errors.join(", ")}"
+rescue Fastbound::UnauthorizedError => e
+  puts "Auth error: #{e.message}"
+rescue Fastbound::ApiError => e
+  puts "API error #{e.status}: #{e.message}"
+end
+```
+
+| Exception | HTTP Status |
+|---|---|
+| `Fastbound::UnauthorizedError` | 401, 403 |
+| `Fastbound::NotFoundError` | 404 |
+| `Fastbound::UnprocessableEntityError` | 400, 422 |
+| `Fastbound::ApiError` | All other errors |
+
+## License
+
+MIT

data/lib/fastbound/client.rb

@@ -0,0 +1,154 @@
+require "faraday"
+require "json"
+
+module Fastbound
+  class Client
+    BASE_URL = "https://cloud.fastbound.com"
+
+    attr_reader :account_number, :audit_user
+
+    def initialize(api_key:, account_number:, audit_user: nil, base_url: BASE_URL)
+      raise ConfigurationError, "api_key is required" if api_key.nil? || api_key.empty?
+      raise ConfigurationError, "account_number is required" if account_number.nil? || account_number.empty?
+
+      @api_key = api_key
+      @account_number = account_number
+      @audit_user = audit_user
+      @base_url = base_url
+    end
+
+    def account
+      @account ||= Resources::Account.new(self)
+    end
+
+    def acquisitions
+      @acquisitions ||= Resources::Acquisitions.new(self)
+    end
+
+    def attachments
+      @attachments ||= Resources::Attachments.new(self)
+    end
+
+    def contacts
+      @contacts ||= Resources::Contacts.new(self)
+    end
+
+    def dispositions
+      @dispositions ||= Resources::Dispositions.new(self)
+    end
+
+    def downloads
+      @downloads ||= Resources::Downloads.new(self)
+    end
+
+    def form4473s
+      @form4473s ||= Resources::Form4473s.new(self)
+    end
+
+    def inventory
+      @inventory ||= Resources::Inventory.new(self)
+    end
+
+    def items
+      @items ||= Resources::Items.new(self)
+    end
+
+    def multiple_sale_reports
+      @multiple_sale_reports ||= Resources::MultipleSaleReports.new(self)
+    end
+
+    def smart_lists
+      @smart_lists ||= Resources::SmartLists.new(self)
+    end
+
+    def users
+      @users ||= Resources::Users.new(self)
+    end
+
+    def webhooks
+      @webhooks ||= Resources::Webhooks.new(self)
+    end
+
+    def get(path, params = {})
+      request(:get, path, params: compact(params))
+    end
+
+    def post(path, body = {}, audit: true)
+      request(:post, path, body: body, audit: audit)
+    end
+
+    def put(path, body = {}, audit: true)
+      request(:put, path, body: body, audit: audit)
+    end
+
+    def delete(path, audit: true)
+      request(:delete, path, audit: audit)
+    end
+
+    def get_binary(path)
+      response = connection.get(path)
+      handle_response(response, raw: true)
+    end
+
+    def post_binary(path, body = {}, audit: true)
+      response = connection(audit: audit).post(path) do |req|
+        req.body = body.to_json
+        req.headers["Content-Type"] = "application/json"
+      end
+      handle_response(response, raw: true)
+    end
+
+    def base_path
+      "/#{account_number}/api"
+    end
+
+    private
+
+    def request(method, path, params: nil, body: nil, audit: false)
+      response = connection(audit: audit).public_send(method, path) do |req|
+        req.params = params if params&.any?
+        if body
+          req.body = body.to_json
+          req.headers["Content-Type"] = "application/json"
+        end
+      end
+      handle_response(response)
+    end
+
+    def handle_response(response, raw: false)
+      case response.status
+      when 200, 201
+        return response.body if raw
+        response.body.empty? ? nil : JSON.parse(response.body)
+      when 204
+        nil
+      when 401, 403
+        raise UnauthorizedError.new(response.status, safe_parse(response.body))
+      when 404
+        raise NotFoundError.new(response.status, safe_parse(response.body))
+      when 400, 422
+        raise UnprocessableEntityError.new(response.status, safe_parse(response.body))
+      else
+        raise ApiError.new(response.status, safe_parse(response.body))
+      end
+    end
+
+    def safe_parse(body)
+      JSON.parse(body)
+    rescue StandardError
+      {}
+    end
+
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
+
+    def connection(audit: false)
+      Faraday.new(url: @base_url) do |conn|
+        conn.request :authorization, :basic, @api_key, ""
+        conn.headers["Accept"] = "application/json"
+        conn.headers["X-AuditUser"] = @audit_user if audit && @audit_user
+      end
+    end
+  end
+end

data/lib/fastbound/error.rb

@@ -0,0 +1,31 @@
+module Fastbound
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class ApiError < Error
+    attr_reader :status, :errors
+
+    def initialize(status, body)
+      @status = status
+      @errors = parse_errors(body)
+      super(build_message)
+    end
+
+    private
+
+    def parse_errors(body)
+      return [] unless body.is_a?(Hash)
+
+      Array(body["errors"]).map { |e| e.is_a?(Hash) ? e["message"] : e.to_s }.compact
+    end
+
+    def build_message
+      base = "HTTP #{status}"
+      errors.any? ? "#{base}: #{errors.join(", ")}" : base
+    end
+  end
+
+  class NotFoundError < ApiError; end
+  class UnprocessableEntityError < ApiError; end
+  class UnauthorizedError < ApiError; end
+end

data/lib/fastbound/resources/account.rb

@@ -0,0 +1,13 @@
+module Fastbound
+  module Resources
+    class Account
+      def initialize(client)
+        @client = client
+      end
+
+      def get
+        @client.get("#{@client.base_path}/Account")
+      end
+    end
+  end
+end

data/lib/fastbound/resources/acquisitions.rb

@@ -0,0 +1,97 @@
+module Fastbound
+  module Resources
+    class Acquisitions
+      def initialize(client)
+        @client = client
+      end
+
+      def list(take: nil, skip: nil, id: nil, external_id: nil, type: nil,
+               purchase_order_number: nil, invoice_number: nil,
+               shipment_tracking_number: nil, is_manufacturing_acquisition: nil,
+               acquired_from_contact_id: nil, acquired_from_contact_external_id: nil,
+               item_id: nil, item_external_id: nil)
+        @client.get("#{base}/Acquisitions", {
+          take: take, skip: skip, id: id, externalId: external_id, type: type,
+          purchaseOrderNumber: purchase_order_number, invoiceNumber: invoice_number,
+          shipmentTrackingNumber: shipment_tracking_number,
+          isManufacturingAcquisition: is_manufacturing_acquisition,
+          acquiredFromContactId: acquired_from_contact_id,
+          acquiredFromContactExternalId: acquired_from_contact_external_id,
+          itemId: item_id, itemExternalId: item_external_id
+        })
+      end
+
+      def find(id)
+        @client.get("#{base}/Acquisitions/#{id}")
+      end
+
+      def find_by_external_id(external_id)
+        @client.get("#{base}/Acquisitions/GetByExternalId/#{external_id}")
+      end
+
+      def create(params = {})
+        @client.post("#{base}/Acquisitions", params)
+      end
+
+      def update(id, params = {})
+        @client.put("#{base}/Acquisitions/#{id}", params)
+      end
+
+      def destroy(id)
+        @client.delete("#{base}/Acquisitions/#{id}")
+      end
+
+      def attach_contact(id, contact_id)
+        @client.put("#{base}/Acquisitions/#{id}/AttachContact/#{contact_id}", {})
+      end
+
+      def commit(id, params = {}, list_acquired_items: nil)
+        path = "#{base}/Acquisitions/#{id}/Commit"
+        path += "?listAcquiredItems=true" if list_acquired_items
+        @client.post(path, params)
+      end
+
+      def create_and_commit(params = {}, list_acquired_items: nil)
+        path = "#{base}/Acquisitions/CreateAndCommit"
+        path += "?listAcquiredItems=true" if list_acquired_items
+        @client.post(path, params)
+      end
+
+      def create_as_pending(params = {})
+        @client.post("#{base}/Acquisitions/CreateAsPending", params)
+      end
+
+      # Item operations
+
+      def get_item(id, acquisition_item_id)
+        @client.get("#{base}/Acquisitions/#{id}/Items/#{acquisition_item_id}")
+      end
+
+      def get_item_by_external_ids(acquisition_external_id, acquisition_item_external_id)
+        @client.get("#{base}/Acquisitions/#{acquisition_external_id}/Items/#{acquisition_item_external_id}")
+      end
+
+      def add_item(id, params = {})
+        @client.post("#{base}/Acquisitions/#{id}/Items", params)
+      end
+
+      def add_items(id, items = [])
+        @client.post("#{base}/Acquisitions/#{id}/Items/Multiple", { items: items })
+      end
+
+      def update_item(id, acquisition_item_id, params = {})
+        @client.put("#{base}/Acquisitions/#{id}/Items/#{acquisition_item_id}", params)
+      end
+
+      def delete_item(id, acquisition_item_id)
+        @client.delete("#{base}/Acquisitions/#{id}/Items/#{acquisition_item_id}")
+      end
+
+      private
+
+      def base
+        @client.base_path
+      end
+    end
+  end
+end

data/lib/fastbound/resources/attachments.rb

@@ -0,0 +1,13 @@
+module Fastbound
+  module Resources
+    class Attachments
+      def initialize(client)
+        @client = client
+      end
+
+      def download(attachment_id)
+        @client.get_binary("#{@client.base_path}/Attachments/Download/#{attachment_id}")
+      end
+    end
+  end
+end

data/lib/fastbound/resources/contacts.rb

@@ -0,0 +1,71 @@
+module Fastbound
+  module Resources
+    class Contacts
+      def initialize(client)
+        @client = client
+      end
+
+      def list(license_name: nil, trade_name: nil, ffl_number: nil,
+               organization_name: nil, first_name: nil, middle_name: nil,
+               last_name: nil, suffix: nil, take: nil, skip: nil)
+        @client.get("#{base}/Contacts", {
+          licenseName: license_name, tradeName: trade_name, fflNumber: ffl_number,
+          organizationName: organization_name, firstName: first_name,
+          middleName: middle_name, lastName: last_name, suffix: suffix,
+          take: take, skip: skip
+        })
+      end
+
+      def find(id)
+        @client.get("#{base}/Contacts/#{id}")
+      end
+
+      def find_by_external_id(external_id)
+        @client.get("#{base}/Contacts/GetByExternalId/#{external_id}")
+      end
+
+      def create(params = {})
+        @client.post("#{base}/Contacts", params)
+      end
+
+      def update(id, params = {})
+        @client.put("#{base}/Contacts/#{id}", params)
+      end
+
+      def destroy(id)
+        @client.delete("#{base}/Contacts/#{id}")
+      end
+
+      def merge(winning_contact_id:, losing_contact_id:)
+        @client.post("#{base}/Contacts/Merge", {
+          winningContactId: winning_contact_id,
+          losingContactId: losing_contact_id
+        })
+      end
+
+      # License operations
+
+      def get_license(id, license_id)
+        @client.get("#{base}/Contacts/#{id}/Licenses/#{license_id}")
+      end
+
+      def create_license(id, params = {})
+        @client.post("#{base}/Contacts/#{id}/Licenses", params)
+      end
+
+      def update_license(id, license_id, params = {})
+        @client.put("#{base}/Contacts/#{id}/Licenses/#{license_id}", params)
+      end
+
+      def delete_license(id, license_id)
+        @client.delete("#{base}/Contacts/#{id}/Licenses/#{license_id}")
+      end
+
+      private
+
+      def base
+        @client.base_path
+      end
+    end
+  end
+end

data/lib/fastbound/resources/dispositions.rb

@@ -0,0 +1,129 @@
+module Fastbound
+  module Resources
+    class Dispositions
+      def initialize(client)
+        @client = client
+      end
+
+      def list(take: nil, skip: nil, include_4473: nil, id: nil, external_id: nil,
+               type: nil, ttsn: nil, otsn: nil, purchase_order_number: nil,
+               invoice_number: nil, shipment_tracking_number: nil,
+               is_manufacturing_disposition: nil, disposed_to_contact_id: nil,
+               disposed_to_contact_external_id: nil, item_id: nil, item_external_id: nil)
+        @client.get("#{base}/Dispositions", {
+          take: take, skip: skip, include4473: include_4473, id: id,
+          externalId: external_id, type: type, TTSN: ttsn, OTSN: otsn,
+          purchaseOrderNumber: purchase_order_number, invoiceNumber: invoice_number,
+          shipmentTrackingNumber: shipment_tracking_number,
+          isManufacturingDisposition: is_manufacturing_disposition,
+          disposedToContactId: disposed_to_contact_id,
+          disposedToContactExternalId: disposed_to_contact_external_id,
+          itemId: item_id, itemExternalId: item_external_id
+        })
+      end
+
+      def list_4473s(take: nil, skip: nil, include_awaiting_completion: nil)
+        @client.get("#{base}/Dispositions/Only4473s", {
+          take: take, skip: skip,
+          includeAwaiting4473Completion: include_awaiting_completion
+        })
+      end
+
+      def find(id)
+        @client.get("#{base}/Dispositions/#{id}")
+      end
+
+      def find_by_external_id(external_id)
+        @client.get("#{base}/Dispositions/GetByExternalId/#{external_id}")
+      end
+
+      def create(params = {})
+        @client.post("#{base}/Dispositions", params)
+      end
+
+      def create_nfa(params = {})
+        @client.post("#{base}/Dispositions/NFA", params)
+      end
+
+      def create_theft_loss(params = {})
+        @client.post("#{base}/Dispositions/TheftLoss", params)
+      end
+
+      def create_destroyed(params = {})
+        @client.post("#{base}/Dispositions/Destroyed", params)
+      end
+
+      def update(id, params = {})
+        @client.put("#{base}/Dispositions/#{id}", params)
+      end
+
+      def destroy(id)
+        @client.delete("#{base}/Dispositions/#{id}")
+      end
+
+      def attach_contact(id, contact_id)
+        @client.put("#{base}/Dispositions/#{id}/AttachContact/#{contact_id}", {})
+      end
+
+      def lock(id)
+        @client.put("#{base}/Dispositions/Lock/#{id}", {})
+      end
+
+      def lock_by_external_id(external_id)
+        @client.put("#{base}/Dispositions/LockByExternalId/#{external_id}", {})
+      end
+
+      def commit(id, params = {}, list_disposed_items: nil)
+        path = "#{base}/Dispositions/#{id}/Commit"
+        path += "?listDisposedItems=true" if list_disposed_items
+        @client.post(path, params)
+      end
+
+      def create_and_commit(params = {}, list_disposed_items: nil)
+        path = "#{base}/Dispositions/CreateAndCommit"
+        path += "?listDisposedItems=true" if list_disposed_items
+        @client.post(path, params)
+      end
+
+      def create_as_pending(params = {})
+        @client.post("#{base}/Dispositions/CreateAsPending", params)
+      end
+
+      # Item operations
+
+      def list_items(id)
+        @client.get("#{base}/Dispositions/#{id}/Items")
+      end
+
+      def add_items(id, items = [])
+        @client.post("#{base}/Dispositions/#{id}/Items", { items: items })
+      end
+
+      def add_items_by_external_id(disposition_external_id, items = [])
+        @client.post("#{base}/Dispositions/#{disposition_external_id}/Items/AddByExternalId", { items: items })
+      end
+
+      def add_items_by_search(disposition_external_id, params = {})
+        @client.post("#{base}/Dispositions/#{disposition_external_id}/Items/AddBySearch", params)
+      end
+
+      def edit_item_price(id, item_id, price:)
+        @client.put("#{base}/Dispositions/#{id}/Items/EditPrice/#{item_id}", { price: price })
+      end
+
+      def remove_item(id, item_id)
+        @client.delete("#{base}/Dispositions/#{id}/Items/Remove/#{item_id}")
+      end
+
+      def remove_item_by_external_id(id, item_external_id)
+        @client.delete("#{base}/Dispositions/#{id}/Items/RemoveByExternalId/#{item_external_id}")
+      end
+
+      private
+
+      def base
+        @client.base_path
+      end
+    end
+  end
+end

data/lib/fastbound/resources/downloads.rb

@@ -0,0 +1,13 @@
+module Fastbound
+  module Resources
+    class Downloads
+      def initialize(client)
+        @client = client
+      end
+
+      def bound_book(params = {})
+        @client.post_binary("#{@client.base_path}/Downloads/BoundBook", params)
+      end
+    end
+  end
+end

data/lib/fastbound/resources/form4473s.rb

@@ -0,0 +1,13 @@
+module Fastbound
+  module Resources
+    class Form4473s
+      def initialize(client)
+        @client = client
+      end
+
+      def download(form4473_id)
+        @client.get_binary("#{@client.base_path}/Form4473s/Download/#{form4473_id}")
+      end
+    end
+  end
+end

data/lib/fastbound/resources/inventory.rb

@@ -0,0 +1,20 @@
+module Fastbound
+  module Resources
+    class Inventory
+      def initialize(client)
+        @client = client
+      end
+
+      def bulk_verify(serials:, rollback_partial: nil, update_location: nil,
+                      location: nil, verified_utc: nil)
+        @client.put("#{@client.base_path}/Inventory/BulkVerify", {
+          serials: serials,
+          rollbackPartial: rollback_partial,
+          updateLocation: update_location,
+          location: location,
+          verifiedUtc: verified_utc
+        }.reject { |_, v| v.nil? })
+      end
+    end
+  end
+end

data/lib/fastbound/resources/items.rb

@@ -0,0 +1,84 @@
+module Fastbound
+  module Resources
+    class Items
+      def initialize(client)
+        @client = client
+      end
+
+      def list(search: nil, item_number: nil, serial: nil, manufacturer: nil,
+               importer: nil, model: nil, type: nil, caliber: nil, location: nil,
+               condition: nil, mpn: nil, upc: nil, sku: nil, is_theft_loss: nil,
+               is_destroyed: nil, do_not_dispose: nil, disposition_id: nil,
+               status: nil, acquired_on_or_after: nil, acquired_on_or_before: nil,
+               acquire_purchase_order_number: nil, acquire_invoice_number: nil,
+               acquire_shipment_tracking_number: nil, disposed_on_or_after: nil,
+               disposed_on_or_before: nil, dispose_purchase_order_number: nil,
+               dispose_invoice_number: nil, dispose_shipment_tracking_number: nil,
+               has_external_id: nil, acquisition_type: nil, ttsn: nil, otsn: nil,
+               take: nil, skip: nil)
+        @client.get("#{base}/Items", {
+          search: search, itemNumber: item_number, serial: serial,
+          manufacturer: manufacturer, importer: importer, model: model,
+          type: type, caliber: caliber, location: location, condition: condition,
+          mpn: mpn, upc: upc, sku: sku, isTheftLoss: is_theft_loss,
+          isDestroyed: is_destroyed, doNotDispose: do_not_dispose,
+          dispositionId: disposition_id, status: status,
+          acquiredOnOrAfter: acquired_on_or_after,
+          acquiredOnOrBefore: acquired_on_or_before,
+          acquirePurchaseOrderNumber: acquire_purchase_order_number,
+          acquireInvoiceNumber: acquire_invoice_number,
+          acquireShipmentTrackingNumber: acquire_shipment_tracking_number,
+          disposedOnOrAfter: disposed_on_or_after,
+          disposedOnOrBefore: disposed_on_or_before,
+          disposePurchaseOrderNumber: dispose_purchase_order_number,
+          disposeInvoiceNumber: dispose_invoice_number,
+          disposeShipmentTrackingNumber: dispose_shipment_tracking_number,
+          hasExternalId: has_external_id, acquisitionType: acquisition_type,
+          ttsn: ttsn, otsn: otsn, take: take, skip: skip
+        })
+      end
+
+      def find(id)
+        @client.get("#{base}/Items/#{id}")
+      end
+
+      def find_by_external_id(external_id)
+        @client.get("#{base}/Items/GetByExternalId/#{external_id}")
+      end
+
+      def update(id, params = {})
+        @client.put("#{base}/Items/#{id}", params)
+      end
+
+      def delete(id, delete_type:, delete_note: nil)
+        @client.post("#{base}/Items/#{id}/Delete", {
+          deleteType: delete_type,
+          deleteNote: delete_note
+        }.reject { |_, v| v.nil? })
+      end
+
+      def set_acquisition_contact(id, contact_id)
+        @client.put("#{base}/Items/#{id}/AcquisitionContact/#{contact_id}", {})
+      end
+
+      def undispose(id, note: nil)
+        body = note ? { note: note } : {}
+        @client.put("#{base}/Items/#{id}/Undispose", body)
+      end
+
+      def set_external_id(id, external_id:)
+        @client.put("#{base}/Items/#{id}/SetExternalId", { externalId: external_id })
+      end
+
+      def set_external_ids(items = [])
+        @client.put("#{base}/Items/SetExternalIds", { items: items })
+      end
+
+      private
+
+      def base
+        @client.base_path
+      end
+    end
+  end
+end

data/lib/fastbound/resources/multiple_sale_reports.rb

@@ -0,0 +1,15 @@
+module Fastbound
+  module Resources
+    class MultipleSaleReports
+      def initialize(client)
+        @client = client
+      end
+
+      def download(multiple_sale_report_id, attachment_id)
+        @client.get_binary(
+          "#{@client.base_path}/MultipleSaleReports/Download/#{multiple_sale_report_id}/a/#{attachment_id}"
+        )
+      end
+    end
+  end
+end

data/lib/fastbound/resources/smart_lists.rb

@@ -0,0 +1,71 @@
+module Fastbound
+  module Resources
+    class SmartLists
+      def initialize(client)
+        @client = client
+      end
+
+      def acquire_types
+        @client.get("#{base}/SmartLists/AcquireType")
+      end
+
+      def calibers
+        @client.get("#{base}/SmartLists/Caliber")
+      end
+
+      def conditions
+        @client.get("#{base}/SmartLists/Condition")
+      end
+
+      def countries_of_manufacture
+        @client.get("#{base}/SmartLists/CountryOfManufacture")
+      end
+
+      def delete_types
+        @client.get("#{base}/SmartLists/DeleteType")
+      end
+
+      def dispose_types
+        @client.get("#{base}/SmartLists/DisposeType")
+      end
+
+      def importers
+        @client.get("#{base}/SmartLists/Importer")
+      end
+
+      def item_types
+        @client.get("#{base}/SmartLists/ItemType")
+      end
+
+      def license_types
+        @client.get("#{base}/SmartLists/LicenseType")
+      end
+
+      def locations
+        @client.get("#{base}/SmartLists/Location")
+      end
+
+      def manufacturers
+        @client.get("#{base}/SmartLists/Manufacturer")
+      end
+
+      def theft_loss_types
+        @client.get("#{base}/SmartLists/TheftLossType")
+      end
+
+      def manufacturing_dispose_types
+        @client.get("#{base}/SmartLists/ManufacturingDisposeType")
+      end
+
+      def manufacturing_acquire_types
+        @client.get("#{base}/SmartLists/ManufacturingAcquireType")
+      end
+
+      private
+
+      def base
+        @client.base_path
+      end
+    end
+  end
+end

data/lib/fastbound/resources/users.rb

@@ -0,0 +1,13 @@
+module Fastbound
+  module Resources
+    class Users
+      def initialize(client)
+        @client = client
+      end
+
+      def list(include_disabled: nil)
+        @client.get("#{@client.base_path}/Users", { IncludeDisabled: include_disabled })
+      end
+    end
+  end
+end

data/lib/fastbound/resources/webhooks.rb

@@ -0,0 +1,39 @@
+module Fastbound
+  module Resources
+    class Webhooks
+      def initialize(client)
+        @client = client
+      end
+
+      def list_events
+        @client.get("#{base}/Webhooks/Events")
+      end
+
+      def find(name)
+        @client.get("#{base}/Webhooks/#{name}")
+      end
+
+      def create(name:, url:, description: nil, events: [])
+        @client.post("#{base}/Webhooks", {
+          name: name, url: url, description: description, events: events
+        }.reject { |_, v| v.nil? })
+      end
+
+      def update(name, url: nil, description: nil, events: nil)
+        @client.put("#{base}/Webhooks/#{name}", {
+          name: name, url: url, description: description, events: events
+        }.reject { |_, v| v.nil? })
+      end
+
+      def destroy(name)
+        @client.delete("#{base}/Webhooks/#{name}")
+      end
+
+      private
+
+      def base
+        @client.base_path
+      end
+    end
+  end
+end

data/lib/fastbound/version.rb

@@ -0,0 +1,3 @@
+module Fastbound
+  VERSION = "0.1.0"
+end

data/lib/fastbound.rb

@@ -0,0 +1,19 @@
+require "fastbound/version"
+require "fastbound/error"
+require "fastbound/client"
+require "fastbound/resources/account"
+require "fastbound/resources/acquisitions"
+require "fastbound/resources/attachments"
+require "fastbound/resources/contacts"
+require "fastbound/resources/dispositions"
+require "fastbound/resources/downloads"
+require "fastbound/resources/form4473s"
+require "fastbound/resources/inventory"
+require "fastbound/resources/items"
+require "fastbound/resources/multiple_sale_reports"
+require "fastbound/resources/smart_lists"
+require "fastbound/resources/users"
+require "fastbound/resources/webhooks"
+
+module Fastbound
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: fastbound
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- JD Warren
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description:
+email:
+- johndavid400@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/fastbound.rb
+- lib/fastbound/client.rb
+- lib/fastbound/error.rb
+- lib/fastbound/resources/account.rb
+- lib/fastbound/resources/acquisitions.rb
+- lib/fastbound/resources/attachments.rb
+- lib/fastbound/resources/contacts.rb
+- lib/fastbound/resources/dispositions.rb
+- lib/fastbound/resources/downloads.rb
+- lib/fastbound/resources/form4473s.rb
+- lib/fastbound/resources/inventory.rb
+- lib/fastbound/resources/items.rb
+- lib/fastbound/resources/multiple_sale_reports.rb
+- lib/fastbound/resources/smart_lists.rb
+- lib/fastbound/resources/users.rb
+- lib/fastbound/resources/webhooks.rb
+- lib/fastbound/version.rb
+homepage: https://github.com/johndavid400/fastbound
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.9
+signing_key:
+specification_version: 4
+summary: Ruby API wrapper for the FastBound firearms compliance API
+test_files: []