blueshift_crm 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae6f2541ddf0c9a5d3e7b02294463398a46e5d0074d0b225a4b3fb29d3449bc8
+  data.tar.gz: 115e3c4bb73537869701e98f6f19aaabd8c6487300abb444aff7573a9381529c
+SHA512:
+  metadata.gz: 8b6cad6ea2db23d2133cf62db0cc8d0ca7bf85a14bb5c015217a265cb46d95d62ae9811cf4132058443db63a8747f52f85d8da925d610cde670d66e2d1db1812
+  data.tar.gz: 62a3c0092d724d0d1ccd2f670820181adeea26392da6ae11455f8ca42238276d27800e47a85d9471731de077b70e6426d02a04bd8b2c8e83c80d75332b63de88

data/README.md

@@ -0,0 +1,60 @@
+# Blueshift CRM (Ruby)
+
+A lightweight Ruby client for the Blueshift CRM API.
+
+## Install
+
+```bash
+bundle add blueshift_crm
+```
+
+### Add ENV variables for API keys:
+
+```bash
+export BLUESHIFT_SITE_ID=""
+export BLUESHIFT_EVENT_API_KEY=""
+export BLUESHIFT_USER_API_KEY=""
+export BLUESHIFT_API_PASSWORD=""
+```
+
+### Optional:
+
+```bash
+export BLUESHIFT_REGION=""
+```
+
+## Usage:
+
+```bash
+# create a client instance:
+client = BlueshiftCRM::Client.new
+```
+#### Adapters:
+```bash
+client.adapters.list
+```
+
+#### Campaigns:
+```bash
+client.campaigns.list
+```
+
+#### Custom User Lists:
+```bash
+client.custom_user_lists.seed_lists
+```
+
+#### Customers:
+```bash
+client.customers.get(uuid: "")
+```
+
+#### Events:
+```bash
+client.events.history(event: "")
+```
+
+#### Segments:
+```bash
+client.campaigns.list
+```

data/lib/blueshift_crm/client.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module BlueshiftCRM
+  class Client
+    DEFAULT_TIMEOUT = 30
+    READONLY_GETS   = %w[GET].freeze
+
+    attr_reader :base_url, :site_id
+
+    # region: "eu" or nil
+    # user_api_key: required for most endpoints (you called this blueshift_api_password; both envs supported)
+    # event_api_key: required for POST /api/v1/event
+    def initialize(
+      region: ENV["BLUESHIFT_REGION"],
+      user_api_key: ENV["BLUESHIFT_USER_API_KEY"] || ENV["blueshift_api_password"],
+      event_api_key: ENV["BLUESHIFT_EVENT_API_KEY"] || ENV["event_api_key"],
+      site_id: ENV["BLUESHIFT_SITE_ID"] || ENV["site_id"],
+      timeout: DEFAULT_TIMEOUT
+    )
+      @base_url = region.to_s.downcase == "eu" ? "https://api.eu.getblueshift.com" : "https://api.getblueshift.com"
+      @user_api_key  = user_api_key
+      @event_api_key = event_api_key
+      @site_id       = site_id
+      @timeout       = timeout
+
+      raise ArgumentError, "Missing user_api_key (BLUESHIFT_USER_API_KEY)" unless @user_api_key
+      raise ArgumentError, "Missing event_api_key (BLUESHIFT_EVENT_API_KEY or event_api_key)" unless @event_api_key
+      raise ArgumentError, "Missing site_id (BLUESHIFT_SITE_ID or site_id)" unless @site_id
+
+      @conn_user  = build_conn(auth_key: @user_api_key)
+      @conn_event = build_conn(auth_key: @event_api_key)
+    end
+
+    # ---- Public resource accessors ----
+    def campaigns         = @campaigns         ||= Resources::Campaigns.new(self)
+    def events            = @events            ||= Resources::Events.new(self)
+    def customers         = @customers         ||= Resources::Customers.new(self)
+    def segments          = @segments          ||= Resources::Segments.new(self)
+    def adapters          = @adapters          ||= Resources::Adapters.new(self)
+    def custom_user_lists = @custom_user_lists ||= Resources::CustomUserLists.new(self)
+
+    # ---- Core HTTP helpers ----
+    def get(path, params: {}, user_api: true)
+      request(:get, path, params: with_site_id(params), user_api: user_api)
+    end
+
+    def post(path, body: {}, params: {}, user_api: true)
+      request(:post, path, body: body, params: with_site_id(params), user_api: user_api)
+    end
+
+    def put(path, body: {}, params: {}, user_api: true)
+      request(:put, path, body: body, params: with_site_id(params), user_api: user_api)
+    end
+
+    def request(method, path, body: nil, params: {}, user_api: true)
+      conn = user_api ? @conn_user : @conn_event
+      resp = conn.public_send(method, path) do |req|
+        req.params.update(params.compact)
+        req.headers["Content-Type"] = "application/json" unless READONLY_GETS.include?(method.to_s.upcase)
+        req.body = JSON.dump(body) if body && !READONLY_GETS.include?(method.to_s.upcase)
+      end
+
+      parse_response(resp)
+    rescue Faraday::ClientError => e
+      status = e.response&.dig(:status)
+      body   = e.response&.dig(:body)
+      raise Error.new("HTTP #{status || 'error'}: #{e.message}", status: status, body: body)
+    rescue Faraday::Error => e
+      raise Error.new("HTTP error: #{e.message}")
+    end
+
+    private
+
+    def with_site_id(params)
+      { site_id: @site_id }.merge(params || {})
+    end
+
+    def build_conn(auth_key:)
+      Faraday.new(url: @base_url) do |f|
+        f.request :retry, max: 2, interval: 0.25, backoff_factor: 2, methods: %i[get put post delete]
+        f.options.timeout = @timeout
+        # HTTP Basic with API key as username and blank password
+        f.request :authorization, :basic, auth_key, ""
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def parse_response(resp)
+      return nil if resp.body.to_s.strip.empty?
+      JSON.parse(resp.body)
+    rescue JSON::ParserError
+      resp.body
+    end
+  end
+end
+

data/lib/blueshift_crm/error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module BlueshiftCRM
+  class Error < StandardError
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body   = body
+    end
+  end
+end
+

data/lib/blueshift_crm/resources/adapters.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module BlueshiftCRM
+  module Resources
+    class Adapters < Base
+      # GET /api/v1/account_adapters?channel_name=...&adapter_name=...
+      def list(channel_name: nil, adapter_name: nil)
+        client.get("/api/v1/account_adapters", params: { channel_name:, adapter_name: })
+      end
+    end
+  end
+end

data/lib/blueshift_crm/resources/base.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module BlueshiftCRM
+  module Resources
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      attr_reader :client
+    end
+  end
+end
+

data/lib/blueshift_crm/resources/campaigns.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BlueshiftCRM
+  module Resources
+    class Campaigns < Base
+      # GET /api/v2/campaigns.json
+      def list(page: nil, per_page: nil, updated_after: nil)
+        client.get("/api/v2/campaigns.json", params: { page:, per_page:, updated_after: })
+      end
+
+      # GET /api/v1/campaigns.json
+      def performance(start_date:, end_date:, timezone: nil)
+        client.get("/api/v1/campaigns.json", params: { start_date:, end_date:, timezone: })
+      end
+
+      # GET /api/v1/campaigns/{uuid}/detail.json
+      def detail(uuid:)
+        client.get("/api/v1/campaigns/#{uuid}/detail.json")
+      end
+
+      # Optional: POST /api/v1/campaigns/{type}
+      def create(campaign_type:, payload:)
+        client.post("/api/v1/campaigns/#{campaign_type}", body: payload)
+      end
+    end
+  end
+end

data/lib/blueshift_crm/resources/custom_user_lists.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module BlueshiftCRM
+  module Resources
+    class CustomUserLists < Base
+      # GET /api/v1/custom_user_lists/seed_lists
+      def seed_lists
+        client.get("/api/v1/custom_user_lists/seed_lists")
+      end
+
+      # GET /api/v1/custom_user_lists/id/{custom_user_list_id}
+      def details(list_id:)
+        client.get("/api/v1/custom_user_lists/id/#{list_id}")
+      end
+
+      # Optional helpers if you plan to create/manage lists:
+      def create(name:, description: nil)
+        client.post("/api/v1/custom_user_lists/create", body: { name:, description: })
+      end
+
+      def add_user(list_id:, identifier:)
+        client.put("/api/v1/custom_user_lists/add_user_to_list/#{list_id}", body: identifier)
+      end
+    end
+  end
+end

data/lib/blueshift_crm/resources/customers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module BlueshiftCRM
+  module Resources
+    class Customers < Base
+      # GET /api/v1/customers/{uuid}
+      def get(uuid:)
+        client.get("/api/v1/customers/#{uuid}")
+      end
+
+      # GET /api/v1/customers?email=... or customer_id=...
+      def search(email: nil, customer_id: nil)
+        client.get("/api/v1/customers", params: { email:, customer_id: })
+      end
+
+      # POST /api/v1/customers (create or update)
+      def upsert(payload:)
+        client.post("/api/v1/customers", body: payload)
+      end
+
+      # GET /api/v1/customer_search/show_events?uuid=...
+      def events(uuid:, limit: nil)
+        client.get("/api/v1/customer_search/show_events", params: { uuid:, limit: })
+      end
+    end
+  end
+end

data/lib/blueshift_crm/resources/events.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module BlueshiftCRM
+  module Resources
+    class Events < Base
+      # POST /api/v1/event (requires Event API key)
+      def send_event(event:)
+        client.request(:post, "/api/v1/event", body: event, user_api: false)
+      end
+
+      # GET /api/v1/event/debug
+      def latest_debug
+        client.get("/api/v1/event/debug")
+      end
+
+      # GET /api/v1/event/history
+      def history(event: nil, limit: nil)
+        client.get("/api/v1/event/history", params: { event:, limit: })
+      end
+    end
+  end
+end

data/lib/blueshift_crm/resources/segments.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module BlueshiftCRM
+  module Resources
+    class Segments < Base
+      # GET /api/v1/segments/list
+      def list
+        client.get("/api/v1/segments/list")
+      end
+
+      # GET /api/v1/segments/{segment_uuid}/matching_users.json
+      def matching_users_count(segment_uuid:)
+        client.get("/api/v1/segments/#{segment_uuid}/matching_users.json")
+      end
+    end
+  end
+end

data/lib/blueshift_crm/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+module BlueshiftCRM
+  VERSION = "0.1.0"
+end

data/lib/blueshift_crm.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "json"
+require "faraday"
+
+require_relative "blueshift_crm/version"
+require_relative "blueshift_crm/error"
+require_relative "blueshift_crm/client"
+
+# resources
+require_relative "blueshift_crm/resources/base"
+require_relative "blueshift_crm/resources/campaigns"
+require_relative "blueshift_crm/resources/events"
+require_relative "blueshift_crm/resources/customers"
+require_relative "blueshift_crm/resources/segments"
+require_relative "blueshift_crm/resources/adapters"
+require_relative "blueshift_crm/resources/custom_user_lists"
+
+module BlueshiftCRM
+  # Entry module namespace
+end
+

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: blueshift_crm
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- JD Warren
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: A lightweight, Faraday-based Ruby client for Blueshift CRM covering campaigns,
+  events, customers, segments, adapters, and custom user lists.
+email:
+- johndavid400@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/blueshift_crm.rb
+- lib/blueshift_crm/client.rb
+- lib/blueshift_crm/error.rb
+- lib/blueshift_crm/resources/adapters.rb
+- lib/blueshift_crm/resources/base.rb
+- lib/blueshift_crm/resources/campaigns.rb
+- lib/blueshift_crm/resources/custom_user_lists.rb
+- lib/blueshift_crm/resources/customers.rb
+- lib/blueshift_crm/resources/events.rb
+- lib/blueshift_crm/resources/segments.rb
+- lib/blueshift_crm/version.rb
+homepage: https://github.com/johndavid400/blueshift_crm
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby client for Blueshift CRM API
+test_files: []