sendcloud_api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 796c66cfdea4b2bec78d7802df95083b114c53874570e6ac1ca56f1aab2ce6d9
+  data.tar.gz: d5079d7779398fd0e3457e7bf3cb4066393ea1c99390c43962f4bec5a4303f00
+SHA512:
+  metadata.gz: 33362f6704bdf4672d035f81d52b9e25672edb92c5100f8932a0e03f9b6e76156889b087152aab54f06c5bda76c9524fae0c51570057963fcc33b7aeeb845b17
+  data.tar.gz: 728cd94df4f90b37106dd5cd247fce3a0445c56514ca790b46de3a342f886c40ac09504d117a5be3850cfef44c4a3bf3186b18e461ce41cc0e4e56585d628f9a

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## [0.1.0] - 2026-10-20
+
+- Add resources for returns (create, validate, retrieve, list, cancel), shipping option search, parcel documents, parcel tracking, contracts (list, create, retrieve, update, delete, schemas), integrations (retrieve, update), account metadata, and invoice items.
+- Add `SendcloudAPI::Pagination.next_params`, which carries the caller's filters to the next page for both Sendcloud cursor styles, and `SendcloudAPI::WebhookSignature.verify` for signed webhooks.
+- Reject unknown list filters before sending, because Sendcloud ignores them and returns every record. Reject `.` and `..` as ids.
+- Add the client foundation for Sendcloud API v3 with HTTP Basic authentication and configurable timeouts.
+- Return JSON, or caller-requested PDF, PNG, and ZPL documents, with typed errors and uncertain write outcomes, without automatic retries. An empty or mismatched document raises `ParseError`. Error messages include Sendcloud's error text, sent as a list or a single string, and leave out a `code` equal to the HTTP status.
+- Remove credentials from responses and errors without changing field names, identifiers, ordinary text in successful JSON, or document bytes. Errors remove every known credential, however short.
+- Reject a path that starts with `/` or a scheme, or has a `.` or `..` segment, before sending, so requests stay under the base URL.
+- Add RSpec, Standard, Ruby 3.3 and 3.4 CI, and RubyGems OIDC publishing from a job that runs no repository code.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PostCo
+
+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,286 @@
+# Sendcloud API
+
+`sendcloud_api` is a Ruby client for the [Sendcloud API v3](https://sendcloud.dev/api/v3).
+Each call sends one HTTP request without automatic retries. The caller owns idempotency, recovery, and business policy.
+
+Version `0.1.0` adds resources for returns, shipping options, parcel documents and tracking, contracts, integrations, account metadata, invoice items, and webhook signatures.
+Ruby 3.3 or newer is required.
+
+## Authentication
+
+Sendcloud uses the public key as the HTTP Basic username and the secret key as the password.
+See [Sendcloud authentication](https://sendcloud.dev/docs/getting-started/authentication/).
+
+```ruby
+client = SendcloudAPI::Client.new(
+  public_key: ENV.fetch("SENDCLOUD_PUBLIC_KEY"),
+  secret_key: ENV.fetch("SENDCLOUD_SECRET_KEY")
+)
+response = client.connection.get("user/auth/metadata")
+```
+
+Both credentials must be non-empty Strings. Configuration belongs to each client instance.
+The default base URL is `https://panel.sendcloud.sc/api/v3/`, the open timeout is 5 seconds, and the request timeout is 30 seconds.
+
+You can override the URL and timeouts or inject a Faraday adapter for tests.
+
+```ruby
+client = SendcloudAPI::Client.new(
+  public_key: "test-public-key",
+  secret_key: "test-secret-key",
+  base_url: "https://example.test/api/v3/",
+  open_timeout: 2,
+  timeout: 10,
+  adapter: [:test, stubs]
+)
+```
+
+## Resources
+
+Each resource method sends one request and returns a `SendcloudAPI::Response` with Sendcloud's body unchanged.
+Payloads are Hashes with Sendcloud's JSON field names as String keys. List filters are keyword arguments with Sendcloud's query parameter names, as Symbol or String keys.
+An unknown filter raises `ArgumentError` before any request is sent, because Sendcloud ignores unknown filters and returns every record.
+Ids and tracking numbers are required and are escaped into one path segment. A value of `.` or `..` raises `ArgumentError` before sending, because it would change the path.
+
+### Returns
+
+```ruby
+created = client.returns.create(payload: {
+  "from_address" => from_address,
+  "to_address" => to_address,
+  "ship_with" => {"type" => "shipping_option_code", "shipping_option_code" => "sendcloud:letterreturn"},
+  "weight" => {"value" => 0.5, "unit" => "kg"},
+  "external_reference" => "postco-123"
+})
+return_id = created.body["return_id"]
+parcel_id = created.body["parcel_id"]
+
+client.returns.validate(payload: return_payload)
+client.returns.retrieve(id: return_id)
+client.returns.list(page_size: 40, from_date: "2026-10-01 00:00:00", to_date: "2026-10-31 00:00:00")
+client.returns.cancel(id: return_id)
+```
+
+Keep the `parcel_id` from the create response. `retrieve` returns the return without a `data` wrapper and without `parcel_id` or `external_reference`.
+The return's `status` stays `open`. The parcel's progress is the last `parent_status` in `status_history`, such as `ready-to-send` or `cancelled`.
+A second return with a used `external_reference` raises `ConflictError`, which is not ambiguous and carries no return id.
+`cancel` answers HTTP 202. Read the return to see the parcel reach `cancelled`.
+`validate` only checks a return, so its failures are never ambiguous.
+
+### Shipping options
+
+```ruby
+client.shipping_options.search(payload: {
+  "from_country_code" => "GB",
+  "to_country_code" => "GB",
+  "functionalities" => {"returns" => true},
+  "parcels" => [{"weight" => {"value" => 1, "unit" => "kg"}}],
+  "calculate_quotes" => true
+})
+```
+
+The search only reads, so its failures are never ambiguous.
+
+### Parcel documents
+
+```ruby
+label = client.parcel_documents.retrieve(parcel_id: parcel_id, type: "label", format: :png, dpi: 300)
+label.body         # PNG bytes
+label.content_type # "image/png"
+```
+
+`format` is `:pdf`, `:png`, or `:zpl` and sets the Accept header. The optional filters are `dpi` and `paper_size`.
+Label documents can take a few seconds to appear after a return is created. Until then Sendcloud answers HTTP 404, which raises `NotFoundError`.
+A carrier-native ZPL label is always returned as ZPL. A `:pdf` or `:png` request for one raises `ParseError` with `ambiguous? == false` and `error.response.content_type == "application/zpl"`.
+Request it again with `format: :zpl`.
+
+### Parcel tracking
+
+```ruby
+client.parcel_tracking.retrieve(tracking_number: tracking_number)
+```
+
+Sendcloud answers HTTP 404 for a parcel its tracking service has not registered yet.
+
+### Contracts
+
+```ruby
+client.contracts.schemas(carrier_code: "dpd_gb")
+client.contracts.list(carrier_code: "dpd_gb", is_active: true, page_size: 100)
+contract = client.contracts.create(payload: {"carrier_code" => "dpd_gb", "is_active" => false, "contract_data" => contract_data})
+client.contracts.retrieve(id: contract_id)
+client.contracts.update(id: contract_id, payload: {"is_active" => true})
+client.contracts.delete(id: contract_id)
+```
+
+A new contract starts in the `validating` state. Read it again to see `active` or `validation_failed`.
+
+### Integrations, account metadata, and invoice items
+
+```ruby
+client.integrations.retrieve(id: integration_id)
+client.integrations.update(id: integration_id, payload: {"webhook_active" => true, "webhook_url" => url})
+client.user.auth_metadata
+client.invoice_items.list(parcel_id: parcel_id, type: "shipment", created_after: "2026-10-01T00:00:00Z")
+```
+
+An integration update answers HTTP 204 with no body.
+
+### Pagination
+
+List methods return one page. `SendcloudAPI::Pagination.next_params(page, params)` returns the params for the next page, or `nil` on the last page.
+It keeps every filter in `params` and sets `cursor`. A Sendcloud cursor holds only a position, so a request with the cursor alone returns records the filters would exclude.
+It reads the `Link` header that contracts and invoice items use, and the body `next` URL that returns use. A next URL without exactly one cursor, or one that does not parse, raises `ParseError`.
+
+```ruby
+contracts = []
+params = {carrier_code: "dpd_gb", page_size: 100}
+while params
+  page = client.contracts.list(**params)
+  contracts.concat(page.body["data"])
+  params = SendcloudAPI::Pagination.next_params(page, params)
+end
+```
+
+### Webhook signatures
+
+Sendcloud signs each webhook with the hex HMAC-SHA256 of the raw request body, keyed with the integration's secret key, in the `Sendcloud-Signature` header.
+
+```ruby
+valid = SendcloudAPI::WebhookSignature.verify(
+  request.raw_post,
+  request.headers[SendcloudAPI::WebhookSignature::HEADER],
+  secret_key
+)
+```
+
+Pass the unparsed body, because a parsed and encoded body has different bytes. The comparison runs in constant time.
+A missing or wrong signature returns `false`, as does any value that is not 64 ASCII hex characters, whatever its encoding. A body that is not a String or an empty secret raises `ArgumentError`.
+
+## Requests and responses
+
+`client.connection` exposes these methods:
+
+```ruby
+get(path, params: {}, accept: "application/json")
+post(path, payload:, read_only: false)
+put(path, payload:)
+patch(path, payload:)
+delete(path, params: {})
+```
+
+Use endpoint paths relative to the configured base URL. Payloads are encoded as JSON without changing field names or amounts.
+HTTP redirects are returned as errors, without another request.
+A path or base URL that is not a valid URL raises `ArgumentError` before any request is sent. The message omits the value.
+A path that starts with `/` or a scheme such as `https:`, or contains a `.` or `..` segment, also raises `ArgumentError` before sending. A leading `/` would replace the base URL's `/api/v3/`, and an absolute URL would send the Authorization header to another host.
+
+Each successful call returns a `SendcloudAPI::Response` with `status`, normalized lowercase `headers`, `body`, and `content_type`.
+`success?` identifies HTTP 200 through 299. `no_content?` identifies HTTP 204 or a nil body.
+
+Every request sends the `accept` value as its Accept header. By default the connection expects JSON.
+A JSON response keeps the provider's String keys. Content types ending in `+json` are JSON, and a missing content type is read as JSON.
+To fetch a document, pass its media type. Sendcloud's parcel documents endpoint returns `application/pdf`, `image/png`, or `application/zpl` depending on Accept.
+The body is then the unchanged response bytes in binary encoding.
+
+```ruby
+label = client.connection.get("parcels/#{parcel_id}/documents/label", accept: "image/png")
+label.body         # PNG bytes
+label.content_type # "image/png"
+```
+
+A successful response in a different format than the caller expected raises `ParseError`.
+That includes HTML answering a JSON request and ZPL answering a PNG request. Sendcloud returns native ZPL labels as ZPL whatever the Accept header says.
+An empty successful response to a document request also raises `ParseError`.
+
+Some Sendcloud POST endpoints only read, such as shipping option searches and return validation.
+Pass `read_only: true` for those so their failures are never reported as ambiguous writes.
+
+```ruby
+client.connection.post("shipping-options", payload: query, read_only: true)
+```
+
+## Errors and recovery
+
+All errors below inherit from `SendcloudAPI::Error`.
+
+| HTTP status | Error class |
+| --- | --- |
+| 400 | `BadRequestError` |
+| 401 | `AuthenticationError` |
+| 403 | `ForbiddenError` |
+| 404 | `NotFoundError` |
+| 405 | `MethodNotAllowedError` |
+| 409 | `ConflictError` |
+| 422 | `UnprocessableEntityError` |
+| 429 | `RateLimitError` |
+| 500 through 599 | `ServerError` |
+| Other unsuccessful statuses | `Error` |
+
+`TransportError` wraps Faraday and decompression failures. `ParseError` reports unreadable JSON or a response in an unexpected format.
+A non-204 write response with empty or null JSON also raises `ParseError`.
+HTTP errors take precedence over parsing errors, so an unreadable HTTP 503 response raises `ServerError`.
+
+```ruby
+begin
+  client.connection.get("user/auth/metadata")
+rescue SendcloudAPI::RateLimitError => error
+  retry_after = error.retry_after
+rescue SendcloudAPI::Error => error
+  status = error.status
+  details = error.body
+end
+```
+
+HTTP errors expose `response`, `status`, `headers`, `body`, and `retry_after`.
+Their messages join each error's `code`, `field`, `message`, `title`, `detail`, and `source` values.
+That covers Sendcloud's two error list shapes, `{code, detail, source, status}` and `{code, field, message}`, and a string `errors` value from return lookups.
+A `code` equal to the HTTP status is left out, so a returns 409 reads "HTTP 409: returns External reference has already been used in another return."
+The joined details are capped at 1,000 characters. The body keeps every error.
+
+`error.ambiguous?` is true for a POST, PUT, PATCH, or DELETE that fails in transport, receives HTTP 5xx, or returns an unreadable or unexpected response.
+A write may already have applied. Read the provider's current state and reconcile the result before deciding whether to retry.
+Reads, `read_only: true` POSTs, and HTTP 4xx rejections have `ambiguous? == false`. This flag describes mutation uncertainty, not retryability.
+`request_method` is a Symbol. `request_path` omits query parameters.
+Invalid JSON input fails before dispatch and raises `JSON::GeneratorError`.
+
+The connection removes credentials before a response or error leaves it.
+It knows the configured keys and their Basic authorization value, and it learns more from submitted and returned fields whose names look like credentials.
+In a successful response, a known value of 8 or more bytes is removed wherever it appears. A shorter value is removed only where it is the whole string, so it cannot alter identifiers such as tracking numbers.
+An error's message, body, headers, and request path lose every known value wherever it appears, whatever its length.
+Fields named like credentials are replaced with `[FILTERED]`. Field names are never changed.
+Successful JSON gets only those two rules, so ordinary text such as "Basic Letter" or a signed URL stays intact.
+Error messages and non-JSON error bodies also lose `Basic` and `Bearer` values, `name=value` or `name: value` credentials, and URL user information.
+Accepted documents are returned byte for byte.
+Redaction does not change caller-owned inputs or outbound payloads.
+Client, connection, resource, redactor, and response inspection omit authentication state and payloads.
+Transport errors omit the upstream message and cause because those can retain the authenticated request.
+Ordinary business data remains in responses and can appear in provider error messages.
+
+## Development
+
+```console
+mise exec -- bundle install
+mise exec -- bundle exec rake
+mise exec -- bundle exec rake build
+```
+
+The default Rake task runs RSpec and Standard. CI tests Ruby 3.3 and 3.4.
+Specs use Faraday's test adapter and a loopback HTTP server. They do not call Sendcloud.
+The gemspec packages only the library, README, changelog, and license. The lockfile is not committed.
+
+Add endpoint classes under `SendcloudAPI::Resources` as subclasses of `Base`.
+They receive a connection in their constructor. Use `get(path, params:, allowed:, accept:)` for reads. It rejects filters missing from `allowed` and omits nil filters.
+Use `connection.post`, `connection.put`, `connection.patch`, or `connection.delete` for writes, and `read_only: true` for a POST that only reads.
+`validate_payload!` checks String keys and required fields. `segment` requires a path value and escapes it.
+Add explicit requires in `lib/sendcloud_api.rb` and memoized resource accessors in `Client`.
+
+## Releases
+
+Publishing a GitHub release triggers `release.yml` only in `PostCo/sendcloud_api`.
+Its build job requires the source commit to be merged into `main`, checks that the tag matches `v<VERSION>`, refuses version `0.0.0`, runs tests and lint, builds the gem, and uploads it as an artifact.
+A second job in the GitHub `release` environment downloads that gem and pushes it through RubyGems OIDC.
+Only that job can request an OIDC token, and it runs no repository code or dependencies.
+
+Before the first release, register the RubyGems trusted publisher for owner `PostCo`, repository `sendcloud_api`, workflow `release.yml`, and environment `release`.
+See [RubyGems Trusted Publishing](https://guides.rubygems.org/trusted-publishing/).
+The local Bundler release task runs tests and lint before its tag and publication tasks, but does not enforce main ancestry.

data/lib/sendcloud_api/client.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  class Client
+    DEFAULT_BASE_URL = "https://panel.sendcloud.sc/api/v3/"
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_TIMEOUT = 30
+
+    attr_reader :connection
+
+    def initialize(
+      public_key:,
+      secret_key:,
+      base_url: DEFAULT_BASE_URL,
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      timeout: DEFAULT_TIMEOUT,
+      adapter: Faraday.default_adapter
+    )
+      validate_credential!(:public_key, public_key)
+      validate_credential!(:secret_key, secret_key)
+
+      @connection = Connection.new(
+        public_key: public_key,
+        secret_key: secret_key,
+        base_url: base_url,
+        open_timeout: open_timeout,
+        timeout: timeout,
+        adapter: adapter
+      )
+    end
+
+    def returns
+      @returns ||= Resources::Returns.new(connection)
+    end
+
+    def shipping_options
+      @shipping_options ||= Resources::ShippingOptions.new(connection)
+    end
+
+    def parcel_documents
+      @parcel_documents ||= Resources::ParcelDocuments.new(connection)
+    end
+
+    def parcel_tracking
+      @parcel_tracking ||= Resources::ParcelTracking.new(connection)
+    end
+
+    def contracts
+      @contracts ||= Resources::Contracts.new(connection)
+    end
+
+    def integrations
+      @integrations ||= Resources::Integrations.new(connection)
+    end
+
+    def user
+      @user ||= Resources::User.new(connection)
+    end
+
+    def invoice_items
+      @invoice_items ||= Resources::InvoiceItems.new(connection)
+    end
+
+    def inspect
+      "#<#{self.class}>"
+    end
+
+    private
+
+    def validate_credential!(name, value)
+      return if value.is_a?(String) && !value.strip.empty?
+
+      raise ArgumentError, "#{name} must be a non-empty String"
+    end
+  end
+end

data/lib/sendcloud_api/connection.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "zlib"
+
+module SendcloudAPI
+  class Connection
+    JSON_MEDIA_TYPE = "application/json"
+    ERROR_DETAILS_LIMIT = 1_000
+    NOT_RELATIVE_PATH = %r{\A(?:/|[a-z][a-z0-9+.-]*:)}i
+    ERROR_CLASSES = {
+      400 => BadRequestError,
+      401 => AuthenticationError,
+      403 => ForbiddenError,
+      404 => NotFoundError,
+      405 => MethodNotAllowedError,
+      409 => ConflictError,
+      422 => UnprocessableEntityError,
+      429 => RateLimitError
+    }.freeze
+
+    def initialize(public_key:, secret_key:, base_url:, open_timeout:, timeout:, adapter:)
+      authorization = Faraday::Utils.basic_header_from(public_key, secret_key)
+      @redactor = Redactor.new([public_key, secret_key, authorization, authorization.delete_prefix("Basic ")])
+      @http = Faraday.new(url: normalize_base_url(base_url)) do |connection|
+        connection.headers["Content-Type"] = JSON_MEDIA_TYPE
+        connection.headers["User-Agent"] = "sendcloud_api/#{VERSION}"
+        connection.headers["Authorization"] = authorization
+        connection.options.open_timeout = open_timeout
+        connection.options.timeout = timeout
+        connection.adapter(*Array(adapter))
+      end
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base_url is not a valid URL", cause: nil
+    end
+
+    def get(path, params: {}, accept: JSON_MEDIA_TYPE)
+      request(:get, path, params: params, accept: accept)
+    end
+
+    def post(path, payload:, read_only: false)
+      request(:post, path, payload: payload, write: !read_only)
+    end
+
+    def put(path, payload:)
+      request(:put, path, payload: payload)
+    end
+
+    def patch(path, payload:)
+      request(:patch, path, payload: payload)
+    end
+
+    def delete(path, params: {})
+      request(:delete, path, params: params)
+    end
+
+    def inspect
+      "#<#{self.class}>"
+    end
+
+    private
+
+    def normalize_base_url(base_url)
+      base_url.end_with?("/") ? base_url : "#{base_url}/"
+    end
+
+    def request(method, path, params: {}, payload: nil, accept: JSON_MEDIA_TYPE, write: method != :get)
+      raise ArgumentError, "path must be relative to the base URL, without a scheme or leading slash" if path.match?(NOT_RELATIVE_PATH)
+
+      raise ArgumentError, "path must not contain . or .. segments" if path.split(/[?#]/, 2).first.split("/").any? { |segment| segment == "." || segment == ".." }
+
+      body = serialize(payload) unless payload.nil?
+      redactor = @redactor.with_sensitive_values([payload, params])
+      context = {request_method: method, request_path: redactor.filter_text(path.split("?").first)}
+
+      raw_response = dispatch(method, path, body, params, accept, context, write: write)
+      status = raw_response.status
+      success = (200..299).cover?(status)
+      headers = raw_response.headers.to_h.transform_keys { |key| key.to_s.downcase }
+      kind, body, problem = decode(success, raw_response.body, media_type(headers["content-type"]), accept.downcase)
+      problem ||= "Sendcloud returned empty JSON" if write && body.nil? && status != 204
+      redactor = redactor.with_sensitive_values([headers, body])
+      redactor = redactor.anywhere if problem || !success
+      body = redactor.filter(body) if kind == :json
+      body = redactor.filter_text(body) if kind == :text
+      response = Response.new(status: status, headers: redactor.filter(headers), body: body)
+
+      raise_for_status!(response, redactor, context, write: write)
+      raise ParseError.new(redactor.filter_text(problem), response: response, ambiguous: write, **context), cause: nil if problem
+
+      response
+    end
+
+    def serialize(payload)
+      JSON.generate(payload)
+    rescue JSON::GeneratorError => error
+      raise error.class, @redactor.with_sensitive_values(payload).filter_text(error.message), cause: nil
+    end
+
+    def dispatch(method, path, body, params, accept, context, write:)
+      @http.run_request(method, path, body, {"Accept" => accept}) do |request|
+        request.params.update(params)
+      end
+    rescue URI::InvalidURIError
+      raise ArgumentError, "path is not a valid URL path", cause: nil
+    rescue Faraday::Error, Zlib::Error => error
+      raise TransportError.new("Sendcloud transport failed (#{error.class})", ambiguous: write, **context), cause: nil
+    end
+
+    def media_type(content_type)
+      content_type.to_s.split(";").first.to_s.strip.downcase
+    end
+
+    def json_type?(media_type)
+      media_type == JSON_MEDIA_TYPE || media_type.end_with?("+json")
+    end
+
+    def decode(success, body, media_type, accept)
+      return decode_document(body, media_type, accept) if success && !json_type?(accept)
+      return [:json, nil, nil] if body.nil? || body.empty?
+      return parse_json(body) if media_type.empty? || json_type?(media_type)
+
+      [:text, body.b, ("Sendcloud returned #{media_type_name(media_type)} instead of JSON" if success)]
+    end
+
+    def decode_document(body, media_type, accept)
+      return [:document, nil, "Sendcloud returned an empty body instead of #{accept}"] if body.nil? || body.empty?
+      return [:document, body.b, nil] if media_type == accept
+
+      [:text, body.b, "Sendcloud returned #{media_type_name(media_type)} instead of #{accept}"]
+    end
+
+    def media_type_name(media_type)
+      media_type.empty? ? "no content type" : media_type
+    end
+
+    def parse_json(body)
+      text = body.dup.force_encoding(Encoding::UTF_8)
+      return [:text, text.scrub, "Sendcloud returned invalid JSON"] unless text.valid_encoding?
+
+      parsed = JSON.parse(text)
+      valid_utf8?(parsed) ? [:json, parsed, nil] : [:text, Redactor::FILTERED, "Sendcloud returned invalid JSON"]
+    rescue JSON::ParserError
+      [:text, text, "Sendcloud returned invalid JSON"]
+    end
+
+    def valid_utf8?(value)
+      case value
+      when Hash
+        value.all? { |key, entry| valid_utf8?(key) && valid_utf8?(entry) }
+      when Array
+        value.all? { |entry| valid_utf8?(entry) }
+      when String
+        value.valid_encoding?
+      else
+        true
+      end
+    end
+
+    def raise_for_status!(response, redactor, context, write:)
+      return if response.success?
+
+      error_class = ERROR_CLASSES.fetch(response.status) { (500..599).cover?(response.status) ? ServerError : Error }
+      message = "Sendcloud request failed with HTTP #{response.status}"
+      details = error_details(response.body, response.status)
+      message += ": #{truncate(redactor.filter_text(details))}" if details
+      raise error_class.new(message, response: response,
+        ambiguous: write && (500..599).cover?(response.status), **context), cause: nil
+    end
+
+    def error_details(body, status)
+      return unless body.is_a?(Hash)
+      return body["errors"] if body["errors"].is_a?(String)
+      return unless body["errors"].is_a?(Array)
+
+      details = body["errors"].filter_map do |error|
+        next unless error.is_a?(Hash)
+
+        error = error.except("code") if error["code"].to_s == status.to_s
+        error.values_at("code", "field", "message", "title", "detail", "source")
+          .compact.map { |value| value.is_a?(String) ? value : JSON.generate(value) }.join(" ")
+      end.reject(&:empty?)
+      details.join("; ") unless details.empty?
+    end
+
+    def truncate(details)
+      (details.length > ERROR_DETAILS_LIMIT) ? "#{details[0, ERROR_DETAILS_LIMIT]}..." : details
+    end
+  end
+end

data/lib/sendcloud_api/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  class Error < StandardError
+    attr_reader :response, :request_method, :request_path
+
+    def initialize(message = nil, response: nil, ambiguous: false, request_method: nil, request_path: nil)
+      @response = response
+      @ambiguous = ambiguous
+      @request_method = request_method
+      @request_path = request_path
+      super(message)
+    end
+
+    def ambiguous?
+      @ambiguous
+    end
+
+    def status
+      response&.status
+    end
+
+    def headers
+      response&.headers
+    end
+
+    def body
+      response&.body
+    end
+
+    def retry_after
+      headers&.fetch("retry-after", nil)
+    end
+  end
+
+  class BadRequestError < Error; end
+  class AuthenticationError < Error; end
+  class ForbiddenError < Error; end
+  class NotFoundError < Error; end
+  class MethodNotAllowedError < Error; end
+  class ConflictError < Error; end
+  class UnprocessableEntityError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+  class TransportError < Error; end
+  class ParseError < Error; end
+end

data/lib/sendcloud_api/pagination.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module SendcloudAPI
+  module Pagination
+    LINK_VALUE = /<([^>]*)>([^<]*)/
+    REL = /;\s*rel\s*=\s*(?:"([^"]*)"|([^\s;,]+))/i
+
+    def self.next_params(response, params)
+      url = next_link(response.headers["link"])
+      url ||= response.body["next"] if response.body.is_a?(Hash)
+      return unless url
+
+      params.transform_keys { |key| key.is_a?(String) ? key.to_sym : key }.merge(cursor: cursor(url, response))
+    end
+
+    def self.next_link(header)
+      header.to_s.scan(LINK_VALUE).find do |_url, attributes|
+        rel = attributes.match(REL)
+        rel && (rel[1] || rel[2]).split.any? { |type| type.casecmp?("next") }
+      end&.first
+    end
+
+    def self.cursor(url, response)
+      cursors = URI.decode_www_form(URI(url).query.to_s).filter_map { |name, value| value if name == "cursor" }
+      return cursors.first if cursors.size == 1 && !cursors.first.empty?
+
+      raise ParseError.new("Sendcloud returned a next page URL without one cursor", response: response)
+    rescue URI::InvalidURIError, ArgumentError
+      raise ParseError.new("Sendcloud returned an invalid next page URL", response: response), cause: nil
+    end
+    private_class_method :next_link, :cursor
+  end
+end

data/lib/sendcloud_api/redactor.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module SendcloudAPI
+  class Redactor
+    FILTERED = "[FILTERED]"
+    CREDENTIAL_NAME = /authorization|authentication|password|passwd|secret|token|cookie|api[-_]?key|public[-_]?key/i
+    CREDENTIAL_ASSIGNMENT = /([\w-]*(?:#{CREDENTIAL_NAME.source})[\w-]*["']?\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;&<>]+)/i
+    MINIMUM_EMBEDDED_BYTES = 8
+
+    def initialize(secrets = [], anywhere: false)
+      @secrets = secrets.grep(String).reject(&:empty?).uniq.freeze
+      @anywhere = anywhere
+      variants = @secrets.flat_map { |value| [value, URI.encode_www_form_component(value)] }.map(&:b).uniq.sort_by { |value| -value.bytesize }
+      short, long = variants.partition { |value| value.bytesize < MINIMUM_EMBEDDED_BYTES }
+      @all = union(variants)
+      @embedded = anywhere ? @all : union(long)
+      @whole = anywhere ? [].freeze : short.freeze
+    end
+
+    def with_sensitive_values(value)
+      self.class.new(@secrets + sensitive_values(value), anywhere: @anywhere)
+    end
+
+    def anywhere
+      self.class.new(@secrets, anywhere: true)
+    end
+
+    def filter(value)
+      case value
+      when Hash
+        value.to_h { |key, entry| [key, credential_name?(key) ? FILTERED : filter(entry)] }
+      when Array
+        value.map { |entry| filter(entry) }
+      when String
+        filter_secrets(value)
+      else
+        value
+      end
+    end
+
+    def filter_text(value)
+      filtered = value.b.gsub(@all, FILTERED)
+      filtered = filtered.gsub(%r{(https?://)[^\s/@]+:[^\s/@]+@}i, "\\1#{FILTERED}@")
+      filtered = filtered.gsub(/\b(Bearer|Basic)\s+[^\s,"'<>]+/i, "\\1 #{FILTERED}")
+      filtered.gsub(CREDENTIAL_ASSIGNMENT, "\\1#{FILTERED}").force_encoding(value.encoding)
+    end
+
+    def inspect
+      "#<#{self.class}>"
+    end
+
+    private
+
+    def credential_name?(key)
+      key.to_s.gsub(/[^a-z0-9]/i, "").match?(CREDENTIAL_NAME)
+    end
+
+    def filter_secrets(value)
+      bytes = value.b
+      return FILTERED.dup.force_encoding(value.encoding) if @whole.include?(bytes)
+
+      bytes.gsub(@embedded, FILTERED).force_encoding(value.encoding)
+    end
+
+    def union(values)
+      return /(?!)/n if values.empty?
+
+      Regexp.new(values.map { |value| Regexp.escape(value) }.join("|").b, Regexp::NOENCODING)
+    end
+
+    def sensitive_values(value)
+      case value
+      when Hash
+        value.flat_map { |key, entry| credential_name?(key) ? strings_in(entry) : sensitive_values(entry) }
+      when Array
+        value.flat_map { |entry| sensitive_values(entry) }
+      else
+        []
+      end
+    end
+
+    def strings_in(value)
+      case value
+      when Hash then value.values.flat_map { |entry| strings_in(entry) }
+      when Array then value.flat_map { |entry| strings_in(entry) }
+      when String then [value, value.sub(/\A(?:Bearer|Basic)\s+/i, "")]
+      else []
+      end
+    end
+  end
+end

data/lib/sendcloud_api/resources/base.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module SendcloudAPI
+  module Resources
+    class Base
+      attr_reader :connection
+
+      def initialize(connection)
+        @connection = connection
+      end
+
+      def inspect
+        "#<#{self.class}>"
+      end
+
+      private
+
+      def get(path, params: {}, allowed: [], accept: Connection::JSON_MEDIA_TYPE)
+        params = params.transform_keys { |key| key.is_a?(String) ? key.to_sym : key }
+        unknown = params.keys - allowed
+        raise ArgumentError, "Unknown parameters: #{unknown.map(&:to_s).sort.join(", ")}" unless unknown.empty?
+
+        connection.get(path, params: params.compact, accept: accept)
+      end
+
+      def segment(name, value)
+        require_parameter!(name, value)
+        raise ArgumentError, "#{name} cannot be . or .." if %w[. ..].include?(value.to_s)
+
+        URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+      end
+
+      def validate_payload!(payload, *identifiers)
+        unless payload.is_a?(Hash) && payload.keys.all? { |key| key.is_a?(String) }
+          raise ArgumentError, "payload must be a Hash with Sendcloud JSON field names as String keys"
+        end
+
+        identifiers.each { |name| require_parameter!(name, payload[name]) }
+      end
+
+      def require_parameter!(name, value)
+        missing = value.nil? || (value.is_a?(String) ? value.strip.empty? : value.respond_to?(:empty?) && value.empty?)
+        return unless missing
+
+        raise ArgumentError, "#{name} is required"
+      end
+    end
+  end
+end

data/lib/sendcloud_api/resources/contracts.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  module Resources
+    class Contracts < Base
+      LIST_PARAMETERS = %i[carrier_code is_active client_id name country_code cursor page_size].freeze
+
+      def list(**filters)
+        get("contracts", params: filters, allowed: LIST_PARAMETERS)
+      end
+
+      def create(payload:)
+        validate_payload!(payload, "carrier_code")
+        connection.post("contracts", payload: payload)
+      end
+
+      def retrieve(id:)
+        get("contracts/#{segment(:id, id)}")
+      end
+
+      def update(id:, payload:)
+        validate_payload!(payload)
+        connection.patch("contracts/#{segment(:id, id)}", payload: payload)
+      end
+
+      def delete(id:)
+        connection.delete("contracts/#{segment(:id, id)}")
+      end
+
+      def schemas(carrier_code: nil)
+        get("contracts/schemas", params: {carrier_code: carrier_code}, allowed: %i[carrier_code])
+      end
+    end
+  end
+end

data/lib/sendcloud_api/resources/integrations.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  module Resources
+    class Integrations < Base
+      def retrieve(id:)
+        get("integrations/#{segment(:id, id)}")
+      end
+
+      def update(id:, payload:)
+        validate_payload!(payload)
+        connection.patch("integrations/#{segment(:id, id)}", payload: payload)
+      end
+    end
+  end
+end

data/lib/sendcloud_api/resources/invoice_items.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  module Resources
+    class InvoiceItems < Base
+      LIST_PARAMETERS = %i[created_after created_before parcel_id invoice_id type cursor page_size].freeze
+
+      def list(**filters)
+        get("invoice-items", params: filters, allowed: LIST_PARAMETERS)
+      end
+    end
+  end
+end

data/lib/sendcloud_api/resources/parcel_documents.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  module Resources
+    class ParcelDocuments < Base
+      FORMATS = {pdf: "application/pdf", png: "image/png", zpl: "application/zpl"}.freeze
+      PARAMETERS = %i[dpi paper_size].freeze
+
+      def retrieve(parcel_id:, type:, format:, **options)
+        accept = FORMATS.fetch(format) { raise ArgumentError, "format must be one of: #{FORMATS.keys.join(", ")}" }
+        path = "parcels/#{segment(:parcel_id, parcel_id)}/documents/#{segment(:type, type)}"
+        get(path, params: options, allowed: PARAMETERS, accept: accept)
+      end
+    end
+  end
+end

data/lib/sendcloud_api/resources/parcel_tracking.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  module Resources
+    class ParcelTracking < Base
+      def retrieve(tracking_number:)
+        get("parcels/tracking/#{segment(:tracking_number, tracking_number)}")
+      end
+    end
+  end
+end

data/lib/sendcloud_api/resources/returns.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  module Resources
+    class Returns < Base
+      LIST_PARAMETERS = %i[cursor page_size from_date to_date parent_parcel_status].freeze
+
+      def create(payload:)
+        validate_payload!(payload)
+        connection.post("returns", payload: payload)
+      end
+
+      def validate(payload:)
+        validate_payload!(payload)
+        connection.post("returns/validate", payload: payload, read_only: true)
+      end
+
+      def retrieve(id:)
+        get("returns/#{segment(:id, id)}")
+      end
+
+      def list(**filters)
+        get("returns", params: filters, allowed: LIST_PARAMETERS)
+      end
+
+      def cancel(id:)
+        connection.patch("returns/#{segment(:id, id)}/cancel", payload: {})
+      end
+    end
+  end
+end

data/lib/sendcloud_api/resources/shipping_options.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  module Resources
+    class ShippingOptions < Base
+      def search(payload:)
+        validate_payload!(payload)
+        connection.post("shipping-options", payload: payload, read_only: true)
+      end
+    end
+  end
+end

data/lib/sendcloud_api/resources/user.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  module Resources
+    class User < Base
+      def auth_metadata
+        get("user/auth/metadata")
+      end
+    end
+  end
+end

data/lib/sendcloud_api/response.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  class Response
+    attr_reader :status, :headers, :body
+
+    def initialize(status:, headers:, body:)
+      @status = status
+      @headers = headers.freeze
+      @body = body
+      freeze
+    end
+
+    def content_type
+      headers["content-type"]
+    end
+
+    def success?
+      (200..299).cover?(status)
+    end
+
+    def no_content?
+      status == 204 || body.nil?
+    end
+
+    def inspect
+      "#<#{self.class} status=#{status}>"
+    end
+  end
+end

data/lib/sendcloud_api/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SendcloudAPI
+  VERSION = "0.1.0"
+end

data/lib/sendcloud_api/webhook_signature.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module SendcloudAPI
+  module WebhookSignature
+    HEADER = "Sendcloud-Signature"
+    HEX_SHA256 = /\A\h{64}\z/
+
+    def self.verify(raw_body, signature, secret)
+      raise ArgumentError, "raw_body must be the unparsed request body String" unless raw_body.is_a?(String)
+      raise ArgumentError, "secret must be a non-empty String" unless secret.is_a?(String) && !secret.empty?
+      hex = signature.b if signature.is_a?(String)
+      return false unless hex&.match?(HEX_SHA256)
+
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, raw_body)
+      OpenSSL.fixed_length_secure_compare(expected, hex.downcase)
+    end
+  end
+end

data/lib/sendcloud_api.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "sendcloud_api/version"
+require_relative "sendcloud_api/errors"
+require_relative "sendcloud_api/response"
+require_relative "sendcloud_api/redactor"
+require_relative "sendcloud_api/connection"
+require_relative "sendcloud_api/pagination"
+require_relative "sendcloud_api/webhook_signature"
+require_relative "sendcloud_api/resources/base"
+require_relative "sendcloud_api/resources/returns"
+require_relative "sendcloud_api/resources/shipping_options"
+require_relative "sendcloud_api/resources/parcel_documents"
+require_relative "sendcloud_api/resources/parcel_tracking"
+require_relative "sendcloud_api/resources/contracts"
+require_relative "sendcloud_api/resources/integrations"
+require_relative "sendcloud_api/resources/user"
+require_relative "sendcloud_api/resources/invoice_items"
+require_relative "sendcloud_api/client"
+
+module SendcloudAPI
+end

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: sendcloud_api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- PostCo
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: uri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.11'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.12'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.12'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.35'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.35'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+description: A small, explicit Ruby client for Sendcloud API v3 reads and writes,
+  without automatic retries.
+email:
+- engineering@postco.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/sendcloud_api.rb
+- lib/sendcloud_api/client.rb
+- lib/sendcloud_api/connection.rb
+- lib/sendcloud_api/errors.rb
+- lib/sendcloud_api/pagination.rb
+- lib/sendcloud_api/redactor.rb
+- lib/sendcloud_api/resources/base.rb
+- lib/sendcloud_api/resources/contracts.rb
+- lib/sendcloud_api/resources/integrations.rb
+- lib/sendcloud_api/resources/invoice_items.rb
+- lib/sendcloud_api/resources/parcel_documents.rb
+- lib/sendcloud_api/resources/parcel_tracking.rb
+- lib/sendcloud_api/resources/returns.rb
+- lib/sendcloud_api/resources/shipping_options.rb
+- lib/sendcloud_api/resources/user.rb
+- lib/sendcloud_api/response.rb
+- lib/sendcloud_api/version.rb
+- lib/sendcloud_api/webhook_signature.rb
+homepage: https://github.com/PostCo/sendcloud_api
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/PostCo/sendcloud_api
+  source_code_uri: https://github.com/PostCo/sendcloud_api
+  changelog_uri: https://github.com/PostCo/sendcloud_api/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A Ruby client for the Sendcloud API v3
+test_files: []