@rkat/mobkit-sdk 0.4.9

package/dist/cjs/builder.cjs

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * MobKit builder chain — chainable configuration for the runtime.
+ *
+ * @example
+ * ```ts
+ * import { MobKit } from "@rkat/mobkit-sdk";
+ *
+ * const rt = await MobKit.builder()
+ *   .mob("config/mob.toml")
+ *   .sessionService(builder, store)
+ *   .discovery(discoverFn)
+ *   .build();
+ *
+ * const handle = rt.mobHandle();
+ * const status = await handle.status();
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MobKit = exports.MobKitBuilder = void 0;
+const node_fs_1 = require("node:fs");
+function defaultConfig() {
+    return {
+        mobConfigPath: null,
+        sessionBuilder: null,
+        sessionStore: null,
+        discoveryCallback: null,
+        preSpawnCallback: null,
+        errorCallback: null,
+        eventLog: null,
+        gatingConfigPath: null,
+        routingConfigPath: null,
+        schedulingFiles: [],
+        memoryConfig: null,
+        authConfig: null,
+        gatewayBin: null,
+        modules: [],
+    };
+}
+// -- MobKitBuilder --------------------------------------------------------
+/**
+ * Chainable builder for MobKit runtime configuration.
+ *
+ * @example
+ * ```ts
+ * const rt = await MobKit.builder()
+ *   .mob("config/mob.toml")
+ *   .gateway("./target/release/phase0b_rpc_gateway")
+ *   .build();
+ * ```
+ */
+class MobKitBuilder {
+    /** @internal */
+    _config = defaultConfig();
+    mob(configPath) {
+        this._config.mobConfigPath = configPath;
+        return this;
+    }
+    sessionService(builder, store) {
+        this._config.sessionBuilder = builder;
+        this._config.sessionStore = store ?? null;
+        return this;
+    }
+    discovery(callback) {
+        this._config.discoveryCallback = callback;
+        return this;
+    }
+    preSpawn(callback) {
+        this._config.preSpawnCallback = callback;
+        return this;
+    }
+    eventLog(options) {
+        this._config.eventLog = { ...options };
+        return this;
+    }
+    onError(callback) {
+        this._config.errorCallback = callback;
+        return this;
+    }
+    gating(configPath) {
+        this._config.gatingConfigPath = configPath;
+        return this;
+    }
+    routing(configPath) {
+        this._config.routingConfigPath = configPath;
+        return this;
+    }
+    scheduling(...scheduleFiles) {
+        this._config.schedulingFiles = scheduleFiles;
+        return this;
+    }
+    memory(config, options) {
+        this._config.memoryConfig =
+            config ?? { stores: options?.stores ?? [] };
+        return this;
+    }
+    auth(config) {
+        this._config.authConfig = config;
+        return this;
+    }
+    gateway(binPath) {
+        this._config.gatewayBin = binPath;
+        return this;
+    }
+    modules(moduleSpecs) {
+        this._config.modules = moduleSpecs;
+        return this;
+    }
+    async build() {
+        this._applyConventionDefaults();
+        // Dynamic import to break circular dep (runtime imports from builder config type)
+        const { MobKitRuntime } = await Promise.resolve().then(() => __importStar(require("./runtime.cjs")));
+        return MobKitRuntime._create(this._config);
+    }
+    _applyConventionDefaults() {
+        if (this._config.gatingConfigPath === null) {
+            const candidate = "config/gating.toml";
+            if ((0, node_fs_1.existsSync)(candidate)) {
+                this._config.gatingConfigPath = candidate;
+            }
+        }
+        if (this._config.routingConfigPath === null) {
+            const candidate = "deployment/routing.toml";
+            if ((0, node_fs_1.existsSync)(candidate)) {
+                this._config.routingConfigPath = candidate;
+            }
+        }
+        if (this._config.schedulingFiles.length === 0) {
+            const files = [];
+            const defaultFile = "config/defaults/schedules.toml";
+            if ((0, node_fs_1.existsSync)(defaultFile))
+                files.push(defaultFile);
+            const overrideFile = "deployment/schedules.toml";
+            if ((0, node_fs_1.existsSync)(overrideFile))
+                files.push(overrideFile);
+            if (files.length > 0) {
+                this._config.schedulingFiles = files;
+            }
+        }
+    }
+}
+exports.MobKitBuilder = MobKitBuilder;
+// -- MobKit static factory ------------------------------------------------
+class MobKit {
+    static builder() {
+        return new MobKitBuilder();
+    }
+}
+exports.MobKit = MobKit;

package/dist/cjs/client.cjs

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * Low-level JSON-RPC clients for MobKit.
+ *
+ * These are the original typed client classes preserved for backward
+ * compatibility. For new code, prefer the high-level {@link MobHandle} API
+ * via `runtime.mobHandle()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MobkitAsyncClient = exports.MobkitTypedClient = void 0;
+const errors_js_1 = require("./errors.cjs");
+const transport_js_1 = require("./transport.cjs");
+// -- Type guards ----------------------------------------------------------
+function asValueObject(value) {
+    if (typeof value !== "object" || value === null)
+        return {};
+    return value;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isMobkitStatusResult(value) {
+    const o = asValueObject(value);
+    return (typeof o.contract_version === "string" &&
+        typeof o.running === "boolean" &&
+        isStringArray(o.loaded_modules));
+}
+function isMobkitCapabilitiesResult(value) {
+    const o = asValueObject(value);
+    return (typeof o.contract_version === "string" &&
+        isStringArray(o.methods) &&
+        isStringArray(o.loaded_modules));
+}
+function isMobkitReconcileResult(value) {
+    const o = asValueObject(value);
+    return (typeof o.accepted === "boolean" &&
+        isStringArray(o.reconciled_modules) &&
+        typeof o.added === "number" &&
+        Number.isInteger(o.added));
+}
+function isMobkitSpawnMemberResult(value) {
+    const o = asValueObject(value);
+    return typeof o.accepted === "boolean" && typeof o.module_id === "string";
+}
+function isMobkitSubscribeResult(value) {
+    const o = asValueObject(value);
+    if (o.scope !== "mob" && o.scope !== "agent" && o.scope !== "interaction") {
+        return false;
+    }
+    if (!(o.replay_from_event_id === null ||
+        typeof o.replay_from_event_id === "string")) {
+        return false;
+    }
+    const ka = asValueObject(o.keep_alive);
+    if (!Number.isInteger(ka.interval_ms) || typeof ka.event !== "string") {
+        return false;
+    }
+    if (typeof o.keep_alive_comment !== "string")
+        return false;
+    if (!isStringArray(o.event_frames))
+        return false;
+    if (!Array.isArray(o.events))
+        return false;
+    return o.events.every((ev) => {
+        const e = asValueObject(ev);
+        return (typeof e.event_id === "string" &&
+            typeof e.source === "string" &&
+            typeof e.timestamp_ms === "number" &&
+            Number.isInteger(e.timestamp_ms) &&
+            Object.prototype.hasOwnProperty.call(e, "event"));
+    });
+}
+// -- Response parsing -----------------------------------------------------
+function parseJsonRpcResponse(payload, expectedId) {
+    if (typeof payload !== "object" || payload === null) {
+        throw new Error("invalid JSON-RPC response envelope");
+    }
+    const envelope = payload;
+    if (envelope.jsonrpc !== "2.0" || envelope.id !== expectedId) {
+        throw new Error("invalid JSON-RPC response envelope");
+    }
+    const hasResult = Object.prototype.hasOwnProperty.call(envelope, "result");
+    const hasError = Object.prototype.hasOwnProperty.call(envelope, "error");
+    if (hasResult === hasError) {
+        throw new Error("invalid JSON-RPC response envelope");
+    }
+    if (hasError) {
+        const rpcError = asValueObject(envelope.error);
+        if (!Number.isInteger(rpcError.code) ||
+            typeof rpcError.message !== "string") {
+            throw new Error("invalid JSON-RPC response envelope");
+        }
+    }
+    return envelope;
+}
+function unwrapTypedResult(response, requestId, method, isExpected) {
+    if ("error" in response && response.error) {
+        throw new errors_js_1.RpcError(response.error.code, response.error.message, requestId, method);
+    }
+    const result = response.result;
+    if (!isExpected(result)) {
+        throw new Error(`invalid result payload for ${method}`);
+    }
+    return result;
+}
+function buildSubscribeParams(params) {
+    const next = {};
+    if (params.scope !== undefined)
+        next.scope = params.scope;
+    if (params.last_event_id !== undefined) {
+        next.last_event_id = params.last_event_id;
+    }
+    if (params.agent_id !== undefined)
+        next.agent_id = params.agent_id;
+    return next;
+}
+// -- MobkitTypedClient (sync) ---------------------------------------------
+class MobkitTypedClient {
+    gatewayBin;
+    syncTransport;
+    constructor(gatewayBin) {
+        this.gatewayBin = gatewayBin;
+        this.syncTransport = (0, transport_js_1.createGatewaySyncTransport)(gatewayBin);
+    }
+    rpc(id, method, params) {
+        const payload = this.syncTransport((0, transport_js_1.buildJsonRpcRequest)(id, method, params));
+        return parseJsonRpcResponse(payload, id);
+    }
+    status(requestId = "status") {
+        return unwrapTypedResult(this.rpc(requestId, "mobkit/status", {}), requestId, "mobkit/status", isMobkitStatusResult);
+    }
+    capabilities(requestId = "capabilities") {
+        return unwrapTypedResult(this.rpc(requestId, "mobkit/capabilities", {}), requestId, "mobkit/capabilities", isMobkitCapabilitiesResult);
+    }
+    reconcile(modules, requestId = "reconcile") {
+        return unwrapTypedResult(this.rpc(requestId, "mobkit/reconcile", { modules }), requestId, "mobkit/reconcile", isMobkitReconcileResult);
+    }
+    spawnMember(moduleId, requestId = "spawn_member") {
+        return unwrapTypedResult(this.rpc(requestId, "mobkit/spawn_member", { module_id: moduleId }), requestId, "mobkit/spawn_member", isMobkitSpawnMemberResult);
+    }
+    subscribeEvents(params = {}, requestId = "events_subscribe") {
+        return unwrapTypedResult(this.rpc(requestId, "mobkit/events/subscribe", buildSubscribeParams(params)), requestId, "mobkit/events/subscribe", isMobkitSubscribeResult);
+    }
+}
+exports.MobkitTypedClient = MobkitTypedClient;
+// -- MobkitAsyncClient (async) --------------------------------------------
+class MobkitAsyncClient {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    static fromGatewayBin(gatewayBin) {
+        return new MobkitAsyncClient((0, transport_js_1.createGatewayAsyncTransport)(gatewayBin));
+    }
+    static fromHttp(endpoint, options = {}) {
+        return new MobkitAsyncClient((0, transport_js_1.createJsonRpcHttpTransport)(endpoint, options));
+    }
+    async rpc(id, method, params) {
+        const payload = await this.transport((0, transport_js_1.buildJsonRpcRequest)(id, method, params));
+        return parseJsonRpcResponse(payload, id);
+    }
+    async request(id, method, params, isExpected) {
+        const response = await this.rpc(id, method, params);
+        return unwrapTypedResult(response, id, method, isExpected);
+    }
+    async status(requestId = "status") {
+        return this.request(requestId, "mobkit/status", {}, isMobkitStatusResult);
+    }
+    async capabilities(requestId = "capabilities") {
+        return this.request(requestId, "mobkit/capabilities", {}, isMobkitCapabilitiesResult);
+    }
+    async reconcile(modules, requestId = "reconcile") {
+        return this.request(requestId, "mobkit/reconcile", { modules }, isMobkitReconcileResult);
+    }
+    async spawnMember(moduleId, requestId = "spawn_member") {
+        return this.request(requestId, "mobkit/spawn_member", { module_id: moduleId }, isMobkitSpawnMemberResult);
+    }
+    async subscribeEvents(params = {}, requestId = "events_subscribe") {
+        return this.request(requestId, "mobkit/events/subscribe", buildSubscribeParams(params), isMobkitSubscribeResult);
+    }
+}
+exports.MobkitAsyncClient = MobkitAsyncClient;

package/dist/cjs/config/auth.cjs

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * Auth configuration for MobKit runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.google = google;
+exports.googleAuthConfigToDict = googleAuthConfigToDict;
+exports.jwt = jwt;
+exports.jwtAuthConfigToDict = jwtAuthConfigToDict;
+function google(clientId, options) {
+    return {
+        clientId,
+        discoveryUrl: options?.discoveryUrl ??
+            "https://accounts.google.com/.well-known/openid-configuration",
+        audience: options?.audience ?? null,
+        leewaySeconds: options?.leewaySeconds ?? 60,
+    };
+}
+function googleAuthConfigToDict(config) {
+    return {
+        provider: "google",
+        client_id: config.clientId,
+        discovery_url: config.discoveryUrl,
+        audience: config.audience ?? config.clientId,
+        leeway_seconds: config.leewaySeconds,
+    };
+}
+function jwt(sharedSecret, options) {
+    return {
+        sharedSecret,
+        issuer: options?.issuer ?? null,
+        audience: options?.audience ?? null,
+        leewaySeconds: options?.leewaySeconds ?? 60,
+    };
+}
+function jwtAuthConfigToDict(config) {
+    return {
+        provider: "jwt",
+        shared_secret: config.sharedSecret,
+        issuer: config.issuer,
+        audience: config.audience,
+        leeway_seconds: config.leewaySeconds,
+    };
+}

package/dist/cjs/config/index.cjs

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Configuration modules for MobKit runtime.
+ *
+ * @example
+ * ```ts
+ * import { auth, memory, sessionStore } from "@rkat/mobkit-sdk";
+ *
+ * const authConfig = auth.google("my-client-id");
+ * const memConfig = memory.elephant("http://elephant:8080");
+ * const storeConfig = sessionStore.json("./sessions.json");
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionStore = exports.memory = exports.auth = void 0;
+exports.auth = __importStar(require("./auth.cjs"));
+exports.memory = __importStar(require("./memory.cjs"));
+exports.sessionStore = __importStar(require("./session-store.cjs"));

package/dist/cjs/config/memory.cjs

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Memory backend configuration for MobKit runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.elephant = elephant;
+exports.elephantMemoryConfigToDict = elephantMemoryConfigToDict;
+function elephant(endpoint, options) {
+    return {
+        endpoint,
+        spaceId: options?.spaceId ?? null,
+        collection: options?.collection ?? null,
+        stores: options?.stores ?? [],
+    };
+}
+function elephantMemoryConfigToDict(config) {
+    const result = {
+        backend: "elephant",
+        endpoint: config.endpoint,
+    };
+    if (config.spaceId)
+        result.space_id = config.spaceId;
+    if (config.collection)
+        result.collection = config.collection;
+    if (config.stores.length > 0)
+        result.stores = [...config.stores];
+    return result;
+}

package/dist/cjs/config/session-store.cjs

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Session store configuration for MobKit runtime.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.json = json;
+exports.jsonSessionStoreConfigToDict = jsonSessionStoreConfigToDict;
+exports.bigquery = bigquery;
+exports.bigquerySessionStoreConfigToDict = bigquerySessionStoreConfigToDict;
+function json(path, options) {
+    return {
+        path,
+        staleLockThresholdSeconds: options?.staleLockThresholdSeconds ?? 30,
+    };
+}
+function jsonSessionStoreConfigToDict(config) {
+    return {
+        store: "json_file",
+        path: config.path,
+        stale_lock_threshold_seconds: config.staleLockThresholdSeconds,
+    };
+}
+function bigquery(dataset, table, options) {
+    return {
+        dataset,
+        table,
+        projectId: options?.projectId ?? null,
+        gcIntervalHours: options?.gcIntervalHours ?? 6,
+    };
+}
+function bigquerySessionStoreConfigToDict(config) {
+    const result = {
+        store: "bigquery",
+        dataset: config.dataset,
+        table: config.table,
+        gc_interval_hours: config.gcIntervalHours,
+    };
+    if (config.projectId)
+        result.project_id = config.projectId;
+    return result;
+}

package/dist/cjs/errors.cjs

@@ -0,0 +1,82 @@
+"use strict";
+/**
+ * Typed error hierarchy for the MobKit SDK.
+ *
+ * @example
+ * ```ts
+ * import { RpcError, MobKitError } from "@rkat/mobkit-sdk";
+ *
+ * try {
+ *   await handle.status();
+ * } catch (err) {
+ *   if (err instanceof RpcError) {
+ *     console.error(`RPC ${err.method} failed: code=${err.code}`);
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MobkitRpcError = exports.NotConnectedError = exports.ContractMismatchError = exports.CapabilityUnavailableError = exports.RpcError = exports.TransportError = exports.MobKitError = void 0;
+// -- Base error -----------------------------------------------------------
+/** Base exception for all MobKit SDK errors. */
+class MobKitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MobKitError";
+    }
+}
+exports.MobKitError = MobKitError;
+// -- Transport errors -----------------------------------------------------
+/** Raised when the transport layer fails (subprocess died, connection refused, etc.). */
+class TransportError extends MobKitError {
+    constructor(message) {
+        super(message);
+        this.name = "TransportError";
+    }
+}
+exports.TransportError = TransportError;
+// -- RPC errors -----------------------------------------------------------
+/** Raised when a JSON-RPC call returns an error response. */
+class RpcError extends MobKitError {
+    code;
+    requestId;
+    method;
+    constructor(code, message, requestId, method) {
+        super(message);
+        this.code = code;
+        this.requestId = requestId;
+        this.method = method;
+        this.name = "RpcError";
+    }
+}
+exports.RpcError = RpcError;
+// -- Capability errors ----------------------------------------------------
+/** Raised when a requested capability is not available on the runtime. */
+class CapabilityUnavailableError extends MobKitError {
+    constructor(message) {
+        super(message);
+        this.name = "CapabilityUnavailableError";
+    }
+}
+exports.CapabilityUnavailableError = CapabilityUnavailableError;
+// -- Contract errors ------------------------------------------------------
+/** Raised when the SDK and runtime contract versions are incompatible. */
+class ContractMismatchError extends MobKitError {
+    constructor(message) {
+        super(message);
+        this.name = "ContractMismatchError";
+    }
+}
+exports.ContractMismatchError = ContractMismatchError;
+// -- Connection errors ----------------------------------------------------
+/** Raised when an operation requires a connected runtime but none is available. */
+class NotConnectedError extends MobKitError {
+    constructor(message) {
+        super(message);
+        this.name = "NotConnectedError";
+    }
+}
+exports.NotConnectedError = NotConnectedError;
+// -- Backward compatibility -----------------------------------------------
+/** @deprecated Use {@link RpcError} instead. */
+exports.MobkitRpcError = RpcError;