oursprivacy-ingest 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8cdcde9b61ee37a6cd1eb19ecb8e4444a9d8a910678ff4c8134ed064dd391b17
-  data.tar.gz: 3edc160e7d78d29da1ac5140356e4e94db135dc18be4afd7dd268c80e2b24dec
+  metadata.gz: d23eb81e41813ee04947b2d1a04f410bf7b8198b2d958ae79042ca379162e62c
+  data.tar.gz: e8a0964d9d45ad11a6a2cc5dd44be08af26382036c5c95e6d6790aacd75f4817
 SHA512:
-  metadata.gz: 9640276478ee03a778fb897b401840d005418ac4bf7dd3dd1cc44ab2a6dc7deb27e2157f386c04ba38cd0389242f0e95f96807749c22fd425a91c5303b3bbe97
-  data.tar.gz: 8fdf075be4fc764fbe36ff172251aa8a7c96fcb0fa39f840e46bdddc29e6776ed89f5ec138f7ed46d02facf9c35b2cdc93dea0e4386761ed5d7c20578a9e1fcc
+  metadata.gz: 2e933d84b08922ee6f9885e9fadb991b4d237a97ed77be3b2672d1e6e59564b1f15e5f9a761cb572fddb1af0c4ccc393137f9b51eccfe371dc1fe6b0661ab75c
+  data.tar.gz: c9575d16b3128719b6aac612889144486685e7894835970a813ccd2258090668507e5e8e50d48dcdfb6bd648d421d6d1b8e2da4bcbeb856bcb9a470bc356f482

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.6.0 (2026-05-07)
+
+Full Changelog: [v1.5.0...v1.6.0](https://github.com/with-ours/ingest-sdk-ruby/compare/v1.5.0...v1.6.0)
+
+### Features
+
+* **api:** api update ([c54431d](https://github.com/with-ours/ingest-sdk-ruby/commit/c54431d5d205b735a570afa625a3b8e4bdd8c67d))
+
+## 1.5.0 (2026-05-06)
+
+Full Changelog: [v1.4.0...v1.5.0](https://github.com/with-ours/ingest-sdk-ruby/compare/v1.4.0...v1.5.0)
+
+### Features
+
+* **api:** api update ([70e698d](https://github.com/with-ours/ingest-sdk-ruby/commit/70e698d9524677ef21e236253598ef7d52babbe7))
+
 ## 1.4.0 (2026-05-06)
 
 Full Changelog: [v1.3.0...v1.4.0](https://github.com/with-ours/ingest-sdk-ruby/compare/v1.3.0...v1.4.0)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "oursprivacy-ingest", "~> 1.4.0"
+gem "oursprivacy-ingest", "~> 1.6.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/oursprivacy_ingest/models/batch_create_params.rb

@@ -28,6 +28,15 @@ module OursprivacyIngest
       #   @param request_options [OursprivacyIngest::RequestOptions, Hash{Symbol=>Object}]
 
       class Event < OursprivacyIngest::Internal::Type::BaseModel
+        # @!attribute distinct_id
+        #   A unique identifier for this event used for deduplication. Highly recommended —
+        #   if omitted, Ours will generate one for you, but supplying your own gives you
+        #   stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
+        #   internal order ID).
+        #
+        #   @return [String]
+        required :distinct_id, String, api_name: :distinctId
+
         # @!attribute event
         #   The name of the event you're tracking. This must be whitelisted in the Ours
         #   dashboard.
@@ -35,12 +44,6 @@ module OursprivacyIngest
         #   @return [String]
         required :event, String
 
-        # @!attribute token
-        #   The token for your Source. You can find this in the dashboard.
-        #
-        #   @return [String, nil]
-        optional :token, String
-
         # @!attribute default_properties
         #   These properties are used throughout the Ours app to pass known values onto
         #   destinations
@@ -51,16 +54,10 @@ module OursprivacyIngest
                  api_name: :defaultProperties,
                  nil?: true
 
-        # @!attribute distinct_id
-        #   A unique identifier for the event. This helps prevent duplicate events.
-        #
-        #   @return [String, nil]
-        optional :distinct_id, String, api_name: :distinctId, nil?: true
-
         # @!attribute email
-        #   The email address of a user. We will associate this event with the user or
-        #   create a user. Used for lookup if externalId and userId are not included in the
-        #   request.
+        #   The email address of a user. Used as a fallback lookup when neither userId nor
+        #   externalId is provided. We search your account for a visitor with this email and
+        #   attach the event to them. If no match is found, a new visitor is created.
         #
         #   @return [String, nil]
         optional :email, String, nil?: true
@@ -75,9 +72,11 @@ module OursprivacyIngest
                  nil?: true
 
         # @!attribute external_id
-        #   The externalId (the ID in your system) of a user. We will associate this event
-        #   with the user or create a user. If included in the request, email lookup is
-        #   ignored.
+        #   Your system's unique identifier for this user. We search your account for an
+        #   existing visitor with this externalId and attach the event to them (resolving to
+        #   their Ours Visitor ID). If no match is found, a new visitor is created. When
+        #   present, email lookup is skipped. If you also have the userId from cookies or
+        #   local storage, send both — it removes the lookup round-trip.
         #
         #   @return [String, nil]
         optional :external_id, String, api_name: :externalId, nil?: true
@@ -101,9 +100,10 @@ module OursprivacyIngest
         optional :time, Float, nil?: true
 
         # @!attribute user_id
-        #   The Ours user id stored in local storage and cookies on your web properties. If
-        #   userId is included in the request, we do not lookup the user by email or
-        #   externalId.
+        #   The Ours Visitor ID stored in local storage and cookies on your web properties.
+        #   When present, this is used directly — no lookup by externalId or email is
+        #   performed. If you have both a userId and an externalId, send both so the event
+        #   is attached to the right visitor without any lookup overhead.
         #
         #   @return [String, nil]
         optional :user_id, String, api_name: :userId, nil?: true
@@ -118,29 +118,27 @@ module OursprivacyIngest
                  api_name: :userProperties,
                  nil?: true
 
-        # @!method initialize(event:, token: nil, default_properties: nil, distinct_id: nil, email: nil, event_properties: nil, external_id: nil, identity_context: nil, time: nil, user_id: nil, user_properties: nil)
+        # @!method initialize(distinct_id:, event:, default_properties: nil, email: nil, event_properties: nil, external_id: nil, identity_context: nil, time: nil, user_id: nil, user_properties: nil)
         #   Some parameter documentations has been truncated, see
         #   {OursprivacyIngest::Models::BatchCreateParams::Event} for more details.
         #
-        #   @param event [String] The name of the event you're tracking. This must be whitelisted in the Ours dash
+        #   @param distinct_id [String] A unique identifier for this event used for deduplication. Highly recommended —
         #
-        #   @param token [String] The token for your Source. You can find this in the dashboard.
+        #   @param event [String] The name of the event you're tracking. This must be whitelisted in the Ours dash
         #
         #   @param default_properties [OursprivacyIngest::Models::BatchCreateParams::Event::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
         #
-        #   @param distinct_id [String, nil] A unique identifier for the event. This helps prevent duplicate events.
-        #
-        #   @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+        #   @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
         #
         #   @param event_properties [Hash{Symbol=>String, nil}, nil] Any additional event properties you want to pass along.
         #
-        #   @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+        #   @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
         #
         #   @param identity_context [OursprivacyIngest::Models::BatchCreateParams::Event::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
         #
         #   @param time [Float, nil] The time at which the event occurred in milliseconds since UTC epoch. The time m
         #
-        #   @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+        #   @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
         #
         #   @param user_properties [OursprivacyIngest::Models::BatchCreateParams::Event::UserProperties, nil] Properties to set on the visitor. (optional) You can also update these propertie
 

data/lib/oursprivacy_ingest/models/batch_create_response.rb

@@ -11,70 +11,112 @@ module OursprivacyIngest
 
       # @!attribute failed
       #
-      #   @return [Float, OursprivacyIngest::Models::BatchCreateResponse::Failed]
-      required :failed, enum: -> { OursprivacyIngest::Models::BatchCreateResponse::Failed }
+      #   @return [Integer]
+      required :failed, Integer
 
       # @!attribute results
       #
-      #   @return [Array<OursprivacyIngest::Models::BatchCreateResponse::Result>]
+      #   @return [Array<OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember0, OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1>]
       required :results,
-               -> { OursprivacyIngest::Internal::Type::ArrayOf[OursprivacyIngest::Models::BatchCreateResponse::Result] }
+               -> { OursprivacyIngest::Internal::Type::ArrayOf[union: OursprivacyIngest::Models::BatchCreateResponse::Result] }
 
       # @!attribute success
       #
-      #   @return [Boolean, OursprivacyIngest::Models::BatchCreateResponse::Success]
-      required :success, enum: -> { OursprivacyIngest::Models::BatchCreateResponse::Success }
+      #   @return [Boolean]
+      required :success, OursprivacyIngest::Internal::Type::Boolean
 
       # @!method initialize(accepted:, failed:, results:, success:)
       #   @param accepted [Integer]
-      #   @param failed [Float, OursprivacyIngest::Models::BatchCreateResponse::Failed]
-      #   @param results [Array<OursprivacyIngest::Models::BatchCreateResponse::Result>]
-      #   @param success [Boolean, OursprivacyIngest::Models::BatchCreateResponse::Success]
+      #   @param failed [Integer]
+      #   @param results [Array<OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember0, OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1>]
+      #   @param success [Boolean]
 
-      # @see OursprivacyIngest::Models::BatchCreateResponse#failed
-      module Failed
-        extend OursprivacyIngest::Internal::Type::Enum
+      module Result
+        extend OursprivacyIngest::Internal::Type::Union
 
-        FAILED_0 = 0
+        variant -> { OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember0 }
 
-        # @!method self.values
-        #   @return [Array<Float>]
-      end
+        variant -> { OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1 }
 
-      class Result < OursprivacyIngest::Internal::Type::BaseModel
-        # @!attribute index
-        #
-        #   @return [Integer]
-        required :index, Integer
+        class UnionMember0 < OursprivacyIngest::Internal::Type::BaseModel
+          # @!attribute index
+          #
+          #   @return [Integer]
+          required :index, Integer
 
-        # @!attribute success
-        #
-        #   @return [Boolean, OursprivacyIngest::Models::BatchCreateResponse::Result::Success]
-        required :success, enum: -> { OursprivacyIngest::Models::BatchCreateResponse::Result::Success }
+          # @!attribute success
+          #
+          #   @return [Boolean, OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember0::Success]
+          required :success,
+                   enum: -> { OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember0::Success }
 
-        # @!method initialize(index:, success:)
-        #   @param index [Integer]
-        #   @param success [Boolean, OursprivacyIngest::Models::BatchCreateResponse::Result::Success]
+          # @!method initialize(index:, success:)
+          #   @param index [Integer]
+          #   @param success [Boolean, OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember0::Success]
 
-        # @see OursprivacyIngest::Models::BatchCreateResponse::Result#success
-        module Success
-          extend OursprivacyIngest::Internal::Type::Enum
+          # @see OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember0#success
+          module Success
+            extend OursprivacyIngest::Internal::Type::Enum
 
-          TRUE = true
+            TRUE = true
 
-          # @!method self.values
-          #   @return [Array<Boolean>]
+            # @!method self.values
+            #   @return [Array<Boolean>]
+          end
         end
-      end
 
-      # @see OursprivacyIngest::Models::BatchCreateResponse#success
-      module Success
-        extend OursprivacyIngest::Internal::Type::Enum
-
-        TRUE = true
+        class UnionMember1 < OursprivacyIngest::Internal::Type::BaseModel
+          # @!attribute code
+          #
+          #   @return [Symbol, OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1::Code]
+          required :code, enum: -> { OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1::Code }
+
+          # @!attribute index
+          #
+          #   @return [Integer]
+          required :index, Integer
+
+          # @!attribute message
+          #
+          #   @return [String]
+          required :message, String
+
+          # @!attribute success
+          #
+          #   @return [Boolean, OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1::Success]
+          required :success,
+                   enum: -> { OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1::Success }
+
+          # @!method initialize(code:, index:, message:, success:)
+          #   @param code [Symbol, OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1::Code]
+          #   @param index [Integer]
+          #   @param message [String]
+          #   @param success [Boolean, OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1::Success]
+
+          # @see OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1#code
+          module Code
+            extend OursprivacyIngest::Internal::Type::Enum
+
+            INVALID_EVENT = :invalid_event
+            QUEUE_FAILED = :queue_failed
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+
+          # @see OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1#success
+          module Success
+            extend OursprivacyIngest::Internal::Type::Enum
+
+            FALSE = false
+
+            # @!method self.values
+            #   @return [Array<Boolean>]
+          end
+        end
 
-        # @!method self.values
-        #   @return [Array<Boolean>]
+        # @!method self.variants
+        #   @return [Array(OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember0, OursprivacyIngest::Models::BatchCreateResponse::Result::UnionMember1)]
       end
     end
   end

data/lib/oursprivacy_ingest/models/track_event_params.rb

@@ -31,15 +31,18 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute distinct_id
-      #   A unique identifier for the event. This helps prevent duplicate events.
+      #   A unique identifier for this event used for deduplication. Highly recommended —
+      #   if omitted, Ours will generate one for you, but supplying your own gives you
+      #   stronger idempotency guarantees (e.g. a Stripe payment intent ID or your
+      #   internal order ID).
       #
       #   @return [String, nil]
       optional :distinct_id, String, api_name: :distinctId, nil?: true
 
       # @!attribute email
-      #   The email address of a user. We will associate this event with the user or
-      #   create a user. Used for lookup if externalId and userId are not included in the
-      #   request.
+      #   The email address of a user. Used as a fallback lookup when neither userId nor
+      #   externalId is provided. We search your account for a visitor with this email and
+      #   attach the event to them. If no match is found, a new visitor is created.
       #
       #   @return [String, nil]
       optional :email, String, nil?: true
@@ -54,9 +57,11 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute external_id
-      #   The externalId (the ID in your system) of a user. We will associate this event
-      #   with the user or create a user. If included in the request, email lookup is
-      #   ignored.
+      #   Your system's unique identifier for this user. We search your account for an
+      #   existing visitor with this externalId and attach the event to them (resolving to
+      #   their Ours Visitor ID). If no match is found, a new visitor is created. When
+      #   present, email lookup is skipped. If you also have the userId from cookies or
+      #   local storage, send both — it removes the lookup round-trip.
       #
       #   @return [String, nil]
       optional :external_id, String, api_name: :externalId, nil?: true
@@ -80,9 +85,10 @@ module OursprivacyIngest
       optional :time, Float, nil?: true
 
       # @!attribute user_id
-      #   The Ours user id stored in local storage and cookies on your web properties. If
-      #   userId is included in the request, we do not lookup the user by email or
-      #   externalId.
+      #   The Ours Visitor ID stored in local storage and cookies on your web properties.
+      #   When present, this is used directly — no lookup by externalId or email is
+      #   performed. If you have both a userId and an externalId, send both so the event
+      #   is attached to the right visitor without any lookup overhead.
       #
       #   @return [String, nil]
       optional :user_id, String, api_name: :userId, nil?: true
@@ -107,19 +113,19 @@ module OursprivacyIngest
       #
       #   @param default_properties [OursprivacyIngest::Models::TrackEventParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      #   @param distinct_id [String, nil] A unique identifier for the event. This helps prevent duplicate events.
+      #   @param distinct_id [String, nil] A unique identifier for this event used for deduplication. Highly recommended —
       #
-      #   @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+      #   @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
       #
       #   @param event_properties [Hash{Symbol=>String, nil}, nil] Any additional event properties you want to pass along.
       #
-      #   @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+      #   @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
       #
       #   @param identity_context [OursprivacyIngest::Models::TrackEventParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #
       #   @param time [Float, nil] The time at which the event occurred in milliseconds since UTC epoch. The time m
       #
-      #   @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+      #   @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
       #
       #   @param user_properties [OursprivacyIngest::Models::TrackEventParams::UserProperties, nil] Properties to set on the visitor. (optional) You can also update these propertie
       #

data/lib/oursprivacy_ingest/models/visitor_upsert_params.rb

@@ -34,17 +34,19 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute email
-      #   The email address of a user. We will associate this event with the user or
-      #   create a user. Used for lookup if externalId and userId are not included in the
-      #   request.
+      #   The email address of a user. Used as a fallback lookup when neither userId nor
+      #   externalId is provided. We search your account for a visitor with this email and
+      #   attach the event to them. If no match is found, a new visitor is created.
       #
       #   @return [String, nil]
       optional :email, String, nil?: true
 
       # @!attribute external_id
-      #   The externalId (the ID in your system) of a user. We will associate this event
-      #   with the user or create a user. If included in the request, email lookup is
-      #   ignored.
+      #   Your system's unique identifier for this user. We search your account for an
+      #   existing visitor with this externalId and attach the event to them (resolving to
+      #   their Ours Visitor ID). If no match is found, a new visitor is created. When
+      #   present, email lookup is skipped. If you also have the userId from cookies or
+      #   local storage, send both — it removes the lookup round-trip.
       #
       #   @return [String, nil]
       optional :external_id, String, api_name: :externalId, nil?: true
@@ -61,9 +63,10 @@ module OursprivacyIngest
                nil?: true
 
       # @!attribute user_id
-      #   The Ours user id stored in local storage and cookies on your web properties. If
-      #   userId is included in the request, we do not lookup the user by email or
-      #   externalId.
+      #   The Ours Visitor ID stored in local storage and cookies on your web properties.
+      #   When present, this is used directly — no lookup by externalId or email is
+      #   performed. If you have both a userId and an externalId, send both so the event
+      #   is attached to the right visitor without any lookup overhead.
       #
       #   @return [String, nil]
       optional :user_id, String, api_name: :userId, nil?: true
@@ -78,13 +81,13 @@ module OursprivacyIngest
       #
       #   @param default_properties [OursprivacyIngest::Models::VisitorUpsertParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      #   @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+      #   @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
       #
-      #   @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+      #   @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
       #
       #   @param identity_context [OursprivacyIngest::Models::VisitorUpsertParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #
-      #   @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+      #   @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
       #
       #   @param request_options [OursprivacyIngest::RequestOptions, Hash{Symbol=>Object}]
 

data/lib/oursprivacy_ingest/resources/track.rb

@@ -6,10 +6,12 @@ module OursprivacyIngest
       # Some parameter documentations has been truncated, see
       # {OursprivacyIngest::Models::TrackEventParams} for more details.
       #
-      # Track events from your server. Please include at least one of: userId,
-      # externalId, or email. These properties help us associate events with existing
-      # users. For top-level visitor properties: null clears the existing value, while
-      # undefined, omitted fields, and empty strings are ignored. For entries inside
+      # Track events from your server. Include at least one of userId, externalId, or
+      # email so the event can be associated with a visitor. Identity resolution runs in
+      # priority order: userId (direct, no lookup) → externalId (lookup by your ID) →
+      # email (fallback lookup). If you know both userId and externalId, send both. For
+      # top-level visitor properties: null clears the existing value, while undefined,
+      # omitted fields, and empty strings are ignored. For entries inside
       # custom_properties: null, undefined, and empty strings are all ignored
       # (custom_properties use merge semantics). See
       # https://docs.oursprivacy.com/docs/data-types for details and common pitfalls.
@@ -22,19 +24,19 @@ module OursprivacyIngest
       #
       # @param default_properties [OursprivacyIngest::Models::TrackEventParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      # @param distinct_id [String, nil] A unique identifier for the event. This helps prevent duplicate events.
+      # @param distinct_id [String, nil] A unique identifier for this event used for deduplication. Highly recommended —
       #
-      # @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+      # @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
       #
       # @param event_properties [Hash{Symbol=>String, nil}, nil] Any additional event properties you want to pass along.
       #
-      # @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+      # @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
       #
       # @param identity_context [OursprivacyIngest::Models::TrackEventParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #
       # @param time [Float, nil] The time at which the event occurred in milliseconds since UTC epoch. The time m
       #
-      # @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+      # @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
       #
       # @param user_properties [OursprivacyIngest::Models::TrackEventParams::UserProperties, nil] Properties to set on the visitor. (optional) You can also update these propertie
       #

data/lib/oursprivacy_ingest/resources/visitor.rb

@@ -6,12 +6,15 @@ module OursprivacyIngest
       # Some parameter documentations has been truncated, see
       # {OursprivacyIngest::Models::VisitorUpsertParams} for more details.
       #
-      # Define visitor properties on an existing visitor or create a new visitor. This
-      # fires a $identify event, making the call visible in the event stream. For
-      # top-level visitor properties: null clears the existing value, while undefined,
-      # omitted fields, and empty strings are ignored. For entries inside
-      # custom_properties: null, undefined, and empty strings are all ignored
-      # (custom_properties use merge semantics). See
+      # Set or update properties on an existing visitor, or create a new visitor if no
+      # match is found. This fires a $identify event, making the call visible in the
+      # event stream. Identity resolution runs in priority order: userId (direct, no
+      # lookup) → externalId (lookup by your ID) → email (fallback lookup). When a
+      # visitor is found, their Ours Visitor ID is used going forward so all future
+      # events are attached to the same profile. For top-level visitor properties: null
+      # clears the existing value, while undefined, omitted fields, and empty strings
+      # are ignored. For entries inside custom_properties: null, undefined, and empty
+      # strings are all ignored (custom_properties use merge semantics). See
       # https://docs.oursprivacy.com/docs/data-types for details and common pitfalls.
       #
       # @overload upsert(token:, user_properties:, default_properties: nil, email: nil, external_id: nil, identity_context: nil, user_id: nil, request_options: {})
@@ -22,13 +25,13 @@ module OursprivacyIngest
       #
       # @param default_properties [OursprivacyIngest::Models::VisitorUpsertParams::DefaultProperties, nil] These properties are used throughout the Ours app to pass known values onto dest
       #
-      # @param email [String, nil] The email address of a user. We will associate this event with the user or creat
+      # @param email [String, nil] The email address of a user. Used as a fallback lookup when neither userId nor e
       #
-      # @param external_id [String, nil] The externalId (the ID in your system) of a user. We will associate this event w
+      # @param external_id [String, nil] Your system's unique identifier for this user. We search your account for an exi
       #
       # @param identity_context [OursprivacyIngest::Models::VisitorUpsertParams::IdentityContext, nil] End-user network context for server-side calls. Required for probabilistic ident
       #
-      # @param user_id [String, nil] The Ours user id stored in local storage and cookies on your web properties. If
+      # @param user_id [String, nil] The Ours Visitor ID stored in local storage and cookies on your web properties.
       #
       # @param request_options [OursprivacyIngest::RequestOptions, Hash{Symbol=>Object}, nil]
       #

data/lib/oursprivacy_ingest/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OursprivacyIngest
-  VERSION = "1.4.0"
+  VERSION = "1.6.0"
 end