wefunder 0.1.0.beta1 → 0.1.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8074f860a3e500b08ddab7a4fa3f7ebecb0ec937926aa52884e666243c310715
-  data.tar.gz: 22dfeff5e30c9aaa4e1def2805eab0c33795d53b69140518b364ed878b257d5c
+  metadata.gz: a3ac10a62a698ee6cb163f3ec6e100248d461dc6c55bf97caeb1bac349b44af6
+  data.tar.gz: 26d0e08433a88d288942da627f8d509ffa196e6e2ed3cc347bae43beadaf84bf
 SHA512:
-  metadata.gz: ad2bc61f75b11d9d1164b81e4d5232f82478a28557ba018f6a7c922f4af5a451e690c05fdcbc9537a1013ea43e9f1328476252ff2f1e14ab3abcde0d48969ccc
-  data.tar.gz: 7dfd26d68fd440c078f8a0f2c5db20fe8fd44c523e85230b86f4bb83eec571f9217185fd61b70a3560f8a6d1c86a1c2fd4de3e58368e0310a32769e108fa3672
+  metadata.gz: 4ee97ef8052e3e7a9476a8b0243b52a706bfd2c6a5911e1b9362c07e5d5d6290529615ed6daace3d953769d126a492440692ebef5191cd7846c418a70f6a54b5
+  data.tar.gz: 535800baceafa25b8fcb744d2a1fc16a0596e14d80db5fba6f0c83772ee371c16a361335f82819b5a5e664bf016d17b008d3ff46a3f07f527eab491d8aa36bdd

data/README.md

@@ -84,6 +84,12 @@ class TokenStore
 end
 ```
 
+The rotated set is saved **before** any thread can use it. If `store.save` or `on_token_refresh` raises, the SDK raises
+`Wefunder::TokenPersistenceError` and keeps the rotated set *pending*: no request is made with it, the
+consumed refresh token is never reused, and the next call retries the save (or persist
+`error.tokens` yourself and call `wf.token_manager.mark_persisted!(error.tokens)`; a stale acknowledgment after another rotation is a no-op). Alert on this error; a process
+that keeps failing to save cannot reconnect after a restart.
+
 Concurrent requests that hit a 401 at the same time share one refresh (the client is thread-safe).
 If several application instances can use the same OAuth connection, serialize refreshes for that
 connection yourself.
@@ -98,7 +104,7 @@ portfolio = wf.portfolio.get
 
 Namespaces: `users`, `offerings`, `investments`, `portfolio`, `campaigns`, `syndicates`, `intents`,
 `attribution`, and `webhook_endpoints`. Query parameters are keyword arguments; enum-typed ones take
-plain strings.
+plain strings, and `Time` / `DateTime` / `Date` values are sent as ISO 8601.
 
 `wf.investments` is the Investment Delta API. `list` without a cursor bootstraps; pass `updated_since:`
 or the `meta.next_cursor` you saved from your last page to receive only records that changed since then.
@@ -136,7 +142,11 @@ end
 
 The SDK retries idempotent `GET` requests after transient network errors, `5xx` responses, and rate
 limits (honouring `X-RateLimit-Reset`). Write requests are not retried automatically, except once after
-a `401` has been recovered.
+a `401` has been recovered. Exhausted network failures raise `Wefunder::Error` with `status` 0 and
+`type` `"network_error"`, from namespaces and `request` alike.
+
+`timeout:` (seconds, default 30) applies to every request the client makes: API calls, `request`, and
+the OAuth token round-trips for refresh and re-mint.
 
 ## Webhooks
 
@@ -220,10 +230,13 @@ sends a fully-wrapped request and returns the decoded JSON.
 ```bash
 bundle install
 bundle exec rubocop
-bundle exec rspec                 # hermetic; spec/e2e is excluded by rake and CI on PRs
-bundle exec rspec spec/e2e        # live sandbox, with WEFUNDER_CLIENT_ID / WEFUNDER_CLIENT_SECRET
+bundle exec rspec                             # hermetic — live examples are tagged :e2e and filtered out
+WEFUNDER_E2E=1 bundle exec rspec spec/e2e     # live sandbox; also needs WEFUNDER_CLIENT_ID / WEFUNDER_CLIENT_SECRET
 ```
 
+The live group is opt-in by tag, not by path: without `WEFUNDER_E2E=1` it never runs, even when sandbox
+credentials happen to be exported in your shell.
+
 Generated files in `lib/wefunder_generated/` come from `openapi/openapi.yaml` via `script/generate`
 (openapi-generator in Docker; no Java needed) and are never edited by hand.
 

data/lib/wefunder/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "time"
 require "uri"
 require "faraday"
 
@@ -36,11 +37,12 @@ module Wefunder
 
       _ = authorize_base_url # only /authorize uses it; see OAuth.create_authorization_url
       @mode = Wefunder.mode_for_token(token_set.access_token)
+      @timeout = timeout
       token_base = OAuth.resolve_token_base(token_base_url: token_base_url, oauth_base_url: oauth_base_url)
-      re_mint = build_re_mint(client_credentials, client_id, client_secret, token_base, faraday, now)
+      re_mint = build_re_mint(client_credentials, client_id, client_secret, token_base, faraday, now, timeout)
       @token_manager = TokenManager.new(token_set, client_id: client_id, client_secret: client_secret, re_mint: re_mint,
                                                    on_token_refresh: on_token_refresh, store: store, faraday: faraday, now: now,
-                                                   token_base_url: token_base)
+                                                   token_base_url: token_base, timeout: timeout)
       @api_client = build_api_client(base_url, api_version, retry_options, faraday, now, sleep, random, timeout)
       @raw = Raw.new(@api_client)
       @users = Users.new(self)
@@ -59,7 +61,8 @@ module Wefunder
     def self.from_client_credentials(client_id:, client_secret:, scopes: nil, **opts)
       tokens = OAuth.client_credentials_grant(
         client_id: client_id, client_secret: client_secret, scopes: scopes,
-        token_base_url: opts[:token_base_url], oauth_base_url: opts[:oauth_base_url], faraday: opts[:faraday], now: opts[:now]
+        token_base_url: opts[:token_base_url], oauth_base_url: opts[:oauth_base_url], faraday: opts[:faraday], now: opts[:now],
+        timeout: opts.fetch(:timeout, 30)
       )
       new(tokens: tokens, client_id: client_id, client_secret: client_secret, client_credentials: { scopes: scopes }, **opts)
     end
@@ -67,6 +70,9 @@ module Wefunder
     # The current token set (rotated refresh token included).
     def tokens = @token_manager.current
 
+    # The TokenManager (for +mark_persisted!+ after handling a TokenPersistenceError).
+    attr_reader :token_manager
+
     # The generated APIs, one accessor per tag (+wf.raw.syndicate_members.list_syndicate_members(id)+).
     # Wrap calls in +wrap+ to get typed errors.
     attr_reader :raw
@@ -88,7 +94,8 @@ module Wefunder
       payload = body.nil? || body.is_a?(String) ? body : JSON.generate(body)
       hdrs = @api_client.default_headers.merge(headers || {})
       response = conn.run_request(method.to_s.downcase.to_sym, path, payload, hdrs) do |req|
-        req.params.update((query || {}).compact.transform_keys(&:to_s))
+        req.options.timeout = @timeout if @timeout # same timeout as the generated calls
+        req.params.update(Client.normalize_params((query || {}).compact).transform_keys(&:to_s))
       end
       if response.status >= 400
         raise Error.from_response(response.status, response.headers, response.body,
@@ -96,6 +103,22 @@ module Wefunder
       end
 
       response.body.to_s.empty? ? nil : JSON.parse(response.body)
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError => e
+      # Same shape the generated calls produce through `wrap` (ApiError with no code).
+      raise Error.new(status: 0, type: "network_error", message: e.message.to_s)
+    end
+
+    # Query values the API wants as ISO 8601: Time / DateTime → +iso8601+, Date → +YYYY-MM-DD+.
+    # Faraday would otherwise serialize a Time with +to_s+ ("2026-09-01 00:00:00 UTC"), which
+    # the server rejects with 400.
+    def self.normalize_params(opts)
+      opts.transform_values do |v|
+        case v
+        when Date then v.iso8601 # Date and DateTime (DateTime < Date)
+        when Time then v.utc.iso8601
+        else v
+        end
+      end
     end
 
     # Single-resource envelopes are +{data: Entity}+; return the entity for ergonomics.
@@ -107,13 +130,13 @@ module Wefunder
 
     private
 
-    def build_re_mint(client_credentials, client_id, client_secret, token_base, faraday, now)
+    def build_re_mint(client_credentials, client_id, client_secret, token_base, faraday, now, timeout)
       return nil unless client_credentials && client_id && client_secret
 
       scopes = client_credentials[:scopes] || client_credentials["scopes"]
       lambda do
         OAuth.client_credentials_grant(client_id: client_id, client_secret: client_secret, scopes: scopes,
-                                       token_base_url: token_base, faraday: faraday, now: now)
+                                       token_base_url: token_base, faraday: faraday, now: now, timeout: timeout)
       end
     end
 
@@ -172,9 +195,11 @@ module Wefunder
       def wrap(&) = @client.wrap(&)
       def raw = @client.raw
       def data_of(env) = Client.data_of(env)
+      def norm(opts) = Client.normalize_params(opts)
 
       # Auto-paginate a list method, keeping +opts+ on every page and threading the cursor.
       def pages(opts, &fetch)
+        opts = norm(opts)
         Wefunder.paginate { |cursor| wrap { fetch.call(cursor.nil? ? opts : opts.merge(cursor: cursor)) } }
       end
     end
@@ -186,7 +211,7 @@ module Wefunder
 
     class Offerings < Namespace
       # One page of GET /explore (+sort:+, +cursor:+, filters). Returns the envelope.
-      def list(**opts) = wrap { raw.explore.list_offerings(opts) }
+      def list(**opts) = wrap { raw.explore.list_offerings(norm(opts)) }
       # Every offering, lazily, +opts+ preserved across pages.
       def all(**opts) = pages(opts) { |o| raw.explore.list_offerings(o) }
       def get(offering_id) = data_of(wrap { raw.explore.get_offering(offering_id) })
@@ -196,7 +221,7 @@ module Wefunder
     # The Investment Delta API. +list+ without a cursor bootstraps; +next_cursor+ is always
     # present (persist it after every sync) and +has_more+ terminates.
     class Investments < Namespace
-      def list(**opts) = wrap { raw.investments.list_investments(opts) }
+      def list(**opts) = wrap { raw.investments.list_investments(norm(opts)) }
       def all(**opts) = pages(opts) { |o| raw.investments.list_investments(o) }
       def collect(**) = all(**).to_a
       def get(investment_id) = data_of(wrap { raw.investments.get_investment(investment_id) })
@@ -204,7 +229,7 @@ module Wefunder
 
     class Portfolio < Namespace
       Positions = Class.new(Namespace) do
-        def list(**opts) = wrap { raw.portfolio.list_portfolio_positions(opts) }
+        def list(**opts) = wrap { raw.portfolio.list_portfolio_positions(norm(opts)) }
         def all(**opts) = pages(opts) { |o| raw.portfolio.list_portfolio_positions(o) }
       end
 
@@ -216,19 +241,22 @@ module Wefunder
       end
 
       # The portfolio summary (+status:+, +company:+ filters).
-      def get(**opts) = data_of(wrap { raw.portfolio.get_portfolio(opts) })
+      def get(**opts) = data_of(wrap { raw.portfolio.get_portfolio(norm(opts)) })
     end
 
     class Campaigns < Namespace
-      def list(**opts) = wrap { raw.campaigns.list_campaigns(opts) }
+      def list(**opts) = wrap { raw.campaigns.list_campaigns(norm(opts)) }
       def all(**opts) = pages(opts) { |o| raw.campaigns.list_campaigns(o) }
     end
 
     class Syndicates < Namespace
-      def list(**opts) = wrap { raw.syndicates.list_syndicates(opts) }
+      def list(**opts) = wrap { raw.syndicates.list_syndicates(norm(opts)) }
       def all(**opts) = pages(opts) { |o| raw.syndicates.list_syndicates(o) }
       def get(syndicate_id) = data_of(wrap { raw.syndicates.get_syndicate(syndicate_id) })
-      def portfolio(syndicate_id, **opts) = data_of(wrap { raw.syndicate_portfolio.get_syndicate_portfolio(syndicate_id, opts) })
+
+      def portfolio(syndicate_id, **opts)
+        data_of(wrap { raw.syndicate_portfolio.get_syndicate_portfolio(syndicate_id, norm(opts)) })
+      end
 
       def portfolio_positions(syndicate_id, **opts)
         pages(opts) { |o| raw.syndicate_portfolio.list_syndicate_portfolio_positions(syndicate_id, o) }
@@ -236,7 +264,7 @@ module Wefunder
     end
 
     class Intents < Namespace
-      def list(**opts) = wrap { raw.intents.list_intents(opts) }
+      def list(**opts) = wrap { raw.intents.list_intents(norm(opts)) }
       def all(**opts) = pages(opts) { |o| raw.intents.list_intents(o) }
       def get(intent_id) = data_of(wrap { raw.intents.get_intent(intent_id) })
       def create(body) = data_of(wrap { raw.intents.create_intent(WefunderGenerated::CreateIntentRequest.new(body)) })

data/lib/wefunder/oauth.rb

@@ -93,32 +93,35 @@ module Wefunder
 
     # Exchange an authorization code (+ PKCE verifier) for a token set. Public (PKCE) clients
     # omit +client_secret+; confidential clients pass it.
-    def exchange_code(client_id:, code:, redirect_uri:, code_verifier:, client_secret: nil, faraday: nil, now: nil, **hosts)
+    def exchange_code(client_id:, code:, redirect_uri:, code_verifier:, client_secret: nil, faraday: nil, now: nil, timeout: nil,
+                      **hosts)
       params = { grant_type: "authorization_code", client_id: client_id, code: code, redirect_uri: redirect_uri,
                  code_verifier: code_verifier }
       params[:client_secret] = client_secret if client_secret
-      post_token(resolve_token_base(**hosts), params, faraday, now)
+      post_token(resolve_token_base(**hosts), params, faraday, now, timeout)
     end
 
     # Mint an application token (server-to-server). cc tokens carry no refresh token.
-    def client_credentials_grant(client_id:, client_secret:, scopes: nil, faraday: nil, now: nil, **hosts)
+    def client_credentials_grant(client_id:, client_secret:, scopes: nil, faraday: nil, now: nil, timeout: nil, **hosts)
       params = { grant_type: "client_credentials", client_id: client_id, client_secret: client_secret }
       params[:scope] = Array(scopes).join(" ") if scopes && !Array(scopes).empty?
-      post_token(resolve_token_base(**hosts), params, faraday, now)
+      post_token(resolve_token_base(**hosts), params, faraday, now, timeout)
     end
 
     # Refresh an access token. CRITICAL: the result carries a NEW refresh token (rotation) —
     # persist it. Reusing the old one after rotation is a permanent 401.
-    def refresh_token(client_id:, refresh_token:, client_secret: nil, faraday: nil, now: nil, **hosts)
+    def refresh_token(client_id:, refresh_token:, client_secret: nil, faraday: nil, now: nil, timeout: nil, **hosts)
       params = { grant_type: "refresh_token", client_id: client_id, refresh_token: refresh_token }
       params[:client_secret] = client_secret if client_secret
-      post_token(resolve_token_base(**hosts), params, faraday, now)
+      post_token(resolve_token_base(**hosts), params, faraday, now, timeout)
     end
 
     # +faraday+ is an optional callable that configures the connection (tests inject an
-    # adapter: +->(conn) { conn.adapter :test, stubs }+).
-    def post_token(base, params, faraday, now)
+    # adapter: +->(conn) { conn.adapter :test, stubs }+). +timeout+ (seconds) covers the token
+    # round-trip so refreshes honour the client's timeout like every other call.
+    def post_token(base, params, faraday, now, timeout = nil)
       conn = Faraday.new do |c|
+        c.options.timeout = timeout if timeout
         faraday&.call(c)
         c.adapter Faraday.default_adapter unless faraday
       end

data/lib/wefunder/token_manager.rb

@@ -8,14 +8,29 @@ module Wefunder
   # manager already holds a different one, another caller recovered in the meantime and the
   # current set is returned without a round-trip. The rotated set is persisted (store +
   # callback) BEFORE the retried request can use it. Thread-safe (Mutex).
+  # Raised when the token store failed to save a rotated token set. +tokens+ is the rotated
+  # set that is NOT yet durable and NOT yet in use; the manager keeps it pending and retries
+  # the save on the next call (or persist it yourself and call +mark_persisted!(tokens)+). Until it is
+  # saved no request is made with it — the consumed refresh token is never reused either.
+  class TokenPersistenceError < StandardError
+    attr_reader :tokens
+
+    def initialize(tokens, cause)
+      super("Token store failed to save the rotated token set: #{cause.message}")
+      @tokens = tokens
+    end
+  end
+
   class TokenManager
     DEFAULT_EXPIRY_LEEWAY_SECONDS = 30.0
 
-    attr_reader :current
+    # The durable, in-use token set. A rotated set that could not be persisted is held in
+    # +pending_tokens+ instead until a save succeeds.
+    attr_reader :current, :pending_tokens
 
     def initialize(tokens, client_id: nil, client_secret: nil, re_mint: nil, on_token_refresh: nil, store: nil,
                    faraday: nil, now: nil, expiry_leeway_seconds: DEFAULT_EXPIRY_LEEWAY_SECONDS,
-                   token_base_url: nil, oauth_base_url: nil)
+                   token_base_url: nil, oauth_base_url: nil, timeout: nil)
       @current = tokens
       @client_id = client_id
       @client_secret = client_secret
@@ -23,6 +38,7 @@ module Wefunder
       @on_token_refresh = on_token_refresh
       @store = store
       @faraday = faraday
+      @timeout = timeout
       @now = now || -> { Time.now.to_f }
       @leeway = expiry_leeway_seconds
       @token_base_url = OAuth.resolve_token_base(token_base_url: token_base_url, oauth_base_url: oauth_base_url)
@@ -34,23 +50,42 @@ module Wefunder
       can_rotate? || !@re_mint.nil?
     end
 
-    # A valid access token, refreshing proactively if expired / within the leeway.
+    # A valid access token, refreshing proactively if expired / within the leeway. If a rotated
+    # set is pending persistence, the save is retried first — no request uses an undurable token.
     def access_token
+      @lock.synchronize { publish_pending! if @pending_tokens } if @pending_tokens # re-check under the lock
       refresh(stale_token: @current.access_token) if near_expiry? && can_refresh?
       @current.access_token
     end
 
+    # Tell the manager you persisted +tokens+ (the set from a TokenPersistenceError) yourself.
+    # Publishes it only if it is still the pending set; a stale acknowledgment (the manager has
+    # since rotated again) is a no-op and returns false, so an older save can never publish a
+    # newer, unsaved set.
+    def mark_persisted!(tokens)
+      @lock.synchronize do
+        return false unless @pending_tokens && same_token_set?(@pending_tokens, tokens)
+
+        @current = @pending_tokens
+        @pending_tokens = nil
+        true
+      end
+    end
+
     # Recover the token (after a 401 or proactively). If +stale_token+ is no longer the current
     # token, someone else already recovered and the current set is returned.
     def refresh(stale_token: nil)
       @lock.synchronize do
+        # A rotated set awaiting persistence: retry the save rather than rotating again (the
+        # old refresh token was consumed by that rotation).
+        return publish_pending! if @pending_tokens
         return @current if stale_token && @current.access_token != stale_token
 
         previous_refresh = @current.refresh_token
         nxt =
           if can_rotate?
             set = OAuth.refresh_token(client_id: @client_id, client_secret: @client_secret, refresh_token: previous_refresh,
-                                      token_base_url: @token_base_url, faraday: @faraday, now: @now)
+                                      token_base_url: @token_base_url, faraday: @faraday, now: @now, timeout: @timeout)
             # Some servers omit a fresh refresh_token on rotation-disabled flows; keep the old one.
             set.refresh_token ||= previous_refresh
             set
@@ -59,15 +94,36 @@ module Wefunder
           else
             raise AuthError, "Access token expired and no refresh token / re-mint capability is configured."
           end
-        @current = nxt
-        @store&.save(nxt)
-        @on_token_refresh&.call(nxt)
-        nxt
+        @pending_tokens = nxt
+        publish_pending!
       end
     end
 
     private
 
+    # Persist BEFORE publishing (caller holds the lock): no thread may use the rotated token
+    # until it is durable, and a failed save must not leave the process working in memory but
+    # unable to reconnect after a restart. On failure the set stays in +pending_tokens+ and
+    # TokenPersistenceError is raised; the next call retries the save.
+    def publish_pending!
+      tokens = @pending_tokens
+      begin
+        @store&.save(tokens)
+        # on_token_refresh is a persistence path too, so it runs BEFORE publication and a failure
+        # keeps the set pending exactly like a store failure.
+        @on_token_refresh&.call(tokens)
+      rescue StandardError => e
+        raise TokenPersistenceError.new(tokens, e)
+      end
+      @pending_tokens = nil
+      @current = tokens
+      tokens
+    end
+
+    def same_token_set?(a, b)
+      a.access_token == b.access_token && a.refresh_token == b.refresh_token
+    end
+
     def can_rotate?
       !@current.refresh_token.nil? && !@current.refresh_token.empty? && !@client_id.nil?
     end

data/lib/wefunder/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wefunder
-  VERSION = "0.1.0.beta1"
+  VERSION = "0.1.0.beta3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wefunder
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta1
+  version: 0.1.0.beta3
 platform: ruby
 authors:
 - Wefunder