@infinitetoken/lumber-kit 0.6.0 → 0.7.0

package/README.md

@@ -125,6 +125,19 @@ import { LogLevel, LogRecord, LogEncrypted, LogPayload, LogsQuery } from '@infin
 
 A plugin sends only the token to the API (`Authorization: Bearer <token>`) and encrypts with the rest, so the encryption key never leaves it.
 
+### Plugins
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `LogIngestBody` | interface | `POST /logs`' body: `{ level, encrypted }` |
+| `LogData` | interface | What a log call takes beside its message: `requestId`, `traceId`, `context`, `metadata` and any other keys |
+| `buildLogPayload` | function | The `LogPayload` a log call encrypts, from its level, message, data and the plugin's automatic context |
+| `DEFAULT_API_ENDPOINT` | constant | `https://api.lumber.infinitetoken.com` |
+| `LOG_KEY_VERSION` | constant | `LogEncrypted`'s `keyVersion` (1) |
+| `logDelivery` | object | Attempts, retry delays and the pause after a 429 |
+| `logDeliveryOutcome` | function | `sent`, `retry`, `drop` or `pause` for a `POST /logs` status (null for a network error) |
+| `logRetryDelayMs` | function | The wait after a log's nth failed attempt: 1s, 2s, 4s, up to 30s |
+
 ## Wire format
 
 All log content is E2E encrypted before leaving the client. `LogRecord` contains only:
@@ -135,14 +148,14 @@ All log content is E2E encrypted before leaving the client. `LogRecord` contains
   createdAt: string        // ISO 8601
   updatedAt: string        // ISO 8601
   appId:     string
-  encrypted: LogEncrypted  // opaque blob — server cannot read this
+  encrypted: LogEncrypted  // opaque to the server, which can't read it
 }
 ```
 
 `LogEncrypted` uses AES-256-GCM:
-- `nonce` — base64(random IV, 12 bytes)
-- `payload` — base64(authTag[16 bytes] + ciphertext)
-- `keyVersion` — always `1` for the current format; changes are semver major
+- `nonce`: base64(random IV, 12 bytes)
+- `payload`: base64(authTag[16 bytes] + ciphertext)
+- `keyVersion`: always `1` for the current format; changes are semver major
 
 The plaintext shape inside `payload` is `LogPayload`:
 
@@ -157,6 +170,10 @@ The plaintext shape inside `payload` is `LogPayload`:
 }
 ```
 
+## Other languages
+
+TypeScript can't be imported from Python or Go, so the kit ships its contract in `contract/`: a JSON Schema of every exported type (`schema.json`, generated from the TypeScript by `npm run contract`) and known answers (`vectors.json`) for API keys, AES-256-GCM, payloads and delivery, which the kit's own tests check against its code. Lumber-Python and Lumber-Go test against a pinned copy. See `contract/README.md`.
+
 ## const enum and Babel consumers
 
 `LogLevel` is a TypeScript `const enum`. TypeScript consumers have values inlined at compile time (zero runtime overhead).

package/contract/README.md

@@ -0,0 +1,21 @@
+# Lumber's contract
+
+The shapes and known answers every Lumber client is tested against, whatever its language. Lumber-Kit's TypeScript is the source: these files are generated from it or checked against it by the kit's own tests, and they ship in the npm package, so a client pins them by the kit's version.
+
+- `schema.json`: a JSON Schema (draft-07) of every type the kit exports, generated by `npm run contract`. A plugin sends `LogIngestBody` to `POST /logs` and encrypts a `LogPayload` into its `encrypted`. `LogPayload` allows no other keys, so a misspelled field (`request_id`) fails validation rather than going missing in the app.
+- `vectors.json`: known answers.
+  - `constants`: the default endpoint, ingestion path, key version, key, nonce and tag sizes, log levels and the delivery policy.
+  - `apiKeys`: how an API key (`<token>.<encryptionKey>`) splits.
+  - `encryption`: AES-256-GCM with a fixed key and nonce, so a plugin's encryption has to give these exact bytes (`payload` is base64 of the 16-byte tag and then the ciphertext, `nonce` the 12-byte IV).
+  - `payloads`: the plaintext a log call builds from its level, message, data and the plugin's automatic context.
+  - `deliveryOutcomes` and `retryDelaysMs`: what each answer from `POST /logs` means, and how long to wait after each failure.
+
+## In another language
+
+Copy this folder into the client's tests at a pinned kit version, and test every vector against the client's own code. The kit's version is the contract's: when the kit changes a shape, the new version's files fail the client's tests until it catches up.
+
+```bash
+curl -sL https://registry.npmjs.org/@infinitetoken/lumber-kit/-/lumber-kit-0.7.0.tgz | tar -xz --strip-components=1 package/contract
+```
+
+Lumber-Python (`scripts/sync_contract.py`) and Lumber-Go (`scripts/sync-contract.sh`) each have a script that does this, and their CI fails when the copy differs from the pinned version's. Lumber-Node reads the contract straight from its installed kit (`@infinitetoken/lumber-kit/contract/vectors.json`).