customerio 5.3.0 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d03e20b960d7934a624f045a54d3d367d35822bbe9cd7f3c39374716256e15a5
-  data.tar.gz: fe48ba820bb31d76d86d66dadc3dcf63dc7dc89d88b25c3b836a631a356e4fb9
+  metadata.gz: 901ad05a932585330dd1455f401b1a281b2a3390d2618d0623de62cdd4458988
+  data.tar.gz: 93f962b44d651e177407a68de2ed555fd6fb0a711a3180afda823eee6973b5a7
 SHA512:
-  metadata.gz: be98051f37025cd4cf23693790663e908f6a4718ed195653fe66931c84f072fdb555ccecbe18d0d587a3ad4297fe48d84677c074edbcf1c821849cfda41fe471
-  data.tar.gz: a77fed86492d234f04a062fa2a0acb3c287b9f8d53601ddfcf033f0563069c705b21dc04ae8912ca22023542e198ca1980360e4885a36517b3d049e58d4e6ad7
+  metadata.gz: 9b787fe471290dd64811543d77f24bced641762d894824ffb1d43d671ed0179a6fb536477040bbceb797ca6ccb5f8c6164b085477dfea58db1cac311fd492be3
+  data.tar.gz: e6c251d418be193333c26d07b78f78c61fa61cb3800f5e89dfef9a8c4680a3fcea9a67db09fa793a843172c6daf9ad800a222d6ce2bc0c9c2a2e99e1b633df21

data/README.md

@@ -1,8 +1,7 @@
-<p align="center">
+<p align=center>
   <a href="https://customer.io">
-    <img src="https://files.gitbook.com/v0/b/gitbook-28427.appspot.com/o/assets%2F-LSFjPaMQn1zKdYh6i89%2F-LU6OglGKqQfqMd5Zl-V%2F-LU6OzOLnOvy8VLwfgdg%2FLogo-Color-Horizontal.png?alt=media&token=add29dd0-cabb-4440-b46b-aed21350ae90" height="60">
+    <img src="https://avatars.githubusercontent.com/u/1152079?s=200&v=4" height="60">
   </a>
-  <p align="center">Power automated communication that people like to receive.</p>
 </p>
 
 [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blueviolet?logo=gitpod)](https://gitpod.io/#https://github.com/customerio/customerio-ruby/)
@@ -10,7 +9,9 @@
 
 # Customer.io Ruby
 
-A ruby client for the [Customer.io Track API](https://customer.io/docs/api/#tag/trackOverview).
+A ruby client for the [Customer.io Journeys Track API](https://customer.io/docs/api/track/).
+
+Supported Ruby versions are the actively maintained Ruby lines, starting at Ruby 3.3.
 
 ## Installation
 
@@ -31,7 +32,7 @@ Or install it yourself:
 ### Before we get started: API client vs. JavaScript snippet
 
 It's helpful to know that everything below can also be accomplished
-through the [Customer.io JavaScript snippet](https://customer.io/docs/javascript-quick-start/).
+through the [Customer.io JavaScript client](https://docs.customer.io/integrations/data-in/connections/javascript/js-source/).
 
 In many cases, using the JavaScript snippet will be easier to integrate with
 your app, but there are several reasons why using the API client is useful:
@@ -59,6 +60,28 @@ $customerio = Customerio::Client.new("YOUR SITE ID", "YOUR API SECRET KEY", regi
 
 `region` is optional and takes one of two values—`US` or `EU`. If you do not specify your region, we assume that your account is based in the US (`US`). If your account is based in the EU and you do not provide the correct region (`EU`), we'll route requests to our EU data centers accordingly, however this may cause data to be logged in the US. 
 
+#### Timeouts
+
+Both clients accept a `timeout` option (in seconds) that controls the HTTP connect and read timeouts. The default is 10 seconds.
+
+```ruby
+# Track API client with a 3-second timeout
+$customerio = Customerio::Client.new("YOUR SITE ID", "YOUR API SECRET KEY", timeout: 3)
+
+# Transactional API client with a 3-second timeout
+client = Customerio::APIClient.new("your API key", timeout: 3)
+```
+
+When a request exceeds the timeout, Ruby raises `Net::OpenTimeout` (connection phase) or `Net::ReadTimeout` (waiting for response). You can rescue both:
+
+```ruby
+begin
+  $customerio.identify(id: 5, email: "person@example.com")
+rescue Net::OpenTimeout, Net::ReadTimeout => e
+  # handle timeout
+end
+```
+
 ### Identify logged in customers
 
 Tracking data of logged in customers is a key part of [Customer.io](https://customer.io). In order to
@@ -188,14 +211,32 @@ encourage your customers to perform an action.
 #                          event. These attributes can be used in your triggers to control who should
 #                          receive the triggered email. You can set any number of data values.
 
-$customerio.track(5, "purchase", :type => "socks", :price => "13.99")
+$customerio.track(5, "purchase", { :type => "socks", :price => "13.99" })
 ```
 
-**Note:** If you want to track events which occurred in the past, you can include a `timestamp` attribute
+**Note:** If you want to track events which occurred in the past, you can pass a `timestamp` keyword argument
 (in seconds since the epoch), and we'll use that as the date the event occurred.
 
 ```ruby
-$customerio.track(5, "purchase", :type => "socks", :price => "13.99", :timestamp => 1365436200)
+$customerio.track(5, "purchase", { :type => "socks", :price => "13.99" }, timestamp: 1365436200)
+```
+
+#### Deduplicating events
+
+You can provide a [ULID](https://github.com/ulid/spec) `id` to deduplicate events. If two events have the same `id`, Customer.io won't process the event a second time.
+
+```ruby
+$customerio.track(5, "purchase", { :type => "socks" }, id: "01BX5ZZKBKACTAV9WEVGEMMVRY")
+
+$customerio.track_anonymous("anon-id", "purchase", { :type => "socks" }, id: "01BX5ZZKBKACTAV9WEVGEMMVRY")
+```
+
+You can also pass `timestamp` as a keyword argument (epoch seconds) instead of including it in the attributes hash:
+
+```ruby
+$customerio.track(5, "purchase", { :type => "socks" }, timestamp: 1561231234)
+
+$customerio.track(5, "purchase", { :type => "socks" }, id: "01BX5ZZKBKACTAV9WEVGEMMVRY", timestamp: 1561231234)
 ```
 
 ### Tracking anonymous events
@@ -210,7 +251,7 @@ Anonymous events cannot trigger campaigns by themselves. To trigger a campaign,
 # name (required)                   - the name of the event you want to track.
 # attributes (optional)             - related information you want to attach to the event.
 
-$customerio.track_anonymous(anonymous_id, "product_view", :type => "socks" )
+$customerio.track_anonymous(anonymous_id, "product_view", { :type => "socks" })
 ```
 
 Use the `recipient` attribute to specify the email address to send the messages to. [See our documentation on how to use anonymous events for more details](https://customer.io/docs/invite-emails/).
@@ -220,7 +261,7 @@ Use the `recipient` attribute to specify the email address to send the messages
 If you previously sent [invite events](https://customer.io/docs/anonymous-invite-emails/), you can achieve the same functionality by sending an anonymous event with `nil` for the anonymous identifier. To send anonymous invites, your event *must* include a `recipient` attribute. 
 
 ```ruby
-$customerio.track_anonymous(nil, "invite", :recipient => "new.person@example.com" )
+$customerio.track_anonymous(nil, "invite", { :recipient => "new.person@example.com" })
 ```
 
 ### Adding a mobile device
@@ -246,6 +287,26 @@ Deleting a device token will remove it from the associated customer to stop furt
 $customerio.delete_device(5, "my_device_token")
 ```
 
+### Tracking delivery metrics
+
+Report delivery metrics using the `track_delivery_metric` method, which calls the `/api/v1/metrics` endpoint. This replaces the deprecated `/push/events` endpoint. The `delivery_id` is required. Valid metrics are: `opened`, `clicked`, `converted`, `delivered`, `bounced`, `deferred`, `dropped`, `spammed`.
+
+```ruby
+$customerio.track_delivery_metric("opened", delivery_id: "RPILAgUBcRillFPDbQQ=")
+
+$customerio.track_delivery_metric("clicked", {
+  delivery_id: "RPILAgUBcRillFPDbQQ=",
+  timestamp: 1561231234,
+  href: "https://example.com/link",
+  recipient: "user@example.com"
+})
+
+$customerio.track_delivery_metric("bounced", {
+  delivery_id: "RPILAgUBcRillFPDbQQ=",
+  reason: "mailbox full"
+})
+```
+
 ### Suppress a user
 
 Deletes the customer with the provided id if it exists and suppresses all future events and identifies for that customer.
@@ -262,6 +323,35 @@ Start tracking events and identifies again for a previously suppressed customer.
 $customerio.unsuppress(5)
 ```
 
+### Batch operations
+
+You can send up to 500KB of operations in a single request using the [Track v2 batch endpoint](https://customer.io/docs/api/track/#tag/Track-v2/operation/batch). Each operation can identify, track events, or delete people and objects.
+
+```ruby
+$customerio.batch([
+  {
+    type: "person",
+    identifiers: { id: "42" },
+    action: "identify",
+    attributes: { first_name: "Jane", plan: "premium" },
+  },
+  {
+    type: "person",
+    identifiers: { id: "42" },
+    action: "event",
+    name: "purchase",
+    data: { amount: 99 },
+  },
+  {
+    type: "person",
+    identifiers: { id: "99" },
+    action: "delete",
+  },
+])
+```
+
+See the [Track v2 API docs](https://customer.io/docs/api/track/#tag/Track-v2/operation/batch) for the full list of supported actions and fields.
+
 ### Send Transactional Messages
 
 To use the Customer.io [Transactional API](https://customer.io/docs/transactional-api), create an instance of the API client using an [app key](https://customer.io/docs/managing-credentials#app-api-keys) and create a request object of your message type.
@@ -272,7 +362,7 @@ Create a new `SendEmailRequest` object containing:
 
 * `transactional_message_id`: the ID of the transactional message you want to send, or the `body`, `from`, and `subject` of a new message.
 * `to`: the email address of your recipients 
-* an `identifiers` object containing the `id` of your recipient. If the `id` does not exist, Customer.io creates it.
+* an `identifiers` object containing the `email` and/or `id` of your recipient. If the person you reference by email or ID does not exist, Customer.io creates them.
 * a `message_data` object containing properties that you want reference in your message using liquid.
 * You can also send attachments with your message. Use `attach` to encode attachments.
 
@@ -296,7 +386,7 @@ request = Customerio::SendEmailRequest.new(
     products: [],
   },
   identifiers: {
-    id: "2",
+    email: "person@example.com",
   },
 )
 
@@ -349,11 +439,52 @@ rescue Customerio::InvalidResponse => e
 end
 ```
 
+### Trigger Broadcasts
+
+You can trigger [API-triggered broadcasts](https://customer.io/docs/api-triggered-broadcasts/) using the `APIClient`. Create a `TriggerBroadcastRequest` with the broadcast's numeric ID and optional audience/data parameters.
+
+```ruby
+require "customerio"
+
+client = Customerio::APIClient.new("your API key", region: Customerio::Regions::US)
+
+request = Customerio::TriggerBroadcastRequest.new(
+  broadcast_id: 12,
+  emails: ["recipient@example.com"],
+  data: {
+    headline: "Roadrunner spotted in Albuquerque!",
+    date: 1511315635,
+  },
+  email_add_duplicates: false,
+  email_ignore_missing: false,
+  id_ignore_missing: false,
+)
+
+begin
+  response = client.trigger_broadcast(request)
+  puts response
+rescue Customerio::InvalidResponse => e
+  puts e.code, e.message
+end
+```
+
+You can target the broadcast audience in several ways. Only one audience option can be present per request:
+
+- `recipients`: a hash with filter conditions (e.g., `{ segment: { id: 7 } }`)
+- `emails`: an array of email addresses
+- `ids`: an array of customer IDs
+- `per_user_data`: an array of per-user objects
+- `data_file_url`: a URL to a JSON lines file
+
+If you omit the audience option, the broadcast uses its default audience configured in the UI.
+
 ## Contributing
 
 1. Fork it
 2. Clone your fork (`git clone git@github.com:MY_USERNAME/customerio-ruby.git && cd customerio-ruby`)
 3. Create your feature branch (`git checkout -b my-new-feature`)
-4. Commit your changes (`git commit -am 'Added some feature'`)
-5. Push to the branch (`git push origin my-new-feature`)
-6. Create new Pull Request
+4. Install dependencies (`bundle install`)
+5. Run the test and lint suite (`bundle exec rake`)
+6. Commit your changes (`git commit -am 'Added some feature'`)
+7. Push to the branch (`git push origin my-new-feature`)
+8. Create new Pull Request

data/lib/customerio/api.rb

@@ -1,47 +1,78 @@
-require 'net/http'
-require 'multi_json'
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
 
 module Customerio
   class APIClient
     def initialize(app_key, options = {})
-      options[:region] = Customerio::Regions::US if options[:region].nil?
-      raise "region must be an instance of Customerio::Regions::Region" unless options[:region].is_a?(Customerio::Regions::Region)
+      options = options.dup
+      options[:region] = Regions::US if options[:region].nil?
+      unless options[:region].is_a?(Regions::Region)
+        raise ArgumentError, "region must be an instance of Customerio::Regions::Region"
+      end
 
       options[:url] = options[:region].api_url if options[:url].nil? || options[:url].empty?
-      @client = Customerio::BaseClient.new({ app_key: app_key }, options)
+      @client = BaseClient.new({ app_key: app_key }, options)
     end
 
     def send_email(req)
-      raise "request must be an instance of Customerio::SendEmailRequest" unless req.is_a?(Customerio::SendEmailRequest)
-      response = @client.request(:post, send_email_path, req.message)
+      validate_request!(req, SendEmailRequest)
 
-      case response
-      when Net::HTTPSuccess then
-        JSON.parse(response.body)
-      when Net::HTTPBadRequest then
-        json = JSON.parse(response.body)
-        raise Customerio::InvalidResponse.new(response.code, json['meta']['error'], response)
-      else
-        raise InvalidResponse.new(response.code, response.body)
-      end
+      deliver(send_email_path, req.message)
     end
 
     def send_push(req)
-      raise "request must be an instance of Customerio::SendPushRequest" unless req.is_a?(Customerio::SendPushRequest)
-      response = @client.request(:post, send_push_path, req.message)
+      validate_request!(req, SendPushRequest)
+
+      deliver(send_push_path, req.message)
+    end
+
+    def send_sms(req)
+      validate_request!(req, SendSMSRequest)
+
+      deliver(send_sms_path, req.message)
+    end
+
+    def send_inbox_message(req)
+      validate_request!(req, SendInboxMessageRequest)
+
+      deliver(send_inbox_message_path, req.message)
+    end
+
+    def send_in_app(req)
+      validate_request!(req, SendInAppRequest)
+
+      deliver(send_in_app_path, req.message)
+    end
+
+    def trigger_broadcast(req)
+      validate_request!(req, TriggerBroadcastRequest)
+
+      deliver(trigger_broadcast_path(req.broadcast_id), req.message)
+    end
+
+    private
+
+    def deliver(path, message)
+      response = @client.request(:post, path, message)
 
       case response
-      when Net::HTTPSuccess then
+      when Net::HTTPSuccess
         JSON.parse(response.body)
-      when Net::HTTPBadRequest then
-        json = JSON.parse(response.body)
-        raise Customerio::InvalidResponse.new(response.code, json['meta']['error'], response)
+      when Net::HTTPBadRequest
+        error = JSON.parse(response.body).dig("meta", "error")
+        raise InvalidResponse.new(response.code, error, response)
       else
-        raise InvalidResponse.new(response.code, response.body)
+        raise InvalidResponse.new(response.code, response.body, response)
       end
     end
 
-    private
+    def validate_request!(request, request_class)
+      return if request.is_a?(request_class)
+
+      raise ArgumentError, "request must be an instance of #{request_class}"
+    end
 
     def send_email_path
       "/v1/send/email"
@@ -50,5 +81,21 @@ module Customerio
     def send_push_path
       "/v1/send/push"
     end
+
+    def send_sms_path
+      "/v1/send/sms"
+    end
+
+    def send_inbox_message_path
+      "/v1/send/inbox_message"
+    end
+
+    def send_in_app_path
+      "/v1/send/in_app"
+    end
+
+    def trigger_broadcast_path(broadcast_id)
+      "/v1/campaigns/#{broadcast_id}/triggers"
+    end
   end
 end

data/lib/customerio/base_client.rb

@@ -1,19 +1,22 @@
-require 'net/http'
-require 'multi_json'
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
 
 module Customerio
-  DEFAULT_TIMEOUT  = 10
+  DEFAULT_TIMEOUT = 10
+
+  class InvalidRequest < StandardError; end
 
-  class InvalidRequest < RuntimeError; end
-  class InvalidResponse < RuntimeError
+  class InvalidResponse < StandardError
     attr_reader :code, :response
 
-    def initialize(code, body, response=nil)
-      @message = body
+    def initialize(code, body, response = nil)
       @code = code
       @response = response
 
-      super(@message)
+      super(body)
     end
   end
 
@@ -36,27 +39,28 @@ module Customerio
 
     def execute(method, path, body = nil, headers = {})
       uri = URI.join(@base_uri, path)
+      request_headers = headers.dup
 
       session = Net::HTTP.new(uri.host, uri.port)
-      session.use_ssl = (uri.scheme == 'https')
+      session.use_ssl = uri.scheme == "https"
       session.open_timeout = @timeout
       session.read_timeout = @timeout
 
-      req = request_class(method).new(uri.path)
+      req = request_class(method).new(uri.request_uri)
 
-      headers['User-Agent'] = "Customer.io Ruby Client/" + Customerio::VERSION
+      request_headers["User-Agent"] = "Customer.io Ruby Client/#{VERSION}"
 
-      if @auth.has_key?(:site_id) && @auth.has_key?(:api_key)
-        req.initialize_http_header(headers)
+      if @auth.key?(:site_id) && @auth.key?(:api_key)
+        req.initialize_http_header(request_headers)
         req.basic_auth @auth[:site_id], @auth[:api_key]
       else
-        headers['Authorization'] = "Bearer #{@auth[:app_key]}"
-        req.initialize_http_header(headers)
+        request_headers["Authorization"] = "Bearer #{@auth[:app_key]}"
+        req.initialize_http_header(request_headers)
       end
 
-      if !body.nil?
-        req.add_field('Content-Type', 'application/json')
-        req.body = MultiJson.dump(body)
+      unless body.nil?
+        req.add_field("Content-Type", "application/json")
+        req.body = JSON.generate(body)
       end
 
       session.start do |http|
@@ -72,14 +76,16 @@ module Customerio
         Net::HTTP::Put
       when :delete
         Net::HTTP::Delete
+      when :get
+        Net::HTTP::Get
       else
-        raise InvalidRequest.new("Invalid request method #{method.inspect}")
+        raise InvalidRequest, "Invalid request method #{method.inspect}"
       end
     end
 
     def verify_response(response)
       case response
-      when Net::HTTPSuccess then
+      when Net::HTTPSuccess
         response
       else
         raise InvalidResponse.new(response.code, response.body, response)