multiwoven-integrations 0.39.3 → 0.40.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 722fb600da2ce3d9e52217a69c531d8991746dc4fef92cb22ac436a5f54b1ad8
-  data.tar.gz: 3ed0109dda31689e8807ac1601b5008fd52c93f06b5f15ba135ca3fc4b6cfbca
+  metadata.gz: d02ac40ce23d00833bf9387f1363d3f871c0abdfb500c235e3d44a37110c9d8f
+  data.tar.gz: e76e2c81bf09fc64962b2639addb8d11ff7d9ad37a38c88b1267e0778d77bd95
 SHA512:
-  metadata.gz: 5ddaaa66f7ca6ac717f5dc1cb4cb4ef7e329dd96e9a57a10424d4edf39a09e5963620a00cfdbf07f58ded7ad366d73d914fd6370661ce96555dd623ade3f94d9
-  data.tar.gz: 85a0969e935fa72f385a2d215cb4aa6c835157f4460d4e561a3d0d8ac1ddebd579d5c8d31ba081f2ab5de1fab7ae6f2a5184c044789ba8a847c6d60981315ae4
+  metadata.gz: 2bf4882833f8c7e2f823b0077b3a4402d78f5c6acbdee0dc068063dd0be1310b0005c3f73305f26389e4bbf34d17ed6011aa6251852dfc0b17a7956a2928bba2
+  data.tar.gz: d460e9bd2b1e2b26fff0c1dd33148952c5f8f1d241cb208bc4da5c4cefbdd9e33b16e6e90ecc449c8e1ddd047b2a40c718dcb51f20aa0b7a9e4d61e21f301229

data/lib/multiwoven/integrations/core/oauth_client_credentials.rb

@@ -1,26 +1,42 @@
 # frozen_string_literal: true
 
+require "jwt"
+require "openssl"
+require "securerandom"
+
 module Multiwoven
   module Integrations::Core
-    # Shared OAuth2 client_credentials flow. Include in a connector client to:
+    # Shared OAuth2 client_credentials flows. Include in a connector client to:
     #   * inject `Authorization: Bearer <token>` when connection_config[:auth_type]
-    #     is `oauth_client_credentials`
+    #     is `oauth_client_credentials` or `oauth_private_key_jwt`
     #   * cache the token in the connector's `configuration` JSON and refresh it
     #     shortly before expiry
     #
+    # `oauth_client_credentials` — classic client_id + client_secret.
+    # `oauth_private_key_jwt` — client_assertion JWT signed with an RSA private
+    #   key (Epic Backend Services / SMART confidential asymmetric).
+    #
     # The including class is expected to set `@connector_instance` (an object
     # responding to `configuration` and `update!`) before making requests that
     # should benefit from the cache. Without it, a fresh token is fetched every
     # call — safe but wasteful.
     module OauthClientCredentials
       AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS = "oauth_client_credentials"
+      AUTH_TYPE_PRIVATE_KEY_JWT = "oauth_private_key_jwt"
+      OAUTH_AUTH_TYPES = [AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS, AUTH_TYPE_PRIVATE_KEY_JWT].freeze
+
+      CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+      # Epic / SMART Backend Services require RS384; RS256 is kept for other IdPs.
+      DEFAULT_JWT_ALGORITHM = "RS384"
+      ALLOWED_JWT_ALGORITHMS = %w[RS384 RS256].freeze
+      JWT_ASSERTION_LIFETIME_SECONDS = 300
       # Refresh access tokens this many seconds before their advertised expiry,
       # so a token that expires mid-request doesn't leave the connector.
       TOKEN_EXPIRY_BUFFER_SECONDS = 300
 
       def build_headers(connection_config)
         headers = (connection_config[:headers] || {}).to_h.dup
-        return headers unless connection_config[:auth_type] == AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS
+        return headers unless oauth_auth_type?(connection_config[:auth_type])
 
         headers["Authorization"] = "Bearer #{ensure_oauth_token(connection_config)}"
         headers
@@ -35,6 +51,10 @@ module Multiwoven
 
       private
 
+      def oauth_auth_type?(auth_type)
+        OAUTH_AUTH_TYPES.include?(auth_type)
+      end
+
       def cached_oauth_token
         config = connector_configuration
         return nil unless config
@@ -50,12 +70,12 @@ module Multiwoven
       end
 
       def fetch_and_cache_oauth_token(connection_config)
-        token_url = connection_config[:token_url]
-        client_id = connection_config[:client_id]
-        client_secret = connection_config[:client_secret]
-        raise ArgumentError, "OAuth token_url, client_id, and client_secret are required when auth_type is #{AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS}" if token_url.to_s.empty? || client_id.to_s.empty? || client_secret.to_s.empty?
-
-        response = post_token_request(token_url, client_id, client_secret, connection_config[:scope])
+        response = case connection_config[:auth_type]
+                   when AUTH_TYPE_PRIVATE_KEY_JWT
+                     post_private_key_jwt_token_request(connection_config)
+                   else
+                     post_client_secret_token_request(connection_config)
+                   end
         raise "OAuth token request failed: #{response.code} #{response.body}" unless response.is_a?(Net::HTTPSuccess)
 
         body = JSON.parse(response.body)
@@ -67,17 +87,126 @@ module Multiwoven
         access_token
       end
 
-      def post_token_request(token_url, client_id, client_secret, scope)
-        uri = URI(token_url)
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = (uri.scheme == "https")
+      def post_client_secret_token_request(connection_config)
+        token_url = connection_config[:token_url]
+        client_id = connection_config[:client_id]
+        client_secret = connection_config[:client_secret]
+        if token_url.to_s.empty? || client_id.to_s.empty? || client_secret.to_s.empty?
+          raise ArgumentError,
+                "OAuth token_url, client_id, and client_secret are required when auth_type is " \
+                "#{AUTH_TYPE_OAUTH_CLIENT_CREDENTIALS}"
+        end
 
         form = {
           "grant_type" => "client_credentials",
           "client_id" => client_id,
           "client_secret" => client_secret
         }
-        form["scope"] = scope unless scope.to_s.empty?
+        form["scope"] = connection_config[:scope] unless connection_config[:scope].to_s.empty?
+        post_form(token_url, form)
+      end
+
+      def post_private_key_jwt_token_request(connection_config)
+        token_url = connection_config[:token_url]
+        client_id = connection_config[:client_id]
+        private_key = connection_config[:private_key]
+        kid = connection_config[:kid]
+        if token_url.to_s.empty? || client_id.to_s.empty? || private_key.to_s.empty? || kid.to_s.empty?
+          raise ArgumentError,
+                "OAuth token_url, client_id, private_key, and kid are required when auth_type is " \
+                "#{AUTH_TYPE_PRIVATE_KEY_JWT}"
+        end
+
+        assertion = build_client_assertion(connection_config)
+        form = {
+          "grant_type" => "client_credentials",
+          "client_id" => client_id,
+          "client_assertion_type" => CLIENT_ASSERTION_TYPE,
+          "client_assertion" => assertion
+        }
+        form["scope"] = connection_config[:scope] unless connection_config[:scope].to_s.empty?
+        post_form(token_url, form)
+      end
+
+      def build_client_assertion(connection_config)
+        token_url = connection_config[:token_url].to_s
+        client_id = connection_config[:client_id].to_s
+        audience = connection_config[:audience].to_s
+        audience = token_url if audience.empty?
+        algorithm = resolve_jwt_algorithm(connection_config[:algorithm])
+        kid = connection_config[:kid].to_s
+
+        now = Time.now.to_i
+        payload = {
+          "iss" => client_id,
+          "sub" => client_id,
+          "aud" => audience,
+          "jti" => SecureRandom.uuid,
+          "iat" => now,
+          "nbf" => now,
+          "exp" => now + JWT_ASSERTION_LIFETIME_SECONDS
+        }
+        headers = { "typ" => "JWT", "kid" => kid }
+
+        key = load_private_key(connection_config[:private_key])
+        JWT.encode(payload, key, algorithm, headers)
+      end
+
+      def resolve_jwt_algorithm(algorithm)
+        algorithm = algorithm.to_s
+        algorithm = DEFAULT_JWT_ALGORITHM if algorithm.empty?
+        return algorithm if ALLOWED_JWT_ALGORITHMS.include?(algorithm)
+
+        raise ArgumentError,
+              "Unsupported OAuth JWT algorithm '#{algorithm}'. " \
+              "Allowed: #{ALLOWED_JWT_ALGORITHMS.join(", ")}"
+      end
+
+      def load_private_key(private_key)
+        key = begin
+          OpenSSL::PKey.read(normalize_pem(private_key))
+        rescue OpenSSL::PKey::PKeyError, ArgumentError => e
+          raise ArgumentError, "Invalid OAuth private_key: #{e.message}"
+        end
+
+        raise ArgumentError, "OAuth private_key must be an RSA private key in PEM format" unless key.is_a?(OpenSSL::PKey::RSA) && key.private?
+
+        key
+      end
+
+      # JSON/UI fields often store PEMs with escaped newlines ("\n") or as a single
+      # line with spaces. OpenSSL::PKey.read rejects both; normalize before parsing.
+      def normalize_pem(private_key)
+        pem = private_key.to_s.strip
+        pem = pem.gsub('\r\n', "\n").gsub('\n', "\n").gsub('\r', "\n")
+
+        return pem if pem.include?("\n")
+
+        labels = [
+          "RSA PRIVATE KEY",
+          "PRIVATE KEY"
+        ]
+
+        labels.each do |label|
+          begin_marker = "-----BEGIN #{label}-----"
+          end_marker = "-----END #{label}-----"
+
+          next unless pem.start_with?(begin_marker) && pem.end_with?(end_marker)
+
+          body = pem.delete_prefix(begin_marker)
+                    .delete_suffix(end_marker)
+                    .delete(" ")
+
+          return "#{begin_marker}\n#{body.scan(/.{1,64}/).join("\n")}\n#{end_marker}\n"
+        end
+
+        pem
+      end
+
+      def post_form(token_url, form)
+        uri = URI(token_url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
 
         request = Net::HTTP::Post.new(uri)
         request["Content-Type"] = "application/x-www-form-urlencoded"

data/lib/multiwoven/integrations/destination/http/config/spec.json

@@ -15,8 +15,8 @@
       "auth_type": {
         "type": "string",
         "title": "Authentication Type",
-        "description": "Select 'oauth_client_credentials' to have Multiwoven fetch and refresh an OAuth2 access token automatically.",
-        "enum": ["none", "oauth_client_credentials"],
+        "description": "Select an OAuth2 option to have Multiwoven fetch and refresh an access token automatically. Use 'oauth_private_key_jwt' for Epic Backend Services / SMART confidential asymmetric clients.",
+        "enum": ["none", "oauth_client_credentials", "oauth_private_key_jwt"],
         "default": "none",
         "order": 2
       },
@@ -65,6 +65,58 @@
               }
             },
             "required": ["token_url", "client_id", "client_secret"]
+          },
+          {
+            "properties": {
+              "auth_type": { "enum": ["oauth_private_key_jwt"] },
+              "token_url": {
+                "type": "string",
+                "title": "OAuth Token URL",
+                "description": "E.g. https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token",
+                "order": 3
+              },
+              "client_id": {
+                "type": "string",
+                "multiwoven_secret": true,
+                "title": "OAuth Client ID",
+                "description": "Non-production or production Client ID from Epic app registration.",
+                "order": 4
+              },
+              "private_key": {
+                "type": "string",
+                "multiwoven_secret": true,
+                "title": "RSA Private Key (PEM)",
+                "description": "PEM-encoded RSA private key used to sign the client_assertion JWT. The matching public key must be published at your registered JWK Set URL.",
+                "order": 5
+              },
+              "kid": {
+                "type": "string",
+                "title": "Key ID (kid)",
+                "description": "Must match the kid of the public key in your JWK Set.",
+                "order": 6
+              },
+              "algorithm": {
+                "type": "string",
+                "title": "JWT Signing Algorithm",
+                "description": "Epic Backend Services require RS384.",
+                "enum": ["RS384", "RS256"],
+                "default": "RS384",
+                "order": 7
+              },
+              "audience": {
+                "type": "string",
+                "title": "JWT Audience (aud)",
+                "description": "Optional. Defaults to the Token URL. Epic expects the token endpoint URL.",
+                "order": 8
+              },
+              "scope": {
+                "type": "string",
+                "title": "OAuth Scope",
+                "description": "Optional. E.g. system/Patient.read system/Observation.read",
+                "order": 9
+              }
+            },
+            "required": ["token_url", "client_id", "private_key", "kid"]
           }
         ]
       }

data/lib/multiwoven/integrations/rollout.rb

@@ -2,7 +2,7 @@
 
 module Multiwoven
   module Integrations
-    VERSION = "0.39.3"
+    VERSION = "0.40.1"
 
     ENABLED_SOURCES = %w[
       Snowflake
@@ -37,6 +37,7 @@ module Multiwoven
       Aisquared
       OneDrive
       MicrosoftDynamics
+      EpicFhir
     ].freeze
 
     ENABLED_DESTINATIONS = %w[

data/lib/multiwoven/integrations/source/epic_fhir/client.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+module Multiwoven::Integrations::Source
+  module EpicFhir
+    include Multiwoven::Integrations::Core
+
+    FHIR_ACCEPT = "application/fhir+json"
+    NDJSON_ACCEPT = "application/fhir+ndjson"
+    DEFAULT_EXPORT_POLL_INTERVAL = 5
+    DEFAULT_EXPORT_TIMEOUT = 120
+    CONCURRENT_EXPORT_MESSAGE = "Another request for this same Client and Group is in progress."
+    REQUIRED_CONFIG_KEYS = %w[fhir_base_url token_url client_id private_key kid export_group_id].freeze
+    DEFAULT_RESOURCES = %w[
+      AllergyIntolerance
+      Appointment
+      CarePlan
+      CareTeam
+      Condition
+      Consent
+      Device
+      DiagnosticReport
+      DocumentReference
+      Encounter
+      EpisodeOfCare
+      Goal
+      Immunization
+      List
+      MedicationRequest
+      Observation
+      Patient
+      Procedure
+      ServiceRequest
+    ].freeze
+
+    class Client < SourceConnector
+      include Multiwoven::Integrations::Core::OauthClientCredentials
+
+      def check_connection(connection_config)
+        connection_config = prepare_config(connection_config)
+        validate_config!(connection_config)
+        build_headers(connection_config)
+        success_status
+      rescue StandardError => e
+        handle_exception(e, {
+                           context: "EPIC_FHIR:CHECK_CONNECTION:EXCEPTION",
+                           type: "error"
+                         })
+        failure_status(e)
+      end
+
+      def discover(connection_config)
+        connection_config = prepare_config(connection_config)
+        validate_config!(connection_config)
+        streams = discover_resource_types(connection_config).map { |resource_type| create_stream(resource_type) }
+
+        Catalog.new(streams: streams).to_multiwoven_message
+      rescue StandardError => e
+        handle_exception(e, {
+                           context: "EPIC_FHIR:DISCOVER:EXCEPTION",
+                           type: "error"
+                         })
+      end
+
+      def read(sync_config)
+        connection_config = prepare_config(sync_config&.source&.connection_specification)
+        validate_config!(connection_config)
+        @connector_instance = sync_config&.source&.connector_instance
+
+        sql_query = sync_config.model.query
+        sql_query = batched_query(sql_query, sync_config.limit, sync_config.offset) if
+          sync_config.limit.present? || sync_config.offset.present?
+        query(connection_config, sql_query)
+      rescue StandardError => e
+        handle_exception(e, {
+                           context: "EPIC_FHIR:READ:EXCEPTION",
+                           type: "error",
+                           sync_id: sync_config.sync_id,
+                           sync_run_id: sync_config.sync_run_id
+                         })
+      end
+
+      private
+
+      def prepare_config(config)
+        config = config.to_unsafe_h if config.respond_to?(:to_unsafe_h)
+        config = {} unless config.is_a?(Hash)
+        config.with_indifferent_access.tap do |conf|
+          conf[:auth_type] = AUTH_TYPE_PRIVATE_KEY_JWT
+          conf[:fhir_base_url] = conf[:fhir_base_url].to_s.sub(%r{/+\z}, "")
+        end
+      end
+
+      def validate_config!(config)
+        missing = REQUIRED_CONFIG_KEYS.reject { |key| config[key].to_s.strip.present? }
+        raise ArgumentError, "Missing required Epic FHIR configuration: #{missing.join(", ")}" if missing.any?
+
+        validate_export_timeout!(config)
+      end
+
+      def validate_export_timeout!(config)
+        raw = config[:export_timeout]
+        return if raw.to_s.strip.empty?
+
+        value = raw.to_f
+        raise ArgumentError, "Export timeout must be greater than 0" unless value.positive?
+        return if value <= DEFAULT_EXPORT_TIMEOUT
+
+        raise ArgumentError,
+              "Export timeout must be equal to or less than #{DEFAULT_EXPORT_TIMEOUT}"
+      end
+
+      # Model preview passes this value back into #query.
+      def create_connection(connection_config)
+        prepare_config(connection_config)
+      end
+
+      def query(connection_config, sql_query)
+        connection_config = prepare_config(connection_config)
+        validate_config!(connection_config)
+        resource_type, limit, offset = parse_sql_query(sql_query)
+
+        bulk_export_resources(connection_config, resource_type, limit: limit, offset: offset).map do |resource|
+          RecordMessage.new(data: displayable_resource(resource), emitted_at: Time.now.to_i).to_multiwoven_message
+        end
+      end
+
+      def displayable_resource(resource)
+        resource.to_h.transform_values do |value|
+          value.is_a?(Hash) || value.is_a?(Array) ? JSON.generate(value) : value
+        end
+      end
+
+      def discover_resource_types(connection_config)
+        configured = configured_resources(connection_config)
+        configured.any? ? configured : DEFAULT_RESOURCES
+      end
+
+      def configured_resources(connection_config)
+        raw = connection_config[:resources]
+        values = raw.is_a?(Array) ? raw : raw.to_s.split(",")
+        values.map(&:to_s).map(&:strip).reject(&:empty?).select { |value| valid_resource_type?(value) }
+      end
+
+      def create_stream(resource_type)
+        Multiwoven::Integrations::Protocol::Stream.new(
+          name: resource_type,
+          action: StreamAction["fetch"],
+          json_schema: base_resource_schema,
+          supported_sync_modes: %w[full_refresh],
+          source_defined_primary_key: [["id"]]
+        )
+      end
+
+      # Shared across resource types: FHIR Resource / DomainResource keys are
+      # always present (nested values become JSON strings in #displayable_resource).
+      # Type-specific fields (e.g. Patient.name) also appear at read time, so the
+      # schema allows additional string properties instead of pretending the
+      # catalog only has id + resourceType.
+      def base_resource_schema
+        schema = convert_to_json_schema(
+          %w[
+            id
+            resourceType
+            meta
+            implicitRules
+            language
+            text
+            contained
+            extension
+            modifierExtension
+          ].map { |column_name| { column_name: column_name, type: "string" } }
+        )
+        schema["additionalProperties"] = true
+        schema
+      end
+
+      # The manifest and records are cached for batched LIMIT/OFFSET reads during this client run.
+      def bulk_export_resources(connection_config, resource_type, limit:, offset:)
+        return [] if limit&.zero?
+
+        @bulk_manifests ||= {}
+        @bulk_records ||= {}
+
+        key = [
+          connection_config[:fhir_base_url],
+          connection_config[:export_group_id],
+          resource_type
+        ]
+
+        manifest = @bulk_manifests[key] ||= run_bulk_export(connection_config, resource_type)
+
+        records = @bulk_records[key] ||= bulk_output_urls(manifest, resource_type).flat_map do |url|
+          download_ndjson(connection_config, url)
+        end
+
+        apply_limit_offset(records, limit: limit, offset: offset)
+      end
+
+      def apply_limit_offset(records, limit:, offset:)
+        start = offset.to_i
+        return records.drop(start) if limit.nil?
+
+        records[start, limit] || []
+      end
+
+      def run_bulk_export(connection_config, resource_type)
+        deadline = Time.now + export_timeout(connection_config)
+        status_url = kickoff_bulk_export(connection_config, resource_type, deadline: deadline)
+        poll_bulk_export(connection_config, status_url, deadline: deadline)
+      end
+
+      def kickoff_bulk_export(connection_config, resource_type, deadline:)
+        url = bulk_export_url(connection_config, resource_type)
+
+        loop do
+          response = fhir_get(connection_config, url, extra_headers: { "Prefer" => "respond-async" })
+          if response.code.to_s == "202"
+            status_url = response["content-location"].presence
+            raise StandardError, "Epic FHIR 202 #{url} missing Content-Location header" if status_url.nil?
+
+            return status_url
+          end
+
+          raise fhir_api_error(response, url) unless concurrent_export?(response)
+          raise concurrent_export_timeout_error unless wait_for_retry?(connection_config, response, deadline)
+        end
+      end
+
+      def poll_bulk_export(connection_config, status_url, deadline:)
+        loop do
+          response = fhir_get(connection_config, status_url)
+          code = response.code.to_s
+          return JSON.parse(response.body) if code == "200"
+          raise fhir_api_error(response, status_url) unless code == "202"
+
+          unless wait_for_retry?(connection_config, response, deadline)
+            raise StandardError,
+                  "Epic FHIR 202 #{status_url} still in progress after #{export_timeout(connection_config)}s"
+          end
+        end
+      end
+
+      # Waits between attempts without ever waiting past the shared export
+      # deadline: sleeping longer and then retrying would issue a request the
+      # caller has already given up on, and Epic counts it as one more
+      # concurrent export for this client and group.
+      def wait_for_retry?(connection_config, response, deadline)
+        remaining = deadline - Time.now
+        return false unless remaining.positive?
+
+        delay = retry_after(response) || export_poll_interval(connection_config)
+        return false if delay > remaining
+
+        sleep(delay)
+        true
+      end
+
+      def concurrent_export?(response)
+        response.body.to_s.downcase.include?(CONCURRENT_EXPORT_MESSAGE.downcase)
+      end
+
+      def concurrent_export_timeout_error
+        StandardError.new(
+          "Epic is still preparing another bulk export for this Client and Group. " \
+          "Retry after the existing export completes."
+        )
+      end
+
+      def download_bulk_output(connection_config, manifest, resource_type, limit:, offset:)
+        return [] if limit&.zero?
+
+        records = []
+        pending_offset = offset.to_i
+
+        bulk_output_urls(manifest, resource_type).each do |url|
+          resources = download_ndjson(connection_config, url)
+          skipped = [pending_offset, resources.size].min
+          pending_offset -= skipped
+          records.concat(resources.drop(skipped))
+          break if limit_reached?(records, limit)
+        end
+
+        limit_reached?(records, limit) ? records.first(limit) : records
+      end
+
+      def bulk_output_urls(manifest, resource_type)
+        Array(manifest["output"]).filter_map do |entry|
+          entry["url"].presence if entry.is_a?(Hash) && entry["type"].to_s == resource_type
+        end
+      end
+
+      def download_ndjson(connection_config, url)
+        response = fhir_get(connection_config, url, accept: NDJSON_ACCEPT)
+        raise fhir_api_error(response, url) unless success?(response)
+
+        parse_ndjson(response.body)
+      end
+
+      def parse_ndjson(body)
+        body.to_s.each_line.with_index(1).filter_map do |line, line_number|
+          line = line.strip
+          next if line.empty?
+
+          JSON.parse(line)
+        rescue JSON::ParserError => e
+          raise StandardError, "Error parsing NDJSON: #{e.message} at line #{line_number}: #{line}"
+        end
+      end
+
+      # Epic serves Bulk Data only from Group level; there is no system-level $export.
+      def bulk_export_url(connection_config, resource_type)
+        group_id = connection_config[:export_group_id].to_s.strip
+        base = "#{connection_config[:fhir_base_url]}/Group/#{group_id}/$export"
+        params = { "_type" => resource_type }
+        since = connection_config[:export_since].to_s.strip
+        params["_since"] = since if since.present?
+        "#{base}?#{URI.encode_www_form(params)}"
+      end
+
+      def retry_after(response)
+        value = response["retry-after"].to_s.strip
+        delay = value.to_i if value.match?(/\A\d+\z/)
+        delay if delay&.positive?
+      end
+
+      def export_poll_interval(connection_config)
+        interval = numeric_setting(connection_config[:export_poll_interval], DEFAULT_EXPORT_POLL_INTERVAL)
+        interval.finite? && interval.positive? ? interval : DEFAULT_EXPORT_POLL_INTERVAL
+      end
+
+      def export_timeout(connection_config)
+        numeric_setting(connection_config[:export_timeout], DEFAULT_EXPORT_TIMEOUT)
+      end
+
+      def numeric_setting(raw, default)
+        return default if raw.to_s.strip.empty?
+
+        value = raw.to_f
+        value.negative? ? default : value
+      end
+
+      def limit_reached?(records, limit)
+        !limit.nil? && records.size >= limit
+      end
+
+      def parse_sql_query(sql_query)
+        query = sql_query.to_s.strip.chomp(";")
+        resource_type = query[/FROM\s+([^\s;]+)/i, 1]
+        raise ArgumentError, "Could not extract FHIR resource type from query" if resource_type.blank?
+        raise ArgumentError, "Invalid FHIR resource type: #{resource_type}" unless valid_resource_type?(resource_type)
+
+        limit = query[/LIMIT\s+(\d+)/i, 1]&.to_i
+        offset = query[/OFFSET\s+(\d+)/i, 1]&.to_i
+        [resource_type, limit, offset]
+      end
+
+      def valid_resource_type?(resource_type)
+        resource_type.match?(/\A[A-Z][A-Za-z0-9]*\z/)
+      end
+
+      def fhir_get(connection_config, url, extra_headers: {}, accept: FHIR_ACCEPT)
+        Multiwoven::Integrations::Core::HttpClient.request(
+          url,
+          HTTP_GET,
+          headers: fhir_headers(connection_config, accept: accept).merge(extra_headers),
+          options: { config: connection_config[:config] || {} }
+        )
+      end
+
+      def fhir_headers(connection_config, accept: FHIR_ACCEPT)
+        headers = build_headers(connection_config).transform_keys(&:to_s)
+        headers["Accept"] = accept
+        headers
+      end
+
+      def fhir_api_error(response, url = nil)
+        body = response.respond_to?(:body) ? response.body.to_s : response.to_s
+        code = response.respond_to?(:code) ? response.code.to_s : "unknown"
+        StandardError.new(["Epic FHIR", code, url, body].map(&:to_s).reject(&:empty?).join(" "))
+      end
+    end
+  end
+end

data/lib/multiwoven/integrations/source/epic_fhir/config/meta.json

@@ -0,0 +1,16 @@
+{
+  "data": {
+    "name": "EpicFhir",
+    "title": "Epic FHIR",
+    "connector_type": "source",
+    "category": "Data Warehouse",
+    "sub_category": "Relational Database",
+    "documentation_url": "https://docs.squared.ai/guides/sources/data-sources/epic_fhir",
+    "github_issue_label": "source-epic-fhir",
+    "icon": "icon.svg",
+    "license": "MIT",
+    "release_stage": "alpha",
+    "support_level": "community",
+    "tags": ["language:ruby", "multiwoven", "fhir", "epic"]
+  }
+}

data/lib/multiwoven/integrations/source/epic_fhir/config/spec.json

@@ -0,0 +1,112 @@
+{
+  "documentation_url": "https://docs.squared.ai/guides/sources/data-sources/epic_fhir",
+  "stream_type": "dynamic",
+  "connector_query_type": "raw_sql",
+  "connection_specification": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "Epic FHIR",
+    "type": "object",
+    "required": ["fhir_base_url", "token_url", "client_id", "private_key", "kid", "export_group_id"],
+    "properties": {
+      "fhir_base_url": {
+        "type": "string",
+        "title": "FHIR Base URL",
+        "description": "Your Epic FHIR R4 base URL.",
+        "order": 0
+      },
+      "token_url": {
+        "type": "string",
+        "title": "OAuth Token URL",
+        "description": "Your Epic OAuth token endpoint.",
+        "order": 1
+      },
+      "client_id": {
+        "type": "string",
+        "multiwoven_secret": true,
+        "title": "OAuth Client ID",
+        "description": "The Client ID from your Epic app.",
+        "order": 2
+      },
+      "private_key": {
+        "type": "string",
+        "multiwoven_secret": true,
+        "title": "RSA Private Key",
+        "description": "The RSA private key for your Epic app.",
+        "order": 3
+      },
+      "kid": {
+        "type": "string",
+        "title": "Key ID (kid)",
+        "description": "The Key ID for your Epic app's public key.",
+        "order": 4
+      },
+      "algorithm": {
+        "type": "string",
+        "title": "JWT Signing Algorithm",
+        "description": "The signing algorithm used for OAuth authentication.",
+        "enum": ["RS384"],
+        "default": "RS384",
+        "order": 5
+      },
+      "audience": {
+        "type": "string",
+        "title": "JWT Audience (aud)",
+        "description": "Optional. Defaults to your OAuth Token URL.",
+        "order": 6
+      },
+      "scope": {
+        "type": "string",
+        "title": "OAuth Scope",
+        "description": "Optional. The OAuth scopes requested from Epic.",
+        "default": "system/*.read",
+        "order": 7
+      },
+      "resources": {
+        "type": "string",
+        "title": "Resources",
+        "description": "Optional. Comma-separated FHIR resources to export, such as Patient, Observation, or Condition.",
+        "order": 8
+      },
+      "export_group_id": {
+        "type": "string",
+        "title": "Bulk Export Group ID",
+        "description": "The Epic Group ID used for Bulk Data exports.",
+        "order": 9
+      },
+      "export_since": {
+        "type": "string",
+        "title": "Export Since",
+        "description": "Optional. Only export resources changed after this date and time.",
+        "order": 10
+      },
+      "export_poll_interval": {
+        "type": "string",
+        "title": "Export Poll Interval (seconds)",
+        "description": "How often to check the export status.",
+        "default": "5",
+        "order": 11
+      },
+      "export_timeout": {
+        "type": "string",
+        "title": "Export Timeout (seconds)",
+        "description": "Maximum time to wait for an export to complete. Must be greater than 0 and at most 120.",
+        "default": "120",
+        "order": 12
+      },
+      "config": {
+        "title": "",
+        "type": "object",
+        "properties": {
+          "timeout": {
+            "type": "string",
+            "default": "30",
+            "title": "HTTP Timeout",
+            "description": "Maximum time to wait for an API response.",
+            "order": 0
+          }
+        },
+        "order": 13
+      }
+    }
+  }
+}

data/lib/multiwoven/integrations/source/epic_fhir/icon.svg

@@ -0,0 +1,5 @@
+<svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect width="128" height="128" rx="24" fill="#0B3D5C"/>
+  <path d="M64 28C44.118 28 28 44.118 28 64C28 83.882 44.118 100 64 100C83.882 100 100 83.882 100 64C100 44.118 83.882 28 64 28ZM64 90C49.641 90 38 78.359 38 64C38 49.641 49.641 38 64 38C78.359 38 90 49.641 90 64C90 78.359 78.359 90 64 90Z" fill="#7FD3F0"/>
+  <path d="M58 48H70V58H80V70H70V80H58V70H48V58H58V48Z" fill="#FFFFFF"/>
+</svg>

data/lib/multiwoven/integrations/source/http/config/spec.json

@@ -36,8 +36,8 @@
       "auth_type": {
         "type": "string",
         "title": "Authentication Type",
-        "description": "Select 'oauth_client_credentials' to have Multiwoven fetch and refresh an OAuth2 access token automatically.",
-        "enum": ["none", "oauth_client_credentials"],
+        "description": "Select an OAuth2 option to have Multiwoven fetch and refresh an access token automatically. Use 'oauth_private_key_jwt' for Epic Backend Services / SMART confidential asymmetric clients.",
+        "enum": ["none", "oauth_client_credentials", "oauth_private_key_jwt"],
         "default": "none",
         "order": 14
       },
@@ -158,6 +158,58 @@
               }
             },
             "required": ["token_url", "client_id", "client_secret"]
+          },
+          {
+            "properties": {
+              "auth_type": { "enum": ["oauth_private_key_jwt"] },
+              "token_url": {
+                "type": "string",
+                "title": "OAuth Token URL",
+                "description": "E.g. https://fhir.epic.com/interconnect-fhir-oauth/oauth2/token",
+                "order": 15
+              },
+              "client_id": {
+                "type": "string",
+                "multiwoven_secret": true,
+                "title": "OAuth Client ID",
+                "description": "Non-production or production Client ID from Epic app registration.",
+                "order": 16
+              },
+              "private_key": {
+                "type": "string",
+                "multiwoven_secret": true,
+                "title": "RSA Private Key (PEM)",
+                "description": "PEM-encoded RSA private key used to sign the client_assertion JWT. The matching public key must be published at your registered JWK Set URL.",
+                "order": 17
+              },
+              "kid": {
+                "type": "string",
+                "title": "Key ID (kid)",
+                "description": "Must match the kid of the public key in your JWK Set.",
+                "order": 18
+              },
+              "algorithm": {
+                "type": "string",
+                "title": "JWT Signing Algorithm",
+                "description": "Epic Backend Services require RS384.",
+                "enum": ["RS384", "RS256"],
+                "default": "RS384",
+                "order": 19
+              },
+              "audience": {
+                "type": "string",
+                "title": "JWT Audience (aud)",
+                "description": "Optional. Defaults to the Token URL. Epic expects the token endpoint URL.",
+                "order": 20
+              },
+              "scope": {
+                "type": "string",
+                "title": "OAuth Scope",
+                "description": "Optional. E.g. system/Patient.read system/Observation.read",
+                "order": 21
+              }
+            },
+            "required": ["token_url", "client_id", "private_key", "kid"]
           }
         ]
       }

data/lib/multiwoven/integrations.rb

@@ -103,6 +103,7 @@ require_relative "integrations/source/http/client"
 require_relative "integrations/source/aisquared/client"
 require_relative "integrations/source/one_drive/client"
 require_relative "integrations/source/microsoft_dynamics/client"
+require_relative "integrations/source/epic_fhir/client"
 
 # Destination
 require_relative "integrations/destination/klaviyo/client"

data/multiwoven-integrations.gemspec

@@ -51,6 +51,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "grpc"
   spec.add_runtime_dependency "hubspot-api-client"
   spec.add_runtime_dependency "iterable-api-client"
+  spec.add_runtime_dependency "jwt"
   spec.add_runtime_dependency "MailchimpMarketing"
   spec.add_runtime_dependency "net-sftp"
   spec.add_runtime_dependency "pg"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: multiwoven-integrations
 version: !ruby/object:Gem::Version
-  version: 0.39.3
+  version: 0.40.1
 platform: ruby
 authors:
 - Subin T P
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-14 00:00:00.000000000 Z
+date: 2026-08-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -262,6 +262,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: MailchimpMarketing
   requirement: !ruby/object:Gem::Requirement
@@ -764,6 +778,10 @@ files:
 - lib/multiwoven/integrations/source/databrics_model/config/meta.json
 - lib/multiwoven/integrations/source/databrics_model/config/spec.json
 - lib/multiwoven/integrations/source/databrics_model/icon.svg
+- lib/multiwoven/integrations/source/epic_fhir/client.rb
+- lib/multiwoven/integrations/source/epic_fhir/config/meta.json
+- lib/multiwoven/integrations/source/epic_fhir/config/spec.json
+- lib/multiwoven/integrations/source/epic_fhir/icon.svg
 - lib/multiwoven/integrations/source/firecrawl/client.rb
 - lib/multiwoven/integrations/source/firecrawl/config/catalog.json
 - lib/multiwoven/integrations/source/firecrawl/config/meta.json