equipoise 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de1fcce8a6fbfaed1a0009371d6350128ac310533cbbd52baf0f0883f8d9cdcf
-  data.tar.gz: d2ea1aced1956bba17728d81a0677900010b4ad8d041397756bd8fd09b0459f6
+  metadata.gz: '0452669965e793163b574be7bec3312e057e7e93d959fd8fdc252adc53027d11'
+  data.tar.gz: 2da982746e503901ec54b261fb7845885fcc722c46ae03778388220632a68fc4
 SHA512:
-  metadata.gz: d9a0dacc4037a20322ed758c1ee56999d50a8bde0585bb0e9bd47f4e363c52bdf0df121ef6b0d2bf4832705e54d2eb183633ebf15891333294cac45e1187de74
-  data.tar.gz: 8808b757de5b892e82a106162c77372d7e9baafce7a67ac9162d362a5751cf65ee023db04430409d25a9e410730c0bf3f55b541446d5d1e61d03b8af2c2bd8da
+  metadata.gz: 300d97710b2ccde31122a986ecc53fb9f76c64c7040a0bd5e5199011cf383e73b27b5ada8f88e67720fde588af95715fa0d2cd71a535fb48869950809e04a723
+  data.tar.gz: 8b9a7a469777ab78cb8f0785d683643d72c24ee7951f013d6d003277593c6de5e36efede76bde0fddf6cb1f6bc09059352c623b87a078e796773443b32bbe286

data/CHANGELOG.md

@@ -6,6 +6,26 @@ semantic versioning once published.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-06
+
+### Added
+
+- **Tunable transport limits with hard guardrails** (from AMP backfill feedback).
+  `read_timeout`, `max_retries`, and the new `batch_size` are configurable in the
+  `Equipoise.configure` block, but every value is clamped to a hard range so a
+  producer's config can never make the gem a bad citizen to the receiver:
+  - `read_timeout` → default raised to `30`s (headroom so a full-size batch
+    doesn't time out and get re-sent) and clamped to `5..120`s (a too-low timeout
+    is how one slow batch becomes two concurrent deliveries).
+  - `max_retries` → clamped to `0..5` (no retry storms).
+  - `batch_size` → clamped to `1..500` (the receiver's per-batch cap); drives the
+    default `contacts.batch_sync` chunk size, and an explicit `chunk_size:` is
+    clamped to the same ceiling.
+  Out-of-range values are clamped (and logged when a `logger` is set), never
+  raised, so a stray setting degrades to "safe" instead of failing boot.
+
+## [0.1.0] - 2026-07-05
+
 ### Added
 
 - **Activity / event ingestion** — `contacts.record_activity(external_id:,
@@ -24,7 +44,7 @@ semantic versioning once published.
   - **`Equipoise.disable!` / `enable!` / `disabled?`** test mode — when disabled,
     the client short-circuits to a no-op before any network call or validation,
     so a stray `EQUIPOISE_API_KEY` in a test env can't make a live call.
-- Initial producer client (External CRM Sync, S12):
+- Initial producer client:
   - `Equipoise.configure` / `Equipoise.client` with env-based, rotation-aware
     credentials.
   - `client.contacts.sync` / `batch_sync` (chunks to 500, deterministic per-chunk

data/README.md

@@ -9,17 +9,17 @@ tag reconciliation, custom-field coercion) lives server-side in the receiver's
 `Crm::ContactSyncService`. This client just handles auth, JSON, idempotency,
 bounded retry/backoff, and typed errors.
 
-- **Contract:** [`EXTERNAL_CRM_SYNC_API.openapi.yaml`](../../documentation/integrations/EXTERNAL_CRM_SYNC_API.openapi.yaml) (OpenAPI 3.1)
-- **Guide:** [`EXTERNAL_CRM_SYNC.md`](../../documentation/integrations/EXTERNAL_CRM_SYNC.md)
+The API contract (OpenAPI 3.1) and integration guide are documented with your
+Equipoise account at [app.equipoi.se](https://app.equipoi.se).
 
-> Pre-1.0 and unpublished — consumed by AMP as a `path:`/git dependency first,
-> published to RubyGems only once proven.
+> Pre-1.0: the client is stable and published to RubyGems, but the server API
+> surface may still change before 1.0.
 
 ## Install
 
 ```ruby
 # In the producer app's Gemfile
-gem "equipoise", path: "../equipoise/gems/equipoise"   # or git:
+gem "equipoise"
 ```
 
 ## Configure
@@ -43,6 +43,24 @@ non-loopback host is refused, so the key is never sent in cleartext).
 Under Rails, run `rails g equipoise:install` to generate
 `config/initializers/equipoise.rb`.
 
+### Tuning (optional)
+
+Three transport knobs are configurable and **clamped** to safe ranges, so a
+producer's config can never make the client a bad citizen to the receiver — an
+out-of-range value is clamped (and logged if a `logger` is set), never raised:
+
+```ruby
+Equipoise.configure do |c|
+  c.read_timeout = 30  # seconds per request; clamped to 5..120
+  c.max_retries  = 2   # transient-failure retries; clamped to 0..5
+  c.batch_size   = 500 # contacts per batch_sync request; clamped to 1..500
+end
+```
+
+For a large `batch_sync` backfill, keep `read_timeout` comfortably above how long
+one full batch takes server-side (or lower `batch_size`) so a slow batch never
+times out and gets re-sent.
+
 ## Use
 
 ```ruby
@@ -57,7 +75,7 @@ Equipoise.client.contacts.sync(
   external_id: user.id, email: user.email, idempotency_key: request_id
 )
 
-# Batch backfill — chunks to ≤500/call, one bad item never fails the batch.
+# Batch backfill — chunks to batch_size (default 500), one bad item never fails it.
 # It never raises mid-batch: per-item rejections and chunk-level transport
 # failures both come back as failed items, so earlier successes are preserved.
 result = Equipoise.client.contacts.batch_sync(

data/lib/equipoise/client.rb

@@ -52,10 +52,10 @@ module Equipoise
       @custom_fields ||= CustomFields.new(self)
     end
 
-    # — Claude authored — the single request chokepoint. Returns a Response on
+    # The single request chokepoint. Returns a Response on
     # 2xx; raises a typed ApiError (or ConnectionError) otherwise.
     def request(method, path, body: nil, query: nil, headers: {})
-      return null_response if config.disabled? # test-mode short-circuit (#5) — before validate! or any I/O
+      return null_response if config.disabled? # test-mode short-circuit — before validate! or any I/O
 
       config.validate!
       uri     = build_uri(path, query)

data/lib/equipoise/configuration.rb

@@ -18,6 +18,12 @@
 # the wire). Local dev (`http://localhost`) is allowed; set `allow_insecure_http`
 # to permit a trusted TLS-terminating internal endpoint.
 #
+# Transport knobs (read_timeout, max_retries, batch_size) are producer-tunable in
+# the configure block but CLAMPED to hard ranges (see *_BOUNDS) so a misconfig
+# can never make the gem a bad citizen to the receiver — an oversized batch, a
+# retry storm, or a too-eager give-up-and-retry. Out-of-range values are clamped
+# (and logged if a logger is set), never raised.
+#
 # Used by: Equipoise.configure, Equipoise::Client
 # =============================================================================
 
@@ -25,20 +31,38 @@ module Equipoise
   class Configuration
     DEFAULT_BASE_URL     = "https://app.equipoi.se/api/v1"
     DEFAULT_OPEN_TIMEOUT = 5
-    DEFAULT_READ_TIMEOUT = 15
+    DEFAULT_READ_TIMEOUT = 30
     DEFAULT_MAX_RETRIES  = 2
+    DEFAULT_BATCH_SIZE   = 500
+
+    # Hard limits — every producer-tunable transport knob is clamped into these
+    # ranges so a misconfigured producer can never punish the receiver:
+    #   read_timeout — floor keeps the producer patient enough that one slow
+    #     batch doesn't become two concurrent deliveries (a low timeout is how a
+    #     retry double-submits); ceiling stops a producer worker hanging forever.
+    #   max_retries  — ceiling means a misconfig can't retry-storm the receiver.
+    #   batch_size   — ceiling is the receiver's own per-batch cap (it rejects
+    #     anything larger); floor of 1 keeps slicing sane.
+    # Out-of-range values are clamped, not raised (see #clamp_to).
+    READ_TIMEOUT_BOUNDS  = (5..120).freeze
+    MAX_RETRIES_BOUNDS   = (0..5).freeze
+    BATCH_SIZE_BOUNDS    = (1..500).freeze
+
     LOOPBACK_HOSTS       = %w[localhost 127.0.0.1 ::1 [::1]].freeze
     PRODUCTION_HOST      = URI.parse(DEFAULT_BASE_URL).host # "app.equipoi.se"
 
     attr_accessor :open_timeout,
-                  :read_timeout,
-                  :max_retries,
                   :retry_backoff_base,
                   :max_retry_backoff,
                   :allow_insecure_http,
                   :enabled,
                   :logger,
                   :user_agent
+    # Clamped knobs — custom writers (below) hold every override inside its
+    # *_BOUNDS so the gem stays a good citizen no matter what a producer sets.
+    attr_reader :read_timeout,
+                :max_retries,
+                :batch_size
     attr_writer :api_key,
                 :base_url,
                 :source
@@ -51,6 +75,7 @@ module Equipoise
       @open_timeout        = DEFAULT_OPEN_TIMEOUT
       @read_timeout        = DEFAULT_READ_TIMEOUT
       @max_retries         = DEFAULT_MAX_RETRIES
+      @batch_size          = DEFAULT_BATCH_SIZE
       @retry_backoff_base  = 0.5
       @max_retry_backoff   = 30
       @allow_insecure_http = false
@@ -59,14 +84,14 @@ module Equipoise
       @user_agent          = "equipoise-ruby/#{Equipoise::VERSION}"
     end
 
-    # — Claude authored — test-mode kill switch (#5). When disabled the client
+    # Test-mode kill switch. When disabled the client
     # short-circuits to a no-op before any network call OR validation, so a stray
     # EQUIPOISE_API_KEY in a producer's test env can never make a live call.
     def disabled?
       !enabled
     end
 
-    # — Claude authored — explicit assignment wins; otherwise read ENV each call
+    # Explicit assignment wins; otherwise read ENV each call
     # (rotation-aware).
     def api_key
       resolve(@api_key, "EQUIPOISE_API_KEY")
@@ -80,6 +105,32 @@ module Equipoise
       resolve(@source, "EQUIPOISE_SOURCE")
     end
 
+    # Clamped transport knobs. Each override is bounded to a
+    # hard range (see *_BOUNDS) so a producer's config can never make the gem a
+    # bad citizen to the receiver. An out-of-range value is clamped (and logged,
+    # if a logger is set) rather than raised, so a stray setting degrades to
+    # "safe" instead of crashing the producer's boot. read_timeout takes
+    # fractional seconds; the count knobs are whole numbers.
+    def read_timeout=(seconds)
+      @read_timeout = clamp_to(:read_timeout, seconds.to_f, READ_TIMEOUT_BOUNDS)
+    end
+
+    def max_retries=(count)
+      @max_retries = clamp_to(:max_retries, count.to_i, MAX_RETRIES_BOUNDS)
+    end
+
+    def batch_size=(size)
+      @batch_size = clamp_to(:batch_size, size.to_i, BATCH_SIZE_BOUNDS)
+    end
+
+    # The effective per-request chunk size: an explicit
+    # `batch_sync(chunk_size:)` wins, else the configured batch_size — but either
+    # way clamped to the receiver's hard cap so the gem never posts an oversized
+    # (and rejected) batch.
+    def bounded_batch_size(requested = nil)
+      clamp_to(:batch_size, (requested || batch_size).to_i, BATCH_SIZE_BOUNDS)
+    end
+
     def validate!
       raise ConfigurationError, "api_key is required (set EQUIPOISE_API_KEY or Equipoise.configure)" if api_key.to_s.empty?
       raise ConfigurationError, "base_url is required" if base_url.to_s.empty?
@@ -91,6 +142,17 @@ module Equipoise
 
     private
 
+    # Clamp a knob into its hard range; warn (never raise) so
+    # a misconfigured value is corrected in place instead of failing the
+    # producer's boot. A logger is optional, so the warning is best-effort.
+    def clamp_to(name, value, range)
+      bounded = value.clamp(range.min, range.max)
+      if bounded != value
+        logger&.warn("[equipoise] #{name}=#{value} is outside #{range.min}..#{range.max}; clamped to #{bounded}")
+      end
+      bounded
+    end
+
     def resolve(explicit, env_key)
       return explicit unless explicit.to_s.empty?
 
@@ -98,7 +160,7 @@ module Equipoise
       value.to_s.empty? ? nil : value
     end
 
-    # — Claude authored — never transmit the Bearer key in cleartext to a remote
+    # Never transmit the Bearer key in cleartext to a remote
     # host. https is always fine; http is allowed only for loopback dev or when
     # the producer explicitly opts in for a trusted internal endpoint.
     def ensure_secure_transport!
@@ -112,7 +174,7 @@ module Equipoise
             "Use https://, or set config.allow_insecure_http = true for a trusted internal endpoint."
     end
 
-    # — Claude authored (#3) — the key prefix encodes its environment (eq_test_ /
+    # The key prefix encodes its environment (eq_test_ /
     # eq_live_); refuse the dangerous host mismatches no producer can see coming:
     # a TEST key pointed at the production host (test creds writing the real CRM)
     # or a LIVE key pointed at localhost (prod creds in a dev loop). Staging and

data/lib/equipoise/contacts.rb

@@ -20,13 +20,15 @@
 
 module Equipoise
   class Contacts
-    BATCH_LIMIT = 500
+    # The receiver's hard per-batch cap. Kept for back-compat; the effective
+    # chunk size now comes from config.batch_size (clamped to this).
+    BATCH_LIMIT = Configuration::BATCH_SIZE_BOUNDS.max # 500
 
     def initialize(client)
       @client = client
     end
 
-    # — Claude authored — upsert one contact by (source, external_id). Unknown
+    # Upsert one contact by (source, external_id). Unknown
     # attributes (email/name/first_name/last_name/phone/tags/custom_fields/
     # create_missing_fields) pass straight through; nils are dropped.
     def sync(external_id:, source: nil, idempotency_key: nil, **attributes)
@@ -38,35 +40,40 @@ module Equipoise
       @client.request(:post, "/contacts/sync", body: payload, headers: headers)
     end
 
-    # — Claude authored — upsert many contacts. Chunks to ≤500/call and returns a
-    # BatchResult aggregating every per-item result across chunks. It NEVER raises
+    # Upsert many contacts. Chunks to the configured
+    # batch_size (default 500, hard-capped at the receiver's per-batch limit) and
+    # returns a BatchResult aggregating every per-item result across chunks. Pass
+    # chunk_size: to override per call — it is clamped to the same hard cap, so a
+    # caller can never post an oversized (and rejected) batch. It NEVER raises
     # mid-batch: a per-item server rejection comes back as an `ok: false` item
     # (the receiver returns 200 per chunk), and a chunk-level transport/HTTP
     # failure marks that chunk's records failed so earlier chunks' successes are
     # preserved and the producer can retry only the failures.
-    def batch_sync(records, source: nil, chunk_size: BATCH_LIMIT)
-      default_source = source || @client.config.source
+    def batch_sync(records, source: nil, chunk_size: nil)
+      config         = @client.config
+      default_source = source || config.source
       prepared       = records.map { |record| prepare_record(record, default_source) }
       ensure_sources!(prepared)
 
-      items = []
-      prepared.each_slice(chunk_size) { |chunk| items.concat(sync_chunk(chunk)) }
+      slice_size = config.bounded_batch_size(chunk_size)
+      items      = []
+      prepared.each_slice(slice_size) { |chunk| items.concat(sync_chunk(chunk)) }
       BatchResult.new(items)
     end
 
-    # — Claude authored — deactivate the external link; the Contact is retained.
+    # Deactivate the external link; the Contact is retained.
     def deactivate(external_id:, source: nil)
       @client.request(:post, "#{sync_path(external_id)}/deactivate",
                       query: { source: resolve_source(source) })
     end
 
-    # — Claude authored — read back the Contact linked to (source, external_id).
+    # Read back the Contact linked to (source, external_id).
     def find(external_id:, source: nil)
       @client.request(:get, sync_path(external_id),
                       query: { source: resolve_source(source) })
     end
 
-    # — Claude authored — record an external event on the contact's timeline.
+    # Record an external event on the contact's timeline.
     # `event_type: "subscribed"`/`"unsubscribed"` toggles the contact's email
     # subscription (state + activity); any other event_type logs a generic
     # timeline event. `metadata` is a free-form hash of producer context.

data/lib/equipoise/custom_fields.rb

@@ -32,7 +32,7 @@ module Equipoise
       @client.request(:get, field_path(key), query: query)
     end
 
-    # — Claude authored — create-or-update a field by key (server returns 201 vs
+    # Create-or-update a field by key (server returns 201 vs
     # 200). `customizable_type` from the body is ignored server-side (defaults to
     # Contact); a client can't declare fields on arbitrary owner types.
     def declare(key:, **attributes)

data/lib/equipoise/errors.rb

@@ -25,7 +25,7 @@
 
 module Equipoise
   class Error < StandardError
-    # — Claude authored — the retry taxonomy lives in the gem so no producer has
+    # The retry taxonomy lives in the gem so no producer has
     # to memorize which failures are transient. Base default: not retryable.
     # A producer's job becomes: `rescue Equipoise::Error => e; raise if e.retryable?`.
     def retryable?
@@ -59,7 +59,7 @@ module Equipoise
       status == 429 || status.to_i >= 500
     end
 
-    # — Claude authored — pick the subclass by HTTP status and parse the error
+    # Pick the subclass by HTTP status and parse the error
     # envelope. Robust to an empty body (401) and the legacy string error body.
     def self.from_response(response)
       status  = response.status

data/lib/equipoise/syncable.rb

@@ -26,7 +26,7 @@
 # (override `equipoise_sync!` to enqueue) so a web request never blocks on the
 # round-trip. In dev, ensure the queue runs inline or the post never fires.
 #
-# Producer-side firing is exercised in AMP (S13); the gem suite tests the
+# Producer-side firing is exercised in AMP; the gem suite tests the
 # transport methods directly.
 #
 # Used by: producer models that opt in (e.g. AMP's User)

data/lib/equipoise/util.rb

@@ -14,7 +14,7 @@ module Equipoise
   module Util
     module_function
 
-    # — Claude authored — shallow string→symbol key transform; passes non-Hash
+    # Shallow string→symbol key transform; passes non-Hash
     # input through untouched.
     def symbolize_keys(hash)
       return hash unless hash.is_a?(Hash)

data/lib/equipoise/version.rb

@@ -3,10 +3,9 @@
 # =============================================================================
 #
 # Single source of truth for the gem version, read by the gemspec and exposed
-# at runtime. Pre-1.0 while the gem is proven against AMP before any public
-# RubyGems publish.
+# at runtime.
 # =============================================================================
 
 module Equipoise
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/equipoise.rb

@@ -16,8 +16,7 @@
 #
 #   Equipoise.client.contacts.sync(external_id: user.id, email: user.email, name: user.name, tags: ["AMP"])
 #
-# Contract: documentation/integrations/EXTERNAL_CRM_SYNC_API.openapi.yaml
-# Guide:    documentation/integrations/EXTERNAL_CRM_SYNC.md
+# API contract and integration guide: https://app.equipoi.se
 # =============================================================================
 
 require "json"
@@ -40,7 +39,7 @@ require "equipoise/custom_fields"
 
 module Equipoise
   class << self
-    # — Claude (External CRM Sync, S12): the process-wide configuration. Built
+    # The process-wide configuration. Built
     # lazily from ENV so a bare `require "equipoise"` is side-effect-free.
     def configuration
       @configuration ||= Configuration.new
@@ -52,7 +51,7 @@ module Equipoise
       configuration
     end
 
-    # — Claude authored — memoized default client. Most callers use this; tests
+    # Memoized default client. Most callers use this; tests
     # and multi-tenant producers build their own Client with an explicit config.
     def client
       @client ||= Client.new(configuration)
@@ -62,7 +61,7 @@ module Equipoise
       !configuration.api_key.to_s.empty?
     end
 
-    # — Claude authored (#5) — test-mode kill switch. Put `Equipoise.disable!` in
+    # Test-mode kill switch. Put `Equipoise.disable!` in
     # a producer's rails_helper (or set test env) so no spec can make a live call
     # even if EQUIPOISE_API_KEY leaks into the environment. Calls become no-ops
     # returning a benign Response.
@@ -78,7 +77,7 @@ module Equipoise
       configuration.disabled?
     end
 
-    # — Claude authored — reset global state (used by the test suite's before
+    # Reset global state (used by the test suite's before
     # hook; also handy in a console).
     def reset!
       @configuration = nil

data/lib/generators/equipoise/templates/equipoise.rb

@@ -6,7 +6,7 @@
 #
 # Generated by `rails g equipoise:install`. Reads credentials from the
 # environment so secrets stay out of source control and key rotation needs no
-# redeploy. See documentation/integrations/EXTERNAL_CRM_SYNC.md.
+# redeploy. See https://app.equipoi.se for the API guide.
 
 Equipoise.configure do |config|
   # api_key and base_url are read from EQUIPOISE_API_KEY / EQUIPOISE_API_URL
@@ -17,6 +17,14 @@ Equipoise.configure do |config|
 
   # config.base_url           = "https://app.equipoi.se/api/v1" # override only if needed
   # config.logger             = Rails.logger                    # logs retries + failures
-  # config.max_retries        = 2
+  #
+  # Transport knobs — tunable, but clamped to hard ranges so the gem stays a good
+  # citizen to the receiver no matter what you set (out-of-range → clamped + logged):
+  # config.read_timeout       = 30   # seconds per request; clamped to 5..120. Raise
+  #                                  #   it further for large batch_sync backfills so
+  #                                  #   a slow batch never times out and gets re-sent.
+  # config.max_retries        = 2    # retries on transient failures; clamped to 0..5
+  # config.batch_size         = 500  # contacts per batch_sync request; clamped to 1..500
+  #
   # config.allow_insecure_http = true                           # trusted internal HTTP endpoint
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: equipoise
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Equipoise
@@ -84,7 +84,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby client for the Equipoise External CRM Sync API.
 test_files: []