@ziggs-ai/api-client 0.38.0 → 0.39.0

package/dist/http/ChatClient.js

@@ -1,219 +0,0 @@
-import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
-import { runtimeLog } from '../shared/runtimeLog.js';
-import { getBackendUrl } from '../utils/urlUtils.js';
-import { throwApiError } from '../shared/apiError.js';
-import { buildCredsHeaders } from './operatorHeaders.js';
-// Auth, agent and the wake's lane, from the one helper — see operatorHeaders.
-const buildHeaders = buildCredsHeaders;
-function assertCreds(creds, op) {
-    if (!creds?.operatorKey)
-        throw new Error(`operatorKey is required for ${op}`);
-    if (!creds?.agentId && !decodeOperatorKeyClaims(creds.operatorKey)?.connectionClientId)
-        throw new Error(`agentId is required for ${op}`);
-}
-export async function openConversation(participant, creds, { newChat = false, agreementId, createIfMissing } = {}) {
-    const input = typeof participant === 'string'
-        ? { participantId: participant, ...(newChat ? { newChat } : {}), ...(agreementId ? { agreementId } : {}), ...(createIfMissing !== undefined ? { createIfMissing } : {}) }
-        : participant;
-    const resumeHire = !!input?.chatId && !!input.agreementId;
-    if (resumeHire && (input.participantId || input.participantIds || input.newChat !== undefined || input.name !== undefined || input.idempotencyKey !== undefined || input.createIfMissing !== undefined)) {
-        throw new Error('To resume hire admission, pass only chatId and agreementId');
-    }
-    if (!input || (!resumeHire && !input.participantId && !input.participantIds?.length)) {
-        throw new Error('participantId is required, or use participantIds to invite people');
-    }
-    assertCreds(creds, 'open conversation');
-    const route = resumeHire
-        ? `/chats/${encodeURIComponent(input.chatId)}/hires/${encodeURIComponent(input.agreementId)}/admission`
-        : '/chats';
-    const res = await fetch(`${getBackendUrl()}${route}`, {
-        method: 'POST',
-        headers: buildHeaders(creds),
-        // Only sent when asked for: an older backend ignores the field, so a
-        // caller that never wants a separate room behaves identically either way.
-        body: JSON.stringify(resumeHire ? {} : input),
-    });
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        throwApiError(res, body, `openConversation failed: ${res.status} ${res.statusText}`);
-    }
-    const data = await res.json().catch(() => null);
-    if (!data?.['chatId'] || typeof data['chatId'] !== 'string') {
-        throw new Error('Invalid response: expected { chatId } from POST /chats');
-    }
-    // left UNDEFINED rather than defaulted when the backend does not
-    // send it. A backend from before this field cannot be assumed to have created
-    // the room — defaulting to false would report a reused conversation as fresh,
-    // which is worse than saying nothing.
-    if (resumeHire && (data.chatId !== input.chatId || data.agreementId !== input.agreementId || !['ready', 'admission_failed'].includes(String(data.status)))) {
-        throw new Error('Invalid hire-admission response: expected the selected chat, hire and admission status');
-    }
-    const reused = data['reused'];
-    const name = data['name'];
-    const invited = Array.isArray(data['invited'])
-        ? data['invited']
-        : undefined;
-    return {
-        chatId: data['chatId'],
-        ...(resumeHire ? {
-            agreementId: input.agreementId,
-            status: data.status,
-            ...(typeof data.reason === 'string' ? { reason: data.reason } : {}),
-        } : {}),
-        ...(typeof reused === 'boolean' ? { reused } : {}),
-        ...(typeof name === 'string' && name ? { name } : {}),
-        ...(invited ? { invited } : {}),
-    };
-}
-function coverageFrom(value) {
-    if (!value || typeof value !== 'object')
-        return null;
-    const row = value;
-    return typeof row['agreementId'] === 'string' &&
-        typeof row['message'] === 'string' &&
-        typeof row['messagesUsed'] === 'number' &&
-        (row['messageLimit'] === null || typeof row['messageLimit'] === 'number')
-        ? {
-            agreementId: row['agreementId'],
-            messagesUsed: row['messagesUsed'],
-            messageLimit: row['messageLimit'],
-            message: row['message'],
-        }
-        : null;
-}
-/**
- * POST /chats/:chatId/members — add user/agent; agent-invite may return pending admission.
- */
-export async function addChatMember(input, creds) {
-    assertCreds(creds, 'add chat member');
-    const res = await fetch(`${getBackendUrl()}/chats/${encodeURIComponent(input.chatId)}/members`, {
-        method: 'POST',
-        headers: buildHeaders(creds),
-        body: JSON.stringify({
-            chatId: input.chatId,
-            memberId: input.memberId,
-            memberType: input.memberType,
-            temporal: input.temporal,
-        }),
-    });
-    const body = await res.text().catch(() => '');
-    if (!res.ok) {
-        throwApiError(res, body, `addChatMember failed: ${res.status} ${res.statusText}`);
-    }
-    const data = JSON.parse(body);
-    if (data['status'] === 'pending' && data['pendingAdmission']) {
-        return {
-            status: 'pending',
-            pendingAdmission: data['pendingAdmission'],
-        };
-    }
-    if (data['status'] === 'approved') {
-        return { status: 'approved', chat: data['chat'] };
-    }
-    return { chat: data['chat'] };
-}
-/**
- * POST /chats/:chatId/messages, or POST /chats/messages when `to` names
- * an existing participant and `chatId` is omitted.
- */
-export async function sendChatMessage(input, creds) {
-    assertCreds(creds, 'send chat message');
-    const chatId = typeof input.chatId === 'string' ? input.chatId.trim() : '';
-    const to = typeof input.to === 'string' ? input.to.trim() : '';
-    if (!chatId && !to) {
-        throw new Error('chatId or to is required for send chat message');
-    }
-    const entryType = input.entryType ?? 'message';
-    const contentType = input.contentType ?? 'text';
-    const personSend = !chatId && Boolean(to);
-    const url = personSend
-        ? `${getBackendUrl()}/chats/messages`
-        : `${getBackendUrl()}/chats/${encodeURIComponent(chatId)}/messages`;
-    const res = await fetch(url, {
-        method: 'POST',
-        headers: buildHeaders(creds),
-        body: JSON.stringify({
-            ...(personSend ? { to } : { chatId }),
-            messageId: input.messageId,
-            text: input.text,
-            entryType,
-            contentType,
-            // Canonical wire shape is `{ id, type? }`; bare strings are still
-            // accepted by the backend after edge normalize, but first-party
-            // clients send the object.
-            receiver: input.receiverId ? { id: input.receiverId } : undefined,
-            underAgreementId: input.underAgreementId,
-            conversationAgreementId: input.conversationAgreementId,
-            taskId: input.taskId,
-            ...(input.sources ? { sources: input.sources } : {}),
-        }),
-    });
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        throwApiError(res, body, `sendChatMessage failed: ${res.status} ${res.statusText}`);
-    }
-    const data = (await res.json().catch(() => null));
-    const delivery = data?.['delivery'];
-    const coverage = coverageFrom(data?.['coverage']);
-    return {
-        success: Boolean(data?.['success']),
-        message: String(data?.['message'] ?? 'ok'),
-        messageId: String(data?.['messageId'] ?? input.messageId),
-        chatId: String(data?.['chatId'] ?? chatId),
-        // Passed through as the server reported it, or absent. Never reconstructed
-        // from the request: the whole point is that the destination may not be the
-        // one the caller named.
-        ...(delivery && typeof delivery === 'object'
-            ? { delivery: delivery }
-            : {}),
-        ...(coverage ? { coverage } : {}),
-    };
-}
-export async function listMyChats(creds, filters = {}) {
-    assertCreds(creds, 'list my chats');
-    const query = new URLSearchParams();
-    if (filters.participantId)
-        query.set('participantId', filters.participantId);
-    if (filters.readable !== undefined)
-        query.set('readable', String(filters.readable));
-    const qs = query.toString();
-    // empty array only for a genuine empty 200; any failure (non-2xx /
-    // network) throws so ziggs_chat_list reports a real error instead of "you
-    // have no chats". HTTP failures are ApiError (status/body/code).
-    let res;
-    try {
-        res = await fetch(`${getBackendUrl()}/chats/mine${qs ? `?${qs}` : ''}`, {
-            method: 'GET',
-            headers: buildHeaders(creds),
-        });
-    }
-    catch (e) {
-        runtimeLog.warn('ChatClient', `⚠️ listMyChats failed: ${e.message}`);
-        throw new Error(`GET /chats/mine network error: ${e.message}`);
-    }
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        runtimeLog.warn('ChatClient', `⚠️ listMyChats failed: ${res.status} ${res.statusText} ${body?.slice(0, 200)}`);
-        throwApiError(res, body, `GET /chats/mine failed: ${res.status}`);
-    }
-    const data = await res.json().catch(() => null);
-    return Array.isArray(data?.['chats']) ? data['chats'] : [];
-}
-export class ChatClient {
-    creds;
-    /**
-     * @param operatorKey Agent-scoped or fleet operator key.
-     * @param agentId Required for fleet keys (sent as X-Agent-Id). Omit for agent-scoped keys.
-     */
-    constructor(operatorKey, agentId) {
-        if (!operatorKey)
-            throw new Error('ChatClient: operatorKey is required');
-        // agentId may be absent for agent-scoped keys; the Creds-based
-        // standalone functions still assert it per call.
-        this.creds = { operatorKey, agentId };
-    }
-    open(participant, opts) { return openConversation(participant, this.creds, opts); }
-    addMember(input) { return addChatMember(input, this.creds); }
-    sendMessage(input) { return sendChatMessage(input, this.creds); }
-    listMine() { return listMyChats(this.creds); }
-}

package/dist/http/MessagesClient.d.ts

@@ -1,40 +0,0 @@
-export interface ListMessagesOptions {
-    /** ISO timestamp; only entries with `timestamp > after` are returned. */
-    after?: string;
-    /** Page size, default 100, hard cap 1000. */
-    limit?: number;
-}
-/**
- * The chat message URL.
- *
- * `after` is a forward delta: the server returns that page only when both
- * `after` and `direction=forward` are set. Omitting both is the newest page,
- * which is how a person asks what just happened without already knowing a time.
- */
-export declare function messagesListUrl(base: string, chatId: string, opts?: ListMessagesOptions): string;
-export interface ListMessagesResult {
-    messages: unknown[];
-    latestSequence: string | null;
-}
-/**
- * Read-side client for forward-delta message reads.
- *
- * Hits the canonical `GET /chats/:chatId/messages?after=&direction=forward&limit=`
- * endpoint and returns a `{ messages, latestSequence }` envelope
- * (`chat-messaging.controller.listMessagesForward` →
- * `MessagesService.listForChat`).
- */
-export declare class MessagesClient {
-    private readonly operatorKey;
-    private readonly agentId;
-    constructor(operatorKey: string, agentId: string);
-    list(chatId: string, opts?: ListMessagesOptions): Promise<ListMessagesResult>;
-    /**
-     * Newest page. No `after`, so the server walks backward from now.
-     * `list` is the forward delta and cannot answer "what just happened".
-     */
-    listLatest(chatId: string, opts?: {
-        limit?: number;
-    }): Promise<ListMessagesResult>;
-    private _headers;
-}

package/dist/http/MessagesClient.js

@@ -1,81 +0,0 @@
-import { decodeOperatorKeyClaims } from '../shared/operatorKey.js';
-import { buildOperatorHeaders } from './operatorHeaders.js';
-import { getBackendUrl } from '../utils/urlUtils.js';
-import { throwApiError } from '../shared/apiError.js';
-/**
- * The chat message URL.
- *
- * `after` is a forward delta: the server returns that page only when both
- * `after` and `direction=forward` are set. Omitting both is the newest page,
- * which is how a person asks what just happened without already knowing a time.
- */
-export function messagesListUrl(base, chatId, opts = {}) {
-    const url = new URL(`${base}/chats/${encodeURIComponent(chatId)}/messages`);
-    if (opts.after) {
-        url.searchParams.set('direction', 'forward');
-        url.searchParams.set('after', opts.after);
-    }
-    if (opts.limit != null)
-        url.searchParams.set('limit', String(opts.limit));
-    return url.toString();
-}
-/**
- * Read-side client for forward-delta message reads.
- *
- * Hits the canonical `GET /chats/:chatId/messages?after=&direction=forward&limit=`
- * endpoint and returns a `{ messages, latestSequence }` envelope
- * (`chat-messaging.controller.listMessagesForward` →
- * `MessagesService.listForChat`).
- */
-export class MessagesClient {
-    operatorKey;
-    agentId;
-    constructor(operatorKey, agentId) {
-        if (!operatorKey)
-            throw new Error('MessagesClient: operatorKey is required');
-        if (!agentId && !decodeOperatorKeyClaims(operatorKey)?.connectionClientId)
-            throw new Error('MessagesClient: agentId is required (operator-token impersonation)');
-        this.operatorKey = operatorKey;
-        this.agentId = agentId;
-    }
-    async list(chatId, opts = {}) {
-        if (!chatId)
-            return { messages: [], latestSequence: null };
-        // Forward-delta read mode. Backend routes to `listMessagesForward`
-        // only when BOTH `after` and `direction=forward` are present; without
-        // `after` the same handler falls into backward pagination and returns
-        // a different envelope. Default `after` to the unix epoch so the
-        // forward branch always wins when callers want "from the beginning".
-        const url = messagesListUrl(getBackendUrl(), chatId, {
-            after: opts.after || '1970-01-01T00:00:00.000Z',
-            limit: opts.limit,
-        });
-        const res = await fetch(url, { headers: this._headers() });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            // Callers branch on ApiError.status (404 = chat deleted/not visible).
-            throwApiError(res, body, `MessagesClient.list failed: ${res.status}`);
-        }
-        return (await res.json());
-    }
-    /**
-     * Newest page. No `after`, so the server walks backward from now.
-     * `list` is the forward delta and cannot answer "what just happened".
-     */
-    async listLatest(chatId, opts = {}) {
-        if (!chatId)
-            return { messages: [], latestSequence: null };
-        const res = await fetch(messagesListUrl(getBackendUrl(), chatId, { limit: opts.limit }), { headers: this._headers() });
-        if (!res.ok) {
-            const body = await res.text().catch(() => '');
-            throwApiError(res, body, `MessagesClient.listLatest failed: ${res.status}`);
-        }
-        return (await res.json());
-    }
-    _headers() {
-        return {
-            'content-type': 'application/json',
-            ...buildOperatorHeaders(this.operatorKey, this.agentId),
-        };
-    }
-}