shedcloud-partner_api 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 145e122f76cf50761a1e721feb510f3bb0ea708809dfb986213da9c59c4c1505
-  data.tar.gz: 98b24f0679f7722abec77cab65c9303e21a2ea63934ffdecf6ee50f45ae2b35c
+  metadata.gz: ef147c587026c0e669b48177eff919ed647ba9220351c2fcb233caa960f57d84
+  data.tar.gz: 14e6b2a150cf3604feb9523705bbba744af9515533cca38a204f7d3c26e0419a
 SHA512:
-  metadata.gz: 9a247a283d4fb7a477ae1c93f68e089799a6667f849168689dddd96e8edf04fd2b7cbaf08322959580f66fded4266aecfc4d56e515de69c1a7066259642ed8c5
-  data.tar.gz: 8dac558602c6efe9774323b06305a6a4c87eac64d521c0d97cf2a27531206c92dd9531198c9bf5975ba9e541711bb65eccd22e2f0163f8068b31ab816652a426
+  metadata.gz: b1adcf401a3a46f25bc75b750e884a59743ac7d721d071f8f92606a621a51c7f44a0095996b5ca4944222bc5eea8c354e8601142311a7865e5fe6184ada71829
+  data.tar.gz: 0fa3865cffaf2a7f55ac5829b4e2bea56d06e202cc18953b624694a3756fe0687e9b46c99543aa3dec5cb8789970b035e658eac7c61a1b292b6f7b31cd94e296

data/AGENTS.md

@@ -23,7 +23,7 @@ shedcloud-gem/
 │       ├── errors.rb
 │       ├── scopes.rb
 │       ├── webhooks.rb
-│       └── resources/          # one file per /partner/v1 resource
+│       └── resources/          # one file per /partner/v1 resource (site_events.rb = snake_case POST body)
 ├── spec/
 ├── examples/
 └── shedcloud-partner_api.gemspec
@@ -36,7 +36,8 @@ shedcloud-gem/
 3. **Scopes** live in `scopes.rb` and must stay in sync with `shedcloud-api-go/internal/partnerauth/scopes.go`.
 4. **Auth stays outside resource classes.** Resources only call `HttpClient#request`. Token exchange/caching belongs in `auth_provider.rb`.
 5. **Keep the surface small.** No portal admin endpoints (`/v1/settings/api-keys`, etc.).
-6. After changing `lib/`, run `bundle exec rspec`.
+6. **`site_events.track` sends its body in snake_case** — the ingest endpoint shares its envelope with the configurator tracker rather than the camelCase style of the rest of `/partner/v1`. Do not normalize keys.
+7. After changing `lib/`, run `bundle exec rspec`.
 
 ## Adding a resource
 

data/CHANGELOG.md

@@ -1,6 +1,19 @@
 # Changelog
 
-## 0.1.0
+## 0.2.0 — 2026-07-19
+
+- **Site events** — `client.site_events.track`, `list`, and `each` for
+  `POST/GET /partner/v1/site-events` (visitor behavioral tracking from partner
+  marketing sites). New scopes `partner-api.site-events.read` and
+  `partner-api.site-events.write`. Ingest uses a **snake_case** wire body
+  (`session_id`, `events[].event_type`, …) — pass the hash through as-is; do
+  not camelCase-convert it. Reads use normal camelCase query params
+  (`sessionId`, `types`, `from`, `to`). Batch-only ingest (max 25 events per
+  call); server-side use only.
+- Parity with `@shedcloud/partner-api` site-events resource and
+  `shedcloud-api-go` Partner API changelog entry (2026-07-19).
+
+## 0.1.0 — 2026-07-13
 
 - Initial `shedcloud-partner_api` Ruby gem
 - Built-in hosts: production `https://go.shedcloud.com` (default), sandbox `https://api.shedcloudtest.com`

data/README.md

@@ -92,6 +92,7 @@ Each resource maps to a section of the [hosted reference](https://go.shedcloud.c
 | `client.payments` | `GET /partner/v1/payments` (read-only) |
 | `client.documents` | `GET /partner/v1/documents`, download |
 | `client.events` | `GET /partner/v1/events`, each iterator, redeliver, deliveries |
+| `client.site_events` | `POST/GET /partner/v1/site-events` (visitor behavioral tracking) |
 | `client.configurator_sessions` | `POST /partner/v1/configurator-sessions` |
 
 ### Idempotency and optimistic concurrency
@@ -118,6 +119,29 @@ For boolean query params that must be sent even when `false`:
 client.quotes.list(converted: ShedCloud::PartnerApi::QueryValue.new(false))
 ```
 
+### Site events (marketing-site behavioral tracking)
+
+Proxy batched events from your backend — never call this from the browser with a partner key. The **ingest body is snake_case** on the wire; query params on reads are camelCase.
+
+```ruby
+res = client.site_events.track(
+  {
+    session_id: SecureRandom.uuid,
+    visitor_id: visitor_id_from_local_storage,
+    site_host: 'lelandssheds.com',
+    events: [
+      { event_type: 'page.view', page: '/sheds/lofted-barn' },
+      { event_type: 'cta.click', page: '/sheds/lofted-barn', payload: { cta: 'design-your-own' } }
+    ]
+  }
+)
+puts res['accepted']
+
+client.site_events.each(types: 'page.view') do |event|
+  puts event['eventId'], event['eventType'], event['source']
+end
+```
+
 ## Webhooks
 
 Verify webhook deliveries with the subscription secret against the **raw** request body:
@@ -147,8 +171,10 @@ end
 ## Scopes
 
 ```ruby
-ShedCloud::PartnerApi::Scopes::LOT_STOCK_READ # partner-api.lot-stock.read
-ShedCloud::PartnerApi::Scopes::ORDERS_WRITE    # partner-api.orders.write
+ShedCloud::PartnerApi::Scopes::LOT_STOCK_READ      # partner-api.lot-stock.read
+ShedCloud::PartnerApi::Scopes::ORDERS_WRITE         # partner-api.orders.write
+ShedCloud::PartnerApi::Scopes::SITE_EVENTS_WRITE    # partner-api.site-events.write
+ShedCloud::PartnerApi::Scopes::SITE_EVENTS_READ     # partner-api.site-events.read
 ```
 
 ## Development
@@ -158,6 +184,19 @@ bundle install
 bundle exec rspec
 ```
 
+## Release
+
+1. Bump `lib/shedcloud/partner_api/version.rb` and add a `CHANGELOG.md` entry.
+2. Commit on `main`, then tag and push — GitHub Actions publishes to RubyGems on tag push:
+
+```bash
+git tag v0.2.0
+git push origin main
+git push origin v0.2.0
+```
+
+The workflow (`.github/workflows/release.yml`) runs `bundle exec rspec`, builds the gem, and pushes via `rubygems/release-gem` (OIDC). Tag format must be `v*` (e.g. `v0.2.0`).
+
 ## Versioning & changelog
 
 The Partner API is **additive-only within `/partner/v1`**. This gem is tagged with semver in lockstep with API additions.
@@ -168,6 +207,7 @@ The Partner API is **additive-only within `/partner/v1`**. This gem is tagged wi
 
 - Partner API reference: https://go.shedcloud.com/partner/reference
 - Backend source of truth: `shedcloud-api-go/docs/PARTNER_API.md`
-- TypeScript twin: [`@shedcloud/partner-api`](https://github.com/Corland-Partners-LLC/shedcloud-npm)
-- Go twin: [`shedcloud-gomod/partnerapi`](https://github.com/Corland-Partners-LLC/shedcloud-gomod)
-- PHP twin: [`shedcloud/partner-api`](https://github.com/Corland-Partners-LLC/shedcloud-php)
+- TypeScript/JavaScript: [`@shedcloud/partner-api`](https://github.com/Corland-Partners-LLC/shedcloud-npm)
+- Go: [`shedcloud-gomod/partnerapi`](https://pkg.go.dev/github.com/Corland-Partners-LLC/shedcloud-gomod/partnerapi)
+- Python: [`shedcloud-partner-api`](https://github.com/Corland-Partners-LLC/shedcloud-pypi)
+- PHP: [`shedcloud/partner-api`](https://github.com/Corland-Partners-LLC/shedcloud-php)

data/lib/shedcloud/partner_api/client.rb

@@ -19,6 +19,7 @@ module ShedCloud
                   :payments,
                   :documents,
                   :events,
+                  :site_events,
                   :configurator_sessions
 
       def initialize(auth:, environment: nil, base_url: nil, transport: HttpTransport.new, timeout_seconds: 30.0,
@@ -57,6 +58,7 @@ module ShedCloud
         @payments = Resources::Payments.new(@http)
         @documents = Resources::Documents.new(@http)
         @events = Resources::Events.new(@http)
+        @site_events = Resources::SiteEvents.new(@http)
         @configurator_sessions = Resources::ConfiguratorSessions.new(@http)
       end
 

data/lib/shedcloud/partner_api/resources/site_events.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module ShedCloud
+  module PartnerApi
+    module Resources
+      # Visitor behavioral events from partner marketing sites.
+      #
+      # Partner keys are server-side secrets: proxy events through your backend and
+      # never call these endpoints from the browser. Ingest is rate limited per
+      # company, so batch events client-side (max 25 per request). Always send a
+      # stable visitor_id — it stitches journeys across the marketing site and the
+      # 3D configurator. Raw events are retained ~90 days on reads.
+      class SiteEvents < Base
+        # POST /partner/v1/site-events (scope partner-api.site-events.write).
+        # Unlike most Partner API endpoints, the ingest body natively speaks
+        # snake_case on the wire (session_id, visitor_id, events[].event_type, ...).
+        #
+        # Forward the end shopper's context via top-level client_ip and
+        # client_user_agent — without them every event is stamped with your
+        # server's IP/UA and visitor geo is meaningless. Identity events may
+        # carry events[].customer (first_name/last_name/email/phone/zip),
+        # events[].delivery (address), and events[].payment
+        # (payment_type "RENT_TO_OWN"|"CASH", monthly_term, ...) snapshots.
+        def track(body, options: nil)
+          @http.request('POST', '/partner/v1/site-events', body: body, headers: option_headers(options)) || {}
+        end
+
+        # GET /partner/v1/site-events (scope partner-api.site-events.read).
+        # Query params are camelCase on the wire: cursor, limit (max 200),
+        # sessionId, types, from, to.
+        def list(params = {})
+          query = params.dup
+          query[:types] = query[:types].join(',') if query[:types].is_a?(Array)
+          @http.request('GET', '/partner/v1/site-events', query: query) || {}
+        end
+
+        def each(params = {})
+          cursor = params[:cursor].to_s
+          last_seen = cursor
+
+          loop do
+            page_params = params.dup
+            if cursor.empty?
+              page_params.delete(:cursor)
+            else
+              page_params[:cursor] = cursor
+            end
+
+            response = list(page_params)
+            data = response['data'].is_a?(Array) ? response['data'] : []
+
+            data.each do |event|
+              result = yield(event)
+              return last_seen if result == false
+
+              last_seen = event['eventId'] if event['eventId'].is_a?(String) && !event['eventId'].empty?
+            end
+
+            break unless response['hasMore'] && response['nextCursor'].is_a?(String) && !response['nextCursor'].empty?
+
+            cursor = response['nextCursor']
+          end
+
+          last_seen
+        end
+      end
+    end
+  end
+end

data/lib/shedcloud/partner_api/scopes.rb

@@ -24,6 +24,8 @@ module ShedCloud
       PAYMENTS_WRITE = 'partner-api.payments.write'
       DOCUMENTS_READ = 'partner-api.documents.read'
       EVENTS_READ = 'partner-api.events.read'
+      SITE_EVENTS_READ = 'partner-api.site-events.read'
+      SITE_EVENTS_WRITE = 'partner-api.site-events.write'
       CONFIGURATOR_SESSIONS_WRITE = 'partner-api.configurator-sessions.write'
       DOMAINS_READ = 'partner-api.domains.read'
       AGREEMENTS_READ = 'partner-api.agreements.read'
@@ -51,6 +53,8 @@ module ShedCloud
         PAYMENTS_WRITE,
         DOCUMENTS_READ,
         EVENTS_READ,
+        SITE_EVENTS_READ,
+        SITE_EVENTS_WRITE,
         CONFIGURATOR_SESSIONS_WRITE,
         DOMAINS_READ,
         AGREEMENTS_READ,

data/lib/shedcloud/partner_api/version.rb

@@ -2,6 +2,6 @@
 
 module ShedCloud
   module PartnerApi
-    VERSION = '0.1.0'
+    VERSION = '0.2.1'
   end
 end

data/lib/shedcloud/partner_api.rb

@@ -26,6 +26,7 @@ require_relative 'partner_api/resources/users'
 require_relative 'partner_api/resources/payments'
 require_relative 'partner_api/resources/documents'
 require_relative 'partner_api/resources/events'
+require_relative 'partner_api/resources/site_events'
 require_relative 'partner_api/resources/configurator_sessions'
 require_relative 'partner_api/client'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: shedcloud-partner_api
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Corland Partners LLC
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-14 00:00:00.000000000 Z
+date: 2026-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -77,6 +77,7 @@ files:
 - lib/shedcloud/partner_api/resources/payments.rb
 - lib/shedcloud/partner_api/resources/products.rb
 - lib/shedcloud/partner_api/resources/quotes.rb
+- lib/shedcloud/partner_api/resources/site_events.rb
 - lib/shedcloud/partner_api/resources/stock_templates.rb
 - lib/shedcloud/partner_api/resources/users.rb
 - lib/shedcloud/partner_api/resources/work_orders.rb