@simpleapps-com/augur-api 2026.9.5 → 2026.9.7

package/README.md

@@ -139,6 +139,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

@@ -194,23 +194,41 @@ response.message   // Status message
 response.status    // HTTP status code
 ```
 
-## Zod Schemas
+## Types and Validation
 
-All request params and response data use Zod schemas:
+Request params and responses are validated with Valibot schemas. Types are exported per service as
+a namespace (`{Service}Types`): params are `{Chain}{Action}Params`, request bodies
+`{Chain}{Action}Body`, response data `{Chain}{Action}Data`.
 
 ```typescript
-import { InvMastListParams, InvMast } from '@simpleapps-com/augur-api';
+import type { ItemsTypes } from '@simpleapps-com/augur-api';
 
 // Type-safe params
-const params: InvMastListParams = { limit: 10, offset: 0 };
-const response = await api.items.invMast.list(params);
+const params: ItemsTypes.InvMastFaqListParams = { limit: 10, offset: 0 };
+const response = await api.items.invMast.faq.list(invMastUid, params);
 
-// Type-safe response
-for (const item of response.data) {
-  console.log(item.itemId);  // IDE autocomplete works
+// Type-safe response data
+const faqs: ItemsTypes.InvMastFaqListData = response.data;
+for (const faq of faqs) {
+  console.log(faq.question);  // IDE autocomplete works
 }
 ```
 
+## 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 |
@@ -219,4 +237,4 @@ for (const item of response.data) {
 | Service: brand-folder | api.brandFolder | api.brand_folder |
 | Resource: inv-mast | .invMast | .inv_mast |
 | Method: invMastUid | invMastUid | inv_mast_uid |
-| Validation | Zod | Pydantic v2 |
+| Validation | Valibot | Pydantic v2 |