@plexspaces/sdk 0.1.7 → 0.1.9

package/README.md

@@ -220,6 +220,121 @@ host.registry.heartbeat(actorId, RegistryObjectType.ACTOR);
 
 WIT TypeScript types are generated automatically as part of the SDK build process (`npm run build`). These types are optional and only used internally by the SDK for type checking. Client code doesn't need to generate or import these types - the SDK abstracts all WIT details away.
 
+## WsThinClient — Browser & Node.js Thin-Node SDK
+
+`WsThinClient` connects a browser tab (or Node.js process) to a PlexSpaces node
+as a **thin node** over a binary protobuf WebSocket connection.  Zero runtime
+dependencies — all wire encoding is hand-rolled in `src/wire/ws-frame-wire.ts`.
+
+### Thin Node vs Full Node
+
+| | Full Node | Thin Node |
+|---|---|---|
+| Connection | gRPC or WebSocket | WebSocket only |
+| Hosts WASM actors | ✓ | ✗ |
+| Receives actor messages | ✓ | ✓ (via `onMessage`) |
+| Sends tell/ask | ✓ | ✓ |
+| Participates in SWIM | ✓ | ✗ (filtered out of indirect ping targets) |
+| Node role | `NODE_ROLE_FULL` | `NODE_ROLE_THIN` |
+
+### Quick Start
+
+```typescript
+import { WsThinClient, ActorID } from "@plexspaces/sdk";
+
+const client = new WsThinClient({
+  wsUrl: "ws://localhost:8091/ws",
+  jwtToken: optionalJwt,           // appended as ?token= query param
+  nodeId: WsThinClient.newUlid(),  // ULID preferred; server assigns one if omitted
+  namespace: "my-app",
+});
+
+// Connect — sends NodeRegistration handshake, receives assigned node_id
+const nodeId = await client.connect();
+
+// Build a canonical actor ID on this thin node
+const myActorId = client.localActorId("alice", "ChatClient", "my-app");
+// → "alice//ChatClient::my-app@<assignedNodeId>"
+
+// Build an ID for a server-side actor
+const roomId = new ActorID("lobby", "ChatRoomActor", "my-app", leaderNodeId).toString();
+
+// Fire-and-forget tell
+await client.tell(roomId, "send", { sender_actor_id: myActorId, text: "hello" });
+
+// Request-reply ask (5s timeout)
+const reply = await client.ask(roomId, "status", {});
+
+// Receive incoming tells addressed to this thin node
+client.onMessage((actorId, msgType, payload) => {
+  if (msgType === "chat_message") console.log(payload);
+});
+
+// Ping another node for resource hints
+const ping = await client.pingNode("other-node-id");
+// → { success, nodeId, cpuPercent, memoryAvailableMb, availableCores }
+
+await client.disconnect();
+```
+
+### Interface
+
+```typescript
+export interface ThinClientOptions {
+  wsUrl: string;        // "ws://host:port/ws"
+  jwtToken?: string;    // optional Bearer token
+  nodeId?: string;      // ULID preferred; auto-generated if omitted
+  tenant?: string;      // placed in NodeRegistration.capabilities["tenant"]
+  namespace?: string;   // placed in NodeRegistration.capabilities["namespace"]
+}
+
+// Typed view of PingResponse resource fields (proto fields 9–11).
+// Not a proto message — TypeScript interface over decoded response.
+export interface ThinNodePingResult {
+  success: boolean;
+  nodeId: string;
+  cpuPercent: number;         // 0–100, from sysinfo on the target node
+  memoryAvailableMb: number;  // available RAM in MiB
+  availableCores: number;     // logical CPU count
+}
+
+export class WsThinClient {
+  constructor(opts: ThinClientOptions)
+
+  connect(): Promise<string>         // returns assigned node_id; starts 25s heartbeat
+  tell(actorId, msgType, payload): Promise<void>
+  ask(actorId, msgType, payload, timeoutMs?): Promise<unknown>
+  onMessage(handler: (actorId, msgType, payload) => void): void
+  pingNode(targetNodeId, timeoutMs?): Promise<ThinNodePingResult>
+  heartbeat(): Promise<void>
+  localActorId(name, type, namespace?): string  // "{name}//{type}::{ns}@{assignedNodeId}"
+  get nodeId(): string
+  static newUlid(): string           // 26-char ULID, Crockford base32, crypto random
+  disconnect(): Promise<void>
+}
+```
+
+### Wire Protocol
+
+Binary protobuf `WsFrame` over WebSocket (`binaryType = 'arraybuffer'`).
+Field numbers are defined in `proto/plexspaces/v1/transport/websocket.proto`
+and documented in `src/wire/ws-frame-wire.ts`.
+
+| Operation | WsFrame field | Direction |
+|---|---|---|
+| NodeRegistration handshake | field 20 → ACK field 21 | client → server → client |
+| tell (fire-and-forget) | field 10 | client → server |
+| tell_response | field 11 | server → client |
+| ask (request-reply) | field 12 → response field 13 | client → server → client |
+| heartbeat | field 24 → ACK field 25 | client → server → client |
+| node_ping | field 22 → response field 23 | client → server → client |
+| incoming_tell (server push) | field 10 | server → client |
+
+### Examples
+
+- [`ws_chat_room`](../../examples/typescript/apps/ws_chat_room/README.md) — real-time chat via PG broadcast
+- [`mersenne_prime`](../../examples/typescript/apps/mersenne_prime/README.md) — distributed computation with Web Workers
+
 ## License
 
 AGPL-3.0-or-later

package/dist/actor.js

@@ -18,10 +18,7 @@
  * Type definitions are generated in src/generated/ but are not imported here
  * to keep the SDK simple. The virtual import works at runtime without types.
  */
-// @ts-ignore - Virtual import provided by jco componentize at runtime
-// eslint-disable-next-line @typescript-eslint/ban-ts-comment
-// @ts-expect-error - Virtual import - types are optional (generated in src/generated/)
-import { log as hostLog } from 'plexspaces:actor/host@0.1.0';
+import { log as hostLog } from 'plexspaces:actor/host-logging@0.1.0';
 import { getActorDefinition } from './decorators.js';
 import { decodeWitPayloadUtf8, encodeWitPayloadUtf8 } from './wit-payload.js';
 /**

package/dist/host.d.ts

@@ -119,12 +119,110 @@ export declare class Registry {
     heartbeat(objectId: string, objectType?: number, tenantId?: string, namespace?: string): void;
 }
 export { RegistryObjectType };
+/**
+ * KVStore provides namespaced KV operations.
+ * Equivalent to Cloudflare DO's this.state.storage API.
+ * Access via host.kv.get(), host.kv.put() etc.
+ */
+export declare class KVStore {
+    get(key: string): string | null;
+    put(key: string, value: string): void;
+    delete(key: string): void;
+    list(prefix: string): string[];
+    putWithTtl(key: string, value: string, ttlSeconds: number): void;
+    getTtl(key: string): number;
+    cas(key: string, expected: string | null, newValue: string): boolean;
+    increment(key: string, delta: number): number;
+    multiGet(keys: string[]): (string | null)[];
+    multiPut(entries: Record<string, string>): void;
+    getJson<T = unknown>(key: string): T | null;
+    putJson(key: string, value: unknown): void;
+}
+/**
+ * AlarmClient provides durable alarm scheduling.
+ * Equivalent to Cloudflare DO's setAlarm/getAlarm/deleteAlarm.
+ * Access via host.alarm.set(), host.alarm.get(), host.alarm.delete() etc.
+ */
+export declare class AlarmClient {
+    set(timestampMs: number): void;
+    setIn(delayMs: number): void;
+    get(): number;
+    delete(): void;
+}
+/**
+ * LockClient provides distributed lock operations.
+ * Access via host.locks.acquire(), host.locks.release() etc.
+ */
+export declare class LockClient {
+    acquire(holderId: string, lockName: string, leaseDurationSecs: number, timeoutMs: bigint): Uint8Array;
+    release(lockId: string, holderId: string, lockVersion: string): void;
+    renew(lockId: string, holderId: string, lockVersion: string, leaseDurationSecs: number): Uint8Array;
+}
+/**
+ * BlobClient provides blob storage operations.
+ * Access via host.blob.upload(), host.blob.download() etc.
+ */
+export declare class BlobClient {
+    upload(name: string, data: Uint8Array, contentType: string): string;
+    download(blobId: string): Uint8Array;
+    delete(blobId: string): void;
+    list(prefix: string): string[];
+}
+/**
+ * ActorRef is a lightweight handle to a named virtual actor.
+ * Equivalent to Cloudflare DO's env.BINDING.get(id).
+ * Use getActorRef() to obtain one.
+ *
+ * @example
+ * ```typescript
+ * const room = getActorRef("ChatRoomActor", roomId, "default");
+ * const result = room.ask("send_message", payload, BigInt(5000));
+ * ```
+ */
+export declare class ActorRef {
+    readonly actorId: string;
+    constructor(actorType: string, name: string, namespace: string);
+    id(): string;
+    tell(msgType: string, payload: Uint8Array): void;
+    ask(msgType: string, payload: Uint8Array, timeoutMs: bigint): Uint8Array;
+}
+/**
+ * getActorRef constructs an ActorRef for a named virtual actor.
+ * The actor is created automatically on first contact (virtual actor pattern).
+ * Equivalent to Cloudflare: `const room = env.CHAT_ROOM.get(roomId)`
+ */
+export declare function getActorRef(actorType: string, name: string, namespace: string): ActorRef;
 export declare class Host {
     readonly processGroups: ProcessGroups;
     /** Tuple space: list-in, list-out. Use null in patterns for wildcards. */
     readonly ts: TupleSpace;
     /** Object registry: register, discover, and look up actors and services. */
     readonly registry: Registry;
+    /** Namespaced KV store: host.kv.get(), host.kv.put() etc. */
+    readonly kv: KVStore;
+    /** Durable alarm client: host.alarm.set(), host.alarm.get() etc. */
+    readonly alarm: AlarmClient;
+    /** Distributed lock client: host.locks.acquire(), host.locks.release() etc. */
+    readonly locks: LockClient;
+    /** Blob storage client: host.blob.upload(), host.blob.download() etc. */
+    readonly blob: BlobClient;
+    /**
+     * Create an ergonomic HTTP client for a named service link.
+     *
+     * The link must be pre-configured in RuntimeConfig.service_links.
+     * The host handles retries, circuit breaking, and auth injection.
+     *
+     * @param linkName - Service link name (e.g. "payments-api")
+     * @returns A {@link ServiceHttpClient} bound to that link
+     *
+     * @example
+     * ```typescript
+     * const http = host.httpClient("payments-api");
+     * const balance = http.get("/v1/balance?account=123");
+     * const result = http.post("/v1/transfer", { amount: 100 });
+     * ```
+     */
+    httpClient(linkName: string): ServiceHttpClient;
     /** Send message to another actor (fire-and-forget) */
     send(to: string, msgType: string, payload?: unknown): string;
     /** Send request and wait for response (request-reply) */
@@ -172,14 +270,6 @@ export declare class Host {
     error(message: string): void;
     /** Get current timestamp in milliseconds */
     nowMs(): number;
-    kvGet(key: string): string;
-    kvPut(key: string, value: string): string;
-    kvDelete(key: string): string;
-    kvList(prefix: string): string;
-    /** Retrieve a JSON value by key. Returns parsed object or null if not found. */
-    kvGetJson<T = unknown>(key: string): T | null;
-    /** Serialize value to JSON and store under key. Throws on write failure. */
-    kvPutJson(key: string, value: unknown): void;
     /** Increment a single named application metric counter by 1. Errors are swallowed. */
     incrCounter(applicationId: string, name: string): void;
     /** Increment one or more named application metric counters. Errors are swallowed. */
@@ -192,13 +282,6 @@ export declare class Host {
     tsTakePayload(data: Uint8Array): Uint8Array;
     /** @internal */
     tsReadAllPayload(data: Uint8Array): Uint8Array;
-    lockAcquire(tenantId: string, namespace: string, holderId: string, lockName: string, leaseDurationSecs?: number, timeoutMs?: number): string;
-    lockRelease(lockId: string, tenantId: string, namespace: string, holderId: string, lockVersion: string): string;
-    lockRenew(lockId: string, tenantId: string, namespace: string, holderId: string, lockVersion: string, leaseDurationSecs?: number): string;
-    blobUpload(blobId: string, data: string, contentType?: string): string;
-    blobDownload(blobId: string): string;
-    blobDelete(blobId: string): string;
-    blobList(prefix: string): string;
     /**
      * Checkout an actor from a named pool. Returns handle { actor_id, pool_name, checkout_id } or null on failure.
      */
@@ -276,9 +359,13 @@ export declare class EventLog {
  * The link must be pre-configured in RuntimeConfig.service_links.
  * The host handles retries, circuit breaking, and auth injection.
  *
+ * Prefer creating instances via {@link Host.httpClient} rather than calling
+ * the constructor directly:
+ *
  * @example
  * ```typescript
- * const http = new ServiceHttpClient("payments-api");
+ * // Preferred: use the factory method
+ * const http = host.httpClient("payments-api");
  * const balance = http.get("/v1/balance?account=123");
  * const result = http.post("/v1/transfer", { amount: 100 });
  * ```