@infinitetoken/lumber-kit 0.7.0 → 1.0.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
 
@@ -34,6 +36,7 @@ import { LogLevel, LogRecord, LogEncrypted, LogPayload, LogsQuery } from '@infin
 | `SubscriptionLevel` | `const enum` | Team tier: Hobby=0 Dev=1 Pro=2 Enterprise=3 |
 | `subscriptionLevelToName` | object | Maps `SubscriptionLevel` to `'hobby' \| 'dev' \| 'pro' \| 'enterprise'` |
 | `subscriptionLimits` | object | Per-tier limits (apps, seats, apiKeys, logRetentionDays, etc.) |
+| `monthlyLogsCap` | object | Past `monthlyLogs`: the lowest level still taken (ERROR) and the hard stop's multiple (2), where every log is refused |
 | `isValidSubscriptionLevel` | function | Type guard for `SubscriptionLevel` values |
 
 ### Plans
@@ -84,6 +87,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'` |
@@ -134,6 +141,7 @@ A plugin sends only the token to the API (`Authorization: Bearer <token>`) and e
 | `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) |
+| `MAX_LOG_PAYLOAD_LENGTH` | constant | The longest `encrypted.payload` `POST /logs` takes (16 KB of base64); longer is refused with a 413 |
 | `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 |
@@ -172,7 +180,7 @@ 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`.
+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
 
@@ -180,20 +188,26 @@ TypeScript can't be imported from Python or Go, so the kit ships its contract in
 
 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
 ```