@firmenakte/api-client 2.9.0 → 2.11.9

package/README.md

@@ -22,12 +22,47 @@ import { createApiClient } from "@firmenakte/api-client";
 const api = createApiClient({
   apiKey: "your-api-key",
   baseUrl: "https://api.firmenakte.at", // optional, defaults to production
+  timeoutMs: 10_000, // optional, defaults to 10 seconds
 });
 
 // Use the API, e.g. list businesses
 const { data } = await api.v1BusinessesList();
 ```
 
+The timeout starts separately for every request and also covers reading its response body. Pass an
+`AbortSignal` in an endpoint's request parameters when the caller needs to cancel sooner:
+
+```ts
+const controller = new AbortController();
+const request = api.v1BusinessesList(undefined, { signal: controller.signal });
+controller.abort();
+await request;
+```
+
+## Credits and rate limits
+
+API calls use your account's weekly credits, shared across all its keys. Free includes 50,
+Starter 500, Business 5,000, and Enterprise an agreed allowance. It resets on Monday at
+00:00 UTC. Purchased credits never expire and pay for calls the weekly allowance cannot cover.
+See [credit pricing](https://firmenakte.at/preise/credits).
+
+Operations declare `x-credit-class` in the OpenAPI spec: `basic` costs 1 credit and
+`expensive` costs 3. Charged responses include `X-Credits-Charged` and `X-Credits-Remaining`.
+The client exposes these on the response's `headers`:
+
+```ts
+const response = await api.v1BusinessesList();
+const charged = response.headers.get("X-Credits-Charged");
+const remaining = response.headers.get("X-Credits-Remaining");
+```
+
+Endpoint responses cost credits even for `400` or `404`. Authentication failures, `401`,
+requests rejected with `429`, and server errors, `5xx`, cost no credits.
+Credit exhaustion returns `429`, an `error` message starting with `Credits aufgebraucht`,
+and `Retry-After` in seconds until Monday 00:00 UTC. The separate burst limit returns
+`Retry-After: 60`. A longer wait means credit exhaustion; near Monday, check the error
+message because the reset can be 60 seconds or less away.
+
 ## Documentation
 
 Full API reference, authentication, and guides: **[https://docs.firmenakte.at](https://docs.firmenakte.at)**