@wix/bex-utils 1.29.0 → 1.31.0

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/api/annotations.proto

@@ -37,7 +37,8 @@ extend google.protobuf.FieldOptions {
     optional Exposure field_exposure = 50106;
     optional Maturity field_maturity = 50107;
     optional bool pii = 50110; // Mark specific field as PII so clients that store the data know it should be encrypted
-    optional string referenced_entity = 50111; // FQDN of foreign keys. For example, an Order message that points to Product message can use it like this: `string product_id = 10 [(wix.api.referenced_entity) = "wix.stores.catalog.product"];`
+    optional string referenced_entity = 50111; // FQDN of foreign keys. For example, an Order message that points to Product message can use it like this: `string product_id = 10 [(wix.api.referenced_entity) = "wix.stores.catalog.v1.product"];`
+    optional ReferenceEntityField referenced_entity_field = 50112; // FQDN and path of a field that is referenced by `referenced_entity`. Should be located at same level or in a nested message with relation to `wix.api.referenced_entity`.
     optional Deprecated field_deprecated = 50143; // Mark a field as deprecated, optionally place replacing asset
     optional Translatable translatable = 50144; // Mark this field as translatable using MultiLingual services
     optional string sample_data = 50149; // Example of data that may be assigned as a value of this field
@@ -49,6 +50,10 @@ extend google.protobuf.EnumValueOptions {
     optional Exposure enum_exposure = 50131;
 }
 
+message ReferenceEntityField {
+    required string path = 1; // field path from root of a message annotated with `wix.api.entity` annotation. For example 'item.name'.
+}
+
 message CacheSettings {
     optional int32 max_age_seconds = 1; // default is 604800 seconds = 1 week
 }
@@ -167,6 +172,7 @@ message SearchMethodOptions {
     optional Paging paging = 2; // present paging mechanism info, default will be of type=`CURSOR`
     required Wql wql = 4; // mark fields that are available for filtering and sorting via WixQueryLanguage
     repeated string me_aliasable_field = 5; // collection of FQNs of fields that MAY be aliased with the const `"me"`
+    repeated Search search = 6; // mark fields that are available for search
 }
 
 message BulkCreateMethodOptions {
@@ -243,6 +249,7 @@ message Wql {
         ANY = 12 [deprecated = true]; // [Array] Matches arrays that contain at least one element specified in the query.
         HAS_SOME = 12; // [Array] Matches arrays that contain at least one element specified in the query.
         EMPTY = 13; // [Array] Matches arrays that contain no elements.
+        MATCH_ALL = 14; // [Array] match multiple fields within array with AND operator semantics.
     }
     enum Sort {
         NONE = 0; // no sorting enabled
@@ -272,6 +279,7 @@ message Wql {
         repeated string field = 5; // a collection of field paths that that accepts this operator
         optional Sort sort = 3; // sort type enabled for this glob
         repeated RequiredFields required_fields = 4; // fields that match this glob, can be used only if the query is also filtered by required_fields
+        optional Maturity maturity = 6;
     }
     // this field is deprecated due to a better and shorter naming
     repeated OperatorFieldSupport operator_field_support = 3 [(.wix.api.field_deprecated) = {
@@ -281,6 +289,11 @@ message Wql {
     repeated OperatorFieldSupport pattern = 4; // supported operators for subject query method
 }
 
+message Search {
+    repeated string field = 1; // a collection of field paths that supports Free Text Search
+    optional Maturity maturity = 2;
+}
+
 message Hookable {
 }
 

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/api/callback.proto

@@ -87,7 +87,7 @@ message Callback {
     }
 
     optional string topic = 1;
-    optional Segment.Segment segment = 8; // currently defaults to "legacy", will be `required` when legacy cluster is removed
+    optional Segment.SegmentName segment = 8; // currently defaults to "legacy", will be `required` when legacy cluster is removed
     optional string payload = 2;
     optional string permission = 3;  
     optional EventType event_type = 4;
@@ -131,7 +131,7 @@ message Segment {
      * However, new topics must provide a segment, or greyhound will throw an exception.
      * @see https://bo.wix.com/wix-docs/rnd/p13n-guidelines---aips/guidance-aips/design-patterns/[7016]-events#p13n-guidelines---aips_guidance-aips_design-patterns_[7016]-events_12-choose-the-right-segment
      */
-    enum Segment {
+    enum SegmentName {
         UNSPECIFIED = 0; // currently means "auto-resolved for old topics", will be forbidden when legacy cluster is removed
 
         /**

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/api/entity.proto

@@ -50,7 +50,7 @@ message Entity {
     optional Exposure exposure = 2 [deprecated=true];
     repeated MessageAppendix appendix_files = 3; // declare external configuration info
     optional string old_fqdn_for_backwards_compatibility = 4; // Topic name for domain events will be based on this attribute if present (only for known legacy FQDNs)
-    optional Segment.Segment segment = 5; // the cluster to which domain events will be produced
+    optional Segment.SegmentName segment = 5; // the cluster to which domain events will be produced
     repeated string implements = 6; // FQDNs of interfaces (i.e. SPIs) that this entity implements. Must begin with `wix.interfaces.`
     optional Extensible extensible = 7; // Indicates that this entity can be extended by apps using data-extension mechanism.
     optional bool trashbin = 8; // Indicates whether trash-bin is exposed on this entity.

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/api/subscription.proto

@@ -25,7 +25,8 @@ extend google.protobuf.MethodOptions {
 
 message Subscription {
     optional string topic = 1;
-    optional Segment.Segment segment = 4; // currently defaults to "legacy", will be `required` when legacy cluster is removed
+    optional Segment.SegmentName segment = 4; // currently defaults to "legacy", will be `required` when legacy cluster is removed
     optional bool batch = 2 [deprecated = true];
     optional string entity = 3;
+    optional bool dynamic = 5;
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/api/validations.proto

@@ -91,6 +91,7 @@ extend google.protobuf.MethodOptions {
     // example use:
     //    option (wix.api.writable) = "id"; // user-generated id is enabled
     repeated string writable = 50213;
+
 }
 
 extend google.protobuf.OneofOptions {
@@ -101,6 +102,8 @@ extend google.protobuf.OneofOptions {
 
 message AlignedWithEnum {
     required string field = 1;
+    // defaults to _options if not specified
+    optional string suffix = 2;
 }
 
 enum Format {
@@ -122,12 +125,10 @@ enum Format {
     DECIMAL_VALUE = 12;
     CURRENCY = 13; // 3 letters - all available currencies
     LANGUAGE_TAG = 14; // IETF BCP 47 language tag (e.g. en-US)
-    COLOR_HEX = 15;
+    COLOR_HEX = 15; // hex color format as defined by the MDN https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color
     LOCAL_DATE = 16; // ISO-8601 extended local date format (YYYY-MM-DD)
     LOCAL_TIME = 17; // ISO-8601 extended local time format (hh:mm[:ss][.sss])
     LOCAL_DATE_TIME = 18; // ISO-8601 extended local date-time format (YYYY-MM-DDThh:mm[:ss][.sss])
     URL_SLUG = 19;
     SYSTEM_SLUG = 20;
 }
-
-

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/catalog/api/v1/catalog.proto

@@ -48,9 +48,14 @@ service CatalogReadApi {
     rpc QueryProductsPlatformized (QueryProductsPlatformizedRequest) returns (QueryProductsPlatformizedResponse) {
         option (google.api.http) = {
             post: "/v1/products/query-platformized"
+            additional_bindings {
+                // for api cache
+                get: "/v1/products/query-platformized"
+            }
         };
+        option (wix.api.cacheable) = {};
         option (wix.api.permission).name = "WIX_STORES.READ_PRODUCTS";
-        option (wix.api.exposure) = INTERNAL;
+        option (wix.api.exposure) = PUBLIC;
         option (.wix.api.crud) = {
             method: QUERY
             query_options: {
@@ -92,6 +97,11 @@ service CatalogReadApi {
                         operator: ALL_APPLICABLE_OPERATORS
                         sort: BOTH
                     }
+                    operator_field_support: {
+                        glob: "priceData.price"
+                        operator: ALL_APPLICABLE_OPERATORS
+                        sort: BOTH
+                    }
                     operator_field_support: {
                         glob: "numericId"
                         operator: ALL_APPLICABLE_OPERATORS
@@ -145,9 +155,26 @@ service CatalogReadApi {
                 get: "/api/v1/products/{id}"
             }
         };
+        option (wix.api.cacheable) = {};
         option (wix.api.permission).name = "WIX_STORES.READ_PRODUCTS";
     }
 
+    // Retrieves a product with the provided ID.
+    rpc GetProductPlatformized (GetProductPlatformizedRequest) returns (GetProductPlatformizedResponse) {
+        option (wix.api.exposure) = PUBLIC;
+        option (google.api.http) = {
+            get: "/v1/products-platformized/{id}"
+        };
+        option (wix.api.permission).name = "WIX_STORES.READ_PRODUCTS";
+        option (.wix.api.crud) = {
+            method: GET_ITEM
+            get_options: {
+                id_field: "id"
+            }
+        };
+        option (wix.api.cacheable) = {};
+    }
+
     // Retrieves a list of up to 100 collections, given the provided paging, sorting and filtering.
     // See [Stores Pagination](https://dev.wix.com/api/rest/wix-stores/pagination) for more information.
     rpc QueryCollections (QueryCollectionsRequest) returns (QueryCollectionsResponse) {
@@ -239,6 +266,7 @@ service CatalogReadApi {
             get: "/v1/variants/{id}"
         };
         option (wix.api.maturity) = BETA;
+        option (wix.api.cacheable) = {};
         option (wix.api.permission).name = "WIX_STORES.READ_PRODUCTS";
     }
 
@@ -370,6 +398,19 @@ message GetProductResponse {
     Product product = 1;
 }
 
+message GetProductPlatformizedRequest {
+    // Requested product ID.
+    string id = 1 [(wix.api.minLength) = 1];
+    // Whether merchant specific data, such as cost and profit data, should be included in the response. Requires permissions to manage products.
+    bool include_merchant_specific_data = 2;
+}
+
+message GetProductPlatformizedResponse {
+    // Requested product data.
+    Product product = 1;
+}
+
+
 message QueryCollectionsRequest {
     // Query options.
     Query query = 1;
@@ -420,7 +461,7 @@ message GetCollectionResponse {
 message ProductOptionsAvailabilityRequest {
     // Requested product ID.
     string id = 1 [(wix.api.minLength) = 1];
-    // Set of key-value pairs. Array containing the selected options (e.g, color: Blue, size: Large).
+    // Array containing the selected options. For example, `["color": "Blue", "size": "Large"]`.
     map<string, string> options = 2;
 }
 
@@ -550,6 +591,24 @@ service CatalogWriteApi {
         option (wix.api.permission).name = "WIX_STORES.MODIFY_PRODUCTS";
     }
 
+    //Creates a new product.
+    rpc CreateProductPlatformized (CreateProductPlatformizedRequest) returns (CreateProductPlatformizedResponse) {
+        option (wix.api.required) = "CreateProductPlatformizedRequest.product.name";
+        option (wix.api.required) = "CreateProductPlatformizedRequest.product.priceData";
+        option (wix.api.required) = "CreateProductPlatformizedRequest.product.priceData.price";
+        option (wix.api.required) = "CreateProductPlatformizedRequest.product.cost_and_profit_data.item_cost";
+        option (wix.api.exposure) = PUBLIC;
+        option (google.api.http) = {
+            post: "/v1/products-platformized"
+        };
+        option (.wix.sdk.signature) = {params: "product"};
+        option (wix.api.permission).name = "WIX_STORES.MODIFY_PRODUCTS";
+       option (.wix.api.callback) = {
+         event_type: CREATED
+         permission: "WIX_STORES.READ_PRODUCTS"
+       };
+    }
+
     //Updates specified fields in a product.
     rpc UpdateProduct (UpdateProductRequest) returns (UpdateProductResponse) {
         option (wix.api.required) = "UpdateProductRequest.product.id";
@@ -560,6 +619,21 @@ service CatalogWriteApi {
         option (wix.api.permission).name = "WIX_STORES.MODIFY_PRODUCTS";
     }
 
+    //Updates specified fields in a product.
+    rpc UpdateProductPlatformized (UpdateProductPlatformizedRequest) returns (UpdateProductPlatformizedResponse) {
+        option (wix.api.required) = "UpdateProductPlatformizedRequest.product.id";
+        option (wix.api.required) = "UpdateProductPlatformizedRequest.product";
+        option (wix.api.exposure) = PUBLIC;
+        option (google.api.http) = {
+            patch: "/v1/products-platformized/{product.id}"
+        };
+        option (wix.api.permission).name = "WIX_STORES.MODIFY_PRODUCTS";
+        option (.wix.api.callback) = {
+          event_type: UPDATED
+          permission: "WIX_STORES.READ_PRODUCTS"
+        };
+    }
+
     //Deletes a product.
     rpc DeleteProduct (DeleteProductRequest) returns (DeleteProductResponse) {
         option (wix.api.required) = "DeleteProductRequest.id";
@@ -569,6 +643,20 @@ service CatalogWriteApi {
         option (wix.api.permission).name = "WIX_STORES.MODIFY_PRODUCTS";
     }
 
+    //Deletes a product.
+    rpc DeleteProductPlatformized (DeleteProductPlatformizedRequest) returns (DeleteProductPlatformizedResponse) {
+        option (wix.api.required) = "DeleteProductPlatformizedRequest.id";
+        option (wix.api.exposure) = PUBLIC;
+        option (google.api.http) = {
+            delete: "/v1/products-platformized/{id}"
+        };
+        option (wix.api.permission).name = "WIX_STORES.MODIFY_PRODUCTS";
+        option (.wix.api.callback) = {
+          event_type: DELETED
+          permission: "WIX_STORES.READ_PRODUCTS"
+        };
+    }
+
     //Deletes a bulk of products.
     rpc BulkDeleteProducts (BulkDeleteProductsRequest) returns (BulkDeleteProductsResponse) {
         option (wix.api.required) = "BulkDeleteProductsRequest.ids";
@@ -830,6 +918,14 @@ service CatalogWriteApi {
             data: "wix.catalog.api.v1.AllowedProductsCountLimitExceededErrorData"
         };
     }
+
+    rpc ReCloneStore(ReCloneStoreRequest) returns (ReCloneStoreResponse) {
+        option (.google.api.http).get = "/v1/reclone";
+        option (.wix.api.required) = "ReCloneStoreRequest.metasite_id";
+        option (.wix.api.permission).name = "WIX_STORES.RECLONE_STORE";
+        option (.wix.api.maturity) = ALPHA;
+        option (wix.api.exposure) = PRIVATE;
+    }
 }
 
 message CreateProductRequest {
@@ -841,6 +937,15 @@ message CreateProductResponse {
     Product product = 1;
 }
 
+message CreateProductPlatformizedRequest {
+    //Product information.
+    Product product = 1;
+}
+
+message CreateProductPlatformizedResponse {
+    Product product = 1;
+}
+
 message UpdateProductRequest {
     Product product = 1;
 }
@@ -849,6 +954,14 @@ message UpdateProductResponse {
     Product product = 1;
 }
 
+message UpdateProductPlatformizedRequest {
+    Product product = 1;
+}
+
+message UpdateProductPlatformizedResponse {
+    Product product = 1;
+}
+
 message DeleteProductRequest {
     //ID of the product to delete.
     string id = 1;
@@ -857,6 +970,14 @@ message DeleteProductRequest {
 message DeleteProductResponse {
 }
 
+message DeleteProductPlatformizedRequest {
+    //ID of the product to delete.
+    string id = 1;
+}
+
+message DeleteProductPlatformizedResponse {
+}
+
 message BulkDeleteProductsRequest {
     //IDs of the products to be deleted.
     repeated string ids = 1 [(wix.api.maxSize) = 1000];
@@ -878,7 +999,7 @@ message UpdateVariantsResponse {
 }
 
 message AddProductsToCollectionRequest {
-    //Collection ID. Cannot be used to add products to All Products
+    //Collection ID.
     string id = 1 [(wix.api.format) = GUID];
     //IDs of the products to add to the collection, separated by commas.
     repeated string product_ids = 2 [(wix.api.maxSize) = 1000];
@@ -888,7 +1009,7 @@ message AddProductsToCollectionResponse {
 }
 
 message RemoveProductsFromCollectionRequest {
-    //Collection ID. Cannot be used to remove products from All Products
+    //Collection ID.
     string id = 1 [(wix.api.format) = GUID];
     //IDs of the products to remove from the collection.
     repeated string product_ids = 2 [(wix.api.maxSize) = 1000];
@@ -1055,7 +1176,7 @@ message GetCollectionBySlugResponse {
 }
 
 message DeleteCollectionRequest {
-    // ID of the collection to delete. Cannot be used to delete All Products
+    // ID of the collection to delete.
     string id = 1 [(wix.api.format) = GUID];
 }
 
@@ -1179,7 +1300,20 @@ message PercentageData {
     // If `true`, result will be rounded to the nearest whole number.
     // If `false`, result will be rounded to 2 places after the decimal point.
     bool roundToInt = 1;
-    // Percentage value, as a whole number (integer) between `-100`` and `1000``.
-    // For example, pass `100`` to increase value by 100% (multiply original value by 2).
+    // Percentage value, as a whole number (integer) between `-100` and `1000`.
+    //
+    // For example: 
+    // + Pass `100` to increase value by 100% (multiply original value by 2).
+    // + Pass `1000` to increase value by 1000% (multiply original value by 10).
+    // + Pass `-50` to decrease value by 50% (original value is halved).
     int32 rate = 2 [(wix.api.min) = -100, (wix.api.max) = 1000];
 }
+
+message ReCloneStoreRequest {
+    // Description of value
+    google.protobuf.StringValue metasite_id = 1[(wix.api.format) = GUID];
+    google.protobuf.StringValue original_metasite_id = 2[(wix.api.format) = GUID];
+}
+
+message ReCloneStoreResponse {
+}

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/catalog/api/v1/product.proto

@@ -90,7 +90,7 @@ message Product {
     // Discount deducted from the product's original price.
     Discount discount = 20;
     // A list of all collection IDs that this product is included in (writable via the Catalog > Collection APIs).
-    repeated string collection_ids = 21 [(wix.api.readOnly) = true];
+    repeated string collection_ids = 21 [(wix.api.readOnly) = true, (.wix.api.referenced_entity) = "wix.stores.catalog.v1.collection"];
     // Product variants, will be provided if the the request was sent with the includeVariants flag.
     repeated Variant variants = 23 [(wix.api.readOnly) = true];
     // Date and time the product was last updated.
@@ -104,7 +104,7 @@ message Product {
     // Product brand. Including a brand name can help improve site and product [visibility on search engines](https://support.wix.com/en/article/adding-brand-names-to-boost-product-page-seo-in-wix-stores).
     google.protobuf.StringValue brand = 29 [(wix.api.minLength) = 1, (wix.api.maxLength) = 50];
     //tax group id
-    google.protobuf.StringValue tax_group_id = 35 [(wix.api.readOnly) = true, (wix.api.field_exposure) = INTERNAL];
+    google.protobuf.StringValue tax_group_id = 35 [(wix.api.format) = GUID, (wix.api.field_exposure) = INTERNAL];
     //internal field used by import/export to know how to link products in csv file to product ids
     string export_product_id = 36 [(wix.api.readOnly) = true, (wix.api.field_exposure) = PRIVATE, (wix.api.maxLength) = 100];
 }

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/catalog/api/v2/collectionRead.proto

@@ -24,9 +24,13 @@ service CollectionReadApi {
     rpc QueryCollections (QueryCollectionsRequest) returns (QueryCollectionsResponse) {
         option (google.api.http) = {
             post: "/v2/collections/query"
+            additional_bindings {
+                // for api cache
+                get: "/v2/collections/query"
+            }
         };
         option (wix.api.exposure) = INTERNAL;
-
+        option (wix.api.cacheable) = {};
         option (.wix.api.crud) = {
             method: QUERY
             query_options: {
@@ -51,8 +55,18 @@ service CollectionReadApi {
         option (google.api.http) = {
             get: "/v2/collections/{id}"
         };
+        option (wix.api.cacheable) = {};
         option (wix.api.crud).method = GET_ITEM;
     }
+
+    // Retrieves a collection with the provided slug.
+    rpc GetCollectionBySlug (GetCollectionBySlugRequest) returns (GetCollectionBySlugResponse) {
+        option (google.api.http) = {
+            get: "/v2/collections/slug/{slug}"
+        };
+        option (wix.api.cacheable) = {};
+        option (wix.api.required) = "GetCollectionBySlugRequest.slug";
+    }
 }
 
 message QueryCollectionsRequest {
@@ -73,3 +87,13 @@ message GetCollectionRequest {
 message GetCollectionResponse {
     wix.catalog.api.v1.Collection collection = 1;
 }
+
+message GetCollectionBySlugRequest {
+    // Slug of the collection to retrieve.
+    string slug = 1 [(wix.api.minLength) = 1, (wix.api.maxLength) = 100];
+}
+
+message GetCollectionBySlugResponse {
+    // The requested collection.
+    wix.catalog.api.v1.Collection collection = 1;
+}

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/common/bulk.proto

@@ -6,22 +6,23 @@ option java_multiple_files = true;
 option java_package = "com.wix.common";
 
 import "google/protobuf/wrappers.proto";
+import "wix/api/annotations.proto";
 import "wix/api/errors.proto";
 
 message BulkActionMetadata {
     // Number of items that were successfully processed.
-    uint32 total_successes = 1;
+    int32 total_successes = 1;
     // Number of items that couldn't be processed.
-    uint32 total_failures = 2;
+    int32 total_failures = 2;
     // Number of failures without details because detailed failure threshold was exceeded.
-    uint32 undetailed_failures = 3;
+    int32 undetailed_failures = 3;
 }
 
 message ItemMetadata {
     // Item ID. Should always be available, unless it's impossible (for example, when failing to create an item).
     google.protobuf.StringValue id = 1;
     // Index of the item within the request array. Allows for correlation between request and response items.
-    uint32 original_index = 2;
+    int32 original_index = 2;
     // Whether the requested action was successful for this item. When `false`, the `error` field is populated.
     bool success = 3;
     // Details about the error in case of failure.

package/@wix/ambassador-fedinfra-exportservice-v1-export-async-job/src/main/proto/wix/common/query.proto

@@ -171,8 +171,8 @@ enum ScalarType {
 message Aggregation {
     message RangeAggregation {
         message RangeBucket {
-            google.protobuf.Int32Value from = 1; // Inclusive lower bound of the range. Required if to is not given.
-            google.protobuf.Int32Value to = 2; // Exclusive upper bound of the range. Required if from is not given.
+            google.protobuf.DoubleValue from = 1; // Inclusive lower bound of the range. Required if to is not given.
+            google.protobuf.DoubleValue to = 2; // Exclusive upper bound of the range. Required if from is not given.
         }
         repeated RangeBucket buckets = 1;
     }
@@ -186,15 +186,39 @@ message Aggregation {
             DESC = 0;
             ASC = 1;
         }
+
+        enum MissingValues {
+            EXCLUDE = 0;
+            INCLUDE = 1;
+        }
+
+        message IncludeMissingValuesOptions {
+            string add_to_bucket = 1; // can specify custom bucket name. Defaults are [string -> "N/A"], [int -> "0"], [bool -> "false"] ...
+        }
+
         SortType sort_type = 1;
         SortDirection sort_direction = 2;
         google.protobuf.Int32Value limit = 3; // How many aggregations would you like to return? Can be between 1 and 250. 10 is the default.
+
+        MissingValues missing_values = 4; // should missing values be included or excluded from the aggregation results. Default is EXCLUDE
+        oneof options {
+            option (.wix.api.aligned_with_enum).field = "missing_values";
+            IncludeMissingValuesOptions include_options = 5; // options for including missing values
+        }
     }
 
     message ScalarAggregation {
         ScalarType type = 1;
     }
 
+    message GroupByAggregation {
+        google.protobuf.StringValue name = 1;
+        string field_path = 3;
+        oneof kind {
+            ValueAggregation value = 4;
+        }
+    }
+
     google.protobuf.StringValue name = 1;
     AggregationType type = 2;
     string field_path = 3;
@@ -203,6 +227,7 @@ message Aggregation {
         RangeAggregation range = 5;
         ScalarAggregation scalar = 6;
     }
+    GroupByAggregation group_by = 7;
 }
 
 message AggregationData {
@@ -217,8 +242,8 @@ message AggregationData {
 
         message RangeResults {
             message RangeAggregationResult {
-                google.protobuf.Int32Value from = 1;
-                google.protobuf.Int32Value to = 2;
+                google.protobuf.DoubleValue from = 1;
+                google.protobuf.DoubleValue to = 2;
                 int32 count = 3;
             }
             repeated RangeAggregationResult results = 1;
@@ -229,12 +254,34 @@ message AggregationData {
             double value = 2;
         }
 
+        message GroupByValueResults {
+            message NestedValueAggregationResult {
+                string value = 1;
+                NestedAggregationResults nested_results = 2;
+
+            }
+            repeated NestedValueAggregationResult results = 1;
+        }
+
+        message NestedAggregationResults {
+            string name = 1;
+            AggregationType type = 2;
+            string field_path = 6;
+            oneof result {
+                ValueResults values = 3;
+                RangeResults ranges = 4;
+                ScalarResult scalar = 5;
+            }
+        }
+
         string name = 1;
         AggregationType type = 2;
+        string field_path = 6;
         oneof result {
             ValueResults values = 3;
             RangeResults ranges = 4;
             ScalarResult scalar = 5;
+            GroupByValueResults grouped_by_value = 7;
         }
     }
 
@@ -414,4 +461,73 @@ message ProductSearchResponse {
       },
       products: [...]
 }
+
+// example Group By Aggregation Request:
+{
+  "filter" : {
+    "region" : "EU"
+  },
+  "aggregations" : [ {
+    "name" : "production countries",
+    "type" : "VALUE",
+    "fieldPath" : "production_countries",
+    "value" : {
+      "limit" : 5
+    },
+    "groupBy" : {
+      "name" : "production companies",
+      "fieldPath" : "production_companies",
+      "value" : { }
+    }
+  } ]
+}
+
+// example Group By Aggregation Response:
+{
+  "aggregations" : {
+    "results" : [ {
+      "name" : "production companies",
+      "type" : "VALUE",
+      "fieldPath" : "production_companies",
+      "groupedByValue" : {
+        "results" : [ {
+          "value" : "Warner Bros.",
+          "nestedResults" : {
+            "name" : "production countries",
+            "type" : "VALUE",
+            "fieldPath" : "production_countries",
+            "values" : {
+              "results" : [ {
+                "value" : "GB",
+                "count" : 221
+              }, {
+                "value" : "PL",
+                "count" : 12
+              } ]
+            }
+          }
+        }, {
+          "value" : "Metro-Goldwyn-Mayer (MGM)",
+          "nestedResults" : {
+            "name" : "production countries",
+            "type" : "VALUE",
+            "fieldPath" : "production_countries",
+            "values" : {
+              "results" : [ {
+                "value" : "SWE",
+                "count" : 24
+              }, {
+                "value" : "FR",
+                "count" : 18
+              }, {
+                "value" : "LT",
+                "count" : 2
+              } ]
+            }
+          }
+        } ]
+      }
+    } ]
+  }
+}
 */