qube_sync 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d91d913272b0ecdd7f2b2bf91b584e2ab2291841a3badf4641d67d385841b51
-  data.tar.gz: 00d4062eead7a747ddc51ee0eaf44f5e25799532028b3ed30343ec25f7e7843e
+  metadata.gz: 1eac592828778d486630d76ff7d8b43072a5006682c1b8182f1c5e13f48097f2
+  data.tar.gz: 04de6f5cc7db7be2569186733e1961f291348d96e8a23dcf832ab4f40a96d722
 SHA512:
-  metadata.gz: b244afce7cc38609ca0b100fb4f85102c13ca194d7d5cfd61d792950c37402cf84dd28e868830be11060bf5948482607ef206749c9b6c5b7f302da9df2883db6
-  data.tar.gz: 923cf67564f27f9be8a715ec059bdb4dfa70befc478eaeba7188bfe3a02c203b21b63d68e4db827c3d55727c4070c4c3d7f2c229f603dc75e109a7e6d9e7db8f
+  metadata.gz: 1011b04d773e99fb8fa441608c11f2d37a173ded5a98a41c07b3237eaa0cc67a3ea460a5fda24b9b39e39441c4dcc2a12cbe0a8c69b2d9994f89d765117a18d5
+  data.tar.gz: 5f681be6ee755144dfae40d73d2a8d3d9eb0a43ceeea9a9c712c89e09719f9a86f52bd6e3dfd056f5a00d660d1ef518f3a22eb0a6a06bccbcd54d54c465ac9a0

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 ## [Unreleased]
 
+- Releases publish through RubyGems trusted publishing, from `release.yml`'s OIDC token; no
+  API key is stored.
+
+## [0.4.0] - 2026-10-25
+
+Adds `QubeSync::Client`, a client for the v2 API. Nothing existing changes: the v1 module
+functions still call `/api/v1` and read `QUBE_API_KEY` and `QUBE_URL`, and are now documented as
+legacy (no runtime warning). New code should use the client.
+
+- `QubeSync::Client.new(api_key:, base_url: "https://qubesync.com", open_timeout: 5,
+  read_timeout: 30, max_retries: 2, total_timeout: 60, on_retry: nil)`. It takes the key as an argument and never reads the
+  environment, sends it as Basic auth, and never shows it in `inspect`. `require
+  "qube_sync/client"` loads it alone, on the standard library (Net::HTTP), without Faraday.
+- Connections: `create_connection`, `get_connection`, `list_connections`, `update_connection`,
+  `delete_connection`, `regenerate_onboarding`, `set_password`, `get_qwc`.
+- Runs and questions: `start_run` (its `reference` is the Idempotency-Key), `get_run`,
+  `list_runs`, `cancel_run`, `run_events`, `answer`, `search`. Methods that take a link refuse
+  one on another scheme, host or port with `ArgumentError`, before any request.
+- QuickBooks operations: one method per operation on its entity, `client.customer.create`,
+  `client.invoice.query`, `client.txn_void.execute`... (261 operations on 124 entities;
+  QuickBooks' `class` is `client.class_`), each `(connection_id, params = {}, webhook_url:,
+  idempotency_key: nil)`. They're generated from the QuickBooks operations manifest
+  (`spec/fixtures/operations.json`, served at https://qubesync.com/libraries/operations.json)
+  by `bin/generate-operations` (`rake operations:generate`), with YARD docs listing every field
+  and RBS records for the params in `sig/qube_sync/operations/`. An entity's file loads on first
+  use. CI fails when the generated files or the vendored manifest drift.
+- `queue(operation_id, connection_id, params = {}, webhook_url:, idempotency_key: nil, method:
+  nil, path: nil)` queues an operation by its id; `method:` and `path:` send one this version
+  doesn't know. A query string repeats an array's key and brackets nested Hashes.
+- Requests: `queue_qbxml`, `get_request`, `request_pages`, `list_requests`, `each_request`
+  (every page), `discard_request`; and `request` for anything else. Operations and
+  `queue_qbxml` make an Idempotency-Key per call when none is given, and reuse it on that call's
+  retries.
+- Signatures for the whole client in `sig/` (`rbs -I sig validate` runs in CI).
+- Retries: a GET, PUT, DELETE or a request with an Idempotency-Key is retried twice (0.5 s, then
+  1 s) on a failed connection, a timeout, or a 429, 502, 503 or 504, honouring `Retry-After` up
+  to 30 s. `answer` is retried too when its link has a `prompt_token`. Anything else outside 2xx
+  raises `QubeSync::APIError` (a `QubeSync::Error`) with `status`, `errors`, `code`, `message`,
+  `body` and `request_id`.
+- A call returns or raises within `total_timeout` (60 s), retries and their waits included: each
+  attempt's timeouts are cut to the time left, and no retry is made unless a second is left after
+  its wait.
+- `on_retry:` is called before each retry's wait with a frozen Hash (`attempt`, `max_retries`,
+  `delay`, `elapsed`, `method`, `url` without its query, `status`, `error`); an exception it
+  raises stops the call.
+- A retried DELETE that gets a 404 after an earlier attempt's answer was lost (a read timeout, a
+  reset or closed connection, a 502 or 504) returns nil, as a 204 would.
+
 ## [0.3.0] - 2026-10-23
 
 Adds `QubeSync::Webhooks`, which verifies a delivery and parses it into a typed event. Nothing

data/README.md

@@ -1,6 +1,7 @@
 # QUBESync
 
-A simple wrapper around the QUBE Sync API.
+The Ruby library for the [QuBe Sync](https://qubesync.com) API: a client for the v2 API, and
+webhook verification. The API's docs are at https://docs.qubesync.com.
 
 ## Installation
 
@@ -14,14 +15,245 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install qube_sync
 
-## Configuration
+## The v2 client
+
+`QubeSync::Client` calls the v2 API. Make one from your app's configuration: it never reads the
+environment itself, so one app can hold a sandbox and a production client at once.
+
+```ruby
+require "qube_sync" # or require "qube_sync/client" alone: it uses only the standard library
+
+QUBE = QubeSync::Client.new(api_key: ENV.fetch("QUBE_API_KEY"))
+```
+
+`base_url:` (default `"https://qubesync.com"`), `open_timeout:` (5 s), `read_timeout:` (30 s),
+`max_retries:` (2), `total_timeout:` (60 s) and `on_retry:` are options (see Retries below). Every method returns the response's `data`, a plain Hash or Array
+with String keys, and nil for an empty answer.
+
+### Onboarding a customer
+
+```ruby
+connection = QUBE.create_connection(webhook_url: "https://myapp.example/qube/connections", name: "Acme Ltd")
+customer.update!(qube_connection_id: connection["id"])
+
+redirect_to connection["links"]["onboarding"], allow_other_host: true
+```
+
+QuBe Sync sends `connection.connected` to the connection's `webhook_url` once the customer's Web
+Connector first checks in. `regenerate_onboarding(id)` makes a fresh onboarding link, and
+`update_connection(id, webhook_url:, name:)` changes either. `get_connection`,
+`list_connections`, `delete_connection`, `set_password(id, password: nil)` and `get_qwc(id)` (the
+QWC file's XML) are there for setup without hosted onboarding.
+
+### Starting a run and answering its question
+
+```ruby
+run = QUBE.start_run(
+  connection_id, "sync_customer", {"customer" => {"name" => "Acme Ltd"}},
+  reference: "customer-#{customer.id}",          # also sent as the Idempotency-Key
+  webhook_url: "https://myapp.example/qube/runs"
+)
+
+# Later, a workflow_run webhook says the run is awaiting input. Its links are the run's own:
+event = QubeSync::Webhooks.verify(raw_body, header, secrets: ENV.fetch("QUBE_WEBHOOK_SECRET"))
+if event.awaiting_input?
+  matches = QUBE.search(event.links["search"], field: "customer", q: "Acme") # a record field's choices
+  QUBE.answer(event.links["decisions"], choice: "rename", data: {"name" => "Acme Ltd (2)"})
+end
+```
+
+`get_run(run_url)` or `get_run(connection_id, run_id)` reads a run, `list_runs(connection_id,
+reference:, state:, outcome:)` finds runs, `cancel_run(cancel_url, reason: nil)` cancels one, and
+`run_events(connection_id, run_id, after:, limit:)` returns a page of its event log whole
+(`{"data" => [...], "next_after" => ...}`). A method that takes a link takes it from a webhook's
+or a run's `links`, or a path under `/api/v2`. A link on any other scheme, host or port raises
+`ArgumentError` before a request is made, so the API key only ever goes to QuBe Sync.
+
+### Queueing an operation
+
+Every QuickBooks operation is a method on its entity: `client.<entity>.<action>`, where the
+action is `create`, `update`, `query`, `delete` or `execute`.
+
+```ruby
+hook = "https://myapp.example/qube/requests"
+
+request = QUBE.customer.create(connection_id, {
+  name: "Acme Ltd",
+  bill_address: {addr1: "1 Main St", city: "Austin", state: "TX"}
+}, webhook_url: hook)
+
+# A query sends its filters as the query string; nested filters are fine.
+QUBE.invoice.query(connection_id, {
+  modified_date_range_filter: {from_modified_date: "2026-10-01T00:00:00"},
+  include_line_items: true,
+  iterator: true, max_returned: 50 # pages of 50, each its own webhook
+}, webhook_url: hook)
+
+QUBE.txn_void.execute(connection_id, {txn_void_type: "Invoice", txn_id: "1A2-1700000000"}, webhook_url: hook)
+
+# qbXML as written.
+QUBE.queue_qbxml(connection_id, request_xml, webhook_url: hook)
+```
+
+- Each method is `(connection_id, params = {}, webhook_url:, idempotency_key: nil)` and returns
+  the queued request. Its documentation (YARD, in `lib/qube_sync/operations/<entity>.rb`) lists
+  every field, nested ones included, says whether QuickBooks answers in pages, and links the API
+  reference. The params' types are RBS records in `sig/qube_sync/operations/`, for Steep or an
+  editor that reads RBS.
+- An entity's file loads the first time you use it, so `require "qube_sync/client"` stays quick.
+- QuickBooks' `class` entity is `client.class_` (`client.class` is Ruby's).
+- `queue(operation_id, connection_id, params = {}, webhook_url:, idempotency_key: nil)` queues one
+  by its id: `QUBE.queue("customer.create", connection_id, {name: "Acme Ltd"}, webhook_url: hook)`
+  sends the same request as `QUBE.customer.create`. For an operation newer than your version of
+  the gem, pass `method:` and `path:` (relative to the connection):
+  `QUBE.queue("widget.create", connection_id, params, webhook_url: hook, method: :post, path: "widgets")`.
+- A query string repeats an array's key (`list_id=1&list_id=2`) and brackets nested Hashes
+  (`name_range_filter[from_name]=A`, `currency_filter[list_id][]=1`), as the API reads them.
+
+The answer comes to `webhook_url` (see Webhooks below). `get_request(connection_id, id)`,
+`request_pages(connection_id, id)` and `discard_request(connection_id, id)` act on one request.
+`list_requests(connection_id, page:, page_size:, state:, ...)` returns a page whole (`{"data" =>
+[...], "meta" => {"page" => 1, "total_pages" => 3}}`), and `each_request(connection_id, **filters)`
+yields every request on every page (an Enumerator without a block).
+
+`request(method, path_or_url, body = nil, query: {}, headers: {})` calls anything else and returns
+the whole parsed body.
+
+### Retries, idempotency and errors
+
+- A GET, PUT or DELETE, or any request with an `Idempotency-Key`, is retried up to `max_retries`
+  times (after 0.5 s, then 1 s) when the connection fails or times out, or QuBe Sync answers 429,
+  502, 503 or 504. A `Retry-After` on a 429 or 503 is honoured, up to 30 s. Other requests
+  (`create_connection`, `cancel_run`...) are sent once.
+- A call returns or raises within `total_timeout` (60 s), retries and their waits included: each
+  attempt's timeouts are cut to the time left, and a retry is made only when at least a second
+  would be left after its wait (a `Retry-After` that doesn't fit isn't waited, nor shortened; the
+  call raises what the last attempt got). Pass `max_retries: 0` for calls made while a user waits
+  on a page, if 60 s is too long.
+- `answer` is retried when its link has a `prompt_token`, as a run's `links.decisions` always
+  does while it asks. A retry after a lost answer may raise a 409 with code `prompt_changed`:
+  the question has been answered, by the first attempt or by someone else. Without a
+  `prompt_token` it's sent once, since an answer sent again could be taken for the run's next
+  question.
+- A retried DELETE (`delete_connection`, or `request(:delete, ...)`) that gets a 404 returns nil,
+  as a 204 would, when an earlier attempt's answer was lost after the request could have reached
+  QuBe Sync (a read timeout, a connection reset or closed, a 502 or 504): that attempt deleted it.
+  Any other 404 raises, including a retry's after a refused connection, a connect timeout, a 429
+  or a 503.
+- `on_retry:` takes a callable, called before each retry's wait with a frozen Hash: `attempt`
+  (1, 2...), `max_retries`, `delay` and `elapsed` (seconds), `method`, `url` (without its query
+  string), `status` (for a status retry) and `error` (for a network failure), and never the key,
+  headers or body. It isn't called when no retry is made. An exception it raises stops the call
+  and reaches the caller.
+
+  ```ruby
+  QubeSync::Client.new(api_key: ENV.fetch("QUBE_API_KEY"),
+    on_retry: ->(r) { Rails.logger.warn("QuBe Sync retry #{r[:attempt]}/#{r[:max_retries]} #{r[:method]} #{r[:url]} #{r[:status] || r[:error].class}") })
+  ```
+- `start_run` sends `reference` as the Idempotency-Key. `queue` and `queue_qbxml` take
+  `idempotency_key:`; without one the client makes a UUID per call and sends it again on that
+  call's retries, so a retry never queues a request twice.
+- Any other answer outside 2xx raises `QubeSync::APIError` (a `QubeSync::Error`): `status`,
+  `errors` (the body's `errors` as parsed), `code` (`errors["code"]`, such as `prompt_changed`, or
+  nil), `message` (one line, safe to log), `body` and `request_id` (the `x-request-id` header, for
+  support). A connection that still fails after the retries raises Ruby's own error
+  (`Net::OpenTimeout`, `Net::ReadTimeout`, `Errno::ECONNREFUSED`...).
+- The API key never appears in an error or in `inspect`.
+
+```ruby
+begin
+  QUBE.answer(decisions_url, choice: "rename")
+rescue QubeSync::APIError => e
+  raise unless e.code == "prompt_changed" # the question changed: show the new one
+  refresh_question(run)
+end
+```
+
+## Webhooks
+
+`QubeSync::Webhooks` verifies a delivery's `X-QUBE-Signature` header and parses the body into a
+typed event. It doesn't need Rails or Rack, and never reads the environment: pass it the raw body,
+the header and your webhook secret.
+
+```ruby
+require "qube_sync"
+
+# raw_body: the request body exactly as received, before anything parses it.
+# header:   the X-QUBE-Signature header (nil when it's absent).
+def handle_qube_webhook(raw_body, header)
+  event = QubeSync::Webhooks.verify(raw_body, header, secrets: ENV.fetch("QUBE_WEBHOOK_SECRET"))
+
+  case event.type
+  when "request"
+    # A queued request's answer. Deduplicate on event.dedupe_key ("<page_request_id>:<state>").
+    # event.response_json, event.error, event.page, event.iteration_state
+  when "workflow_run"
+    # A run is waiting for an answer, or has ended. Skip it unless event.newer_than?(stored)
+    # for the revision stored with event.reference: deliveries can arrive out of order.
+    # event.awaiting_input? / completed? / failed? / cancelled?, event.prompt, event.output
+  when "notification"
+    # Data a running workflow sent. Deduplicate on event.dedupe_key (the delivery_id), and
+    # never skip one by revision. event.name, event.data
+  when "connection"
+    # Connected, setup cancelled, stalled or resumed. Deduplicate on event.dedupe_key, and skip
+    # it unless event.newer_than?(the revision stored for event.connection_id).
+  when "name_index"
+    # event.connection_id, event.name_index
+  else
+    # An event this version doesn't know yet: acknowledge it.
+  end
+
+  200
+rescue QubeSync::Webhooks::SignatureError => e
+  # e.reason is :missing, :malformed, :stale or :mismatch. The message is safe to log.
+  warn "QuBe Sync webhook refused: #{e.message}"
+  401
+end
+```
+
+- `secrets:` takes one secret or a list. While a secret rotates, a delivery carries one `v1`
+  signature per active secret, and either secret verifies it.
+- The timestamp must be within 300 seconds of now, either way. `tolerance:` (seconds) sets
+  another window, and `now:` (unix seconds or a `Time`) sets the clock, for tests.
+- Every event has `type`, `event`, `timestamp`, `app_id`, `sandbox`, `dedupe_key` and `to_h`
+  (the whole body). A missing key reads as `nil`, and `event["any_key"]` reads any other key.
+- `QubeSync::Webhooks.parse(raw_body)` builds the event without verifying it, for tests or for
+  code that verified the delivery elsewhere.
+
+In Rails, read the raw body with `request.raw_post`:
+
+```ruby
+class QubeWebhooksController < ActionController::API
+  def create
+    event = QubeSync::Webhooks.verify(
+      request.raw_post,
+      request.headers[QubeSync::Webhooks::HEADER],
+      secrets: Rails.application.credentials.qube_webhook_secret
+    )
+    QubeWebhookJob.perform_later(event.to_h) # route by type in the job, as above
+    head :ok
+  rescue QubeSync::Webhooks::SignatureError => e
+    Rails.logger.warn("QuBe Sync webhook refused: #{e.message}")
+    head :unauthorized
+  end
+end
+```
+
+`QubeSync.verify_and_build_webhook!` (0.2.4) still works, and still returns the parsed Hash.
+
+## v1 (legacy)
+
+The v1 module functions below call `/api/v1` and still work, but the v2 client above is the one to
+use for new code.
+
+### Configuration
 
 You'll need to set two evironment variables in your application to use this gem:
 
 `QUBE_API_KEY` - This is your API key, which you can find in your QUBE Sync application's settings.
 `QUBE_WEBHOOK_SECRET` - This is the secret key used to sign the webhook payloads. You can find this in your QUBE Sync application's settings.
 
-## Usage
+### Usage
 
 ```ruby
 require 'qube_sync'
@@ -128,78 +360,6 @@ QubeSync.verify_and_build_webhook!(request.body.read, request.headers['X-Qube-Si
 QubeSync.verify_and_build_webhook!(request.body.read, request.headers['X-Qube-Signature'], max_age: 120)
 ```
 
-## Webhooks
-
-`QubeSync::Webhooks` verifies a delivery's `X-QUBE-Signature` header and parses the body into a
-typed event. It doesn't need Rails or Rack, and never reads the environment: pass it the raw body,
-the header and your webhook secret.
-
-```ruby
-require "qube_sync"
-
-# raw_body: the request body exactly as received, before anything parses it.
-# header:   the X-QUBE-Signature header (nil when it's absent).
-def handle_qube_webhook(raw_body, header)
-  event = QubeSync::Webhooks.verify(raw_body, header, secrets: ENV.fetch("QUBE_WEBHOOK_SECRET"))
-
-  case event.type
-  when "request"
-    # A queued request's answer. Deduplicate on event.dedupe_key ("<page_request_id>:<state>").
-    # event.response_json, event.error, event.page, event.iteration_state
-  when "workflow_run"
-    # A run is waiting for an answer, or has ended. Skip it unless event.newer_than?(stored)
-    # for the revision stored with event.reference: deliveries can arrive out of order.
-    # event.awaiting_input? / completed? / failed? / cancelled?, event.prompt, event.output
-  when "notification"
-    # Data a running workflow sent. Deduplicate on event.dedupe_key (the delivery_id), and
-    # never skip one by revision. event.name, event.data
-  when "connection"
-    # Connected, setup cancelled, stalled or resumed. Deduplicate on event.dedupe_key, and skip
-    # it unless event.newer_than?(the revision stored for event.connection_id).
-  when "name_index"
-    # event.connection_id, event.name_index
-  else
-    # An event this version doesn't know yet: acknowledge it.
-  end
-
-  200
-rescue QubeSync::Webhooks::SignatureError => e
-  # e.reason is :missing, :malformed, :stale or :mismatch. The message is safe to log.
-  warn "QuBe Sync webhook refused: #{e.message}"
-  401
-end
-```
-
-- `secrets:` takes one secret or a list. While a secret rotates, a delivery carries one `v1`
-  signature per active secret, and either secret verifies it.
-- The timestamp must be within 300 seconds of now, either way. `tolerance:` (seconds) sets
-  another window, and `now:` (unix seconds or a `Time`) sets the clock, for tests.
-- Every event has `type`, `event`, `timestamp`, `app_id`, `sandbox`, `dedupe_key` and `to_h`
-  (the whole body). A missing key reads as `nil`, and `event["any_key"]` reads any other key.
-- `QubeSync::Webhooks.parse(raw_body)` builds the event without verifying it, for tests or for
-  code that verified the delivery elsewhere.
-
-In Rails, read the raw body with `request.raw_post`:
-
-```ruby
-class QubeWebhooksController < ActionController::API
-  def create
-    event = QubeSync::Webhooks.verify(
-      request.raw_post,
-      request.headers[QubeSync::Webhooks::HEADER],
-      secrets: Rails.application.credentials.qube_webhook_secret
-    )
-    QubeWebhookJob.perform_later(event.to_h) # route by type in the job, as above
-    head :ok
-  rescue QubeSync::Webhooks::SignatureError => e
-    Rails.logger.warn("QuBe Sync webhook refused: #{e.message}")
-    head :unauthorized
-  end
-end
-```
-
-`QubeSync.verify_and_build_webhook!` (0.2.4) still works, and still returns the parsed Hash.
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -6,3 +6,15 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+namespace :operations do
+  desc "Write the per-operation methods and signatures from spec/fixtures/operations.json"
+  task :generate do
+    ruby "bin/generate-operations"
+  end
+
+  desc "Fail when the generated operations are stale, missing or orphaned"
+  task :check do
+    ruby "bin/generate-operations", "--check"
+  end
+end