@infinitetoken/lumber-kit 0.6.0 → 0.8.0

package/README.md

@@ -1,6 +1,8 @@
 # @infinitetoken/lumber-kit
 
-Shared TypeScript types, wire format contract, and query interfaces for the [Lumber](https://github.com/infinitetoken/Lumber) cloud logging suite.
+Shared TypeScript types, wire format contract, and query interfaces for the [Lumber](https://lumber.infinitetoken.com) cloud logging suite. Lumber is end-to-end encrypted: a client encrypts every log with AES-256-GCM before it leaves the process, and the server stores only ciphertext plus each log's level.
+
+To send logs from your own code, you want a client rather than this package: [`@infinitetoken/lumber`](https://github.com/infinitetoken/Lumber-Node) for Node.js, [`lumber-cloud`](https://github.com/infinitetoken/Lumber-Python) for Python or [`lumber-go`](https://github.com/infinitetoken/lumber-go) for Go. The kit is what those clients and Lumber's own apps and services share, and its [contract](contract/README.md) is what a client in any language is tested against.
 
 ## Install
 
@@ -84,6 +86,10 @@ import { LogLevel, LogRecord, LogEncrypted, LogPayload, LogsQuery } from '@infin
 | `AppRecord` | interface | API response shape for an app |
 | `AppCreatedRecord` | interface | POST /apps 201 response (includes `encryptedKey` once) |
 | `UserRecord` | interface | API response shape for a user |
+| `TimeFormat` | interface | How a user reads times on every device: `{ clock: '24h' \| '12h', zone: 'local' \| 'utc' }` |
+| `DEFAULT_TIME_FORMAT` | constant | 24-hour, local: what a user gets until they pick one |
+| `isValidTimeFormat` | function | A known clock and zone, and nothing else |
+| `normalizeTimeFormat` | function | A stored or sent time format, each part the default when missing or unknown |
 | `TeamRecord` | interface | API response shape for a team |
 | `TeamMemberRecord` | interface | Team membership record (listed members carry name, handle, color and picture) |
 | `AppTeamAccess` | type | Who on an app's team reads it: `'everyone'` or `'owner'` |
@@ -125,6 +131,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 +154,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,26 +176,36 @@ 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`](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).
 
 If your project uses Babel, esbuild, or `isolatedModules: true`, the runtime enum object is available because Lumber-Kit is compiled with `preserveConstEnums: true`. No special configuration is needed.
 
-## Local development (yalc)
+## Developing
+
+```bash
+npm install
+npm run verify     # lint, test, typecheck, build
+npm run contract   # regenerate contract/schema.json after changing a type
+```
 
-Do NOT use `npm link` — it creates symlinks that break Metro in the Expo client.
+To try a change in a project that uses the kit before it's published, use [yalc](https://github.com/wclr/yalc) rather than `npm link`, whose symlinks break Metro (React Native's bundler):
 
 ```bash
-# In Lumber-Kit:
+# In Lumber-Kit
 npm run build
 yalc publish
 
-# In a consumer repo (Lumber-API, Lumber-Node, Lumber Expo client):
+# In the project using it
 yalc add @infinitetoken/lumber-kit
 npm install
 
-# After updating Lumber-Kit:
+# After each change to Lumber-Kit
 npm run build
-yalc push   # propagates to all linked consumers
+yalc push   # updates every project that added it
 ```

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`).