qubesync 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,42 @@
 # Changelog
 
-## 0.1.0 (unreleased)
+## 0.2.0 (2026-10-25)
+
+The v2 API client.
+
+- `new Client({ apiKey, baseUrl = "https://qubesync.com", connectTimeout = 5000, timeout = 30000, maxRetries = 2 })`:
+  Basic auth with the key passed in (the environment is never read), and the key never in
+  `util.inspect`, `JSON.stringify` or an error.
+- Connections: `createConnection`, `getConnection`, `listConnections`, `updateConnection`,
+  `deleteConnection`, `regenerateOnboarding`, `setPassword`, `getQwc`.
+- Runs: `startRun` (the `reference` is the Idempotency-Key), `getRun` by link or ids, `listRuns`,
+  `cancelRun`, `runEvents`. Questions: `answer`, `search`.
+- Every QuickBooks operation as a method, entity then action: `qube.customer.create(connectionId,
+  params, { webhookUrl, idempotencyKey })`, `qube.customerMsg.query(...)`, `qube.txnVoid.execute(...)`
+  (261 operations on 124 entities). Each entity's module loads on first use, and can be imported
+  alone (`qubesync/operations/<entity>`). Generated from the QuBe Sync operations manifest
+  (`test/fixtures/operations.json`, served at https://qubesync.com/libraries/operations.json) by
+  `node scripts/generate-operations.js`, with full nested param types and every field's description
+  in `operations/*.d.ts`; CI fails when the generated files or the vendored manifest drift.
+- Query params: nested objects go bracketed (`name_range[from]=A`), arrays of scalars as a repeated key.
+- `queue(operationId, connectionId, params, { webhookUrl, idempotencyKey, method, path })` queues by
+  operation id; an id this version doesn't know needs `method` and `path`.
+- Requests: `queueQbxml`, `getRequest`, `requestPages`, `listRequests`, `eachRequest` (an async
+  iterator over every page), `discardRequest`; `request` for anything else.
+- Links are refused unless they're on the client's own origin.
+- Retries for retry-safe requests on a failed connection, a timeout, 429, 502, 503 and 504, with
+  `Retry-After` honoured up to 30 s. `answer` is retried when its link has a `prompt_token`.
+- `totalTimeout` (60000 ms): a call returns or rejects within it, retries and waits included; each
+  attempt's timeouts are cut to the time left, and a retry that would leave under 1 s isn't made.
+- `onRetry({ attempt, maxRetries, delayMs, elapsedMs, method, url, status, error })` before each
+  retry's wait; the URL without its query, never the key; a throw stops the call.
+- A retried DELETE that gets a 404 after an earlier attempt's answer was lost (a read timeout, a
+  reset after connecting, a 502 or 504) resolves to `null`, as a 204 would.
+- `APIError` with `status`, `code`, `message`, `errors`, `body` and `requestId`.
+- Releases publish through npm trusted publishing, from `release.yml`'s OIDC token; no npm
+  token is stored.
+
+## 0.1.0 (2026-10-24)
 
 First version: webhooks only.
 
@@ -16,4 +52,4 @@ First version: webhooks only.
 - CommonJS and ESM entry points, TypeScript declarations, zero dependencies, Node 16.17 and later.
 - Tested against the server's own test vectors (`test/fixtures/test_vectors.json`), and CI checks
   that copy against https://qubesync.com/webhooks/test_vectors.json.
-- A `v*` tag publishes to npm (`release.yml`, with the `NPM_TOKEN` secret).
+- A `v*` tag publishes to npm (`release.yml`).

package/README.md

@@ -1,13 +1,192 @@
 # qubesync (Node)
 
-Verify and parse [QuBe Sync](https://qubesync.com) webhooks: QuickBooks Desktop through
-qubesync.com. Plain JavaScript, zero dependencies, Node 16.17 and later, CommonJS and ESM,
-TypeScript declarations included.
+The [QuBe Sync](https://qubesync.com) v2 API client, and webhook verification and parsing:
+QuickBooks Desktop through qubesync.com. Plain JavaScript, zero dependencies, Node 16.17 and
+later, CommonJS and ESM, TypeScript declarations included. API docs: https://docs.qubesync.com.
 
 ```bash
 npm install qubesync
 ```
 
+## The v2 client
+
+Make one client with your app's API key. The library never reads the environment, so pass the
+key in (and hold a sandbox and a production client at once if you need both):
+
+```js
+const { Client, APIError } = require("qubesync"); // or: import { Client, APIError } from "qubesync";
+
+const qube = new Client({ apiKey: process.env.QUBE_API_KEY });
+```
+
+`new Client({ apiKey, baseUrl = "https://qubesync.com", connectTimeout = 5000, timeout = 30000, maxRetries = 2, totalTimeout = 60000, onRetry })`.
+Timeouts are in milliseconds: `connectTimeout` to open the connection, `timeout` for the socket to
+sit idle waiting for the answer, and `totalTimeout` for the whole call (see below). Every method returns a Promise of the response's `data`, with
+the API's own snake_case keys (`webhook_url`, `total_pages`), or `null` for an empty answer.
+
+### Onboarding a customer
+
+```js
+const connection = await qube.createConnection({ webhookUrl: "https://app.example.com/webhooks/qube", name: "Acme" });
+// Store connection.id, and send your customer to connection.links.onboarding.
+// A connection.connected webhook arrives once their Web Connector checks in.
+
+const fresh = await qube.regenerateOnboarding(connection.id); // a new onboarding link
+```
+
+Also `getConnection(id)`, `listConnections()`, `updateConnection(id, { webhookUrl, name })`,
+`deleteConnection(id)`, and for setup without hosted onboarding `setPassword(id, { password })`
+(leave `password` out to have one generated) and `getQwc(id)` (the QWC file's XML, a string).
+
+### Starting a run and answering its question
+
+```js
+const run = await qube.startRun(connectionId, "customer_sync", { customer: { name: "Acme" } }, {
+  reference: "customer-1042", // your own id for the run, and its Idempotency-Key
+  webhookUrl: "https://app.example.com/webhooks/qube",
+});
+
+// Later, in the workflow_run.awaiting_input webhook (event.prompt), answer by choice:
+await qube.answer(event.prompt.links.decisions, { choice: "use_existing", data: { customer: "80000001-1700000000" } });
+// A question's record field: search QuickBooks with the prompt's search link.
+const matches = await qube.search(event.prompt.links.search, { field: "customer", q: "Acm" });
+```
+
+Also `getRun(runUrl)` (a run's `links.run`) or `getRun(connectionId, runId)`,
+`listRuns(connectionId, { reference, state, outcome })`, `cancelRun(run.links.cancel, { reason })` and
+`runEvents(connectionId, runId, { after, limit })`, which returns the whole body,
+`{ data, next_after }`.
+
+Links (`links.run`, `links.decisions`, `links.search`, `links.cancel`) are used as they come, query
+string included. A link on another origin than the client's `baseUrl` (scheme, host and port) is
+refused with a `TypeError` before any request, so the API key only ever goes to QuBe Sync.
+
+### Queueing an operation
+
+Every QuickBooks operation is a method, entity then action: `create`, `update`, `query`, `delete` or
+`execute`. Each takes the connection id, the params (the API's own snake_case fields) and
+`{ webhookUrl, idempotencyKey }`, and resolves to the queued request; the answer arrives at
+`webhookUrl`.
+
+```js
+// POST /connections/{id}/customers
+const queued = await qube.customer.create(connectionId, {
+  name: "Acme",
+  bill_address: { addr1: "1 Main St", city: "Austin", state: "TX", postal_code: "78701" },
+}, { webhookUrl: "https://app.example.com/webhooks/qube" });
+
+// GET /connections/{id}/invoices: a query's params go in the query string.
+await qube.invoice.query(connectionId, {
+  modified_date_range_filter: { from_modified_date: "2026-10-01T00:00:00Z" },
+  include_line_items: true,
+}, { webhookUrl: "https://app.example.com/webhooks/qube" });
+
+await qube.customerMsg.query(connectionId, {}, { webhookUrl: "https://app.example.com/webhooks/qube" });
+await qube.txnVoid.execute(connectionId, { txn_id: "1A2B-1700000000", txn_void_type: "Invoice" }, {
+  webhookUrl: "https://app.example.com/webhooks/qube",
+});
+```
+
+Each entity's module loads the first time you use it (`qube.customer`), so the 124 of them cost
+nothing until then. A bundled app can import one alone:
+`const { Customer } = require("qubesync/operations/customer"); new Customer(qube).create(...)`.
+
+The types are in `operations/<entity>.d.ts` (and nested ones shared between entities in
+`operations/types.d.ts`): every field with its description, required where QuickBooks requires it,
+enums as literal unions, so an editor completes and checks the params. Each method's doc says whether
+QuickBooks answers in pages (each page comes as its own webhook) and links its
+[API reference](https://docs.qubesync.com) page. They're generated from the QuBe Sync operations
+manifest (`node scripts/generate-operations.js`), not written by hand.
+
+`queue(operationId, connectionId, params, { webhookUrl, idempotencyKey, method, path })` queues an
+operation by its id, the same as the method: `qube.queue("customer.create", connectionId, params, options)`.
+For an operation newer than this version, pass `method` and `path` (relative to the connection):
+`qube.queue("widget.create", connectionId, params, { webhookUrl, method: "POST", path: "widgets" })`.
+
+qbXML as written:
+
+```js
+await qube.queueQbxml(connectionId, requestXml, { webhookUrl: "https://app.example.com/webhooks/qube" });
+```
+
+Also `getRequest(connectionId, id)`, `requestPages(connectionId, id)`, `discardRequest(connectionId, id)`,
+and `listRequests(connectionId, { page, pageSize, state, webhookState, sort, sortDirection, searchPhrase })`,
+which returns the whole body, `{ data, meta: { page, total_pages } }`. To walk every page:
+
+```js
+for await (const request of qube.eachRequest(connectionId, { state: "errored" })) {
+  console.log(request.id);
+}
+```
+
+### Anything else
+
+`request(method, pathOrUrl, body, { query, headers })` sends any v2 call, a path under `/api/v2`
+(`"/workflows"`) or a same-origin URL, and returns the parsed body whole.
+
+### Retries and idempotency
+
+A request that's safe to send again (a GET, PUT or DELETE, or one with an `Idempotency-Key`) is
+retried up to `maxRetries` times, 0.5 s then 1 s apart, when the connection fails or times out, or
+QuBe Sync answers 429, 502, 503 or 504 (a 429 or 503's `Retry-After` is honoured, up to 30 s).
+
+- `startRun` sends `reference` as the Idempotency-Key, so a retried start never starts two runs.
+- Every operation method, `queue` and `queueQbxml` take `idempotencyKey`; left out, the client makes
+  a UUID per call and sends it again on that call's retries, so a retry never queues a request twice.
+- `answer` is retried when its link has a `prompt_token` (a run's `links.decisions` always does
+  while it asks). A retry after a lost answer may reject with a `409` whose `code` is
+  `prompt_changed`: the question has been answered, by the first attempt or by someone else.
+  Without a `prompt_token` it's sent once, since a repeat could be taken for the run's next question.
+- The other POSTs (`createConnection`, `cancelRun`, `setPassword`, `getQwc`,
+  `regenerateOnboarding`, `discardRequest`) are sent once.
+- A retried DELETE (`deleteConnection`, or `request("DELETE", ...)`) that gets a `404` resolves to
+  `null`, as a 204 would, when an earlier attempt's answer was lost after the request could have
+  arrived (a read timeout, a connection reset after it opened, a 502 or 504): that attempt may have
+  deleted it. Any other 404 still rejects, including a retry's after a refused connection, a
+  connect timeout, a 429 or a 503.
+
+A call returns or rejects within `totalTimeout` (60 s), retries and their waits included: each
+attempt's timeouts are cut to the time left, and a retry is skipped (the last answer or error
+rejects) when its wait, a `Retry-After` included, would leave under a second. Pass `maxRetries: 0`
+for calls made while a user waits on a page, if 60 s is too long.
+
+`onRetry` is called before each retry's wait with a frozen object: `attempt` (1, 2...),
+`maxRetries`, `delayMs`, `elapsedMs`, `method`, `url` (without its query string), and `status` for
+a retried status or `error` for a network failure or timeout (the other is `null`). It's never
+given the API key, headers or body, and it isn't called when no retry is made. Anything it throws
+stops the call, which rejects with that error:
+
+```js
+const qube = new Client({
+  apiKey: process.env.QUBE_API_KEY,
+  onRetry: ({ attempt, maxRetries, delayMs, method, url, status, error }) =>
+    console.warn(`QuBe Sync retry ${attempt}/${maxRetries} in ${Math.round(delayMs)} ms: ${method} ${url} (${status ?? error.code})`),
+});
+```
+
+### Errors
+
+Any answer outside 2xx rejects with `APIError`:
+
+```js
+try {
+  await qube.answer(decisionsUrl, { choice: "create" });
+} catch (error) {
+  if (!(error instanceof APIError)) throw error; // Node's own error: the connection failed after the retries
+  error.status;    // 409
+  error.code;      // "prompt_changed", when errors carries a code
+  error.errors;    // the body's errors as parsed: a sentence, { detail, code }, fields, or [{ path, message }]
+  error.message;   // "QuBe Sync answered 409: ...", one line, safe to log
+  error.body;      // the raw body
+  error.requestId; // the x-request-id header, for support
+}
+```
+
+A connection that still fails after the retries rejects with Node's own error (`ECONNREFUSED`,
+`ECONNRESET`, or `ETIMEDOUT` for a timeout), unchanged. Neither ever holds the API key, and
+`util.inspect(client)` and `JSON.stringify(client)` show only the `baseUrl`. See
+[error handling](https://docs.qubesync.com/error_handling).
+
 ## Webhooks
 
 Every delivery carries an `X-QUBE-Signature` header: `t=<unix seconds>,v1=<hex>[,v1=<hex>...]`,
@@ -132,10 +311,14 @@ app.post("/webhooks/qube", express.raw({ type: "application/json" }), (req, res)
 ```sh
 npm test            # node:test, no dependencies
 npm run test:types  # tsc --strict against test/types.ts (fetches TypeScript with npx)
+node scripts/generate-operations.js          # regenerate operations/ from test/fixtures/operations.json
+node scripts/generate-operations.js --check  # fail when operations/ is stale
 ```
 
-`test/fixtures/test_vectors.json` comes from the QuBe Sync server (`mix webhook_vectors.gen`).
-Copy a new version in; don't edit it.
+`test/fixtures/test_vectors.json` comes from the QuBe Sync server (`mix webhook_vectors.gen`), and
+`test/fixtures/operations.json` from https://qubesync.com/libraries/operations.json
+(`mix library_operations.gen`). Copy a new version in, then regenerate; don't edit either, or
+anything in `operations/`.
 
 ## License