@wix/bex-utils 2.71.0 → 2.72.0

package/@wix/ambassador-dealer-v1-serving-offer/src/main/proto/wix/api/api_errors.proto

@@ -0,0 +1,142 @@
+syntax = "proto2";
+
+package wix.api;
+
+import "google/protobuf/descriptor.proto";
+import "wix/api/annotations.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "ApiErrorsProto";
+option java_package = "com.wix.api";
+
+/**
+* Annotation for method returned errors.
+* Example usage:
+**/
+//import "google/protobuf/empty.proto";
+//service FooService {
+//  // Definition of a service-level error.
+//  // Accepts `markdown` and multiline.
+//  option (wix.api.error_def) = {
+//    http_code: FAILED_PRECONDITION
+//    application_code: "NO_FOO_SUPPLY"
+//  };
+//
+//  rpc CreateFoo (google.protobuf.Empty) returns (google.protobuf.Empty) {
+//    // Reference to a service-level error.
+//    option (wix.api.error_ref) = {
+//      application_code: "NO_FOO_SUPPLY"
+//    };
+//    // Definition of a method-level error.
+//    // Accepts `markdown` and multiline.
+//    option (wix.api.error) = {
+//      http_code: FAILED_PRECONDITION
+//      application_code: "NO_FOO_SUPPLY"
+//      data: "com.wixpress.foo.v1.NoFooSupplyError"
+//    };
+//    // You can specify multiple errors.
+//    option (wix.api.custom_validation_error) = {
+//      rule_name: "INVALID_NOTE"
+//      data: "com.wixpress.foo.v1.MyRuleViolationError"
+//    };
+//    // This method MAY throw standard crud errors of BULK_UPDATE method type.
+//    option (wix.api.inherit_crud_errors) = {
+//      method: BULK_UPDATE
+//    };
+//  }
+//}
+
+extend google.protobuf.ServiceOptions {
+  repeated Error error_def = 50600;
+}
+
+extend google.protobuf.MethodOptions {
+  repeated Error error = 50801;
+  repeated CustomValidationError custom_validation_error = 50802;
+  repeated InheritCrudErrors inherit_crud_errors = 50803;
+  repeated ErrorRef error_ref = 50804;
+}
+
+/**
+  ApplicationError: named Error for backwards compatibility
+**/
+message Error {
+  required StatusCodes.HttpStatusCode http_code = 1;
+  optional string application_code = 2;
+  optional string data = 3; // FQN path to the message that will be sent as payload for this error
+}
+
+/**
+  Method-level reference to a service-level error.
+**/
+message ErrorRef {
+  // Must match existing service-level error application code.
+  required string application_code = 1;
+}
+
+/**
+  CustomValidationError: field level validation, only declare when you have specific validation in your service that is not coming from infra
+**/
+message CustomValidationError {
+  required string rule_name = 1;
+  optional string data = 2; // FQN path to the message that will be sent as payload for this error
+}
+
+/**
+  InheritCrudErrors: does this method throw standard crud errors?
+**/
+message InheritCrudErrors {
+  required Crud.Method method = 1; // types of crud methods to inherit default errors from
+}
+
+message StatusCodes {
+  enum HttpStatusCode {
+    OK = 0; // 200
+
+    //Default error codes (applicable to all endpoints)
+
+    // 401 - Identity missing (missing, invalid or expired oAuth token,
+    // signed instance or cookies)
+    UNAUTHENTICATED = 1;
+
+    // 403 - Identity does not have the permission needed for this method / resource
+    PERMISSION_DENIED = 2;
+
+    // 400 - Bad Request. The client sent malformed body
+    // or one of the arguments was invalid
+    INVALID_ARGUMENT = 3;
+
+    // 404 - Resource does not exist
+    NOT_FOUND = 4;
+
+    // 500 - Internal Server Error
+    INTERNAL = 5;
+
+    // 503 - Come back later, server is currently unavailable
+    UNAVAILABLE = 6;
+
+    // 429 - The client has sent too many requests
+    // in a given amount of time (rate limit)
+    RESOURCE_EXHAUSTED = 7;
+
+    //Custom error codes - need to be documented
+
+    // 499 - Request cancelled by the client
+    CANCELED = 8;
+
+    // 409 - Can't recreate same resource or concurrency conflict
+    ALREADY_EXISTS = 9; //409
+
+    // 428 - request cannot be executed in current system state
+    // such as deleting a non-empty folder or paying with no funds
+    FAILED_PRECONDITION = 10;
+
+    //DO NOT USE IN WIX
+    // ABORTED = 11; // 409
+    // OUT_OF_RANGE = 12; // 400
+    // DEADLINE_EXEEDED = 13; // 504
+    // DATA_LOSS = 14; // 500
+    // UNIMPLEMENTED = 15; // 501
+  }
+}
+

package/@wix/ambassador-dealer-v1-serving-offer/src/main/proto/wix/api/callback.proto

@@ -0,0 +1,163 @@
+syntax = "proto2";
+
+package wix.api;
+
+import "google/protobuf/descriptor.proto";
+import "wix/api/annotations.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "CallbackProto";
+option java_package = "com.wix.api";
+
+/*
+callback option is used to denote two separate concepts:
+1. DomainEvents- these are events your service sends on all activities in your entity. Emitted as a result of this method.
+service BlooperService {
+   option (wix.api.service_entity).message = "com.wixpress.examples.Blooper"; //the "main" entity
+   rpc CreateBlooper (CreateBlooperRequest) returns (CreateBlooperResponse) {
+       option (wix.api.callback) = {
+           event_type: CREATED
+       };
+   };
+   rpc MissedBlooper (MissedBlooperRequest) returns (MissedBlooperResponse) {
+       option (wix.api.callback) = {
+           event_type: Action
+           payload: "com.wixpress.examples.BlooperWasMissed"
+       };
+   };
+}
+message Blooper {
+   option (wix.api.entity) = {
+       fqdn: "wix.examples.Blooper"
+   };
+}
+message BlooperWasMissed {
+    int32 how_funny_it_could_have_been = 1;
+}
+
+
+2. Kafka events that are internal to your domain and that are not related to a specific entity. Emitted as a result of this method.
+service BlooperService {
+   rpc Update (Request) returns (Response) {
+       option (wix.api.callback) = {
+           segment: USERS
+           topic: "Blooper.Update"
+           payload: "BlooperUpdateNotification" //name of the Message that is sent as event
+           permission: "Some.Permission" //permission required to consume this event as a webhook
+       };
+   };
+}
+*/
+extend google.protobuf.MethodOptions {
+    repeated Callback callback = 50000;
+    repeated Emits emits = 50001;
+}
+
+/*
+event option is used to denote two separate concepts:
+1. DomainEvents- these are events your service sends on all activities in your entity (see examples above)
+2. Kafka events that are internal to your domain and that are not related to a specific entity
+Both are emitted by the service, not necessarily as a result of a method call (some internal process of the service)
+Internal to domain event example:
+service BlooperService {
+   option (wix.api.event) = {
+       segment: PUBLIC
+       topic: "Blooper.Update"
+       payload: "BlooperUpdateNotification" //name of the Message that is sent as event
+       permission: "Some.Permission" //permission required to consume this event as a webhook
+   };
+   rpc Update (Request) returns (Response) {
+       //...
+   };
+}
+*/
+extend google.protobuf.ServiceOptions {
+    repeated Callback event = 50000;
+    repeated CallbackDeprecation event_deprecated = 50001;
+    // reserved 50002; TODO(aplus, 2024-08-13) remove when all artifact sync/GA
+}
+
+message Callback {
+    enum EventType {
+        UNKNOWN = 0;
+        CREATED = 1;
+        UPDATED = 2;
+        DELETED = 3;
+        ACTION = 4;
+    }
+
+    optional string topic = 1;
+    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;
+    optional Exposure exposure = 6;
+    optional Maturity maturity = 7;
+}
+
+message DomainEvent {
+    enum EventType {
+        UNKNOWN = 0;
+        CREATED = 1;
+        UPDATED = 2;
+        DELETED = 3;
+        ACTION = 4;
+    }
+    optional string action_message_fqn = 2; // Required when event_type == ACTION, otherwise must not be set
+    optional string webhook_permission_override = 3;
+    optional EventType event_type = 4;
+    optional Exposure exposure = 6;
+    optional Maturity maturity = 7;
+    optional string additional_metadata_fqn = 8;
+    optional DomainEventDeprecation deprecated = 9; // assigned and detailed where the subject event is deprecated
+}
+
+message Emits {
+    required DomainEvent.EventType event_type = 1;
+    optional string action_message_fqn = 2; // Required when event_type == ACTION, otherwise must not be set
+}
+
+message DomainEventDeprecation {
+    optional string replaced_by = 1;
+    optional string target_removal_date = 2;
+}
+
+message CallbackDeprecation {
+    optional string replaced_by = 1;
+    optional string target_removal_date = 2;
+    optional Callback.EventType event_type = 3;
+    optional string custom_slug = 4; // required when event_type=action
+    optional string payload = 5;
+}
+
+message Segment {
+
+    /**
+     * [Segment] annotation registers to Confluent clusters.
+     * Existing topics might have a hard-coded segment in Greyhound, so this option is not required in proto.
+     * 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 SegmentName {
+        UNSPECIFIED = 0; // currently means "auto-resolved for old topics", will be forbidden when legacy cluster is removed
+
+        /**
+         * For events that are consumed in 42 and uw2 only.
+         * This also includes a case where an event is produced from 84/AE1 via toMainDC
+         */
+        USERS = 1;
+
+        /**
+         * For events that are consumed in all DCs.
+         * This includes both cases where an event is published from 84/AE1 and cases where it's published from 42/uw2 and replicated via Raven to 84/AE1
+         */
+        PUBLIC = 2;
+
+        /**
+         * For DevEx services/migrations.
+         * Deployed on 42, uw2.
+         */
+        OTHERS = 3;
+    }
+}
+

package/@wix/ambassador-dealer-v1-serving-offer/src/main/proto/wix/api/context.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+package wix.api;
+
+option java_multiple_files = true;
+option java_outer_classname = "ContextProto";
+option java_package = "com.wix.api";
+
+message RequestContext {
+    map<string, string> aspects = 1;
+}
+
+message ResponseContext {
+    repeated ResponseContextEntry aspects = 1;
+}
+
+message ResponseContextEntry {
+    map<string, string> aspectEntry = 1;
+}

package/@wix/ambassador-dealer-v1-serving-offer/src/main/proto/wix/api/entity.proto

@@ -0,0 +1,127 @@
+syntax = "proto2";
+
+package wix.api;
+
+import "google/protobuf/descriptor.proto";
+import "wix/api/annotations.proto";
+import "wix/api/callback.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "EntityProto";
+option java_package = "com.wix.api";
+
+/*
+Marks that message X is the "main" entity of service Y
+Key requirement for DomainEvents used in callback/event
+
+package com.wixpress.examples;
+
+service BlooperService {
+    option (wix.api.service_entity).message = "com.wixpress.examples.Blooper"; // the "main" entity
+    rpc Update (BlooperRequest) returns (BlooperResponse) {
+        //...
+    };
+}
+
+message Blooper {
+   option (wix.api.entity) = {
+       fqdn: "wix.examples.Blooper" // A fully qualified domain name for this entity. Example: wix.stores.catalog.product, wix.bookings.session, wix.payments.transaction
+       exposure: PUBLIC // Optional exposure field. Will be used by systems like corvid and webhooks to decide if to expose events related to this entity to external parties
+   };
+}
+*/
+
+extend google.protobuf.ServiceOptions {
+    optional ServiceEntity service_entity = 50500;
+}
+
+message ServiceEntity {
+    required string message = 1;
+    optional string namespace = 50501; // use to avoid naming collisions between functions listed under the same fqdn/entity. Business Schema service shall use it using this hierarchy: [Entity > namespace > action]
+}
+
+extend google.protobuf.MessageOptions {
+    optional Entity entity = 50500;
+    repeated DomainEvent domain_event = 50501;
+}
+
+message Entity {
+    required string fqdn = 1;
+    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.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.
+    optional string plural = 9; // plural form of this entity. e.g. singular: `entity`; plural: `entities`;
+    optional string domain_events_read_permission = 10; // permission to consume all event types of this entity from topic. affects internal/external consumers. For external webhook subscribers - MAY be overridden by event/callback `permission` field.
+    optional string app_def_id = 11; // the app in devcenter that owns this entity
+    optional DomainEventOptions domain_events = 12;
+    optional Taggable taggable = 13; // Indicates whether this entity supports tagging
+    optional QueryOptions query_options = 14;
+    optional Exposure events_exposure = 15; // default events exposure, may be overridden in `wix.api.domain_event`
+    optional Maturity events_maturity = 16; // default events maturity, may be overridden in `wix.api.domain_event`
+    optional Persistence persistence = 17; // persistence config: type and tenancy model
+    optional PermissionCatalogOptions permission_options = 18; // options for permissions catalog auto generation
+}
+
+message PermissionCatalogOptions {
+    optional bool auto_generate_permissions = 1; // indicates whether to auto-generate permissions in the catalog for this entity
+    optional bool auto_generate_scopes = 2; // indicates whether to auto-generate scopes in the catalog for this entity
+}
+
+message Persistence {
+    enum Type {
+        STANDARD = 0; // multiple records per tenant
+        SINGLETON = 1; // single record per tenant
+        NONE = 2; // zero records per tenant - stateless
+    }
+    optional Type type = 1;
+}
+
+message Extensible {
+
+    optional string nested_extension_field_path = 1;
+    // Indicates whether this entity supports filtering by extended fields which are marked in schema as `x-wix-filterable`
+    optional bool filterable = 2;
+    repeated NestedExtensionPointMapping nested_extension_point_mappings = 3; // mappings for nested extensionPoint
+}
+
+message NestedExtensionPointMapping {
+    required string extension_point = 1; // the logical name of the extension point
+    required string path = 2; // the path to the parent object that contains the `extended_fields` field
+}
+
+message MessageAppendix {
+    enum Type {
+        UNKNOWN_APPENDIX_TYPE = 0;
+        AUTO_VELO = 1; // auto velo configuration
+        DOCS_CONF = 2; // wix docs configuration: `documentation.yaml`
+        MULTILINGUAL = 3; // wix multilingual configuration
+        SEARCH = 4; // nile search configuration
+        AUTO_SDK = 5; // auto sdk configuration 
+    }
+    required Type type = 1; // appendix type
+    required string path = 2; // absolute from module root
+}
+
+message DomainEventOptions {
+    optional bool event_sequence_number = 1; // indicated whenever `entity_event_sequence` in the envelope is set/populated for CUD events.
+    optional bool deleted_include_entity = 2; // indicated whenever `deleted_entity_as_json` is set/populated for EntityDeletedEvent events.
+    optional bool updated_include_modified_fields = 3; // indicated whenever `modified_fields` is set/populated for EntityUpdatedEvent events.
+}
+
+message Taggable {}
+
+message QueryOptions {
+    required Wql wql = 1; // mark fields that are available for filtering and sorting via WixQueryLanguage
+    repeated Search search = 2; // mark fields that are available for search
+    repeated NamedQueryOptions additional_query_options = 10; //additional query options
+}
+
+message NamedQueryOptions {
+    required string name  = 1; // additional options should be named
+    required Wql wql = 2; // mark fields that are available for filtering and sorting via WixQueryLanguage
+    repeated Search search = 3; // mark fields that are available for search
+}

package/@wix/ambassador-dealer-v1-serving-offer/src/main/proto/wix/api/errors.proto

@@ -0,0 +1,127 @@
+syntax = "proto3";
+
+package wix.api;
+
+option java_package = "com.wix.api";
+
+import "google/protobuf/struct.proto";
+import "google/protobuf/wrappers.proto";
+
+message Details {
+    oneof kind {
+        ApplicationError application_error = 1;
+        ValidationError validation_error = 2;
+        SystemError system_error = 4;
+    }
+    map<string, string> tracing = 3 [deprecated = true]; // deprecated in API's - to enable migration from rendering arbitrary tracing to rest response
+}
+
+message ApplicationError {
+    // Error code.
+    string code = 1;
+    // Description of the error.
+    string description = 2;
+    // Data related to the error.
+    google.protobuf.Struct data = 3;
+}
+
+message SystemError {
+    // Error code.
+    google.protobuf.StringValue errorCode = 1;
+}
+
+/**
+example result:
+{
+  "fieldViolations": [
+    {
+      "field": "fieldA",
+      "description": "invalid music note. supported notes: [do,re,mi,fa,sol,la,ti]",
+      "violatedRule": "OTHER",
+      "ruleName": "INVALID_NOTE",
+      "data": {
+        "value": "FI"
+      }
+    },
+    {
+      "field": "fieldB",
+      "description": "field value out of range. supported range: [0-20]",
+      "violatedRule": "MAX",
+      "data": {
+        "threshold": 20
+      }
+    },
+    {
+      "field": "fieldC",
+      "description": "invalid phone number. provide a valid phone number of size: [7-12], supported characters: [0-9, +, -, (, )]",
+      "violatedRule": "FORMAT",
+      "data": {
+        "type": "PHONE"
+      }
+    }
+  ]
+}
+**/
+message ValidationError {
+    enum RuleType {
+        VALIDATION = 0;
+        OTHER = 1;
+        MAX = 2;
+        MIN = 3;
+        MAX_LENGTH = 4;
+        MIN_LENGTH = 5;
+        MAX_SIZE = 6;
+        MIN_SIZE = 7;
+        FORMAT = 8;
+        DECIMAL_LTE = 9;
+        DECIMAL_GTE = 10;
+        DECIMAL_LT = 11;
+        DECIMAL_GT = 12;
+        DECIMAL_MAX_SCALE = 13;
+        INVALID_ENUM_VALUE = 14;
+        REQUIRED_FIELD = 15;
+        FIELD_NOT_ALLOWED = 16;
+        ONE_OF_ALIGNMENT = 17;
+        EXACT_LENGTH = 18;
+        EXACT_SIZE = 19;
+        REQUIRED_ONE_OF_FIELD = 20;
+    }
+    message FieldViolation {
+        string field = 1;
+        string description = 2;
+        RuleType violated_rule = 3;
+        google.protobuf.StringValue rule_name = 4; // applicable when violated_rule=OTHER
+        google.protobuf.Struct data = 5;
+    }
+    repeated FieldViolation field_violations = 1;
+}
+
+// for all kinds of min/max violations - match to type provided in annotation
+message LimitRuleInt32DataPayload {
+    int32 threshold = 1;
+}
+
+// for all kinds of min/max violations - match to type provided in annotation
+message LimitRuleDoubleDataPayload {
+    double threshold = 1;
+}
+
+// for all kinds of min/max violations - match to type provided in annotation
+message LimitRuleStringDataPayload {
+    string threshold = 1;
+}
+
+// for format violations
+message FormatRuleDataPayload {
+    string type = 1;
+}
+
+// for enum violations
+message EnumRuleDataPayload {
+    repeated string supported = 1;
+}
+
+// for required one-of violations
+message RequiredOneOfRuleDataPayload {
+    repeated string supported = 1;
+}

package/@wix/ambassador-dealer-v1-serving-offer/src/main/proto/wix/api/idempotency.proto

@@ -0,0 +1,25 @@
+syntax = "proto2";
+
+package wix.api;
+
+import "google/protobuf/descriptor.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "IdempotencyProto";
+option java_package = "com.wix.api";
+
+/* Idempotency annotation for Loom Prime
+Configures idempotency for the method.
+See ExecutionGuard README for more details: https://github.com/wix-private/server-infra/blob/master/aglianico/execution-guard/README.md#loom-prime-with-zero-code
+
+[NOTE]:
+The annotation affects only Loom Prime services.
+Any other service will ignore this annotation.
+*/
+extend google.protobuf.MethodOptions {
+    optional Idempotency idempotency = 50153;
+}
+
+message Idempotency {
+    optional string key = 1;
+}

package/@wix/ambassador-dealer-v1-serving-offer/src/main/proto/wix/api/permissions.proto

@@ -0,0 +1,46 @@
+syntax = "proto2";
+
+package wix.api;
+
+import "google/protobuf/descriptor.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "PermissionsProto";
+option java_package = "com.wix.api";
+
+/**
+* Annotation for method permission rules
+* example usage:
+* import "wix/api/permissions.proto";
+* service Bloop {
+*    rpc Create (CreateBloopRequest) returns (CreateBloopResponse) {
+*        option (wix.api.permission).name = "SOME_PERMISSION_NAME";
+*    }
+*    rpc SpecialDelete (SpecialDeleteBloopRequest) returns (SpecialDeleteResponse) {
+*        option (wix.api.permission) = {
+*           name: "SOME_PERMISSION_NAME"
+*           type: MANUAL
+*        }
+*    }
+* }
+**/
+extend google.protobuf.MethodOptions {
+    optional PermissionRule permission = 50301;
+    repeated PermissionRule additional_permission = 50302;
+}
+
+message PermissionRule {
+  optional string name = 1;
+  optional PermissionType type = 2;
+  optional AbacRequestValidationMode abac_request_validation = 3;
+}
+
+enum PermissionType {
+    AUTO = 0;
+    MANUAL = 1;
+}
+
+enum AbacRequestValidationMode {
+  ON = 0;
+  OFF = 1;
+}

package/@wix/ambassador-dealer-v1-serving-offer/src/main/proto/wix/api/sla.proto

@@ -0,0 +1,24 @@
+syntax = "proto2";
+
+package wix.api;
+
+import "google/protobuf/descriptor.proto";
+
+option java_multiple_files = true;
+option java_outer_classname = "SlaProto";
+option java_package = "com.wix.api";
+
+extend google.protobuf.MethodOptions {
+    optional Sla sla = 50700;
+}
+
+message Sla {
+    /*
+     * Number of milliseconds after which the method will timeout
+     * and return TIMEOUT (504) response for http or DEADLINE_EXCEEDED
+     * for grpc.
+     * This default deadline will be applied automatically
+     * if request does not contain deadline information.
+     */
+    optional int32 response_time_ms = 1;
+}