nxus-qbd 0.8.0 → 1.0.0

package/README.md

@@ -1,4 +1,4 @@
-# nxus-qbd
+# nxus-qbd v1.0.0
 
 Official TypeScript SDK for the [Nxus](https://nx-us.net/docs/) QuickBooks Desktop API.
 
@@ -45,25 +45,33 @@ const nxus = new NxusClient({
   timeout: 120_000,
 });
 
-const page = await nxus.transactions.list({
-  connectionId: "your-connection-id",
-  limit: 100,
-  DetailLevel: "all",
-  timeout: 30_000,
-});
+const page = await nxus.transactions.list(
+  {
+    limit: 100,
+    DetailLevel: "all",
+  },
+  {
+    connectionId: "your-connection-id",
+    timeout: 30_000,
+  },
+);
 ```
 
 Paginated/list requests can also send a backend timeout hint without changing
 the SDK's local abort timer:
 
 ```ts
-const page = await nxus.transactions.list({
-  connectionId: "your-connection-id",
-  limit: 100,
-  DetailLevel: "all",
-  timeout: 30_000,
-  timeoutSeconds: 45,
-});
+const page = await nxus.transactions.list(
+  {
+    limit: 100,
+    DetailLevel: "all",
+    timeoutSeconds: 45,
+  },
+  {
+    connectionId: "your-connection-id",
+    timeout: 30_000,
+  },
+);
 ```
 
 When `timeoutSeconds` is provided on a `.list()` call, the SDK sends it as the
@@ -98,7 +106,28 @@ back in.
 For backoff, the standard `Retry-After` response header (seconds or HTTP-date)
 is honored when present, with `error.retryAfter` (seconds) in the JSON body
 as a fallback. Local timeouts (the SDK's abort timer) are treated as
-cancellations and are not retried.
+cancellations for reads, updates, deletes, and other non-idempotent calls.
+Generic Creates are the exception: their idempotency key makes timeout retries
+safe, so they reuse the same key on the next attempt.
+
+## Safe Create Retries
+
+Every generic resource `.create()` call automatically sends a cryptographically
+random `Idempotency-Key`. The SDK generates it once before retries begin and
+uses the same key for every attempt, including `.withResponse.create()`.
+
+For a workflow that can resume after the current process exits, supply and
+persist your own key:
+
+```ts
+await nxus.bills.create(request, {
+  idempotencyKey: `billing-import-${importJobId}`,
+});
+```
+
+The key is sent only as the `Idempotency-Key` HTTP header, never in the JSON
+body. QuickBooks recovery identifiers and recovery status remain server-owned;
+on a timeout, retry the same logical Create key and follow `x-should-retry`.
 
 Configure globally or per-request:
 
@@ -109,12 +138,16 @@ const nxus = new NxusClient({
 });
 
 // Disable retries for one call
-const created = await nxus.invoices.create({
-  customerRefListId: "...",
-  invoiceLineAdds: [{ itemRefListId: "...", amount: 100 }],
-  connectionId: "...",
-  maxRetries: 0,
-});
+const created = await nxus.invoices.create(
+  {
+    customerRefListId: "...",
+    invoiceLineAdds: [{ itemRefListId: "...", amount: 100 }],
+  },
+  {
+    connectionId: "...",
+    maxRetries: 0,
+  },
+);
 ```
 
 ## Verbose Logging
@@ -126,7 +159,7 @@ and error. Sensitive headers (`Authorization`, `Cookie`, `Set-Cookie`,
 ```ts
 const nxus = new NxusClient({
   apiKey: "sk_live_...",
-  verbose: true,                     // logs to console
+  verbose: true, // logs to console
 });
 ```
 
@@ -138,8 +171,8 @@ import type { NxusLogger } from "nxus-qbd";
 
 const logger: NxusLogger = {
   debug: (m, c) => myLogger.debug({ event: m, ...c }),
-  info:  (m, c) => myLogger.info({ event: m, ...c }),
-  warn:  (m, c) => myLogger.warn({ event: m, ...c }),
+  info: (m, c) => myLogger.info({ event: m, ...c }),
+  warn: (m, c) => myLogger.warn({ event: m, ...c }),
   error: (m, c) => myLogger.error({ event: m, ...c }),
 };
 
@@ -181,29 +214,50 @@ const nxus = new NxusClient({
 
 `fetchOptions` may also be supplied per request to override the client default.
 
-## Raw HTTP Access
+## Response Metadata
 
-When you need direct access to the underlying `Response` — headers, streaming
-bodies, custom status handling — use `transport.raw()`. Authentication, default
-headers, the timeout, and retries are still applied; only JSON parsing and the
-typed error mapping are bypassed.
+Every resource method has a `withResponse` twin that returns the parsed model
+_and_ the response metadata that came with it:
 
 ```ts
-import { NxusClient } from "nxus-qbd";
+const check = await nxus.checks.create({ payeeId });
+// -> Check
 
-const nxus = new NxusClient({ apiKey: "sk_live_..." });
+const wrapped = await nxus.checks.withResponse.create({ payeeId });
+// -> NxusResponse<Check>
+
+wrapped.data; // the same Check
+wrapped.statusCode; // 200
+wrapped.requestId; // 'req_abc123' — quote this in support requests
+wrapped.headers; // frozen, lower-cased names
+```
+
+Both forms are the same call. The plain method is a wrapper that discards the
+metadata, so parsing, retries and error translation are identical — only the
+return value differs. Errors throw `NxusApiError` in both.
 
-const res = await (nxus as unknown as { transport: { raw: (path: string, init?: RequestInit) => Promise<Response> } })
-  .transport.raw("/api/v1/vendors", { method: "GET" });
+`NxusResponse` is frozen, as is its `headers` object.
 
-console.log(res.status, res.headers.get("x-request-id"));
-const stream = res.body; // ReadableStream for large downloads
+The undecoded body is not retained unless you ask for it, since keeping it for
+every call would hold a second full copy of every payload alive:
+
+```ts
+const wrapped = await nxus.vendors.withResponse.retrieve(id, {
+  includeRawBody: true,
+});
+wrapped.rawBody; // the exact text the server sent
 ```
 
-Non-2xx responses are returned, not thrown — the caller is responsible for
-checking `response.ok`. Use this only for cases the typed resource methods
-can't model (binary downloads, response-header inspection, custom error
-semantics).
+The SDK never hands back a `fetch` `Response`. A `Response` body can only be
+read once, so exposing one would mean handing consumers an object that is
+already consumed — and would put the runtime's stream semantics into this
+SDK's contract. Everything useful is copied out while the response is still
+readable, so a `NxusResponse` is safe to keep, log, or pass around.
+
+`withResponse.list` returns the **first page** only and does not auto-paginate:
+later pages are separate requests with their own status and headers, which one
+wrapper could not honestly describe. Use `wrapped.data.hasMore` and
+`wrapped.data.cursor` to continue, or the plain `list` for the async iterator.
 
 ## Quick Start
 
@@ -213,7 +267,10 @@ import { NxusClient } from "nxus-qbd";
 const nxus = new NxusClient({ apiKey: "sk_live_..." });
 
 // List vendors
-const page = await nxus.vendors.list({ limit: 50, connectionId: "your-connection-id" });
+const page = await nxus.vendors.list(
+  { limit: 50 },
+  { connectionId: "your-connection-id" },
+);
 
 for (const vendor of page.data) {
   console.log(vendor.name);
@@ -224,21 +281,28 @@ const customer = await nxus.customers.retrieve("80000001-1234567890", {
   connectionId: "your-connection-id",
 });
 
-// Create an invoice (flat params)
-const invoice = await nxus.invoices.create({
-  customerRefListId: "80000001-1234567890",
-  invoiceLineAdds: [
-    { itemRefListId: "80000002-1234567890", amount: 150.0 },
-  ],
-  connectionId: "your-connection-id",
-});
-
-// Update a vendor (ID first, flat fields)
-const updated = await nxus.vendors.update("80000001-1234567890", {
-  name: "Acme (Updated)",
-  revisionNumber: vendor.revisionNumber,
-  connectionId: "your-connection-id",
-});
+// Create an invoice (payload first, transport options second)
+const invoice = await nxus.invoices.create(
+  {
+    customerRefListId: "80000001-1234567890",
+    invoiceLineAdds: [{ itemRefListId: "80000002-1234567890", amount: 150.0 }],
+  },
+  {
+    connectionId: "your-connection-id",
+  },
+);
+
+// Update a vendor (ID first, payload second, transport options third)
+const updated = await nxus.vendors.update(
+  "80000001-1234567890",
+  {
+    name: "Acme (Updated)",
+    revisionNumber: vendor.revisionNumber,
+  },
+  {
+    connectionId: "your-connection-id",
+  },
+);
 
 // Delete
 await nxus.vendors.delete("80000001-1234567890", {
@@ -252,14 +316,113 @@ Every request requires a `connectionId` to identify which QuickBooks Desktop com
 
 ```ts
 // Per-request
-const page = await nxus.vendors.list({ limit: 10, connectionId: "your-connection-id" });
-const vendor = await nxus.vendors.retrieve("id", { connectionId: "your-connection-id" });
+const page = await nxus.vendors.list(
+  { limit: 10 },
+  { connectionId: "your-connection-id" },
+);
+const vendor = await nxus.vendors.retrieve("id", {
+  connectionId: "your-connection-id",
+});
 
 // Global default
 const nxus = new NxusClient({
   apiKey: "sk_live_...",
-  headers: { "X-Connection-Id": "your-connection-id" },
+  connectionId: "your-connection-id",
+});
+```
+
+## Request Options
+
+Resource methods that accept a request body or query now prefer a split call shape:
+
+```ts
+await nxus.vendors.create(
+  { name: "Acme" },
+  { connectionId: "your-connection-id", timeout: 30_000 },
+);
+
+await nxus.vendors.list(
+  { limit: 50, timeoutSeconds: 45 },
+  { connectionId: "your-connection-id" },
+);
+
+await nxus.reports.retrieveAging(
+  { reportType: "summary" },
+  { connectionId: "your-connection-id" },
+);
+```
+
+This keeps transport options out of serialized request bodies and query strings.
+
+`authSessions.create()` is the main special case because `connectionId` is a real
+payload field on that endpoint. When you need both the auth-session payload
+connection and a transport-level connection header, pass them separately:
+
+```ts
+await nxus.authSessions.create(
+  {
+    connectionId: "payload-connection-id",
+    redirectUrl: "https://example.com/after-qwc",
+  },
+  {
+    connectionId: "transport-connection-id",
+  },
+);
+```
+
+## Filtering By Active Status
+
+QuickBooks returns only active records unless a list request says otherwise.
+`activeStatus` is typed, so the value comes from `QbdActiveStatus` rather than
+a hand-written string:
+
+```ts
+import { NxusClient, QbdActiveStatus } from "nxus-qbd";
+
+// Active and inactive records
+const all = await nxus.vendors.list({
+  limit: 50,
+  activeStatus: QbdActiveStatus.ALL,
+});
+
+// Only the records QuickBooks has marked inactive
+const inactive = await nxus.vendors.list({
+  limit: 50,
+  activeStatus: QbdActiveStatus.INACTIVE_ONLY,
 });
+
+// Omit it entirely for QuickBooks' ActiveOnly default
+const active = await nxus.vendors.list({ limit: 50 });
+```
+
+The wire values are `ActiveOnly`, `InactiveOnly` and `All`, and QuickBooks
+matches them exactly. A near miss such as `"all"` is not rejected as a bad
+request — it travels all the way into qbXML and comes back as QBD error 3110,
+`The enumerated value "all" in the field "ActiveStatus" is unknown or invalid`.
+That is what the enum is for.
+
+The enum and its wire string are interchangeable, so both of these compile and
+send the same request, while a typo does not compile at all:
+
+```ts
+await nxus.vendors.list({ activeStatus: QbdActiveStatus.ALL });
+await nxus.vendors.list({ activeStatus: "All" });
+
+// @ts-expect-error — "all" is not one of the three literals
+await nxus.vendors.list({ activeStatus: "all" });
+```
+
+A value the compiler only knows as `string` — an environment variable, a CLI
+flag, a database column — cannot be checked that way. `toActiveStatus` closes
+that gap by validating locally instead of letting QuickBooks fail the request:
+
+```ts
+import { toActiveStatus } from "nxus-qbd";
+
+const activeStatus = toActiveStatus(process.env.NXUS_ACTIVE_STATUS ?? "All");
+await nxus.vendors.list({ limit: 50, activeStatus });
+
+// `isActiveStatus(value)` narrows without throwing.
 ```
 
 ## Auto-Pagination
@@ -268,7 +431,10 @@ List methods return an `AutoPaginationPromise` that supports both manual page na
 
 ```ts
 // Auto-paginate through all records
-for await (const vendor of nxus.vendors.list({ limit: 100, timeoutSeconds: 45 })) {
+for await (const vendor of nxus.vendors.list({
+  limit: 100,
+  timeoutSeconds: 45,
+})) {
   console.log(vendor.name);
 }
 
@@ -289,17 +455,16 @@ while (page.hasNextPage()) {
 
 Runnable examples live in [`examples/`](examples/):
 
-| Example | Description |
-|---|---|
-| [`basic-crud.ts`](examples/basic-crud.ts) | Create, retrieve, update, list, and delete a vendor |
-| [`authSetup.ts`](examples/authSetup.ts) | Create a connection, generate a hosted QWC auth flow URL, and check auth status |
-| [`auto-pagination.ts`](examples/auto-pagination.ts) | Auto-iteration across pages plus manual page navigation |
-| [`connection-scoped.ts`](examples/connection-scoped.ts) | Multi-company isolation with `connectionId` |
-| [`error-handling.ts`](examples/error-handling.ts) | Error categorization and typed SDK errors |
-| [`pagination-walkthrough.ts`](examples/pagination-walkthrough.ts) | Cursor handling walkthrough |
-| [`reports.ts`](examples/reports.ts) | Aging, general detail, and general summary reports |
-| [`timeout-tuning.ts`](examples/timeout-tuning.ts) | Default timeout behavior, client-wide overrides, and per-request timeout tuning |
-
+| Example                                                           | Description                                                                     |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| [`basic-crud.ts`](examples/basic-crud.ts)                         | Create, retrieve, update, list, and delete a vendor                             |
+| [`authSetup.ts`](examples/authSetup.ts)                           | Create a connection, generate a hosted QWC auth flow URL, and check auth status |
+| [`auto-pagination.ts`](examples/auto-pagination.ts)               | Auto-iteration across pages plus manual page navigation                         |
+| [`connection-scoped.ts`](examples/connection-scoped.ts)           | Multi-company isolation with `connectionId`                                     |
+| [`error-handling.ts`](examples/error-handling.ts)                 | Error categorization and typed SDK errors                                       |
+| [`pagination-walkthrough.ts`](examples/pagination-walkthrough.ts) | Cursor handling walkthrough                                                     |
+| [`reports.ts`](examples/reports.ts)                               | Aging, general detail, and general summary reports                              |
+| [`timeout-tuning.ts`](examples/timeout-tuning.ts)                 | Default timeout behavior, client-wide overrides, and per-request timeout tuning |
 
 ## Error Handling
 
@@ -312,40 +477,54 @@ try {
   await nxus.vendors.retrieve("non-existent-id");
 } catch (err) {
   if (err instanceof NxusApiError) {
-    console.log(err.status);          // 404
-    console.log(err.userMessage);     // User-safe message
-    console.log(err.isNotFound);      // true
-    console.log(err.isAuthError);     // false
-    console.log(err.isRateLimited);   // false
+    console.log(err.status); // 404
+    console.log(err.userMessage); // User-safe message
+    console.log(err.retryAfter); // Requested retry delay in seconds, if present
+    console.log(err.isNotFound); // true
+    console.log(err.isAuthError); // false
+    console.log(err.isRateLimited); // false
+    console.log(err.isRestrictionError); // lifecycle or billing restriction
+    console.log(err.isArchivedConnection); // lifecycleState === "archived"
+    console.log(err.isConnectorOffline); // QuickBooks Web Connector is not polling
   }
 }
 ```
 
+Restriction responses also expose `lifecycleState`, `restrictionReason`,
+`restrictionCode`, `requiresPayment`, and `checkoutUrl`. `throwIfError(value)`
+converts an arbitrary generated-client error value into `NxusApiError`.
+
+`isConnectorOffline` is worth handling on its own: it means the QuickBooks Web
+Connector is not polling, so the API answered 503 without queuing anything and
+retrying cannot succeed until someone starts the connector. Read `code` to tell
+`QWC_NEVER_CONNECTED` (the `.qwc` file was never installed) from
+`QWC_NOT_CONNECTED` (it authenticated once and has since stopped) — the two want
+different operator instructions.
+
 ## Resources
 
 All QuickBooks Desktop resources are available as namespaced properties:
 
-| Category | Resources |
-|---|---|
+| Category         | Resources                                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Transactions** | `invoices`, `bills`, `checks`, `deposits`, `estimates`, `creditMemos`, `purchaseOrders`, `salesReceipts`, `journalEntries`, `receivePayments`, `vendorCredits`, `creditCardCharges`, `creditCardBills`, `creditCardCredits`, `charges`, `buildAssemblies`, `arRefundCreditCards`, `salesTaxPaymentChecks`, `itemReceipts`, `CheckBillPayments`, `timeTrackings`, `transactions` |
-| **Lists** | `accounts`, `customers`, `vendors`, `employees`, `otherNames`, `currencies`, `terms`, `dateDrivenTerms`, `paymentMethods`, `shipMethods`, `salesTaxCodes`, `priceLevels`, `qbdClasses`, `customerTypes`, `vendorTypes`, `billingRates`, `inventorySites`, `barCodes`, `accountTaxLineInfos`, `unitOfMeasureSets`, `specialItems` |
-| **Read-only** | `billToPay` |
-| **Items** | `items`, `inventoryItems`, `itemDiscounts`, `itemFixedAssets`, `itemGroups`, `itemInventoryAssemblies`, `itemNonInventory`, `itemOtherCharges`, `itemPayments`, `itemSalesTax`, `itemSalesTaxGroups`, `serviceItems`, `itemSubtotals` |
-| **Payroll** | `payrollItemNonWages`, `payrollItemWages`, `workersCompCodes` |
-| **Reports** | `reports.retrieveAging()`, `reports.retrieveGeneralDetail()`, `reports.retrieveGeneralSummary()`, `reports.retrieveBudgetSummary()`, `reports.retrieveJob()`, `reports.retrieveTime()`, `reports.retrieveCustomDetail()`, `reports.retrieveCustomSummary()`, `reports.retrievePayrollDetail()` |
-| **Core** | `authSessions`, `connections` |
-
+| **Lists**        | `accounts`, `customers`, `vendors`, `employees`, `otherNames`, `currencies`, `terms`, `dateDrivenTerms`, `paymentMethods`, `shipMethods`, `salesTaxCodes`, `priceLevels`, `qbdClasses`, `customerTypes`, `vendorTypes`, `billingRates`, `inventorySites`, `barCodes`, `accountTaxLineInfos`, `unitOfMeasureSets`, `specialItems`                                                |
+| **Read-only**    | `billToPay`                                                                                                                                                                                                                                                                                                                                                                     |
+| **Items**        | `items`, `inventoryItems`, `itemDiscounts`, `itemFixedAssets`, `itemGroups`, `itemInventoryAssemblies`, `itemNonInventory`, `itemOtherCharges`, `itemPayments`, `itemSalesTax`, `itemSalesTaxGroups`, `serviceItems`, `itemSubtotals`                                                                                                                                           |
+| **Payroll**      | `payrollItemNonWages`, `payrollItemWages`, `workersCompCodes`                                                                                                                                                                                                                                                                                                                   |
+| **Reports**      | `reports.retrieveAging()`, `reports.retrieveGeneralDetail()`, `reports.retrieveGeneralSummary()`, `reports.retrieveBudgetSummary()`, `reports.retrieveJob()`, `reports.retrieveTime()`, `reports.retrieveCustomDetail()`, `reports.retrieveCustomSummary()`, `reports.retrievePayrollDetail()`                                                                                  |
+| **Core**         | `authSessions`, `connections`                                                                                                                                                                                                                                                                                                                                                   |
 
 ## Custom fields and data extensions
 
 QuickBooks Desktop uses the same underlying mechanism for both UI-visible custom fields and application-only integration data:
 
-| QuickBooks concept | SDK/API name | Purpose |
-|---|---|---|
-| Data extension definition | `DataExtDef` / custom field definition | Describes a field's owner, name, data type, and supported object types. |
-| Data extension value | `DataExt` / custom field value | Stores the field's value on one specific QuickBooks list object, transaction, or transaction line. |
+| QuickBooks concept        | SDK/API name                                  | Purpose                                                                                            |
+| ------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Data extension definition | `DataExtDefinition` / custom field definition | Describes a field's owner, name, data type, and supported object types.                            |
+| Data extension value      | `DataExt` / custom field value                | Stores the field's value on one specific QuickBooks list object, transaction, or transaction line. |
 
-A definition must exist before a value can be written. Definitions are identified by `ownerId + name`; values add the specific QuickBooks target to that composite identity. QuickBooks may omit `DataExtID` for private definitions, so SDK consumers must allow `DataExtDef.id` to be `null`.
+A definition must exist before a value can be written. Definitions are identified by `ownerId + name`; values add the specific QuickBooks target to that composite identity. QuickBooks may omit `DataExtID` for private definitions, so SDK consumers must allow `DataExtDefinition.id` to be `null`.
 
 The `ownerId` determines how a definition is used:
 
@@ -356,14 +535,13 @@ The `assignToObjects` property is therefore optional in the SDK request type, bu
 
 The normal workflow is:
 
-1. Create the `DataExtDef`.
+1. Create the `DataExtDefinition`.
 2. Create a `DataExt` value using the same `ownerId` and field name, plus a target such as a Customer `ListID`, an Invoice `TxnID`, or a transaction-line `TxnLineID`.
 3. Update or delete the value using that same composite identity.
 4. Delete a private definition only after its values are no longer needed. Public definitions must be managed in the QuickBooks UI because QuickBooks does not support deleting them through `DataExtDefDel`.
 
 Public fields are typically used for information users should see or edit in QuickBooks. Private extensions are commonly used for external-system identifiers, synchronization or verification markers, workflow state, migration metadata, and other integration data that should not appear in the QuickBooks UI.
 
-
 ## License
 
 MIT