@kevludwig/lexware-office 0.3.0 → 0.4.1

package/README.md

@@ -27,7 +27,8 @@ One client is one rate-limit queue: requests are spaced (the API allows two per
 | `appUrl` | `https://app.lexware.de` | Base of the links `voucherUrl()` builds |
 | `minSpacingMs` | `550` | Spacing between two requests |
 | `timeoutMs` | `20000` | Per request, counted from when it fires |
-| `rateLimitBackoffMs` | `1000` | Wait before the retry after a 429 |
+| `rateLimitBackoffMs` | `1000` | Wait before a retry after a 429 without `Retry-After`, growing with each retry |
+| `rateLimitRetries` | `3` | How often a request answered with 429 is sent again; `Retry-After` is honoured (at most 10 s) |
 | `fetch` | global `fetch` | Your own implementation, e.g. in tests |
 
 A failed request throws `LexwareApiError` with `status` and `responseBody`; `describeError(error)` turns it into a sentence worth showing a person — a 403 says which permission the key lacks, a 406 what the API usually means by it.
@@ -89,7 +90,7 @@ The ledger needs somewhere to keep one small JSON record per invoice. `JsonStore
 
 ## Tests
 
-`npm test` runs 38 tests against a fake API — no account, no network. `test/fake-api.ts` shows the pattern: routes answer by method and path, and every call is recorded.
+`npm test` runs 56 tests against a fake API — no account, no network. `test/fake-api.ts` shows the pattern: routes answer by method and path, and every call is recorded.
 
 ## Not affiliated with Lexware
 

package/dist/client.d.ts

@@ -3,9 +3,10 @@
  *
  * One client per account: the API allows two requests per second for the
  * whole account, so every call of a client goes through one serial queue with
- * a minimum spacing. A single retry on 429 covers the case that something else
- * uses the same account at the same time. Share one client instead of creating
- * one per call — separate clients do not know about each other's requests.
+ * a minimum spacing. Retries on 429 — honouring Retry-After — cover other
+ * clients on the same account: serverless instances, a second app. Share one
+ * client per process; separate clients do not know about each other's
+ * requests, the retries only soften that.
  */
 export declare const DEFAULT_BASE_URL = "https://api.lexware.io/v1";
 /** Where a voucher opens in the Lexware Office web app. */
@@ -27,8 +28,10 @@ export interface LexwareClientOptions {
      * a file that arrives anyway. Default: 120 000.
      */
     uploadTimeoutMs?: number;
-    /** Wait before retrying a request answered with 429, in ms. Default: 1 000. */
+    /** Wait before retrying a request answered with 429 without Retry-After, in ms; grows with each retry. Default: 1 000. */
     rateLimitBackoffMs?: number;
+    /** How often a request answered with 429 is sent again. Default: 3. */
+    rateLimitRetries?: number;
     /** A fetch implementation, e.g. for tests. Default: the global fetch. */
     fetch?: typeof fetch;
 }

package/dist/client.js

@@ -3,9 +3,10 @@
  *
  * One client per account: the API allows two requests per second for the
  * whole account, so every call of a client goes through one serial queue with
- * a minimum spacing. A single retry on 429 covers the case that something else
- * uses the same account at the same time. Share one client instead of creating
- * one per call — separate clients do not know about each other's requests.
+ * a minimum spacing. Retries on 429 — honouring Retry-After — cover other
+ * clients on the same account: serverless instances, a second app. Share one
+ * client per process; separate clients do not know about each other's
+ * requests, the retries only soften that.
  */
 export const DEFAULT_BASE_URL = "https://api.lexware.io/v1";
 /** Where a voucher opens in the Lexware Office web app. */
@@ -54,6 +55,33 @@ export function query(params) {
     return rendered ? `?${rendered}` : "";
 }
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Waits `ms`, or rejects with the signal's reason as soon as it aborts. */
+function abortableSleep(ms, signal) {
+    if (!signal)
+        return sleep(ms).then(() => undefined);
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** The server's Retry-After in ms (seconds or an HTTP date), capped at 10 s; null without one. */
+function retryAfterMs(response) {
+    const header = response.headers.get("retry-after")?.trim();
+    if (!header)
+        return null;
+    const seconds = Number(header);
+    const ms = Number.isFinite(seconds) ? seconds * 1_000 : Date.parse(header) - Date.now();
+    return Number.isFinite(ms) ? Math.min(Math.max(ms, 0), 10_000) : null;
+}
 export function createLexwareClient(options) {
     if (!options.apiKey?.trim())
         throw new Error("Lexware Office: apiKey fehlt.");
@@ -63,6 +91,7 @@ export function createLexwareClient(options) {
     const timeoutMs = options.timeoutMs ?? 20_000;
     const uploadTimeoutMs = options.uploadTimeoutMs ?? 120_000;
     const backoffMs = options.rateLimitBackoffMs ?? 1_000;
+    const retries = options.rateLimitRetries ?? 3;
     const fetchImpl = options.fetch ?? fetch;
     // The queue: each request waits for the previous one to start plus the
     // spacing. The time limit starts when the request fires, not when queued.
@@ -81,9 +110,9 @@ export function createLexwareClient(options) {
         return run;
     }
     /**
-     * One request, queued, with a single retry on 429 — then the API
-     * demonstrably did not run it. A transport error after a POST is never
-     * retried: the voucher may well exist already.
+     * One request, queued, retried on 429 — then the API demonstrably did not
+     * run it. A transport error after a POST is never retried: the voucher may
+     * well exist already.
      */
     async function send(path, init, limitMs = timeoutMs) {
         const method = init.method ?? "GET";
@@ -96,8 +125,10 @@ export function createLexwareClient(options) {
             });
         });
         let response = await fire();
-        if (response.status === 429) {
-            await sleep(backoffMs);
+        for (let attempt = 1; response.status === 429 && attempt <= retries; attempt++) {
+            await response.body?.cancel().catch(() => undefined);
+            // The caller's cancellation also ends the wait between retries.
+            await abortableSleep(retryAfterMs(response) ?? backoffMs * attempt, init.signal);
             response = await fire();
         }
         if (!response.ok) {

package/dist/contacts.d.ts

@@ -1,8 +1,8 @@
 /**
  * Contacts — customers and vendors alike.
  *
- * Search is fuzzy on the API side: "Nordlicht" finds "Nordlicht Consulting
- * GmbH", "Müller" may find three. Functions here return candidates and leave
+ * Search is fuzzy on the API side: "Beispiel" finds "Beispiel GmbH",
+ * "Müller" may find three. Functions here return candidates and leave
  * the choice to the caller; guessing one of several is the worse mistake.
  */
 import { type LexwareClient } from "./client.ts";

package/dist/contacts.js

@@ -1,8 +1,8 @@
 /**
  * Contacts — customers and vendors alike.
  *
- * Search is fuzzy on the API side: "Nordlicht" finds "Nordlicht Consulting
- * GmbH", "Müller" may find three. Functions here return candidates and leave
+ * Search is fuzzy on the API side: "Beispiel" finds "Beispiel GmbH",
+ * "Müller" may find three. Functions here return candidates and leave
  * the choice to the caller; guessing one of several is the worse mistake.
  */
 import { query } from "./client.js";

package/dist/reminder-mail.d.ts

@@ -42,7 +42,7 @@ export declare class MailNotSentError extends Error {
     });
 }
 export interface ReminderSender {
-    /** Signature name, e.g. "Kevin Ludwig". */
+    /** Signature name, e.g. "Max Muster". */
     name: string;
     /** Lines under the name, e.g. the company and town. */
     signature?: readonly string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kevludwig/lexware-office",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Typed client and domain logic for the Lexware Office Public API: contacts, receivables, payment reminder rules.",
   "type": "module",
   "license": "MIT",