wefunder 0.1.0.beta1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8074f860a3e500b08ddab7a4fa3f7ebecb0ec937926aa52884e666243c310715
+  data.tar.gz: 22dfeff5e30c9aaa4e1def2805eab0c33795d53b69140518b364ed878b257d5c
+SHA512:
+  metadata.gz: ad2bc61f75b11d9d1164b81e4d5232f82478a28557ba018f6a7c922f4af5a451e690c05fdcbc9537a1013ea43e9f1328476252ff2f1e14ab3abcde0d48969ccc
+  data.tar.gz: 7dfd26d68fd440c078f8a0f2c5db20fe8fd44c523e85230b86f4bb83eec571f9217185fd61b70a3560f8a6d1c86a1c2fd4de3e58368e0310a32769e108fa3672

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wefunder, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,263 @@
+# wefunder
+
+Official Ruby SDK for the [Wefunder API](https://docs.wefunder.com). **Beta** — the API is pre-launch
+and `0.x` releases may include breaking changes.
+
+- A `Wefunder::Client` on [Faraday](https://lostisland.github.io/faraday/) with a generated, typed
+  layer for every public operation
+- OAuth 2.0: `client_credentials` for server-to-server, `authorization_code` + PKCE for user consent,
+  refresh-token rotation handled for you
+- Automatic retries (rate limits, transient errors) and one-shot token recovery on 401
+- Lazy auto-pagination over opaque cursors
+- Typed errors with the `request_id` support asks for
+- Webhook signature verification, envelope parsing, and dispatch
+
+Requires Ruby 3.2+.
+
+## Install
+
+```bash
+gem install wefunder --pre
+# or in a Gemfile:
+gem "wefunder", "~> 0.1.0.beta"
+```
+
+`--pre` is needed while the SDK is in beta (pre-release gems are not selected by default).
+
+## Authentication
+
+### Server-to-server
+
+```ruby
+require "wefunder"
+
+wf = Wefunder::Client.from_client_credentials(
+  client_id: ENV.fetch("WEFUNDER_CLIENT_ID"),
+  client_secret: ENV.fetch("WEFUNDER_CLIENT_SECRET"),
+  scopes: ["read:public"]
+)
+page = wf.offerings.list
+```
+
+Client-credentials tokens represent the application, not a user. They cannot call user-scoped
+endpoints such as `wf.users.me` or `wf.portfolio.get`. The SDK mints a new token automatically when a
+client-credentials token expires.
+
+### User authorization with PKCE
+
+Generate the authorization URL on your server; store `state` and the PKCE verifier in the user's
+session before redirecting:
+
+```ruby
+pkce = Wefunder.generate_pkce
+state = SecureRandom.urlsafe_base64(32)
+save_oauth_attempt(state: state, code_verifier: pkce.code_verifier)
+
+url = Wefunder.create_authorization_url(
+  client_id: client_id, redirect_uri: redirect_uri, scopes: ["read:investments"], state: state, pkce: pkce
+)
+```
+
+The consent host is chosen from the `client_id`: `pk_test_` ids go to the sandbox, everything else to
+wefunder.com. On the callback, validate `state` and exchange the code:
+
+```ruby
+attempt = consume_oauth_attempt(state)
+tokens = Wefunder.exchange_code(
+  client_id: client_id, client_secret: client_secret, # omit for public clients
+  code: params[:code], redirect_uri: redirect_uri, code_verifier: attempt.code_verifier
+)
+
+wf = Wefunder::Client.new(tokens: tokens, client_id: client_id, client_secret: client_secret, store: TokenStore.new)
+```
+
+### Refresh tokens
+
+Refresh tokens rotate. When the SDK refreshes an access token it calls `store.save(tokens)` with the
+new set **before** retrying the request. Persist the entire token set each time:
+
+```ruby
+class TokenStore
+  def save(tokens)
+    DB.save_tokens(tokens.access_token, tokens.refresh_token, tokens.expires_at)
+  end
+end
+```
+
+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.
+
+## Calling the API
+
+```ruby
+offerings = wf.offerings.list(sort: "newest")
+investments = wf.investments.list(company_id: "co_example")
+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.
+
+`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.
+`next_cursor` is always present, even on the final page, so persist it after every sync.
+
+The API base URL is `https://api.wefunder.com`. Paths are version-free; the SDK sends the API version in
+the `Wefunder-Version` request header.
+
+## Pagination
+
+```ruby
+page = wf.offerings.list(sort: "newest")           # one page, and its cursor
+puts page.meta.next_cursor
+
+wf.offerings.all(sort: "most_raised").each do |offering|  # every item, lazily (an Enumerator)
+  puts offering.id
+end
+
+investments = wf.investments.collect                # everything in one Array
+```
+
+Cursors are opaque. Pass the value returned by the API without modifying it.
+
+## Errors and retries
+
+API failures raise `Wefunder::Error`:
+
+```ruby
+begin
+  wf.syndicates.get("syn_example")
+rescue Wefunder::Error => e
+  puts e.status, e.type, e.message, e.request_id, e.remediation
+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.
+
+## Webhooks
+
+### 1. Register an endpoint
+
+Endpoints belong to your application and are managed through the live API (scope `write:webhooks`).
+The signing secret is returned only on create and rotate, so store it immediately.
+
+```ruby
+endpoint = wf.webhook_endpoints.create(
+  url: "https://yourapp.com/webhooks/wefunder",  # public HTTPS; localhost and private IPs are rejected
+  events: ["offering.opened", "investment.executed"],
+  mode: "live"                                   # "test" endpoints receive sandbox events
+)
+save_secret(endpoint.attributes.secret)
+```
+
+`wf.webhook_endpoints` also provides `list`, `get`, `update`, `remove`, `rotate_secret`, `reenable`,
+and `test`.
+
+### 2. Verify and handle deliveries
+
+Pass the **raw** request body, the headers (a Rack env works), and your secret to
+`Wefunder.construct_event`. It raises `Wefunder::WebhookSignatureError` (with a `reason`) when a
+delivery is not authentic.
+
+```ruby
+post "/webhooks/wefunder" do
+  begin
+    event = Wefunder.construct_event(request.body.read, request.env, WEBHOOK_SECRET)
+  rescue Wefunder::WebhookSignatureError => e
+    halt 400, e.reason
+  end
+
+  Wefunder.dispatch_webhook(event, {
+    "investment.executed" => ->(e) { record_funding(e.data["id"], e.data.dig("amounts", "committed")) },
+    "offering.opened" => ->(e) { announce(e.data.dig("company", "name")) },
+    default: ->(e) { logger.info("unhandled #{e.event}") }
+  })
+  200
+end
+```
+
+Deliveries are at-least-once and unordered. Deduplicate on `event.id`, and where a payload carries
+`occurred_at`, keep the state from the latest one you have seen.
+
+### 3. Test your handler
+
+`wf.webhook_endpoints.test(endpoint.id)` sends a real, signed example event and reports the outcome.
+To unit-test your handler without the API, sign a fixture yourself:
+
+```ruby
+header = Wefunder.sign_webhook(body, secret)
+# POST `body` to your handler with `Wefunder-Signature: <header>`
+```
+
+### Signature scheme
+
+Each delivery carries `Wefunder-Signature: t=<unix seconds>,v1=<hex>` where `v1` is
+`HMAC-SHA256(secret, "<t>.<raw body>")`. Requests whose `t` is more than five minutes from now are
+rejected (`tolerance_seconds:` adjusts this). During a secret rotation the header carries one `v1` per
+active secret and `construct_event` accepts either. `Wefunder.verify_webhook` and
+`Wefunder.check_webhook_signature` expose the check without parsing, and `construct_event` still accepts
+the retired attribution headers (`X-Wefunder-Signature` / `X-Wefunder-Timestamp`).
+
+## Generated operations
+
+Typed namespaces cover the common resources. Every operation in the public OpenAPI specification is
+generated under `WefunderGenerated::<Tag>Api` and reachable through `wf.raw.<tag>`; wrap the call to get
+the same auth, retries, and typed errors:
+
+```ruby
+members = wf.wrap { wf.raw.syndicate_members.list_syndicate_members("syn_example") }
+```
+
+For a path the generated layer does not know yet, `wf.request(:get, path, query:, body:, headers:)`
+sends a fully-wrapped request and returns the decoded JSON.
+
+## Development
+
+```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
+```
+
+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.
+
+### Conformance vectors
+
+`conformance/*.json` is the cross-language behavioural contract shared with `wefunder-node` and
+`wefunder-python`: signatures, token rotation, pagination, retries, errors. `spec/conformance_spec.rb`
+runs every case. The files are vendored from `Wefunder/wefunder-node` at the ref in `conformance/PIN`;
+refresh with `ruby script/sync_conformance.rb [ref]`. Never edit a vector to make the shell pass.
+
+### Examples
+
+`examples/` is the source of truth for the Ruby snippets on docs.wefunder.com; see
+`examples/README.md`. After adding one, run `ruby script/build_examples_manifest.rb` and remove its
+`operationId` from `examples/coverage-allowlist.json`.
+
+### Updating the API specification
+
+```bash
+script/sync_spec /path/to/wefunder   # public-tier spec → openapi/openapi.yaml
+script/generate                      # → lib/wefunder_generated
+bundle exec rspec
+```
+
+Commit the specification and generated client together.
+
+### Releasing
+
+Set the version in `lib/wefunder/version.rb` (e.g. `0.1.0.beta2`), rebuild `examples_manifest.json`,
+commit, then:
+
+```bash
+git tag v0.1.0.beta2
+git push --follow-tags
+```
+
+The release workflow verifies the tag, runs the checks, and publishes to RubyGems via trusted publishing.

data/lib/wefunder/client.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "faraday"
+
+module Wefunder
+  # Version-free base — the edge gateway serves the API at the host root; +/api/v2+ remains a
+  # back-compat alias. The API version is pinned via the +Wefunder-Version+ header, not the path.
+  DEFAULT_API_BASE_URL = "https://api.wefunder.com"
+  DEFAULT_API_VERSION = "2025-01-15"
+  API_VERSION_HEADER = "Wefunder-Version"
+
+  # "live" / "test" from the access-token prefix. UX only — never used for routing.
+  def self.mode_for_token(token)
+    return "live" if token.to_s.start_with?("at_live_")
+    return "test" if token.to_s.start_with?("at_test_")
+
+    "unknown"
+  end
+
+  # The Wefunder client — the stable, hand-written surface over the generated layer
+  # (+WefunderGenerated+). Wires: a single API host (the gateway routes live/sandbox by token
+  # mode), a pinned +Wefunder-Version+, the retry/refresh transport, token rotation,
+  # 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
+
+    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,
+                   token_base_url: nil, oauth_base_url: nil, store: nil, on_token_refresh: nil, retry_options: nil,
+                   faraday: nil, now: nil, sleep: nil, random: nil, timeout: 30)
+      token_set = tokens || (access_token && TokenSet.new(access_token: access_token))
+      raise ArgumentError, "Wefunder::Client: provide access_token: or tokens:" unless token_set
+
+      _ = authorize_base_url # only /authorize uses it; see OAuth.create_authorization_url
+      @mode = Wefunder.mode_for_token(token_set.access_token)
+      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)
+      @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)
+      @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)
+      @offerings = Offerings.new(self)
+      @investments = Investments.new(self)
+      @portfolio = Portfolio.new(self)
+      @campaigns = Campaigns.new(self)
+      @syndicates = Syndicates.new(self)
+      @intents = Intents.new(self)
+      @attribution = Attribution.new(self)
+      @webhook_endpoints = WebhookEndpoints.new(self)
+    end
+
+    # Mint an application token now and auto-re-mint on expiry/401 (cc tokens have no refresh
+    # token). Extra options are forwarded to +new+.
+    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]
+      )
+      new(tokens: tokens, client_id: client_id, client_secret: client_secret, client_credentials: { scopes: scopes }, **opts)
+    end
+
+    # The current token set (rotated refresh token included).
+    def tokens = @token_manager.current
+
+    # 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
+
+    # Run a block of generated-API calls, converting +WefunderGenerated::ApiError+ into +Wefunder::Error+.
+    def wrap
+      yield
+    rescue WefunderGenerated::ApiError => e
+      raise Error.new(status: 0, type: "network_error", message: e.message.to_s) if e.code.nil? || e.code.zero?
+
+      raise Error.from_response(e.code, e.response_headers, e.response_body, reason_phrase: e.message)
+    end
+
+    # Escape hatch for any path (preview ops, brand-new endpoints): full envelope — auth +
+    # recovery, Wefunder-Version, retries, typed errors. Returns parsed JSON (nil for an empty
+    # body). +body+ is sent as JSON unless it is a String.
+    def request(method, path, query: nil, body: nil, headers: nil)
+      conn = @api_client.connection(header_params: {})
+      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))
+      end
+      if response.status >= 400
+        raise Error.from_response(response.status, response.headers, response.body,
+                                  reason_phrase: response.reason_phrase)
+      end
+
+      response.body.to_s.empty? ? nil : JSON.parse(response.body)
+    end
+
+    # Single-resource envelopes are +{data: Entity}+; return the entity for ergonomics.
+    def self.data_of(envelope)
+      return envelope["data"] || envelope[:data] if envelope.is_a?(Hash)
+
+      envelope.respond_to?(:data) ? envelope.data : envelope
+    end
+
+    private
+
+    def build_re_mint(client_credentials, client_id, client_secret, token_base, faraday, now)
+      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)
+      end
+    end
+
+    def build_api_client(base_url, api_version, retry_opts, faraday, now, sleep, random, timeout)
+      config = WefunderGenerated::Configuration.new
+      uri = URI(base_url)
+      config.scheme = uri.scheme
+      config.host = uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+      config.base_path = uri.path.to_s
+      config.server_index = nil
+      # The transport owns the Authorization header (it reads the managed token per attempt),
+      # so the generated client's own token is a placeholder.
+      config.access_token = "managed"
+      config.timeout = timeout
+      tm = @token_manager
+      now_ms = now && -> { now.call * 1000 }
+      config.configure_faraday_connection do |conn|
+        conn.use Transport, token_manager: tm, retry_options: retry_opts, sleep: sleep, now_ms: now_ms, random: random
+        faraday&.call(conn)
+      end
+      client = WefunderGenerated::ApiClient.new(config)
+      client.default_headers[API_VERSION_HEADER] = api_version
+      client
+    end
+
+    # Lazily-built generated API instances, one per tag.
+    class Raw
+      APIS = {
+        activity: "ActivityApi", attribution: "AttributionApi", attribution_partners: "AttributionPartnersApi",
+        attribution_webhooks: "AttributionWebhooksApi", campaigns: "CampaignsApi", companies: "CompaniesApi",
+        explore: "ExploreApi", installations: "InstallationsApi", intents: "IntentsApi",
+        investment_delta: "InvestmentDeltaApi", investments: "InvestmentsApi", portfolio: "PortfolioApi",
+        syndicate_deals: "SyndicateDealsApi", syndicate_members: "SyndicateMembersApi",
+        syndicate_portfolio: "SyndicatePortfolioApi", syndicate_statistics: "SyndicateStatisticsApi",
+        syndicates: "SyndicatesApi", users: "UsersApi", webhook_endpoints: "WebhookEndpointsApi"
+      }.freeze
+
+      def initialize(api_client)
+        @api_client = api_client
+        @apis = {}
+      end
+
+      APIS.each do |name, klass|
+        define_method(name) { @apis[name] ||= WefunderGenerated.const_get(klass).new(@api_client) }
+      end
+    end
+
+    # Base for the resource namespaces.
+    class Namespace
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      def wrap(&) = @client.wrap(&)
+      def raw = @client.raw
+      def data_of(env) = Client.data_of(env)
+
+      # Auto-paginate a list method, keeping +opts+ on every page and threading the cursor.
+      def pages(opts, &fetch)
+        Wefunder.paginate { |cursor| wrap { fetch.call(cursor.nil? ? opts : opts.merge(cursor: cursor)) } }
+      end
+    end
+
+    class Users < Namespace
+      # GET /users/me (needs read:profile; a client_credentials token gets 403).
+      def me = data_of(wrap { raw.users.get_current_user })
+    end
+
+    class Offerings < Namespace
+      # One page of GET /explore (+sort:+, +cursor:+, filters). Returns the envelope.
+      def list(**opts) = wrap { raw.explore.list_offerings(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) })
+      def stats(offering_id) = data_of(wrap { raw.investments.get_offering_stats(offering_id) })
+    end
+
+    # 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 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) })
+    end
+
+    class Portfolio < Namespace
+      Positions = Class.new(Namespace) do
+        def list(**opts) = wrap { raw.portfolio.list_portfolio_positions(opts) }
+        def all(**opts) = pages(opts) { |o| raw.portfolio.list_portfolio_positions(o) }
+      end
+
+      attr_reader :positions
+
+      def initialize(client)
+        super
+        @positions = Positions.new(client)
+      end
+
+      # The portfolio summary (+status:+, +company:+ filters).
+      def get(**opts) = data_of(wrap { raw.portfolio.get_portfolio(opts) })
+    end
+
+    class Campaigns < Namespace
+      def list(**opts) = wrap { raw.campaigns.list_campaigns(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 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_positions(syndicate_id, **opts)
+        pages(opts) { |o| raw.syndicate_portfolio.list_syndicate_portfolio_positions(syndicate_id, o) }
+      end
+    end
+
+    class Intents < Namespace
+      def list(**opts) = wrap { raw.intents.list_intents(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)) })
+      def preview(body) = data_of(wrap { raw.intents.preview_intent(WefunderGenerated::PreviewIntentRequest.new(body)) })
+    end
+
+    class Attribution < Namespace
+      def me = data_of(wrap { raw.attribution_partners.get_attribution_me })
+    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
+      def create(url:, events:, mode: nil)
+        attrs = { url: url, events: Array(events) }
+        attrs[:mode] = mode if mode
+        data_of(wrap do
+          raw.webhook_endpoints.create_webhook_endpoint(WefunderGenerated::CreateWebhookEndpointRequest.new(attrs))
+        end)
+      end
+
+      # The list envelope (+meta.quota+ is the max endpoints per app).
+      def list = wrap { raw.webhook_endpoints.list_webhook_endpoints }
+      def get(endpoint_id) = data_of(wrap { raw.webhook_endpoints.get_webhook_endpoint(endpoint_id) })
+
+      # +events+ replaces the list wholesale.
+      def update(endpoint_id, **changes)
+        body = WefunderGenerated::UpdateWebhookEndpointRequest.new(changes)
+        data_of(wrap { raw.webhook_endpoints.update_webhook_endpoint(endpoint_id, update_webhook_endpoint_request: body) })
+      end
+
+      def remove(endpoint_id) = data_of(wrap { raw.webhook_endpoints.delete_webhook_endpoint(endpoint_id) })
+      # A new secret; the old one keeps signing for 24h and deliveries carry both v1s.
+      def rotate_secret(endpoint_id) = data_of(wrap { raw.webhook_endpoints.rotate_webhook_endpoint_secret(endpoint_id) })
+      def reenable(endpoint_id) = data_of(wrap { raw.webhook_endpoints.reenable_webhook_endpoint(endpoint_id) })
+
+      # Send a real, signed example event to the endpoint and report the outcome.
+      def test(endpoint_id, event = nil)
+        opts = event ? { test_webhook_endpoint_request: WefunderGenerated::TestWebhookEndpointRequest.new(event: event) } : {}
+        data_of(wrap { raw.webhook_endpoints.test_webhook_endpoint(endpoint_id, opts) })
+      end
+    end
+  end
+end

data/lib/wefunder/errors.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Wefunder
+  # Response header carrying the partner-facing request id (Stripe-style +req_…+).
+  REQUEST_ID_HEADER = "X-Wf-Request-Id"
+  # +type+ reported when the body is not the documented envelope.
+  FALLBACK_ERROR_TYPE = "api_error"
+
+  # An API call failed. Mapped from the REAL error envelope
+  # (api/v2/base_controller.rb#render_error):
+  #   {"error": {"type", "message", "details"?, "request_id", "remediation"?}}
+  # +request_id+ and +remediation+ are NESTED under +error+. The +X-Wf-Request-Id+ response
+  # header is set on every authenticated response — even an HTML 502 from the edge — so it
+  # is preferred over the body's id.
+  class Error < StandardError
+    DOCUMENTATION_URL = "https://docs.wefunder.com/api-reference"
+
+    attr_reader :status, :type, :request_id, :details, :remediation
+
+    def initialize(status:, type:, message:, request_id: nil, details: nil, remediation: nil)
+      super(message)
+      @status = status
+      @type = type
+      @request_id = request_id
+      @details = details
+      @remediation = remediation
+    end
+
+    # One-line summary for logs. (+message+ stays the server's message verbatim — in Ruby
+    # +Exception#message+ delegates to +to_s+, so this is deliberately NOT a +to_s+ override.)
+    def summary
+      parts = ["#{status} #{type}: #{message}"]
+      parts << "(request_id=#{request_id})" if request_id
+      parts << "— #{remediation}" if remediation
+      parts.join(" ")
+    end
+
+    def inspect = "#<#{self.class.name} #{summary}>"
+
+    # Prefer the +X-Wf-Request-Id+ header; fall back to a body-derived id.
+    def self.request_id_from(headers, body_request_id)
+      header = (headers || {}).find { |k, _| k.to_s.casecmp?(REQUEST_ID_HEADER) }&.last
+      header = header.first if header.is_a?(Array)
+      (header.nil? || header.empty? ? nil : header) || body_request_id
+    end
+
+    # Build an Error from a failed response's parts. Degrades gracefully when the body is
+    # not the documented shape (non-JSON, empty, or a bare object).
+    def self.from_response(status, headers, body, reason_phrase: nil)
+      parsed = parse_body(body)
+      err = parsed.is_a?(Hash) && parsed["error"].is_a?(Hash) ? parsed["error"] : {}
+      top_level_request_id = parsed.is_a?(Hash) ? parsed["request_id"] : nil
+      message = if err["message"].is_a?(String)
+                  err["message"]
+                else
+                  (reason_phrase.to_s.empty? ? "Request failed" : reason_phrase)
+                end
+      new(
+        status: status.to_i,
+        type: err["type"].is_a?(String) ? err["type"] : FALLBACK_ERROR_TYPE,
+        message: message,
+        request_id: request_id_from(headers, err["request_id"] || top_level_request_id),
+        details: err["details"],
+        remediation: err["remediation"].is_a?(String) ? err["remediation"] : nil
+      )
+    end
+
+    def self.parse_body(body)
+      return body if body.is_a?(Hash)
+      return nil if body.nil? || body.to_s.empty?
+
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+    private_class_method :parse_body
+  end
+
+  # Raised when a token must be recovered but no refresh token / re-mint capability exists.
+  class AuthError < Error
+    def initialize(message)
+      super(status: 401, type: "unauthorized", message: message)
+    end
+  end
+end