feat(api): manual updates

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 1
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-8c712fe19f280b0b89ecc8a3ce61e9f6b165cee97ce33f66c66a7a5db339c755.yml
-openapi_spec_hash: 1ea71129cc1a1ccc3dc8a99566082311
+configured_endpoints: 14
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/beeper%2Fbeeper-desktop-api-9f5190d7df873112f3512b5796cd95341f0fa0d2585488d3e829be80ee6045ce.yml
+openapi_spec_hash: ba834200758376aaea47b2a276f64c1b
 config_hash: f83b2b6eb86f2dd68101065998479cb2

README.md

@@ -24,9 +24,10 @@ const client = new BeeperDesktop({
   accessToken: process.env['BEEPER_ACCESS_TOKEN'], // This is the default and can be omitted
 });
 
-const userInfo = await client.token.info();
+const page = await client.chats.search({ includeMuted: true, limit: 3, type: 'single' });
+const chat = page.items[0];
 
-console.log(userInfo.sub);
+console.log(chat.id);
 ```
 
 ### Request & Response types
@@ -41,7 +42,7 @@ const client = new BeeperDesktop({
   accessToken: process.env['BEEPER_ACCESS_TOKEN'], // This is the default and can be omitted
 });
 
-const userInfo: BeeperDesktop.UserInfo = await client.token.info();
+const accounts: BeeperDesktop.AccountListResponse = await client.accounts.list();
 ```
 
 Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors.
@@ -54,15 +55,17 @@ a subclass of `APIError` will be thrown:
 
 <!-- prettier-ignore -->
 ```ts
-const userInfo = await client.token.info().catch(async (err) => {
-  if (err instanceof BeeperDesktop.APIError) {
-    console.log(err.status); // 400
-    console.log(err.name); // BadRequestError
-    console.log(err.headers); // {server: 'nginx', ...}
-  } else {
-    throw err;
-  }
-});
+const response = await client.messages
+  .send({ chatID: '1229391', text: 'Hello! Just checking in on the project status.' })
+  .catch(async (err) => {
+    if (err instanceof BeeperDesktop.APIError) {
+      console.log(err.status); // 400
+      console.log(err.name); // BadRequestError
+      console.log(err.headers); // {server: 'nginx', ...}
+    } else {
+      throw err;
+    }
+  });
 ```
 
 Error codes are as follows:
@@ -94,7 +97,7 @@ const client = new BeeperDesktop({
 });
 
 // Or, configure per-request:
-await client.token.info({
+await client.accounts.list({
   maxRetries: 5,
 });
 ```
@@ -111,7 +114,7 @@ const client = new BeeperDesktop({
 });
 
 // Override per-request:
-await client.token.info({
+await client.accounts.list({
   timeout: 5 * 1000,
 });
 ```
@@ -120,6 +123,45 @@ On timeout, an `APIConnectionTimeoutError` is thrown.
 
 Note that requests which time out will be [retried twice by default](#retries).
 
+## Auto-pagination
+
+List methods in the BeeperDesktop API are paginated.
+You can use the `for await … of` syntax to iterate through items across all pages:
+
+```ts
+async function fetchAllMessages(params) {
+  const allMessages = [];
+  // Automatically fetches more pages as needed.
+  for await (const message of client.messages.search({
+    accountIDs: ['local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI'],
+    limit: 10,
+    query: 'deployment',
+  })) {
+    allMessages.push(message);
+  }
+  return allMessages;
+}
+```
+
+Alternatively, you can request a single page at a time:
+
+```ts
+let page = await client.messages.search({
+  accountIDs: ['local-telegram_ba_QFrb5lrLPhO3OT5MFBeTWv0x4BI'],
+  limit: 10,
+  query: 'deployment',
+});
+for (const message of page.items) {
+  console.log(message);
+}
+
+// Convenience methods are provided for manually paginating:
+while (page.hasNextPage()) {
+  page = await page.getNextPage();
+  // ...
+}
+```
+
 ## Advanced Usage
 
 ### Accessing raw Response data (e.g., headers)
@@ -134,13 +176,13 @@ Unlike `.asResponse()` this method consumes the body, returning once it is parse
 ```ts
 const client = new BeeperDesktop();
 
-const response = await client.token.info().asResponse();
+const response = await client.accounts.list().asResponse();
 console.log(response.headers.get('X-My-Header'));
 console.log(response.statusText); // access the underlying Response object
 
-const { data: userInfo, response: raw } = await client.token.info().withResponse();
+const { data: accounts, response: raw } = await client.accounts.list().withResponse();
 console.log(raw.headers.get('X-My-Header'));
-console.log(userInfo.sub);
+console.log(accounts);
 ```
 
 ### Logging
@@ -220,7 +262,7 @@ parameter. This library doesn't validate at runtime that the request matches the
 send will be sent as-is.
 
 ```ts
-client.token.info({
+client.chats.search({
   // ...
   // @ts-expect-error baz is not yet public
   baz: 'undocumented option',

api.md

@@ -1,5 +1,17 @@
 # BeeperDesktop
 
+Types:
+
+- <code><a href="./src/resources/top-level.ts">DownloadAssetResponse</a></code>
+- <code><a href="./src/resources/top-level.ts">OpenResponse</a></code>
+- <code><a href="./src/resources/top-level.ts">SearchResponse</a></code>
+
+Methods:
+
+- <code title="post /v1/app/download-asset">client.<a href="./src/index.ts">downloadAsset</a>({ ...params }) -> DownloadAssetResponse</code>
+- <code title="post /v1/app/open">client.<a href="./src/index.ts">open</a>({ ...params }) -> OpenResponse</code>
+- <code title="get /v1/search">client.<a href="./src/index.ts">search</a>({ ...params }) -> SearchResponse</code>
+
 # Shared
 
 Types:
@@ -16,19 +28,54 @@ Types:
 Types:
 
 - <code><a href="./src/resources/accounts.ts">Account</a></code>
+- <code><a href="./src/resources/accounts.ts">AccountListResponse</a></code>
+
+Methods:
+
+- <code title="get /v1/accounts">client.accounts.<a href="./src/resources/accounts.ts">list</a>() -> AccountListResponse</code>
 
 # Contacts
 
+Types:
+
+- <code><a href="./src/resources/contacts.ts">ContactSearchResponse</a></code>
+
+Methods:
+
+- <code title="get /v1/contacts/search">client.contacts.<a href="./src/resources/contacts.ts">search</a>({ ...params }) -> ContactSearchResponse</code>
+
 # Chats
 
 Types:
 
 - <code><a href="./src/resources/chats/chats.ts">Chat</a></code>
+- <code><a href="./src/resources/chats/chats.ts">ChatCreateResponse</a></code>
+
+Methods:
+
+- <code title="post /v1/chats">client.chats.<a href="./src/resources/chats/chats.ts">create</a>({ ...params }) -> ChatCreateResponse</code>
+- <code title="get /v1/chats/{chatID}">client.chats.<a href="./src/resources/chats/chats.ts">retrieve</a>(chatID, { ...params }) -> Chat</code>
+- <code title="post /v1/chats/{chatID}/archive">client.chats.<a href="./src/resources/chats/chats.ts">archive</a>(chatID, { ...params }) -> BaseResponse</code>
+- <code title="get /v1/chats/search">client.chats.<a href="./src/resources/chats/chats.ts">search</a>({ ...params }) -> ChatsCursor</code>
 
 ## Reminders
 
+Methods:
+
+- <code title="post /v1/chats/{chatID}/reminders">client.chats.reminders.<a href="./src/resources/chats/reminders.ts">create</a>(chatID, { ...params }) -> BaseResponse</code>
+- <code title="delete /v1/chats/{chatID}/reminders">client.chats.reminders.<a href="./src/resources/chats/reminders.ts">delete</a>(chatID) -> BaseResponse</code>
+
 # Messages
 
+Types:
+
+- <code><a href="./src/resources/messages.ts">MessageSendResponse</a></code>
+
+Methods:
+
+- <code title="get /v1/messages/search">client.messages.<a href="./src/resources/messages.ts">search</a>({ ...params }) -> MessagesCursor</code>
+- <code title="post /v1/messages">client.messages.<a href="./src/resources/messages.ts">send</a>({ ...params }) -> MessageSendResponse</code>
+
 # Token
 
 Types:

packages/mcp-server/README.md

@@ -59,6 +59,7 @@ You can filter by multiple aspects:
 - `--tool` includes a specific tool by name
 - `--resource` includes all tools under a specific resource, and can have wildcards, e.g. `my.resource*`
 - `--operation` includes just read (get/list) or just write operations
+- `--tag` includes a set of endpoints with custom tags provided
 
 ### Dynamic tools
 
@@ -179,7 +180,7 @@ http://localhost:3000?client=cursor&capability=tool-name-length%3D40
 import { server, endpoints, init } from "@beeper/desktop-api-mcp/server";
 
 // import a specific tool
-import infoToken from "@beeper/desktop-api-mcp/tools/token/info-token";
+import downloadAssetClient from "@beeper/desktop-api-mcp/tools/top-level/download-asset-client";
 
 // initialize the server and all endpoints
 init({ server, endpoints });
@@ -204,13 +205,56 @@ const myCustomEndpoint = {
 };
 
 // initialize the server with your custom endpoints
-init({ server: myServer, endpoints: [infoToken, myCustomEndpoint] });
+init({ server: myServer, endpoints: [downloadAssetClient, myCustomEndpoint] });
 ```
 
 ## Available Tools
 
 The following tools are available in this MCP server.
 
+### Resource `$client`:
+
+- `download_asset_client` (`write`): Download a Matrix asset using its mxc:// or localmxc:// URL and return the local file URL.
+- `open_in_app` (`write`) tags: [app]: Open Beeper Desktop and optionally navigate to a specific chat, message, or pre-fill draft text and attachment.
+- `search` (`read`) tags: [app]: Search for chats, participant name matches in groups, and the first page of messages in one call. Use this when the user asks for a specific chat, group, or person.
+
+### Resource `accounts`:
+
+- `get_accounts` (`read`) tags: [accounts]: List connected accounts on this device. Use to pick account context.
+
+### Resource `contacts`:
+
+- `search_contacts` (`read`): Search contacts across on a specific account using the network's search API. Only use for creating new chats.
+
+### Resource `chats`:
+
+- `create_chats` (`write`): Create a single or group chat on a specific account using participant IDs and optional title.
+- `get_chat` (`read`) tags: [chats]: Get chat details: metadata, participants (limited), last activity.
+- `archive_chat` (`write`) tags: [chats]: Archive or unarchive a chat.
+- `search_chats` (`read`) tags: [chats]: Search chats by title/network or participants using Beeper Desktop's renderer algorithm. Optional 'scope'.
+
+### Resource `chats.reminders`:
+
+- `set_chat_reminder` (`write`) tags: [chats]: Set a reminder for a chat at a specific time.
+- `clear_chat_reminder` (`write`) tags: [chats]: Clear a chat reminder.
+
+### Resource `messages`:
+
+- `search_messages` (`read`) tags: [messages]: Search messages across chats using Beeper's message index.
+  - When to use: find messages by text and/or filters (chatIDs, accountIDs, chatType, media type filters, sender, date ranges).
+  - CRITICAL: Query is LITERAL WORD MATCHING, NOT semantic search! Only finds messages containing these EXACT words.
+    • ✅ RIGHT: query="dinner" or query="sick" or query="error" (single words users type)
+    • ❌ WRONG: query="dinner plans tonight" or query="health issues" (phrases/concepts)
+    • The query matches ALL words provided (in any order). Example: query="flight booking" finds messages with both "flight" AND "booking".
+  - Performance: provide chatIDs/accountIDs when known. Omitted 'query' returns results based on filters only. Partial matches enabled; 'excludeLowPriority' defaults to true.
+  - Workflow tip: To search messages in specific conversations: 1) Use find-chats to get chatIDs, 2) Use search-messages with those chatIDs.
+  - IMPORTANT: Chat names vary widely. ASK the user for clarification:
+    • "Which chat do you mean by family?" (could be "The Smiths", "Mom Dad Kids", etc.)
+    • "What's the name of your work chat?" (could be "Team", company name, project name)
+    • "Who are the participants?" (use scope="participants" in search-chats)
+    Returns: matching messages and referenced chats.
+- `send_message` (`write`) tags: [messages]: Send a text message to a specific chat. Supports replying to existing messages. Returns the sent message ID and a deeplink to the chat
+
 ### Resource `token`:
 
 - `info_token` (`read`): Returns information about the authenticated user/token

packages/mcp-server/src/tools/accounts/get-accounts.ts

@@ -0,0 +1,34 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@beeper/desktop-api-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import BeeperDesktop from '@beeper/desktop-api';
+
+export const metadata: Metadata = {
+  resource: 'accounts',
+  operation: 'read',
+  tags: ['accounts'],
+  httpMethod: 'get',
+  httpPath: '/v1/accounts',
+  operationId: 'getAccounts',
+};
+
+export const tool: Tool = {
+  name: 'get_accounts',
+  description: 'List connected accounts on this device. Use to pick account context.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: [],
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+export const handler = async (client: BeeperDesktop, args: Record<string, unknown> | undefined) => {
+  return asTextContentResult(await client.accounts.list());
+};
+
+export default { metadata, tool, handler };

packages/mcp-server/src/tools/chats/archive-chat.ts

@@ -0,0 +1,43 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from '@beeper/desktop-api-mcp/tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import BeeperDesktop from '@beeper/desktop-api';
+
+export const metadata: Metadata = {
+  resource: 'chats',
+  operation: 'write',
+  tags: ['chats'],
+  httpMethod: 'post',
+  httpPath: '/v1/chats/{chatID}/archive',
+  operationId: 'archiveChat',
+};
+
+export const tool: Tool = {
+  name: 'archive_chat',
+  description: 'Archive or unarchive a chat.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      chatID: {
+        type: 'string',
+        description:
+          'The identifier of the chat to archive or unarchive (accepts both chatID and local chat ID)',
+      },
+      archived: {
+        type: 'boolean',
+        description: 'True to archive, false to unarchive',
+      },
+    },
+    required: ['chatID'],
+  },
+  annotations: {},
+};
+
+export const handler = async (client: BeeperDesktop, args: Record<string, unknown> | undefined) => {
+  const { chatID, ...body } = args as any;
+  return asTextContentResult(await client.chats.archive(chatID, body));
+};
+
+export default { metadata, tool, handler };