// Copyright 2026 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/protobuf/field_mask.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 = "SectionProto";
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";
option (google.api.resource_definition) = {
  type: "chat.googleapis.com/User"
  pattern: "users/{user}"
};

// Represents a [section](https://support.google.com/chat/answer/16059854) in
// Google Chat. Sections help users organize their spaces. There are two types
// of sections:
//
// 1.  **System Sections:** These are predefined sections managed by Google
// Chat.
//     Their resource names are fixed, and they cannot be created, deleted, or
//     have their `display_name` modified. Examples include:
//     *   `users/{user}/sections/default-direct-messages`
//     *   `users/{user}/sections/default-spaces`
//     *   `users/{user}/sections/default-apps`
//
// 2.  **Custom Sections:** These are sections created and managed by the user.
//     Creating a custom section using `CreateSection` **requires** a
//     `display_name`. Custom sections can be updated using `UpdateSection` and
//     deleted using `DeleteSection`.
message Section {
  option (google.api.resource) = {
    type: "chat.googleapis.com/Section"
    pattern: "users/{user}/sections/{section}"
    plural: "sections"
    singular: "section"
  };

  // Section types.
  enum SectionType {
    // Unspecified section type.
    SECTION_TYPE_UNSPECIFIED = 0;

    // Custom section.
    CUSTOM_SECTION = 1;

    // Default section containing
    // [DIRECT_MESSAGE](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#spacetype)
    // between two human users or
    // [GROUP_CHAT](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#spacetype)
    // spaces that don't belong to any custom section.
    DEFAULT_DIRECT_MESSAGES = 2;

    // Default spaces that don't belong to any custom section.
    DEFAULT_SPACES = 3;

    // Default section containing a user's installed apps.
    DEFAULT_APPS = 6;
  }

  // Identifier. Resource name of the section.
  //
  // For system sections, the section ID is a constant string:
  //
  // - DEFAULT_DIRECT_MESSAGES: `users/{user}/sections/default-direct-messages`
  // - DEFAULT_SPACES: `users/{user}/sections/default-spaces`
  // - DEFAULT_APPS: `users/{user}/sections/default-apps`
  //
  // Format: `users/{user}/sections/{section}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Optional. The section's display name. Only populated for sections of type
  // `CUSTOM_SECTION`. Supports up to 80 characters. Required when creating a
  // `CUSTOM_SECTION`.
  string display_name = 2 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The order of the section in relation to other sections.
  // Sections with a lower `sort_order` value appear before sections with a
  // higher value.
  int32 sort_order = 3;

  // Required. The type of the section.
  SectionType type = 4 [(google.api.field_behavior) = REQUIRED];
}

// A user's defined section item. This is used to represent section items, such
// as spaces, grouped under a section.
message SectionItem {
  option (google.api.resource) = {
    type: "chat.googleapis.com/SectionItem"
    pattern: "users/{user}/sections/{section}/items/{item}"
    plural: "sectionItems"
    singular: "sectionItem"
  };

  // Identifier. The resource name of the section item.
  //
  // Format: `users/{user}/sections/{section}/items/{item}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Required. The section item.
  oneof item {
    // Optional. The space resource name.
    //
    // Format: `spaces/{space}`
    string space = 2 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = { type: "chat.googleapis.com/Space" }
    ];
  }
}

// Request message for creating a section.
message CreateSectionRequest {
  // Required. The parent resource name where the section is created.
  //
  // Format: `users/{user}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/User" }
  ];

  // Required. The section to create.
  Section section = 2 [(google.api.field_behavior) = REQUIRED];
}

// Request message for deleting a section.
// [Developer Preview](https://developers.google.com/workspace/preview).
message DeleteSectionRequest {
  // Required. The name of the section to delete.
  //
  // Format: `users/{user}/sections/{section}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Section" }
  ];
}

// Request message for updating a section.
message UpdateSectionRequest {
  // Required. The section to update.
  Section section = 1 [(google.api.field_behavior) = REQUIRED];

  // Required. The mask to specify which fields to update.
  //
  // Currently supported field paths:
  //
  // - `display_name`
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = REQUIRED];
}

// Request message for listing sections.
message ListSectionsRequest {
  // Required. The parent, which is the user resource name that owns this
  // collection of sections. Only supports listing sections for the calling
  // user. To refer to the calling user, set one of the following:
  //
  // - The `me` alias. For example, `users/me`.
  //
  // - Their Workspace email address. For example, `users/user@example.com`.
  //
  // - Their user id. For example, `users/123456789`.
  //
  // Format: `users/{user}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/User" }
  ];

  // Optional. The maximum number of sections to return. The service may return
  // fewer than this value.
  //
  // If unspecified, at most 10 sections will be returned.
  //
  // The maximum value is 100. If you use a value more than 100, it's
  // automatically changed to 100.
  //
  // Negative values return an `INVALID_ARGUMENT` error.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous list sections call.
  // Provide this 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 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for listing sections.
message ListSectionsResponse {
  // The sections from the specified user.
  repeated Section sections = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// Request message for positioning a section.
message PositionSectionRequest {
  // The position of the section.
  enum Position {
    // Unspecified position.
    POSITION_UNSPECIFIED = 0;

    // Start of the list of sections.
    START = 1;

    // End of the list of sections.
    END = 2;
  }

  // Required. The resource name of the section to position.
  //
  // Format: `users/{user}/sections/{section}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Section" }
  ];

  // Required. The new position of the section.
  oneof position {
    // Optional. The absolute position of the section in the list of sections.
    // The position must be greater than 0. If the position is greater than the
    // number of sections, the section will be appended to the end of the list.
    // This operation inserts the section at the given position and shifts the
    // original section at that position, and those below it, to the next
    // position.
    int32 sort_order = 2 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The relative position of the section in the list of sections.
    Position relative_position = 3 [(google.api.field_behavior) = OPTIONAL];
  }
}

// Response message for positioning a section.
message PositionSectionResponse {
  // The updated section.
  Section section = 1;
}

// Request message for listing section items.
message ListSectionItemsRequest {
  // Required. The parent, which is the section resource name that owns this
  // collection of section items. Only supports listing section items for the
  // calling user.
  //
  // When you're filtering by space, use the wildcard `-` to search across all
  // sections. For example, `users/{user}/sections/-`.
  //
  // Format: `users/{user}/sections/{section}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Section" }
  ];

  // Optional. The maximum number of section items to return. The service may
  // return fewer than this value.
  //
  // If unspecified, at most 10 section items will be returned.
  //
  // The maximum value is 100. If you use a value more than 100, it's
  // automatically changed to 100.
  //
  // Negative values return an `INVALID_ARGUMENT` error.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous list section items call.
  // Provide this 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 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A query filter.
  //
  // Currently only supports filtering by space.
  //
  // For example, `space = spaces/{space}`.
  //
  // Invalid queries are rejected with an `INVALID_ARGUMENT` error.
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for listing section items.
message ListSectionItemsResponse {
  // The section items from the specified section.
  repeated SectionItem section_items = 1;

  // A token, which can be sent as `page_token` to retrieve the next page. If
  // this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}

// Request message for moving a section item across sections.
message MoveSectionItemRequest {
  // Required. The resource name of the section item to move.
  //
  // Format: `users/{user}/sections/{section}/items/{item}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "chat.googleapis.com/SectionItem"
    }
  ];

  // Required. The resource name of the section to move the section item to.
  //
  // Format: `users/{user}/sections/{section}`
  string target_section = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "chat.googleapis.com/Section" }
  ];
}

// Response message for moving a section item.
message MoveSectionItemResponse {
  // The updated section item.
  SectionItem section_item = 1;
}