candidhealth 1.11.0 → 1.14.3

data/lib/candid/internal/types/model.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Candid
+  module Internal
+    module Types
+      # @abstract
+      #
+      # An abstract model that all data objects will inherit from
+      class Model
+        include Type
+
+        class << self
+          # The defined fields for this model
+          #
+          # @api private
+          #
+          # @return [Hash<Symbol, Field>]
+          def fields
+            @fields ||= if self < Candid::Internal::Types::Model
+                          superclass.fields.dup
+                        else
+                          {}
+                        end
+          end
+
+          # Any extra fields that have been created from instantiation
+          #
+          # @api private
+          #
+          # @return [Hash<Symbol, Field>]
+          def extra_fields
+            @extra_fields ||= {}
+          end
+
+          # Define a new field on this model
+          #
+          # @param name [Symbol] The name of the field
+          # @param type [Class] Type of the field
+          # @option optional [Boolean] If it is an optional field
+          # @option nullable [Boolean] If it is a nullable field
+          # @option api_name [Symbol, String] Name in the API of this field. When serializing/deserializing, will use
+          #   this field name
+          # @return [void]
+          def field(name, type, optional: false, nullable: false, api_name: nil, default: nil)
+            add_field_definition(name: name, type: type, optional: optional, nullable: nullable, api_name: api_name,
+                                 default: default)
+
+            define_accessor(name)
+            define_setter(name)
+          end
+
+          # Define a new literal for this model
+          #
+          # @param name [Symbol]
+          # @param value [Object]
+          # @option api_name [Symbol, String]
+          # @return [void]
+          def literal(name, value, api_name: nil)
+            add_field_definition(name: name, type: value.class, optional: false, nullable: false, api_name: api_name,
+                                 value: value)
+
+            define_accessor(name)
+          end
+
+          # Adds a new field definition into the class's fields registry
+          #
+          # @api private
+          #
+          # @param name [Symbol]
+          # @param type [Class]
+          # @option optional [Boolean]
+          # @return [void]
+          private def add_field_definition(name:, type:, optional:, nullable:, api_name:, default: nil, value: nil)
+            fields[name.to_sym] =
+              Field.new(name: name, type: type, optional: optional, nullable: nullable, api_name: api_name,
+                        value: value, default: default)
+          end
+
+          # Adds a new field definition into the class's extra fields registry
+          #
+          # @api private
+          #
+          # @param name [Symbol]
+          # @param type [Class]
+          # @option required [Boolean]
+          # @option optional [Boolean]
+          # @return [void]
+          def add_extra_field_definition(name:, type:)
+            return if extra_fields.key?(name.to_sym)
+
+            extra_fields[name.to_sym] = Field.new(name: name, type: type, optional: true, nullable: false)
+
+            define_accessor(name)
+            define_setter(name)
+          end
+
+          # @api private
+          private def define_accessor(name)
+            method_name = name.to_sym
+
+            define_method(method_name) do
+              @data[name]
+            end
+          end
+
+          # @api private
+          private def define_setter(name)
+            method_name = :"#{name}="
+
+            define_method(method_name) do |val|
+              @data[name] = val
+            end
+          end
+
+          def coerce(value, strict: (respond_to?(:strict?) ? strict? : false))
+            return value if value.is_a?(self)
+
+            return value unless value.is_a?(::Hash)
+
+            new(value)
+          end
+
+          def load(str)
+            coerce(::JSON.parse(str, symbolize_names: true))
+          end
+
+          def ===(instance)
+            instance.class.ancestors.include?(self)
+          end
+        end
+
+        # Creates a new instance of this model
+        # TODO: Should all this logic be in `#coerce` instead?
+        #
+        # @param values [Hash]
+        # @option strict [Boolean]
+        # @return [self]
+        def initialize(values = {})
+          @data = {}
+
+          values = Utils.symbolize_keys(values.dup)
+
+          self.class.fields.each do |field_name, field|
+            value = values.delete(field.api_name)
+
+            field_value = value || (if field.literal?
+                                      field.value
+                                    elsif field.default
+                                      field.default
+                                    end)
+
+            @data[field_name] = Utils.coerce(field.type, field_value)
+          end
+
+          # Any remaining values in the input become extra fields
+          values.each do |name, value|
+            self.class.add_extra_field_definition(name: name, type: value.class)
+
+            @data[name.to_sym] = value
+          end
+        end
+
+        def to_h
+          self.class.fields.merge(self.class.extra_fields).each_with_object({}) do |(name, field), acc|
+            # If there is a value present in the data, use that value
+            # If there is a `nil` value present in the data, and it is optional but NOT nullable, exclude key altogether
+            # If there is a `nil` value present in the data, and it is optional and nullable, use the nil value
+
+            value = @data[name]
+
+            next if value.nil? && field.optional && !field.nullable
+
+            if value.is_a?(::Array)
+              value = value.map { |item| item.respond_to?(:to_h) ? item.to_h : item }
+            elsif value.respond_to?(:to_h)
+              value = value.to_h
+            end
+
+            acc[field.api_name] = value
+          end
+        end
+
+        def ==(other)
+          self.class == other.class && to_h == other.to_h
+        end
+
+        # @return [String]
+        def inspect
+          attrs = @data.map do |name, value|
+            "#{name}=#{value.inspect}"
+          end
+
+          "#<#{self.class.name}:0x#{object_id&.to_s(16)} #{attrs.join(" ")}>"
+        end
+      end
+    end
+  end
+end

data/lib/candid/internal/types/type.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Candid
+  module Internal
+    module Types
+      # @abstract
+      module Type
+        include Candid::Internal::JSON::Serializable
+
+        # Coerces a value to this type
+        #
+        # @param value [unknown]
+        # @option strict [Boolean] If we should strictly coerce this value
+        def coerce(value, strict: strict?)
+          raise NotImplementedError
+        end
+
+        # Returns if strictness is on for this type, defaults to `false`
+        #
+        # @return [Boolean]
+        def strict?
+          @strict ||= false
+        end
+
+        # Enable strictness by default for this type
+        #
+        # @return [void]
+        def strict!
+          @strict = true
+          self
+        end
+      end
+    end
+  end
+end

data/lib/candid/internal/types/union.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Candid
+  module Internal
+    module Types
+      # Define a union between two types
+      module Union
+        include Candid::Internal::Types::Type
+
+        def members
+          @members ||= []
+        end
+
+        # Add a member to this union
+        #
+        # @param type [Object]
+        # @option key [Symbol, String]
+        # @return [void]
+        def member(type, key: nil)
+          members.push([key, Utils.wrap_type(type)])
+          self
+        end
+
+        def member?(type)
+          members.any? { |_key, type_fn| type == type_fn.call }
+        end
+
+        # Set the discriminant for this union
+        #
+        # @param key [Symbol, String]
+        # @return [void]
+        def discriminant(key)
+          @discriminant = key
+        end
+
+        # @api private
+        private def discriminated?
+          !@discriminant.nil?
+        end
+
+        # Resolves the type of a value to be one of the members
+        #
+        # @param value [Object]
+        # @return [Class]
+        private def resolve_member(value)
+          if discriminated? && value.is_a?(::Hash)
+            discriminant_value = value.fetch(@discriminant, nil)
+
+            return if discriminant_value.nil?
+
+            members.to_h[discriminant_value]&.call
+          else
+            members.find do |_key, mem|
+              member_type = Utils.unwrap_type(mem)
+
+              value.is_a?(member_type)
+            end&.last&.call
+          end
+        end
+
+        def coerce(value, strict: strict?)
+          type = resolve_member(value)
+
+          unless type
+            return value unless strict
+
+            if discriminated?
+              raise Errors::TypeError,
+                    "value of type `#{value.class}` not member of union #{self}"
+            end
+
+            raise Errors::TypeError, "could not resolve to member of union #{self}"
+          end
+
+          Utils.coerce(type, value, strict: strict)
+        end
+      end
+    end
+  end
+end

data/lib/candid/internal/types/unknown.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Candid
+  module Internal
+    module Types
+      module Unknown
+        include Candid::Internal::Types::Type
+
+        def coerce(value)
+          value
+        end
+      end
+    end
+  end
+end

data/lib/candid/internal/types/utils.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Candid
+  module Internal
+    module Types
+      # Utilities for dealing with and checking types
+      module Utils
+        # Wraps a type into a type function
+        #
+        # @param type [Proc, Object]
+        # @return [Proc]
+        def self.wrap_type(type)
+          case type
+          when Proc
+            type
+          else
+            -> { type }
+          end
+        end
+
+        # Resolves a type or type function into a type
+        #
+        # @param type [Proc, Object]
+        # @return [Object]
+        def self.unwrap_type(type)
+          type.is_a?(Proc) ? type.call : type
+        end
+
+        def self.coerce(target, value, strict: false) # rubocop:disable Metrics/CyclomaticComplexity
+          type = unwrap_type(target)
+
+          case type
+          in Array
+            case value
+            when ::Array
+              return type.coerce(value, strict: strict)
+            when Set, ::Hash
+              return coerce(type, value.to_a)
+            end
+          in Hash
+            case value
+            when ::Hash
+              return type.coerce(value, strict: strict)
+            when ::Array
+              return coerce(type, value.to_h)
+            end
+          in ->(t) { t <= NilClass }
+            return nil
+          in ->(t) { t <= String }
+            case value
+            when String, Symbol, Numeric, TrueClass, FalseClass
+              return value.to_s
+            end
+          in ->(t) { t <= Symbol }
+            case value
+            when Symbol, String
+              return value.to_sym
+            end
+          in ->(t) { t <= Integer }
+            case value
+            when Numeric, String, Time
+              return value.to_i
+            end
+          in ->(t) { t <= Float }
+            case value
+            when Numeric, Time, String
+              return value.to_f
+            end
+          in ->(t) { t <= Model }
+            case value
+            when type
+              return value
+            when ::Hash
+              return type.coerce(value, strict: strict)
+            end
+          in Module
+            case type
+            in ->(t) { t.singleton_class.included_modules.include?(Enum) }
+              return type.coerce(value, strict: strict)
+            in ->(t) { t.singleton_class.included_modules.include?(Union) }
+              return type.coerce(value, strict: strict)
+            else
+              value
+            end
+          else
+            value
+          end
+
+          raise Errors::TypeError, "cannot coerce value of type `#{value.class}` to `#{target}`" if strict
+
+          value
+        end
+
+        def self.symbolize_keys(hash)
+          hash.transform_keys(&:to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/types/invoice.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module Types
+      class Invoice < Internal::Types::Model
+        field :id, -> { String }, optional: false, nullable: false
+        field :created_at, -> { String }, optional: false, nullable: false
+        field :updated_at, -> { String }, optional: false, nullable: false
+        field :organzation_id, -> { String }, optional: false, nullable: false
+        field :source_id, -> { String }, optional: false, nullable: false
+        field :source_customer_id, -> { String }, optional: false, nullable: false
+        field :patient_external_id, -> { String }, optional: false, nullable: false
+        field :note, -> { String }, optional: true, nullable: false
+        field :due_date, -> { String }, optional: false, nullable: false
+        field :status, -> { Candid::Invoices::Types::InvoiceStatus }, optional: false, nullable: false
+        field :url, -> { String }, optional: true, nullable: false
+        field :customer_invoice_url, -> { String }, optional: true, nullable: false
+        field :items, lambda {
+          Internal::Types::Array[Candid::Invoices::Types::InvoiceItem]
+        }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/candid/invoices/types/invoice_item.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module Types
+      class InvoiceItem < Internal::Types::Model
+        field :service_line_id, -> { String }, optional: false, nullable: false
+        field :amount_cents, -> { Integer }, optional: false, nullable: false
+      end
+    end
+  end
+end

data/lib/candid/invoices/types/invoice_status.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module Types
+      module InvoiceStatus
+        extend Candid::Internal::Types::Enum
+
+        DRAFT = "draft"
+        OPEN = "open"
+        PAID = "paid"
+        VOID = "void"
+        UNCOLLECTIBLE = "uncollectible"
+        HELD = "held"
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/claim_invoice_item.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        class ClaimInvoiceItem < Internal::Types::Model
+          field :claim_id, -> { String }, optional: false, nullable: false
+          field :amount_cents, -> { Integer }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/claim_invoice_item_info.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        class ClaimInvoiceItemInfo < Internal::Types::Model
+          field :claim_invoice_item, lambda {
+            Candid::Invoices::V2::Types::ClaimInvoiceItem
+          }, optional: true, nullable: false
+          field :service_line_invoice_items, lambda {
+            Internal::Types::Hash[String, Candid::Invoices::V2::Types::ServiceLineInvoiceItem]
+          }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/invoice.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        class Invoice < Internal::Types::Model
+          field :amount_cents, -> { Integer }, optional: false, nullable: false
+          field :created_at, -> { String }, optional: false, nullable: false
+          field :updated_at, -> { String }, optional: false, nullable: false
+          field :organization_id, -> { String }, optional: false, nullable: false
+          field :invoice_destination_metadata, lambda {
+            Candid::Invoices::V2::Types::InvoiceDestinationMetadata
+          }, optional: false, nullable: false
+          field :patient_external_id, -> { String }, optional: false, nullable: false
+          field :note, -> { String }, optional: true, nullable: false
+          field :due_date, -> { String }, optional: false, nullable: false
+          field :status, -> { Candid::Invoices::V2::Types::InvoiceStatus }, optional: false, nullable: false
+          field :url, -> { String }, optional: true, nullable: false
+          field :customer_invoice_url, -> { String }, optional: true, nullable: false
+          field :items, -> { Candid::Invoices::V2::Types::InvoiceItemInfo }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/invoice_destination.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        module InvoiceDestination
+          extend Candid::Internal::Types::Enum
+
+          STRIPE = "STRIPE"
+          CEDAR = "CEDAR"
+          HEALTHIE = "HEALTHIE"
+          COLLECTLY = "COLLECTLY"
+          THIRD_PARTY_PAYERS = "THIRD_PARTY_PAYERS"
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/invoice_destination_metadata.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        class InvoiceDestinationMetadata < Internal::Types::Model
+          field :invoice_destination, lambda {
+            Candid::Invoices::V2::Types::InvoiceDestination
+          }, optional: false, nullable: false
+          field :source_id, -> { String }, optional: false, nullable: false
+          field :source_customer_id, -> { String }, optional: false, nullable: false
+          field :destination_status, -> { String }, optional: true, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/invoice_info.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        class InvoiceInfo < Internal::Types::Model
+          field :id, -> { String }, optional: false, nullable: false
+          field :invoice, -> { Candid::Invoices::V2::Types::Invoice }, optional: false, nullable: false
+          field :invoice_type, -> { Candid::Invoices::V2::Types::InvoiceDestination }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/invoice_item_attribution_create.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        # Points to the claim or service line that this invoice is attributed to
+        class InvoiceItemAttributionCreate < Internal::Types::Model
+          extend Candid::Internal::Types::Union
+
+          discriminant :type
+
+          member -> { String }, key: "SERVICE_LINE_ID"
+          member -> { String }, key: "CLAIM_ID"
+          member -> { Object }, key: "UNATTRIBUTED"
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/invoice_item_create.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        class InvoiceItemCreate < Internal::Types::Model
+          field :attribution, lambda {
+            Candid::Invoices::V2::Types::InvoiceItemAttributionCreate
+          }, optional: false, nullable: false
+          field :amount_cents, -> { Integer }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/invoice_item_info.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        class InvoiceItemInfo < Internal::Types::Model
+          field :claim_invoice_items, lambda {
+            Internal::Types::Hash[String, Candid::Invoices::V2::Types::ClaimInvoiceItemInfo]
+          }, optional: false, nullable: false
+          field :unattributed_items, lambda {
+            Internal::Types::Array[Candid::Invoices::V2::Types::UnattributedInvoiceItem]
+          }, optional: false, nullable: false
+        end
+      end
+    end
+  end
+end

data/lib/candid/invoices/v_2/types/invoice_sort_field.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Candid
+  module Invoices
+    module V2
+      module Types
+        module InvoiceSortField
+          extend Candid::Internal::Types::Enum
+
+          CREATED_AT = "CREATED_AT"
+          UPDATED_AT = "UPDATED_AT"
+          PATIENT_EXTERNAL_ID = "PATIENT_EXTERNAL_ID"
+          NOTE = "NOTE"
+          DUE_DATE = "DUE_DATE"
+          STATUS = "STATUS"
+        end
+      end
+    end
+  end
+end