@google-apps/chat 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.10.0](https://github.com/googleapis/google-cloud-node/compare/chat-v0.9.0...chat-v0.10.0) (2024-10-10)
+
+
+### Features
+
+* [chat] Add doc for permission settings & announcement space support ([#5731](https://github.com/googleapis/google-cloud-node/issues/5731)) ([d5a4a46](https://github.com/googleapis/google-cloud-node/commit/d5a4a469cfc03b75356e33e9659aa720ff6ee71d))
+
+## [0.9.0](https://github.com/googleapis/google-cloud-node/compare/chat-v0.8.0...chat-v0.9.0) (2024-09-13)
+
+
+### Features
+
+* [chat] If you're a domain administrator or a delegated administrator, you can now include the `useAdminAccess` parameter when you call the Chat API with your administrator privileges with the following methods to manage Chat spaces and membership... ([#5675](https://github.com/googleapis/google-cloud-node/issues/5675)) ([4f0945e](https://github.com/googleapis/google-cloud-node/commit/4f0945ef49b10c71039eafc00ac7e93dd6a3ddee))
+
 ## [0.8.0](https://github.com/googleapis/google-cloud-node/compare/chat-v0.7.0...chat-v0.8.0) (2024-09-10)
 
 

package/README.md

@@ -44,7 +44,7 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained].
 1.  [Select or create a Cloud Platform project][projects].
 1.  [Enable billing for your project][billing].
 1.  [Enable the Google Chat API API][enable_api].
-1.  [Set up authentication with a service account][auth] so you can access the
+1.  [Set up authentication][auth] so you can access the
     API from your local workstation.
 
 ### Installing the client library
@@ -148,6 +148,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/google-cloud-node/
 | Chat_service.list_reactions | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-chat/samples/generated/v1/chat_service.list_reactions.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-chat/samples/generated/v1/chat_service.list_reactions.js,packages/google-chat/samples/README.md) |
 | Chat_service.list_space_events | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-chat/samples/generated/v1/chat_service.list_space_events.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-chat/samples/generated/v1/chat_service.list_space_events.js,packages/google-chat/samples/README.md) |
 | Chat_service.list_spaces | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-chat/samples/generated/v1/chat_service.list_spaces.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-chat/samples/generated/v1/chat_service.list_spaces.js,packages/google-chat/samples/README.md) |
+| Chat_service.search_spaces | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-chat/samples/generated/v1/chat_service.search_spaces.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-chat/samples/generated/v1/chat_service.search_spaces.js,packages/google-chat/samples/README.md) |
 | Chat_service.set_up_space | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-chat/samples/generated/v1/chat_service.set_up_space.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-chat/samples/generated/v1/chat_service.set_up_space.js,packages/google-chat/samples/README.md) |
 | Chat_service.update_membership | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-chat/samples/generated/v1/chat_service.update_membership.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-chat/samples/generated/v1/chat_service.update_membership.js,packages/google-chat/samples/README.md) |
 | Chat_service.update_message | [source code](https://github.com/googleapis/google-cloud-node/blob/main/packages/google-chat/samples/generated/v1/chat_service.update_message.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-cloud-node&page=editor&open_in_editor=packages/google-chat/samples/generated/v1/chat_service.update_message.js,packages/google-chat/samples/README.md) |
@@ -223,4 +224,4 @@ See [LICENSE](https://github.com/googleapis/google-cloud-node/blob/main/LICENSE)
 [projects]: https://console.cloud.google.com/project
 [billing]: https://support.google.com/cloud/answer/6293499#enable-billing
 [enable_api]: https://console.cloud.google.com/flows/enableapi?apiid=chat.googleapis.com
-[auth]: https://cloud.google.com/docs/authentication/getting-started
+[auth]: https://cloud.google.com/docs/authentication/external/set-up-adc-local

package/build/protos/google/chat/v1/chat_service.proto

@@ -66,18 +66,30 @@ service ChatService {
       "https://www.googleapis.com/auth/chat.users.readstate,"
       "https://www.googleapis.com/auth/chat.users.readstate.readonly";
 
-  // Creates a message in a Google Chat space. The maximum message size,
-  // including text and cards, is 32,000 bytes. For an example, see [Send a
+  // Creates a message in a Google Chat space. For an example, see [Send a
   // message](https://developers.google.com/workspace/chat/create-messages).
   //
-  // Calling this method requires
-  // [authentication](https://developers.google.com/workspace/chat/authenticate-authorize)
-  // and supports the following authentication types:
+  // The `create()` method requires either user or app authentication. Chat
+  // attributes the message sender differently depending on the type of
+  // authentication that you use in your request.
   //
-  // - For text messages, user authentication or app authentication are
-  // supported.
-  // - For card messages, only app authentication is supported. (Only Chat apps
-  // can create card messages.)
+  // The following image shows how Chat attributes a message when you use app
+  // authentication. Chat displays the Chat app as the message
+  // sender. The content of the message can contain text (`text`), cards
+  // (`cardsV2`), and accessory widgets (`accessoryWidgets`).
+  //
+  // ![Message sent with app
+  // authentication](https://developers.google.com/workspace/chat/images/message-app-auth.svg)
+  //
+  // The following image shows how Chat attributes a message when you use user
+  // authentication. Chat displays the user as the message sender and attributes
+  // the Chat app to the message by displaying its name. The content of message
+  // can only contain text (`text`).
+  //
+  // ![Message sent with user
+  // authentication](https://developers.google.com/workspace/chat/images/message-user-auth.svg)
+  //
+  // The maximum message size, including the message contents, is 32,000 bytes.
   rpc CreateMessage(CreateMessageRequest) returns (Message) {
     option (google.api.http) = {
       post: "/v1/{parent=spaces/*}/messages"
@@ -87,8 +99,12 @@ service ChatService {
   }
 
   // Lists messages in a space that the caller is a member of, including
-  // messages from blocked members and spaces. For an example, see
-  // [List messages](/chat/api/guides/v1/messages/list).
+  // messages from blocked members and spaces. If you list messages from a
+  // space with no messages, the response is an empty object. When using a
+  // REST/HTTP interface, the response contains an empty JSON object, `{}`.
+  // For an example, see
+  // [List
+  // messages](https://developers.google.com/workspace/chat/api/guides/v1/messages/list).
   // Requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
   rpc ListMessages(ListMessagesRequest) returns (ListMessagesResponse) {
@@ -269,6 +285,18 @@ service ChatService {
     option (google.api.method_signature) = "";
   }
 
+  // Returns a list of spaces in a Google Workspace organization based on an
+  // administrator's search. Requires [user
+  // authentication with administrator
+  // privileges](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user#admin-privileges).
+  // In the request, set `use_admin_access` to `true`.
+  rpc SearchSpaces(SearchSpacesRequest) returns (SearchSpacesResponse) {
+    option (google.api.http) = {
+      get: "/v1/spaces:search"
+    };
+    option (google.api.method_signature) = "";
+  }
+
   // Returns details about a space. For an example, see
   // [Get details about a
   // space](https://developers.google.com/workspace/chat/get-spaces).
@@ -287,14 +315,19 @@ service ChatService {
     option (google.api.method_signature) = "name";
   }
 
-  // Creates a named space. Spaces grouped by topics aren't supported. For an
-  // example, see [Create a
+  // Creates a space with no members. Can be used to create a named space.
+  // Spaces grouped by topics aren't supported. For an example, see
+  // [Create a
   // space](https://developers.google.com/workspace/chat/create-spaces).
   //
   //  If you receive the error message `ALREADY_EXISTS` when creating
   //  a space, try a different `displayName`. An existing space within
   //  the Google Workspace organization might already use this display name.
   //
+  // If you're a member of the [Developer Preview
+  // program](https://developers.google.com/workspace/preview), you can create a
+  // group chat in import mode using `spaceType.GROUP_CHAT`.
+  //
   // Requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
   rpc CreateSpace(CreateSpaceRequest) returns (Space) {
@@ -436,40 +469,25 @@ service ChatService {
     };
   }
 
-  // Creates a human membership or app membership for the calling app. Creating
-  // memberships for other apps isn't supported. For an example, see
-  // [Invite or add a user or a Google Chat app to a
-  // space](https://developers.google.com/workspace/chat/create-members).
+  // Creates a membership for the calling Chat app, a user, or a Google Group.
+  // Creating memberships for other Chat apps isn't supported.
   // When creating a membership, if the specified member has their auto-accept
   // policy turned off, then they're invited, and must accept the space
   // invitation before joining. Otherwise, creating a membership adds the member
-  // directly to the specified space. Requires [user
+  // directly to the specified space.
+  // Requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
   //
-  // To specify the member to add, set the `membership.member.name` for the
-  // human or app member, or set the `membership.group_member.name` for the
-  // group member.
-  //
-  // - To add the calling app to a space or a direct message between two human
-  //   users, use `users/app`. Unable to add other
-  //   apps to the space.
-  //
-  // - To add a human user, use `users/{user}`, where `{user}` can be the email
-  // address for the user. For users in the same Workspace organization `{user}`
-  // can also be the `id` for the person from the People API, or the `id` for
-  // the user in the Directory API. For example, if the People API Person
-  // profile ID for `user@example.com` is `123456789`, you can add the user to
-  // the space by setting the `membership.member.name` to
-  // `users/user@example.com` or `users/123456789`.
-  //
-  // - To add or invite a Google group in a named space, use
-  // `groups/{group}`, where `{group}` is the `id` for the group from the Cloud
-  // Identity Groups API. For example, you can use [Cloud Identity Groups lookup
-  // API](https://cloud.google.com/identity/docs/reference/rest/v1/groups/lookup)
-  // to retrieve the ID `123456789` for group email `group@example.com`, then
-  // you can add or invite the group to a named space by setting the
-  // `membership.group_member.name` to `groups/123456789`. Group email is not
-  // supported, and Google groups can only be added as members in named spaces.
+  // For example usage, see:
+  //
+  // - [Invite or add a user to a
+  // space](https://developers.google.com/workspace/chat/create-members#create-user-membership).
+  //
+  // - [Invite or add a Google Group to a
+  // space](https://developers.google.com/workspace/chat/create-members#create-group-membership).
+  //
+  // - [Add the Chat app to a
+  // space](https://developers.google.com/workspace/chat/create-members#create-membership-calling-api).
   rpc CreateMembership(CreateMembershipRequest) returns (Membership) {
     option (google.api.http) = {
       post: "/v1/{parent=spaces/*}/members"
@@ -593,6 +611,9 @@ service ChatService {
   // updated, the server returns the updated `Message` resource in the event
   // payload.
   //
+  // Note: The `permissionSettings` field is not returned in the Space
+  // object of the Space event data for this request.
+  //
   // Requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
   // To get an event, the authenticated user must be a member of the space.

package/build/protos/google/chat/v1/membership.proto

@@ -156,6 +156,21 @@ message CreateMembershipRequest {
   // membership relation for itself, it must use the `chat.memberships.app`
   // scope, set `user.type` to `BOT`, and set `user.name` to `users/app`.
   Membership membership = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.memberships` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Creating app memberships or creating memberships for users outside the
+  // administrator's Google Workspace organization isn't supported using admin
+  // access.
+  bool use_admin_access = 5;
 }
 
 // Request message for updating a membership.
@@ -172,6 +187,17 @@ message UpdateMembershipRequest {
   // - `role`
   google.protobuf.FieldMask update_mask = 2
       [(google.api.field_behavior) = REQUIRED];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.memberships` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  bool use_admin_access = 3;
 }
 
 // Request message for listing memberships.
@@ -215,8 +241,8 @@ message ListMembershipsRequest {
   //
   // To filter by role, set `role` to `ROLE_MEMBER` or `ROLE_MANAGER`.
   //
-  // To filter by type, set `member.type` to `HUMAN` or `BOT`. Developer
-  // Preview: You can also filter for `member.type` using the `!=` operator.
+  // To filter by type, set `member.type` to `HUMAN` or `BOT`. You can also
+  // filter for `member.type` using the `!=` operator.
   //
   // To filter by both role and type, use the `AND` operator. To filter by
   // either role or type, use the `OR` operator.
@@ -263,6 +289,20 @@ message ListMembershipsRequest {
   // Currently requires [user
   // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user).
   bool show_invited = 7 [(google.api.field_behavior) = OPTIONAL];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires either the `chat.admin.memberships.readonly` or
+  // `chat.admin.memberships` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Listing app memberships in a space isn't supported when using admin access.
+  bool use_admin_access = 8;
 }
 
 // Response to list memberships of the space.
@@ -295,6 +335,20 @@ message GetMembershipRequest {
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "chat.googleapis.com/Membership" }
   ];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.memberships` or `chat.admin.memberships.readonly`
+  // [OAuth 2.0
+  // scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Getting app memberships in a space isn't supported when using admin access.
+  bool use_admin_access = 3;
 }
 
 // Request to delete a membership in a space.
@@ -317,4 +371,17 @@ message DeleteMembershipRequest {
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "chat.googleapis.com/Membership" }
   ];
+
+  // When `true`, the method runs using the user's Google Workspace
+  // administrator privileges.
+  //
+  // The calling user must be a Google Workspace administrator with the
+  // [manage chat and spaces conversations
+  // privilege](https://support.google.com/a/answer/13369245).
+  //
+  // Requires the `chat.admin.memberships` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Deleting app memberships in a space isn't supported using admin access.
+  bool use_admin_access = 2;
 }

package/build/protos/google/chat/v1/message.proto

@@ -102,8 +102,8 @@ message Message {
   // user](https://developers.google.com/workspace/chat/format-messages#messages-@mention),
   // or everyone in the space.
   //
-  // To learn about creating text messages, see [Send a text
-  // message](https://developers.google.com/workspace/chat/create-messages#create-text-messages).
+  // To learn about creating text messages, see [Send a
+  // message](https://developers.google.com/workspace/chat/create-messages).
   string text = 4;
 
   // Output only. Contains the message `text` with markups added to communicate
@@ -146,8 +146,8 @@ message Message {
   // user](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user),
   // the messages can't contain cards.
   //
-  // To learn about cards and how to create them, see [Send card
-  // messages](https://developers.google.com/workspace/chat/create-messages#create).
+  // To learn how to create a message that contains cards, see [Send a
+  // message](https://developers.google.com/workspace/chat/create-messages).
   //
   // [Card builder](https://addons.gsuite.google.com/uikit/builder)
   repeated CardWithId cards_v2 = 22;
@@ -214,16 +214,17 @@ message Message {
 
   // Immutable. Input for creating a message, otherwise output only. The user
   // that can view the message. When set, the message is private and only
-  // visible to the specified user and the Chat app. Link previews and
-  // attachments aren't supported for private messages.
+  // visible to the specified user and the Chat app. To include this field in
+  // your request, you must call the Chat API using [app
+  // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app)
+  // and omit the following:
   //
-  // Only Chat apps can send private messages. If your Chat app [authenticates
-  // as a
-  // user](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user)
-  // to send a message, the message can't be private and must omit this field.
+  // * [Attachments](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages.attachments)
+  // * [Accessory
+  // widgets](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages#Message.AccessoryWidget)
   //
-  // For details, see [Send private messages to Google Chat
-  // users](https://developers.google.com/workspace/chat/private-messages).
+  // For details, see [Send a message
+  // privately](https://developers.google.com/workspace/chat/create-messages#private).
   User private_message_viewer = 36 [(google.api.field_behavior) = IMMUTABLE];
 
   // Output only. Information about a deleted message. A message is deleted when
@@ -292,7 +293,7 @@ message Thread {
     pattern: "spaces/{space}/threads/{thread}"
   };
 
-  // Output only. Resource name of the thread.
+  // Resource name of the thread.
   //
   // Example: `spaces/{space}/threads/{thread}`
   string name = 1;