wefunder 0.1.0.beta2 → 0.1.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 946ede1e59f03277730fa442f9df079e44bac9532db1587306f488d1d8c0a616
-  data.tar.gz: 53ca111474c48a0e954a690caa7001b34cad1c28cd9ba2e275d2489e5f3a235c
+  metadata.gz: 5debc49eda9f51f36042922d2fa820f891d2c847e20f83409d7e61fa1ff2e95a
+  data.tar.gz: d8f9889dc16fb317efd3900b5dafc881807e60a4822b4dcab8a7ded46a2f4d39
 SHA512:
-  metadata.gz: 96cafc3351d195aae306c22a512d0ae1ea7613b2a0d7ffdc843cfc2c37614006effae50197c38c175020ecee6145140e2271f5c26355b39a53eac7a2636626c4
-  data.tar.gz: 381a50ca34d2084e923b4336e4d39b7d6403ad6f2c15feb03602493d0ab1ad3ebf88123bf5bf86cb75bab1a718f7709f00e4b7d8d79b1ac34973e7d22fe1ef3e
+  metadata.gz: 9b7c81d6afb161eacc9a727aaa4bcca3720a6b6bc77e3c8efc332ac594e5e35581680d4ad847c6dd6fb3df5d7382eb2149fcff0f072e0b75d189b96281cee6bc
+  data.tar.gz: 85613d6d2be67d40039f2a9a953682ee180d45811076f4e477629f9a2effce804274e1726c4bbf098b1d8d59ef7fc4fbf5a9fab358a1d656c23088265ea1ff87

data/README.md

@@ -84,10 +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.
+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
@@ -102,8 +103,12 @@ 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, and `Time` / `DateTime` / `Date` values are sent as ISO 8601.
+`attribution`, `installations`, and `webhook_endpoints`. Query parameters are keyword arguments;
+enum-typed ones take plain strings, and `Time` / `DateTime` / `Date` values are sent as ISO 8601.
+
+`wf.installations` lets your app act as a company or syndicate: `eligible_targets`, `create`,
+`mint_token`, `list`, `get`, `revoke`, and `install_or_mint_token`, which handles the API's 409
+`already_installed` answer by minting a token for the existing install with the same scopes.
 
 `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.
@@ -229,10 +234,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

@@ -26,7 +26,7 @@ module Wefunder
   # typed-error unwrapping, and lazy auto-pagination. +raw+ exposes every generated API.
   class Client
     attr_reader :mode, :users, :offerings, :investments, :portfolio, :campaigns, :syndicates, :intents,
-                :attribution, :webhook_endpoints
+                :attribution, :installations, :webhook_endpoints
 
     def initialize(access_token: nil, tokens: nil, client_id: nil, client_secret: nil, client_credentials: nil,
                    api_version: DEFAULT_API_VERSION, base_url: DEFAULT_API_BASE_URL, authorize_base_url: nil,
@@ -53,6 +53,7 @@ module Wefunder
       @syndicates = Syndicates.new(self)
       @intents = Intents.new(self)
       @attribution = Attribution.new(self)
+      @installations = Installations.new(self)
       @webhook_endpoints = WebhookEndpoints.new(self)
     end
 
@@ -70,6 +71,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
@@ -272,6 +276,58 @@ module Wefunder
       def me = data_of(wrap { raw.attribution_partners.get_attribution_me })
     end
 
+    # /installations (read:installations / write:installations; write does not imply read). An
+    # install lets your app act AS a company or syndicate: +create+ and +mint_token+ return the
+    # envelope whose +token.access_token+ is a company-owned token (shown once, no expiry, no
+    # refresh) — build a second client with it. Installing is also what makes a company or
+    # syndicate an audience for your webhooks.
+    class Installations < Namespace
+      # Companies / syndicates the token's user may install your app on (empty for an investor).
+      def eligible_targets(target_type: nil)
+        opts = target_type ? { target_type: target_type } : {}
+        data_of(wrap { raw.installations.list_eligible_install_targets(opts) }) || []
+      end
+
+      # Every install of your app; the envelope (+meta.count+).
+      def list = wrap { raw.installations.list_installations }
+      def get(installation_id) = data_of(wrap { raw.installations.get_installation(installation_id) })
+
+      # Install on a target (+target_type:+, +target_id:+, optional +scopes:+ / +tier:+). Returns the
+      # envelope: +data+ is the install, +token.access_token+ the one-time token. If the app is
+      # already installed there the API answers 409 +already_installed+ with
+      # +details["installation"]+ = the existing id; see +install_or_mint_token+.
+      def create(**attrs)
+        attrs = attrs.transform_keys(&:to_sym)
+        wrap { raw.installations.create_installation(WefunderGenerated::CreateInstallationRequest.new(attrs)) }
+      end
+
+      # A fresh company-owned token for an existing install. +scopes+ narrows within the install's
+      # ceiling; omit for the ceiling. An explicit +[]+ grants nothing, so only nil omits the body.
+      def mint_token(installation_id, scopes = nil)
+        opts = {}
+        opts[:create_installation_token_request] = WefunderGenerated::CreateInstallationTokenRequest.new(scopes: scopes) if scopes
+        wrap { raw.installations.create_installation_token(installation_id, opts) }
+      end
+
+      # +create+, falling back to +mint_token+ for the existing install on 409 +already_installed+.
+      # The mint re-requests +scopes+ so a retry never widens the grant. Any other error (revoked
+      # install, missing scope) still raises.
+      def install_or_mint_token(**attrs)
+        # Normalize once so the fallback re-requests exactly what create sent — string-keyed
+        # attrs (e.g. from JSON.parse) must not turn a restricted or empty grant into the ceiling.
+        attrs = attrs.transform_keys(&:to_sym)
+        create(**attrs)
+      rescue Wefunder::Error => e
+        existing_id = e.details["installation"] if e.type == "already_installed" && e.details.is_a?(Hash)
+        raise unless existing_id.is_a?(String) && !existing_id.empty?
+
+        mint_token(existing_id, attrs[:scopes])
+      end
+
+      # Revoke an install: its tokens stop working at once. Returns the install, now +revoked+.
+      def revoke(installation_id) = data_of(wrap { raw.installations.revoke_installation(installation_id) })
+    end
+
     # Endpoints belong to your application and are managed through the LIVE API
     # (write:webhooks). The signing secret is returned only on create and rotate.
     class WebhookEndpoints < Namespace

data/lib/wefunder/token_manager.rb

@@ -8,8 +8,10 @@ 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.
+  # 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
 
@@ -22,7 +24,9 @@ module Wefunder
   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,
@@ -46,16 +50,35 @@ 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
@@ -71,26 +94,35 @@ module Wefunder
           else
             raise AuthError, "Access token expired and no refresh token / re-mint capability is configured."
           end
-        persist(nxt)
-        @current = nxt
-        @on_token_refresh&.call(nxt)
-        nxt
+        @pending_tokens = nxt
+        publish_pending!
       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
+    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
-      raise TokenPersistenceError.new(tokens, e)
+      tokens
     end
 
-    private
+    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?

data/lib/wefunder/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wefunder
 version: !ruby/object:Gem::Version
-  version: 0.1.0.beta2
+  version: 0.1.0.beta4
 platform: ruby
 authors:
 - Wefunder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday