diff --git a/protos/google/firestore/v1beta1/common.proto b/protos/google/firestore/v1beta1/common.proto new file mode 100644 index 000000000..d6b3dce03 --- /dev/null +++ b/protos/google/firestore/v1beta1/common.proto @@ -0,0 +1,83 @@ +// 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.firestore.v1beta1; + +import "google/api/annotations.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Firestore.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/firestore/v1beta1;firestore"; +option java_multiple_files = true; +option java_outer_classname = "CommonProto"; +option java_package = "com.google.firestore.v1beta1"; +option objc_class_prefix = "GCFS"; +option php_namespace = "Google\\Cloud\\Firestore\\V1beta1"; + + +// A set of field paths on a document. +// Used to restrict a get or update operation on a document to a subset of its +// fields. +// This is different from standard field masks, as this is always scoped to a +// [Document][google.firestore.v1beta1.Document], and takes in account the dynamic nature of [Value][google.firestore.v1beta1.Value]. +message DocumentMask { + // The list of field paths in the mask. See [Document.fields][google.firestore.v1beta1.Document.fields] for a field + // path syntax reference. + repeated string field_paths = 1; +} + +// A precondition on a document, used for conditional operations. +message Precondition { + // The type of precondition. + oneof condition_type { + // When set to `true`, the target document must exist. + // When set to `false`, the target document must not exist. + bool exists = 1; + + // When set, the target document must exist and have been last updated at + // that time. + google.protobuf.Timestamp update_time = 2; + } +} + +// Options for creating a new transaction. +message TransactionOptions { + // Options for a transaction that can be used to read and write documents. + message ReadWrite { + // An optional transaction to retry. + bytes retry_transaction = 1; + } + + // Options for a transaction that can only be used to read documents. + message ReadOnly { + // The consistency mode for this transaction. If not set, defaults to strong + // consistency. + oneof consistency_selector { + // Reads documents at the given time. + // This may not be older than 60 seconds. + google.protobuf.Timestamp read_time = 2; + } + } + + // The mode of the transaction. + oneof mode { + // The transaction can only be used for read operations. + ReadOnly read_only = 2; + + // The transaction can be used for both read and write operations. + ReadWrite read_write = 3; + } +} diff --git a/protos/google/firestore/v1beta1/document.proto b/protos/google/firestore/v1beta1/document.proto new file mode 100644 index 000000000..aaa90516c --- /dev/null +++ b/protos/google/firestore/v1beta1/document.proto @@ -0,0 +1,150 @@ +// 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.firestore.v1beta1; + +import "google/api/annotations.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; +import "google/type/latlng.proto"; + +option csharp_namespace = "Google.Cloud.Firestore.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/firestore/v1beta1;firestore"; +option java_multiple_files = true; +option java_outer_classname = "DocumentProto"; +option java_package = "com.google.firestore.v1beta1"; +option objc_class_prefix = "GCFS"; +option php_namespace = "Google\\Cloud\\Firestore\\V1beta1"; + + +// A Firestore document. +// +// Must not exceed 1 MiB - 4 bytes. +message Document { + // The resource name of the document, for example + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + string name = 1; + + // The document's fields. + // + // The map keys represent field names. + // + // A simple field name contains only characters `a` to `z`, `A` to `Z`, + // `0` to `9`, or `_`, and must not start with `0` to `9`. For example, + // `foo_bar_17`. + // + // Field names matching the regular expression `__.*__` are reserved. Reserved + // field names are forbidden except in certain documented contexts. The map + // keys, represented as UTF-8, must not exceed 1,500 bytes and cannot be + // empty. + // + // Field paths may be used in other contexts to refer to structured fields + // defined here. For `map_value`, the field path is represented by the simple + // or quoted field names of the containing fields, delimited by `.`. For + // example, the structured field + // `"foo" : { map_value: { "x&y" : { string_value: "hello" }}}` would be + // represented by the field path `foo.x&y`. + // + // Within a field path, a quoted field name starts and ends with `` ` `` and + // may contain any character. Some characters, including `` ` ``, must be + // escaped using a `\`. For example, `` `x&y` `` represents `x&y` and + // `` `bak\`tik` `` represents `` bak`tik ``. + map fields = 2; + + // Output only. The time at which the document was created. + // + // This value increases monotonically when a document is deleted then + // recreated. It can also be compared to values from other documents and + // the `read_time` of a query. + google.protobuf.Timestamp create_time = 3; + + // Output only. The time at which the document was last changed. + // + // This value is initially set to the `create_time` then increases + // monotonically with each change to the document. It can also be + // compared to values from other documents and the `read_time` of a query. + google.protobuf.Timestamp update_time = 4; +} + +// A message that can hold any of the supported value types. +message Value { + // Must have a value set. + oneof value_type { + // A null value. + google.protobuf.NullValue null_value = 11; + + // A boolean value. + bool boolean_value = 1; + + // An integer value. + int64 integer_value = 2; + + // A double value. + double double_value = 3; + + // A timestamp value. + // + // Precise only to microseconds. When stored, any additional precision is + // rounded down. + google.protobuf.Timestamp timestamp_value = 10; + + // A string value. + // + // The string, represented as UTF-8, must not exceed 1 MiB - 89 bytes. + // Only the first 1,500 bytes of the UTF-8 representation are considered by + // queries. + string string_value = 17; + + // A bytes value. + // + // Must not exceed 1 MiB - 89 bytes. + // Only the first 1,500 bytes are considered by queries. + bytes bytes_value = 18; + + // A reference to a document. For example: + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + string reference_value = 5; + + // A geo point value representing a point on the surface of Earth. + google.type.LatLng geo_point_value = 8; + + // An array value. + // + // Cannot directly contain another array value, though can contain an + // map which contains another array. + ArrayValue array_value = 9; + + // A map value. + MapValue map_value = 6; + } +} + +// An array value. +message ArrayValue { + // Values in the array. + repeated Value values = 1; +} + +// A map value. +message MapValue { + // The map's fields. + // + // The map keys represent field names. Field names matching the regular + // expression `__.*__` are reserved. Reserved field names are forbidden except + // in certain documented contexts. The map keys, represented as UTF-8, must + // not exceed 1,500 bytes and cannot be empty. + map fields = 1; +} diff --git a/protos/google/firestore/v1beta1/firestore.proto b/protos/google/firestore/v1beta1/firestore.proto new file mode 100644 index 000000000..7b6c8914b --- /dev/null +++ b/protos/google/firestore/v1beta1/firestore.proto @@ -0,0 +1,760 @@ +// 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.firestore.v1beta1; + +import "google/api/annotations.proto"; +import "google/firestore/v1beta1/common.proto"; +import "google/firestore/v1beta1/document.proto"; +import "google/firestore/v1beta1/query.proto"; +import "google/firestore/v1beta1/write.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/timestamp.proto"; +import "google/rpc/status.proto"; + +option csharp_namespace = "Google.Cloud.Firestore.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/firestore/v1beta1;firestore"; +option java_multiple_files = true; +option java_outer_classname = "FirestoreProto"; +option java_package = "com.google.firestore.v1beta1"; +option objc_class_prefix = "GCFS"; +option php_namespace = "Google\\Cloud\\Firestore\\V1beta1"; +// Specification of the Firestore API. + +// The Cloud Firestore service. +// +// This service exposes several types of comparable timestamps: +// +// * `create_time` - The time at which a document was created. Changes only +// when a document is deleted, then re-created. Increases in a strict +// monotonic fashion. +// * `update_time` - The time at which a document was last updated. Changes +// every time a document is modified. Does not change when a write results +// in no modifications. Increases in a strict monotonic fashion. +// * `read_time` - The time at which a particular state was observed. Used +// to denote a consistent snapshot of the database or the time at which a +// Document was observed to not exist. +// * `commit_time` - The time at which the writes in a transaction were +// committed. Any read with an equal or greater `read_time` is guaranteed +// to see the effects of the transaction. +service Firestore { + // Gets a single document. + rpc GetDocument(GetDocumentRequest) returns (Document) { + option (google.api.http) = { + get: "/v1beta1/{name=projects/*/databases/*/documents/*/**}" + }; + } + + // Lists documents. + rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse) { + option (google.api.http) = { + get: "/v1beta1/{parent=projects/*/databases/*/documents/*/**}/{collection_id}" + }; + } + + // Creates a new document. + rpc CreateDocument(CreateDocumentRequest) returns (Document) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/databases/*/documents/**}/{collection_id}" + body: "document" + }; + } + + // Updates or inserts a document. + rpc UpdateDocument(UpdateDocumentRequest) returns (Document) { + option (google.api.http) = { + patch: "/v1beta1/{document.name=projects/*/databases/*/documents/*/**}" + body: "document" + }; + } + + // Deletes a document. + rpc DeleteDocument(DeleteDocumentRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + delete: "/v1beta1/{name=projects/*/databases/*/documents/*/**}" + }; + } + + // Gets multiple documents. + // + // Documents returned by this method are not guaranteed to be returned in the + // same order that they were requested. + rpc BatchGetDocuments(BatchGetDocumentsRequest) returns (stream BatchGetDocumentsResponse) { + option (google.api.http) = { + post: "/v1beta1/{database=projects/*/databases/*}/documents:batchGet" + body: "*" + }; + } + + // Starts a new transaction. + rpc BeginTransaction(BeginTransactionRequest) returns (BeginTransactionResponse) { + option (google.api.http) = { + post: "/v1beta1/{database=projects/*/databases/*}/documents:beginTransaction" + body: "*" + }; + } + + // Commits a transaction, while optionally updating documents. + rpc Commit(CommitRequest) returns (CommitResponse) { + option (google.api.http) = { + post: "/v1beta1/{database=projects/*/databases/*}/documents:commit" + body: "*" + }; + } + + // Rolls back a transaction. + rpc Rollback(RollbackRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { + post: "/v1beta1/{database=projects/*/databases/*}/documents:rollback" + body: "*" + }; + } + + // Runs a query. + rpc RunQuery(RunQueryRequest) returns (stream RunQueryResponse) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/databases/*/documents}:runQuery" + body: "*" + additional_bindings { + post: "/v1beta1/{parent=projects/*/databases/*/documents/*/**}:runQuery" + body: "*" + } + }; + } + + // Streams batches of document updates and deletes, in order. + rpc Write(stream WriteRequest) returns (stream WriteResponse) { + option (google.api.http) = { + post: "/v1beta1/{database=projects/*/databases/*}/documents:write" + body: "*" + }; + } + + // Listens to changes. + rpc Listen(stream ListenRequest) returns (stream ListenResponse) { + option (google.api.http) = { + post: "/v1beta1/{database=projects/*/databases/*}/documents:listen" + body: "*" + }; + } + + // Lists all the collection IDs underneath a document. + rpc ListCollectionIds(ListCollectionIdsRequest) returns (ListCollectionIdsResponse) { + option (google.api.http) = { + post: "/v1beta1/{parent=projects/*/databases/*/documents}:listCollectionIds" + body: "*" + additional_bindings { + post: "/v1beta1/{parent=projects/*/databases/*/documents/*/**}:listCollectionIds" + body: "*" + } + }; + } +} + +// The request for [Firestore.GetDocument][google.firestore.v1beta1.Firestore.GetDocument]. +message GetDocumentRequest { + // The resource name of the Document to get. In the format: + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + string name = 1; + + // The fields to return. If not set, returns all fields. + // + // If the document has a field that is not present in this mask, that field + // will not be returned in the response. + DocumentMask mask = 2; + + // The consistency mode for this transaction. + // If not set, defaults to strong consistency. + oneof consistency_selector { + // Reads the document in a transaction. + bytes transaction = 3; + + // Reads the version of the document at the given time. + // This may not be older than 60 seconds. + google.protobuf.Timestamp read_time = 5; + } +} + +// The request for [Firestore.ListDocuments][google.firestore.v1beta1.Firestore.ListDocuments]. +message ListDocumentsRequest { + // The parent resource name. In the format: + // `projects/{project_id}/databases/{database_id}/documents` or + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + // For example: + // `projects/my-project/databases/my-database/documents` or + // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + string parent = 1; + + // The collection ID, relative to `parent`, to list. For example: `chatrooms` + // or `messages`. + string collection_id = 2; + + // The maximum number of documents to return. + int32 page_size = 3; + + // The `next_page_token` value returned from a previous List request, if any. + string page_token = 4; + + // The order to sort results by. For example: `priority desc, name`. + string order_by = 6; + + // The fields to return. If not set, returns all fields. + // + // If a document has a field that is not present in this mask, that field + // will not be returned in the response. + DocumentMask mask = 7; + + // The consistency mode for this transaction. + // If not set, defaults to strong consistency. + oneof consistency_selector { + // Reads documents in a transaction. + bytes transaction = 8; + + // Reads documents as they were at the given time. + // This may not be older than 60 seconds. + google.protobuf.Timestamp read_time = 10; + } + + // If the list should show missing documents. A missing document is a + // document that does not exist but has sub-documents. These documents will + // be returned with a key but will not have fields, [Document.create_time][google.firestore.v1beta1.Document.create_time], + // or [Document.update_time][google.firestore.v1beta1.Document.update_time] set. + // + // Requests with `show_missing` may not specify `where` or + // `order_by`. + bool show_missing = 12; +} + +// The response for [Firestore.ListDocuments][google.firestore.v1beta1.Firestore.ListDocuments]. +message ListDocumentsResponse { + // The Documents found. + repeated Document documents = 1; + + // The next page token. + string next_page_token = 2; +} + +// The request for [Firestore.CreateDocument][google.firestore.v1beta1.Firestore.CreateDocument]. +message CreateDocumentRequest { + // The parent resource. For example: + // `projects/{project_id}/databases/{database_id}/documents` or + // `projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}` + string parent = 1; + + // The collection ID, relative to `parent`, to list. For example: `chatrooms`. + string collection_id = 2; + + // The client-assigned document ID to use for this document. + // + // Optional. If not specified, an ID will be assigned by the service. + string document_id = 3; + + // The document to create. `name` must not be set. + Document document = 4; + + // The fields to return. If not set, returns all fields. + // + // If the document has a field that is not present in this mask, that field + // will not be returned in the response. + DocumentMask mask = 5; +} + +// The request for [Firestore.UpdateDocument][google.firestore.v1beta1.Firestore.UpdateDocument]. +message UpdateDocumentRequest { + // The updated document. + // Creates the document if it does not already exist. + Document document = 1; + + // The fields to update. + // None of the field paths in the mask may contain a reserved name. + // + // If the document exists on the server and has fields not referenced in the + // mask, they are left unchanged. + // Fields referenced in the mask, but not present in the input document, are + // deleted from the document on the server. + DocumentMask update_mask = 2; + + // The fields to return. If not set, returns all fields. + // + // If the document has a field that is not present in this mask, that field + // will not be returned in the response. + DocumentMask mask = 3; + + // An optional precondition on the document. + // The request will fail if this is set and not met by the target document. + Precondition current_document = 4; +} + +// The request for [Firestore.DeleteDocument][google.firestore.v1beta1.Firestore.DeleteDocument]. +message DeleteDocumentRequest { + // The resource name of the Document to delete. In the format: + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + string name = 1; + + // An optional precondition on the document. + // The request will fail if this is set and not met by the target document. + Precondition current_document = 2; +} + +// The request for [Firestore.BatchGetDocuments][google.firestore.v1beta1.Firestore.BatchGetDocuments]. +message BatchGetDocumentsRequest { + // The database name. In the format: + // `projects/{project_id}/databases/{database_id}`. + string database = 1; + + // The names of the documents to retrieve. In the format: + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + // The request will fail if any of the document is not a child resource of the + // given `database`. Duplicate names will be elided. + repeated string documents = 2; + + // The fields to return. If not set, returns all fields. + // + // If a document has a field that is not present in this mask, that field will + // not be returned in the response. + DocumentMask mask = 3; + + // The consistency mode for this transaction. + // If not set, defaults to strong consistency. + oneof consistency_selector { + // Reads documents in a transaction. + bytes transaction = 4; + + // Starts a new transaction and reads the documents. + // Defaults to a read-only transaction. + // The new transaction ID will be returned as the first response in the + // stream. + TransactionOptions new_transaction = 5; + + // Reads documents as they were at the given time. + // This may not be older than 60 seconds. + google.protobuf.Timestamp read_time = 7; + } +} + +// The streamed response for [Firestore.BatchGetDocuments][google.firestore.v1beta1.Firestore.BatchGetDocuments]. +message BatchGetDocumentsResponse { + // A single result. + // This can be empty if the server is just returning a transaction. + oneof result { + // A document that was requested. + Document found = 1; + + // A document name that was requested but does not exist. In the format: + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + string missing = 2; + } + + // The transaction that was started as part of this request. + // Will only be set in the first response, and only if + // [BatchGetDocumentsRequest.new_transaction][google.firestore.v1beta1.BatchGetDocumentsRequest.new_transaction] was set in the request. + bytes transaction = 3; + + // The time at which the document was read. + // This may be monotically increasing, in this case the previous documents in + // the result stream are guaranteed not to have changed between their + // read_time and this one. + google.protobuf.Timestamp read_time = 4; +} + +// The request for [Firestore.BeginTransaction][google.firestore.v1beta1.Firestore.BeginTransaction]. +message BeginTransactionRequest { + // The database name. In the format: + // `projects/{project_id}/databases/{database_id}`. + string database = 1; + + // The options for the transaction. + // Defaults to a read-write transaction. + TransactionOptions options = 2; +} + +// The response for [Firestore.BeginTransaction][google.firestore.v1beta1.Firestore.BeginTransaction]. +message BeginTransactionResponse { + // The transaction that was started. + bytes transaction = 1; +} + +// The request for [Firestore.Commit][google.firestore.v1beta1.Firestore.Commit]. +message CommitRequest { + // The database name. In the format: + // `projects/{project_id}/databases/{database_id}`. + string database = 1; + + // The writes to apply. + // + // Always executed atomically and in order. + repeated Write writes = 2; + + // If set, applies all writes in this transaction, and commits it. + bytes transaction = 3; +} + +// The response for [Firestore.Commit][google.firestore.v1beta1.Firestore.Commit]. +message CommitResponse { + // The result of applying the writes. + // + // This i-th write result corresponds to the i-th write in the + // request. + repeated WriteResult write_results = 1; + + // The time at which the commit occurred. + google.protobuf.Timestamp commit_time = 2; +} + +// The request for [Firestore.Rollback][google.firestore.v1beta1.Firestore.Rollback]. +message RollbackRequest { + // The database name. In the format: + // `projects/{project_id}/databases/{database_id}`. + string database = 1; + + // The transaction to roll back. + bytes transaction = 2; +} + +// The request for [Firestore.RunQuery][google.firestore.v1beta1.Firestore.RunQuery]. +message RunQueryRequest { + // The parent resource name. In the format: + // `projects/{project_id}/databases/{database_id}/documents` or + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + // For example: + // `projects/my-project/databases/my-database/documents` or + // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + string parent = 1; + + // The query to run. + oneof query_type { + // A structured query. + StructuredQuery structured_query = 2; + } + + // The consistency mode for this transaction. + // If not set, defaults to strong consistency. + oneof consistency_selector { + // Reads documents in a transaction. + bytes transaction = 5; + + // Starts a new transaction and reads the documents. + // Defaults to a read-only transaction. + // The new transaction ID will be returned as the first response in the + // stream. + TransactionOptions new_transaction = 6; + + // Reads documents as they were at the given time. + // This may not be older than 60 seconds. + google.protobuf.Timestamp read_time = 7; + } +} + +// The response for [Firestore.RunQuery][google.firestore.v1beta1.Firestore.RunQuery]. +message RunQueryResponse { + // The transaction that was started as part of this request. + // Can only be set in the first response, and only if + // [RunQueryRequest.new_transaction][google.firestore.v1beta1.RunQueryRequest.new_transaction] was set in the request. + // If set, no other fields will be set in this response. + bytes transaction = 2; + + // A query result. + // Not set when reporting partial progress. + Document document = 1; + + // The time at which the document was read. This may be monotonically + // increasing; in this case, the previous documents in the result stream are + // guaranteed not to have changed between their `read_time` and this one. + // + // If the query returns no results, a response with `read_time` and no + // `document` will be sent, and this represents the time at which the query + // was run. + google.protobuf.Timestamp read_time = 3; + + // The number of results that have been skipped due to an offset between + // the last response and the current response. + int32 skipped_results = 4; +} + +// The request for [Firestore.Write][google.firestore.v1beta1.Firestore.Write]. +// +// The first request creates a stream, or resumes an existing one from a token. +// +// When creating a new stream, the server replies with a response containing +// only an ID and a token, to use in the next request. +// +// When resuming a stream, the server first streams any responses later than the +// given token, then a response containing only an up-to-date token, to use in +// the next request. +message WriteRequest { + // The database name. In the format: + // `projects/{project_id}/databases/{database_id}`. + // This is only required in the first message. + string database = 1; + + // The ID of the write stream to resume. + // This may only be set in the first message. When left empty, a new write + // stream will be created. + string stream_id = 2; + + // The writes to apply. + // + // Always executed atomically and in order. + // This must be empty on the first request. + // This may be empty on the last request. + // This must not be empty on all other requests. + repeated Write writes = 3; + + // A stream token that was previously sent by the server. + // + // The client should set this field to the token from the most recent + // [WriteResponse][google.firestore.v1beta1.WriteResponse] it has received. This acknowledges that the client has + // received responses up to this token. After sending this token, earlier + // tokens may not be used anymore. + // + // The server may close the stream if there are too many unacknowledged + // responses. + // + // Leave this field unset when creating a new stream. To resume a stream at + // a specific point, set this field and the `stream_id` field. + // + // Leave this field unset when creating a new stream. + bytes stream_token = 4; + + // Labels associated with this write request. + map labels = 5; +} + +// The response for [Firestore.Write][google.firestore.v1beta1.Firestore.Write]. +message WriteResponse { + // The ID of the stream. + // Only set on the first message, when a new stream was created. + string stream_id = 1; + + // A token that represents the position of this response in the stream. + // This can be used by a client to resume the stream at this point. + // + // This field is always set. + bytes stream_token = 2; + + // The result of applying the writes. + // + // This i-th write result corresponds to the i-th write in the + // request. + repeated WriteResult write_results = 3; + + // The time at which the commit occurred. + google.protobuf.Timestamp commit_time = 4; +} + +// A request for [Firestore.Listen][google.firestore.v1beta1.Firestore.Listen] +message ListenRequest { + // The database name. In the format: + // `projects/{project_id}/databases/{database_id}`. + string database = 1; + + // The supported target changes. + oneof target_change { + // A target to add to this stream. + Target add_target = 2; + + // The ID of a target to remove from this stream. + int32 remove_target = 3; + } + + // Labels associated with this target change. + map labels = 4; +} + +// The response for [Firestore.Listen][google.firestore.v1beta1.Firestore.Listen]. +message ListenResponse { + // The supported responses. + oneof response_type { + // Targets have changed. + TargetChange target_change = 2; + + // A [Document][google.firestore.v1beta1.Document] has changed. + DocumentChange document_change = 3; + + // A [Document][google.firestore.v1beta1.Document] has been deleted. + DocumentDelete document_delete = 4; + + // A [Document][google.firestore.v1beta1.Document] has been removed from a target (because it is no longer + // relevant to that target). + DocumentRemove document_remove = 6; + + // A filter to apply to the set of documents previously returned for the + // given target. + // + // Returned when documents may have been removed from the given target, but + // the exact documents are unknown. + ExistenceFilter filter = 5; + } +} + +// A specification of a set of documents to listen to. +message Target { + // A target specified by a set of documents names. + message DocumentsTarget { + // The names of the documents to retrieve. In the format: + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + // The request will fail if any of the document is not a child resource of + // the given `database`. Duplicate names will be elided. + repeated string documents = 2; + } + + // A target specified by a query. + message QueryTarget { + // The parent resource name. In the format: + // `projects/{project_id}/databases/{database_id}/documents` or + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + // For example: + // `projects/my-project/databases/my-database/documents` or + // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + string parent = 1; + + // The query to run. + oneof query_type { + // A structured query. + StructuredQuery structured_query = 2; + } + } + + // The type of target to listen to. + oneof target_type { + // A target specified by a query. + QueryTarget query = 2; + + // A target specified by a set of document names. + DocumentsTarget documents = 3; + } + + // When to start listening. + // + // If not specified, all matching Documents are returned before any + // subsequent changes. + oneof resume_type { + // A resume token from a prior [TargetChange][google.firestore.v1beta1.TargetChange] for an identical target. + // + // Using a resume token with a different target is unsupported and may fail. + bytes resume_token = 4; + + // Start listening after a specific `read_time`. + // + // The client must know the state of matching documents at this time. + google.protobuf.Timestamp read_time = 11; + } + + // A client provided target ID. + // + // If not set, the server will assign an ID for the target. + // + // Used for resuming a target without changing IDs. The IDs can either be + // client-assigned or be server-assigned in a previous stream. All targets + // with client provided IDs must be added before adding a target that needs + // a server-assigned id. + int32 target_id = 5; + + // If the target should be removed once it is current and consistent. + bool once = 6; +} + +// Targets being watched have changed. +message TargetChange { + // The type of change. + enum TargetChangeType { + // No change has occurred. Used only to send an updated `resume_token`. + NO_CHANGE = 0; + + // The targets have been added. + ADD = 1; + + // The targets have been removed. + REMOVE = 2; + + // The targets reflect all changes committed before the targets were added + // to the stream. + // + // This will be sent after or with a `read_time` that is greater than or + // equal to the time at which the targets were added. + // + // Listeners can wait for this change if read-after-write semantics + // are desired. + CURRENT = 3; + + // The targets have been reset, and a new initial state for the targets + // will be returned in subsequent changes. + // + // After the initial state is complete, `CURRENT` will be returned even + // if the target was previously indicated to be `CURRENT`. + RESET = 4; + } + + // The type of change that occurred. + TargetChangeType target_change_type = 1; + + // The target IDs of targets that have changed. + // + // If empty, the change applies to all targets. + // + // For `target_change_type=ADD`, the order of the target IDs matches the order + // of the requests to add the targets. This allows clients to unambiguously + // associate server-assigned target IDs with added targets. + // + // For other states, the order of the target IDs is not defined. + repeated int32 target_ids = 2; + + // The error that resulted in this change, if applicable. + google.rpc.Status cause = 3; + + // A token that can be used to resume the stream for the given `target_ids`, + // or all targets if `target_ids` is empty. + // + // Not set on every target change. + bytes resume_token = 4; + + // The consistent `read_time` for the given `target_ids` (omitted when the + // target_ids are not at a consistent snapshot). + // + // The stream is guaranteed to send a `read_time` with `target_ids` empty + // whenever the entire stream reaches a new consistent snapshot. ADD, + // CURRENT, and RESET messages are guaranteed to (eventually) result in a + // new consistent snapshot (while NO_CHANGE and REMOVE messages are not). + // + // For a given stream, `read_time` is guaranteed to be monotonically + // increasing. + google.protobuf.Timestamp read_time = 6; +} + +// The request for [Firestore.ListCollectionIds][google.firestore.v1beta1.Firestore.ListCollectionIds]. +message ListCollectionIdsRequest { + // The parent document. In the format: + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + // For example: + // `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + string parent = 1; + + // The maximum number of results to return. + int32 page_size = 2; + + // A page token. Must be a value from + // [ListCollectionIdsResponse][google.firestore.v1beta1.ListCollectionIdsResponse]. + string page_token = 3; +} + +// The response from [Firestore.ListCollectionIds][google.firestore.v1beta1.Firestore.ListCollectionIds]. +message ListCollectionIdsResponse { + // The collection ids. + repeated string collection_ids = 1; + + // A page token that may be used to continue the list. + string next_page_token = 2; +} diff --git a/protos/google/firestore/v1beta1/query.proto b/protos/google/firestore/v1beta1/query.proto new file mode 100644 index 000000000..02d0aaaab --- /dev/null +++ b/protos/google/firestore/v1beta1/query.proto @@ -0,0 +1,235 @@ +// 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.firestore.v1beta1; + +import "google/api/annotations.proto"; +import "google/firestore/v1beta1/document.proto"; +import "google/protobuf/wrappers.proto"; + +option csharp_namespace = "Google.Cloud.Firestore.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/firestore/v1beta1;firestore"; +option java_multiple_files = true; +option java_outer_classname = "QueryProto"; +option java_package = "com.google.firestore.v1beta1"; +option objc_class_prefix = "GCFS"; +option php_namespace = "Google\\Cloud\\Firestore\\V1beta1"; + + +// A Firestore query. +message StructuredQuery { + // A selection of a collection, such as `messages as m1`. + message CollectionSelector { + // The collection ID. + // When set, selects only collections with this ID. + string collection_id = 2; + + // When false, selects only collections that are immediate children of + // the `parent` specified in the containing `RunQueryRequest`. + // When true, selects all descendant collections. + bool all_descendants = 3; + } + + // A filter. + message Filter { + // The type of filter. + oneof filter_type { + // A composite filter. + CompositeFilter composite_filter = 1; + + // A filter on a document field. + FieldFilter field_filter = 2; + + // A filter that takes exactly one argument. + UnaryFilter unary_filter = 3; + } + } + + // A filter that merges multiple other filters using the given operator. + message CompositeFilter { + // A composite filter operator. + enum Operator { + // Unspecified. This value must not be used. + OPERATOR_UNSPECIFIED = 0; + + // The results are required to satisfy each of the combined filters. + AND = 1; + } + + // The operator for combining multiple filters. + Operator op = 1; + + // The list of filters to combine. + // Must contain at least one filter. + repeated Filter filters = 2; + } + + // A filter on a specific field. + message FieldFilter { + // A field filter operator. + enum Operator { + // Unspecified. This value must not be used. + OPERATOR_UNSPECIFIED = 0; + + // Less than. Requires that the field come first in `order_by`. + LESS_THAN = 1; + + // Less than or equal. Requires that the field come first in `order_by`. + LESS_THAN_OR_EQUAL = 2; + + // Greater than. Requires that the field come first in `order_by`. + GREATER_THAN = 3; + + // Greater than or equal. Requires that the field come first in + // `order_by`. + GREATER_THAN_OR_EQUAL = 4; + + // Equal. + EQUAL = 5; + + // Contains. Requires that the field is an array. + ARRAY_CONTAINS = 7; + } + + // The field to filter by. + FieldReference field = 1; + + // The operator to filter by. + Operator op = 2; + + // The value to compare to. + Value value = 3; + } + + // A filter with a single operand. + message UnaryFilter { + // A unary operator. + enum Operator { + // Unspecified. This value must not be used. + OPERATOR_UNSPECIFIED = 0; + + // Test if a field is equal to NaN. + IS_NAN = 2; + + // Test if an exprestion evaluates to Null. + IS_NULL = 3; + } + + // The unary operator to apply. + Operator op = 1; + + // The argument to the filter. + oneof operand_type { + // The field to which to apply the operator. + FieldReference field = 2; + } + } + + // An order on a field. + message Order { + // The field to order by. + FieldReference field = 1; + + // The direction to order by. Defaults to `ASCENDING`. + Direction direction = 2; + } + + // A reference to a field, such as `max(messages.time) as max_time`. + message FieldReference { + string field_path = 2; + } + + // The projection of document's fields to return. + message Projection { + // The fields to return. + // + // If empty, all fields are returned. To only return the name + // of the document, use `['__name__']`. + repeated FieldReference fields = 2; + } + + // A sort direction. + enum Direction { + // Unspecified. + DIRECTION_UNSPECIFIED = 0; + + // Ascending. + ASCENDING = 1; + + // Descending. + DESCENDING = 2; + } + + // The projection to return. + Projection select = 1; + + // The collections to query. + repeated CollectionSelector from = 2; + + // The filter to apply. + Filter where = 3; + + // The order to apply to the query results. + // + // Firestore guarantees a stable ordering through the following rules: + // + // * Any field required to appear in `order_by`, that is not already + // specified in `order_by`, is appended to the order in field name order + // by default. + // * If an order on `__name__` is not specified, it is appended by default. + // + // Fields are appended with the same sort direction as the last order + // specified, or 'ASCENDING' if no order was specified. For example: + // + // * `SELECT * FROM Foo ORDER BY A` becomes + // `SELECT * FROM Foo ORDER BY A, __name__` + // * `SELECT * FROM Foo ORDER BY A DESC` becomes + // `SELECT * FROM Foo ORDER BY A DESC, __name__ DESC` + // * `SELECT * FROM Foo WHERE A > 1` becomes + // `SELECT * FROM Foo WHERE A > 1 ORDER BY A, __name__` + repeated Order order_by = 4; + + // A starting point for the query results. + Cursor start_at = 7; + + // A end point for the query results. + Cursor end_at = 8; + + // The number of results to skip. + // + // Applies before limit, but after all other constraints. Must be >= 0 if + // specified. + int32 offset = 6; + + // The maximum number of results to return. + // + // Applies after all other constraints. + // Must be >= 0 if specified. + google.protobuf.Int32Value limit = 5; +} + +// A position in a query result set. +message Cursor { + // The values that represent a position, in the order they appear in + // the order by clause of a query. + // + // Can contain fewer values than specified in the order by clause. + repeated Value values = 1; + + // If the position is just before or just after the given values, relative + // to the sort order defined by the query. + bool before = 2; +} diff --git a/protos/google/firestore/v1beta1/write.proto b/protos/google/firestore/v1beta1/write.proto new file mode 100644 index 000000000..9901e3101 --- /dev/null +++ b/protos/google/firestore/v1beta1/write.proto @@ -0,0 +1,214 @@ +// 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.firestore.v1beta1; + +import "google/api/annotations.proto"; +import "google/firestore/v1beta1/common.proto"; +import "google/firestore/v1beta1/document.proto"; +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.Firestore.V1Beta1"; +option go_package = "google.golang.org/genproto/googleapis/firestore/v1beta1;firestore"; +option java_multiple_files = true; +option java_outer_classname = "WriteProto"; +option java_package = "com.google.firestore.v1beta1"; +option objc_class_prefix = "GCFS"; +option php_namespace = "Google\\Cloud\\Firestore\\V1beta1"; + + +// A write on a document. +message Write { + // The operation to execute. + oneof operation { + // A document to write. + Document update = 1; + + // A document name to delete. In the format: + // `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + string delete = 2; + + // Applies a tranformation to a document. + // At most one `transform` per document is allowed in a given request. + // An `update` cannot follow a `transform` on the same document in a given + // request. + DocumentTransform transform = 6; + } + + // The fields to update in this write. + // + // This field can be set only when the operation is `update`. + // If the mask is not set for an `update` and the document exists, any + // existing data will be overwritten. + // If the mask is set and the document on the server has fields not covered by + // the mask, they are left unchanged. + // Fields referenced in the mask, but not present in the input document, are + // deleted from the document on the server. + // The field paths in this mask must not contain a reserved field name. + DocumentMask update_mask = 3; + + // An optional precondition on the document. + // + // The write will fail if this is set and not met by the target document. + Precondition current_document = 4; +} + +// A transformation of a document. +message DocumentTransform { + // A transformation of a field of the document. + message FieldTransform { + // A value that is calculated by the server. + enum ServerValue { + // Unspecified. This value must not be used. + SERVER_VALUE_UNSPECIFIED = 0; + + // The time at which the server processed the request, with millisecond + // precision. + REQUEST_TIME = 1; + } + + // The path of the field. See [Document.fields][google.firestore.v1beta1.Document.fields] for the field path syntax + // reference. + string field_path = 1; + + // The transformation to apply on the field. + oneof transform_type { + // Sets the field to the given server value. + ServerValue set_to_server_value = 2; + + // Append the given elements in order if they are not already present in + // the current field value. + // If the field is not an array, or if the field does not yet exist, it is + // first set to the empty array. + // + // Equivalent numbers of different types (e.g. 3L and 3.0) are + // considered equal when checking if a value is missing. + // NaN is equal to NaN, and Null is equal to Null. + // If the input contains multiple equivalent values, only the first will + // be considered. + // + // The corresponding transform_result will be the null value. + ArrayValue append_missing_elements = 6; + + // Remove all of the given elements from the array in the field. + // If the field is not an array, or if the field does not yet exist, it is + // set to the empty array. + // + // Equivalent numbers of the different types (e.g. 3L and 3.0) are + // considered equal when deciding whether an element should be removed. + // NaN is equal to NaN, and Null is equal to Null. + // This will remove all equivalent values if there are duplicates. + // + // The corresponding transform_result will be the null value. + ArrayValue remove_all_from_array = 7; + } + } + + // The name of the document to transform. + string document = 1; + + // The list of transformations to apply to the fields of the document, in + // order. + // This must not be empty. + repeated FieldTransform field_transforms = 2; +} + +// The result of applying a write. +message WriteResult { + // The last update time of the document after applying the write. Not set + // after a `delete`. + // + // If the write did not actually change the document, this will be the + // previous update_time. + google.protobuf.Timestamp update_time = 1; + + // The results of applying each [DocumentTransform.FieldTransform][google.firestore.v1beta1.DocumentTransform.FieldTransform], in the + // same order. + repeated Value transform_results = 2; +} + +// A [Document][google.firestore.v1beta1.Document] has changed. +// +// May be the result of multiple [writes][google.firestore.v1beta1.Write], including deletes, that +// ultimately resulted in a new value for the [Document][google.firestore.v1beta1.Document]. +// +// Multiple [DocumentChange][google.firestore.v1beta1.DocumentChange] messages may be returned for the same logical +// change, if multiple targets are affected. +message DocumentChange { + // The new state of the [Document][google.firestore.v1beta1.Document]. + // + // If `mask` is set, contains only fields that were updated or added. + Document document = 1; + + // A set of target IDs of targets that match this document. + repeated int32 target_ids = 5; + + // A set of target IDs for targets that no longer match this document. + repeated int32 removed_target_ids = 6; +} + +// A [Document][google.firestore.v1beta1.Document] has been deleted. +// +// May be the result of multiple [writes][google.firestore.v1beta1.Write], including updates, the +// last of which deleted the [Document][google.firestore.v1beta1.Document]. +// +// Multiple [DocumentDelete][google.firestore.v1beta1.DocumentDelete] messages may be returned for the same logical +// delete, if multiple targets are affected. +message DocumentDelete { + // The resource name of the [Document][google.firestore.v1beta1.Document] that was deleted. + string document = 1; + + // A set of target IDs for targets that previously matched this entity. + repeated int32 removed_target_ids = 6; + + // The read timestamp at which the delete was observed. + // + // Greater or equal to the `commit_time` of the delete. + google.protobuf.Timestamp read_time = 4; +} + +// A [Document][google.firestore.v1beta1.Document] has been removed from the view of the targets. +// +// Sent if the document is no longer relevant to a target and is out of view. +// Can be sent instead of a DocumentDelete or a DocumentChange if the server +// can not send the new value of the document. +// +// Multiple [DocumentRemove][google.firestore.v1beta1.DocumentRemove] messages may be returned for the same logical +// write or delete, if multiple targets are affected. +message DocumentRemove { + // The resource name of the [Document][google.firestore.v1beta1.Document] that has gone out of view. + string document = 1; + + // A set of target IDs for targets that previously matched this document. + repeated int32 removed_target_ids = 2; + + // The read timestamp at which the remove was observed. + // + // Greater or equal to the `commit_time` of the change/delete/remove. + google.protobuf.Timestamp read_time = 4; +} + +// A digest of all the documents that match a given target. +message ExistenceFilter { + // The target ID to which this filter applies. + int32 target_id = 1; + + // The total count of documents that match [target_id][google.firestore.v1beta1.ExistenceFilter.target_id]. + // + // If different from the count of documents in the client that match, the + // client must manually determine which documents no longer match the target. + int32 count = 2; +} diff --git a/src/v1beta1/doc/google/firestore/v1beta1/doc_common.js b/src/v1beta1/doc/google/firestore/v1beta1/doc_common.js new file mode 100644 index 000000000..1789033f6 --- /dev/null +++ b/src/v1beta1/doc/google/firestore/v1beta1/doc_common.js @@ -0,0 +1,108 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * A set of field paths on a document. + * Used to restrict a get or update operation on a document to a subset of its + * fields. + * This is different from standard field masks, as this is always scoped to a + * Document, and takes in account the dynamic nature of Value. + * + * @property {string[]} fieldPaths + * The list of field paths in the mask. See Document.fields for a field + * path syntax reference. + * + * @typedef DocumentMask + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.DocumentMask definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/common.proto} + */ +var DocumentMask = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A precondition on a document, used for conditional operations. + * + * @property {boolean} exists + * When set to `true`, the target document must exist. + * When set to `false`, the target document must not exist. + * + * @property {Object} updateTime + * When set, the target document must exist and have been last updated at + * that time. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef Precondition + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.Precondition definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/common.proto} + */ +var Precondition = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Options for creating a new transaction. + * + * @property {Object} readOnly + * The transaction can only be used for read operations. + * + * This object should have the same structure as [ReadOnly]{@link google.firestore.v1beta1.ReadOnly} + * + * @property {Object} readWrite + * The transaction can be used for both read and write operations. + * + * This object should have the same structure as [ReadWrite]{@link google.firestore.v1beta1.ReadWrite} + * + * @typedef TransactionOptions + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.TransactionOptions definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/common.proto} + */ +var TransactionOptions = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * Options for a transaction that can be used to read and write documents. + * + * @property {string} retryTransaction + * An optional transaction to retry. + * + * @typedef ReadWrite + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.TransactionOptions.ReadWrite definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/common.proto} + */ + ReadWrite: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * Options for a transaction that can only be used to read documents. + * + * @property {Object} readTime + * Reads documents at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef ReadOnly + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.TransactionOptions.ReadOnly definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/common.proto} + */ + ReadOnly: { + // This is for documentation. Actual contents will be loaded by gRPC. + } +}; \ No newline at end of file diff --git a/src/v1beta1/doc/google/firestore/v1beta1/doc_document.js b/src/v1beta1/doc/google/firestore/v1beta1/doc_document.js new file mode 100644 index 000000000..35088fdd9 --- /dev/null +++ b/src/v1beta1/doc/google/firestore/v1beta1/doc_document.js @@ -0,0 +1,180 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * A Firestore document. + * + * Must not exceed 1 MiB - 4 bytes. + * + * @property {string} name + * The resource name of the document, for example + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * + * @property {Object.} fields + * The document's fields. + * + * The map keys represent field names. + * + * A simple field name contains only characters `a` to `z`, `A` to `Z`, + * `0` to `9`, or `_`, and must not start with `0` to `9`. For example, + * `foo_bar_17`. + * + * Field names matching the regular expression `__.*__` are reserved. Reserved + * field names are forbidden except in certain documented contexts. The map + * keys, represented as UTF-8, must not exceed 1,500 bytes and cannot be + * empty. + * + * Field paths may be used in other contexts to refer to structured fields + * defined here. For `map_value`, the field path is represented by the simple + * or quoted field names of the containing fields, delimited by `.`. For + * example, the structured field + * `"foo" : { map_value: { "x&y" : { string_value: "hello" }}}` would be + * represented by the field path `foo.x&y`. + * + * Within a field path, a quoted field name starts and ends with `` ` `` and + * may contain any character. Some characters, including `` ` ``, must be + * escaped using a `\`. For example, `` `x&y` `` represents `x&y` and + * `` `bak\`tik` `` represents `` bak`tik ``. + * + * @property {Object} createTime + * Output only. The time at which the document was created. + * + * This value increases monotonically when a document is deleted then + * recreated. It can also be compared to values from other documents and + * the `read_time` of a query. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @property {Object} updateTime + * Output only. The time at which the document was last changed. + * + * This value is initially set to the `create_time` then increases + * monotonically with each change to the document. It can also be + * compared to values from other documents and the `read_time` of a query. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef Document + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.Document definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/document.proto} + */ +var Document = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A message that can hold any of the supported value types. + * + * @property {number} nullValue + * A null value. + * + * The number should be among the values of [NullValue]{@link google.protobuf.NullValue} + * + * @property {boolean} booleanValue + * A boolean value. + * + * @property {number} integerValue + * An integer value. + * + * @property {number} doubleValue + * A double value. + * + * @property {Object} timestampValue + * A timestamp value. + * + * Precise only to microseconds. When stored, any additional precision is + * rounded down. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @property {string} stringValue + * A string value. + * + * The string, represented as UTF-8, must not exceed 1 MiB - 89 bytes. + * Only the first 1,500 bytes of the UTF-8 representation are considered by + * queries. + * + * @property {string} bytesValue + * A bytes value. + * + * Must not exceed 1 MiB - 89 bytes. + * Only the first 1,500 bytes are considered by queries. + * + * @property {string} referenceValue + * A reference to a document. For example: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * + * @property {Object} geoPointValue + * A geo point value representing a point on the surface of Earth. + * + * This object should have the same structure as [LatLng]{@link google.type.LatLng} + * + * @property {Object} arrayValue + * An array value. + * + * Cannot directly contain another array value, though can contain an + * map which contains another array. + * + * This object should have the same structure as [ArrayValue]{@link google.firestore.v1beta1.ArrayValue} + * + * @property {Object} mapValue + * A map value. + * + * This object should have the same structure as [MapValue]{@link google.firestore.v1beta1.MapValue} + * + * @typedef Value + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.Value definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/document.proto} + */ +var Value = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * An array value. + * + * @property {Object[]} values + * Values in the array. + * + * This object should have the same structure as [Value]{@link google.firestore.v1beta1.Value} + * + * @typedef ArrayValue + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.ArrayValue definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/document.proto} + */ +var ArrayValue = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A map value. + * + * @property {Object.} fields + * The map's fields. + * + * The map keys represent field names. Field names matching the regular + * expression `__.*__` are reserved. Reserved field names are forbidden except + * in certain documented contexts. The map keys, represented as UTF-8, must + * not exceed 1,500 bytes and cannot be empty. + * + * @typedef MapValue + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.MapValue definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/document.proto} + */ +var MapValue = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/src/v1beta1/doc/google/firestore/v1beta1/doc_firestore.js b/src/v1beta1/doc/google/firestore/v1beta1/doc_firestore.js new file mode 100644 index 000000000..79a13d8f6 --- /dev/null +++ b/src/v1beta1/doc/google/firestore/v1beta1/doc_firestore.js @@ -0,0 +1,870 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * The request for Firestore.GetDocument. + * + * @property {string} name + * The resource name of the Document to get. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * + * @property {Object} mask + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * + * @property {string} transaction + * Reads the document in a transaction. + * + * @property {Object} readTime + * Reads the version of the document at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef GetDocumentRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.GetDocumentRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var GetDocumentRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.ListDocuments. + * + * @property {string} parent + * The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents` or + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * + * @property {string} collectionId + * The collection ID, relative to `parent`, to list. For example: `chatrooms` + * or `messages`. + * + * @property {number} pageSize + * The maximum number of documents to return. + * + * @property {string} pageToken + * The `next_page_token` value returned from a previous List request, if any. + * + * @property {string} orderBy + * The order to sort results by. For example: `priority desc, name`. + * + * @property {Object} mask + * The fields to return. If not set, returns all fields. + * + * If a document has a field that is not present in this mask, that field + * will not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * + * @property {string} transaction + * Reads documents in a transaction. + * + * @property {Object} readTime + * Reads documents as they were at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @property {boolean} showMissing + * If the list should show missing documents. A missing document is a + * document that does not exist but has sub-documents. These documents will + * be returned with a key but will not have fields, Document.create_time, + * or Document.update_time set. + * + * Requests with `show_missing` may not specify `where` or + * `order_by`. + * + * @typedef ListDocumentsRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.ListDocumentsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var ListDocumentsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for Firestore.ListDocuments. + * + * @property {Object[]} documents + * The Documents found. + * + * This object should have the same structure as [Document]{@link google.firestore.v1beta1.Document} + * + * @property {string} nextPageToken + * The next page token. + * + * @typedef ListDocumentsResponse + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.ListDocumentsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var ListDocumentsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.CreateDocument. + * + * @property {string} parent + * The parent resource. For example: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}` + * + * @property {string} collectionId + * The collection ID, relative to `parent`, to list. For example: `chatrooms`. + * + * @property {string} documentId + * The client-assigned document ID to use for this document. + * + * Optional. If not specified, an ID will be assigned by the service. + * + * @property {Object} document + * The document to create. `name` must not be set. + * + * This object should have the same structure as [Document]{@link google.firestore.v1beta1.Document} + * + * @property {Object} mask + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * + * @typedef CreateDocumentRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.CreateDocumentRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var CreateDocumentRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.UpdateDocument. + * + * @property {Object} document + * The updated document. + * Creates the document if it does not already exist. + * + * This object should have the same structure as [Document]{@link google.firestore.v1beta1.Document} + * + * @property {Object} updateMask + * The fields to update. + * None of the field paths in the mask may contain a reserved name. + * + * If the document exists on the server and has fields not referenced in the + * mask, they are left unchanged. + * Fields referenced in the mask, but not present in the input document, are + * deleted from the document on the server. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * + * @property {Object} mask + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * + * @property {Object} currentDocument + * An optional precondition on the document. + * The request will fail if this is set and not met by the target document. + * + * This object should have the same structure as [Precondition]{@link google.firestore.v1beta1.Precondition} + * + * @typedef UpdateDocumentRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.UpdateDocumentRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var UpdateDocumentRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.DeleteDocument. + * + * @property {string} name + * The resource name of the Document to delete. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * + * @property {Object} currentDocument + * An optional precondition on the document. + * The request will fail if this is set and not met by the target document. + * + * This object should have the same structure as [Precondition]{@link google.firestore.v1beta1.Precondition} + * + * @typedef DeleteDocumentRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.DeleteDocumentRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var DeleteDocumentRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.BatchGetDocuments. + * + * @property {string} database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * + * @property {string[]} documents + * The names of the documents to retrieve. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * The request will fail if any of the document is not a child resource of the + * given `database`. Duplicate names will be elided. + * + * @property {Object} mask + * The fields to return. If not set, returns all fields. + * + * If a document has a field that is not present in this mask, that field will + * not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * + * @property {string} transaction + * Reads documents in a transaction. + * + * @property {Object} newTransaction + * Starts a new transaction and reads the documents. + * Defaults to a read-only transaction. + * The new transaction ID will be returned as the first response in the + * stream. + * + * This object should have the same structure as [TransactionOptions]{@link google.firestore.v1beta1.TransactionOptions} + * + * @property {Object} readTime + * Reads documents as they were at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef BatchGetDocumentsRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.BatchGetDocumentsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var BatchGetDocumentsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The streamed response for Firestore.BatchGetDocuments. + * + * @property {Object} found + * A document that was requested. + * + * This object should have the same structure as [Document]{@link google.firestore.v1beta1.Document} + * + * @property {string} missing + * A document name that was requested but does not exist. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * + * @property {string} transaction + * The transaction that was started as part of this request. + * Will only be set in the first response, and only if + * BatchGetDocumentsRequest.new_transaction was set in the request. + * + * @property {Object} readTime + * The time at which the document was read. + * This may be monotically increasing, in this case the previous documents in + * the result stream are guaranteed not to have changed between their + * read_time and this one. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef BatchGetDocumentsResponse + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.BatchGetDocumentsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var BatchGetDocumentsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.BeginTransaction. + * + * @property {string} database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * + * @property {Object} options + * The options for the transaction. + * Defaults to a read-write transaction. + * + * This object should have the same structure as [TransactionOptions]{@link google.firestore.v1beta1.TransactionOptions} + * + * @typedef BeginTransactionRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.BeginTransactionRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var BeginTransactionRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for Firestore.BeginTransaction. + * + * @property {string} transaction + * The transaction that was started. + * + * @typedef BeginTransactionResponse + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.BeginTransactionResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var BeginTransactionResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.Commit. + * + * @property {string} database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * + * @property {Object[]} writes + * The writes to apply. + * + * Always executed atomically and in order. + * + * This object should have the same structure as [Write]{@link google.firestore.v1beta1.Write} + * + * @property {string} transaction + * If set, applies all writes in this transaction, and commits it. + * + * @typedef CommitRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.CommitRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var CommitRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for Firestore.Commit. + * + * @property {Object[]} writeResults + * The result of applying the writes. + * + * This i-th write result corresponds to the i-th write in the + * request. + * + * This object should have the same structure as [WriteResult]{@link google.firestore.v1beta1.WriteResult} + * + * @property {Object} commitTime + * The time at which the commit occurred. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef CommitResponse + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.CommitResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var CommitResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.Rollback. + * + * @property {string} database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * + * @property {string} transaction + * The transaction to roll back. + * + * @typedef RollbackRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.RollbackRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var RollbackRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.RunQuery. + * + * @property {string} parent + * The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents` or + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * + * @property {Object} structuredQuery + * A structured query. + * + * This object should have the same structure as [StructuredQuery]{@link google.firestore.v1beta1.StructuredQuery} + * + * @property {string} transaction + * Reads documents in a transaction. + * + * @property {Object} newTransaction + * Starts a new transaction and reads the documents. + * Defaults to a read-only transaction. + * The new transaction ID will be returned as the first response in the + * stream. + * + * This object should have the same structure as [TransactionOptions]{@link google.firestore.v1beta1.TransactionOptions} + * + * @property {Object} readTime + * Reads documents as they were at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef RunQueryRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.RunQueryRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var RunQueryRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for Firestore.RunQuery. + * + * @property {string} transaction + * The transaction that was started as part of this request. + * Can only be set in the first response, and only if + * RunQueryRequest.new_transaction was set in the request. + * If set, no other fields will be set in this response. + * + * @property {Object} document + * A query result. + * Not set when reporting partial progress. + * + * This object should have the same structure as [Document]{@link google.firestore.v1beta1.Document} + * + * @property {Object} readTime + * The time at which the document was read. This may be monotonically + * increasing; in this case, the previous documents in the result stream are + * guaranteed not to have changed between their `read_time` and this one. + * + * If the query returns no results, a response with `read_time` and no + * `document` will be sent, and this represents the time at which the query + * was run. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @property {number} skippedResults + * The number of results that have been skipped due to an offset between + * the last response and the current response. + * + * @typedef RunQueryResponse + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.RunQueryResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var RunQueryResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The request for Firestore.Write. + * + * The first request creates a stream, or resumes an existing one from a token. + * + * When creating a new stream, the server replies with a response containing + * only an ID and a token, to use in the next request. + * + * When resuming a stream, the server first streams any responses later than the + * given token, then a response containing only an up-to-date token, to use in + * the next request. + * + * @property {string} database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * This is only required in the first message. + * + * @property {string} streamId + * The ID of the write stream to resume. + * This may only be set in the first message. When left empty, a new write + * stream will be created. + * + * @property {Object[]} writes + * The writes to apply. + * + * Always executed atomically and in order. + * This must be empty on the first request. + * This may be empty on the last request. + * This must not be empty on all other requests. + * + * This object should have the same structure as [Write]{@link google.firestore.v1beta1.Write} + * + * @property {string} streamToken + * A stream token that was previously sent by the server. + * + * The client should set this field to the token from the most recent + * WriteResponse it has received. This acknowledges that the client has + * received responses up to this token. After sending this token, earlier + * tokens may not be used anymore. + * + * The server may close the stream if there are too many unacknowledged + * responses. + * + * Leave this field unset when creating a new stream. To resume a stream at + * a specific point, set this field and the `stream_id` field. + * + * Leave this field unset when creating a new stream. + * + * @property {Object.} labels + * Labels associated with this write request. + * + * @typedef WriteRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.WriteRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var WriteRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for Firestore.Write. + * + * @property {string} streamId + * The ID of the stream. + * Only set on the first message, when a new stream was created. + * + * @property {string} streamToken + * A token that represents the position of this response in the stream. + * This can be used by a client to resume the stream at this point. + * + * This field is always set. + * + * @property {Object[]} writeResults + * The result of applying the writes. + * + * This i-th write result corresponds to the i-th write in the + * request. + * + * This object should have the same structure as [WriteResult]{@link google.firestore.v1beta1.WriteResult} + * + * @property {Object} commitTime + * The time at which the commit occurred. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef WriteResponse + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.WriteResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var WriteResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A request for Firestore.Listen + * + * @property {string} database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * + * @property {Object} addTarget + * A target to add to this stream. + * + * This object should have the same structure as [Target]{@link google.firestore.v1beta1.Target} + * + * @property {number} removeTarget + * The ID of a target to remove from this stream. + * + * @property {Object.} labels + * Labels associated with this target change. + * + * @typedef ListenRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.ListenRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var ListenRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response for Firestore.Listen. + * + * @property {Object} targetChange + * Targets have changed. + * + * This object should have the same structure as [TargetChange]{@link google.firestore.v1beta1.TargetChange} + * + * @property {Object} documentChange + * A Document has changed. + * + * This object should have the same structure as [DocumentChange]{@link google.firestore.v1beta1.DocumentChange} + * + * @property {Object} documentDelete + * A Document has been deleted. + * + * This object should have the same structure as [DocumentDelete]{@link google.firestore.v1beta1.DocumentDelete} + * + * @property {Object} documentRemove + * A Document has been removed from a target (because it is no longer + * relevant to that target). + * + * This object should have the same structure as [DocumentRemove]{@link google.firestore.v1beta1.DocumentRemove} + * + * @property {Object} filter + * A filter to apply to the set of documents previously returned for the + * given target. + * + * Returned when documents may have been removed from the given target, but + * the exact documents are unknown. + * + * This object should have the same structure as [ExistenceFilter]{@link google.firestore.v1beta1.ExistenceFilter} + * + * @typedef ListenResponse + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.ListenResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var ListenResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A specification of a set of documents to listen to. + * + * @property {Object} query + * A target specified by a query. + * + * This object should have the same structure as [QueryTarget]{@link google.firestore.v1beta1.QueryTarget} + * + * @property {Object} documents + * A target specified by a set of document names. + * + * This object should have the same structure as [DocumentsTarget]{@link google.firestore.v1beta1.DocumentsTarget} + * + * @property {string} resumeToken + * A resume token from a prior TargetChange for an identical target. + * + * Using a resume token with a different target is unsupported and may fail. + * + * @property {Object} readTime + * Start listening after a specific `read_time`. + * + * The client must know the state of matching documents at this time. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @property {number} targetId + * A client provided target ID. + * + * If not set, the server will assign an ID for the target. + * + * Used for resuming a target without changing IDs. The IDs can either be + * client-assigned or be server-assigned in a previous stream. All targets + * with client provided IDs must be added before adding a target that needs + * a server-assigned id. + * + * @property {boolean} once + * If the target should be removed once it is current and consistent. + * + * @typedef Target + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.Target definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var Target = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A target specified by a set of documents names. + * + * @property {string[]} documents + * The names of the documents to retrieve. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * The request will fail if any of the document is not a child resource of + * the given `database`. Duplicate names will be elided. + * + * @typedef DocumentsTarget + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.Target.DocumentsTarget definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ + DocumentsTarget: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * A target specified by a query. + * + * @property {string} parent + * The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents` or + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * + * @property {Object} structuredQuery + * A structured query. + * + * This object should have the same structure as [StructuredQuery]{@link google.firestore.v1beta1.StructuredQuery} + * + * @typedef QueryTarget + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.Target.QueryTarget definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ + QueryTarget: { + // This is for documentation. Actual contents will be loaded by gRPC. + } +}; + +/** + * Targets being watched have changed. + * + * @property {number} targetChangeType + * The type of change that occurred. + * + * The number should be among the values of [TargetChangeType]{@link google.firestore.v1beta1.TargetChangeType} + * + * @property {number[]} targetIds + * The target IDs of targets that have changed. + * + * If empty, the change applies to all targets. + * + * For `target_change_type=ADD`, the order of the target IDs matches the order + * of the requests to add the targets. This allows clients to unambiguously + * associate server-assigned target IDs with added targets. + * + * For other states, the order of the target IDs is not defined. + * + * @property {Object} cause + * The error that resulted in this change, if applicable. + * + * This object should have the same structure as [Status]{@link google.rpc.Status} + * + * @property {string} resumeToken + * A token that can be used to resume the stream for the given `target_ids`, + * or all targets if `target_ids` is empty. + * + * Not set on every target change. + * + * @property {Object} readTime + * The consistent `read_time` for the given `target_ids` (omitted when the + * target_ids are not at a consistent snapshot). + * + * The stream is guaranteed to send a `read_time` with `target_ids` empty + * whenever the entire stream reaches a new consistent snapshot. ADD, + * CURRENT, and RESET messages are guaranteed to (eventually) result in a + * new consistent snapshot (while NO_CHANGE and REMOVE messages are not). + * + * For a given stream, `read_time` is guaranteed to be monotonically + * increasing. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef TargetChange + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.TargetChange definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var TargetChange = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * The type of change. + * + * @enum {number} + * @memberof google.firestore.v1beta1 + */ + TargetChangeType: { + + /** + * No change has occurred. Used only to send an updated `resume_token`. + */ + NO_CHANGE: 0, + + /** + * The targets have been added. + */ + ADD: 1, + + /** + * The targets have been removed. + */ + REMOVE: 2, + + /** + * The targets reflect all changes committed before the targets were added + * to the stream. + * + * This will be sent after or with a `read_time` that is greater than or + * equal to the time at which the targets were added. + * + * Listeners can wait for this change if read-after-write semantics + * are desired. + */ + CURRENT: 3, + + /** + * The targets have been reset, and a new initial state for the targets + * will be returned in subsequent changes. + * + * After the initial state is complete, `CURRENT` will be returned even + * if the target was previously indicated to be `CURRENT`. + */ + RESET: 4 + } +}; + +/** + * The request for Firestore.ListCollectionIds. + * + * @property {string} parent + * The parent document. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * + * @property {number} pageSize + * The maximum number of results to return. + * + * @property {string} pageToken + * A page token. Must be a value from + * ListCollectionIdsResponse. + * + * @typedef ListCollectionIdsRequest + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.ListCollectionIdsRequest definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var ListCollectionIdsRequest = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * The response from Firestore.ListCollectionIds. + * + * @property {string[]} collectionIds + * The collection ids. + * + * @property {string} nextPageToken + * A page token that may be used to continue the list. + * + * @typedef ListCollectionIdsResponse + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.ListCollectionIdsResponse definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/firestore.proto} + */ +var ListCollectionIdsResponse = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/src/v1beta1/doc/google/firestore/v1beta1/doc_query.js b/src/v1beta1/doc/google/firestore/v1beta1/doc_query.js new file mode 100644 index 000000000..c5c8f21e4 --- /dev/null +++ b/src/v1beta1/doc/google/firestore/v1beta1/doc_query.js @@ -0,0 +1,391 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * A Firestore query. + * + * @property {Object} select + * The projection to return. + * + * This object should have the same structure as [Projection]{@link google.firestore.v1beta1.Projection} + * + * @property {Object[]} from + * The collections to query. + * + * This object should have the same structure as [CollectionSelector]{@link google.firestore.v1beta1.CollectionSelector} + * + * @property {Object} where + * The filter to apply. + * + * This object should have the same structure as [Filter]{@link google.firestore.v1beta1.Filter} + * + * @property {Object[]} orderBy + * The order to apply to the query results. + * + * Firestore guarantees a stable ordering through the following rules: + * + * * Any field required to appear in `order_by`, that is not already + * specified in `order_by`, is appended to the order in field name order + * by default. + * * If an order on `__name__` is not specified, it is appended by default. + * + * Fields are appended with the same sort direction as the last order + * specified, or 'ASCENDING' if no order was specified. For example: + * + * * `SELECT * FROM Foo ORDER BY A` becomes + * `SELECT * FROM Foo ORDER BY A, __name__` + * * `SELECT * FROM Foo ORDER BY A DESC` becomes + * `SELECT * FROM Foo ORDER BY A DESC, __name__ DESC` + * * `SELECT * FROM Foo WHERE A > 1` becomes + * `SELECT * FROM Foo WHERE A > 1 ORDER BY A, __name__` + * + * This object should have the same structure as [Order]{@link google.firestore.v1beta1.Order} + * + * @property {Object} startAt + * A starting point for the query results. + * + * This object should have the same structure as [Cursor]{@link google.firestore.v1beta1.Cursor} + * + * @property {Object} endAt + * A end point for the query results. + * + * This object should have the same structure as [Cursor]{@link google.firestore.v1beta1.Cursor} + * + * @property {number} offset + * The number of results to skip. + * + * Applies before limit, but after all other constraints. Must be >= 0 if + * specified. + * + * @property {Object} limit + * The maximum number of results to return. + * + * Applies after all other constraints. + * Must be >= 0 if specified. + * + * This object should have the same structure as [Int32Value]{@link google.protobuf.Int32Value} + * + * @typedef StructuredQuery + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.StructuredQuery definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ +var StructuredQuery = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A selection of a collection, such as `messages as m1`. + * + * @property {string} collectionId + * The collection ID. + * When set, selects only collections with this ID. + * + * @property {boolean} allDescendants + * When false, selects only collections that are immediate children of + * the `parent` specified in the containing `RunQueryRequest`. + * When true, selects all descendant collections. + * + * @typedef CollectionSelector + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.StructuredQuery.CollectionSelector definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ + CollectionSelector: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * A filter. + * + * @property {Object} compositeFilter + * A composite filter. + * + * This object should have the same structure as [CompositeFilter]{@link google.firestore.v1beta1.CompositeFilter} + * + * @property {Object} fieldFilter + * A filter on a document field. + * + * This object should have the same structure as [FieldFilter]{@link google.firestore.v1beta1.FieldFilter} + * + * @property {Object} unaryFilter + * A filter that takes exactly one argument. + * + * This object should have the same structure as [UnaryFilter]{@link google.firestore.v1beta1.UnaryFilter} + * + * @typedef Filter + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.StructuredQuery.Filter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ + Filter: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * A filter that merges multiple other filters using the given operator. + * + * @property {number} op + * The operator for combining multiple filters. + * + * The number should be among the values of [Operator]{@link google.firestore.v1beta1.Operator} + * + * @property {Object[]} filters + * The list of filters to combine. + * Must contain at least one filter. + * + * This object should have the same structure as [Filter]{@link google.firestore.v1beta1.Filter} + * + * @typedef CompositeFilter + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.StructuredQuery.CompositeFilter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ + CompositeFilter: { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A composite filter operator. + * + * @enum {number} + * @memberof google.firestore.v1beta1 + */ + Operator: { + + /** + * Unspecified. This value must not be used. + */ + OPERATOR_UNSPECIFIED: 0, + + /** + * The results are required to satisfy each of the combined filters. + */ + AND: 1 + } + }, + + /** + * A filter on a specific field. + * + * @property {Object} field + * The field to filter by. + * + * This object should have the same structure as [FieldReference]{@link google.firestore.v1beta1.FieldReference} + * + * @property {number} op + * The operator to filter by. + * + * The number should be among the values of [Operator]{@link google.firestore.v1beta1.Operator} + * + * @property {Object} value + * The value to compare to. + * + * This object should have the same structure as [Value]{@link google.firestore.v1beta1.Value} + * + * @typedef FieldFilter + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.StructuredQuery.FieldFilter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ + FieldFilter: { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A field filter operator. + * + * @enum {number} + * @memberof google.firestore.v1beta1 + */ + Operator: { + + /** + * Unspecified. This value must not be used. + */ + OPERATOR_UNSPECIFIED: 0, + + /** + * Less than. Requires that the field come first in `order_by`. + */ + LESS_THAN: 1, + + /** + * Less than or equal. Requires that the field come first in `order_by`. + */ + LESS_THAN_OR_EQUAL: 2, + + /** + * Greater than. Requires that the field come first in `order_by`. + */ + GREATER_THAN: 3, + + /** + * Greater than or equal. Requires that the field come first in + * `order_by`. + */ + GREATER_THAN_OR_EQUAL: 4, + + /** + * Equal. + */ + EQUAL: 5, + + /** + * Contains. Requires that the field is an array. + */ + ARRAY_CONTAINS: 7 + } + }, + + /** + * A filter with a single operand. + * + * @property {number} op + * The unary operator to apply. + * + * The number should be among the values of [Operator]{@link google.firestore.v1beta1.Operator} + * + * @property {Object} field + * The field to which to apply the operator. + * + * This object should have the same structure as [FieldReference]{@link google.firestore.v1beta1.FieldReference} + * + * @typedef UnaryFilter + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.StructuredQuery.UnaryFilter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ + UnaryFilter: { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A unary operator. + * + * @enum {number} + * @memberof google.firestore.v1beta1 + */ + Operator: { + + /** + * Unspecified. This value must not be used. + */ + OPERATOR_UNSPECIFIED: 0, + + /** + * Test if a field is equal to NaN. + */ + IS_NAN: 2, + + /** + * Test if an exprestion evaluates to Null. + */ + IS_NULL: 3 + } + }, + + /** + * An order on a field. + * + * @property {Object} field + * The field to order by. + * + * This object should have the same structure as [FieldReference]{@link google.firestore.v1beta1.FieldReference} + * + * @property {number} direction + * The direction to order by. Defaults to `ASCENDING`. + * + * The number should be among the values of [Direction]{@link google.firestore.v1beta1.Direction} + * + * @typedef Order + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.StructuredQuery.Order definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ + Order: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * A reference to a field, such as `max(messages.time) as max_time`. + * + * @property {string} fieldPath + * + * @typedef FieldReference + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.StructuredQuery.FieldReference definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ + FieldReference: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * The projection of document's fields to return. + * + * @property {Object[]} fields + * The fields to return. + * + * If empty, all fields are returned. To only return the name + * of the document, use `['__name__']`. + * + * This object should have the same structure as [FieldReference]{@link google.firestore.v1beta1.FieldReference} + * + * @typedef Projection + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.StructuredQuery.Projection definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ + Projection: { + // This is for documentation. Actual contents will be loaded by gRPC. + }, + + /** + * A sort direction. + * + * @enum {number} + * @memberof google.firestore.v1beta1 + */ + Direction: { + + /** + * Unspecified. + */ + DIRECTION_UNSPECIFIED: 0, + + /** + * Ascending. + */ + ASCENDING: 1, + + /** + * Descending. + */ + DESCENDING: 2 + } +}; + +/** + * A position in a query result set. + * + * @property {Object[]} values + * The values that represent a position, in the order they appear in + * the order by clause of a query. + * + * Can contain fewer values than specified in the order by clause. + * + * This object should have the same structure as [Value]{@link google.firestore.v1beta1.Value} + * + * @property {boolean} before + * If the position is just before or just after the given values, relative + * to the sort order defined by the query. + * + * @typedef Cursor + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.Cursor definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/query.proto} + */ +var Cursor = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/src/v1beta1/doc/google/firestore/v1beta1/doc_write.js b/src/v1beta1/doc/google/firestore/v1beta1/doc_write.js new file mode 100644 index 000000000..85f332fc0 --- /dev/null +++ b/src/v1beta1/doc/google/firestore/v1beta1/doc_write.js @@ -0,0 +1,293 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * A write on a document. + * + * @property {Object} update + * A document to write. + * + * This object should have the same structure as [Document]{@link google.firestore.v1beta1.Document} + * + * @property {string} delete + * A document name to delete. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * + * @property {Object} transform + * Applies a tranformation to a document. + * At most one `transform` per document is allowed in a given request. + * An `update` cannot follow a `transform` on the same document in a given + * request. + * + * This object should have the same structure as [DocumentTransform]{@link google.firestore.v1beta1.DocumentTransform} + * + * @property {Object} updateMask + * The fields to update in this write. + * + * This field can be set only when the operation is `update`. + * If the mask is not set for an `update` and the document exists, any + * existing data will be overwritten. + * If the mask is set and the document on the server has fields not covered by + * the mask, they are left unchanged. + * Fields referenced in the mask, but not present in the input document, are + * deleted from the document on the server. + * The field paths in this mask must not contain a reserved field name. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * + * @property {Object} currentDocument + * An optional precondition on the document. + * + * The write will fail if this is set and not met by the target document. + * + * This object should have the same structure as [Precondition]{@link google.firestore.v1beta1.Precondition} + * + * @typedef Write + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.Write definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/write.proto} + */ +var Write = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A transformation of a document. + * + * @property {string} document + * The name of the document to transform. + * + * @property {Object[]} fieldTransforms + * The list of transformations to apply to the fields of the document, in + * order. + * This must not be empty. + * + * This object should have the same structure as [FieldTransform]{@link google.firestore.v1beta1.FieldTransform} + * + * @typedef DocumentTransform + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.DocumentTransform definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/write.proto} + */ +var DocumentTransform = { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A transformation of a field of the document. + * + * @property {string} fieldPath + * The path of the field. See Document.fields for the field path syntax + * reference. + * + * @property {number} setToServerValue + * Sets the field to the given server value. + * + * The number should be among the values of [ServerValue]{@link google.firestore.v1beta1.ServerValue} + * + * @property {Object} appendMissingElements + * Append the given elements in order if they are not already present in + * the current field value. + * If the field is not an array, or if the field does not yet exist, it is + * first set to the empty array. + * + * Equivalent numbers of different types (e.g. 3L and 3.0) are + * considered equal when checking if a value is missing. + * NaN is equal to NaN, and Null is equal to Null. + * If the input contains multiple equivalent values, only the first will + * be considered. + * + * The corresponding transform_result will be the null value. + * + * This object should have the same structure as [ArrayValue]{@link google.firestore.v1beta1.ArrayValue} + * + * @property {Object} removeAllFromArray + * Remove all of the given elements from the array in the field. + * If the field is not an array, or if the field does not yet exist, it is + * set to the empty array. + * + * Equivalent numbers of the different types (e.g. 3L and 3.0) are + * considered equal when deciding whether an element should be removed. + * NaN is equal to NaN, and Null is equal to Null. + * This will remove all equivalent values if there are duplicates. + * + * The corresponding transform_result will be the null value. + * + * This object should have the same structure as [ArrayValue]{@link google.firestore.v1beta1.ArrayValue} + * + * @typedef FieldTransform + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.DocumentTransform.FieldTransform definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/write.proto} + */ + FieldTransform: { + // This is for documentation. Actual contents will be loaded by gRPC. + + /** + * A value that is calculated by the server. + * + * @enum {number} + * @memberof google.firestore.v1beta1 + */ + ServerValue: { + + /** + * Unspecified. This value must not be used. + */ + SERVER_VALUE_UNSPECIFIED: 0, + + /** + * The time at which the server processed the request, with millisecond + * precision. + */ + REQUEST_TIME: 1 + } + } +}; + +/** + * The result of applying a write. + * + * @property {Object} updateTime + * The last update time of the document after applying the write. Not set + * after a `delete`. + * + * If the write did not actually change the document, this will be the + * previous update_time. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @property {Object[]} transformResults + * The results of applying each DocumentTransform.FieldTransform, in the + * same order. + * + * This object should have the same structure as [Value]{@link google.firestore.v1beta1.Value} + * + * @typedef WriteResult + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.WriteResult definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/write.proto} + */ +var WriteResult = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A Document has changed. + * + * May be the result of multiple writes, including deletes, that + * ultimately resulted in a new value for the Document. + * + * Multiple DocumentChange messages may be returned for the same logical + * change, if multiple targets are affected. + * + * @property {Object} document + * The new state of the Document. + * + * If `mask` is set, contains only fields that were updated or added. + * + * This object should have the same structure as [Document]{@link google.firestore.v1beta1.Document} + * + * @property {number[]} targetIds + * A set of target IDs of targets that match this document. + * + * @property {number[]} removedTargetIds + * A set of target IDs for targets that no longer match this document. + * + * @typedef DocumentChange + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.DocumentChange definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/write.proto} + */ +var DocumentChange = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A Document has been deleted. + * + * May be the result of multiple writes, including updates, the + * last of which deleted the Document. + * + * Multiple DocumentDelete messages may be returned for the same logical + * delete, if multiple targets are affected. + * + * @property {string} document + * The resource name of the Document that was deleted. + * + * @property {number[]} removedTargetIds + * A set of target IDs for targets that previously matched this entity. + * + * @property {Object} readTime + * The read timestamp at which the delete was observed. + * + * Greater or equal to the `commit_time` of the delete. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef DocumentDelete + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.DocumentDelete definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/write.proto} + */ +var DocumentDelete = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A Document has been removed from the view of the targets. + * + * Sent if the document is no longer relevant to a target and is out of view. + * Can be sent instead of a DocumentDelete or a DocumentChange if the server + * can not send the new value of the document. + * + * Multiple DocumentRemove messages may be returned for the same logical + * write or delete, if multiple targets are affected. + * + * @property {string} document + * The resource name of the Document that has gone out of view. + * + * @property {number[]} removedTargetIds + * A set of target IDs for targets that previously matched this document. + * + * @property {Object} readTime + * The read timestamp at which the remove was observed. + * + * Greater or equal to the `commit_time` of the change/delete/remove. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * + * @typedef DocumentRemove + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.DocumentRemove definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/write.proto} + */ +var DocumentRemove = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * A digest of all the documents that match a given target. + * + * @property {number} targetId + * The target ID to which this filter applies. + * + * @property {number} count + * The total count of documents that match target_id. + * + * If different from the count of documents in the client that match, the + * client must manually determine which documents no longer match the target. + * + * @typedef ExistenceFilter + * @memberof google.firestore.v1beta1 + * @see [google.firestore.v1beta1.ExistenceFilter definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/firestore/v1beta1/write.proto} + */ +var ExistenceFilter = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/src/v1beta1/doc/google/protobuf/doc_any.js b/src/v1beta1/doc/google/protobuf/doc_any.js new file mode 100644 index 000000000..c5c5bbafa --- /dev/null +++ b/src/v1beta1/doc/google/protobuf/doc_any.js @@ -0,0 +1,136 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * `Any` contains an arbitrary serialized protocol buffer message along with a + * URL that describes the type of the serialized message. + * + * Protobuf library provides support to pack/unpack Any values in the form + * of utility functions or additional generated methods of the Any type. + * + * Example 1: Pack and unpack a message in C++. + * + * Foo foo = ...; + * Any any; + * any.PackFrom(foo); + * ... + * if (any.UnpackTo(&foo)) { + * ... + * } + * + * Example 2: Pack and unpack a message in Java. + * + * Foo foo = ...; + * Any any = Any.pack(foo); + * ... + * if (any.is(Foo.class)) { + * foo = any.unpack(Foo.class); + * } + * + * Example 3: Pack and unpack a message in Python. + * + * foo = Foo(...) + * any = Any() + * any.Pack(foo) + * ... + * if any.Is(Foo.DESCRIPTOR): + * any.Unpack(foo) + * ... + * + * Example 4: Pack and unpack a message in Go + * + * foo := &pb.Foo{...} + * any, err := ptypes.MarshalAny(foo) + * ... + * foo := &pb.Foo{} + * if err := ptypes.UnmarshalAny(any, foo); err != nil { + * ... + * } + * + * The pack methods provided by protobuf library will by default use + * 'type.googleapis.com/full.type.name' as the type URL and the unpack + * methods only use the fully qualified type name after the last '/' + * in the type URL, for example "foo.bar.com/x/y.z" will yield type + * name "y.z". + * + * + * # JSON + * + * The JSON representation of an `Any` value uses the regular + * representation of the deserialized, embedded message, with an + * additional field `@type` which contains the type URL. Example: + * + * package google.profile; + * message Person { + * string first_name = 1; + * string last_name = 2; + * } + * + * { + * "@type": "type.googleapis.com/google.profile.Person", + * "firstName": , + * "lastName": + * } + * + * If the embedded message type is well-known and has a custom JSON + * representation, that representation will be embedded adding a field + * `value` which holds the custom JSON in addition to the `@type` + * field. Example (for message google.protobuf.Duration): + * + * { + * "@type": "type.googleapis.com/google.protobuf.Duration", + * "value": "1.212s" + * } + * + * @property {string} typeUrl + * A URL/resource name that uniquely identifies the type of the serialized + * protocol buffer message. The last segment of the URL's path must represent + * the fully qualified name of the type (as in + * `path/google.protobuf.Duration`). The name should be in a canonical form + * (e.g., leading "." is not accepted). + * + * In practice, teams usually precompile into the binary all types that they + * expect it to use in the context of Any. However, for URLs which use the + * scheme `http`, `https`, or no scheme, one can optionally set up a type + * server that maps type URLs to message definitions as follows: + * + * * If no scheme is provided, `https` is assumed. + * * An HTTP GET on the URL must yield a google.protobuf.Type + * value in binary format, or produce an error. + * * Applications are allowed to cache lookup results based on the + * URL, or have them precompiled into a binary to avoid any + * lookup. Therefore, binary compatibility needs to be preserved + * on changes to types. (Use versioned type names to manage + * breaking changes.) + * + * Note: this functionality is not currently available in the official + * protobuf release, and it is not used for type URLs beginning with + * type.googleapis.com. + * + * Schemes other than `http`, `https` (or the empty scheme) might be + * used with implementation specific semantics. + * + * @property {string} value + * Must be a valid serialized protocol buffer of the above specified type. + * + * @typedef Any + * @memberof google.protobuf + * @see [google.protobuf.Any definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/any.proto} + */ +var Any = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/src/v1beta1/doc/google/protobuf/doc_empty.js b/src/v1beta1/doc/google/protobuf/doc_empty.js new file mode 100644 index 000000000..5e3640e90 --- /dev/null +++ b/src/v1beta1/doc/google/protobuf/doc_empty.js @@ -0,0 +1,34 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * A generic empty message that you can re-use to avoid defining duplicated + * empty messages in your APIs. A typical example is to use it as the request + * or the response type of an API method. For instance: + * + * service Foo { + * rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); + * } + * + * The JSON representation for `Empty` is empty JSON object `{}`. + * @typedef Empty + * @memberof google.protobuf + * @see [google.protobuf.Empty definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/empty.proto} + */ +var Empty = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/src/v1beta1/doc/google/protobuf/doc_timestamp.js b/src/v1beta1/doc/google/protobuf/doc_timestamp.js new file mode 100644 index 000000000..51d8f40f5 --- /dev/null +++ b/src/v1beta1/doc/google/protobuf/doc_timestamp.js @@ -0,0 +1,115 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * A Timestamp represents a point in time independent of any time zone + * or calendar, represented as seconds and fractions of seconds at + * nanosecond resolution in UTC Epoch time. It is encoded using the + * Proleptic Gregorian Calendar which extends the Gregorian calendar + * backwards to year one. It is encoded assuming all minutes are 60 + * seconds long, i.e. leap seconds are "smeared" so that no leap second + * table is needed for interpretation. Range is from + * 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. + * By restricting to that range, we ensure that we can convert to + * and from RFC 3339 date strings. + * See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). + * + * # Examples + * + * Example 1: Compute Timestamp from POSIX `time()`. + * + * Timestamp timestamp; + * timestamp.set_seconds(time(NULL)); + * timestamp.set_nanos(0); + * + * Example 2: Compute Timestamp from POSIX `gettimeofday()`. + * + * struct timeval tv; + * gettimeofday(&tv, NULL); + * + * Timestamp timestamp; + * timestamp.set_seconds(tv.tv_sec); + * timestamp.set_nanos(tv.tv_usec * 1000); + * + * Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + * + * FILETIME ft; + * GetSystemTimeAsFileTime(&ft); + * UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + * + * // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z + * // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. + * Timestamp timestamp; + * timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); + * timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + * + * Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + * + * long millis = System.currentTimeMillis(); + * + * Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) + * .setNanos((int) ((millis % 1000) * 1000000)).build(); + * + * + * Example 5: Compute Timestamp from current time in Python. + * + * timestamp = Timestamp() + * timestamp.GetCurrentTime() + * + * # JSON Mapping + * + * In JSON format, the Timestamp type is encoded as a string in the + * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the + * format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" + * where {year} is always expressed using four digits while {month}, {day}, + * {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional + * seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), + * are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone + * is required. A proto3 JSON serializer should always use UTC (as indicated by + * "Z") when printing the Timestamp type and a proto3 JSON parser should be + * able to accept both UTC and other timezones (as indicated by an offset). + * + * For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past + * 01:30 UTC on January 15, 2017. + * + * In JavaScript, one can convert a Date object to this format using the + * standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString] + * method. In Python, a standard `datetime.datetime` object can be converted + * to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) + * with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one + * can use the Joda Time's [`ISODateTimeFormat.dateTime()`](https://cloud.google.com + * http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime-- + * ) to obtain a formatter capable of generating timestamps in this format. + * + * @property {number} seconds + * Represents seconds of UTC time since Unix epoch + * 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to + * 9999-12-31T23:59:59Z inclusive. + * + * @property {number} nanos + * Non-negative fractions of a second at nanosecond resolution. Negative + * second values with fractions must still have non-negative nanos values + * that count forward in time. Must be from 0 to 999,999,999 + * inclusive. + * + * @typedef Timestamp + * @memberof google.protobuf + * @see [google.protobuf.Timestamp definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/timestamp.proto} + */ +var Timestamp = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/src/v1beta1/doc/google/protobuf/doc_wrappers.js b/src/v1beta1/doc/google/protobuf/doc_wrappers.js new file mode 100644 index 000000000..791b600ab --- /dev/null +++ b/src/v1beta1/doc/google/protobuf/doc_wrappers.js @@ -0,0 +1,160 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * Wrapper message for `double`. + * + * The JSON representation for `DoubleValue` is JSON number. + * + * @property {number} value + * The double value. + * + * @typedef DoubleValue + * @memberof google.protobuf + * @see [google.protobuf.DoubleValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ +var DoubleValue = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Wrapper message for `float`. + * + * The JSON representation for `FloatValue` is JSON number. + * + * @property {number} value + * The float value. + * + * @typedef FloatValue + * @memberof google.protobuf + * @see [google.protobuf.FloatValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ +var FloatValue = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Wrapper message for `int64`. + * + * The JSON representation for `Int64Value` is JSON string. + * + * @property {number} value + * The int64 value. + * + * @typedef Int64Value + * @memberof google.protobuf + * @see [google.protobuf.Int64Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ +var Int64Value = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Wrapper message for `uint64`. + * + * The JSON representation for `UInt64Value` is JSON string. + * + * @property {number} value + * The uint64 value. + * + * @typedef UInt64Value + * @memberof google.protobuf + * @see [google.protobuf.UInt64Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ +var UInt64Value = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Wrapper message for `int32`. + * + * The JSON representation for `Int32Value` is JSON number. + * + * @property {number} value + * The int32 value. + * + * @typedef Int32Value + * @memberof google.protobuf + * @see [google.protobuf.Int32Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ +var Int32Value = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Wrapper message for `uint32`. + * + * The JSON representation for `UInt32Value` is JSON number. + * + * @property {number} value + * The uint32 value. + * + * @typedef UInt32Value + * @memberof google.protobuf + * @see [google.protobuf.UInt32Value definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ +var UInt32Value = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Wrapper message for `bool`. + * + * The JSON representation for `BoolValue` is JSON `true` and `false`. + * + * @property {boolean} value + * The bool value. + * + * @typedef BoolValue + * @memberof google.protobuf + * @see [google.protobuf.BoolValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ +var BoolValue = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Wrapper message for `string`. + * + * The JSON representation for `StringValue` is JSON string. + * + * @property {string} value + * The string value. + * + * @typedef StringValue + * @memberof google.protobuf + * @see [google.protobuf.StringValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ +var StringValue = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; + +/** + * Wrapper message for `bytes`. + * + * The JSON representation for `BytesValue` is JSON string. + * + * @property {string} value + * The bytes value. + * + * @typedef BytesValue + * @memberof google.protobuf + * @see [google.protobuf.BytesValue definition in proto format]{@link https://github.com/google/protobuf/blob/master/src/google/protobuf/wrappers.proto} + */ +var BytesValue = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/src/v1beta1/doc/google/rpc/doc_status.js b/src/v1beta1/doc/google/rpc/doc_status.js new file mode 100644 index 000000000..7122f1682 --- /dev/null +++ b/src/v1beta1/doc/google/rpc/doc_status.js @@ -0,0 +1,92 @@ +// 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 +// +// https://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. + +// Note: this file is purely for documentation. Any contents are not expected +// to be loaded as the JS file. + +/** + * The `Status` type defines a logical error model that is suitable for different + * programming environments, including REST APIs and RPC APIs. It is used by + * [gRPC](https://github.com/grpc). The error model is designed to be: + * + * - Simple to use and understand for most users + * - Flexible enough to meet unexpected needs + * + * # Overview + * + * The `Status` message contains three pieces of data: error code, error message, + * and error details. The error code should be an enum value of + * google.rpc.Code, but it may accept additional error codes if needed. The + * error message should be a developer-facing English message that helps + * developers *understand* and *resolve* the error. If a localized user-facing + * error message is needed, put the localized message in the error details or + * localize it in the client. The optional error details may contain arbitrary + * information about the error. There is a predefined set of error detail types + * in the package `google.rpc` that can be used for common error conditions. + * + * # Language mapping + * + * The `Status` message is the logical representation of the error model, but it + * is not necessarily the actual wire format. When the `Status` message is + * exposed in different client libraries and different wire protocols, it can be + * mapped differently. For example, it will likely be mapped to some exceptions + * in Java, but more likely mapped to some error codes in C. + * + * # Other uses + * + * The error model and the `Status` message can be used in a variety of + * environments, either with or without APIs, to provide a + * consistent developer experience across different environments. + * + * Example uses of this error model include: + * + * - Partial errors. If a service needs to return partial errors to the client, + * it may embed the `Status` in the normal response to indicate the partial + * errors. + * + * - Workflow errors. A typical workflow has multiple steps. Each step may + * have a `Status` message for error reporting. + * + * - Batch operations. If a client uses batch request and batch response, the + * `Status` message should be used directly inside batch response, one for + * each error sub-response. + * + * - Asynchronous operations. If an API call embeds asynchronous operation + * results in its response, the status of those operations should be + * represented directly using the `Status` message. + * + * - Logging. If some API errors are stored in logs, the message `Status` could + * be used directly after any stripping needed for security/privacy reasons. + * + * @property {number} code + * The status code, which should be an enum value of google.rpc.Code. + * + * @property {string} message + * A developer-facing error message, which should be in English. Any + * user-facing error message should be localized and sent in the + * google.rpc.Status.details field, or localized by the client. + * + * @property {Object[]} details + * A list of messages that carry the error details. There is a common set of + * message types for APIs to use. + * + * This object should have the same structure as [Any]{@link google.protobuf.Any} + * + * @typedef Status + * @memberof google.rpc + * @see [google.rpc.Status definition in proto format]{@link https://github.com/googleapis/googleapis/blob/master/google/rpc/status.proto} + */ +var Status = { + // This is for documentation. Actual contents will be loaded by gRPC. +}; \ No newline at end of file diff --git a/src/v1beta1/firestore_client.js b/src/v1beta1/firestore_client.js new file mode 100644 index 000000000..94afdb4e9 --- /dev/null +++ b/src/v1beta1/firestore_client.js @@ -0,0 +1,1446 @@ +// 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 +// +// https://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. + +'use strict'; + +const gapicConfig = require('./firestore_client_config'); +const gax = require('google-gax'); +const merge = require('lodash.merge'); +const path = require('path'); + +const VERSION = require('../../package.json').version; + +/** + * The Cloud Firestore service. + * + * This service exposes several types of comparable timestamps: + * + * * `create_time` - The time at which a document was created. Changes only + * when a document is deleted, then re-created. Increases in a strict + * monotonic fashion. + * * `update_time` - The time at which a document was last updated. Changes + * every time a document is modified. Does not change when a write results + * in no modifications. Increases in a strict monotonic fashion. + * * `read_time` - The time at which a particular state was observed. Used + * to denote a consistent snapshot of the database or the time at which a + * Document was observed to not exist. + * * `commit_time` - The time at which the writes in a transaction were + * committed. Any read with an equal or greater `read_time` is guaranteed + * to see the effects of the transaction. + * + * @class + * @memberof v1beta1 + */ +class FirestoreClient { + /** + * Construct an instance of FirestoreClient. + * + * @param {object} [options] - The configuration object. See the subsequent + * parameters for more details. + * @param {object} [options.credentials] - Credentials object. + * @param {string} [options.credentials.client_email] + * @param {string} [options.credentials.private_key] + * @param {string} [options.email] - Account email address. Required when + * using a .pem or .p12 keyFilename. + * @param {string} [options.keyFilename] - Full path to the a .json, .pem, or + * .p12 key downloaded from the Google Developers Console. If you provide + * a path to a JSON file, the projectId option below is not necessary. + * NOTE: .pem and .p12 require you to specify options.email as well. + * @param {number} [options.port] - The port on which to connect to + * the remote host. + * @param {string} [options.projectId] - The project ID from the Google + * Developer's Console, e.g. 'grape-spaceship-123'. We will also check + * the environment variable GCLOUD_PROJECT for your project ID. If your + * app is running in an environment which supports + * {@link https://developers.google.com/identity/protocols/application-default-credentials Application Default Credentials}, + * your project ID will be detected automatically. + * @param {function} [options.promise] - Custom promise module to use instead + * of native Promises. + * @param {string} [options.servicePath] - The domain name of the + * API remote host. + */ + constructor(opts) { + this._descriptors = {}; + + // Ensure that options include the service address and port. + opts = Object.assign( + { + clientConfig: {}, + port: this.constructor.port, + servicePath: this.constructor.servicePath, + }, + opts + ); + + // Create a `gaxGrpc` object, with any grpc-specific options + // sent to the client. + opts.scopes = this.constructor.scopes; + var gaxGrpc = new gax.GrpcClient(opts); + + // Save the auth object to the client, for use by other methods. + this.auth = gaxGrpc.auth; + + // Determine the client header string. + var clientHeader = [ + `gl-node/${process.version}`, + `grpc/${gaxGrpc.grpcVersion}`, + `gax/${gax.version}`, + `gapic/${VERSION}`, + ]; + if (opts.libName && opts.libVersion) { + clientHeader.push(`${opts.libName}/${opts.libVersion}`); + } + + // Load the applicable protos. + var protos = merge( + {}, + gaxGrpc.loadProto( + path.join(__dirname, '..', '..', 'protos'), + 'google/firestore/v1beta1/firestore.proto' + ) + ); + + // This API contains "path templates"; forward-slash-separated + // identifiers to uniquely identify resources within the API. + // Create useful helper objects for these. + this._pathTemplates = { + databaseRootPathTemplate: new gax.PathTemplate( + 'projects/{project}/databases/{database}' + ), + documentRootPathTemplate: new gax.PathTemplate( + 'projects/{project}/databases/{database}/documents' + ), + documentPathPathTemplate: new gax.PathTemplate( + 'projects/{project}/databases/{database}/documents/{document_path=**}' + ), + anyPathPathTemplate: new gax.PathTemplate( + 'projects/{project}/databases/{database}/documents/{document}/{any_path=**}' + ), + }; + + // Some of the methods on this service return "paged" results, + // (e.g. 50 results at a time, with tokens to get subsequent + // pages). Denote the keys used for pagination and results. + this._descriptors.page = { + listDocuments: new gax.PageDescriptor( + 'pageToken', + 'nextPageToken', + 'documents' + ), + listCollectionIds: new gax.PageDescriptor( + 'pageToken', + 'nextPageToken', + 'collectionIds' + ), + }; + + // Some of the methods on this service provide streaming responses. + // Provide descriptors for these. + this._descriptors.stream = { + batchGetDocuments: new gax.StreamDescriptor(gax.StreamType.SERVER_STREAMING), + runQuery: new gax.StreamDescriptor(gax.StreamType.SERVER_STREAMING), + write: new gax.StreamDescriptor(gax.StreamType.BIDI_STREAMING), + listen: new gax.StreamDescriptor(gax.StreamType.BIDI_STREAMING), + }; + + // Put together the default options sent with requests. + var defaults = gaxGrpc.constructSettings( + 'google.firestore.v1beta1.Firestore', + gapicConfig, + opts.clientConfig, + {'x-goog-api-client': clientHeader.join(' ')} + ); + + // Set up a dictionary of "inner API calls"; the core implementation + // of calling the API is handled in `google-gax`, with this code + // merely providing the destination and request information. + this._innerApiCalls = {}; + + // Put together the "service stub" for + // google.firestore.v1beta1.Firestore. + var firestoreStub = gaxGrpc.createStub( + protos.google.firestore.v1beta1.Firestore, + opts + ); + + // Iterate over each of the methods that the service provides + // and create an API call method for each. + var firestoreStubMethods = [ + 'getDocument', + 'listDocuments', + 'createDocument', + 'updateDocument', + 'deleteDocument', + 'batchGetDocuments', + 'beginTransaction', + 'commit', + 'rollback', + 'runQuery', + 'write', + 'listen', + 'listCollectionIds', + ]; + for (let methodName of firestoreStubMethods) { + this._innerApiCalls[methodName] = gax.createApiCall( + firestoreStub.then( + stub => + function() { + var args = Array.prototype.slice.call(arguments, 0); + return stub[methodName].apply(stub, args); + } + ), + defaults[methodName], + this._descriptors.page[methodName] || this._descriptors.stream[methodName] + ); + } + } + + /** + * The DNS address for this API service. + */ + static get servicePath() { + return 'firestore.googleapis.com'; + } + + /** + * The port for this API service. + */ + static get port() { + return 443; + } + + /** + * The scopes needed to make gRPC calls for every method defined + * in this service. + */ + static get scopes() { + return [ + 'https://www.googleapis.com/auth/cloud-platform', + 'https://www.googleapis.com/auth/datastore', + ]; + } + + /** + * Return the project ID used by this class. + * @param {function(Error, string)} callback - the callback to + * be called with the current project Id. + */ + getProjectId(callback) { + return this.auth.getProjectId(callback); + } + + // ------------------- + // -- Service calls -- + // ------------------- + + /** + * Gets a single document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * The resource name of the Document to get. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * @param {Object} [request.mask] + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * @param {string} [request.transaction] + * Reads the document in a transaction. + * @param {Object} [request.readTime] + * Reads the version of the document at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @param {function(?Error, ?Object)} [callback] + * The function which will be called with the result of the API call. + * + * The second parameter to the callback is an object representing [Document]{@link google.firestore.v1beta1.Document}. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Document]{@link google.firestore.v1beta1.Document}. + * The promise has a method named "cancel" which cancels the ongoing API call. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedName = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * client.getDocument({name: formattedName}) + * .then(responses => { + * var response = responses[0]; + * // doThingsWith(response) + * }) + * .catch(err => { + * console.error(err); + * }); + */ + getDocument(request, options, callback) { + if (options instanceof Function && callback === undefined) { + callback = options; + options = {}; + } + options = options || {}; + + return this._innerApiCalls.getDocument(request, options, callback); + } + + /** + * Lists documents. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents` or + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * @param {string} request.collectionId + * The collection ID, relative to `parent`, to list. For example: `chatrooms` + * or `messages`. + * @param {number} [request.pageSize] + * The maximum number of resources contained in the underlying API + * response. If page streaming is performed per-resource, this + * parameter does not affect the return value. If page streaming is + * performed per-page, this determines the maximum number of + * resources in a page. + * @param {string} [request.orderBy] + * The order to sort results by. For example: `priority desc, name`. + * @param {Object} [request.mask] + * The fields to return. If not set, returns all fields. + * + * If a document has a field that is not present in this mask, that field + * will not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * @param {string} [request.transaction] + * Reads documents in a transaction. + * @param {Object} [request.readTime] + * Reads documents as they were at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * @param {boolean} [request.showMissing] + * If the list should show missing documents. A missing document is a + * document that does not exist but has sub-documents. These documents will + * be returned with a key but will not have fields, Document.create_time, + * or Document.update_time set. + * + * Requests with `show_missing` may not specify `where` or + * `order_by`. + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @param {function(?Error, ?Array, ?Object, ?Object)} [callback] + * The function which will be called with the result of the API call. + * + * The second parameter to the callback is Array of [Document]{@link google.firestore.v1beta1.Document}. + * + * When autoPaginate: false is specified through options, it contains the result + * in a single response. If the response indicates the next page exists, the third + * parameter is set to be used for the next request object. The fourth parameter keeps + * the raw response object of an object representing [ListDocumentsResponse]{@link google.firestore.v1beta1.ListDocumentsResponse}. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of [Document]{@link google.firestore.v1beta1.Document}. + * + * When autoPaginate: false is specified through options, the array has three elements. + * The first element is Array of [Document]{@link google.firestore.v1beta1.Document} in a single response. + * The second element is the next request object if the response + * indicates the next page exists, or null. The third element is + * an object representing [ListDocumentsResponse]{@link google.firestore.v1beta1.ListDocumentsResponse}. + * + * The promise has a method named "cancel" which cancels the ongoing API call. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * // Iterate over all elements. + * var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * var collectionId = ''; + * var request = { + * parent: formattedParent, + * collectionId: collectionId, + * }; + * + * client.listDocuments(request) + * .then(responses => { + * var resources = responses[0]; + * for (let i = 0; i < resources.length; i += 1) { + * // doThingsWith(resources[i]) + * } + * }) + * .catch(err => { + * console.error(err); + * }); + * + * // Or obtain the paged response. + * var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * var collectionId = ''; + * var request = { + * parent: formattedParent, + * collectionId: collectionId, + * }; + * + * + * var options = {autoPaginate: false}; + * var callback = responses => { + * // The actual resources in a response. + * var resources = responses[0]; + * // The next request if the response shows that there are more responses. + * var nextRequest = responses[1]; + * // The actual response object, if necessary. + * // var rawResponse = responses[2]; + * for (let i = 0; i < resources.length; i += 1) { + * // doThingsWith(resources[i]); + * } + * if (nextRequest) { + * // Fetch the next page. + * return client.listDocuments(nextRequest, options).then(callback); + * } + * } + * client.listDocuments(request, options) + * .then(callback) + * .catch(err => { + * console.error(err); + * }); + */ + listDocuments(request, options, callback) { + if (options instanceof Function && callback === undefined) { + callback = options; + options = {}; + } + options = options || {}; + + return this._innerApiCalls.listDocuments(request, options, callback); + } + + /** + * Equivalent to {@link listDocuments}, but returns a NodeJS Stream object. + * + * This fetches the paged responses for {@link listDocuments} continuously + * and invokes the callback registered for 'data' event for each element in the + * responses. + * + * The returned object has 'end' method when no more elements are required. + * + * autoPaginate option will be ignored. + * + * @see {@link https://nodejs.org/api/stream.html} + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents` or + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * @param {string} request.collectionId + * The collection ID, relative to `parent`, to list. For example: `chatrooms` + * or `messages`. + * @param {number} [request.pageSize] + * The maximum number of resources contained in the underlying API + * response. If page streaming is performed per-resource, this + * parameter does not affect the return value. If page streaming is + * performed per-page, this determines the maximum number of + * resources in a page. + * @param {string} [request.orderBy] + * The order to sort results by. For example: `priority desc, name`. + * @param {Object} [request.mask] + * The fields to return. If not set, returns all fields. + * + * If a document has a field that is not present in this mask, that field + * will not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * @param {string} [request.transaction] + * Reads documents in a transaction. + * @param {Object} [request.readTime] + * Reads documents as they were at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * @param {boolean} [request.showMissing] + * If the list should show missing documents. A missing document is a + * document that does not exist but has sub-documents. These documents will + * be returned with a key but will not have fields, Document.create_time, + * or Document.update_time set. + * + * Requests with `show_missing` may not specify `where` or + * `order_by`. + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @returns {Stream} + * An object stream which emits an object representing [Document]{@link google.firestore.v1beta1.Document} on 'data' event. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * var collectionId = ''; + * var request = { + * parent: formattedParent, + * collectionId: collectionId, + * }; + * client.listDocumentsStream(request) + * .on('data', element => { + * // doThingsWith(element) + * }).on('error', err => { + * console.log(err); + * }); + */ + listDocumentsStream(request, options) { + options = options || {}; + + return this._descriptors.page.listDocuments.createStream( + this._innerApiCalls.listDocuments, + request, + options + ); + }; + + /** + * Creates a new document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * The parent resource. For example: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/chatrooms/{chatroom_id}` + * @param {string} request.collectionId + * The collection ID, relative to `parent`, to list. For example: `chatrooms`. + * @param {string} request.documentId + * The client-assigned document ID to use for this document. + * + * Optional. If not specified, an ID will be assigned by the service. + * @param {Object} request.document + * The document to create. `name` must not be set. + * + * This object should have the same structure as [Document]{@link google.firestore.v1beta1.Document} + * @param {Object} [request.mask] + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @param {function(?Error, ?Object)} [callback] + * The function which will be called with the result of the API call. + * + * The second parameter to the callback is an object representing [Document]{@link google.firestore.v1beta1.Document}. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Document]{@link google.firestore.v1beta1.Document}. + * The promise has a method named "cancel" which cancels the ongoing API call. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * var collectionId = ''; + * var documentId = ''; + * var document = {}; + * var request = { + * parent: formattedParent, + * collectionId: collectionId, + * documentId: documentId, + * document: document, + * }; + * client.createDocument(request) + * .then(responses => { + * var response = responses[0]; + * // doThingsWith(response) + * }) + * .catch(err => { + * console.error(err); + * }); + */ + createDocument(request, options, callback) { + if (options instanceof Function && callback === undefined) { + callback = options; + options = {}; + } + options = options || {}; + + return this._innerApiCalls.createDocument(request, options, callback); + } + + /** + * Updates or inserts a document. + * + * @param {Object} request + * The request object that will be sent. + * @param {Object} request.document + * The updated document. + * Creates the document if it does not already exist. + * + * This object should have the same structure as [Document]{@link google.firestore.v1beta1.Document} + * @param {Object} request.updateMask + * The fields to update. + * None of the field paths in the mask may contain a reserved name. + * + * If the document exists on the server and has fields not referenced in the + * mask, they are left unchanged. + * Fields referenced in the mask, but not present in the input document, are + * deleted from the document on the server. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * @param {Object} [request.mask] + * The fields to return. If not set, returns all fields. + * + * If the document has a field that is not present in this mask, that field + * will not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * @param {Object} [request.currentDocument] + * An optional precondition on the document. + * The request will fail if this is set and not met by the target document. + * + * This object should have the same structure as [Precondition]{@link google.firestore.v1beta1.Precondition} + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @param {function(?Error, ?Object)} [callback] + * The function which will be called with the result of the API call. + * + * The second parameter to the callback is an object representing [Document]{@link google.firestore.v1beta1.Document}. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [Document]{@link google.firestore.v1beta1.Document}. + * The promise has a method named "cancel" which cancels the ongoing API call. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var document = {}; + * var updateMask = {}; + * var request = { + * document: document, + * updateMask: updateMask, + * }; + * client.updateDocument(request) + * .then(responses => { + * var response = responses[0]; + * // doThingsWith(response) + * }) + * .catch(err => { + * console.error(err); + * }); + */ + updateDocument(request, options, callback) { + if (options instanceof Function && callback === undefined) { + callback = options; + options = {}; + } + options = options || {}; + + return this._innerApiCalls.updateDocument(request, options, callback); + } + + /** + * Deletes a document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.name + * The resource name of the Document to delete. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * @param {Object} [request.currentDocument] + * An optional precondition on the document. + * The request will fail if this is set and not met by the target document. + * + * This object should have the same structure as [Precondition]{@link google.firestore.v1beta1.Precondition} + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @param {function(?Error)} [callback] + * The function which will be called with the result of the API call. + * @returns {Promise} - The promise which resolves when API call finishes. + * The promise has a method named "cancel" which cancels the ongoing API call. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedName = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * client.deleteDocument({name: formattedName}).catch(err => { + * console.error(err); + * }); + */ + deleteDocument(request, options, callback) { + if (options instanceof Function && callback === undefined) { + callback = options; + options = {}; + } + options = options || {}; + + return this._innerApiCalls.deleteDocument(request, options, callback); + } + + /** + * Gets multiple documents. + * + * Documents returned by this method are not guaranteed to be returned in the + * same order that they were requested. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {string[]} request.documents + * The names of the documents to retrieve. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * The request will fail if any of the document is not a child resource of the + * given `database`. Duplicate names will be elided. + * @param {Object} [request.mask] + * The fields to return. If not set, returns all fields. + * + * If a document has a field that is not present in this mask, that field will + * not be returned in the response. + * + * This object should have the same structure as [DocumentMask]{@link google.firestore.v1beta1.DocumentMask} + * @param {string} [request.transaction] + * Reads documents in a transaction. + * @param {Object} [request.newTransaction] + * Starts a new transaction and reads the documents. + * Defaults to a read-only transaction. + * The new transaction ID will be returned as the first response in the + * stream. + * + * This object should have the same structure as [TransactionOptions]{@link google.firestore.v1beta1.TransactionOptions} + * @param {Object} [request.readTime] + * Reads documents as they were at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @returns {Stream} + * An object stream which emits [BatchGetDocumentsResponse]{@link google.firestore.v1beta1.BatchGetDocumentsResponse} on 'data' event. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + * var documents = []; + * var request = { + * database: formattedDatabase, + * documents: documents, + * }; + * client.batchGetDocuments(request).on('data', response => { + * // doThingsWith(response) + * }); + */ + batchGetDocuments(request, options) { + options = options || {}; + + return this._innerApiCalls.batchGetDocuments(request, options); + } + + /** + * Starts a new transaction. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {Object} [request.options] + * The options for the transaction. + * Defaults to a read-write transaction. + * + * This object should have the same structure as [TransactionOptions]{@link google.firestore.v1beta1.TransactionOptions} + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @param {function(?Error, ?Object)} [callback] + * The function which will be called with the result of the API call. + * + * The second parameter to the callback is an object representing [BeginTransactionResponse]{@link google.firestore.v1beta1.BeginTransactionResponse}. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [BeginTransactionResponse]{@link google.firestore.v1beta1.BeginTransactionResponse}. + * The promise has a method named "cancel" which cancels the ongoing API call. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + * client.beginTransaction({database: formattedDatabase}) + * .then(responses => { + * var response = responses[0]; + * // doThingsWith(response) + * }) + * .catch(err => { + * console.error(err); + * }); + */ + beginTransaction(request, options, callback) { + if (options instanceof Function && callback === undefined) { + callback = options; + options = {}; + } + options = options || {}; + + return this._innerApiCalls.beginTransaction(request, options, callback); + } + + /** + * Commits a transaction, while optionally updating documents. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {Object[]} request.writes + * The writes to apply. + * + * Always executed atomically and in order. + * + * This object should have the same structure as [Write]{@link google.firestore.v1beta1.Write} + * @param {string} [request.transaction] + * If set, applies all writes in this transaction, and commits it. + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @param {function(?Error, ?Object)} [callback] + * The function which will be called with the result of the API call. + * + * The second parameter to the callback is an object representing [CommitResponse]{@link google.firestore.v1beta1.CommitResponse}. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is an object representing [CommitResponse]{@link google.firestore.v1beta1.CommitResponse}. + * The promise has a method named "cancel" which cancels the ongoing API call. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + * var writes = []; + * var request = { + * database: formattedDatabase, + * writes: writes, + * }; + * client.commit(request) + * .then(responses => { + * var response = responses[0]; + * // doThingsWith(response) + * }) + * .catch(err => { + * console.error(err); + * }); + */ + commit(request, options, callback) { + if (options instanceof Function && callback === undefined) { + callback = options; + options = {}; + } + options = options || {}; + + return this._innerApiCalls.commit(request, options, callback); + } + + /** + * Rolls back a transaction. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.database + * The database name. In the format: + * `projects/{project_id}/databases/{database_id}`. + * @param {string} request.transaction + * The transaction to roll back. + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @param {function(?Error)} [callback] + * The function which will be called with the result of the API call. + * @returns {Promise} - The promise which resolves when API call finishes. + * The promise has a method named "cancel" which cancels the ongoing API call. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + * var transaction = ''; + * var request = { + * database: formattedDatabase, + * transaction: transaction, + * }; + * client.rollback(request).catch(err => { + * console.error(err); + * }); + */ + rollback(request, options, callback) { + if (options instanceof Function && callback === undefined) { + callback = options; + options = {}; + } + options = options || {}; + + return this._innerApiCalls.rollback(request, options, callback); + } + + /** + * Runs a query. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * The parent resource name. In the format: + * `projects/{project_id}/databases/{database_id}/documents` or + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents` or + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * @param {Object} [request.structuredQuery] + * A structured query. + * + * This object should have the same structure as [StructuredQuery]{@link google.firestore.v1beta1.StructuredQuery} + * @param {string} [request.transaction] + * Reads documents in a transaction. + * @param {Object} [request.newTransaction] + * Starts a new transaction and reads the documents. + * Defaults to a read-only transaction. + * The new transaction ID will be returned as the first response in the + * stream. + * + * This object should have the same structure as [TransactionOptions]{@link google.firestore.v1beta1.TransactionOptions} + * @param {Object} [request.readTime] + * Reads documents as they were at the given time. + * This may not be older than 60 seconds. + * + * This object should have the same structure as [Timestamp]{@link google.protobuf.Timestamp} + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @returns {Stream} + * An object stream which emits [RunQueryResponse]{@link google.firestore.v1beta1.RunQueryResponse} on 'data' event. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * client.runQuery({parent: formattedParent}).on('data', response => { + * // doThingsWith(response) + * }); + */ + runQuery(request, options) { + options = options || {}; + + return this._innerApiCalls.runQuery(request, options); + } + + /** + * Streams batches of document updates and deletes, in order. + * + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @returns {Stream} + * An object stream which is both readable and writable. It accepts objects + * representing [WriteRequest]{@link google.firestore.v1beta1.WriteRequest} for write() method, and + * will emit objects representing [WriteResponse]{@link google.firestore.v1beta1.WriteResponse} on 'data' event asynchronously. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var stream = client.write().on('data', response => { + * // doThingsWith(response) + * }); + * var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + * var request = { + * database: formattedDatabase, + * }; + * // Write request objects. + * stream.write(request); + */ + write(options) { + options = options || {}; + + return this._innerApiCalls.write(options); + } + + /** + * Listens to changes. + * + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @returns {Stream} + * An object stream which is both readable and writable. It accepts objects + * representing [ListenRequest]{@link google.firestore.v1beta1.ListenRequest} for write() method, and + * will emit objects representing [ListenResponse]{@link google.firestore.v1beta1.ListenResponse} on 'data' event asynchronously. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var stream = client.listen().on('data', response => { + * // doThingsWith(response) + * }); + * var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + * var request = { + * database: formattedDatabase, + * }; + * // Write request objects. + * stream.write(request); + */ + listen(options) { + options = options || {}; + + return this._innerApiCalls.listen(options); + } + + /** + * Lists all the collection IDs underneath a document. + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * The parent document. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * @param {number} [request.pageSize] + * The maximum number of resources contained in the underlying API + * response. If page streaming is performed per-resource, this + * parameter does not affect the return value. If page streaming is + * performed per-page, this determines the maximum number of + * resources in a page. + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @param {function(?Error, ?Array, ?Object, ?Object)} [callback] + * The function which will be called with the result of the API call. + * + * The second parameter to the callback is Array of string. + * + * When autoPaginate: false is specified through options, it contains the result + * in a single response. If the response indicates the next page exists, the third + * parameter is set to be used for the next request object. The fourth parameter keeps + * the raw response object of an object representing [ListCollectionIdsResponse]{@link google.firestore.v1beta1.ListCollectionIdsResponse}. + * @returns {Promise} - The promise which resolves to an array. + * The first element of the array is Array of string. + * + * When autoPaginate: false is specified through options, the array has three elements. + * The first element is Array of string in a single response. + * The second element is the next request object if the response + * indicates the next page exists, or null. The third element is + * an object representing [ListCollectionIdsResponse]{@link google.firestore.v1beta1.ListCollectionIdsResponse}. + * + * The promise has a method named "cancel" which cancels the ongoing API call. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * // Iterate over all elements. + * var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * + * client.listCollectionIds({parent: formattedParent}) + * .then(responses => { + * var resources = responses[0]; + * for (let i = 0; i < resources.length; i += 1) { + * // doThingsWith(resources[i]) + * } + * }) + * .catch(err => { + * console.error(err); + * }); + * + * // Or obtain the paged response. + * var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * + * + * var options = {autoPaginate: false}; + * var callback = responses => { + * // The actual resources in a response. + * var resources = responses[0]; + * // The next request if the response shows that there are more responses. + * var nextRequest = responses[1]; + * // The actual response object, if necessary. + * // var rawResponse = responses[2]; + * for (let i = 0; i < resources.length; i += 1) { + * // doThingsWith(resources[i]); + * } + * if (nextRequest) { + * // Fetch the next page. + * return client.listCollectionIds(nextRequest, options).then(callback); + * } + * } + * client.listCollectionIds({parent: formattedParent}, options) + * .then(callback) + * .catch(err => { + * console.error(err); + * }); + */ + listCollectionIds(request, options, callback) { + if (options instanceof Function && callback === undefined) { + callback = options; + options = {}; + } + options = options || {}; + + return this._innerApiCalls.listCollectionIds(request, options, callback); + } + + /** + * Equivalent to {@link listCollectionIds}, but returns a NodeJS Stream object. + * + * This fetches the paged responses for {@link listCollectionIds} continuously + * and invokes the callback registered for 'data' event for each element in the + * responses. + * + * The returned object has 'end' method when no more elements are required. + * + * autoPaginate option will be ignored. + * + * @see {@link https://nodejs.org/api/stream.html} + * + * @param {Object} request + * The request object that will be sent. + * @param {string} request.parent + * The parent document. In the format: + * `projects/{project_id}/databases/{database_id}/documents/{document_path}`. + * For example: + * `projects/my-project/databases/my-database/documents/chatrooms/my-chatroom` + * @param {number} [request.pageSize] + * The maximum number of resources contained in the underlying API + * response. If page streaming is performed per-resource, this + * parameter does not affect the return value. If page streaming is + * performed per-page, this determines the maximum number of + * resources in a page. + * @param {Object} [options] + * Optional parameters. You can override the default settings for this call, e.g, timeout, + * retries, paginations, etc. See [gax.CallOptions]{@link https://googleapis.github.io/gax-nodejs/global.html#CallOptions} for the details. + * @returns {Stream} + * An object stream which emits a string on 'data' event. + * + * @example + * + * const firestore = require('firestore.v1beta1'); + * + * var client = new firestore.v1beta1.FirestoreClient({ + * // optional auth parameters. + * }); + * + * var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + * client.listCollectionIdsStream({parent: formattedParent}) + * .on('data', element => { + * // doThingsWith(element) + * }).on('error', err => { + * console.log(err); + * }); + */ + listCollectionIdsStream(request, options) { + options = options || {}; + + return this._descriptors.page.listCollectionIds.createStream( + this._innerApiCalls.listCollectionIds, + request, + options + ); + }; + + // -------------------- + // -- Path templates -- + // -------------------- + + /** + * Return a fully-qualified database_root resource name string. + * + * @param {String} project + * @param {String} database + * @returns {String} + */ + databaseRootPath(project, database) { + return this._pathTemplates.databaseRootPathTemplate.render({ + project: project, + database: database, + }); + } + + /** + * Return a fully-qualified document_root resource name string. + * + * @param {String} project + * @param {String} database + * @returns {String} + */ + documentRootPath(project, database) { + return this._pathTemplates.documentRootPathTemplate.render({ + project: project, + database: database, + }); + } + + /** + * Return a fully-qualified document_path resource name string. + * + * @param {String} project + * @param {String} database + * @param {String} documentPath + * @returns {String} + */ + documentPathPath(project, database, documentPath) { + return this._pathTemplates.documentPathPathTemplate.render({ + project: project, + database: database, + document_path: documentPath, + }); + } + + /** + * Return a fully-qualified any_path resource name string. + * + * @param {String} project + * @param {String} database + * @param {String} document + * @param {String} anyPath + * @returns {String} + */ + anyPathPath(project, database, document, anyPath) { + return this._pathTemplates.anyPathPathTemplate.render({ + project: project, + database: database, + document: document, + any_path: anyPath, + }); + } + + /** + * Parse the databaseRootName from a database_root resource. + * + * @param {String} databaseRootName + * A fully-qualified path representing a database_root resources. + * @returns {String} - A string representing the project. + */ + matchProjectFromDatabaseRootName(databaseRootName) { + return this._pathTemplates.databaseRootPathTemplate + .match(databaseRootName) + .project; + } + + /** + * Parse the databaseRootName from a database_root resource. + * + * @param {String} databaseRootName + * A fully-qualified path representing a database_root resources. + * @returns {String} - A string representing the database. + */ + matchDatabaseFromDatabaseRootName(databaseRootName) { + return this._pathTemplates.databaseRootPathTemplate + .match(databaseRootName) + .database; + } + + /** + * Parse the documentRootName from a document_root resource. + * + * @param {String} documentRootName + * A fully-qualified path representing a document_root resources. + * @returns {String} - A string representing the project. + */ + matchProjectFromDocumentRootName(documentRootName) { + return this._pathTemplates.documentRootPathTemplate + .match(documentRootName) + .project; + } + + /** + * Parse the documentRootName from a document_root resource. + * + * @param {String} documentRootName + * A fully-qualified path representing a document_root resources. + * @returns {String} - A string representing the database. + */ + matchDatabaseFromDocumentRootName(documentRootName) { + return this._pathTemplates.documentRootPathTemplate + .match(documentRootName) + .database; + } + + /** + * Parse the documentPathName from a document_path resource. + * + * @param {String} documentPathName + * A fully-qualified path representing a document_path resources. + * @returns {String} - A string representing the project. + */ + matchProjectFromDocumentPathName(documentPathName) { + return this._pathTemplates.documentPathPathTemplate + .match(documentPathName) + .project; + } + + /** + * Parse the documentPathName from a document_path resource. + * + * @param {String} documentPathName + * A fully-qualified path representing a document_path resources. + * @returns {String} - A string representing the database. + */ + matchDatabaseFromDocumentPathName(documentPathName) { + return this._pathTemplates.documentPathPathTemplate + .match(documentPathName) + .database; + } + + /** + * Parse the documentPathName from a document_path resource. + * + * @param {String} documentPathName + * A fully-qualified path representing a document_path resources. + * @returns {String} - A string representing the document_path. + */ + matchDocumentPathFromDocumentPathName(documentPathName) { + return this._pathTemplates.documentPathPathTemplate + .match(documentPathName) + .document_path; + } + + /** + * Parse the anyPathName from a any_path resource. + * + * @param {String} anyPathName + * A fully-qualified path representing a any_path resources. + * @returns {String} - A string representing the project. + */ + matchProjectFromAnyPathName(anyPathName) { + return this._pathTemplates.anyPathPathTemplate + .match(anyPathName) + .project; + } + + /** + * Parse the anyPathName from a any_path resource. + * + * @param {String} anyPathName + * A fully-qualified path representing a any_path resources. + * @returns {String} - A string representing the database. + */ + matchDatabaseFromAnyPathName(anyPathName) { + return this._pathTemplates.anyPathPathTemplate + .match(anyPathName) + .database; + } + + /** + * Parse the anyPathName from a any_path resource. + * + * @param {String} anyPathName + * A fully-qualified path representing a any_path resources. + * @returns {String} - A string representing the document. + */ + matchDocumentFromAnyPathName(anyPathName) { + return this._pathTemplates.anyPathPathTemplate + .match(anyPathName) + .document; + } + + /** + * Parse the anyPathName from a any_path resource. + * + * @param {String} anyPathName + * A fully-qualified path representing a any_path resources. + * @returns {String} - A string representing the any_path. + */ + matchAnyPathFromAnyPathName(anyPathName) { + return this._pathTemplates.anyPathPathTemplate + .match(anyPathName) + .any_path; + } +} + + +module.exports = FirestoreClient; diff --git a/src/v1beta1/firestore_client_config.json b/src/v1beta1/firestore_client_config.json new file mode 100644 index 000000000..4c15ed4e8 --- /dev/null +++ b/src/v1beta1/firestore_client_config.json @@ -0,0 +1,100 @@ +{ + "interfaces": { + "google.firestore.v1beta1.Firestore": { + "retry_codes": { + "idempotent": [ + "DEADLINE_EXCEEDED", + "UNAVAILABLE" + ], + "non_idempotent": [] + }, + "retry_params": { + "default": { + "initial_retry_delay_millis": 100, + "retry_delay_multiplier": 1.3, + "max_retry_delay_millis": 60000, + "initial_rpc_timeout_millis": 20000, + "rpc_timeout_multiplier": 1.0, + "max_rpc_timeout_millis": 20000, + "total_timeout_millis": 600000 + }, + "streaming": { + "initial_retry_delay_millis": 100, + "retry_delay_multiplier": 1.3, + "max_retry_delay_millis": 60000, + "initial_rpc_timeout_millis": 300000, + "rpc_timeout_multiplier": 1.0, + "max_rpc_timeout_millis": 300000, + "total_timeout_millis": 600000 + } + }, + "methods": { + "GetDocument": { + "timeout_millis": 60000, + "retry_codes_name": "idempotent", + "retry_params_name": "default" + }, + "ListDocuments": { + "timeout_millis": 60000, + "retry_codes_name": "idempotent", + "retry_params_name": "default" + }, + "CreateDocument": { + "timeout_millis": 60000, + "retry_codes_name": "non_idempotent", + "retry_params_name": "default" + }, + "UpdateDocument": { + "timeout_millis": 60000, + "retry_codes_name": "non_idempotent", + "retry_params_name": "default" + }, + "DeleteDocument": { + "timeout_millis": 60000, + "retry_codes_name": "idempotent", + "retry_params_name": "default" + }, + "BatchGetDocuments": { + "timeout_millis": 300000, + "retry_codes_name": "idempotent", + "retry_params_name": "streaming" + }, + "BeginTransaction": { + "timeout_millis": 60000, + "retry_codes_name": "idempotent", + "retry_params_name": "default" + }, + "Commit": { + "timeout_millis": 60000, + "retry_codes_name": "non_idempotent", + "retry_params_name": "default" + }, + "Rollback": { + "timeout_millis": 60000, + "retry_codes_name": "idempotent", + "retry_params_name": "default" + }, + "RunQuery": { + "timeout_millis": 60000, + "retry_codes_name": "idempotent", + "retry_params_name": "default" + }, + "Write": { + "timeout_millis": 86400000, + "retry_codes_name": "non_idempotent", + "retry_params_name": "streaming" + }, + "Listen": { + "timeout_millis": 86400000, + "retry_codes_name": "idempotent", + "retry_params_name": "streaming" + }, + "ListCollectionIds": { + "timeout_millis": 60000, + "retry_codes_name": "idempotent", + "retry_params_name": "default" + } + } + } + } +} diff --git a/test/gapic-v1beta1.js b/test/gapic-v1beta1.js new file mode 100644 index 000000000..4af8afff0 --- /dev/null +++ b/test/gapic-v1beta1.js @@ -0,0 +1,870 @@ +// 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 +// +// https://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. + +'use strict'; + +const assert = require('assert'); +const through2 = require('through2'); + +const firestoreModule = require('../src'); + +var FAKE_STATUS_CODE = 1; +var error = new Error(); +error.code = FAKE_STATUS_CODE; + +describe('FirestoreClient', () => { + describe('getDocument', () => { + it('invokes getDocument without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedName = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var request = { + name: formattedName, + }; + + // Mock response + var name2 = 'name2-1052831874'; + var expectedResponse = { + name: name2, + }; + + // Mock Grpc layer + client._innerApiCalls.getDocument = mockSimpleGrpcMethod( + request, + expectedResponse + ); + + client.getDocument(request, (err, response) => { + assert.ifError(err); + assert.deepStrictEqual(response, expectedResponse); + done(); + }); + }); + + it('invokes getDocument with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedName = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var request = { + name: formattedName, + }; + + // Mock Grpc layer + client._innerApiCalls.getDocument = mockSimpleGrpcMethod( + request, + null, + error + ); + + client.getDocument(request, (err, response) => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + assert(typeof response === 'undefined'); + done(); + }); + }); + }); + + describe('listDocuments', () => { + it('invokes listDocuments without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var collectionId = 'collectionId-821242276'; + var request = { + parent: formattedParent, + collectionId: collectionId, + }; + + // Mock response + var nextPageToken = ''; + var documentsElement = {}; + var documents = [documentsElement]; + var expectedResponse = { + nextPageToken: nextPageToken, + documents: documents, + }; + + // Mock Grpc layer + client._innerApiCalls.listDocuments = (actualRequest, options, callback) => { + assert.deepStrictEqual(actualRequest, request); + callback(null, expectedResponse.documents); + }; + + client.listDocuments(request, (err, response) => { + assert.ifError(err); + assert.deepStrictEqual(response, expectedResponse.documents); + done(); + }); + }); + + it('invokes listDocuments with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var collectionId = 'collectionId-821242276'; + var request = { + parent: formattedParent, + collectionId: collectionId, + }; + + // Mock Grpc layer + client._innerApiCalls.listDocuments = mockSimpleGrpcMethod( + request, + null, + error + ); + + client.listDocuments(request, (err, response) => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + assert(typeof response === 'undefined'); + done(); + }); + }); + }); + + describe('createDocument', () => { + it('invokes createDocument without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var collectionId = 'collectionId-821242276'; + var documentId = 'documentId506676927'; + var document = {}; + var request = { + parent: formattedParent, + collectionId: collectionId, + documentId: documentId, + document: document, + }; + + // Mock response + var name = 'name3373707'; + var expectedResponse = { + name: name, + }; + + // Mock Grpc layer + client._innerApiCalls.createDocument = mockSimpleGrpcMethod( + request, + expectedResponse + ); + + client.createDocument(request, (err, response) => { + assert.ifError(err); + assert.deepStrictEqual(response, expectedResponse); + done(); + }); + }); + + it('invokes createDocument with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var collectionId = 'collectionId-821242276'; + var documentId = 'documentId506676927'; + var document = {}; + var request = { + parent: formattedParent, + collectionId: collectionId, + documentId: documentId, + document: document, + }; + + // Mock Grpc layer + client._innerApiCalls.createDocument = mockSimpleGrpcMethod( + request, + null, + error + ); + + client.createDocument(request, (err, response) => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + assert(typeof response === 'undefined'); + done(); + }); + }); + }); + + describe('updateDocument', () => { + it('invokes updateDocument without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var document = {}; + var updateMask = {}; + var request = { + document: document, + updateMask: updateMask, + }; + + // Mock response + var name = 'name3373707'; + var expectedResponse = { + name: name, + }; + + // Mock Grpc layer + client._innerApiCalls.updateDocument = mockSimpleGrpcMethod( + request, + expectedResponse + ); + + client.updateDocument(request, (err, response) => { + assert.ifError(err); + assert.deepStrictEqual(response, expectedResponse); + done(); + }); + }); + + it('invokes updateDocument with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var document = {}; + var updateMask = {}; + var request = { + document: document, + updateMask: updateMask, + }; + + // Mock Grpc layer + client._innerApiCalls.updateDocument = mockSimpleGrpcMethod( + request, + null, + error + ); + + client.updateDocument(request, (err, response) => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + assert(typeof response === 'undefined'); + done(); + }); + }); + }); + + describe('deleteDocument', () => { + it('invokes deleteDocument without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedName = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var request = { + name: formattedName, + }; + + // Mock Grpc layer + client._innerApiCalls.deleteDocument = mockSimpleGrpcMethod(request); + + client.deleteDocument(request, err => { + assert.ifError(err); + done(); + }); + }); + + it('invokes deleteDocument with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedName = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var request = { + name: formattedName, + }; + + // Mock Grpc layer + client._innerApiCalls.deleteDocument = mockSimpleGrpcMethod( + request, + null, + error + ); + + client.deleteDocument(request, err => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + done(); + }); + }); + }); + + describe('batchGetDocuments', () => { + it('invokes batchGetDocuments without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var documents = []; + var request = { + database: formattedDatabase, + documents: documents, + }; + + // Mock response + var missing = 'missing1069449574'; + var transaction = '-34'; + var expectedResponse = { + missing: missing, + transaction: transaction, + }; + + // Mock Grpc layer + client._innerApiCalls.batchGetDocuments = mockServerStreamingGrpcMethod(request, expectedResponse); + + var stream = client.batchGetDocuments(request); + stream.on('data', response => { + assert.deepStrictEqual(response, expectedResponse); + done(); + }); + stream.on('error', err => { + done(err); + }); + + stream.write(); + }); + + it('invokes batchGetDocuments with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var documents = []; + var request = { + database: formattedDatabase, + documents: documents, + }; + + // Mock Grpc layer + client._innerApiCalls.batchGetDocuments = mockServerStreamingGrpcMethod(request, null, error); + + var stream = client.batchGetDocuments(request); + stream.on('data', () => { + assert.fail(); + }); + stream.on('error', err => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + done(); + }); + + stream.write(); + }); + }); + + describe('beginTransaction', () => { + it('invokes beginTransaction without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var request = { + database: formattedDatabase, + }; + + // Mock response + var transaction = '-34'; + var expectedResponse = { + transaction: transaction, + }; + + // Mock Grpc layer + client._innerApiCalls.beginTransaction = mockSimpleGrpcMethod( + request, + expectedResponse + ); + + client.beginTransaction(request, (err, response) => { + assert.ifError(err); + assert.deepStrictEqual(response, expectedResponse); + done(); + }); + }); + + it('invokes beginTransaction with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var request = { + database: formattedDatabase, + }; + + // Mock Grpc layer + client._innerApiCalls.beginTransaction = mockSimpleGrpcMethod( + request, + null, + error + ); + + client.beginTransaction(request, (err, response) => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + assert(typeof response === 'undefined'); + done(); + }); + }); + }); + + describe('commit', () => { + it('invokes commit without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var writes = []; + var request = { + database: formattedDatabase, + writes: writes, + }; + + // Mock response + var expectedResponse = {}; + + // Mock Grpc layer + client._innerApiCalls.commit = mockSimpleGrpcMethod( + request, + expectedResponse + ); + + client.commit(request, (err, response) => { + assert.ifError(err); + assert.deepStrictEqual(response, expectedResponse); + done(); + }); + }); + + it('invokes commit with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var writes = []; + var request = { + database: formattedDatabase, + writes: writes, + }; + + // Mock Grpc layer + client._innerApiCalls.commit = mockSimpleGrpcMethod( + request, + null, + error + ); + + client.commit(request, (err, response) => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + assert(typeof response === 'undefined'); + done(); + }); + }); + }); + + describe('rollback', () => { + it('invokes rollback without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var transaction = '-34'; + var request = { + database: formattedDatabase, + transaction: transaction, + }; + + // Mock Grpc layer + client._innerApiCalls.rollback = mockSimpleGrpcMethod(request); + + client.rollback(request, err => { + assert.ifError(err); + done(); + }); + }); + + it('invokes rollback with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var transaction = '-34'; + var request = { + database: formattedDatabase, + transaction: transaction, + }; + + // Mock Grpc layer + client._innerApiCalls.rollback = mockSimpleGrpcMethod( + request, + null, + error + ); + + client.rollback(request, err => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + done(); + }); + }); + }); + + describe('runQuery', () => { + it('invokes runQuery without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var request = { + parent: formattedParent, + }; + + // Mock response + var transaction = '-34'; + var skippedResults = 880286183; + var expectedResponse = { + transaction: transaction, + skippedResults: skippedResults, + }; + + // Mock Grpc layer + client._innerApiCalls.runQuery = mockServerStreamingGrpcMethod(request, expectedResponse); + + var stream = client.runQuery(request); + stream.on('data', response => { + assert.deepStrictEqual(response, expectedResponse); + done(); + }); + stream.on('error', err => { + done(err); + }); + + stream.write(); + }); + + it('invokes runQuery with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var request = { + parent: formattedParent, + }; + + // Mock Grpc layer + client._innerApiCalls.runQuery = mockServerStreamingGrpcMethod(request, null, error); + + var stream = client.runQuery(request); + stream.on('data', () => { + assert.fail(); + }); + stream.on('error', err => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + done(); + }); + + stream.write(); + }); + }); + + describe('write', () => { + it('invokes write without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var request = { + database: formattedDatabase, + }; + + // Mock response + var streamId = 'streamId-315624902'; + var streamToken = '122'; + var expectedResponse = { + streamId: streamId, + streamToken: streamToken, + }; + + // Mock Grpc layer + client._innerApiCalls.write = mockBidiStreamingGrpcMethod(request, expectedResponse); + + var stream = client.write().on('data', response => { + assert.deepStrictEqual(response, expectedResponse); + done(); + }).on('error', err => { + done(err); + }); + + stream.write(request); + }); + + it('invokes write with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var request = { + database: formattedDatabase, + }; + + // Mock Grpc layer + client._innerApiCalls.write = mockBidiStreamingGrpcMethod(request, null, error); + + var stream = client.write().on('data', () => { + assert.fail(); + }).on('error', err => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + done(); + }); + + stream.write(request); + }); + }); + + describe('listen', () => { + it('invokes listen without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var request = { + database: formattedDatabase, + }; + + // Mock response + var expectedResponse = {}; + + // Mock Grpc layer + client._innerApiCalls.listen = mockBidiStreamingGrpcMethod(request, expectedResponse); + + var stream = client.listen().on('data', response => { + assert.deepStrictEqual(response, expectedResponse); + done(); + }).on('error', err => { + done(err); + }); + + stream.write(request); + }); + + it('invokes listen with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedDatabase = client.databaseRootPath('[PROJECT]', '[DATABASE]'); + var request = { + database: formattedDatabase, + }; + + // Mock Grpc layer + client._innerApiCalls.listen = mockBidiStreamingGrpcMethod(request, null, error); + + var stream = client.listen().on('data', () => { + assert.fail(); + }).on('error', err => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + done(); + }); + + stream.write(request); + }); + }); + + describe('listCollectionIds', () => { + it('invokes listCollectionIds without error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var request = { + parent: formattedParent, + }; + + // Mock response + var nextPageToken = ''; + var collectionIdsElement = 'collectionIdsElement1368994900'; + var collectionIds = [collectionIdsElement]; + var expectedResponse = { + nextPageToken: nextPageToken, + collectionIds: collectionIds, + }; + + // Mock Grpc layer + client._innerApiCalls.listCollectionIds = (actualRequest, options, callback) => { + assert.deepStrictEqual(actualRequest, request); + callback(null, expectedResponse.collectionIds); + }; + + client.listCollectionIds(request, (err, response) => { + assert.ifError(err); + assert.deepStrictEqual(response, expectedResponse.collectionIds); + done(); + }); + }); + + it('invokes listCollectionIds with error', done => { + var client = new firestoreModule.v1beta1({ + credentials: {client_email: 'bogus', private_key: 'bogus'}, + projectId: 'bogus', + }); + + // Mock request + var formattedParent = client.anyPathPath('[PROJECT]', '[DATABASE]', '[DOCUMENT]', '[ANY_PATH]'); + var request = { + parent: formattedParent, + }; + + // Mock Grpc layer + client._innerApiCalls.listCollectionIds = mockSimpleGrpcMethod( + request, + null, + error + ); + + client.listCollectionIds(request, (err, response) => { + assert(err instanceof Error); + assert.strictEqual(err.code, FAKE_STATUS_CODE); + assert(typeof response === 'undefined'); + done(); + }); + }); + }); + +}); + +function mockSimpleGrpcMethod(expectedRequest, response, error) { + return function(actualRequest, options, callback) { + assert.deepStrictEqual(actualRequest, expectedRequest); + if (error) { + callback(error); + } else if (response) { + callback(null, response); + } else { + callback(null); + } + }; +} + +function mockServerStreamingGrpcMethod(expectedRequest, response, error) { + return actualRequest => { + assert.deepStrictEqual(actualRequest, expectedRequest); + var mockStream = through2.obj((chunk, enc, callback) => { + if (error) { + callback(error); + } + else { + callback(null, response); + } + }); + return mockStream; + }; +} + +function mockBidiStreamingGrpcMethod(expectedRequest, response, error) { + return () => { + var mockStream = through2.obj((chunk, enc, callback) => { + assert.deepStrictEqual(chunk, expectedRequest); + if (error) { + callback(error); + } + else { + callback(null, response); + } + }); + return mockStream; + } +}