// Copyright 2018 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.cloud.dialogflow.v2beta1;

import "google/api/annotations.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Dialogflow.V2beta1";
option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/v2beta1;dialogflow";
option java_multiple_files = true;
option java_outer_classname = "DocumentProto";
option java_package = "com.google.cloud.dialogflow.v2beta1";
option objc_class_prefix = "DF";


// Manages documents of a knowledge base.
service Documents {
  // Returns the list of all documents of the knowledge base.
  rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) {
    option (google.api.http) = {
      get: "/v2beta1/{parent=projects/*/knowledgeBases/*}/documents"
      additional_bindings {
        get: "/v2beta1/{parent=projects/*/agent/knowledgeBases/*}/documents"
      }
    };
  }

  // Retrieves the specified document.
  rpc GetDocument(GetDocumentRequest) returns (Document) {
    option (google.api.http) = {
      get: "/v2beta1/{name=projects/*/knowledgeBases/*/documents/*}"
      additional_bindings {
        get: "/v2beta1/{name=projects/*/agent/knowledgeBases/*/documents/*}"
      }
    };
  }

  // Creates a new document.
  //
  // Operation <response: [Document][google.cloud.dialogflow.v2beta1.Document],
  //            metadata: [KnowledgeOperationMetadata][google.cloud.dialogflow.v2beta1.KnowledgeOperationMetadata]>
  rpc CreateDocument(CreateDocumentRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v2beta1/{parent=projects/*/knowledgeBases/*}/documents"
      body: "document"
      additional_bindings {
        post: "/v2beta1/{parent=projects/*/agent/knowledgeBases/*}/documents"
        body: "document"
      }
    };
  }

  // Deletes the specified document.
  //
  // Operation <response: [google.protobuf.Empty][google.protobuf.Empty],
  //            metadata: [KnowledgeOperationMetadata][google.cloud.dialogflow.v2beta1.KnowledgeOperationMetadata]>
  rpc DeleteDocument(DeleteDocumentRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v2beta1/{name=projects/*/knowledgeBases/*/documents/*}"
      additional_bindings {
        delete: "/v2beta1/{name=projects/*/agent/knowledgeBases/*/documents/*}"
      }
    };
  }
}

// A document resource.
message Document {
  // The knowledge type of document content.
  enum KnowledgeType {
    // The type is unspecified or arbitrary.
    KNOWLEDGE_TYPE_UNSPECIFIED = 0;

    // The document content contains question and answer pairs as either HTML or
    // CSV. Typical FAQ HTML formats are parsed accurately, but unusual formats
    // may fail to be parsed.
    //
    // CSV must have questions in the first column and answers in the second,
    // with no header. Because of this explicit format, they are always parsed
    // accurately.
    FAQ = 1;

    // Documents for which unstructured text is extracted and used for
    // question answering.
    EXTRACTIVE_QA = 2;
  }

  // The document resource name.
  // The name must be empty when creating a document.
  // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base
  // ID>/documents/<Document ID>`.
  string name = 1;

  // Required. The display name of the document. The name must be 1024 bytes or
  // less; otherwise, the creation request fails.
  string display_name = 2;

  // Required. The MIME type of this document.
  string mime_type = 3;

  // Required. The knowledge type of document content.
  repeated KnowledgeType knowledge_types = 4;

  // Required. The source of this document.
  oneof source {
    // The URI where the file content is located.
    //
    // For documents stored in Google Cloud Storage, these URIs must have
    // the form `gs://<bucket-name>/<object-name>`.
    //
    // NOTE: External URLs must correspond to public webpages, i.e., they must
    // be indexed by Google Search. In particular, URLs for showing documents in
    // Google Cloud Storage (i.e. the URL in your browser) are not supported.
    // Instead use the `gs://` format URI described above.
    string content_uri = 5;

    // The raw content of the document. This field is only permitted for
    // EXTRACTIVE_QA and FAQ knowledge types.
    string content = 6;
  }
}

// Request message for [Documents.ListDocuments][google.cloud.dialogflow.v2beta1.Documents.ListDocuments].
message ListDocumentsRequest {
  // Required. The knowledge base to list all documents for.
  // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base ID>`.
  string parent = 1;

  // Optional. The maximum number of items to return in a single page. By
  // default 10 and at most 100.
  int32 page_size = 2;

  // Optional. The next_page_token value returned from a previous list request.
  string page_token = 3;
}

// Response message for [Documents.ListDocuments][google.cloud.dialogflow.v2beta1.Documents.ListDocuments].
message ListDocumentsResponse {
  // The list of documents.
  repeated Document documents = 1;

  // Token to retrieve the next page of results, or empty if there are no
  // more results in the list.
  string next_page_token = 2;
}

// Request message for [Documents.GetDocument][google.cloud.dialogflow.v2beta1.Documents.GetDocument].
message GetDocumentRequest {
  // Required. The name of the document to retrieve.
  // Format `projects/<Project ID>/knowledgeBases/<Knowledge Base
  // ID>/documents/<Document ID>`.
  string name = 1;
}

// Request message for [Documents.CreateDocument][google.cloud.dialogflow.v2beta1.Documents.CreateDocument].
message CreateDocumentRequest {
  // Required. The knoweldge base to create a document for.
  // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base ID>`.
  string parent = 1;

  // Required. The document to create.
  Document document = 2;
}

// Request message for [Documents.DeleteDocument][google.cloud.dialogflow.v2beta1.Documents.DeleteDocument].
message DeleteDocumentRequest {
  // The name of the document to delete.
  // Format: `projects/<Project ID>/knowledgeBases/<Knowledge Base
  // ID>/documents/<Document ID>`.
  string name = 1;
}

// Metadata in google::longrunning::Operation for Knowledge operations.
message KnowledgeOperationMetadata {
  // States of the operation.
  enum State {
    // State unspecified.
    STATE_UNSPECIFIED = 0;

    // The operation has been created.
    PENDING = 1;

    // The operation is currently running.
    RUNNING = 2;

    // The operation is done, either cancelled or completed.
    DONE = 3;
  }

  // Required. The current state of this operation.
  State state = 1;
}