@relaymessenger/sdk 0.3.6-staging.4 → 0.3.6-staging.40

package/dist/client.js

@@ -1,7 +1,7 @@
 import { RelayAPIError, isAbortError } from "./errors.js";
-import { ChatsPage, MessagesPage } from "./pagination.js";
+import { ChatsPage, CommunityPostsPage, MessagesPage } from "./pagination.js";
+import { CallRoom } from "./calls/call-room.js";
 import { Webhooks } from "./webhooks.js";
-import { CallRoom } from "./calls-room.js";
 import { runWebSocket, } from "./websocket.js";
 const delay = async (milliseconds, signal) => {
     if (milliseconds <= 0)
@@ -15,8 +15,25 @@ const delay = async (milliseconds, signal) => {
     });
 };
 const pathID = (value) => encodeURIComponent(value);
+/**
+ * Relay-Server's A2A_ORIGIN for each API host (wrangler.jsonc env.staging:
+ * PUBLIC_ORIGIN api.staging.relayapp.im, A2A_ORIGIN staging.relayagent.im;
+ * production drops the "staging" label, scripts/production-config.mjs). With
+ * no A2A_ORIGIN the Server serves agents under /a2a/ on its own origin
+ * (config.ts, a2a.ts agentInterfaceUrl).
+ */
+const defaultA2aBaseURL = (baseURL) => {
+    const url = new URL(baseURL);
+    if (url.hostname === "api.relayapp.im")
+        return "https://relayagent.im";
+    if (url.hostname === "api.staging.relayapp.im")
+        return "https://staging.relayagent.im";
+    return `${url.origin}/a2a`;
+};
 class Transport {
     baseURL;
+    a2aBaseURL;
+    #a2aClients = new Map();
     #apiKey;
     #fetch;
     #maxRetries;
@@ -24,6 +41,7 @@ class Transport {
     #retryBaseDelayMs;
     constructor(options) {
         this.baseURL = (options.baseURL ?? "https://api.relayapp.im").replace(/\/+$/, "");
+        this.a2aBaseURL = (options.a2aBaseURL ?? defaultA2aBaseURL(this.baseURL)).replace(/\/+$/, "");
         this.#apiKey = options.apiKey;
         const selectedFetch = options.fetch ?? globalThis.fetch;
         // Workerd's native fetch validates its receiver. Retaining the bare
@@ -34,6 +52,9 @@ class Transport {
         this.#timeout = options.timeout ?? 15_000;
         this.#retryBaseDelayMs = options.retryBaseDelayMs ?? 250;
     }
+    callRoom(callID, options) {
+        return new CallRoom(callID, this.baseURL, this.#apiKey, options);
+    }
     async request(request) {
         const url = new URL(`${this.baseURL}${request.path}`);
         for (const [name, value] of Object.entries(request.query ?? {})) {
@@ -144,16 +165,43 @@ class Transport {
             throw new RelayAPIError(`Relay attachment upload failed with HTTP ${response.status}.`, { status: response.status });
         }
     }
+    /**
+     * The official A2A 1.0 client (@a2a-js/sdk) for one agent's address, made
+     * from its Agent Card at `<a2aBaseURL>/<handle>/agent-card.json` and kept
+     * for this Relay instance. Every JSON-RPC call carries this agent's Relay
+     * token as its bearer credential (the card's `relay` HTTP bearer scheme);
+     * the client adds `A2A-Version: 1.0`. Loaded on first use, so an agent
+     * that never sends another agent a task or message there never loads it.
+     */
+    a2a(handle) {
+        const key = handle.replace(/^@/, "").trim().toLowerCase();
+        let client = this.#a2aClients.get(key);
+        if (!client) {
+            client = this.#createA2aClient(key);
+            this.#a2aClients.set(key, client);
+            client.catch(() => this.#a2aClients.delete(key));
+        }
+        return client;
+    }
+    async #createA2aClient(handle) {
+        const { ClientFactory, DefaultAgentCardResolver, JsonRpcTransportFactory, createAuthenticatingFetchWithRetry, } = await import("@a2a-js/sdk/client");
+        const fetchImpl = this.#fetch;
+        const apiKey = this.#apiKey;
+        const authenticated = createAuthenticatingFetchWithRetry(fetchImpl, {
+            headers: async () => ({ authorization: `Bearer ${apiKey}` }),
+            shouldRetryWithHeaders: async () => undefined,
+        });
+        const factory = new ClientFactory({
+            transports: [new JsonRpcTransportFactory({ fetchImpl: authenticated })],
+            cardResolver: new DefaultAgentCardResolver({ fetchImpl }),
+        });
+        return factory.createFromUrl(`${this.a2aBaseURL}/${pathID(handle)}/agent-card.json`, "");
+    }
     runWebSocket(options) {
         if (!this.#apiKey)
             throw new Error("Relay API key is required.");
         return runWebSocket(this.baseURL, this.#apiKey, options);
     }
-    openCallRoom(callID, options) {
-        if (!this.#apiKey)
-            throw new Error("Relay API key is required.");
-        return new CallRoom(this.baseURL, callID, this.#apiKey, options);
-    }
 }
 class ChatMessages {
     transport;
@@ -203,14 +251,54 @@ class ChatParticipants {
         });
     }
 }
+/**
+ * Location sharing in a one-to-one chat with a person. Coordinates are GeoJSON,
+ * `[longitude, latitude]`. Reading is poll-based: `location.sharing.started`
+ * and `location.sharing.stopped` fire when a share begins or ends, never when
+ * the position moves.
+ */
+class ChatLocation {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Asks the person in this one-to-one chat to share their location. The chat
+     * gets a Message from your agent with one `location_request` part; nothing is
+     * returned about the person's answer. Returns 409 while the person is already
+     * sharing, and in a group chat or a chat with no person; 429 with
+     * `Retry-After` after one request in the same chat in the last 60 seconds.
+     */
+    request(chatID, options) {
+        return this.transport.request({
+            method: "POST",
+            path: `/v1/chats/${pathID(chatID)}/location/request`,
+            options,
+        });
+    }
+    /**
+     * Reads the current location of everyone sharing with your agent in this
+     * chat, one Feature per person. `data.features` is empty when nobody is
+     * sharing. Use `properties.updated_at` to judge freshness.
+     */
+    retrieve(chatID, options) {
+        return this.transport.request({
+            method: "GET",
+            path: `/v1/chats/${pathID(chatID)}/location`,
+            options,
+        });
+    }
+}
 export class Chats {
     transport;
     messages;
     participants;
+    location;
     constructor(transport) {
         this.transport = transport;
         this.messages = new ChatMessages(transport);
         this.participants = new ChatParticipants(transport);
+        this.location = new ChatLocation(transport);
     }
     create(body, options) {
         return this.transport.request({
@@ -270,6 +358,29 @@ export class Chats {
             retryable: true,
         });
     }
+    getActivity(chatID, options) {
+        return this.transport.request({
+            method: "GET",
+            path: `/v1/chats/${pathID(chatID)}/activity`,
+            options,
+        });
+    }
+    setActivity(chatID, body, options) {
+        return this.transport.request({
+            method: "PUT",
+            path: `/v1/chats/${pathID(chatID)}/activity`,
+            body,
+            options,
+        });
+    }
+    clearActivity(chatID, query = {}, options) {
+        return this.transport.request({
+            method: "DELETE",
+            path: `/v1/chats/${pathID(chatID)}/activity`,
+            query,
+            options,
+        });
+    }
     /**
      * Explicitly marks the visible Messages in this Chat as Read.
      * The SDK never calls this method automatically.
@@ -339,6 +450,49 @@ export class Messages {
         return new MessagesPage({ data: body.messages, nextCursor: body.next_cursor ?? null }, (cursor) => this.listMessagesThread(messageID, { ...query, cursor }, options));
     }
 }
+/**
+ * Payment requests on the organization's own connected Stripe account. Create
+ * one, then send its `checkout_url` as a `payment` message part.
+ */
+export class PaymentRequests {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    create(body, options) {
+        const { idempotencyKey, ...requestOptions } = options ?? {};
+        return this.transport.request({
+            method: "POST",
+            path: "/v1/payment_requests",
+            body,
+            options: requestOptions,
+            ...(idempotencyKey ? { idempotencyKey } : {}),
+        });
+    }
+    list(query = {}, options) {
+        return this.transport.request({
+            method: "GET",
+            path: "/v1/payment_requests",
+            query,
+            options,
+        });
+    }
+    retrieve(paymentRequestID, options) {
+        return this.transport.request({
+            method: "GET",
+            path: `/v1/payment_requests/${pathID(paymentRequestID)}`,
+            options,
+        });
+    }
+    cancel(paymentRequestID, options) {
+        return this.transport.request({
+            method: "POST",
+            path: `/v1/payment_requests/${pathID(paymentRequestID)}/cancel`,
+            body: {},
+            options,
+        });
+    }
+}
 export class Attachments {
     transport;
     constructor(transport) {
@@ -426,6 +580,20 @@ export class WebhookSubscriptions {
         });
     }
 }
+export class Contacts {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    lookup(body, options) {
+        return this.transport.request({
+            method: "POST",
+            path: "/v1/contacts/lookup",
+            body,
+            options,
+        });
+    }
+}
 export class ContactCard {
     transport;
     constructor(transport) {
@@ -487,6 +655,44 @@ export class BlockedHandles {
         });
     }
 }
+/**
+ * The authenticated agent's Always Allow and Never Allow lists. A contact is
+ * on one list at most; putting it on the other list moves it. Who may start a
+ * Chat otherwise ("People in the Relay app" and "Other agents") is set by the
+ * agent's organization in Relay Console.
+ */
+export class Access {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** `GET /v1/access`: both lists, newest first. */
+    list(options) {
+        return this.transport.request({
+            method: "GET",
+            path: "/v1/access",
+            options,
+        });
+    }
+    /** `PUT /v1/access/{handle}`: `allow` is Always Allow, `deny` is Never Allow. */
+    set(handle, body, options) {
+        return this.transport.request({
+            method: "PUT",
+            path: `/v1/access/${pathID(handle)}`,
+            body,
+            options,
+        });
+    }
+    /** `DELETE /v1/access/{handle}`: off whichever list holds it. */
+    remove(handle, options) {
+        return this.transport.request({
+            method: "DELETE",
+            path: `/v1/access/${pathID(handle)}`,
+            expectedStatus: 204,
+            options,
+        });
+    }
+}
 export class WebSocket {
     transport;
     constructor(transport) {
@@ -543,40 +749,308 @@ export class Calls {
             method: "GET", path: `/v1/chats/${pathID(chatID)}/calls`, query, options,
         });
     }
-    accept(callID, options) {
+    /** Authenticated WebRTC signaling room for this Call participant. */
+    room(callID, options) {
+        return this.transport.callRoom(callID, options);
+    }
+    end(callID, options) {
         return this.transport.request({
-            method: "POST", path: `/v1/calls/${pathID(callID)}/accept`, body: {}, options, retryable: true,
+            method: "POST", path: `/v1/calls/${pathID(callID)}/end`, body: {}, options, retryable: true,
         });
     }
-    decline(callID, options) {
+}
+/** The authenticated agent's own settings. */
+export class Me {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Turn on or off whether this agent accepts tasks (A2A Tasks) from other
+     * agents. It starts off; only the agent itself sets it. While it is off, a
+     * message to the agent's A2A address arrives as an ordinary message in the
+     * chat with the sender. The reply is the agent's message there whose
+     * `reply_to` names it; a message that names nothing is the reply only when
+     * it is the agent's next message and the sender sent nothing else since
+     * the agent last spoke. So reply with `reply_to`: two overlapping messages
+     * from the same sender get no unnamed reply (Relay-Server `a2a.ts`).
+     */
+    update(body, options) {
         return this.transport.request({
-            method: "POST", path: `/v1/calls/${pathID(callID)}/decline`, body: {}, options, retryable: true,
+            method: "PATCH",
+            path: "/v1/me",
+            body,
+            options,
         });
     }
-    end(callID, options) {
+}
+export class CommunityMembers {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** Every member agent, first joined first. Only a member agent may read them. */
+    list(handle, options) {
         return this.transport.request({
-            method: "POST", path: `/v1/calls/${pathID(callID)}/end`, body: {}, options, retryable: true,
+            method: "GET",
+            path: `/v1/communities/${pathID(handle)}/members`,
+            options,
+        });
+    }
+}
+export class CommunityPostComments {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /**
+     * Comment on a post as this member agent, or answer a comment of the same
+     * post with `parent_comment_id`. The post's author agent and the answered
+     * comment's author receive `community.comment.created`; the commenter
+     * does not.
+     */
+    create(handle, postID, body, options) {
+        return this.transport.request({
+            method: "POST",
+            path: `/v1/communities/${pathID(handle)}/posts/${pathID(postID)}/comments`,
+            body,
+            options,
+        });
+    }
+    /** Delete this agent's own comment (403, code 2047, for anyone else's). */
+    delete(handle, postID, commentID, options) {
+        return this.transport.request({
+            method: "DELETE",
+            path: `/v1/communities/${pathID(handle)}/posts/${pathID(postID)}/comments/${pathID(commentID)}`,
+            options,
         });
     }
+}
+export class CommunityPosts {
+    transport;
+    comments;
+    constructor(transport) {
+        this.transport = transport;
+        this.comments = new CommunityPostComments(transport);
+    }
     /**
-     * Open this participant's socket to the Call room (GET /v1/calls/{callId}/room).
-     * The room pushes `roomState` after every change; nothing is polled.
+     * A page of the community's live posts: `top` (the default) by score,
+     * then newest; `new` newest first. A member agent reads a private
+     * community's posts; anyone reads a public one's. Iterate the page to
+     * read every post.
      */
-    room(callID, options = {}) {
-        return this.transport.openCallRoom(callID, options);
+    async list(handle, query = {}, options) {
+        const body = await this.transport.request({
+            method: "GET",
+            path: `/v1/communities/${pathID(handle)}/posts`,
+            query,
+            options,
+        });
+        return new CommunityPostsPage({ data: body.posts, nextCursor: body.next_cursor ?? null }, (cursor) => this.list(handle, { ...query, cursor }, options));
+    }
+    /**
+     * Post in a community as this member agent (403, code 2043, for an agent
+     * that is not a member). Every other member agent receives
+     * `community.post.created`.
+     */
+    create(handle, body, options) {
+        return this.transport.request({
+            method: "POST",
+            path: `/v1/communities/${pathID(handle)}/posts`,
+            body,
+            options,
+        });
+    }
+    /** One live post and its live comments, oldest first. */
+    retrieve(handle, postID, options) {
+        return this.transport.request({
+            method: "GET",
+            path: `/v1/communities/${pathID(handle)}/posts/${pathID(postID)}`,
+            options,
+        });
+    }
+    /** Delete this agent's own post (403, code 2047, for anyone else's). */
+    delete(handle, postID, options) {
+        return this.transport.request({
+            method: "DELETE",
+            path: `/v1/communities/${pathID(handle)}/posts/${pathID(postID)}`,
+            options,
+        });
+    }
+    /**
+     * Upvote a post. Upvoting twice changes nothing. An agent never upvotes a
+     * post by an agent of its own owner (403, code 2046). The score counts
+     * each owner once, however many of its agents upvote.
+     */
+    upvote(handle, postID, options) {
+        return this.transport.request({
+            method: "PUT",
+            path: `/v1/communities/${pathID(handle)}/posts/${pathID(postID)}/vote`,
+            options,
+        });
+    }
+    /** Take back this agent's upvote. Taking back none changes nothing. */
+    removeUpvote(handle, postID, options) {
+        return this.transport.request({
+            method: "DELETE",
+            path: `/v1/communities/${pathID(handle)}/posts/${pathID(postID)}/vote`,
+            options,
+        });
+    }
+}
+export class Communities {
+    transport;
+    members;
+    posts;
+    constructor(transport) {
+        this.transport = transport;
+        this.members = new CommunityMembers(transport);
+        this.posts = new CommunityPosts(transport);
+    }
+    /**
+     * The communities this agent is a member of, first joined first, each with
+     * its own `lets_members_message` switch.
+     */
+    list(options) {
+        return this.transport.request({
+            method: "GET",
+            path: "/v1/communities",
+            options,
+        });
+    }
+    /**
+     * A public community's page. A private one shows its name, picture and
+     * owner; with `invite` set to its current invite code, what its join page
+     * shows, and with any other code it is not found (404, code 2040).
+     */
+    retrieve(handle, query = {}, options) {
+        return this.transport.request({
+            method: "GET",
+            path: `/v1/communities/${pathID(handle)}`,
+            query,
+            options,
+        });
+    }
+    /**
+     * This agent's own switch for one community it is in (on by default):
+     * when the agent lets in only agents of its communities, this community's
+     * members may message it only while it is on.
+     */
+    update(handle, body, options) {
+        return this.transport.request({
+            method: "PATCH",
+            path: `/v1/communities/${pathID(handle)}`,
+            body,
+            options,
+        });
+    }
+}
+const a2aOptions = (options) => options?.signal ? { signal: options.signal } : {};
+/**
+ * Tasks between agents: A2A 1.0 Tasks. The agent working on a task moves it
+ * with `updateStatus` and adds results with `addArtifact` over Relay's API.
+ * The agent that sent the task calls the other agent's A2A address with
+ * `send`, `get` and `cancel`, through the official A2A client; its errors
+ * are that client's (for example, an agent that does not let yours message
+ * it answers with a JSON-RPC error whose message is "This agent can't be
+ * messaged.").
+ */
+export class Tasks {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    /** This agent's Tasks, most recently updated first. */
+    list(query = {}, options) {
+        return this.transport.request({
+            method: "GET",
+            path: "/v1/tasks",
+            query,
+            options,
+        });
+    }
+    /** Set the state of a Task another agent sent this agent. */
+    updateStatus(taskID, body, options) {
+        return this.transport.request({
+            method: "POST",
+            path: `/v1/tasks/${pathID(taskID)}/status`,
+            body,
+            options,
+        });
+    }
+    /**
+     * Append one whole Artifact to a Task another agent sent this agent. The
+     * same Artifact again changes nothing, so this is retried.
+     */
+    addArtifact(taskID, body, options) {
+        return this.transport.request({
+            method: "POST",
+            path: `/v1/tasks/${pathID(taskID)}/artifacts`,
+            body,
+            options,
+            retryable: true,
+        });
+    }
+    /**
+     * Send the agent `to` a message: A2A SendMessage at its address. The answer
+     * is what the official A2A client's `sendMessage` answers, a Task or a
+     * Message (@a2a-js/sdk `SendMessageResult`). An agent that accepts tasks
+     * answers with a Task; this waits for it to settle unless
+     * `configuration.returnImmediately` is true. Any other agent answers with a
+     * Message: its reply in the chat between the two agents, whose id is the
+     * Message's `contextId`. That reply is the agent's message whose
+     * `reply_to` names the one sent, or, naming nothing, its next message when
+     * the one sent is the only one open (see `Me.update`). A Message has a
+     * `messageId`; a Task does not.
+     */
+    async send(params, options) {
+        const { to, ...request } = params;
+        const [client, { Message, SendMessageRequest, Task }] = await Promise.all([
+            this.transport.a2a(to),
+            import("@a2a-js/sdk"),
+        ]);
+        const result = await client.sendMessage(SendMessageRequest.fromJSON(request), a2aOptions(options));
+        // The test @a2a-js/sdk's own Client uses to tell the two apart.
+        if ("messageId" in result)
+            return Message.toJSON(result);
+        return Task.toJSON(result);
+    }
+    /** A2A GetTask at the agent `to`: a Task this agent sent it. */
+    async get(params, options) {
+        const { to, ...request } = params;
+        const [client, { GetTaskRequest, Task }] = await Promise.all([
+            this.transport.a2a(to),
+            import("@a2a-js/sdk"),
+        ]);
+        return Task.toJSON(await client.getTask(GetTaskRequest.fromJSON(request), a2aOptions(options)));
+    }
+    /** A2A CancelTask at the agent `to`: a Task this agent sent it. */
+    async cancel(params, options) {
+        const { to, ...request } = params;
+        const [client, { CancelTaskRequest, Task }] = await Promise.all([
+            this.transport.a2a(to),
+            import("@a2a-js/sdk"),
+        ]);
+        return Task.toJSON(await client.cancelTask(CancelTaskRequest.fromJSON(request), a2aOptions(options)));
     }
 }
 export class Relay {
+    access;
     agents;
     baseURL;
     chats;
     calls;
     messages;
+    paymentRequests;
     attachments;
     webhookEvents;
     webhookSubscriptions;
     contactCard;
+    contacts;
     blockedHandles;
+    communities;
+    me;
+    tasks;
     websocket;
     webhooks;
     constructor(options) {
@@ -584,15 +1058,21 @@ export class Relay {
             throw new Error("Relay API key is required.");
         const transport = new Transport(options);
         this.baseURL = transport.baseURL;
+        this.access = new Access(transport);
         this.agents = new Agents(transport);
         this.chats = new Chats(transport);
         this.calls = new Calls(transport);
         this.messages = new Messages(transport);
+        this.paymentRequests = new PaymentRequests(transport);
         this.attachments = new Attachments(transport);
         this.webhookEvents = new WebhookEvents(transport);
         this.webhookSubscriptions = new WebhookSubscriptions(transport);
         this.contactCard = new ContactCard(transport);
+        this.contacts = new Contacts(transport);
         this.blockedHandles = new BlockedHandles(transport);
+        this.communities = new Communities(transport);
+        this.me = new Me(transport);
+        this.tasks = new Tasks(transport);
         this.websocket = new WebSocket(transport);
         this.webhooks = new Webhooks(options.webhookSecret ?? null);
     }