// Copyright 2024 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.chat.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/chat/v1/history_state.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Apps.Chat.V1";
option go_package = "cloud.google.com/go/chat/apiv1/chatpb;chatpb";
option java_multiple_files = true;
option java_outer_classname = "SpaceProto";
option java_package = "com.google.chat.v1";
option objc_class_prefix = "DYNAPIProto";
option php_namespace = "Google\\Apps\\Chat\\V1";
option ruby_package = "Google::Apps::Chat::V1";

// A space in Google Chat. Spaces are conversations between two or more users
// or 1:1 messages between a user and a Chat app.
message Space {
  option (google.api.resource) = {
    type: "chat.googleapis.com/Space"
    pattern: "spaces/{space}"
  };

  // Deprecated: Use `SpaceType` instead.
  enum Type {
    // Reserved.
    TYPE_UNSPECIFIED = 0;

    // Conversations between two or more humans.
    ROOM = 1;

    // 1:1 Direct Message between a human and a Chat app, where all messages are
    // flat. Note that this doesn't include direct messages between two humans.
    DM = 2;
  }

  // The type of space. Required when creating or updating a space. Output only
  // for other usage.
  enum SpaceType {
    // Reserved.
    SPACE_TYPE_UNSPECIFIED = 0;

    // A place where people send messages, share files, and collaborate.
    // A `SPACE` can include Chat apps.
    SPACE = 1;

    // Group conversations between 3 or more people.
    // A `GROUP_CHAT` can include Chat apps.
    GROUP_CHAT = 2;

    // 1:1 messages between two humans or a human and a Chat app.
    DIRECT_MESSAGE = 3;
  }

  // Specifies the type of threading state in the Chat space.
  enum SpaceThreadingState {
    // Reserved.
    SPACE_THREADING_STATE_UNSPECIFIED = 0;

    // Named spaces that support message threads. When users respond to a
    // message, they can reply in-thread, which keeps their response in the
    // context of the original message.
    THREADED_MESSAGES = 2;

    // Named spaces where the conversation is organized by topic. Topics and
    // their replies are grouped together.
    GROUPED_MESSAGES = 3;

    // Direct messages (DMs) between two people and group conversations between
    // 3 or more people.
    UNTHREADED_MESSAGES = 4;
  }

  // Details about the space including description and rules.
  message SpaceDetails {
    // Optional. A description of the space. For example, describe the space's
    // discussion topic, functional purpose, or participants.
    //
    // Supports up to 150 characters.
    string description = 1;

    // Optional. The space's rules, expectations, and etiquette.
    //
    // Supports up to 5,000 characters.
    string guidelines = 2;
  }

  // Represents the [access
  // setting](https://support.google.com/chat/answer/11971020) of the space.
  message AccessSettings {
    // Represents the access state of the space.
    enum AccessState {
      // Access state is unknown or not supported in this API.
      ACCESS_STATE_UNSPECIFIED = 0;

      // Space is discoverable by added or invited members or groups.
      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.
      DISCOVERABLE = 2;
    }

    // Output only. Indicates the access state of the space.
    AccessState access_state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // 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
    // 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`.
    string audience = 3 [(google.api.field_behavior) = OPTIONAL];
  }

  // Resource name of the space.
  //
  // Format: `spaces/{space}`
  string name = 1;

  // Output only. Deprecated: Use `space_type` instead.
  // The type of a space.
  Type type = 2 [deprecated = true, (google.api.field_behavior) = OUTPUT_ONLY];

  // The type of space. Required when creating a space or updating the space
  // type of a space. Output only for other usage.
  SpaceType space_type = 10;

  // Optional. Whether the space is a DM between a Chat app and a single
  // human.
  bool single_user_bot_dm = 4 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Deprecated: Use `spaceThreadingState` instead.
  // Whether messages are threaded in this space.
  bool threaded = 5
      [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.
  //
  // For direct messages, this field might be empty.
  //
  // Supports up to 128 characters.
  string display_name = 3;

  // Immutable. Whether this space permits any Google Chat user as a member.
  // Input when creating a space in a Google Workspace organization. Omit this
  // field when creating spaces in the following conditions:
  //
  //   * The authenticated user uses a consumer account (unmanaged user
  //     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];

  // Output only. The threading state in the Chat space.
  SpaceThreadingState space_threading_state = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Details about the space including description and rules.
  SpaceDetails space_details = 11;

  // The message history state for messages and threads in this space.
  HistoryState space_history_state = 13;

  // Optional. Whether this space is created in `Import Mode` as part of a data
  // migration into Google Workspace. While spaces are being imported, they
  // aren't visible to users until the import is complete.
  bool import_mode = 16 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Immutable. For spaces created in Chat, the time the space was
  // created. This field is output only, except when used in import mode spaces.
  //
  // For import mode spaces, set this field to the historical timestamp at which
  // the space was created in the source in order to preserve the original
  // creation time.
  //
  // Only populated in the output when `spaceType` is `GROUP_CHAT` or `SPACE`.
  google.protobuf.Timestamp create_time = 17 [
    (google.api.field_behavior) = IMMUTABLE,
    (google.api.field_behavior) = OPTIONAL
  ];

  // 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
  // their organization.
  //
  // To support admin install, your Chat app must feature direct messaging.
  bool admin_installed = 19 [(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`.
  AccessSettings access_settings = 23 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The URI for a user to access the space.
  string space_uri = 25 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// A request to create a named space.
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,
  // try a different `displayName`. An existing space within the Google
  // Workspace organization might already use this display name.
  //
  // 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];

  // Optional. A unique identifier for this request.
  // A random UUID is recommended.
  // Specifying an existing request ID returns the space created with that ID
  // instead of creating a new space.
  // Specifying an existing request ID from the same Chat app with a different
  // authenticated user returns an error.
  string request_id = 2 [(google.api.field_behavior) = OPTIONAL];
}

// A request to list the spaces the caller is a member of.
message ListSpacesRequest {
  // Optional. The maximum number of spaces to return. The service might 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.
  //
  // Negative values return an `INVALID_ARGUMENT` error.
  int32 page_size = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous list spaces call.
  // Provide this parameter to retrieve the subsequent page.
  //
  // When paginating, the filter value should match the call that provided the
  // page token. Passing a different value may lead to unexpected results.
  string page_token = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A query filter.
  //
  // You can filter spaces by the space type
  // ([`space_type`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#spacetype)).
  //
  // To filter by space type, you must specify valid enum value, such as
  // `SPACE` or `GROUP_CHAT` (the `space_type` can't be
  // `SPACE_TYPE_UNSPECIFIED`). To query for multiple space types, use the `OR`
  // operator.
  //
  // For example, the following queries are valid:
  //
  // ```
  // space_type = "SPACE"
  // spaceType = "GROUP_CHAT" OR spaceType = "DIRECT_MESSAGE"
  // ```
  //
  // Invalid queries are rejected by the server with an `INVALID_ARGUMENT`
  // error.
  string filter = 3 [(google.api.field_behavior) = OPTIONAL];
}

// The response for a list spaces request.
message ListSpacesResponse {
  // List of spaces in the requested (or first) page.
  repeated Space spaces = 1;

  // You can send a token as `pageToken` to retrieve the next page of
  // results. If empty, there are no subsequent pages.
  string next_page_token = 2;
}

// A request to return a single space.
message GetSpaceRequest {
  // Required. Resource name of the space, in the form `spaces/{space}`.
  //
  // Format: `spaces/{space}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
  ];
}

// A request to get direct message space based on the user resource.
message FindDirectMessageRequest {
  // Required. Resource name of the user to find direct message with.
  //
  // Format: `users/{user}`, where `{user}` is either the `id` for the
  // [person](https://developers.google.com/people/api/rest/v1/people) from the
  // People API, or the `id` for the
  // [user](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users)
  // in the Directory API. For example, if the People API profile ID is
  // `123456789`, you can find a direct message with that person by using
  // `users/123456789` as the `name`. When [authenticated as a
  // user](https://developers.google.com/workspace/chat/authenticate-authorize-chat-user),
  // you can use the email as an alias for `{user}`. For example,
  // `users/example@gmail.com` where `example@gmail.com` is the email of the
  // Google Chat user.
  string name = 1 [(google.api.field_behavior) = REQUIRED];
}

// A request to update a single space.
message UpdateSpaceRequest {
  // Required. Space with fields to be updated. `Space.name` must be
  // populated in the form of `spaces/{space}`. Only fields
  // specified by `update_mask` are updated.
  Space space = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The updated field paths, comma separated if there are
  // multiple.
  //
  // Currently supported field paths:
  //
  // - `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_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`
  //
  // - `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
  // 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.
  google.protobuf.FieldMask update_mask = 2;
}

// Request for deleting a space.
message DeleteSpaceRequest {
  // Required. Resource name of the space to delete.
  //
  // Format: `spaces/{space}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
  ];
}

// Request message for completing the import process for a space.
message CompleteImportSpaceRequest {
  // Required. Resource name of the import mode space.
  //
  // Format: `spaces/{space}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
  ];
}

// Response message for completing the import process for a space.
message CompleteImportSpaceResponse {
  // The import mode space.
  Space space = 1;
}
