@google-apps/chat 0.9.0 → 0.10.0

package/CHANGELOG.md

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

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
@@ -224,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) {
@@ -299,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) {
@@ -448,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"
@@ -605,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/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;

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

@@ -121,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;
     }
 
@@ -135,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.
@@ -169,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.
   //
@@ -188,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];
 
@@ -253,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];
@@ -322,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
@@ -379,54 +470,64 @@ 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:
   //
-  // - `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.)
+  // `space_details`: Updates the space's description. Supports up to 150
+  // characters.
   //
-  // - `space_type` (Only supports changing a `GROUP_CHAT` space type to
+  // `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`. 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.
-  //
-  // - `space_details`
+  // argument error.
+  // `space_type` 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.
+  // `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`.
   //
-  // - `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

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.