@localhostdevs/sdk 0.2.0

package/README.md

@@ -0,0 +1,111 @@
+# @localhostdevs/sdk
+
+The JavaScript SDK for building bots on **[localhostdevs](https://localhostdevs.com)** — run your app on your own laptop and publish it as a command-driven bot that anyone can use through a chat-style interface.
+
+## Install
+
+```bash
+npm install @localhostdevs/sdk
+```
+
+## Quickstart
+
+After creating a bot in the [dashboard](https://localhostdevs.com/dashboard/bots) and copying your API key, write this to `app.js`:
+
+```js
+import { Bot } from '@localhostdevs/sdk';
+
+const bot = new Bot({
+  id: 'price-bot', // your bot's handle (matches the @handle on the marketplace)
+  natsUrl: 'nats://broker.localhostdevs.com:4222',
+  // natsToken: process.env.LHD_NATS_TOKEN, // optional; auto-read from env if unset
+});
+
+bot.cmd('ping', async (ctx) => {
+  await ctx.reply({ text: 'pong' });
+});
+
+bot.cmd('echo', async (ctx) => {
+  await ctx.reply({ text: `echo: ${JSON.stringify(ctx.args)}` });
+});
+
+await bot.connect();
+console.log('bot online — waiting for commands');
+```
+
+Then:
+
+```bash
+LHD_NATS_TOKEN=<broker token from the dashboard> node app.js
+```
+
+The bot stays online for as long as the process runs. Heartbeats fire every 5 seconds so the marketplace shows it as online.
+
+## API
+
+### `new Bot(opts)`
+
+| Option               | Type                | Default                      | Notes                                                                                    |
+| -------------------- | ------------------- | ---------------------------- | ---------------------------------------------------------------------------------------- |
+| `id`                 | `string` (required) | —                            | Your bot's handle. Lowercase letters / digits / dashes.                                  |
+| `natsUrl`            | `string`            | `nats://localhost:4222`      | The NATS broker URL.                                                                     |
+| `natsToken`          | `string`            | `process.env.LHD_NATS_TOKEN` | Token presented at NATS connect. Required by the production broker; unset for local dev. |
+| `heartbeatMs`        | `number`            | `5000`                       | Heartbeat interval in milliseconds.                                                      |
+| `idempotencyLruSize` | `number`            | `1024`                       | How many recent message IDs to remember for deduplication.                               |
+
+### `bot.cmd(name, handler)`
+
+Register a handler for a command. Must be called before `connect()`. Handler receives a `CommandContext`:
+
+```ts
+bot.cmd('greet', async (ctx) => {
+  // ctx.args:  parsed args from the consumer
+  // ctx.command: 'greet'
+  // ctx.msgId: unique id for this invocation
+
+  await ctx.reply({ text: `Hello, ${ctx.args.name ?? 'world'}!` });
+
+  // ctx.reply also supports:
+  //   data: any                — structured payload alongside text
+  //   dispatch: { to, command, args }  — chain to another bot (max depth 5)
+});
+```
+
+### `await bot.connect()`
+
+Open the NATS connection, subscribe to your command subject, and start emitting heartbeats. Resolves after the subscription is registered with the broker — safe to publish from outside immediately after.
+
+### `await bot.disconnect()`
+
+Stop heartbeats, drain the subscription, close the connection.
+
+### `bot.subjectFor(commandName)`
+
+Helper that returns the NATS subject this command would land on. Useful in tests and scripts.
+
+## Idempotency
+
+Every command from the platform carries a `msgId`. The SDK deduplicates redelivered messages via a fixed-size LRU keyed by `msgId`. If a consumer accidentally re-sends the same command, your handler runs once.
+
+## Heartbeats
+
+The SDK publishes a heartbeat every `heartbeatMs` (default 5s) so the marketplace can show your bot as **online**. If heartbeats stop arriving for >15s the bot appears **stale**; >30s it goes **offline**.
+
+## Bot-to-bot composition
+
+A reply can carry a `dispatch` directive to chain a command to another bot:
+
+```js
+bot.cmd('summary', async (ctx) => {
+  await ctx.reply({
+    text: 'fetching price first…',
+    dispatch: { to: 'price-bot', command: 'price', args: { ticker: 'AAPL' } },
+  });
+});
+```
+
+Chains run up to depth 5 with loop detection. The original consumer pays for every step.
+
+## License
+
+MIT

package/dist/bot.d.ts

@@ -0,0 +1,26 @@
+import { nanoid } from 'nanoid';
+import type { BotOptions, CommandHandler } from './types.js';
+export declare class Bot {
+    private readonly opts;
+    private nc;
+    private subscription;
+    private heartbeatTimer;
+    private readonly handlers;
+    private readonly seen;
+    private readonly seenQueue;
+    constructor(opts: BotOptions);
+    /** Register a handler for a command. Must be called before connect(). */
+    cmd(name: string, handler: CommandHandler): this;
+    /** Helper for tests + scripts: the subject a command should be published to. */
+    subjectFor(command: string): string;
+    /** Open NATS connection, subscribe to command subjects, start heartbeat. */
+    connect(): Promise<void>;
+    /** Tear down: stop heartbeat, drain subscription, close NATS. */
+    disconnect(): Promise<void>;
+    private publishHeartbeat;
+    private consume;
+    private isDuplicate;
+    private recordSeen;
+}
+export { nanoid };
+//# sourceMappingURL=bot.d.ts.map

package/dist/bot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC,OAAO,KAAK,EAAE,UAAU,EAAmB,cAAc,EAAqB,MAAM,YAAY,CAAC;AASjG,qBAAa,GAAG;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,EAAE,CAA+B;IACzC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;gBAE9B,IAAI,EAAE,UAAU;IAa5B,yEAAyE;IACzE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAWhD,gFAAgF;IAChF,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAInC,4EAA4E;IACtE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB9B,iEAAiE;IAC3D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAejC,OAAO,CAAC,gBAAgB;YAMV,OAAO;IA+BrB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,UAAU;CAQnB;AAGD,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/bot.js

@@ -0,0 +1,129 @@
+import { connect, JSONCodec } from 'nats';
+import { nanoid } from 'nanoid';
+import { createCommandContext } from './context.js';
+import { subjects } from './subjects.js';
+const codec = JSONCodec();
+const DEFAULT_NATS_URL = 'nats://localhost:4222';
+const DEFAULT_HEARTBEAT_MS = 5000;
+const DEFAULT_IDEMPOTENCY_LRU_SIZE = 1024;
+export class Bot {
+    opts;
+    nc = null;
+    subscription = null;
+    heartbeatTimer = null;
+    handlers = new Map();
+    seen = new Set();
+    seenQueue = []; // FIFO for LRU eviction
+    constructor(opts) {
+        if (!opts.id || !/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(opts.id)) {
+            throw new Error(`Bot id must be lowercase alphanumeric + dashes (got ${opts.id})`);
+        }
+        this.opts = {
+            id: opts.id,
+            natsUrl: opts.natsUrl ?? DEFAULT_NATS_URL,
+            natsToken: opts.natsToken ?? process.env.LHD_NATS_TOKEN ?? null,
+            heartbeatMs: opts.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
+            idempotencyLruSize: opts.idempotencyLruSize ?? DEFAULT_IDEMPOTENCY_LRU_SIZE,
+        };
+    }
+    /** Register a handler for a command. Must be called before connect(). */
+    cmd(name, handler) {
+        if (this.nc) {
+            throw new Error('cmd() must be called before connect()');
+        }
+        if (this.handlers.has(name)) {
+            throw new Error(`duplicate handler for command ${name}`);
+        }
+        this.handlers.set(name, handler);
+        return this;
+    }
+    /** Helper for tests + scripts: the subject a command should be published to. */
+    subjectFor(command) {
+        return subjects.cmd(this.opts.id, command);
+    }
+    /** Open NATS connection, subscribe to command subjects, start heartbeat. */
+    async connect() {
+        if (this.nc) {
+            throw new Error('already connected');
+        }
+        const connectOpts = { servers: this.opts.natsUrl };
+        if (this.opts.natsToken) {
+            connectOpts.token = this.opts.natsToken;
+        }
+        this.nc = await connect(connectOpts);
+        this.subscription = this.nc.subscribe(subjects.cmdAll(this.opts.id));
+        // Force the SUB protocol command to be ack'd by the server before connect()
+        // resolves. Without this, callers (and tests) that publish immediately after
+        // connect() can lose the first message — NATS core drops messages with no
+        // matching subscribers.
+        await this.nc.flush();
+        void this.consume();
+        this.heartbeatTimer = setInterval(() => this.publishHeartbeat(), this.opts.heartbeatMs);
+        this.publishHeartbeat(); // emit immediately on connect
+    }
+    /** Tear down: stop heartbeat, drain subscription, close NATS. */
+    async disconnect() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.subscription) {
+            this.subscription.unsubscribe();
+            this.subscription = null;
+        }
+        if (this.nc) {
+            await this.nc.drain();
+            this.nc = null;
+        }
+    }
+    publishHeartbeat() {
+        if (!this.nc)
+            return;
+        const beat = { botId: this.opts.id, ts: Date.now() };
+        this.nc.publish(subjects.heartbeat(this.opts.id), codec.encode(beat));
+    }
+    async consume() {
+        if (!this.subscription || !this.nc)
+            return;
+        for await (const msg of this.subscription) {
+            try {
+                const envelope = codec.decode(msg.data);
+                if (!envelope ||
+                    typeof envelope.command !== 'string' ||
+                    typeof envelope.msgId !== 'string') {
+                    continue; // malformed; drop silently
+                }
+                if (this.isDuplicate(envelope.msgId)) {
+                    continue;
+                }
+                this.recordSeen(envelope.msgId);
+                const handler = this.handlers.get(envelope.command);
+                if (!handler) {
+                    // Unknown command — could publish an error reply; v1 keeps it simple and drops.
+                    continue;
+                }
+                const ctx = createCommandContext(this.nc, envelope);
+                await handler(ctx);
+            }
+            catch (err) {
+                // Don't let one bad message kill the loop. Log to stderr for now.
+                console.error('[localhostdevs sdk] command dispatch error:', err);
+            }
+        }
+    }
+    isDuplicate(msgId) {
+        return this.seen.has(msgId);
+    }
+    recordSeen(msgId) {
+        this.seen.add(msgId);
+        this.seenQueue.push(msgId);
+        while (this.seenQueue.length > this.opts.idempotencyLruSize) {
+            const evicted = this.seenQueue.shift();
+            if (evicted)
+                this.seen.delete(evicted);
+        }
+    }
+}
+// Re-export nanoid so demo scripts can use the same id generator the SDK expects.
+export { nanoid };
+//# sourceMappingURL=bot.js.map

package/dist/bot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.js","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,11 @@
+import type { NatsConnection } from 'nats';
+import type { CommandContext } from './types.js';
+import { subjects } from './subjects.js';
+export declare function createCommandContext(nc: NatsConnection, envelope: {
+    command: string;
+    args: Record<string, unknown>;
+    msgId: string;
+    replyTo: string;
+}): CommandContext;
+export { subjects };
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAA4B,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAIzC,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC3F,cAAc,CAiBhB;AAGD,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/context.js

@@ -0,0 +1,23 @@
+import { JSONCodec } from 'nats';
+import { subjects } from './subjects.js';
+const codec = JSONCodec();
+export function createCommandContext(nc, envelope) {
+    let replied = false;
+    return {
+        command: envelope.command,
+        args: envelope.args,
+        msgId: envelope.msgId,
+        async reply(body) {
+            if (replied) {
+                throw new Error(`reply() called more than once for msgId=${envelope.msgId}`);
+            }
+            replied = true;
+            const payload = { msgId: envelope.msgId, body };
+            nc.publish(envelope.replyTo, codec.encode(payload));
+            // No need to await — NATS publish is fire-and-forget.
+        },
+    };
+}
+// Re-export for tests.
+export { subjects };
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AAEjC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;AAE1B,MAAM,UAAU,oBAAoB,CAClC,EAAkB,EAClB,QAA4F;IAE5F,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACL,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,KAAK,CAAC,KAAK,CAAC,IAAe;YACzB,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,2CAA2C,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;YAC/E,CAAC;YACD,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,OAAO,GAAkB,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;YAC/D,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;YACpD,sDAAsD;QACxD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,uBAAuB;AACvB,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export declare const SDK_PACKAGE_VERSION = "0.2.0";
+export { Bot } from './bot.js';
+export { subjects } from './subjects.js';
+export type { BotOptions, CommandContext, CommandHandler, CommandEnvelope, ReplyBody, ReplyEnvelope, HeartbeatEnvelope, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,eAAe,EACf,SAAS,EACT,aAAa,EACb,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export const SDK_PACKAGE_VERSION = '0.2.0';
+export { Bot } from './bot.js';
+export { subjects } from './subjects.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAC3C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC"}

package/dist/subjects.d.ts

@@ -0,0 +1,17 @@
+/**
+ * NATS subject helpers.
+ *
+ *   bot.<id>.cmd.<command>       — command published by gateway/CLI, consumed by bot
+ *   bot.<id>.heartbeat           — 5-second presence pings from the bot
+ *   reply.<msgId>                — per-message reply subject; publisher subscribes to this
+ *
+ * The reply subject deliberately doesn't include the bot id; replies are correlated
+ * via msgId, and the publisher only listens to its own short-lived reply subject.
+ */
+export declare const subjects: {
+    cmd: (botId: string, command: string) => string;
+    cmdAll: (botId: string) => string;
+    heartbeat: (botId: string) => string;
+    reply: (msgId: string) => string;
+};
+//# sourceMappingURL=subjects.d.ts.map

package/dist/subjects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subjects.d.ts","sourceRoot":"","sources":["../src/subjects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,QAAQ;iBACN,MAAM,WAAW,MAAM,KAAG,MAAM;oBAC7B,MAAM,KAAG,MAAM;uBACZ,MAAM,KAAG,MAAM;mBACnB,MAAM,KAAG,MAAM;CAC/B,CAAC"}

package/dist/subjects.js

@@ -0,0 +1,17 @@
+/**
+ * NATS subject helpers.
+ *
+ *   bot.<id>.cmd.<command>       — command published by gateway/CLI, consumed by bot
+ *   bot.<id>.heartbeat           — 5-second presence pings from the bot
+ *   reply.<msgId>                — per-message reply subject; publisher subscribes to this
+ *
+ * The reply subject deliberately doesn't include the bot id; replies are correlated
+ * via msgId, and the publisher only listens to its own short-lived reply subject.
+ */
+export const subjects = {
+    cmd: (botId, command) => `bot.${botId}.cmd.${command}`,
+    cmdAll: (botId) => `bot.${botId}.cmd.>`,
+    heartbeat: (botId) => `bot.${botId}.heartbeat`,
+    reply: (msgId) => `reply.${msgId}`,
+};
+//# sourceMappingURL=subjects.js.map

package/dist/subjects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subjects.js","sourceRoot":"","sources":["../src/subjects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,GAAG,EAAE,CAAC,KAAa,EAAE,OAAe,EAAU,EAAE,CAAC,OAAO,KAAK,QAAQ,OAAO,EAAE;IAC9E,MAAM,EAAE,CAAC,KAAa,EAAU,EAAE,CAAC,OAAO,KAAK,QAAQ;IACvD,SAAS,EAAE,CAAC,KAAa,EAAU,EAAE,CAAC,OAAO,KAAK,YAAY;IAC9D,KAAK,EAAE,CAAC,KAAa,EAAU,EAAE,CAAC,SAAS,KAAK,EAAE;CACnD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,59 @@
+export type CommandHandler = (ctx: CommandContext) => Promise<void> | void;
+export interface CommandContext {
+    /** Bot-scoped command name (e.g., 'price', 'analyze'). */
+    readonly command: string;
+    /** Decoded argument map from the publisher. */
+    readonly args: Record<string, unknown>;
+    /** Unique id assigned by the publisher; used for idempotency dedup + reply correlation. */
+    readonly msgId: string;
+    /** Sends a reply to the publisher. May be called at most once per command. */
+    reply(body: ReplyBody): Promise<void>;
+}
+export interface ReplyBody {
+    /** Plain text reply. Optional. */
+    text?: string;
+    /** Optional structured payload (free-form for v1; refined in later plans). */
+    data?: unknown;
+    /**
+     * Bot-to-bot composition: when set, the platform invokes another bot
+     * with this command using the same originating consumer as the principal.
+     * Only single-dispatch is supported in v1.
+     */
+    dispatch?: {
+        to: string;
+        command: string;
+        args?: Record<string, unknown>;
+    };
+}
+export interface BotOptions {
+    /** Stable identifier for this bot (e.g., 'price-bot'). Used in NATS subject names. */
+    id: string;
+    /** NATS connection URL. Defaults to `nats://localhost:4222`. */
+    natsUrl?: string;
+    /**
+     * Token presented at NATS connect time when the broker requires auth.
+     * For localhostdevs production, the platform supplies this via the
+     * `LHD_NATS_TOKEN` env var. Falls back to `process.env.LHD_NATS_TOKEN`.
+     */
+    natsToken?: string;
+    /** Heartbeat interval in milliseconds. Defaults to 5000. */
+    heartbeatMs?: number;
+    /** Idempotency LRU size. Defaults to 1024. */
+    idempotencyLruSize?: number;
+}
+export interface CommandEnvelope {
+    msgId: string;
+    command: string;
+    args: Record<string, unknown>;
+    /** NATS subject the bot should reply on. */
+    replyTo: string;
+}
+export interface ReplyEnvelope {
+    msgId: string;
+    body: ReplyBody;
+}
+export interface HeartbeatEnvelope {
+    botId: string;
+    ts: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE3E,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,SAAS;IACxB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE;QACT,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,CAAC;CACH;AAED,MAAM,WAAW,UAAU;IACzB,sFAAsF;IACtF,EAAE,EAAE,MAAM,CAAC;IACX,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@localhostdevs/sdk",
+  "version": "0.2.0",
+  "description": "JavaScript SDK for building bots on localhostdevs — run your app on your laptop, publish it as a command-driven bot.",
+  "keywords": [
+    "localhostdevs",
+    "bot",
+    "nats",
+    "chatops",
+    "cli",
+    "sdk"
+  ],
+  "homepage": "https://github.com/jugod0/localhostdevelopers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jugod0/localhostdevelopers.git",
+    "directory": "packages/sdk"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "demo:client": "tsx scripts/demo-client.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "nanoid": "^5.1.11",
+    "nats": "^2.29.3"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}