@google-apps/chat 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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

@@ -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) |

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

@@ -269,6 +269,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).

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/space.proto

@@ -103,6 +103,16 @@ message Space {
     string guidelines = 2;
   }
 
+  // Represents the count of memberships of a space, grouped into categories.
+  message MembershipCount {
+    // Count of human users that have directly joined the space, not counting
+    // users joined by having membership in a joined group.
+    int32 joined_direct_human_user_count = 4;
+
+    // Count of all groups that have directly joined the space.
+    int32 joined_group_count = 5;
+  }
+
   // Represents the [access
   // setting](https://support.google.com/chat/answer/11971020) of the space.
   message AccessSettings {
@@ -218,6 +228,10 @@ message Space {
     (google.api.field_behavior) = OPTIONAL
   ];
 
+  // Output only. Timestamp of the last message in the space.
+  google.protobuf.Timestamp last_active_time = 18
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // Output only. For direct message (DM) spaces with a Chat app, whether the
   // space was created by a Google Workspace administrator. Administrators can
   // install and set up a direct message with a Chat app on behalf of users in
@@ -226,6 +240,12 @@ message Space {
   // To support admin install, your Chat app must feature direct messaging.
   bool admin_installed = 19 [(google.api.field_behavior) = OUTPUT_ONLY];
 
+  // Output only. The count of joined memberships grouped by member type.
+  // Populated when the `space_type` is `SPACE`, `DIRECT_MESSAGE` or
+  // `GROUP_CHAT`.
+  MembershipCount membership_count = 20
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // Optional. Specifies the [access
   // setting](https://support.google.com/chat/answer/11971020) of the space.
   // Only populated when the `space_type` is `SPACE`.
@@ -318,6 +338,17 @@ message GetSpaceRequest {
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
   ];
+
+  // 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.spaces` or `chat.admin.spaces.readonly` [OAuth 2.0
+  // scopes](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  bool use_admin_access = 2;
 }
 
 // A request to get direct message space based on the user resource.
@@ -397,6 +428,165 @@ message UpdateSpaceRequest {
   //  (Warning: mutually exclusive with all other non-permission settings field
   // paths). `permission_settings` is not supported with admin access.
   google.protobuf.FieldMask update_mask = 2;
+
+  // 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.spaces` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // Some `FieldMask` values are not supported using admin access. For details,
+  // see the description of `update_mask`.
+  bool use_admin_access = 3;
+}
+
+// Request to search for a list of spaces based on a query.
+message SearchSpacesRequest {
+  // 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.spaces.readonly` or `chat.admin.spaces`
+  // [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  //
+  // This method currently only supports admin access, thus only `true` is
+  // accepted for this field.
+  bool use_admin_access = 1;
+
+  // The maximum number of spaces to return. The service may return fewer than
+  // this value.
+  //
+  // If unspecified, at most 100 spaces are returned.
+  //
+  // The maximum value is 1000. If you use a value more than 1000, it's
+  // automatically changed to 1000.
+  int32 page_size = 2;
+
+  // A token, received from the previous search spaces call. Provide this
+  // parameter to retrieve the subsequent page.
+  //
+  // When paginating, all other parameters provided should match the call that
+  // provided the page token. Passing different values to the other parameters
+  // might lead to unexpected results.
+  string page_token = 3;
+
+  // Required. A search query.
+  //
+  // You can search by using the following parameters:
+  //
+  // - `create_time`
+  // - `customer`
+  // - `display_name`
+  // - `external_user_allowed`
+  // - `last_active_time`
+  // - `space_history_state`
+  // - `space_type`
+  //
+  // `create_time` and `last_active_time` accept a timestamp in
+  // [RFC-3339](https://www.rfc-editor.org/rfc/rfc3339) format and the supported
+  // comparison operators are: `=`, `<`, `>`, `<=`, `>=`.
+  //
+  // `customer` is required and is used to indicate which customer
+  // to fetch spaces from. `customers/my_customer` is the only supported value.
+  //
+  // `display_name` only accepts the `HAS` (`:`) operator. The text to
+  // match is first tokenized into tokens and each token is prefix-matched
+  // case-insensitively and independently as a substring anywhere in the space's
+  // `display_name`. For example, `Fun Eve` matches `Fun event` or `The
+  // evening was fun`, but not `notFun event` or `even`.
+  //
+  // `external_user_allowed` accepts either `true` or `false`.
+  //
+  // `space_history_state` only accepts values from the [`historyState`]
+  // (https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#Space.HistoryState)
+  // field of a `space` resource.
+  //
+  // `space_type` is required and the only valid value is `SPACE`.
+  //
+  // Across different fields, only `AND` operators are supported. A valid
+  // example is `space_type = "SPACE" AND display_name:"Hello"` and an invalid
+  // example is `space_type = "SPACE" OR display_name:"Hello"`.
+  //
+  // Among the same field,
+  // `space_type` doesn't support `AND` or `OR` operators.
+  // `display_name`, 'space_history_state', and 'external_user_allowed' only
+  // support `OR` operators.
+  // `last_active_time` and `create_time` support both `AND` and `OR` operators.
+  // `AND` can only be used to represent an interval, such as `last_active_time
+  // < "2022-01-01T00:00:00+00:00" AND last_active_time >
+  // "2023-01-01T00:00:00+00:00"`.
+  //
+  // The following example queries are valid:
+  //
+  // ```
+  // customer = "customers/my_customer" AND space_type = "SPACE"
+  //
+  // customer = "customers/my_customer" AND space_type = "SPACE" AND
+  // display_name:"Hello World"
+  //
+  // customer = "customers/my_customer" AND space_type = "SPACE" AND
+  // (last_active_time < "2020-01-01T00:00:00+00:00" OR last_active_time >
+  // "2022-01-01T00:00:00+00:00")
+  //
+  // customer = "customers/my_customer" AND space_type = "SPACE" AND
+  // (display_name:"Hello World" OR display_name:"Fun event") AND
+  // (last_active_time > "2020-01-01T00:00:00+00:00" AND last_active_time <
+  // "2022-01-01T00:00:00+00:00")
+  //
+  // customer = "customers/my_customer" AND space_type = "SPACE" AND
+  // (create_time > "2019-01-01T00:00:00+00:00" AND create_time <
+  // "2020-01-01T00:00:00+00:00") AND (external_user_allowed = "true") AND
+  // (space_history_state = "HISTORY_ON" OR space_history_state = "HISTORY_OFF")
+  // ```
+  string query = 4 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. How the list of spaces is ordered.
+  //
+  // Supported attributes to order by are:
+  //
+  // - `membership_count.joined_direct_human_user_count` — Denotes the count of
+  // human users that have directly joined a space.
+  // - `last_active_time` — Denotes the time when last eligible item is added to
+  // any topic of this space.
+  // - `create_time` — Denotes the time of the space creation.
+  //
+  // Valid ordering operation values are:
+  //
+  // - `ASC` for ascending. Default value.
+  //
+  // - `DESC` for descending.
+  //
+  // The supported syntax are:
+  //
+  // - `membership_count.joined_direct_human_user_count DESC`
+  // - `membership_count.joined_direct_human_user_count ASC`
+  // - `last_active_time DESC`
+  // - `last_active_time ASC`
+  // - `create_time DESC`
+  // - `create_time ASC`
+  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Response with a list of spaces corresponding to the search spaces request.
+message SearchSpacesResponse {
+  // A page of the requested spaces.
+  repeated Space spaces = 1;
+
+  // A token that can be used to retrieve the next page. If this field is empty,
+  // there are no subsequent pages.
+  string next_page_token = 2;
+
+  // The total number of spaces that match the query, across all pages. If the
+  // result is over 10,000 spaces, this value is an estimate.
+  int32 total_size = 3;
 }
 
 // Request for deleting a space.
@@ -408,6 +598,17 @@ message DeleteSpaceRequest {
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
   ];
+
+  // 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.delete` [OAuth 2.0
+  // scope](https://developers.google.com/workspace/chat/authenticate-authorize#chat-api-scopes).
+  bool use_admin_access = 2;
 }
 
 // Request message for completing the import process for a space.