@plexspaces/sdk 0.1.5 → 0.1.8

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) */
@@ -133,12 +231,19 @@ export declare class Host {
     selfId(): string;
     /**
      * Spawn a new actor through the framework-owned actor spawn path exposed by the host.
+     * Returns the canonical actor ID assigned by the framework — use this ID (not actorName)
+     * for all subsequent ask/send/stop calls.
+     *
      * @param moduleRef - Actor type/module reference (must be deployed)
-     * @param actorId - Unique ID for the new actor (empty = auto-generated ULID)
-     * @param initConfig - Optional config passed to the new actor's init()
-     * @returns Spawned actor ID string (may be auto-generated if actorId was empty)
+     * @param actorName - Requested name for the new actor. The framework forms the full canonical
+     *                    ID from this name, moduleRef, namespace and node. Pass empty string to
+     *                    let the framework auto-generate a ULID name.
+     * @param role - Disambiguation key used ONLY when multiple actors in the same supervisor share
+     *               the same actor_type (moduleRef). Pass empty string when moduleRef is unique.
+     * @param args - Key-value init arguments forwarded to the new actor's init()
+     * @returns Canonical actor ID string assigned by the framework
      */
-    spawn(moduleRef: string, actorId?: string, initConfig?: unknown): string;
+    spawn(moduleRef: string, actorName?: string, role?: string, args?: Record<string, string>): string;
     /** Stop an actor gracefully */
     stop(actorId: string): void;
     /** Bidirectional link */
@@ -165,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. */
@@ -185,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.
      */
@@ -269,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 });
  * ```