@band-ai/band-sdk-core 0.4.0-dev.2 → 0.4.1

package/README.md

@@ -1,46 +1,88 @@
-# band-sdk-core-wasm
+# @band-ai/band-sdk-core
 
-JavaScript package for [`band-sdk-core-core`](../core), published as
-`@band-ai/band-sdk-core` for Node.
+Shared Band event-payload validation, memory-taxonomy, and inbound-delivery
+runtime state, compiled from Rust to WebAssembly for Node. Every function
+is synchronous, pure computation — no network, filesystem, or logging.
+
+```
+band-sdk-core-core (Rust)  -->  @band-ai/band-sdk-core (this package, npm)  -->  band-sdk-typescript
+```
+
+If you're using [`band-sdk-typescript`](https://github.com/band-ai/band-sdk-typescript),
+it already depends on this package — you don't need to install it
+yourself. Install it directly only if you're calling into it without that
+SDK. Full picture: [repository architecture](https://github.com/band-ai/band-sdk-core#architecture).
+
+## Install
+
+```bash
+npm install @band-ai/band-sdk-core
+```
+
+The package is Node CommonJS with an eager WASM load — there is no `init`
+step, and no Rust or `wasm-pack` toolchain needed to install. Both
+`require()` and ESM `import()` resolve it at the package root.
+
+## Quickstart
+
+```js
+const { validateEventPayload } = require("@band-ai/band-sdk-core");
+
+try {
+  const payload = validateEventPayload("room_deleted", { id: "room-1" });
+} catch (err) {
+  for (const { path, code, message } of err.issues) {
+    console.error(`${path}: ${code} - ${message}`);
+  }
+}
+```
+
+`validateEventPayload` is the platform's inbound WebSocket payload policy:
+normalize a well-formed payload, or throw with every violation reported at
+once, never just the first.
 
 ## Public surface
 
-`validateEventPayload(eventType, raw, traceContext?)`. `eventType` is the
-platform event name (`"message_created"`, `"agent.control"`, …). `raw` is a
-plain JS value. Success returns the normalized payload (`event_created`
-returns the input unchanged). Failure throws a native `Error` with
-`.issues` (`{path, code, message}` objects) and `.traceContext` — not a
-message-only error. There is no custom exception class.
+### `validateEventPayload(eventType, raw, traceContext?)`
+
+`eventType` is the platform event name (`"message_created"`,
+`"agent.control"`, …). `raw` is a plain JS value. Success returns the
+normalized payload (`event_created` returns the input unchanged). Failure
+throws a native `Error` with `.issues` (`{path, code, message}` objects)
+and `.traceContext` — not a message-only error. There is no custom
+exception class.
+
+### Delivery-state runtime classes
 
 `ClaimRegistry`, `RetryTracker`, and `ParticipantRoster` are the
-inbound-delivery runtime state classes -- lifecycle and design decisions:
-[`../core/docs/runtime-state-policy.md`](../core/docs/runtime-state-policy.md).
+inbound-delivery runtime state classes — lifecycle and design decisions:
+[`runtime-state-policy.md`](https://github.com/band-ai/band-sdk-core/blob/main/crates/core/docs/runtime-state-policy.md).
+
 A participant is any plain object; `add`/`setAll` read `id`, `name`,
 `type`, `handle`, `description` from it and `list()` returns objects with
 exactly those five keys. `id` is required and must be a string; the other
 four are each a string or `null`/absent. `setAll` takes an optional
-`traceContext` and throws -- leaving the roster unchanged, with `.issues`
-and `.traceContext` attached like `validateEventPayload`'s error -- if its
+`traceContext` and throws — leaving the roster unchanged, with `.issues`
+and `.traceContext` attached like `validateEventPayload`'s error — if its
 snapshot names the same `id` twice. `RetryTracker`'s `maxTracked` must be
 at least `1`; `0` throws. `ClaimRegistry`'s `maxCompleted` must be at
-least `1` too -- `0` also throws.
+least `1` too — `0` also throws.
+
+### `validateMemoryTypeForSystem(system, type, traceContext?)`
 
-`validateMemoryTypeForSystem(system, type, traceContext?)` validates the
-canonical memory taxonomy -- design decisions:
-[`../core/docs/memory-taxonomy-policy.md`](../core/docs/memory-taxonomy-policy.md).
+Validates the canonical memory taxonomy — design decisions:
+[`memory-taxonomy-policy.md`](https://github.com/band-ai/band-sdk-core/blob/main/crates/core/docs/memory-taxonomy-policy.md).
 `system` and `type` are wire-name strings (`MemorySystem`/`MemoryType` in
-`index.d.ts` are string-literal types, not classes -- there is no runtime
+`index.d.ts` are string-literal types, not classes — there is no runtime
 enum on this boundary, matching how `EventType` stays a plain string in
 `validateEventPayload`). Returns `void` on success. Failure throws a
 native `Error` with the same `.issues`/`.traceContext` contract as
-`validateEventPayload` -- an unrecognized `system` and an unrecognized
+`validateEventPayload` — an unrecognized `system` and an unrecognized
 `type` are independent issues, both reported when both strings are
 invalid.
 
-The package is Node CommonJS with an eager WASM load. There is no default
-`init`. The public declaration is `index.d.ts`:
-`validateEventPayload(...): unknown`. Node `require()` and ESM `import()`
-both resolve `@band-ai/band-sdk-core` at the package root.
+The public declaration is
+[`index.d.ts`](https://github.com/band-ai/band-sdk-core/blob/main/crates/wasm/index.d.ts).
 
 ## Build / test
 
@@ -51,3 +93,7 @@ just test-wasm   # suite in Node
 just pack-npm    # Node tarball + require/import consumers
 just build-wasm  # Node package output
 ```
+
+## License
+
+MIT — see [LICENSE](https://github.com/band-ai/band-sdk-core/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@band-ai/band-sdk-core",
-  "version": "0.4.0-dev.2",
+  "version": "0.4.1",
   "description": "Shared Band event-payload validation",
   "license": "MIT",
   "repository": {