pug-sh 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 893420d16827c4d7472d599fde6fc5278e354cc559ffcd217b5ff34151c0d5c5
-  data.tar.gz: d9f76d529e9e0fda1fc678a6096cc9922076e84e0a7c53515e5c6ec98eee4eed
+  metadata.gz: e3fa18ab593cd55c417d83dc152eb219e7f7d3d5d6053a84abf426ace5028fde
+  data.tar.gz: 9cb0fc72b31991999476f98d1a49a65f707910b7f09020f405ef8fe1e7b81ca6
 SHA512:
-  metadata.gz: 9194a40e3a2eb238d5dce9f1db3803ca4fd103a0ae366ef27d8dfd266f93fff923fba12afbbce82796af440175a0563bc39495b4e12e007fe32bb7fbb3fb3540
-  data.tar.gz: 4db8dc628a8f10582f53eae2242bd6e35c8e1511669cf643e81b1c095615353fcbbc58ca362e058cbbe72bd81eb4f35b886d34cb88c0c8209688f4764b6a7d7f
+  metadata.gz: 8076f0a24d015d3c1f40cc233cb77e880f913a5bebf0afa2bccbe7ad52acaaee57932c3e89cc85db2f79d146f2c35f0e5e1acf3285e35cb57a5c2e6b5cf8ceef
+  data.tar.gz: a89f4b45abb12e384855e49a142474dcf1c16a0b410fb5b96b6f0fc4a24c30b99388c6b4ac38221113753f641cd1c3392f3b30241871065e6276ae8b5e394412

data/README.md

@@ -4,7 +4,7 @@
 
 # pug-sh
 
-Pug server-side SDK for Ruby — event tracking, profile identify, and analytics reads.
+Pug server-side SDK for Ruby: event tracking, profile identify, and analytics reads.
 
 It is instance-based and authenticates with a **private** project API key (`prv_…`). Ingestion
 never raises, so a tracking call can't take down your request path.
@@ -25,13 +25,13 @@ require "pug"
 
 pug = Pug::Client.new(api_key: ENV.fetch("PUG_API_KEY"))
 
-# Track an event. distinct_id (who the event is for) comes first — a server has no ambient user.
+# Track an event. distinct_id (who the event is for) comes first, as a server has no ambient user.
 pug.track("user_42", "order.completed", amount: 49.0, currency: "USD")
 
 # Well-known events get their properties type-checked and validated against the event's schema.
 pug.track("user_42", "feature_used", feature_id: "export")
 
-# Identify a profile (never raises — failures are logged).
+# Identify a profile (never raises; failures are logged).
 pug.identify("user_42", email: "ada@example.com", plan: "pro")
 
 # Reads raise Pug::Error.
@@ -56,9 +56,9 @@ pug.close
   `max_wait` after the failure, but no sooner than a second; a permanent one (a fixed set of
   client-error Connect codes, plus any non-transport error) dead-letters them via `on_error`.
   `close` drains and reports anything still undelivered through `on_error` and the log.
-  `on_error` covers buffered `track` events only — `identify` failures are logged, and so are
+  `on_error` covers buffered `track` events only: `identify` failures are logged, and so are
   events the server drops from a batch it accepts (`BatchCreateResponse.dropped`), at WARN.
-- **Reads are request/response and do raise** `Pug::Error` — they run in your control flow, so
+- **Reads are request/response and do raise** `Pug::Error`: they run in your control flow, so
   you own retry. They are not auto-retried.
 - **Well-known events** have typed, validated properties; any other `kind` is accepted as a
   custom event with loose properties.
@@ -72,7 +72,7 @@ pug.close
 
 | Option     | Type          | Default                     | Description                                                                                                                       |
 | ---------- | ------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `api_key`  | `String`      | —                           | **Required.** Private project key (`prv_…`).                                                                                      |
+| `api_key`  | `String`      | none                        | **Required.** Private project key (`prv_…`).                                                                                      |
 | `endpoint` | `String`      | hosted endpoint             | Pug server origin.                                                                                                                |
 | `batch`    | `Hash`        | see below                   | Ingestion buffer: `max_size` (100, capped at 1000), `max_wait` (5 seconds), `max_queue_size` (10,000).                            |
 | `on_error` | callable      | none                        | Dead-letter hook for undeliverable buffered `track` events, called with `(error, events)`.                                        |
@@ -100,13 +100,13 @@ they behave as anywhere else, blocking the thread that called `track`.
 
 ### Ingestion (never raises)
 
-- `pug.track(distinct_id, kind, properties = nil, options = nil)` — enqueue an event. Non-blocking.
-- `pug.identify(external_id, traits = nil, options = nil)` — create or update a profile. Blocks
+- `pug.track(distinct_id, kind, properties = nil, options = nil)`: enqueue an event. Non-blocking.
+- `pug.identify(external_id, traits = nil, options = nil)`: create or update a profile. Blocks
   until the server answers.
-- `pug.flush(timeout: nil)` — send the currently buffered events now and wait for that attempt.
+- `pug.flush(timeout: nil)`: send the currently buffered events now and wait for that attempt.
   Returns `false` if `timeout` (seconds) passed first. `true` means the attempt finished, not that
   every event was delivered: a transient failure keeps them queued for a retry.
-- `pug.close(timeout: nil)` — drain and shut down; call on graceful exit so nothing buffered is lost.
+- `pug.close(timeout: nil)`: drain and shut down; call on graceful exit so nothing buffered is lost.
   Returns `false` if `timeout` passed first. Either way, by the time it returns every event it
   couldn't send has gone to `on_error` and the log, including a batch still being sent when the
   timeout ran out, which may yet arrive.
@@ -125,7 +125,7 @@ pug.track("user_42", "signup", { plan: "pro", location: "landing" }, location: {
 ```
 
 `track` options: `timestamp` (a `Time`; defaults to now), `session_id` (a UUID overriding the
-client's per-instance session), `location` (the visitor's location — see below).
+client's per-instance session), `location` (the visitor's location; see below).
 `identify` options, which work the same way with traits: `anonymous_id` (must start with `anon-`;
 triggers anon→identified merge), `device_id`. Traits must be JSON-serializable, with nested values
 mapped as for properties below; they travel as a protobuf `Struct`, whose numbers are doubles, so
@@ -150,14 +150,21 @@ becomes an ISO 8601 string and a `BigDecimal` or `Rational` a number, while a va
 form for, such as a `Set`, drops the whole property with a warning. Strings are capped at 1024
 bytes (truncated with a warning), and invalid UTF-8 is repaired.
 
+Keys in snake_case are sent in camelCase, so `order_total:` arrives as `orderTotal`, the spelling
+well-known event fields use and JavaScript code usually writes. Any other key, camelCase or not, is
+sent as written, as are the keys inside a nested `Hash`. Pug's Node, Go and Python SDKs send every
+key as written, so `order_total` from them stays `order_total`. If two keys come out the same, such
+as `order_total` and `orderTotal`, the last one is sent and the other is dropped with a warning, as
+with `Hash#merge`. Trait keys work the same way.
+
 ### Well-known events
 
 For a well-known kind such as `purchase`, properties are checked against the event's schema.
 Keys may be the field's name (`product_id`) or its JSON name (`productId`); either way the
-property is sent under the JSON name, like every other Pug SDK. A field's type comes from the
-schema rather than the Ruby value, so `amount: 10` is sent as a double. A value of the wrong type,
-or one failing the schema's rules, drops the event with an error; other keys ride along as custom
-properties.
+property is sent under the JSON name, like every other Pug SDK, but giving both drops the event
+with an error. A field's type comes from the schema rather than the Ruby value, so `amount: 10` is
+sent as a double. A value of the wrong type, or one failing the schema's rules, drops the event
+with an error; other keys ride along as custom properties.
 
 ```ruby
 pug.track("user_42", "purchase", product_id: "p1", amount: 49, currency: "USD", coupon: "FALL")
@@ -169,36 +176,37 @@ Duration fields take seconds as a number, `{ seconds:, nanos: }`, or a `Google::
 ### Location
 
 Pug only derives geo from CDN headers on browser (public-key) requests. This SDK uses a private
-key, so the server adds no geo of its own — without `location`, an event has no geo at all:
+key, so the server adds no geo of its own. Without `location`, an event has no geo at all:
 
 ```ruby
 pug.track("user_42", "checkout_completed", { plan: "pro" }, location: { country: "DE", city: "Berlin" })
 ```
 
 Fields: `continent`, `country`, `region`, `city`, `postal_code`, `metro_code`, `timezone`,
-`latitude`, `longitude` — strings, except the two coordinates. `country` must be an ISO 3166-1
+`latitude`, `longitude`: strings, except the two coordinates. `country` must be an ISO 3166-1
 alpha-2 code (case and surrounding spaces are normalized); `latitude` and `longitude` are only
 sent as a pair.
 
-A field that is missing, nil or empty is omitted silently. One that looks like a mistake —
-unknown key, wrong type, unknown country, coordinate out of range — is dropped with a warning and
+A field that is missing, nil or empty is omitted silently. One that looks like a mistake
+(unknown key, wrong type, unknown country, coordinate out of range) is dropped with a warning and
 the rest is still sent. If nothing is usable the event goes out with no geo.
 
 ### Reads (raise `Pug::Error`)
 
 These run in your control flow:
 
-- `pug.profiles` — `get(id, include_bots: false)`, `get_by_external_id(external_id, include_bots: false)`,
+- `pug.profiles`: `get(id, include_bots: false)`, `get_by_external_id(external_id, include_bots: false)`,
   `delete(id)`, `list(request = nil, timeout: nil)` (auto-paginating: yields each profile to a
   block, or returns an `Enumerator`). The timeout bounds the whole stream, the time your block
   takes included, so `timeout:` (seconds) can give one long `list` more than the client's.
-- `pug.activity` — `feed`, `event_explorer`, `heatmap`, `profile_sessions`, `profile_stats`,
+- `pug.activity`: `feed`, `event_explorer`, `heatmap`, `profile_sessions`, `profile_stats`,
   `filter_schema`, `property_values`.
-- `pug.insights` — `query`, `segment_users`, `filter_schema`, `property_values`.
+- `pug.insights`: `query`, `segment_users`, `filter_schema`, `property_values`.
 
 Requests are a Hash or the generated request message, and responses are the generated messages,
 under `Pug::Proto` (`Pug::Proto::Shared::Insights::V1::QueryResponse`, …); call `to_h` on one
-for plain Ruby data.
+for plain Ruby data. Property names are the ones stored, so a property tracked as `order_total:`
+is filtered on, and comes back, as `orderTotal`.
 
 ```ruby
 sessions = pug.activity.profile_sessions(distinct_id: "user_42", page_size: 50)

data/lib/pug/client.rb

@@ -239,10 +239,25 @@ module Pug
     # Struct can't carry, such as NaN. A Struct's numbers are doubles, so an integer past 2^53
     # would arrive changed.
     def to_struct(traits)
-      ready = EventBuilder.json_ready(traits, max_integer: EventBuilder::MAX_SAFE_FLOAT)
+      ready = EventBuilder.json_ready(camel_case_keys(traits), max_integer: EventBuilder::MAX_SAFE_FLOAT)
       ::Google::Protobuf::Struct.from_hash(JSON.parse(JSON.generate(ready)))
     rescue StandardError => e
       raise NotSerializable, e.message
     end
+
+    # Only the top level, as for properties: a nested Hash is as likely data keyed by ids.
+    def camel_case_keys(traits)
+      given = {}
+      traits.each_with_object({}) do |(key, value), out|
+        name = key.to_s
+        name = EventBuilder.camel_case(name.encoding.ascii_compatible? ? name : name.encode(Encoding::UTF_8))
+        if given.key?(name)
+          @log.warn("identify() traits #{given[name].inspect} and #{key.inspect} both go out as #{name.inspect}; " \
+                    "sending the last")
+        end
+        given[name] = key
+        out[name] = value
+      end
+    end
   end
 end

data/lib/pug/event_builder.rb

@@ -30,6 +30,8 @@ module Pug
     # Past 2^53 a Float may already have been rounded, so it can't stand for an exact integer.
     MAX_SAFE_FLOAT = 2**53
 
+    SNAKE_CASE = /\A[a-z][a-z0-9]*(?:_[a-z0-9]+)+\z/
+
     INTEGER_RANGES = {
       int32: (-(2**31))..((2**31) - 1),
       sint32: (-(2**31))..((2**31) - 1),
@@ -66,15 +68,15 @@ module Pug
     Timestamp = ::Google::Protobuf::Timestamp
 
     SchemaField = Struct.new(:descriptor, :name, :json_name, :type)
-    Schema = Struct.new(:klass, :name, :by_key, :fields)
+    Schema = Struct.new(:klass, :name, :by_json_name, :fields)
 
-    # Field lookups for every well-known schema, by proto name and JSON name, worked out once.
+    # Field lookups for every well-known schema, by JSON name, worked out once.
     SCHEMAS = WellKnown::CATALOG.transform_values do |klass|
       fields = klass.descriptor.map do |field|
         SchemaField.new(field, field.name, field.json_name, field.type).freeze
       end
-      by_key = fields.flat_map { |field| [[field.name, field], [field.json_name, field]] }.to_h
-      Schema.new(klass, klass.descriptor.name, by_key.freeze, fields.freeze).freeze
+      by_json_name = fields.to_h { |field| [field.json_name, field] }
+      Schema.new(klass, klass.descriptor.name, by_json_name.freeze, fields.freeze).freeze
     end.freeze
 
     class FieldError < StandardError
@@ -127,6 +129,13 @@ module Pug
       end
     end
 
+    # Protobuf's JSON-name rule, so order_total lands on a well-known field's JSON name. Only
+    # lowercase snake_case is renamed, since the full rule would turn ORDER_ID into ORDERID; the
+    # ascii_only? check keeps match? from raising on a UTF-16 or broken key.
+    def self.camel_case(key)
+      key.ascii_only? && key.match?(SNAKE_CASE) ? key.gsub(/_[a-z0-9]/) { |pair| pair[1].upcase } : key
+    end
+
     def initialize(log)
       @log = log
     end
@@ -213,8 +222,8 @@ module Pug
     end
 
     # Typed fields render by their proto type rather than their Ruby value, so a whole-number
-    # double stays a double. Keys may be the field's proto name or its JSON name; unknown keys
-    # ride along as custom properties.
+    # double stays a double. A key names a field once camel-cased, so the proto name works as well
+    # as the JSON name; unknown keys ride along as custom properties.
     def well_known_properties(schema, kind, properties)
       message, extras = typed_message(schema, properties)
       violations = Validator.validate(message)
@@ -234,9 +243,9 @@ module Pug
       extras = {}
       properties.each do |key, value|
         name = utf8(key.to_s)
-        field = schema.by_key[name]
+        field = schema.by_json_name[self.class.camel_case(name)]
         if field.nil?
-          extras[name] = value
+          extras[key] = value
         elsif given.key?(field)
           raise FieldError.new(field.name, "given twice, as #{given[field].first} and #{name}")
         else
@@ -373,9 +382,18 @@ module Pug
     end
 
     def custom_properties(properties, kind)
+      given = {}
       properties.each_with_object({}) do |(key, value), out|
+        name = self.class.camel_case(utf8(key.to_s))
         mapped = custom_value(value)
-        out[utf8(key.to_s)] = mapped if mapped
+        next unless mapped
+
+        if given.key?(name)
+          @log.warn("Properties #{given[name].inspect} and #{key.inspect} on event \"#{kind}\" both go out as " \
+                    "#{name.inspect}; sending the last")
+        end
+        given[name] = key
+        out[name] = mapped
       rescue NotRepresentable => e
         @log.warn("Property \"#{key}\" on event \"#{kind}\" not representable (#{e.message}), skipping")
       end

data/lib/pug/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pug
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pug-sh
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - pug.sh