wenmar 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 43545722c16579d457083b3ca7c8ce6d5d29c04810f409009aef3d54f4a46cd4
+  data.tar.gz: 91d256168a7a1dac6ab545420a3567d28e2bc1a1a99c1dc9d660e33b013aca98
+SHA512:
+  metadata.gz: e433cfa494a87297b498ad3f9586800eb1dabc37b241caafc24f552232d411ad9e1e15104c6a8d5f184ddc2e9c01589671afe4d05fc17f0e544353d8503649f1
+  data.tar.gz: f6cb3a1c6187e884a9ef94774ef25873d8351680fe0522c057802f405836c91095e4170e6611a838e9e141bc0783eb57c450a79af2607e722ad991aba66230a7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wenmar Pro
+
+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,162 @@
+# wenmar — Ruby SDK
+
+Ruby SDK for the Wenmar Pro API.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "wenmar"
+```
+
+then run `bundle install`. Or install it directly:
+
+```sh
+gem install wenmar
+```
+
+## Quick start
+
+```ruby
+require "wenmar"
+
+client = Wenmar::Client.new(token: "YOUR_API_TOKEN")
+
+# List customers (paginated)
+customers = client.list_customers
+customers # => [{ "id" => 1, "full_name" => "Jane Doe", ... }]
+
+# Show a customer
+customer = client.show_customer(1)
+customer # => { "id" => 1, "full_name" => "Jane Doe", ... }
+
+# Create a customer (request body is nested under the resource key)
+created = client.create_customer(customer: { first_name: "Jane", last_name: "Doe" })
+```
+
+## Configuration
+
+`Wenmar::Client.new` takes a token (required) and an optional base URL:
+
+```ruby
+client = Wenmar::Client.new(token: "YOUR_API_KEY", base_url: "https://app.wenmarpro.com")
+```
+
+## Location scoping
+
+Use `for_location` to scope every request to a specific location. The parent
+client is not mutated:
+
+```ruby
+shop = client.for_location("42")
+shop.list_customers # sends X-Wenmar-Location: 42
+```
+
+## API coverage
+
+The full surface is generated into `resources.rb` — hundreds of methods across
+every tag. See the [generated API reference](../docs/api/api-reference.md) for
+the live list. A representative sample:
+
+| Operation | Method |
+|---|---|
+| List customers | `list_customers(customer_tag_id:, has_balance:, has_vehicle:, last_visit_months:, page:, per_page:, q:, status:, type:)` |
+| Create customer | `create_customer(customer:)` |
+| Show customer | `show_customer(id)` |
+| Update customer | `update_customer(id, customer:)` |
+| List vehicles | `list_vehicles(page:, per_page:, q:, ...)` |
+| Create vehicle | `create_vehicle(vehicle:)` |
+| Show vehicle | `show_vehicle(id)` |
+| Update vehicle | `update_vehicle(id, vehicle:)` |
+| Trash vehicle | `trash_vehicle(id)` |
+| Decode VIN | `decode_vin(vin:)` |
+| Check duplicates | `check_vehicle_duplicate(vin:)` |
+| List work orders | `list_work_orders(page:, per_page:, q:, ...)` |
+| Create work order | `create_work_order(work_order:)` |
+| Show work order | `show_work_order(id)` |
+| Update work order | `update_work_order(id, work_order:)` |
+| Void work order | `void_work_order(id, closure_reason:)` |
+| Reopen work order | `reopen_work_order(id)` |
+
+Work orders use a domain workflow (`stage`) and are never hard-deleted — use
+`void_work_order`/`reopen_work_order`. Lifecycle-managed resources (customers,
+vehicles, vendors, …) support `trash_*`/`archive_*`/`restore_*` rather than
+`delete`.
+
+Every paginated list also has a `get_all_*` variant that auto-paginates with a
+1,000-item safety cap, e.g. `get_all_customers`.
+
+## Pagination
+
+List endpoints paginate via the RFC 5988 `Link` header. Paginated list methods
+return a `Wenmar::Paginator`:
+
+```ruby
+result = client.list_customers
+result.each { |customer| puts customer["full_name"] }
+```
+
+Or collect everything with `get_all_customers`.
+
+## Errors
+
+All non-2xx responses raise `Wenmar::Error`:
+
+```ruby
+begin
+  client.show_customer(999)
+rescue Wenmar::Error => e
+  e.code   # => "not_found"
+  e.status # => 404
+  e.message
+  e.field_errors
+end
+```
+
+See [docs/errors.md](../docs/api/errors.md) for the full error envelope and code table.
+
+## Retry
+
+The client retries 429/503/504 with exponential backoff (max 3 retries). It
+respects the `Retry-After` response header. Mutations are only retried on 429 —
+never on transport errors, which could duplicate a write.
+
+## OAuth and credential storage
+
+For OAuth (the browser `authorization_code` + PKCE flow is a CLI concern; the
+SDK ships the token model, store, and refresh machinery):
+
+```ruby
+require "wenmar"
+
+# Exchange a refresh token for a new access token.
+token = Wenmar::OAuth.refresh(
+  base_url: "https://app.wenmarpro.com",
+  refresh_token: refresh_token
+)
+
+# Persist the full token (access + refresh + expiry) with 0600 permissions.
+store = Wenmar::CredentialStore.new
+store.save_token(token)
+
+# Auto-refresh when the token is expired or within 5 minutes of expiry.
+manager = Wenmar::AuthManager.new(store: store, oauth: { base_url: "https://app.wenmarpro.com" })
+provider = Wenmar::CredentialStoreProvider.new(store: store, manager: manager)
+client = Wenmar::Client.new(token_provider: provider)
+```
+
+`Wenmar::KeychainStore` is an alternative macOS keychain-backed store (it
+requires the optional `ruby-keychain` gem, which is **not** a runtime
+dependency — install it yourself if you want keychain storage).
+
+## Documentation
+
+- [API reference](../docs/api/api-reference.md)
+- [Authentication](../docs/api/authentication.md)
+- [Pagination](../docs/api/pagination.md)
+- [Errors](../docs/api/errors.md)
+
+## License
+
+MIT

data/lib/wenmar/auth.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Wenmar
+  class TokenError < StandardError; end
+
+  module TokenProvider
+    def token
+      raise NotImplementedError
+    end
+  end
+
+  class StaticTokenProvider
+    include TokenProvider
+
+    def initialize(token)
+      raise ArgumentError, "token is required" if token.nil? || token.empty?
+
+      @token = token
+    end
+
+    attr_reader :token
+  end
+
+  # Reads a Wenmar::Token from a store, auto-refreshing via an AuthManager when
+  # the stored token is expired or within a refresh window of expiry.
+  class CredentialStoreProvider
+    DEFAULT_REFRESH_WINDOW = 300
+
+    def initialize(store:, manager: nil, refresh_window: DEFAULT_REFRESH_WINDOW)
+      @store = store
+      @manager = manager
+      @refresh_window = refresh_window
+    end
+
+    def token
+      token = @store.get_token
+      return nil if token.nil? || token.access_token.nil? || token.access_token.empty?
+
+      if token.expired? || token.will_expire_within?(@refresh_window)
+        if @manager
+          @manager.refresh
+          token = @store.get_token
+        end
+      end
+      token&.access_token
+    end
+  end
+
+  # Coordinates token storage, retrieval, and refresh. When configured with an
+  # oauth hash (base_url and optional client_id), #refresh exchanges the stored
+  # refresh token at the Doorkeeper token endpoint.
+  class AuthManager
+    def initialize(store:, provider: nil, oauth: nil)
+      @store = store
+      @provider = provider
+      @refresh_fn = oauth ? build_oauth_refresh(oauth) : nil
+    end
+
+    # Overrides the refresh function used by #refresh. Useful for tests and
+    # custom refresh flows.
+    def set_refresh_fn(fn = nil, &block)
+      @refresh_fn = fn || block
+    end
+
+    def token
+      return @provider.token if @provider
+
+      token = @store.get_token
+      token&.access_token
+    end
+
+    def refresh
+      token = @store.get_token
+      raise TokenError, "no token stored" if token.nil?
+      raise TokenError, "no refresh token stored" if token.refresh_token.nil? || token.refresh_token.empty?
+      raise TokenError, "OAuth refresh is not configured" if @refresh_fn.nil?
+
+      new_token = @refresh_fn.call(token.refresh_token)
+      @store.save_token(new_token)
+      new_token
+    end
+
+    def logout
+      @store.delete
+    end
+
+    private
+
+    def build_oauth_refresh(oauth)
+      oauth = {base_url: oauth} if oauth.is_a?(String)
+      base_url = oauth[:base_url]
+      client_id = oauth[:client_id] || OAuth::DEFAULT_CLIENT_ID
+      return nil if base_url.nil? || base_url.empty?
+
+      ->(refresh_token) { OAuth.refresh(base_url: base_url, refresh_token: refresh_token, client_id: client_id) }
+    end
+  end
+end

data/lib/wenmar/client.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require "uri"
+require_relative "version"
+require_relative "error"
+require_relative "auth"
+require_relative "config"
+require_relative "credentials"
+require_relative "pagination"
+
+module Wenmar
+  class Client
+    DEFAULT_BASE_URL = "https://app.wenmarpro.com"
+
+    # Faraday's retry middleware raises RetriableResponse internally when a
+    # response status matches retry_statuses. The write connection must match
+    # only that synthetic exception so 429s retry while transport errors
+    # (Faraday::ConnectionFailed, etc.) do not — mutations are not safe to
+    # replay on a lost connection.
+    WRITE_RETRY_EXCEPTIONS = [Faraday::RetriableResponse].freeze
+
+    attr_reader :base_url, :location_id, :config
+
+    def initialize(config = nil, token: nil, base_url: nil, token_provider: nil)
+      @config = config.is_a?(Config) ? config : Config.new(config || {})
+      @config.access_token = token if token
+      @config.token_provider = token_provider if token_provider
+      @config.base_url = base_url if base_url
+
+      @base_url = (@config.base_url || DEFAULT_BASE_URL).to_s.sub(%r{/+\z}, "")
+      @location_id = @config.location_id
+      raise ArgumentError, "base_url must use https (http only allowed for localhost)" unless https_or_localhost?(@base_url)
+
+      @read_connection = build_connection(retry_statuses: [429, 500, 502, 503, 504])
+      @write_connection = build_connection(retry_statuses: [429], methods: %i[post patch delete], exceptions: WRITE_RETRY_EXCEPTIONS)
+      @cache = {}
+      @cache_mutex = Mutex.new
+    end
+
+    def https_or_localhost?(url)
+      parsed = URI.parse(url)
+      return true if parsed.scheme == "https"
+
+      %w[localhost 127.0.0.1].include?(parsed.host)
+    rescue URI::InvalidURIError
+      false
+    end
+    private :https_or_localhost?
+
+    def token_provider
+      @config.token_provider || StaticTokenProvider.new(@config.access_token)
+    end
+
+    def for_location(location_id)
+      scoped = dup
+      scoped.instance_variable_set(:@location_id, location_id)
+      scoped.instance_variable_set(:@cache, {})
+      scoped.instance_variable_set(:@cache_mutex, Mutex.new)
+      scoped.instance_variable_set(:@read_connection, build_connection(retry_statuses: [429, 500, 502, 503, 504], location_id: location_id))
+      scoped.instance_variable_set(:@write_connection, build_connection(retry_statuses: [429], methods: %i[post patch delete], exceptions: WRITE_RETRY_EXCEPTIONS, location_id: location_id))
+      scoped
+    end
+
+    def get(path, params = {})
+      cache_key = cache_key(path, params)
+      cached = if @config.cache_enabled
+        @cache_mutex.synchronize { @cache[cache_key] }
+      end
+
+      response = @read_connection.get(path, params) do |req|
+        if cached
+          req.headers["If-None-Match"] = cached[:etag] if cached[:etag]
+          req.headers["If-Modified-Since"] = cached[:last_modified] if cached[:last_modified]
+        end
+      end
+
+      if response.status == 304 && cached
+        response = Faraday::Response.new(
+          status: 200,
+          response_headers: cached[:headers],
+          body: cached[:body]
+        )
+      end
+
+      if @config.cache_enabled && response.status == 200 && (response.headers["ETag"] || response.headers["Last-Modified"])
+        @cache_mutex.synchronize do
+          @cache[cache_key] = {
+            etag: response.headers["ETag"],
+            last_modified: response.headers["Last-Modified"],
+            body: response.body,
+            headers: response.headers
+          }
+        end
+      end
+
+      handle_response(response)
+    end
+
+    def get_raw(url)
+      response = @read_connection.get(url) do |req|
+        req.headers["Accept"] = "application/json"
+      end
+      raise Wenmar::Error.from_response(response) if response.status >= 400
+
+      response
+    end
+
+    def post(path, body = nil, params = {})
+      response = @write_connection.post(path) do |req|
+        req.params.merge!(params) unless params.empty?
+        req.body = body.to_json if body
+      end
+      handle_response(response)
+    end
+
+    def patch(path, body = nil, params = {})
+      response = @write_connection.patch(path) do |req|
+        req.params.merge!(params) unless params.empty?
+        req.body = body.to_json if body
+      end
+      handle_response(response)
+    end
+
+    def delete(path, params = {})
+      response = @write_connection.delete(path) do |req|
+        req.params.merge!(params) unless params.empty?
+      end
+      handle_response(response)
+    end
+
+    # paginator_to_a collects all pages from a paginated list result, up to
+    # max items (default 1000). The returned array includes the initial page
+    # (the response body) plus every subsequent page fetched via the Link
+    # header. We intentionally do NOT delegate to Paginator#to_a: that method
+    # starts from the paginator's own (empty) data and would drop the initial
+    # page.
+    def paginator_to_a(result, max = 1000)
+      return result unless result.respond_to?(:paginator)
+
+      paginator = result.paginator
+      return result unless paginator
+
+      items = result.dup
+      while paginator.has_next? && items.size < max
+        page = paginator.next_page
+        break if page.nil?
+
+        items.concat(page)
+      end
+      items.first(max)
+    end
+
+    private
+
+    def build_connection(retry_statuses:, methods: Faraday::Retry::Middleware::IDEMPOTENT_METHODS, exceptions: [Faraday::Error], location_id: @location_id)
+      Faraday.new(url: @base_url) do |conn|
+        conn.headers["Accept"] = "application/json"
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["User-Agent"] = "wenmar-sdk-ruby/#{Wenmar::VERSION}"
+        conn.headers["X-Wenmar-Location"] = location_id if location_id
+        conn.options.timeout = @config.timeout
+        conn.options.open_timeout = @config.timeout
+        conn.request :authorization, "Bearer", -> { resolve_token }
+        conn.request :retry, retry_options.merge(
+          retry_statuses: retry_statuses,
+          methods: methods,
+          exceptions: exceptions
+        )
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    # Builds the Faraday retry middleware options from @config.retry_options,
+    # defaulting max to @config.max_retries when not present. These may be
+    # overridden per-connection (retry_statuses/methods/exceptions) by callers
+    # of build_connection, which always win.
+    def retry_options
+      @config.retry_options.dup.tap do |opts|
+        opts[:max] = @config.max_retries unless opts.key?(:max) && opts[:max]
+      end
+    end
+
+    def resolve_token
+      token_provider.token
+    rescue TokenError => e
+      raise Error.new(code: "auth_failed", message: e.message)
+    end
+
+    def cache_key(path, params)
+      "#{location_id}|#{path_with_query(path, params)}"
+    end
+
+    def path_with_query(path, params)
+      return path if params.nil? || params.empty?
+
+      "#{path}?#{URI.encode_www_form(params)}"
+    end
+
+    def handle_response(response)
+      if response.status >= 400
+        raise Wenmar::Error.from_response(response)
+      end
+
+      body = response.body
+      return nil if body.nil? || body == ""
+
+      body = JSON.parse(body) if body.is_a?(String)
+
+      # Attach a paginator to list responses that carry a Link header.
+      if body.is_a?(Array) && response.headers["Link"]
+        client = self
+        body.define_singleton_method(:paginator) do
+          Paginator.from_response(response, client)
+        end
+      end
+      body
+    end
+  end
+end

data/lib/wenmar/config.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Wenmar
+  class Config
+    attr_accessor :base_url, :access_token, :token_provider, :location_id,
+      :timeout, :max_retries, :cache_enabled, :retry_options
+
+    def initialize(attrs = {})
+      @base_url = attrs[:base_url] || "https://app.wenmarpro.com"
+      @access_token = attrs[:access_token]
+      @token_provider = attrs[:token_provider]
+      @location_id = attrs[:location_id]
+      @timeout = attrs[:timeout] || 30
+      @max_retries = attrs[:max_retries] || 3
+      @cache_enabled = attrs.fetch(:cache_enabled, true)
+      @retry_options = attrs[:retry_options] || {
+        max: @max_retries,
+        interval: 0.1,
+        interval_randomness: 0.5,
+        backoff_factor: 2,
+        max_interval: 30
+      }
+    end
+
+    def self.from_env
+      new(
+        base_url: ENV.fetch("WENMAR_BASE_URL", "https://app.wenmarpro.com"),
+        timeout: ENV["WENMAR_TIMEOUT"]&.to_i || 30,
+        max_retries: ENV["WENMAR_MAX_RETRIES"]&.to_i || 3,
+        cache_enabled: ENV["WENMAR_CACHE"] != "false"
+      )
+    end
+  end
+end

data/lib/wenmar/credentials.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Wenmar
+  class CredentialStore
+    TOKEN_KEY = "access_token"
+    LEGACY_TOKEN_KEY = "token"
+
+    def initialize(path = default_path)
+      @path = path
+    end
+
+    def load
+      return {} unless File.exist?(@path)
+
+      JSON.parse(File.read(@path))
+    rescue JSON::ParserError
+      {}
+    end
+
+    # Legacy: returns the access token string or nil. Prefer get_token.
+    def token
+      data = load
+      data[TOKEN_KEY] || data[LEGACY_TOKEN_KEY]
+    end
+
+    # Legacy: wraps a token string in a Wenmar::Token and persists it.
+    def save(token)
+      save_token(Token.new(access_token: token))
+    end
+
+    def get_token
+      data = load
+      return nil if data.empty?
+
+      return Token.new(access_token: data[LEGACY_TOKEN_KEY]) if data[LEGACY_TOKEN_KEY] && !data[TOKEN_KEY]
+
+      Token.from_h(data)
+    rescue TokenError
+      nil
+    end
+
+    def save_token(token)
+      token = Token.from_h(token) if token.is_a?(Hash)
+      FileUtils.mkdir_p(File.dirname(@path))
+      File.write(@path, JSON.pretty_generate(token.to_h), perm: 0o600)
+    end
+
+    def delete
+      FileUtils.rm_f(@path)
+    end
+
+    private
+
+    def default_path
+      File.join(Dir.home, ".config", "wenmar", "credentials.json")
+    end
+  end
+
+  class KeychainStore
+    SERVICE = "wenmar"
+    LEGACY_SERVICE = "wenmar-cli"
+    ACCOUNT = "token"
+
+    # The ruby-keychain gem is macOS-only and optional. It must not be a hard
+    # runtime dependency, so we require it lazily and only when a keychain
+    # operation is attempted. Keychain users must `gem install ruby-keychain`
+    # themselves.
+    def initialize
+      require_keychain
+    end
+
+    def get_token
+      password = read_password
+      return nil unless password
+
+      Token.from_h(JSON.parse(password))
+    rescue TokenError, JSON::ParserError
+      # A legacy plain-token entry has no JSON envelope; treat it as a bare
+      # access token.
+      bare = read_password
+      bare ? Token.new(access_token: bare) : nil
+    end
+
+    def save_token(token)
+      token = Token.from_h(token) if token.is_a?(Hash)
+      write_password(JSON.generate(token.to_h))
+    end
+
+    def delete
+      require_keychain
+      Keychain.generic_passwords.where(service: SERVICE, account: ACCOUNT).first&.destroy
+    end
+
+    private
+
+    def require_keychain
+      require "keychain"
+    rescue LoadError
+      raise TokenError, "The 'ruby-keychain' gem is required to use KeychainStore. Run `gem install ruby-keychain`."
+    end
+
+    def read_password
+      require_keychain
+      item = Keychain.generic_passwords.where(service: SERVICE, account: ACCOUNT).first
+      return item.password if item
+
+      legacy = Keychain.generic_passwords.where(service: LEGACY_SERVICE, account: ACCOUNT).first
+      return nil unless legacy
+
+      # Migrate a legacy entry into the current service.
+      write_password(legacy.password)
+      legacy.password
+    end
+
+    def write_password(password)
+      require_keychain
+      Keychain.generic_passwords.where(service: SERVICE, account: ACCOUNT).first&.destroy
+      Keychain.generic_passwords.create(service: SERVICE, account: ACCOUNT, password: password)
+    end
+  end
+end