@google-apps/chat 0.8.0 → 0.10.0

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 {
@@ -111,12 +121,16 @@ message Space {
       // Access state is unknown or not supported in this API.
       ACCESS_STATE_UNSPECIFIED = 0;
 
-      // Space is discoverable by added or invited members or groups.
+      // Only users or Google Groups that have been individually added or
+      // invited by other users or Google Workspace administrators can discover
+      // and access the space.
       PRIVATE = 1;
 
-      // Space is discoverable by the selected [target
-      // audience](https://support.google.com/a/answer/9934697), as well as
-      // added or invited members or groups.
+      // A space manager has granted a target audience access to
+      // the space. Users or Google Groups that have been individually added or
+      // invited to the space can also discover and access the space. To learn
+      // more, see [Make a space discoverable to specific
+      // users](https://developers.google.com/workspace/chat/space-target-audience).
       DISCOVERABLE = 2;
     }
 
@@ -125,20 +139,90 @@ message Space {
 
     // Optional. The resource name of the [target
     // audience](https://support.google.com/a/answer/9934697) who can discover
-    // the space, join the space, and preview the messages in the space. For
-    // details, see [Make a space discoverable to a target
+    // the space, join the space, and preview the messages in the space. If
+    // unset, only users or Google Groups who have been individually invited or
+    // added to the space can access it. For details, see [Make a space
+    // discoverable to a target
     // audience](https://developers.google.com/workspace/chat/space-target-audience).
     //
     // Format: `audiences/{audience}`
     //
     // To use the default target audience for the Google Workspace organization,
     // set to `audiences/default`.
+    //
+    // This field is not populated when using the `chat.bot` scope with [app
+    // authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app).
     string audience = 3 [(google.api.field_behavior) = OPTIONAL];
   }
 
+  // Predefined permission settings that you can only specify when creating a
+  // named space. More settings might be added in the future.
+  // For details about permission settings for named spaces, see [Learn about
+  // spaces](https://support.google.com/chat/answer/7659784).
+  enum PredefinedPermissionSettings {
+    // Unspecified. Don't use.
+    PREDEFINED_PERMISSION_SETTINGS_UNSPECIFIED = 0;
+
+    // Setting to make the space a collaboration space where all members can
+    // post messages.
+    COLLABORATION_SPACE = 1;
+
+    // Setting to make the space an announcement space where only space managers
+    // can post messages.
+    ANNOUNCEMENT_SPACE = 2;
+  }
+
+  // [Permission settings](https://support.google.com/chat/answer/13340792)
+  // that you can specify when updating an existing named space.
+  //
+  // To set permission settings when creating a space, specify the
+  // `PredefinedPermissionSettings` field in your request.
+  message PermissionSettings {
+    // Setting for managing members and groups in a space.
+    optional PermissionSetting manage_members_and_groups = 1;
+
+    // Setting for updating space name, avatar, description and guidelines.
+    optional PermissionSetting modify_space_details = 2;
+
+    // Setting for toggling space history on and off.
+    optional PermissionSetting toggle_history = 3;
+
+    // Setting for using @all in a space.
+    optional PermissionSetting use_at_mention_all = 4;
+
+    // Setting for managing apps in a space.
+    optional PermissionSetting manage_apps = 5;
+
+    // Setting for managing webhooks in a space.
+    optional PermissionSetting manage_webhooks = 6;
+
+    // Output only. Setting for posting messages in a space.
+    optional PermissionSetting post_messages = 7
+        [(google.api.field_behavior) = OUTPUT_ONLY];
+
+    // Setting for replying to messages in a space.
+    optional PermissionSetting reply_messages = 8;
+  }
+
+  // Represents a space permission setting.
+  message PermissionSetting {
+    // Whether spaces managers have this permission.
+    bool managers_allowed = 1;
+
+    // Whether non-manager members have this permission.
+    bool members_allowed = 2;
+  }
+
   // Resource name of the space.
   //
   // Format: `spaces/{space}`
+  //
+  // Where `{space}` represents the system-assigned ID for the space. You can
+  // obtain the space ID by calling the
+  // [`spaces.list()`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/list)
+  // method or from the space URL. For example, if the space URL
+  // is `https://mail.google.com/mail/u/0/#chat/space/AAAAAAAAA`, the space ID
+  // is `AAAAAAAAA`.
   string name = 1;
 
   // Output only. Deprecated: Use `space_type` instead.
@@ -159,11 +243,11 @@ message Space {
       [deprecated = true, (google.api.field_behavior) = OUTPUT_ONLY];
 
   // The space's display name. Required when [creating a
-  // space](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/create).
-  // If you receive the error message `ALREADY_EXISTS` when creating a space or
-  // updating the `displayName`, try a different `displayName`. An
-  // existing space within the Google Workspace organization might already use
-  // this display name.
+  // space](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces/create)
+  // with a `spaceType` of `SPACE`. If you receive the error message
+  // `ALREADY_EXISTS` when creating a space or updating the `displayName`, try a
+  // different `displayName`. An existing space within the Google Workspace
+  // organization might already use this display name.
   //
   // For direct messages, this field might be empty.
   //
@@ -178,15 +262,6 @@ message Space {
   //     account). By default, a space created by a consumer account permits any
   //     Google Chat user.
   //
-  //   * The space is used to [import data to Google Chat]
-  //     (https://developers.google.com/chat/api/guides/import-data-overview)
-  //     because import mode spaces must only permit members from the same
-  //     Google Workspace organization. However, as part of the [Google
-  //     Workspace Developer Preview
-  //     Program](https://developers.google.com/workspace/preview), import mode
-  //     spaces can permit any Google Chat user so this field can then be set
-  //     for import mode spaces.
-  //
   // For existing spaces, this field is output only.
   bool external_user_allowed = 8 [(google.api.field_behavior) = IMMUTABLE];
 
@@ -218,6 +293,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 +305,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`.
@@ -233,17 +318,41 @@ message Space {
 
   // Output only. The URI for a user to access the space.
   string space_uri = 25 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Represents the [permission settings]
+  // (https://support.google.com/chat/answer/13340792) of a space. Only
+  // populated when the `space_type` is `SPACE`.
+  oneof space_permission_settings {
+    // Optional. Input only. Predefined space permission settings, input only
+    // when creating a space. If the field is not set, a collaboration space is
+    // created. After you create the space, settings are populated in the
+    // `PermissionSettings` field.
+    PredefinedPermissionSettings predefined_permission_settings = 26 [
+      (google.api.field_behavior) = INPUT_ONLY,
+      (google.api.field_behavior) = OPTIONAL
+    ];
+
+    // Optional. Space permission settings for existing spaces. Input for
+    // updating exact space permission settings, where existing permission
+    // settings are replaced. Output lists current permission settings.
+    PermissionSettings permission_settings = 27
+        [(google.api.field_behavior) = OPTIONAL];
+  }
 }
 
-// A request to create a named space.
+// A request to create a named space with no members.
 message CreateSpaceRequest {
   // Required. The `displayName` and `spaceType` fields must be populated.  Only
   // `SpaceType.SPACE` is supported.
   //
-  // If you receive the error message `ALREADY_EXISTS` when creating a space,
+  // If you receive the error message `ALREADY_EXISTS`,
   // 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),
+  // `SpaceType.GROUP_CHAT` can be used if `importMode` is set to true.
+  //
   // The space `name` is assigned on the server so anything specified in this
   // field will be ignored.
   Space space = 1 [(google.api.field_behavior) = REQUIRED];
@@ -302,6 +411,8 @@ message ListSpacesRequest {
 // The response for a list spaces request.
 message ListSpacesResponse {
   // List of spaces in the requested (or first) page.
+  // Note: The `permissionSettings` field is not returned in the Space
+  // object for list requests.
   repeated Space spaces = 1;
 
   // You can send a token as `pageToken` to retrieve the next page of
@@ -318,6 +429,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.
@@ -348,55 +470,224 @@ message UpdateSpaceRequest {
   // Required. The updated field paths, comma separated if there are
   // multiple.
   //
-  // Currently supported field paths:
+  // You can update the following fields for a space:
+  //
+  // `space_details`: Updates the space's description. Supports up to 150
+  // characters.
   //
-  // - `display_name` (Only supports changing the display name of a space with
-  // the `SPACE` type, or when also including the `space_type` mask to change a
-  // `GROUP_CHAT` space type to `SPACE`. Trying to update the display name of a
-  // `GROUP_CHAT` or a `DIRECT_MESSAGE` space results in an invalid argument
-  // error. If you receive the error message `ALREADY_EXISTS` when updating the
-  // `displayName`, try a different `displayName`. An existing space within the
-  // Google Workspace organization might already use this display name.)
+  // `display_name`: Only supports updating the display name for spaces where
+  // `spaceType` field is `SPACE`.
+  //  If you receive the error message `ALREADY_EXISTS`, try a different
+  //  value. An existing space within the
+  // Google Workspace organization might already use this display name.
   //
-  // - `space_type` (Only supports changing a `GROUP_CHAT` space type to
+  // `space_type`: Only supports changing a `GROUP_CHAT` space type to
   // `SPACE`. Include `display_name` together
   // with `space_type` in the update mask and ensure that the specified space
   // has a non-empty display name and the `SPACE` space type. Including the
   // `space_type` mask and the `SPACE` type in the specified space when updating
   // the display name is optional if the existing space already has the `SPACE`
   // type. Trying to update the space type in other ways results in an invalid
-  // argument error).
-  // `space_type` is not supported with admin access.
+  // argument error.
+  // `space_type` is not supported with `useAdminAccess`.
   //
-  // - `space_details`
+  // `space_history_state`: Updates [space history
+  // settings](https://support.google.com/chat/answer/7664687) by turning
+  // history on or off for the space. Only supported if history settings are
+  // enabled for the Google Workspace organization. To update the
+  // space history state, you must omit all other field masks in your request.
+  // `space_history_state` is not supported with `useAdminAccess`.
   //
-  // - `space_history_state` (Supports [turning history on or off for the
-  // space](https://support.google.com/chat/answer/7664687) if [the organization
-  // allows users to change their history
-  // setting](https://support.google.com/a/answer/7664184).
-  // Warning: mutually exclusive with all other field paths.)
-  // `space_history_state` is not supported with admin access.
-  //
-  // - `access_settings.audience` (Supports changing the [access
+  // `access_settings.audience`: Updates the [access
   // setting](https://support.google.com/chat/answer/11971020) of who can
-  // discover the space, join the space, and preview the messages in space. If
-  // no audience is specified in the access setting, the space's access setting
-  // is updated to private. Warning: mutually exclusive with all other field
-  // paths.)
-  // `access_settings.audience` is not supported with admin access.
-  //
-  // - Developer Preview: Supports changing the [permission
-  // settings](https://support.google.com/chat/answer/13340792) of a space,
-  // supported field paths
-  // include: `permission_settings.manage_members_and_groups`,
-  // `permission_settings.modify_space_details`,
-  // `permission_settings.toggle_history`,
-  // `permission_settings.use_at_mention_all`,
-  // `permission_settings.manage_apps`, `permission_settings.manage_webhooks`,
-  // `permission_settings.reply_messages`
-  //  (Warning: mutually exclusive with all other non-permission settings field
-  // paths). `permission_settings` is not supported with admin access.
+  // discover the space, join the space, and preview the messages in named space
+  // where `spaceType` field is `SPACE`. If the existing space has a
+  // target audience, you can remove the audience and restrict space access by
+  // omitting a value for this field mask. To update access settings for a
+  // space, the authenticating user must be a space manager and omit all other
+  // field masks in your request. You can't update this field if the space is in
+  // [import
+  // mode](https://developers.google.com/workspace/chat/import-data-overview).
+  // To learn more, see [Make a space discoverable to specific
+  // users](https://developers.google.com/workspace/chat/space-target-audience).
+  // `access_settings.audience` is not supported with `useAdminAccess`.
+  //
+  // `permission_settings`: Supports changing the
+  // [permission settings](https://support.google.com/chat/answer/13340792)
+  // of a space.
+  // When updating permission settings, you can only specify
+  // `permissionSettings` field masks; you cannot update other field masks
+  // at the same time. `permissionSettings` is not supported with
+  // `useAdminAccess`.
+  // The supported field masks include:
+  //
+  // - `permission_settings.manageMembersAndGroups`
+  // - `permission_settings.modifySpaceDetails`
+  // - `permission_settings.toggleHistory`
+  // - `permission_settings.useAtMentionAll`
+  // - `permission_settings.manageApps`
+  // - `permission_settings.manageWebhooks`
+  // - `permission_settings.replyMessages`
   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 +699,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.

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

@@ -284,6 +284,8 @@ message ListSpaceEventsRequest {
 // Response message for listing space events.
 message ListSpaceEventsResponse {
   // Results are returned in chronological order (oldest event first).
+  // Note: The `permissionSettings` field is not returned in the Space
+  // object for list requests.
   repeated SpaceEvent space_events = 1;
 
   // Continuation token used to fetch more events.