@myronsi/messenger-api 2.0.0-alpha.5.next.46 → 2.0.0-alpha.7.next.49

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Contract changes only. The backend changelog is `CHANGELOG.md` in the repository root. Rules: `docs/api-compatibility.md`.
 
+## 2.0.0-alpha.7
+
+Search:
+
+- New `GET /search/messages`: full-text search across all chats of the caller, with filters (`chat_id`, `sender_id`,
+  `type`, `from`, `to`) and `search_after` paging.
+- `SearchHit.highlight` wraps the matched words in U+E000 and U+E001.
+- `GET /chats/{chat_id}/messages/search` can answer `429` (searches are rate limited).
+
+## 2.0.0-alpha.6
+
+Groups, found while implementing them:
+
+- `POST /groups` can answer `403`: a member who does not allow invitations from the caller fails the request.
+- `PUT /groups/{chat_id}/avatar` (`422`: not an image the caller uploaded as an avatar) and
+  `POST /groups/{chat_id}/transfer-owner` (`422`: to yourself) document their validation errors.
+
 ## 2.0.0-alpha.5
 
 Chats, found while implementing the chat list:

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.5. Do not edit. */
-export declare const API_VERSION: "2.0.0-alpha.5";
+/* Generated from api/openapi.yaml 2.0.0-alpha.7. Do not edit. */
+export declare const API_VERSION: "2.0.0-alpha.7";
 export type { paths, components, operations } from "./schema.js";
 export * from "./ws-events.js";

package/dist/index.js

@@ -1 +1 @@
-export const API_VERSION = "2.0.0-alpha.5";
+export const API_VERSION = "2.0.0-alpha.7";

package/dist/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Messenger API
-  version: 2.0.0-alpha.5
+  version: 2.0.0-alpha.7
   summary: REST contract of the Messenger backend (v2).
   description: |
     Contract for the Go backend. The WebSocket protocol is described in `websocket/` and
@@ -1127,6 +1127,7 @@ paths:
         "401": { $ref: "#/components/responses/Unauthorized" }
         "404": { $ref: "#/components/responses/NotFound" }
         "422": { $ref: "#/components/responses/ValidationFailed" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
   /chats/{chat_id}/media:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -1240,6 +1241,62 @@ paths:
         "422": { $ref: "#/components/responses/ValidationFailed" }
         "429": { $ref: "#/components/responses/TooManyRequests" }
 
+  # -------------------------------------------------------------- search
+  /search/messages:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+    get:
+      tags: [messages]
+      operationId: searchAllMessages
+      summary: Search messages in all my chats
+      description: |
+        Full-text search across every chat the caller is in, newest first. Only chats the caller
+        is a member of are searched, messages they deleted for themselves are left out, and every
+        hit is checked against the message store before it is returned (a deleted message never
+        shows, even when the index lags behind). Edits and deletions reach the results within a
+        few seconds.
+      parameters:
+        - name: q
+          in: query
+          required: true
+          schema: { type: string, minLength: 2, maxLength: 128 }
+        - name: chat_id
+          in: query
+          description: Only this chat
+          schema: { $ref: "#/components/schemas/Id" }
+        - name: sender_id
+          in: query
+          description: Only messages of this user
+          schema: { $ref: "#/components/schemas/Id" }
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: [text, file, voice]
+        - name: from
+          in: query
+          description: Messages created at or after this time
+          schema: { $ref: "#/components/schemas/Timestamp" }
+        - name: to
+          in: query
+          description: Messages created before this time
+          schema: { $ref: "#/components/schemas/Timestamp" }
+        - $ref: "#/components/parameters/Limit"
+        - $ref: "#/components/parameters/After"
+      responses:
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "200":
+          description: Matches, newest first
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/MessageSearchPage" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "404": { $ref: "#/components/responses/NotFound" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
+
   # ------------------------------------------------------------ requests
   /requests:
     parameters:
@@ -1333,7 +1390,9 @@ paths:
       tags: [groups]
       operationId: createGroup
       summary: Create a group
-      description: Members whose `group_invites` setting requires approval get an approval request instead of being added.
+      description: |
+        Members whose `group_invites` setting requires approval get an approval request instead of being added.
+        If any of them does not allow invitations from the caller at all, nothing is created (`403`).
       requestBody:
         required: true
         content:
@@ -1348,6 +1407,7 @@ paths:
               schema: { $ref: "#/components/schemas/Group" }
         "400": { $ref: "#/components/responses/BadRequest" }
         "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
         "422": { $ref: "#/components/responses/ValidationFailed" }
         "429": { $ref: "#/components/responses/TooManyRequests" }
   /groups/{chat_id}:
@@ -1411,6 +1471,7 @@ paths:
       tags: [groups]
       operationId: setGroupAvatar
       summary: Set the group avatar from an uploaded attachment
+      description: The attachment must be an image the caller uploaded with purpose `avatar` (`422` otherwise).
       requestBody:
         required: true
         content:
@@ -1427,6 +1488,7 @@ paths:
         "401": { $ref: "#/components/responses/Unauthorized" }
         "403": { $ref: "#/components/responses/Forbidden" }
         "404": { $ref: "#/components/responses/NotFound" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
   /groups/{chat_id}/participants:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -1501,6 +1563,7 @@ paths:
       tags: [groups]
       operationId: transferGroupOwnership
       summary: Make another member the owner
+      description: The previous owner becomes an admin. Transferring to yourself is `422`.
       requestBody:
         required: true
         content:
@@ -1517,6 +1580,7 @@ paths:
         "401": { $ref: "#/components/responses/Unauthorized" }
         "403": { $ref: "#/components/responses/Forbidden" }
         "404": { $ref: "#/components/responses/NotFound" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
   /groups/{chat_id}/leave:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -2189,7 +2253,11 @@ components:
         message: { $ref: "#/components/schemas/Message" }
         highlight:
           type: [string, "null"]
-          description: Plain-text excerpt; never HTML.
+          description: |
+            Plain-text excerpt of the matching text or file name; never HTML. The matched words are
+            wrapped in U+E000 (start) and U+E001 (end), characters of the Unicode private use area,
+            so a client can mark them without parsing markup. `null` when the message matched without
+            an excerpt.
     MessageSearchPage:
       type: object
       required: [items, next_cursor]

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.5. Do not edit. */
+/* Generated from api/openapi.yaml 2.0.0-alpha.7. Do not edit. */
 export interface paths {
     "/meta": {
         parameters: {
@@ -990,6 +990,35 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/search/messages": {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Search messages in all my chats
+         * @description Full-text search across every chat the caller is in, newest first. Only chats the caller
+         *     is a member of are searched, messages they deleted for themselves are left out, and every
+         *     hit is checked against the message store before it is returned (a deleted message never
+         *     shows, even when the index lags behind). Edits and deletions reach the results within a
+         *     few seconds.
+         */
+        get: operations["searchAllMessages"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/requests": {
         parameters: {
             query?: never;
@@ -1078,6 +1107,7 @@ export interface paths {
         /**
          * Create a group
          * @description Members whose `group_invites` setting requires approval get an approval request instead of being added.
+         *     If any of them does not allow invitations from the caller at all, nothing is created (`403`).
          */
         post: operations["createGroup"];
         delete?: never;
@@ -1127,7 +1157,10 @@ export interface paths {
             cookie?: never;
         };
         get?: never;
-        /** Set the group avatar from an uploaded attachment */
+        /**
+         * Set the group avatar from an uploaded attachment
+         * @description The attachment must be an image the caller uploaded with purpose `avatar` (`422` otherwise).
+         */
         put: operations["setGroupAvatar"];
         post?: never;
         delete?: never;
@@ -1202,7 +1235,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Make another member the owner */
+        /**
+         * Make another member the owner
+         * @description The previous owner becomes an admin. Transferring to yourself is `422`.
+         */
         post: operations["transferGroupOwnership"];
         delete?: never;
         options?: never;
@@ -1543,7 +1579,12 @@ export interface components {
         };
         SearchHit: {
             message: components["schemas"]["Message"];
-            /** @description Plain-text excerpt; never HTML. */
+            /**
+             * @description Plain-text excerpt of the matching text or file name; never HTML. The matched words are
+             *     wrapped in U+E000 (start) and U+E001 (end), characters of the Unicode private use area,
+             *     so a client can mark them without parsing markup. `null` when the message matched without
+             *     an excerpt.
+             */
             highlight?: string | null;
         };
         MessageSearchPage: {
@@ -3310,6 +3351,7 @@ export interface operations {
             404: components["responses"]["NotFound"];
             422: components["responses"]["ValidationFailed"];
             426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
         };
     };
     listChatMedia: {
@@ -3460,6 +3502,52 @@ export interface operations {
             429: components["responses"]["TooManyRequests"];
         };
     };
+    searchAllMessages: {
+        parameters: {
+            query: {
+                q: string;
+                /** @description Only this chat */
+                chat_id?: components["schemas"]["Id"];
+                /** @description Only messages of this user */
+                sender_id?: components["schemas"]["Id"];
+                type?: "text" | "file" | "voice";
+                /** @description Messages created at or after this time */
+                from?: components["schemas"]["Timestamp"];
+                /** @description Messages created before this time */
+                to?: components["schemas"]["Timestamp"];
+                /** @description Page size */
+                limit?: components["parameters"]["Limit"];
+                /** @description Opaque `next_cursor` of the previous page */
+                after?: components["parameters"]["After"];
+            };
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Matches, newest first */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MessageSearchPage"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["ValidationFailed"];
+            426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     listApprovalRequests: {
         parameters: {
             query?: {
@@ -3622,6 +3710,7 @@ export interface operations {
             };
             400: components["responses"]["BadRequest"];
             401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
             422: components["responses"]["ValidationFailed"];
             426: components["responses"]["ClientOutdated"];
             429: components["responses"]["TooManyRequests"];
@@ -3758,6 +3847,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
+            422: components["responses"]["ValidationFailed"];
             426: components["responses"]["ClientOutdated"];
         };
     };
@@ -3900,6 +3990,7 @@ export interface operations {
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
             404: components["responses"]["NotFound"];
+            422: components["responses"]["ValidationFailed"];
             426: components["responses"]["ClientOutdated"];
         };
     };

package/dist/ws-events.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.5. Do not edit. */
+/* Generated from api/openapi.yaml 2.0.0-alpha.7. Do not edit. */
 
 /**
  * Any WebSocket event, in either direction.

package/dist/ws-events.schema.json

@@ -1178,7 +1178,7 @@
             "string",
             "null"
           ],
-          "description": "Plain-text excerpt; never HTML."
+          "description": "Plain-text excerpt of the matching text or file name; never HTML. The matched words are\nwrapped in U+E000 (start) and U+E001 (end), characters of the Unicode private use area,\nso a client can mark them without parsing markup. `null` when the message matched without\nan excerpt.\n"
         }
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myronsi/messenger-api",
-  "version": "2.0.0-alpha.5.next.46",
+  "version": "2.0.0-alpha.7.next.49",
   "description": "API contract of the Messenger backend: OpenAPI document, WebSocket event schemas and generated TypeScript types",
   "license": "MIT",
   "repository": {