openpanel-sdk 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42836fb7514e3e373797c069fcee5fef7b7399615910b284275292b7775eabc4
-  data.tar.gz: e45aa86ad6c7ac09d6af7f1610aab60febfe33404739d969dbe46638d73511df
+  metadata.gz: c159e40267698c580c68f4eb194e3d84bad06967c89157402cc34f56b831d350
+  data.tar.gz: 0427f3b059c49f4df136875d93d65c99dd01625f370c7f8560d1edc45a935c74
 SHA512:
-  metadata.gz: 49b8de377f80b5190c5f93375c75873ded920f153292b7317d96164e6e8065f6d1f75d12fab0ba011b6bde4bc93abf1d2743532221faded38eb0865cff217ef4
-  data.tar.gz: 601909795ac404331caafd5c0455d285cbf50e94b0038b9dea24eee017a271f5808f1f189e1ba6503ae836abbd38259ca5f8d43c16326fb83b80fba5dd635a60
+  metadata.gz: eb4f828530306445f30c1de85ec402fb09346bd19d8afbc146eb7ee97d318f57dc2d545dbe11c406408bb97bc0ad7a1bac8fb989fd3aeaf41ea6f5c86faa4d90
+  data.tar.gz: a3465621ab65ada9a9c1f3f503507a5bb44dc702f09cb97bf992f0b185c041487e2522413c68dbb5aa26c8115a92c94fcd4cc459b38c874778e24a78dffbc5d1

data/.junie/AGENTS.md

@@ -0,0 +1,67 @@
+# Development Guidelines for OpenPanel SDK
+
+This document provides project-specific information for developers working on the OpenPanel Ruby SDK.
+
+## Build and Configuration
+
+### Environment Setup
+1. **Dependencies**: Install the required gems using Bundler:
+   ```bash
+   bundle install
+   ```
+2. **Environment Variables**: The project uses `dotenv` to manage environment variables. Create a `.env` file in the root directory based on `.env_sample`:
+   ```env
+   OPENPANEL_TRACK_URL=https://api.openpanel.dev/track
+   OPENPANEL_CLIENT_ID=<YOUR_CLIENT_ID>
+   OPENPANEL_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
+   ```
+   *Note: Ensure these variables are set correctly for the tracker to authenticate with the OpenPanel API.*
+
+### SDK Initialization
+The `OpenPanel::SDK::Tracker` requires `OPENPANEL_CLIENT_ID` and `OPENPANEL_CLIENT_SECRET` to be present in the environment if events are to be sent. You can disable event sending for testing purposes by passing `disabled: true` to the initializer.
+
+## Testing
+
+### Running Tests
+The project uses RSpec. To run the full test suite:
+```bash
+bundle exec rspec
+```
+
+### Adding New Tests
+When adding new features or fixing bugs, add corresponding specs in the `spec/` directory. Ensure you require `spec_helper` at the top of your spec file.
+
+### Simple Test Example
+Below is a basic test demonstrating how to verify the SDK version and tracker initialization without making network requests:
+
+```ruby
+# spec/example_spec.rb
+require 'spec_helper'
+
+RSpec.describe 'SDK Setup' do
+  it 'verifies version is defined' do
+    expect(OpenPanel::SDK::VERSION).not_to be_nil
+  end
+
+  it 'initializes tracker in disabled mode' do
+    tracker = OpenPanel::SDK::Tracker.new({ app: 'test' }, disabled: true)
+    expect(tracker.global_properties[:app]).to eq('test')
+  end
+end
+```
+
+## Additional Development Information
+
+### HTTP Client
+The SDK uses **Faraday** for HTTP communication. The `Tracker` class handles the request logic, including basic error handling for common HTTP status codes (401, 429, 500).
+
+### Code Style
+- Follow standard Ruby naming conventions (snake_case for methods/variables, PascalCase for classes/modules).
+- The project includes `rubocop` for linting. You can run it with:
+  ```bash
+  bundle exec rubocop
+  ```
+
+### Key Components
+- `OpenPanel::SDK::Tracker`: Main entry point for tracking events, users, and revenue.
+- `OpenPanel::SDK::IdentifyUser`: Data class for user identification properties.

data/lib/openpanel/sdk/group.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenPanel
+  module SDK
+    # Group payload class. Use this class to create or update a group in OpenPanel.
+    # @attr id [String] group ID
+    # @attr type [String] group type (e.g. 'company', 'team')
+    # @attr name [String] group name
+    # @attr properties [Hash] group properties
+    class Group
+      attr_accessor :id, :type, :name, :properties
+
+      def initialize(id: nil, type: nil, name: nil, properties: {})
+        @id = id
+        @type = type
+        @name = name
+        @properties = properties
+      end
+
+      def to_json(*_args)
+        {
+          id: id,
+          type: type,
+          name: name,
+          properties: properties
+        }.to_json
+      end
+    end
+  end
+end

data/lib/openpanel/sdk/tracker.rb

@@ -13,6 +13,8 @@ module OpenPanel
       TRACKING_TYPE_TRACK = 'track'
       TRACKING_TYPE_INCREMENT = 'increment'
       TRACKING_TYPE_DECREMENT = 'decrement'
+      TRACKING_TYPE_GROUP = 'group'
+      TRACKING_TYPE_ASSIGN_GROUP = 'assign_group'
 
       attr_reader :headers, :global_properties
 
@@ -42,14 +44,17 @@ module OpenPanel
       # @param profile_id [String] (optional) user profile ID
       # @param tracking_type [String]
       # @param payload [Hash] event payload
+      # @param groups [Array<String>] (optional) list of group IDs
       # @param filter [Lambda] pass in a lambda to filter events. If the lambda returns true, the event won't be tracked.
       # @return [Faraday::Response | nil] The Faraday plain response object or nil, if the event was filtered out
       # @raise [OpenPanel::SDK::OpenPanelError] if the request fails or the event filter is not a method or lambda
-      def track(event, profile_id: '', tracking_type: TRACKING_TYPE_TRACK, payload: {}, filter: ->(_payload) { false })
+      def track(event, profile_id: '', tracking_type: TRACKING_TYPE_TRACK, payload: {}, groups: nil, filter: ->(_payload) { false })
         return if filter.call(payload)
 
         payload = global_properties.merge(payload) unless global_properties.empty?
-        payload = { type: tracking_type, payload: { name: event, profileId: profile_id, properties: payload } }
+        payload = { name: event, profileId: profile_id, properties: payload }
+        payload[:groups] = Array(groups) if groups
+        payload = { type: tracking_type, payload: payload }
 
         send_request payload: payload
       rescue StandardError => e
@@ -73,8 +78,8 @@ module OpenPanel
       # @param property [String] property to increment
       # @param value [Integer] value to increment by
       def increment_property(user, property = 'visits', value = 1)
-        payload = { property: property, value: value }
-        payload = { type: TRACKING_TYPE_INCREMENT, profileId: user.profile_id, payload: payload }
+        payload = { profileId: user.profile_id, property: property, value: value }
+        payload = { type: TRACKING_TYPE_INCREMENT, payload: payload }
 
         send_request payload: payload
       end
@@ -84,8 +89,8 @@ module OpenPanel
       # @param property [String] property to increment
       # @param value [Integer] value to decrement by
       def decrement_property(user, property = 'visits', value = 1)
-        payload = { property: property, value: value }
-        payload = { type: TRACKING_TYPE_DECREMENT, profileId: user.profile_id, payload: payload }
+        payload = { profileId: user.profile_id, property: property, value: value }
+        payload = { type: TRACKING_TYPE_DECREMENT, payload: payload }
 
         send_request payload: payload
       end
@@ -100,6 +105,35 @@ module OpenPanel
         track 'revenue', profile_id: user.profile_id, payload: payload
       end
 
+      # Create or update a group in OpenPanel
+      # @param group [OpenPanel::SDK::Group] group to create/update
+      def upsert_group(group)
+        payload = { id: group.id, type: group.type, name: group.name, properties: group.properties }
+        payload = { type: TRACKING_TYPE_GROUP, payload: payload }
+
+        send_request payload: payload
+      end
+
+      # Assign user to a group in OpenPanel
+      # @param profile_id [String] user profile ID
+      # @param group_id [String] group ID
+      def set_group(profile_id, group_id)
+        payload = { profileId: profile_id, groupIds: [group_id] }
+        payload = { type: TRACKING_TYPE_ASSIGN_GROUP, payload: payload }
+
+        send_request payload: payload
+      end
+
+      # Assign user to multiple groups in OpenPanel
+      # @param profile_id [String] user profile ID
+      # @param group_ids [Array<String>] list of group IDs
+      def set_groups(profile_id, group_ids)
+        payload = { profileId: profile_id, groupIds: group_ids }
+        payload = { type: TRACKING_TYPE_ASSIGN_GROUP, payload: payload }
+
+        send_request payload: payload
+      end
+
       def fetch_device_id
         return if @disabled
 

data/lib/openpanel/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module OpenPanel
   module SDK
-    VERSION = '0.3.3'
+    VERSION = '0.3.4'
   end
 end

data/lib/openpanel/sdk.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 require_relative 'sdk/identify_user'
+require_relative 'sdk/group'
 require_relative 'sdk/tracker'
 require_relative 'sdk/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openpanel-sdk
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.4
 platform: ruby
 authors:
 - Thomas Stätter
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-08 00:00:00.000000000 Z
+date: 2026-05-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -47,10 +47,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".env_sample"
+- ".junie/AGENTS.md"
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/openpanel/sdk.rb
+- lib/openpanel/sdk/group.rb
 - lib/openpanel/sdk/identify_user.rb
 - lib/openpanel/sdk/tracker.rb
 - lib/openpanel/sdk/version.rb