@simpleapps-com/augur-api 2026.9.6 → 2026.10.1

package/README.md

@@ -8,6 +8,8 @@ TypeScript client library for Augur microservices.
 npm install @simpleapps-com/augur-api
 ```
 
+**Pin the version.** Versions are CalVer (`YYYY.MM.PATCH`), and a month roll can carry breaking changes when the Augur API changes upstream, but npm treats `^2026.9.7` as accepting `2026.10.0`. Use an exact version or `~` (patch updates only), and read the [release notes](https://github.com/simpleapps-com/augur-api/releases) before moving to a new month.
+
 ## Quick Start
 
 ```typescript
@@ -139,6 +141,35 @@ try {
 }
 ```
 
+The status decides the class: 400 → `ValidationError`, 401 → `AuthenticationError`, 404 → `NotFoundError`, 429 → `RateLimitError`, anything else → `AugurError`. `error.endpoint` is the path template (`/inv-mast/{invMastUid}`), and messages never contain parameter values.
+
+## Endpoint Registry and `call()`
+
+`AugurAPI.endpoints()` lists every endpoint (id, method, path template, params). `call()` invokes one by id or alias id, with no typed method:
+
+```typescript
+const result = await api.call('items.invMast.doc.get', {
+  pathParams: { invMastUid: 12345 },
+  query: { edgeCache: 1 },
+});
+
+result.httpStatus; // 200
+result.envelope?.data; // set when the body is the standard 8-key envelope
+result.body; // parsed JSON, or the raw text when the body isn't JSON
+```
+
+- Arguments are checked before any request: path params must match exactly, query keys must be declared, and a body is allowed only on POST/PUT. Violations throw `InvalidArgumentError`.
+- A 2xx always resolves; there is no schema validation. Use the typed methods when you want validated, typed responses.
+- Non-2xx responses throw the same errors as the typed methods.
+
+## Path Values
+
+Path values are sent unencoded, because the API does not decode path segments (`/bins/D%2FS` looks up the literal `D%2FS`). A string path value MUST use only letters, digits and `- . _ ~ ! $ & ' ( ) * + , ; = : @`. Anything else, such as `/`, `?`, `#`, `%`, spaces or non-ASCII, throws `InvalidArgumentError` before any request. Pass the raw value, never a pre-encoded one. Use the query parameter instead where there is one:
+
+```typescript
+await api.call('items.locations.bins.list', { pathParams: { locationId: 100 }, query: { bin: 'D/S' } });
+```
+
 ## For AI Agents
 
 See [SKILL.md](./SKILL.md) for guidance on using this package with AI assistance.

package/SKILL.md

@@ -110,9 +110,11 @@ Apply same pattern to any service:
 
 | Resource | URL Pattern | Use When |
 |----------|-------------|----------|
-| **llms.txt** | `https://{service}.augur-api.com/llms.txt` | Discover endpoints |
-| **endpoints.jsonl** | `https://{service}.augur-api.com/endpoints.jsonl` | Get parameters |
-| **openapi.json** | `https://{service}.augur-api.com/openapi.json` | Full schemas |
+| **endpoints.jsonl** | `https://{service}.augur-api.com/endpoints.jsonl` | **Start here.** One JSON line per endpoint: method, path, path params and query params, each with type and required flag. Grep it for a path; for a GET that line is all you need. It has no request or response bodies |
+| **openapi.json** | `https://{service}.augur-api.com/openapi.json` | Request and response bodies field by field, descriptions, formats, documented errors |
+| **llms.txt** | `https://{service}.augur-api.com/llms.txt` | Plain-text endpoint list and the other Augur services |
+
+The generated code carries the same information: every method's doc lists its summary, documented errors, path and query params, body and response fields with their meaning, and a link to its operation in `openapi.json`.
 
 **Central Reference:** https://augur-api.info
 
@@ -147,8 +149,8 @@ Every client also inherits `healthCheck`, `ping`, and `whoami` (each with a `…
 
 1. **Start** - `new AugurAPI({ siteId, bearerToken })`
 2. **Discover** - Fetch any `llms.txt`, find "Other Services"
-3. **Find endpoints** - Fetch target service's `llms.txt`
-4. **Get parameters** - Fetch `endpoints.jsonl` for method signatures
+3. **Find the endpoint and its params** - Grep the service's `endpoints.jsonl`; for a GET, that line is everything you need
+4. **Bodies** - For POST/PUT bodies and response fields, read the method's doc in `src/services/{service}/generated/types.ts` (or the `openapi.json` operation it links)
 5. **Convert to code** - Apply the path→property pattern
 6. **Verify** - Check `src/services/{service}/client.ts` if unsure
 
@@ -214,6 +216,21 @@ for (const faq of faqs) {
 }
 ```
 
+## Calling by Endpoint Id (`call()`)
+
+For generic callers (tools, agents, scripts) that should not hard-code a typed method:
+
+```typescript
+AugurAPI.endpoints(); // every endpoint: id, method, path template, pathParams, queryParams, hasBody
+const result = await api.call('items.invMast.doc.get', { pathParams: { invMastUid: 12345 } });
+result.envelope?.data; // null envelope means the body isn't the 8-key envelope; see result.body
+```
+
+- Ids are `camelCase(service).chain.action`, the same as the typed call path.
+- Arguments are checked before any request (`InvalidArgumentError`). A 2xx never fails validation.
+- Errors: 400 → `ValidationError`, 401 → `AuthenticationError`, 404 → `NotFoundError`, 429 → `RateLimitError`, anything else → `AugurError`. `error.endpoint` is the path template.
+- Path values are sent unencoded: a string path value with `/ ? # %`, spaces or non-ASCII is rejected. Use the query param instead (e.g. `bins.list` with `query: { bin: 'D/S' }`).
+
 ## Key Differences from Python Client
 
 | Aspect | TypeScript | Python |