shedcloud-partner_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 145e122f76cf50761a1e721feb510f3bb0ea708809dfb986213da9c59c4c1505
+  data.tar.gz: 98b24f0679f7722abec77cab65c9303e21a2ea63934ffdecf6ee50f45ae2b35c
+SHA512:
+  metadata.gz: 9a247a283d4fb7a477ae1c93f68e089799a6667f849168689dddd96e8edf04fd2b7cbaf08322959580f66fded4266aecfc4d56e515de69c1a7066259642ed8c5
+  data.tar.gz: 8dac558602c6efe9774323b06305a6a4c87eac64d521c0d97cf2a27531206c92dd9531198c9bf5975ba9e541711bb65eccd22e2f0163f8068b31ab816652a426

data/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2'
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec
+
+      - name: Publish to RubyGems
+        uses: rubygems/release-gem@v1

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/Gemfile.lock
+/pkg/
+/tmp/
+/.rspec_status
+/coverage/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+Thumbs.db

data/AGENTS.md

@@ -0,0 +1,47 @@
+# AGENTS.md — shedcloud-gem
+
+Orientation for coding agents working in this repository.
+
+## What this is
+
+`shedcloud-partner_api` is the official Ruby gem for ShedCloud's public **Partner API** (`/partner/v1/*`). Partners authenticate with a company-scoped API key (`sc_live_…`) or OAuth2 client credentials (`POST /oauth/token`).
+
+This repo is the **consumer library**. The API itself lives in `shedcloud-api-go` (`internal/handler/partnerapi`, `docs/PARTNER_API.md`, `docs/partner-api/swagger.yaml`). The TypeScript twin is `shedcloud-npm` (`@shedcloud/partner-api`); the Go twin is `shedcloud-gomod` (`partnerapi`); the PHP twin is `shedcloud-php` (`shedcloud/partner-api`).
+
+## Layout
+
+```
+shedcloud-gem/
+├── lib/shedcloud/
+│   ├── partner_api.rb          # require entry
+│   └── partner_api/
+│       ├── client.rb           # Client
+│       ├── hosts.rb            # production / sandbox base URLs
+│       ├── auth.rb             # API key + OAuth credentials
+│       ├── auth_provider.rb    # token cache
+│       ├── http_client.rb      # request helper + query encoding
+│       ├── errors.rb
+│       ├── scopes.rb
+│       ├── webhooks.rb
+│       └── resources/          # one file per /partner/v1 resource
+├── spec/
+├── examples/
+└── shedcloud-partner_api.gemspec
+```
+
+## Rules of the road
+
+1. **Never invent endpoints or field names.** Mirror `shedcloud-api-go/docs/PARTNER_API.md` and keep parity with the other SDKs.
+2. **Hosts** are fixed in `hosts.rb`: production `https://go.shedcloud.com`, sandbox `https://api.shedcloudtest.com`.
+3. **Scopes** live in `scopes.rb` and must stay in sync with `shedcloud-api-go/internal/partnerauth/scopes.go`.
+4. **Auth stays outside resource classes.** Resources only call `HttpClient#request`. Token exchange/caching belongs in `auth_provider.rb`.
+5. **Keep the surface small.** No portal admin endpoints (`/v1/settings/api-keys`, etc.).
+6. After changing `lib/`, run `bundle exec rspec`.
+
+## Adding a resource
+
+1. Confirm the route + scopes in `shedcloud-api-go/internal/router/partner_api_routes.go`.
+2. Add `lib/shedcloud/partner_api/resources/<name>.rb` with `list` / `get` / `update` / `update_status` as applicable.
+3. Wire it on `Client` in `client.rb` and require it from `partner_api.rb`.
+4. Add an RSpec example with a mocked transport.
+5. Mirror the same change in the other SDK repos when practical.

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Initial `shedcloud-partner_api` Ruby gem
+- Built-in hosts: production `https://go.shedcloud.com` (default), sandbox `https://api.shedcloudtest.com`
+- Auth: API key bearer + OAuth2 client-credentials with token cache
+- Resources: lot-stock, stock-templates, leads, quotes, orders, work-orders, locations, customers, domains, agreements, products, users, payments, documents, events, configurator-sessions
+- Typed errors (`PartnerApiError`, `AuthError`) and scope constants
+- Webhook signature verification
+- Parity with `@shedcloud/partner-api`, `shedcloud-gomod/partnerapi`, and `shedcloud/partner-api`

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corland Partners LLC
+
+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,173 @@
+# shedcloud-gem
+
+Official Ruby gem for the ShedCloud Partner API (`/partner/v1/*`).
+
+Use this gem from Ruby 3.2+ to call company-scoped Partner API endpoints with an API key (`sc_live_…`) or OAuth2 client credentials.
+
+## Install
+
+```bash
+gem install shedcloud-partner_api
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'shedcloud-partner_api'
+```
+
+## Hosts
+
+| Environment | Host |
+|-------------|------|
+| `production` (default) | `https://go.shedcloud.com` |
+| `sandbox` | `https://api.shedcloudtest.com` |
+
+Pass `environment:` for sandbox, or `base_url:` for a custom/local override.
+
+## Quick start
+
+### API key (production)
+
+```ruby
+require 'shedcloud/partner_api'
+
+client = ShedCloud::PartnerApi::Client.new(
+  auth: ShedCloud::PartnerApi::Auth.new(api_key: ENV.fetch('SHEDCLOUD_API_KEY'))
+)
+
+stock = client.lot_stock.list(
+  limit: 50,
+  purchaseType: 'Lot Stock',
+  sort: 'price',
+  order: 'asc'
+)
+
+puts stock['total']
+puts stock['data'].first['title']
+```
+
+### Sandbox
+
+```ruby
+client = ShedCloud::PartnerApi::Client.new(
+  environment: 'sandbox',
+  auth: ShedCloud::PartnerApi::Auth.new(api_key: ENV.fetch('SHEDCLOUD_API_KEY'))
+)
+```
+
+### OAuth2 client credentials
+
+```ruby
+client = ShedCloud::PartnerApi::Client.new(
+  auth: ShedCloud::PartnerApi::Auth.new(
+    client_id: ENV.fetch('SHEDCLOUD_CLIENT_ID'),
+    client_secret: ENV.fetch('SHEDCLOUD_CLIENT_SECRET')
+  )
+)
+
+orders = client.orders.list(status: 'Unprocessed', limit: 25)
+```
+
+Create credentials in the ShedCloud portal under **Settings → Developer API**.
+
+## Resources
+
+Each resource maps to a section of the [hosted reference](https://go.shedcloud.com/partner/reference).
+
+| Client property | Endpoints |
+|-----------------|-----------|
+| `client.lot_stock` | `GET /partner/v1/lot-stock` |
+| `client.stock_templates` | `GET /partner/v1/stock-templates` |
+| `client.leads` | `GET/POST/PATCH /partner/v1/leads`, status + status-history |
+| `client.quotes` | `GET/POST/PATCH /partner/v1/quotes`, convert, line-items |
+| `client.orders` | `GET/POST/PATCH /partner/v1/orders`, contract, payments, payment-links |
+| `client.work_orders` | `GET/POST/PATCH /partner/v1/work-orders`, status + status-history |
+| `client.locations` | `GET/POST/PATCH /partner/v1/locations` |
+| `client.customers` | `GET/POST/PATCH /partner/v1/customers`, merge |
+| `client.products` | `GET/POST/PATCH /partner/v1/products`, create sizes |
+| `client.domains` | `GET /partner/v1/domains`, location domains |
+| `client.agreements` | `GET /partner/v1/agreements`, state-legal |
+| `client.users` | `GET/POST/PATCH /partner/v1/users`, roles |
+| `client.payments` | `GET /partner/v1/payments` (read-only) |
+| `client.documents` | `GET /partner/v1/documents`, download |
+| `client.events` | `GET /partner/v1/events`, each iterator, redeliver, deliveries |
+| `client.configurator_sessions` | `POST /partner/v1/configurator-sessions` |
+
+### Idempotency and optimistic concurrency
+
+```ruby
+quote = client.quotes.create(
+  {
+    serialNumber: 'SC-2024-00123',
+    customer: { name: 'Jane Doe', email: 'jane@example.com' }
+  },
+  options: ShedCloud::PartnerApi::RequestOptions.with_idempotency_key(SecureRandom.uuid)
+)
+
+client.orders.update(
+  order['id'],
+  { customerPhone: '555-0100' },
+  options: ShedCloud::PartnerApi::RequestOptions.with_if_match(order['version'])
+)
+```
+
+For boolean query params that must be sent even when `false`:
+
+```ruby
+client.quotes.list(converted: ShedCloud::PartnerApi::QueryValue.new(false))
+```
+
+## Webhooks
+
+Verify webhook deliveries with the subscription secret against the **raw** request body:
+
+```ruby
+body = request.body.read
+ShedCloud::PartnerApi::Webhooks.verify_signature(
+  ENV.fetch('SHEDCLOUD_WEBHOOK_SECRET'),
+  request.headers['X-ShedCloud-Signature'],
+  body
+)
+```
+
+## Errors
+
+Failed responses raise `ShedCloud::PartnerApi::PartnerApiError` (or `AuthError` for OAuth token failures):
+
+```ruby
+begin
+  client.orders.get(id)
+rescue ShedCloud::PartnerApi::PartnerApiError => e
+  puts e.status, e.message
+  # e.forbidden?, e.not_found?, e.rate_limited?
+end
+```
+
+## Scopes
+
+```ruby
+ShedCloud::PartnerApi::Scopes::LOT_STOCK_READ # partner-api.lot-stock.read
+ShedCloud::PartnerApi::Scopes::ORDERS_WRITE    # partner-api.orders.write
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## Versioning & changelog
+
+The Partner API is **additive-only within `/partner/v1`**. This gem is tagged with semver in lockstep with API additions.
+
+- API changes: [hosted changelog](https://go.shedcloud.com/partner/reference#changelog)
+
+## Docs
+
+- Partner API reference: https://go.shedcloud.com/partner/reference
+- Backend source of truth: `shedcloud-api-go/docs/PARTNER_API.md`
+- TypeScript twin: [`@shedcloud/partner-api`](https://github.com/Corland-Partners-LLC/shedcloud-npm)
+- Go twin: [`shedcloud-gomod/partnerapi`](https://github.com/Corland-Partners-LLC/shedcloud-gomod)
+- PHP twin: [`shedcloud/partner-api`](https://github.com/Corland-Partners-LLC/shedcloud-php)

data/Rakefile

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+# Tag pushes run in a detached HEAD. Skip bundler's git tag/push steps and only
+# build + push the gem (release-gem configures RubyGems credentials via OIDC).
+if ENV['GITHUB_ACTIONS']
+  Rake::Task['release'].clear
+
+  task release: :build do
+    gem = Dir.glob('pkg/*.gem').max
+    raise 'No gem found in pkg/' unless gem
+
+    sh "gem push #{gem}"
+  end
+end

data/examples/list_lot_stock.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'shedcloud/partner_api'
+
+client = ShedCloud::PartnerApi::Client.new(
+  auth: ShedCloud::PartnerApi::Auth.new(api_key: ENV.fetch('SHEDCLOUD_API_KEY', ''))
+)
+
+stock = client.lot_stock.list(
+  limit: 5,
+  purchaseType: 'Lot Stock',
+  sort: 'price',
+  order: 'asc'
+)
+
+puts "total=#{stock['total']} returned=#{stock['data']&.length || 0}"
+
+if stock['data']&.any?
+  item = stock['data'].first
+  puts format('first: %s | %s | $%.2f', item['serialNumber'], item['title'], item['price'].to_f)
+end

data/lib/shedcloud/partner_api/auth.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ShedCloud
+  module PartnerApi
+    class Auth
+      attr_reader :api_key, :client_id, :client_secret
+
+      def initialize(api_key: nil, client_id: nil, client_secret: nil)
+        @api_key = api_key
+        @client_id = client_id
+        @client_secret = client_secret
+      end
+
+      def validate!
+        has_key = !api_key.to_s.strip.empty?
+        has_oauth = !client_id.to_s.strip.empty? && !client_secret.to_s.strip.empty?
+
+        raise ArgumentError, 'auth: set exactly one of api_key or client_id+client_secret' if has_key == has_oauth
+      end
+
+      def api_key?
+        !api_key.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/shedcloud/partner_api/auth_provider.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+
+module ShedCloud
+  module PartnerApi
+    class AuthProvider
+      def initialize(base_url:, auth:, transport: HttpTransport.new, token_skew_seconds: 60)
+        @base_url = Hosts.trim_trailing_slashes(base_url)
+        @auth = auth
+        @transport = transport
+        @token_skew_seconds = token_skew_seconds
+        @cached_access_token = nil
+        @cached_expires_at = nil
+      end
+
+      def access_token
+        return @auth.api_key.to_s.strip if @auth.api_key?
+
+        now = Time.now.to_i
+        if @cached_access_token && @cached_expires_at && now < (@cached_expires_at - @token_skew_seconds)
+          return @cached_access_token
+        end
+
+        refresh_oauth_token
+      end
+
+      def refresh
+        return @auth.api_key.to_s.strip if @auth.api_key?
+
+        @cached_access_token = nil
+        @cached_expires_at = nil
+        refresh_oauth_token
+      end
+
+      private
+
+      def refresh_oauth_token
+        url = "#{@base_url}/oauth/token"
+        credentials = ["#{@auth.client_id}:#{@auth.client_secret}"].pack('m0')
+
+        response = @transport.send(
+          'POST',
+          url,
+          {
+            'Accept' => 'application/json',
+            'Authorization' => "Basic #{credentials}",
+            'Content-Type' => 'application/x-www-form-urlencoded'
+          },
+          URI.encode_www_form(grant_type: 'client_credentials')
+        )
+
+        parsed = parse_json(response[:body])
+
+        if response[:status] < 200 || response[:status] >= 300
+          message, code = extract_error(parsed, response[:status].to_s)
+          raise AuthError.new(message, status: response[:status], body: parsed, code: code)
+        end
+
+        token = parsed.is_a?(Hash) ? parsed['access_token'] : nil
+        if token.to_s.empty?
+          raise AuthError.new('OAuth token response missing access_token', status: response[:status], body: parsed)
+        end
+
+        expires_in = parsed['expires_in'].to_i
+        expires_in = 3600 if expires_in <= 0
+
+        @cached_access_token = token
+        @cached_expires_at = Time.now.to_i + expires_in
+        @cached_access_token
+      end
+
+      def parse_json(raw)
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        raw
+      end
+
+      def extract_error(body, fallback)
+        message = fallback
+        code = nil
+
+        return [message, code] unless body.is_a?(Hash)
+
+        message = body['error_description'] if body['error_description'].is_a?(String) && !body['error_description'].empty?
+        message = body['error'] if message == fallback && body['error'].is_a?(String) && !body['error'].empty?
+        message = body['message'] if message == fallback && body['message'].is_a?(String) && !body['message'].empty?
+        code = body['error'] if body['error'].is_a?(String)
+
+        [message, code]
+      end
+    end
+  end
+end

data/lib/shedcloud/partner_api/client.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ShedCloud
+  module PartnerApi
+    class Client
+      attr_reader :base_url,
+                  :lot_stock,
+                  :stock_templates,
+                  :leads,
+                  :quotes,
+                  :orders,
+                  :work_orders,
+                  :locations,
+                  :customers,
+                  :domains,
+                  :agreements,
+                  :products,
+                  :users,
+                  :payments,
+                  :documents,
+                  :events,
+                  :configurator_sessions
+
+      def initialize(auth:, environment: nil, base_url: nil, transport: HttpTransport.new, timeout_seconds: 30.0,
+                     user_agent: 'shedcloud-ruby/partner-api', token_skew_seconds: 60)
+        raise ArgumentError, 'Client: auth is required' unless auth.is_a?(Auth)
+
+        auth.validate!
+
+        @base_url = Hosts.resolve_base_url(base_url: base_url, environment: environment)
+        @auth_provider = AuthProvider.new(
+          base_url: @base_url,
+          auth: auth,
+          transport: transport,
+          token_skew_seconds: token_skew_seconds
+        )
+
+        @http = HttpClient.new(
+          base_url: @base_url,
+          get_access_token: -> { @auth_provider.access_token },
+          transport: transport,
+          user_agent: user_agent
+        )
+
+        @lot_stock = Resources::LotStock.new(@http)
+        @stock_templates = Resources::StockTemplates.new(@http)
+        @leads = Resources::Leads.new(@http)
+        @quotes = Resources::Quotes.new(@http)
+        @orders = Resources::Orders.new(@http)
+        @work_orders = Resources::WorkOrders.new(@http)
+        @locations = Resources::Locations.new(@http)
+        @customers = Resources::Customers.new(@http)
+        @domains = Resources::Domains.new(@http)
+        @agreements = Resources::Agreements.new(@http)
+        @products = Resources::Products.new(@http)
+        @users = Resources::Users.new(@http)
+        @payments = Resources::Payments.new(@http)
+        @documents = Resources::Documents.new(@http)
+        @events = Resources::Events.new(@http)
+        @configurator_sessions = Resources::ConfiguratorSessions.new(@http)
+      end
+
+      def me
+        @http.request('GET', '/partner/v1/me') || {}
+      end
+
+      def refresh_access_token
+        @auth_provider.refresh
+      end
+    end
+  end
+end

data/lib/shedcloud/partner_api/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ShedCloud
+  module PartnerApi
+    class PartnerApiError < StandardError
+      attr_reader :status, :body, :code
+
+      def initialize(message, status:, body: nil, code: nil)
+        @status = status
+        @body = body
+        @code = code
+        super(format_message(message))
+      end
+
+      def unauthorized? = status == 401
+      def forbidden? = status == 403
+      def not_found? = status == 404
+      def rate_limited? = status == 429
+
+      private
+
+      def format_message(message)
+        if code && !code.empty?
+          "#{message} (status=#{status} code=#{code})"
+        else
+          "#{message} (status=#{status})"
+        end
+      end
+    end
+
+    class AuthError < StandardError
+      attr_reader :status, :body, :code
+
+      def initialize(message, status:, body: nil, code: nil)
+        @status = status
+        @body = body
+        @code = code
+        super(format_message(message))
+      end
+
+      def unauthorized? = status == 401
+
+      private
+
+      def format_message(message)
+        if code && !code.empty?
+          "partner-api auth: #{message} (status=#{status} code=#{code})"
+        else
+          "partner-api auth: #{message} (status=#{status})"
+        end
+      end
+    end
+  end
+end

data/lib/shedcloud/partner_api/hosts.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module ShedCloud
+  module PartnerApi
+    module Hosts
+      HOST_PRODUCTION = 'https://go.shedcloud.com'
+      HOST_SANDBOX = 'https://api.shedcloudtest.com'
+      DEFAULT_BASE_URL = HOST_PRODUCTION
+
+      ENVIRONMENT_PRODUCTION = 'production'
+      ENVIRONMENT_SANDBOX = 'sandbox'
+
+      module_function
+
+      def resolve_base_url(base_url: nil, environment: nil)
+        trimmed = trim_trailing_slashes(base_url.to_s)
+        return trimmed unless trimmed.empty?
+
+        case environment
+        when ENVIRONMENT_SANDBOX then HOST_SANDBOX
+        when ENVIRONMENT_PRODUCTION, nil, '' then HOST_PRODUCTION
+        else HOST_PRODUCTION
+        end
+      end
+
+      def trim_trailing_slashes(value)
+        value.to_s.sub(%r{/+\z}, '')
+      end
+    end
+  end
+end