@abdarrahmanabdelnasir/relay-node 0.1.6

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Commandless
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,80 @@
+# @commandless/relay-node
+
+Lightweight Node SDK to integrate your Discord bot with the Commandless backend. It forwards events (messages/interactions) and executes returned actions (AI replies or commands). Your bot token never leaves your app.
+
+## Install
+
+```bash
+npm i discord.js @commandless/relay-node
+```
+
+## Quickstart (Discord.js v14)
+
+```ts
+import { Client, GatewayIntentBits } from 'discord.js';
+import { RelayClient, useDiscordAdapter } from '@commandless/relay-node';
+
+const discord = new Client({
+  intents: [
+    GatewayIntentBits.Guilds,
+    GatewayIntentBits.GuildMessages,
+    GatewayIntentBits.MessageContent,
+  ],
+});
+
+const relay = new RelayClient({
+  apiKey: process.env.COMMANDLESS_API_KEY!,
+  baseUrl: process.env.COMMANDLESS_SERVICE_URL,
+  hmacSecret: process.env.COMMANDLESS_HMAC_SECRET, // optional but recommended
+});
+
+useDiscordAdapter({ client: discord, relay });
+
+discord.login(process.env.BOT_TOKEN);
+```
+
+### Templates
+
+- AI-only (conversational replies, no local commands): see `examples/index.ai-only.js` in the main repo.
+- With registry (route command actions to your handlers): see `examples/index.with-registry.js`.
+
+### Environment variables
+
+- `BOT_TOKEN` — Discord bot token
+- `COMMANDLESS_API_KEY` — API key created in the dashboard
+- `COMMANDLESS_SERVICE_URL` — your Commandless service base URL
+- `COMMANDLESS_HMAC_SECRET` — optional HMAC signing secret
+- `BOT_ID` — optional fixed bot id to lock persona to a specific bot row
+
+## API
+
+- `RelayClient(opts)`
+  - `sendEvent(event)` → `Decision | null` (retries + idempotency)
+  - `enqueue(event)` → fire-and-forget queue
+- `useDiscordAdapter({ client, relay, execute? })`
+  - Wires `messageCreate` and `interactionCreate`
+  - Optional `execute(decision, ctx)` to override default reply behavior
+  - `mentionRequired` (default true) to only process when mentioned or replying to the bot
+
+## Security
+
+- Every request includes `x-commandless-key`.
+- Optional `x-signature` HMAC (SHA-256 of raw body) if you set `hmacSecret`.
+- Idempotency with `x-idempotency-key` to dedupe retries.
+
+## Troubleshooting
+
+- No persona loaded: ensure events carry `botId` (set `BOT_ID` or let `registerBot` link) and the bot row has a saved personality; ensure your API key maps to the same `user_id`.
+- 401/405 errors from dashboard: set `COMMANDLESS_SERVICE_URL` correctly; SDK calls should go to the service (Railway), not the dashboard host.
+- Empty AI responses: verify OpenRouter/OpenAI envs on the backend and timeouts; the SDK will log decisions and retries.
+
+## Requirements
+
+- Node 18+
+- Discord.js 14+
+
+## Notes
+
+MVP; surface may evolve pre‑1.0. Please file issues and suggestions.
+
+

package/dist/adapters/discord.d.ts

@@ -0,0 +1,21 @@
+import type { Client, Message, Interaction } from "discord.js";
+import { RelayClient } from "../relayClient.js";
+import type { Decision } from "../types.js";
+export interface DiscordAdapterOptions {
+    client: Client;
+    relay: RelayClient;
+    execute?: (dec: Decision, ctx: {
+        message?: Message;
+        interaction?: Interaction;
+    }) => Promise<void>;
+    onCommand?: (spec: {
+        slash?: string;
+        name?: string;
+        args?: Record<string, unknown>;
+    }, ctx: {
+        message?: Message;
+        interaction?: Interaction;
+    }) => Promise<void>;
+    mentionRequired?: boolean;
+}
+export declare function useDiscordAdapter(opts: DiscordAdapterOptions): void;

package/dist/adapters/discord.js

@@ -0,0 +1,289 @@
+export function useDiscordAdapter(opts) {
+    const { client, relay } = opts;
+    client.on("messageCreate", async (message) => {
+        if (message.author.bot)
+            return;
+        const mentionRequired = opts.mentionRequired !== false;
+        const mentioned = !!client.user?.id && (message.mentions?.users?.has?.(client.user.id) ?? false);
+        // Typing indicator will be driven by a short loop only when addressed
+        // Detect reply-to-bot accurately
+        let isReplyToBot = false;
+        try {
+            if (message.reference?.messageId && client.user?.id) {
+                const ref = await message.channel.messages.fetch(message.reference.messageId).catch(() => null);
+                if (ref && ref.author && ref.author.id === client.user.id)
+                    isReplyToBot = true;
+            }
+        }
+        catch { }
+        if (mentionRequired && !mentioned && !isReplyToBot)
+            return;
+        const evt = {
+            type: "messageCreate",
+            id: message.id,
+            guildId: message.guildId ?? undefined,
+            channelId: message.channelId,
+            authorId: message.author.id,
+            content: message.content,
+            timestamp: message.createdTimestamp,
+            botClientId: client.user?.id,
+            isReplyToBot,
+            referencedMessageId: message.reference?.messageId,
+            referencedMessageAuthorId: message.reference ? client.user?.id : undefined,
+        };
+        try {
+            let typingTimer = null;
+            try {
+                await message.channel?.sendTyping?.();
+            }
+            catch { }
+            typingTimer = setInterval(() => {
+                try {
+                    message.channel?.sendTyping?.();
+                }
+                catch { }
+            }, 8000);
+            const dec = await relay.sendEvent(evt);
+            if (dec)
+                await (opts.execute ? opts.execute(dec, { message }) : defaultExecute(dec, { message }, opts));
+            if (typingTimer)
+                clearInterval(typingTimer);
+        }
+        catch (err) {
+            // swallow; user code can add logging
+            // ensure typing cleared
+            // no-op: interval cleared by GC if not set
+        }
+    });
+    client.on("interactionCreate", async (interaction) => {
+        if (!interaction.isCommand())
+            return;
+        const cmd = interaction;
+        const evt = {
+            type: "interactionCreate",
+            id: interaction.id,
+            guildId: interaction.guildId ?? undefined,
+            channelId: interaction.channelId ?? undefined,
+            userId: interaction.user.id,
+            name: cmd.commandName,
+            options: (() => {
+                const out = {};
+                try {
+                    // Guard for discord.js v14 CommandInteractionOptionResolver
+                    const data = cmd.options?.data || [];
+                    for (const d of data)
+                        out[d.name] = d.value;
+                }
+                catch { }
+                return out;
+            })(),
+            timestamp: Date.now(),
+        };
+        try {
+            const dec = await relay.sendEvent(evt);
+            if (dec)
+                await (opts.execute ? opts.execute(dec, { interaction }) : defaultExecute(dec, { interaction }, opts));
+        }
+        catch (err) {
+            // swallow
+        }
+    });
+}
+function getByPath(root, path) {
+    if (!root || !path)
+        return undefined;
+    try {
+        return path.split('.').reduce((o, k) => (o ? o[k] : undefined), root);
+    }
+    catch {
+        return undefined;
+    }
+}
+function pickHandler(registry, action) {
+    if (!registry || !action)
+        return null;
+    try {
+        if (typeof registry.get === 'function') {
+            return registry.get(action) || registry.get(action.toLowerCase());
+        }
+        return registry[action] || registry[action.toLowerCase?.()];
+    }
+    catch {
+        return null;
+    }
+}
+async function runHandler(handler, message, args, rest) {
+    if (!handler)
+        return false;
+    try {
+        if (typeof handler.execute === 'function') {
+            await handler.execute(message, args, rest);
+            return true;
+        }
+        if (typeof handler.run === 'function') {
+            await handler.run(message, args, rest);
+            return true;
+        }
+        if (typeof handler.messageRun === 'function') {
+            await handler.messageRun(message, { args, rest });
+            return true;
+        }
+        if (typeof handler.exec === 'function') {
+            await handler.exec(message, rest.join(' '));
+            return true;
+        }
+        if (typeof handler === 'function') {
+            await handler({ message, args, rest });
+            return true;
+        }
+    }
+    catch {
+        // swallow; user code can add logging
+        return true; // handler existed and threw; consider handled to avoid double-processing
+    }
+    return false;
+}
+async function defaultExecute(decision, ctx, opts) {
+    const reply = decision.actions?.find(a => a.kind === "reply");
+    const command = decision.actions?.find(a => a.kind === "command");
+    if (reply) {
+        if (ctx.message) {
+            await ctx.message.reply({ content: reply.content });
+        }
+        else if (ctx.interaction && ctx.interaction.isRepliable())
+            await ctx.interaction.reply({ content: reply.content, ephemeral: reply.ephemeral ?? false });
+    }
+    if (command && ctx.message) {
+        const slash = String(command.slash || '').trim();
+        const disableBuiltins = String(process.env.COMMANDLESS_DISABLE_BUILTINS || '').toLowerCase() === 'true';
+        const registryPath = process.env.COMMAND_REGISTRY_PATH || '';
+        // If user provided explicit handler via onCommand, prefer it
+        if (opts?.onCommand) {
+            await opts.onCommand({ slash, name: command.name, args: command.args || {} }, ctx).catch(() => { });
+            return;
+        }
+        // Env-based auto-routing to existing registry
+        if (registryPath) {
+            const aliasesRaw = process.env.COMMAND_REGISTRY_ALIAS_JSON || '';
+            let alias = {};
+            try {
+                if (aliasesRaw)
+                    alias = JSON.parse(aliasesRaw);
+            }
+            catch { }
+            const fromSlash = slash ? parseSlash(slash).action : null;
+            const base = String(command.name || fromSlash || '').toLowerCase();
+            const action = (alias[base] || base);
+            const registry = getByPath(opts?.client, registryPath);
+            const handler = pickHandler(registry, action);
+            const ok = await runHandler(handler, ctx.message, (command.args || {}), []);
+            if (ok || disableBuiltins)
+                return; // handled or built-ins disabled
+            // fallthrough to built-ins only if not disabled
+        }
+        // Default built-ins (only if not disabled)
+        if (!disableBuiltins) {
+            if (slash)
+                await executeLocalDiscordCommand(slash, ctx.message).catch(() => { });
+            else
+                await executeLocalAction(String(command.name || ''), command.args || {}, ctx.message).catch(() => { });
+        }
+    }
+}
+async function executeLocalDiscordCommand(slashText, message) {
+    const { action, params } = parseSlash(slashText);
+    if (!action)
+        return;
+    try {
+        switch (action) {
+            case 'say': {
+                const content = String(params.message || params.text || params.content || '').trim();
+                const ch = message.channel;
+                if (content && ch && typeof ch.send === 'function')
+                    await ch.send({ content });
+                break;
+            }
+            case 'pin': {
+                let target = null;
+                if (message.reference?.messageId) {
+                    try {
+                        target = await message.channel.messages.fetch(message.reference.messageId);
+                    }
+                    catch { }
+                }
+                if (!target) {
+                    const fetched = await message.channel.messages.fetch({ limit: 2 });
+                    target = fetched.filter(m => m.id !== message.id).first() || fetched.first();
+                }
+                if (target && typeof target.pin === 'function')
+                    await target.pin();
+                break;
+            }
+            case 'purge': {
+                const amt = Number(params.amount || params.n || params.count || '0');
+                if (amt > 0 && 'bulkDelete' in message.channel) {
+                    await message.channel.bulkDelete(Math.min(amt, 100), true);
+                    break;
+                }
+                // No amount -> delete referenced/last message
+                let target = null;
+                if (message.reference?.messageId) {
+                    try {
+                        target = await message.channel.messages.fetch(message.reference.messageId);
+                    }
+                    catch { }
+                }
+                if (!target) {
+                    const fetched = await message.channel.messages.fetch({ limit: 2 });
+                    target = fetched.filter((m) => m.id !== message.id).first() || fetched.first();
+                }
+                if (target && typeof target.delete === 'function')
+                    await target.delete().catch(() => { });
+                break;
+            }
+            default:
+                // Let bots handle domain-specific actions via custom routing
+                break;
+        }
+    }
+    catch { }
+}
+async function executeLocalAction(action, params, message) {
+    try {
+        switch (action) {
+            case 'say': {
+                const t = String(params.message || '').trim();
+                const ch = message.channel;
+                if (t && ch?.send)
+                    await ch.send({ content: t });
+                break;
+            }
+            // Add common cross-bot actions here if desired
+            default:
+                break;
+        }
+    }
+    catch { }
+}
+function parseSlash(text) {
+    const out = {};
+    const t = String(text || '').trim().replace(/^\//, '');
+    if (!t)
+        return { action: null, params: out };
+    const [head, ...rest] = t.split(/\s+/);
+    let action = head.toLowerCase();
+    // parse k=v pairs
+    for (const part of rest) {
+        const m = part.match(/^([^=]+)=(.*)$/);
+        if (m)
+            out[m[1]] = m[2];
+    }
+    // also support freeform for simple commands e.g., "purge 5" or "say hello" (map to message)
+    if (!Object.keys(out).length && rest.length) {
+        if (action === 'purge' && /^\d+$/.test(rest[0]))
+            out.amount = rest[0];
+        else
+            out.message = rest.join(' ');
+    }
+    return { action, params: out };
+}

package/dist/http.d.ts

@@ -0,0 +1,6 @@
+import { HttpResponse } from "./types.js";
+export declare function postJson<T>(url: string, apiKey: string, body: unknown, opts?: {
+    hmacSecret?: string;
+    timeoutMs?: number;
+    idempotencyKey?: string;
+}): Promise<HttpResponse<T>>;

package/dist/http.js

@@ -0,0 +1,41 @@
+import { hmacSign, nowUnixMs } from "./signing.js";
+export async function postJson(url, apiKey, body, opts) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 15000);
+    const json = JSON.stringify(body);
+    const headers = {
+        "content-type": "application/json",
+        // Use canonical header expected by the server; keep legacy for compatibility
+        "x-api-key": apiKey,
+        "x-commandless-key": apiKey,
+        "x-timestamp": String(nowUnixMs())
+    };
+    if (opts?.hmacSecret)
+        headers["x-signature"] = hmacSign(json, opts.hmacSecret);
+    if (opts?.idempotencyKey)
+        headers["x-idempotency-key"] = opts.idempotencyKey;
+    try {
+        const res = await fetch(url, { method: "POST", body: json, headers, signal: controller.signal });
+        const requestId = res.headers.get("x-request-id") ?? undefined;
+        if (!res.ok) {
+            const text = await safeText(res);
+            return { ok: false, status: res.status, error: text, requestId };
+        }
+        const data = (await res.json());
+        return { ok: true, status: res.status, data, requestId };
+    }
+    catch (err) {
+        return { ok: false, status: 0, error: err?.message ?? String(err) };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./signing.js";
+export * from "./http.js";
+export * from "./relayClient.js";
+export * from "./adapters/discord.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./signing.js";
+export * from "./http.js";
+export * from "./relayClient.js";
+export * from "./adapters/discord.js";

package/dist/relayClient.d.ts

@@ -0,0 +1,22 @@
+import { Decision, RelayClientOptions, RelayEvent } from "./types.js";
+export declare class RelayClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly hmacSecret?;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly queue;
+    private sending;
+    private botId?;
+    constructor(opts: RelayClientOptions);
+    registerBot(info: {
+        platform: 'discord';
+        name?: string;
+        clientId?: string;
+    }): Promise<string | null>;
+    heartbeat(): Promise<void>;
+    sendEvent(event: RelayEvent): Promise<Decision | null>;
+    enqueue(event: RelayEvent): void;
+    private drain;
+    private sendWithRetry;
+}

package/dist/relayClient.js

@@ -0,0 +1,90 @@
+import { postJson } from "./http.js";
+const DEFAULT_BASE = "https://api.commandless.app";
+export class RelayClient {
+    constructor(opts) {
+        this.maxRetries = 3;
+        this.queue = [];
+        this.sending = false;
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
+        this.hmacSecret = opts.hmacSecret;
+        this.timeoutMs = opts.timeoutMs ?? 15000;
+    }
+    // Optional: register this SDK bot and obtain/confirm botId
+    async registerBot(info) {
+        try {
+            const url = `${this.baseUrl}/v1/relay/register`;
+            const res = await postJson(url, this.apiKey, info, {
+                hmacSecret: this.hmacSecret,
+                timeoutMs: this.timeoutMs,
+            });
+            if (res.ok && res.data?.botId) {
+                this.botId = res.data.botId;
+                return this.botId;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // Optional heartbeat to show online status
+    async heartbeat() {
+        try {
+            const url = `${this.baseUrl}/v1/relay/heartbeat`;
+            const res = await postJson(url, this.apiKey, { botId: this.botId }, {
+                hmacSecret: this.hmacSecret,
+                timeoutMs: this.timeoutMs,
+            });
+            // Return server response to caller (index.js checks syncRequested)
+            return res.data;
+        }
+        catch { }
+    }
+    async sendEvent(event) {
+        // Immediate send with retries and idempotency
+        if (this.botId)
+            event.botId = this.botId;
+        return await this.sendWithRetry(event);
+    }
+    enqueue(event) {
+        this.queue.push(event);
+        if (!this.sending)
+            void this.drain();
+    }
+    async drain() {
+        this.sending = true;
+        while (this.queue.length) {
+            const evt = this.queue.shift();
+            try {
+                await this.sendWithRetry(evt);
+            }
+            catch { /* swallow to keep draining */ }
+        }
+        this.sending = false;
+    }
+    async sendWithRetry(event) {
+        const url = `${this.baseUrl}/v1/relay/events`;
+        const idem = makeIdempotencyKey(event);
+        let lastErr;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const res = await postJson(url, this.apiKey, event, {
+                hmacSecret: this.hmacSecret,
+                timeoutMs: this.timeoutMs,
+                idempotencyKey: idem,
+            });
+            if (res.ok)
+                return res.data?.decision ?? null;
+            lastErr = new Error(`Commandless error (${res.status}): ${res.error ?? "unknown"}`);
+            // basic backoff
+            await sleep(200 * (attempt + 1));
+        }
+        throw lastErr;
+    }
+}
+function makeIdempotencyKey(event) {
+    // Simple stable key: type-id-timestamp buckets (can be improved)
+    const base = `${event.type}:${event.id}:${Math.floor(event.timestamp / 1000)}`;
+    return Buffer.from(base).toString("base64url");
+}
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }

package/dist/signing.d.ts

@@ -0,0 +1,2 @@
+export declare function hmacSign(body: string, secret: string): string;
+export declare function nowUnixMs(): number;

package/dist/signing.js

@@ -0,0 +1,7 @@
+import crypto from "crypto";
+export function hmacSign(body, secret) {
+    return crypto.createHmac("sha256", secret).update(body).digest("hex");
+}
+export function nowUnixMs() {
+    return Date.now();
+}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+export type Snowflake = string;
+export type RelayEvent = {
+    type: "messageCreate";
+    id: string;
+    guildId?: Snowflake;
+    channelId: Snowflake;
+    authorId: Snowflake;
+    content: string;
+    timestamp: number;
+    botClientId?: Snowflake;
+    isReplyToBot?: boolean;
+    referencedMessageId?: string;
+    referencedMessageAuthorId?: Snowflake;
+    referencedMessageContent?: string;
+} | {
+    type: "interactionCreate";
+    id: string;
+    guildId?: Snowflake;
+    channelId?: Snowflake;
+    userId: Snowflake;
+    name: string;
+    options?: Record<string, unknown>;
+    timestamp: number;
+    botClientId?: Snowflake;
+};
+export interface Decision {
+    id: string;
+    intent: string;
+    confidence: number;
+    params: Record<string, unknown>;
+    safety?: {
+        blocked?: boolean;
+        reasons?: string[];
+    };
+    next_step?: string;
+    actions?: Array<{
+        kind: "reply";
+        content: string;
+        ephemeral?: boolean;
+    } | {
+        kind: "command";
+        name?: string;
+        args?: Record<string, unknown>;
+        slash?: string;
+        simulate?: boolean;
+    }>;
+}
+export interface RelayClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    hmacSecret?: string;
+    timeoutMs?: number;
+}
+export interface HttpResponse<T> {
+    ok: boolean;
+    status: number;
+    data?: T;
+    error?: string;
+    requestId?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist-cjs/adapters/discord.d.ts

@@ -0,0 +1,21 @@
+import type { Client, Message, Interaction } from "discord.js";
+import { RelayClient } from "../relayClient.js";
+import type { Decision } from "../types.js";
+export interface DiscordAdapterOptions {
+    client: Client;
+    relay: RelayClient;
+    execute?: (dec: Decision, ctx: {
+        message?: Message;
+        interaction?: Interaction;
+    }) => Promise<void>;
+    onCommand?: (spec: {
+        slash?: string;
+        name?: string;
+        args?: Record<string, unknown>;
+    }, ctx: {
+        message?: Message;
+        interaction?: Interaction;
+    }) => Promise<void>;
+    mentionRequired?: boolean;
+}
+export declare function useDiscordAdapter(opts: DiscordAdapterOptions): void;

package/dist-cjs/adapters/discord.js

@@ -0,0 +1,292 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDiscordAdapter = useDiscordAdapter;
+function useDiscordAdapter(opts) {
+    const { client, relay } = opts;
+    client.on("messageCreate", async (message) => {
+        if (message.author.bot)
+            return;
+        const mentionRequired = opts.mentionRequired !== false;
+        const mentioned = !!client.user?.id && (message.mentions?.users?.has?.(client.user.id) ?? false);
+        // Typing indicator will be driven by a short loop only when addressed
+        // Detect reply-to-bot accurately
+        let isReplyToBot = false;
+        try {
+            if (message.reference?.messageId && client.user?.id) {
+                const ref = await message.channel.messages.fetch(message.reference.messageId).catch(() => null);
+                if (ref && ref.author && ref.author.id === client.user.id)
+                    isReplyToBot = true;
+            }
+        }
+        catch { }
+        if (mentionRequired && !mentioned && !isReplyToBot)
+            return;
+        const evt = {
+            type: "messageCreate",
+            id: message.id,
+            guildId: message.guildId ?? undefined,
+            channelId: message.channelId,
+            authorId: message.author.id,
+            content: message.content,
+            timestamp: message.createdTimestamp,
+            botClientId: client.user?.id,
+            isReplyToBot,
+            referencedMessageId: message.reference?.messageId,
+            referencedMessageAuthorId: message.reference ? client.user?.id : undefined,
+        };
+        try {
+            let typingTimer = null;
+            try {
+                await message.channel?.sendTyping?.();
+            }
+            catch { }
+            typingTimer = setInterval(() => {
+                try {
+                    message.channel?.sendTyping?.();
+                }
+                catch { }
+            }, 8000);
+            const dec = await relay.sendEvent(evt);
+            if (dec)
+                await (opts.execute ? opts.execute(dec, { message }) : defaultExecute(dec, { message }, opts));
+            if (typingTimer)
+                clearInterval(typingTimer);
+        }
+        catch (err) {
+            // swallow; user code can add logging
+            // ensure typing cleared
+            // no-op: interval cleared by GC if not set
+        }
+    });
+    client.on("interactionCreate", async (interaction) => {
+        if (!interaction.isCommand())
+            return;
+        const cmd = interaction;
+        const evt = {
+            type: "interactionCreate",
+            id: interaction.id,
+            guildId: interaction.guildId ?? undefined,
+            channelId: interaction.channelId ?? undefined,
+            userId: interaction.user.id,
+            name: cmd.commandName,
+            options: (() => {
+                const out = {};
+                try {
+                    // Guard for discord.js v14 CommandInteractionOptionResolver
+                    const data = cmd.options?.data || [];
+                    for (const d of data)
+                        out[d.name] = d.value;
+                }
+                catch { }
+                return out;
+            })(),
+            timestamp: Date.now(),
+        };
+        try {
+            const dec = await relay.sendEvent(evt);
+            if (dec)
+                await (opts.execute ? opts.execute(dec, { interaction }) : defaultExecute(dec, { interaction }, opts));
+        }
+        catch (err) {
+            // swallow
+        }
+    });
+}
+function getByPath(root, path) {
+    if (!root || !path)
+        return undefined;
+    try {
+        return path.split('.').reduce((o, k) => (o ? o[k] : undefined), root);
+    }
+    catch {
+        return undefined;
+    }
+}
+function pickHandler(registry, action) {
+    if (!registry || !action)
+        return null;
+    try {
+        if (typeof registry.get === 'function') {
+            return registry.get(action) || registry.get(action.toLowerCase());
+        }
+        return registry[action] || registry[action.toLowerCase?.()];
+    }
+    catch {
+        return null;
+    }
+}
+async function runHandler(handler, message, args, rest) {
+    if (!handler)
+        return false;
+    try {
+        if (typeof handler.execute === 'function') {
+            await handler.execute(message, args, rest);
+            return true;
+        }
+        if (typeof handler.run === 'function') {
+            await handler.run(message, args, rest);
+            return true;
+        }
+        if (typeof handler.messageRun === 'function') {
+            await handler.messageRun(message, { args, rest });
+            return true;
+        }
+        if (typeof handler.exec === 'function') {
+            await handler.exec(message, rest.join(' '));
+            return true;
+        }
+        if (typeof handler === 'function') {
+            await handler({ message, args, rest });
+            return true;
+        }
+    }
+    catch {
+        // swallow; user code can add logging
+        return true; // handler existed and threw; consider handled to avoid double-processing
+    }
+    return false;
+}
+async function defaultExecute(decision, ctx, opts) {
+    const reply = decision.actions?.find(a => a.kind === "reply");
+    const command = decision.actions?.find(a => a.kind === "command");
+    if (reply) {
+        if (ctx.message) {
+            await ctx.message.reply({ content: reply.content });
+        }
+        else if (ctx.interaction && ctx.interaction.isRepliable())
+            await ctx.interaction.reply({ content: reply.content, ephemeral: reply.ephemeral ?? false });
+    }
+    if (command && ctx.message) {
+        const slash = String(command.slash || '').trim();
+        const disableBuiltins = String(process.env.COMMANDLESS_DISABLE_BUILTINS || '').toLowerCase() === 'true';
+        const registryPath = process.env.COMMAND_REGISTRY_PATH || '';
+        // If user provided explicit handler via onCommand, prefer it
+        if (opts?.onCommand) {
+            await opts.onCommand({ slash, name: command.name, args: command.args || {} }, ctx).catch(() => { });
+            return;
+        }
+        // Env-based auto-routing to existing registry
+        if (registryPath) {
+            const aliasesRaw = process.env.COMMAND_REGISTRY_ALIAS_JSON || '';
+            let alias = {};
+            try {
+                if (aliasesRaw)
+                    alias = JSON.parse(aliasesRaw);
+            }
+            catch { }
+            const fromSlash = slash ? parseSlash(slash).action : null;
+            const base = String(command.name || fromSlash || '').toLowerCase();
+            const action = (alias[base] || base);
+            const registry = getByPath(opts?.client, registryPath);
+            const handler = pickHandler(registry, action);
+            const ok = await runHandler(handler, ctx.message, (command.args || {}), []);
+            if (ok || disableBuiltins)
+                return; // handled or built-ins disabled
+            // fallthrough to built-ins only if not disabled
+        }
+        // Default built-ins (only if not disabled)
+        if (!disableBuiltins) {
+            if (slash)
+                await executeLocalDiscordCommand(slash, ctx.message).catch(() => { });
+            else
+                await executeLocalAction(String(command.name || ''), command.args || {}, ctx.message).catch(() => { });
+        }
+    }
+}
+async function executeLocalDiscordCommand(slashText, message) {
+    const { action, params } = parseSlash(slashText);
+    if (!action)
+        return;
+    try {
+        switch (action) {
+            case 'say': {
+                const content = String(params.message || params.text || params.content || '').trim();
+                const ch = message.channel;
+                if (content && ch && typeof ch.send === 'function')
+                    await ch.send({ content });
+                break;
+            }
+            case 'pin': {
+                let target = null;
+                if (message.reference?.messageId) {
+                    try {
+                        target = await message.channel.messages.fetch(message.reference.messageId);
+                    }
+                    catch { }
+                }
+                if (!target) {
+                    const fetched = await message.channel.messages.fetch({ limit: 2 });
+                    target = fetched.filter(m => m.id !== message.id).first() || fetched.first();
+                }
+                if (target && typeof target.pin === 'function')
+                    await target.pin();
+                break;
+            }
+            case 'purge': {
+                const amt = Number(params.amount || params.n || params.count || '0');
+                if (amt > 0 && 'bulkDelete' in message.channel) {
+                    await message.channel.bulkDelete(Math.min(amt, 100), true);
+                    break;
+                }
+                // No amount -> delete referenced/last message
+                let target = null;
+                if (message.reference?.messageId) {
+                    try {
+                        target = await message.channel.messages.fetch(message.reference.messageId);
+                    }
+                    catch { }
+                }
+                if (!target) {
+                    const fetched = await message.channel.messages.fetch({ limit: 2 });
+                    target = fetched.filter((m) => m.id !== message.id).first() || fetched.first();
+                }
+                if (target && typeof target.delete === 'function')
+                    await target.delete().catch(() => { });
+                break;
+            }
+            default:
+                // Let bots handle domain-specific actions via custom routing
+                break;
+        }
+    }
+    catch { }
+}
+async function executeLocalAction(action, params, message) {
+    try {
+        switch (action) {
+            case 'say': {
+                const t = String(params.message || '').trim();
+                const ch = message.channel;
+                if (t && ch?.send)
+                    await ch.send({ content: t });
+                break;
+            }
+            // Add common cross-bot actions here if desired
+            default:
+                break;
+        }
+    }
+    catch { }
+}
+function parseSlash(text) {
+    const out = {};
+    const t = String(text || '').trim().replace(/^\//, '');
+    if (!t)
+        return { action: null, params: out };
+    const [head, ...rest] = t.split(/\s+/);
+    let action = head.toLowerCase();
+    // parse k=v pairs
+    for (const part of rest) {
+        const m = part.match(/^([^=]+)=(.*)$/);
+        if (m)
+            out[m[1]] = m[2];
+    }
+    // also support freeform for simple commands e.g., "purge 5" or "say hello" (map to message)
+    if (!Object.keys(out).length && rest.length) {
+        if (action === 'purge' && /^\d+$/.test(rest[0]))
+            out.amount = rest[0];
+        else
+            out.message = rest.join(' ');
+    }
+    return { action, params: out };
+}

package/dist-cjs/http.d.ts

@@ -0,0 +1,6 @@
+import { HttpResponse } from "./types.js";
+export declare function postJson<T>(url: string, apiKey: string, body: unknown, opts?: {
+    hmacSecret?: string;
+    timeoutMs?: number;
+    idempotencyKey?: string;
+}): Promise<HttpResponse<T>>;

package/dist-cjs/http.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postJson = postJson;
+const signing_js_1 = require("./signing.js");
+async function postJson(url, apiKey, body, opts) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 15000);
+    const json = JSON.stringify(body);
+    const headers = {
+        "content-type": "application/json",
+        // Use canonical header expected by the server; keep legacy for compatibility
+        "x-api-key": apiKey,
+        "x-commandless-key": apiKey,
+        "x-timestamp": String((0, signing_js_1.nowUnixMs)())
+    };
+    if (opts?.hmacSecret)
+        headers["x-signature"] = (0, signing_js_1.hmacSign)(json, opts.hmacSecret);
+    if (opts?.idempotencyKey)
+        headers["x-idempotency-key"] = opts.idempotencyKey;
+    try {
+        const res = await fetch(url, { method: "POST", body: json, headers, signal: controller.signal });
+        const requestId = res.headers.get("x-request-id") ?? undefined;
+        if (!res.ok) {
+            const text = await safeText(res);
+            return { ok: false, status: res.status, error: text, requestId };
+        }
+        const data = (await res.json());
+        return { ok: true, status: res.status, data, requestId };
+    }
+    catch (err) {
+        return { ok: false, status: 0, error: err?.message ?? String(err) };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+async function safeText(res) {
+    try {
+        return await res.text();
+    }
+    catch {
+        return "";
+    }
+}

package/dist-cjs/index.cjs

@@ -0,0 +1,21 @@
+"use strict";
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./signing.js"), exports);
+__exportStar(require("./http.js"), exports);
+__exportStar(require("./relayClient.js"), exports);
+__exportStar(require("./adapters/discord.js"), exports);

package/dist-cjs/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./signing.js";
+export * from "./http.js";
+export * from "./relayClient.js";
+export * from "./adapters/discord.js";

package/dist-cjs/relayClient.d.ts

@@ -0,0 +1,22 @@
+import { Decision, RelayClientOptions, RelayEvent } from "./types.js";
+export declare class RelayClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly hmacSecret?;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly queue;
+    private sending;
+    private botId?;
+    constructor(opts: RelayClientOptions);
+    registerBot(info: {
+        platform: 'discord';
+        name?: string;
+        clientId?: string;
+    }): Promise<string | null>;
+    heartbeat(): Promise<void>;
+    sendEvent(event: RelayEvent): Promise<Decision | null>;
+    enqueue(event: RelayEvent): void;
+    private drain;
+    private sendWithRetry;
+}

package/dist-cjs/relayClient.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayClient = void 0;
+const http_js_1 = require("./http.js");
+const DEFAULT_BASE = "https://api.commandless.app";
+class RelayClient {
+    constructor(opts) {
+        this.maxRetries = 3;
+        this.queue = [];
+        this.sending = false;
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
+        this.hmacSecret = opts.hmacSecret;
+        this.timeoutMs = opts.timeoutMs ?? 15000;
+    }
+    // Optional: register this SDK bot and obtain/confirm botId
+    async registerBot(info) {
+        try {
+            const url = `${this.baseUrl}/v1/relay/register`;
+            const res = await (0, http_js_1.postJson)(url, this.apiKey, info, {
+                hmacSecret: this.hmacSecret,
+                timeoutMs: this.timeoutMs,
+            });
+            if (res.ok && res.data?.botId) {
+                this.botId = res.data.botId;
+                return this.botId;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // Optional heartbeat to show online status
+    async heartbeat() {
+        try {
+            const url = `${this.baseUrl}/v1/relay/heartbeat`;
+            const res = await (0, http_js_1.postJson)(url, this.apiKey, { botId: this.botId }, {
+                hmacSecret: this.hmacSecret,
+                timeoutMs: this.timeoutMs,
+            });
+            // Return server response to caller (index.js checks syncRequested)
+            return res.data;
+        }
+        catch { }
+    }
+    async sendEvent(event) {
+        // Immediate send with retries and idempotency
+        if (this.botId)
+            event.botId = this.botId;
+        return await this.sendWithRetry(event);
+    }
+    enqueue(event) {
+        this.queue.push(event);
+        if (!this.sending)
+            void this.drain();
+    }
+    async drain() {
+        this.sending = true;
+        while (this.queue.length) {
+            const evt = this.queue.shift();
+            try {
+                await this.sendWithRetry(evt);
+            }
+            catch { /* swallow to keep draining */ }
+        }
+        this.sending = false;
+    }
+    async sendWithRetry(event) {
+        const url = `${this.baseUrl}/v1/relay/events`;
+        const idem = makeIdempotencyKey(event);
+        let lastErr;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const res = await (0, http_js_1.postJson)(url, this.apiKey, event, {
+                hmacSecret: this.hmacSecret,
+                timeoutMs: this.timeoutMs,
+                idempotencyKey: idem,
+            });
+            if (res.ok)
+                return res.data?.decision ?? null;
+            lastErr = new Error(`Commandless error (${res.status}): ${res.error ?? "unknown"}`);
+            // basic backoff
+            await sleep(200 * (attempt + 1));
+        }
+        throw lastErr;
+    }
+}
+exports.RelayClient = RelayClient;
+function makeIdempotencyKey(event) {
+    // Simple stable key: type-id-timestamp buckets (can be improved)
+    const base = `${event.type}:${event.id}:${Math.floor(event.timestamp / 1000)}`;
+    return Buffer.from(base).toString("base64url");
+}
+function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }

package/dist-cjs/signing.d.ts

@@ -0,0 +1,2 @@
+export declare function hmacSign(body: string, secret: string): string;
+export declare function nowUnixMs(): number;

package/dist-cjs/signing.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hmacSign = hmacSign;
+exports.nowUnixMs = nowUnixMs;
+const crypto_1 = __importDefault(require("crypto"));
+function hmacSign(body, secret) {
+    return crypto_1.default.createHmac("sha256", secret).update(body).digest("hex");
+}
+function nowUnixMs() {
+    return Date.now();
+}

package/dist-cjs/types.d.ts

@@ -0,0 +1,60 @@
+export type Snowflake = string;
+export type RelayEvent = {
+    type: "messageCreate";
+    id: string;
+    guildId?: Snowflake;
+    channelId: Snowflake;
+    authorId: Snowflake;
+    content: string;
+    timestamp: number;
+    botClientId?: Snowflake;
+    isReplyToBot?: boolean;
+    referencedMessageId?: string;
+    referencedMessageAuthorId?: Snowflake;
+    referencedMessageContent?: string;
+} | {
+    type: "interactionCreate";
+    id: string;
+    guildId?: Snowflake;
+    channelId?: Snowflake;
+    userId: Snowflake;
+    name: string;
+    options?: Record<string, unknown>;
+    timestamp: number;
+    botClientId?: Snowflake;
+};
+export interface Decision {
+    id: string;
+    intent: string;
+    confidence: number;
+    params: Record<string, unknown>;
+    safety?: {
+        blocked?: boolean;
+        reasons?: string[];
+    };
+    next_step?: string;
+    actions?: Array<{
+        kind: "reply";
+        content: string;
+        ephemeral?: boolean;
+    } | {
+        kind: "command";
+        name?: string;
+        args?: Record<string, unknown>;
+        slash?: string;
+        simulate?: boolean;
+    }>;
+}
+export interface RelayClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    hmacSecret?: string;
+    timeoutMs?: number;
+}
+export interface HttpResponse<T> {
+    ok: boolean;
+    status: number;
+    data?: T;
+    error?: string;
+    requestId?: string;
+}

package/dist-cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@abdarrahmanabdelnasir/relay-node",
+  "version": "0.1.6",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist-cjs/index.cjs",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "dist-cjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist-cjs/package.cjs','')\" && node -e \"const fs=require('fs');fs.renameSync('dist-cjs/index.js','dist-cjs/index.cjs')\"",
+    "clean": "rimraf dist || rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GMOnyx/Commandlessapp"
+  },
+  "homepage": "https://github.com/GMOnyx/Commandlessapp#readme",
+  "bugs": {
+    "url": "https://github.com/GMOnyx/Commandlessapp/issues"
+  },
+  "author": "Commandless",
+  "keywords": [
+    "commandless",
+    "discord",
+    "relay",
+    "sdk",
+    "nlp",
+    "intent"
+  ],
+  "peerDependencies": {
+    "discord.js": ">=14.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.0"
+  }
+}