@komaa/standin-sdk 0.1.0

package/dist/chat.d.ts

@@ -0,0 +1,226 @@
+/**
+ * chat-schema.yaml SCHEMA_VERSION. A MAJOR version: additive evolution does not
+ * bump it, because the schema already requires receivers to ignore unknown
+ * fields. An integer above ours therefore means incompatible semantics.
+ */
+export declare const SCHEMA_VERSION = 1;
+export declare const DEFAULT_CHAT_URL = "wss://teams.standin.komaa.com/api/chat/channel";
+/**
+ * What may be rendered inline in a reply. Raster only, and the decoded bytes
+ * must actually carry the type's signature.
+ *
+ * `image/svg+xml` is deliberately absent and is not a gap to fill later. SVG is
+ * scriptable XML, which is precisely what "an image" must not be.
+ */
+export declare const OUTBOUND_IMAGE_CONTENT_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
+/** What an inline image may weigh, decoded. */
+export declare const OUTBOUND_IMAGE_MAX_BYTES: number;
+/**
+ * A picture to render inline in a reply, carried as bytes.
+ *
+ * Bytes rather than a link, because a link is a beacon: an off-domain image
+ * loads with no click, under this bot's name, and what it serves can be swapped
+ * after anyone looked at it. Bytes can be checked, and {@link outboundImage}
+ * checks them.
+ */
+export interface OutboundImage {
+    readonly contentType: string;
+    readonly contentBase64: string;
+    readonly name?: string;
+}
+/**
+ * One path-free segment, bounded, or undefined.
+ *
+ * A filename reaches a chat as a download under this bot's identity, and the
+ * model that chose it is being steered by whoever is in the conversation.
+ */
+export declare function sanitizeImageName(name: string | undefined): string | undefined;
+/** What these bytes actually are, or undefined. */
+export declare function sniffImageType(data: Buffer): string | undefined;
+/**
+ * Check a picture and build the wire form. Throws on anything it will not send.
+ *
+ * Three checks, and the second is the one that matters. A declared type is a
+ * claim made by whatever produced the bytes; the signature is what they are.
+ * Without it an HTML document or an SVG labelled `image/png` is posted into
+ * somebody's chat under this bot's name.
+ */
+export declare function outboundImage(data: Buffer | string, contentType: string, name?: string): OutboundImage;
+/**
+ * One user message, already authenticated and resolved to your connection.
+ *
+ * Reserved bot commands are handled by StandIn and never arrive here. In group
+ * and channel scope only messages that @mention the bot are relayed, and the
+ * mention is already stripped from `text`.
+ */
+export interface InboundMessage {
+    readonly tenantId: string;
+    readonly conversationId: string;
+    readonly activityId: string;
+    readonly scope: string;
+    readonly text: string;
+    readonly senderName?: string;
+    readonly senderAadId?: string;
+    readonly senderIsGuest: boolean;
+    readonly senderIsLinkedOwner: boolean;
+    readonly attachments: Record<string, unknown>[];
+    readonly mentions: string[];
+    readonly locale?: string;
+    /**
+     * Submit payload of an Action.Submit on a card this agent sent. `text` is
+     * empty on these messages.
+     */
+    readonly cardAction?: Record<string, unknown>;
+    /**
+     * Which StandIn connection this conversation resolved to. Stable for a
+     * tenant, and {@link buildReply} echoes it: one tenant can have several
+     * connections, so the tenant alone no longer says who a reply is from.
+     */
+    readonly bindingId?: string;
+}
+/** True when the message came from a 1:1 chat rather than a group or channel. */
+export declare function isPersonal(message: InboundMessage): boolean;
+/**
+ * How long a remembered 1:1 chat stays usable as a delivery target: 12 hours.
+ *
+ * Long enough to cover a working day, short enough that a conversation from
+ * last week is not treated as evidence of who is on the phone today.
+ */
+export declare const CHAT_FALLBACK_WINDOW_MS: number;
+/** Somebody's own 1:1 chat with this bot, as last seen. */
+export interface PersonalChat {
+    readonly conversationId: string;
+    readonly tenantId: string;
+    /** The sender's AAD object id, or "" when the message carried none. */
+    readonly aadId: string;
+    readonly displayName: string;
+    /** When this chat was last seen, in epoch milliseconds. */
+    readonly atMs: number;
+}
+/** What {@link PersonalChats.forCaller} needs to admit a chat. */
+export interface ForCallerOptions {
+    /** The caller's AAD object id, from the call. */
+    callerAadId?: string;
+    /** The tenant this worker is bound to. Never the caller's own tenant id. */
+    tenantId: string;
+    /** Now, in epoch milliseconds. Defaults to the clock. */
+    nowMs?: number;
+    /**
+     * Drop the identity rule alone, for a single-operator install where the only
+     * person who ever chats with the bot is the only person who ever calls it.
+     * Default false, and every use is warned about by name, because with it on an
+     * unidentified caller's minutes go to whoever messaged this bot last.
+     */
+    allowUnidentified?: boolean;
+}
+/**
+ * The 1:1 chats this bot has been messaged in, so a call can be answered in one.
+ *
+ * A 1:1 CALL carries no thread id and no conversation to post into, so the only
+ * honest source of the caller's own chat is a message they sent the bot from
+ * it. Feed this from the chat lane and read it from the call lane:
+ *
+ * ```ts
+ * const chats = new PersonalChats();
+ * const channel = new ChatChannel({ respond, chats });
+ * // later, on a call:
+ * const mine = chats.forCaller({ callerAadId, tenantId });
+ * ```
+ *
+ * Both lanes have to be in one process for that to work, or the memory has to
+ * be shared some other way. Until it is, a 1:1 recap can only be delivered to
+ * somebody who has messaged this bot inside {@link CHAT_FALLBACK_WINDOW_MS}.
+ *
+ * Nothing is remembered from a group or a channel. That is decided by the
+ * message's SCOPE and by nothing else: an @mention in a team channel would
+ * otherwise make that channel the caller's "chat" and put a private escalation
+ * in front of their whole team.
+ */
+export declare class PersonalChats {
+    #private;
+    constructor(windowMs?: number);
+    /**
+     * Record a 1:1 chat. Anything else is ignored, including a message whose
+     * conversation id merely looks personal.
+     */
+    remember(message: InboundMessage, atMs?: number): void;
+    /**
+     * The chat a call may be answered in, or undefined when there is not one.
+     *
+     * Four things have to hold, and posting call content into the wrong
+     * conversation is the failure all four exist to prevent: the chat was a 1:1
+     * chat, it is in this tenant, it was seen inside
+     * {@link CHAT_FALLBACK_WINDOW_MS}, and the call names a caller whose AAD id
+     * is the one that sent it. Without that last rule every anonymous caller
+     * collapses onto whoever chatted last.
+     */
+    forCaller(options: ForCallerOptions): PersonalChat | undefined;
+}
+/**
+ * Parse and validate an inbound message. Throws naming the problem; the caller
+ * maps that to HTTP 400.
+ */
+export declare function parseInbound(body: string): InboundMessage;
+/**
+ * The gateway-bound reply. tenantId and conversationId echo the inbound
+ * EXACTLY: the gateway rejects a mismatch, and that check is the cross-tenant
+ * leak guard the whole relay rests on.
+ */
+export declare function buildReply(message: InboundMessage, text: string, kind?: string, image?: OutboundImage): Record<string, unknown>;
+/** Options for {@link ChatChannel}. */
+export interface ChatChannelOptions {
+    /**
+     * Async callable taking an {@link InboundMessage} and returning the reply
+     * text. An empty string makes the channel say so rather than leaving the user
+     * watching a typing indicator forever.
+     */
+    respond: (message: InboundMessage) => Promise<string>;
+    /** Your StandIn connection secret, defaulting to `STANDIN_SECRET`. */
+    secret?: string;
+    /** The chat channel URL, defaulting to `STANDIN_CHAT_URL`. */
+    url?: string;
+    /**
+     * Remembers who has a 1:1 chat with this bot, fed on every inbound message.
+     * Share one instance with the call lane and a 1:1 call has somewhere to post
+     * its minutes.
+     */
+    chats?: PersonalChats;
+}
+/**
+ * Answer Microsoft Teams messages with your agent.
+ *
+ * Dialed out from the worker, like the call lane, so nothing listens and there
+ * is nothing to expose. Managed connections only, and that needs no flag: the
+ * socket authenticates with your connection secret, so if it opens at all you
+ * are managed.
+ *
+ * ```ts
+ * const chat = new ChatChannel({
+ *   respond: async (msg) => `You said: ${msg.text}`,
+ * });
+ * await chat.start();
+ * ```
+ */
+export declare class ChatChannel {
+    #private;
+    constructor(options: ChatChannelOptions);
+    /** Dial StandIn and begin taking messages. */
+    start(): Promise<void>;
+    /** Stop taking messages and close the socket. */
+    aclose(): Promise<void>;
+    /**
+     * Post into a Microsoft Teams conversation with no inbound message to answer.
+     *
+     * Useful from inside a call. Best-effort: returns false rather than throwing,
+     * because a failed post must never break a live call.
+     */
+    send(options: {
+        tenantId: string;
+        conversationId: string;
+        text: string;
+        image?: OutboundImage;
+        bindingId?: string;
+        idempotencyKey?: string;
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=chat.d.ts.map

package/dist/chat.d.ts.map

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