mirah-ruby 0.1.0

data/lib/mirah/collection.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Mirah
+  # Collections represent a pageable view into a given collection. They automatically let you iterate through
+  # record sets in a stable manner.
+  #
+  # @example Iterate through a collection of multiple pages
+  #   while(collection.next_page?)
+  #     collection = collection.next_page
+  #     collection.records.each do |record|
+  #       # process record
+  #     end
+  #   end
+  class Collection
+    def initialize(results:, page_info:, client:, query:)
+      @results = results
+      @page_info = page_info
+      @client = client
+      @query = query
+    end
+
+    # The Mirah client, used for sending additional paged requests.
+    attr_reader :client
+
+    # The current results of the query
+    attr_reader :results
+
+    # The information on the current page as returned by the server
+    attr_reader :page_info
+
+    # The current set of paging parameters
+    attr_reader :paging
+
+    # The original query, stored to allow us to retrigger a query with a new page.
+    attr_reader :query
+
+    def length
+      results&.length
+    end
+
+    def next_page?
+      page_info.next_page?
+    end
+
+    def prev_page?
+      page_info.prev_page?
+    end
+
+    def refresh_with_new_paging(paging)
+      # Update everything as before, but set the new paging.
+      client.query_connection(
+        query[:query],
+        query[:input],
+        paging,
+        query[:data_klass],
+        query[:path]
+      )
+    end
+
+    def next_page
+      raise Errors::InvalidPage, 'This collection does not have a next page' unless next_page?
+
+      return @next_page if @next_page
+
+      @next_page = refresh_with_new_paging(next_page_params)
+    end
+
+    def prev_page
+      raise Errors::InvalidPage, 'This collection does not have a previous page' unless prev_page?
+
+      return @prev_page if @prev_page
+
+      @prev_page = refresh_with_new_paging(prev_page_params)
+    end
+
+    private
+
+    def next_page_params
+      last = query[:paging]
+      Filters::Paging.new(
+        after: page_info.end_cursor,
+        before: nil,
+        first: last.first || last.last,
+        last: nil
+      )
+    end
+
+    def prev_page_params
+      last = query[:paging]
+      Filters::Paging.new(
+        before: page_info.start_cursor,
+        after: nil,
+        last: last.last || last.first,
+        first: nil
+      )
+    end
+  end
+end

data/lib/mirah/data/appointment.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Mirah
+  module Data
+    # Appointments represent a planned or past meeting between a patient and a practitioner. This is based
+    # on https://www.hl7.org/fhir/appointment.html
+    # As part of the integration flow, Mirah will work out whether this appointments needs an accompanying measurement
+    # encounter and automatically create one as appropriate. Mirah's ETL will generally make a best effort to estimate
+    # where and what context the measurement should be taken. The more information (Episode of Care, Organization,
+    # etc) that you supply, the more likely it is to be correct.
+    # Note that as part of this processing, Mirah may immediately choose to create assessments and trigger
+    # communications with the patient or other participants, for example by text message or email.
+    # In order to keep adherence statistics up to date, Mirah also requires that updates on past
+    # appointments are sent, so that we can calculate whether e.g. the appointment was a no-show.
+    class Appointment < BaseObject
+      # @!attribute [r] id
+      #   @return [string] The internal Mirah identifier
+      attribute :id
+
+      # @!attribute [r] external_id
+      #   @return [string] The identifier provided by your system
+      attribute :external_id
+
+      # @!attribute [r] start_date
+      #   @return [Date] The appointment start date
+      attribute :start_date, serializer: Serializers::DateTimeSerializer
+
+      # @!attribute [r] end_date
+      #   @return [Date] The appointment end date
+      attribute :end_date, serializer: Serializers::DateTimeSerializer
+
+      # @!attribute [r] minutes_duration
+      #   @return [Integer] The legnth of this appointment in minutes
+      attribute :minutes_duration
+
+      # @!attribute [r] status
+      #   @return [string] The appointment status
+      attribute :status
+
+      # @!attribute [r] patient_id
+      #   @return [string] The internal mirah id of the patient
+      attribute :patient_id, path: %w[patient], target: 'id'
+
+      # @!attribute [r] external_patient_id
+      #   @return [string] Your system identifier for the patient
+      attribute :external_patient_id, path: %w[patient], target: 'externalId'
+
+      # @!attribute [r] practitioner_id
+      #   @return [string] The internal mirah id of the practitioner this appointment is with
+      attribute :practitioner_id, path: %w[practitioner], target: 'id'
+
+      # @!attribute [r] external_practitioner_id
+      #   @return [string] Your system identifier for the practitioner this appointment is with
+      attribute :external_practitioner_id, path: %w[practitioner], target: 'externalId'
+
+      # @!attribute [r] organization_id
+      #   @return [string] The internal mirah id of the organization this appointment is with
+      attribute :organization_id, path: %w[organization], target: 'id'
+
+      # @!attribute [r] external_organization_id
+      #   @return [string] Your system identifier for the organization this appointment is with
+      attribute :external_organization_id, path: %w[organization], target: 'externalId'
+    end
+  end
+end

data/lib/mirah/data/organization.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mirah
+  module Data
+    # Organizations in the Mirah system currently represent a hierarchy of units/facilities
+    # requiring either different treatment configurations (e.g. inpatient facilities require different
+    # measurement protocols to outpatient) or useful for the purpose of analytics. It is roughly based on
+    # https://www.hl7.org/fhir/organization.html
+    class Organization < BaseObject
+      # @!attribute [r] id
+      #   @return [string] The internal Mirah identifier
+      attribute :id
+
+      # @!attribute [r] external_id
+      #   @return [string] The identifier provided by your system
+      attribute :external_id
+
+      # @!attribute [r] name
+      #   @return [string] The organization's name
+      attribute :name
+
+      # @!attribute [r] part_of_id
+      #   @return [string] The internal mirah id of the organization this organization is a child of
+      attribute :part_of_id, path: %w[partOf], target: 'id'
+
+      # @!attribute [r] external_part_of_id
+      #   @return [string] Your system identifier for the organization this organization is a child of
+      attribute :external_part_of_id, path: %w[partOf], target: 'externalId'
+    end
+  end
+end

data/lib/mirah/data/page_info.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Mirah
+  module Data
+    # PageInfo gives information on the current state of paging as returned by the server. This includes information
+    # about the start and the end cursors of the result set, and whether or not there are additiona pages.
+    # This can be used in combination with {Mirah::Filters::Paging} to make a stable cursor-based pagination call.
+    class PageInfo < BaseObject
+      # @!attribute [r] end_cursor
+      #   @return [string] The cursor of the last record of the current set.
+      #    This can be used as a starting point for the next page of the query.
+      attribute :end_cursor
+
+      # @!attribute [r] start_cursor
+      #   @return [string] The cursor of the first record of the current set.
+      #    This can be used to get the previous page.
+      attribute :start_cursor
+
+      # @!attribute [r] has_next_page
+      #   @return [Boolean] Whether the data set has a next page
+      attribute :has_next_page
+
+      # @!attribute [r] has_previous_page
+      #   @return [Boolean] Whether the data set has a next page
+      attribute :has_previous_page
+
+      # @see has_next_page
+      # @return [Boolean]
+      def next_page?
+        has_next_page
+      end
+
+      # @see has_previous_page
+      # @return [Boolean]
+      def prev_page?
+        has_previous_page
+      end
+    end
+  end
+end

data/lib/mirah/data/patient.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Mirah
+  module Data
+    # Patients represent people who are in treatment. They can have appointments, and be the target of assessments.
+    # Patients are only treated in the context of an episode of care.
+    class Patient < BaseObject
+      # @!attribute [r] id
+      #   @return [string] The internal Mirah identifier
+      attribute :id
+
+      # @!attribute [r] external_id
+      #   @return [string] The identifier provided by your system
+      attribute :external_id
+
+      # @!attribute [r] given_name
+      #   @return [string] The patient's first or given name
+      attribute :given_name
+
+      # @!attribute [r] family_name
+      #   @return [string] The patient's last or family name
+      attribute :family_name
+
+      # @!attribute [r] birth_date
+      #   @return [Date] The patient's date of birth.
+      attribute :birth_date, serializer: Serializers::DateSerializer
+
+      # @!attribute [r] gender
+      #   @return [string] The patient's gender
+      attribute :gender
+
+      # @!attribute [r] primary_language
+      #   @return [string] The patient's primary language
+      attribute :primary_language
+
+      # @!attribute [r] email
+      #   @return [string] The patient's primary email address
+      attribute :email
+
+      # @!attribute [r] phone_number
+      #   @return [string] The patient's primary phone number that is suitable for receiving text messages.
+      #    Please do not use a phone number which corresponds to a landline as text messages will not be received.
+      attribute :phone_number
+    end
+  end
+end

data/lib/mirah/data/practitioner.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Mirah
+  module Data
+    # FHIR Practitioners represent people directly involved in the provision of care.
+    # See https://www.hl7.org/fhir/practitioner.html for more details.
+    class Practitioner < BaseObject
+      # @!attribute [r] id
+      #   @return [string] The internal Mirah identifier
+      attribute :id
+
+      # @!attribute [r] external_id
+      #   @return [string] The identifier provided by your system
+      attribute :external_id
+
+      # @!attribute [r] given_name
+      #   @return [string] The practitioner's first or given name
+      attribute :given_name
+
+      # @!attribute [r] family_name
+      #   @return [string] The practitioner's last or family name
+      attribute :family_name
+
+      # @!attribute [r] title
+      #   @return [string] The practitioner's title, e.g. 'Dr'
+      attribute :title
+
+      # @!attribute [r] suffix
+      #   @return [string] The practitioner's suffix, e.g. 'MD'
+      attribute :suffix
+
+      # @!attribute [r] email
+      #   @return [string] The practitioner's primary email address
+      attribute :email
+
+      # @!attribute [r] default_practitioner_role
+      #   @return [string] The clinical role for this practitioner
+      attribute :default_practitioner_role
+
+      # @!attribute [r] sso_username
+      #   @return [string] The username (nameid) used for single sign on by this practitioner.
+      attribute :sso_username
+
+      # @!attribute [r] organization_ids
+      #   @return [Array<string>] The internal mirah organization ids this practitioner has a role in
+      attribute :organization_ids, path: %w[organization], target: 'id'
+
+      # @!attribute [r] external_organization_ids
+      #   @return [Array<string>] The identifiers from your system of the organizations this practitioner has a role in
+      attribute :external_organization_ids, path: %w[organizations], target: 'externalId'
+    end
+  end
+end

data/lib/mirah/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Mirah
+  # A top level error from the Mirah system. It is implemented in multiple places with a
+  class Error < StandardError; end
+
+  module Errors
+    # This exception is thrown when the credentials you have specified for the service are invalid.
+    class InvalidCredentials < Error; end
+
+    # This exception is thrown when an unknown error occurs on the server side.
+    class ServerError < Error; end
+
+    # This exception is thrown when an error happens in this process rather than on the server side.
+    class ClientError < Error; end
+
+    # A parameter you supplied as an input was not valid for the query.
+    # An error class that shows the record was invalid
+    class InvalidParameter < Error
+      def initialize(param)
+        @param = param
+      end
+
+      attr_reader :param
+    end
+
+    # A required parameter was not passed in
+    class MissingParameter < Error
+      def initialize(param)
+        @param = param
+      end
+
+      attr_reader :param
+    end
+
+    # You attempted to fetch a page that was not valid - you probably called `next_page` on the end of the collection.
+    class InvalidPage < Error; end
+  end
+end

data/lib/mirah/filters.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Mirah
+  # These filters represent ways of querying data. Each endpoint has a set of filters that you can apply.
+  module Filters
+  end
+end

data/lib/mirah/filters/appointment_filters.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mirah
+  module Filters
+    # Input parameters and filters for queries returning {Data::Appointment} objects.
+    class AppointmentFilters < BaseObject
+      # @!attribute [r] external_id
+      #   @return [Array<string>] An array of external identifiers to match.
+      attribute :external_id
+
+      # @!attribute [r] status
+      #   @return [string] The appointment status
+      attribute :status
+    end
+  end
+end

data/lib/mirah/filters/organization_filters.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Mirah
+  module Filters
+    # Input parameters and filters for queries returning {Data::Organization} objects.
+    class OrganizationFilters < BaseObject
+      # @!attribute [r] external_id
+      #   @return [Array<string>] An array of external identifiers to match.
+      attribute :external_id
+
+      # @!attribute [r] search
+      #   @return [string] Smart search by name and other fields where appropriate
+      attribute :search
+    end
+  end
+end

data/lib/mirah/filters/paging.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mirah
+  module Filters
+    # A set of input parameters designed to let you select how many and which records you want from a pagination cursor.
+    # It is based on Graphql's Relay specification.
+    # This can be used with {Data::PageInfo}, which will be provided by the results of a server query, to provide
+    # stable pagination framework.
+    class Paging < BaseObject
+      # @!attribute [r] first
+      #   @return [string] Return the first N rows from either the start, or the current cursor position.
+      #    Cannot be used at the same time as #last
+      attribute :first
+
+      # @!attribute [r] last
+      #   @return [string] Return the last N rows from either the end, or the current cursor position.
+      #    Cannot be used at the same time as #first
+      attribute :last
+
+      # @!attribute [r] before
+      #   @return [string] Return rows before the given cursor position
+      attribute :before
+
+      # @!attribute [r] after
+      #   @return [string] Return rows after the given cursor position
+      attribute :after
+
+      def self.default
+        new(first: 100)
+      end
+    end
+  end
+end