wefunder 0.1.0.beta1 → 0.1.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8074f860a3e500b08ddab7a4fa3f7ebecb0ec937926aa52884e666243c310715
-  data.tar.gz: 22dfeff5e30c9aaa4e1def2805eab0c33795d53b69140518b364ed878b257d5c
+  metadata.gz: 946ede1e59f03277730fa442f9df079e44bac9532db1587306f488d1d8c0a616
+  data.tar.gz: 53ca111474c48a0e954a690caa7001b34cad1c28cd9ba2e275d2489e5f3a235c
 SHA512:
-  metadata.gz: ad2bc61f75b11d9d1164b81e4d5232f82478a28557ba018f6a7c922f4af5a451e690c05fdcbc9537a1013ea43e9f1328476252ff2f1e14ab3abcde0d48969ccc
-  data.tar.gz: 7dfd26d68fd440c078f8a0f2c5db20fe8fd44c523e85230b86f4bb83eec571f9217185fd61b70a3560f8a6d1c86a1c2fd4de3e58368e0310a32769e108fa3672
+  metadata.gz: 96cafc3351d195aae306c22a512d0ae1ea7613b2a0d7ffdc843cfc2c37614006effae50197c38c175020ecee6145140e2271f5c26355b39a53eac7a2636626c4
+  data.tar.gz: 381a50ca34d2084e923b4336e4d39b7d6403ad6f2c15feb03602493d0ab1ad3ebf88123bf5bf86cb75bab1a718f7709f00e4b7d8d79b1ac34973e7d22fe1ef3e

data/README.md

@@ -84,6 +84,11 @@ class TokenStore
 end
 ```
 
+The rotated set is saved **before** any thread can use it. If `store.save` raises, the SDK still
+switches to the new set in memory (the old refresh token is already dead) and raises
+`Wefunder::TokenPersistenceError`, whose `tokens` is the set that is live but not durable. Alert on it
+and retry the save; do not swallow it, or a restart will not be able to reconnect.
+
 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 +103,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 +141,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
 

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
@@ -88,7 +91,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 +100,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 +127,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 +192,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 +208,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 +218,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 +226,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 +238,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 +261,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,6 +8,17 @@ 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 set that
+  # is now live in memory but NOT durable; +cause+ is the store's exception.
+  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
 
@@ -15,7 +26,7 @@ module Wefunder
 
     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 +34,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)
@@ -50,7 +62,7 @@ module Wefunder
         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,13 +71,25 @@ module Wefunder
           else
             raise AuthError, "Access token expired and no refresh token / re-mint capability is configured."
           end
+        persist(nxt)
         @current = nxt
-        @store&.save(nxt)
         @on_token_refresh&.call(nxt)
         nxt
       end
     end
 
+    # Persist BEFORE publishing: no other 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. If the store raises we still have the only copy of the rotated refresh
+    # token (the old one is dead), so it is published anyway and the failure is surfaced as
+    # TokenPersistenceError — handle it (alert, retry the save with +error.tokens+), don't swallow it.
+    def persist(tokens)
+      @store&.save(tokens)
+    rescue StandardError => e
+      @current = tokens
+      raise TokenPersistenceError.new(tokens, e)
+    end
+
     private
 
     def can_rotate?

data/lib/wefunder/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Wefunder
-  VERSION = "0.1.0.beta1"
+  VERSION = "0.1.0.beta2"
 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.beta2
 platform: ruby
 authors:
 - Wefunder