@wix/sdk-types 1.13.14 → 1.13.15

package/build/browser/index.d.mts

@@ -1,5 +1,5 @@
 import { MonitoringClient } from '@wix/monitoring-types';
-import { ConditionalExcept, EmptyObject, Simplify, Paths, SetRequiredDeep } from 'type-fest';
+import { ConditionalExcept, EmptyObject, Simplify, Paths, SetRequiredDeep, JsonObject } from 'type-fest';
 
 type HostModule<T, H extends Host> = {
     __type: 'host';
@@ -303,4 +303,469 @@ type NonNullablePaths<T, K extends Paths<T>> = globalThis.SDKTypeMode extends {
     strict: true;
 } ? SetRequiredDeep<T, K> : T;
 
-export { type APIMetadata, type AmbassadorFactory, type AmbassadorFunctionDescriptor, type AmbassadorRequestOptions, type AuthenticationStrategy, type BaseEventMetadata, type BoundAuthenticationStrategy, type BuildAmbassadorFunction, type BuildDescriptors, type BuildEventDefinition, type BuildRESTFunction, type BuildServicePluginDefinition, type Descriptors, EventDefinition, type EventHandler, type EventIdentity, type ExposeFieldsBasedOnToggle, type HTTPMethod, type Host, type HostModule, type HostModuleAPI, type HttpClient, type HttpResponse, type MaybeContext, type Method, type NonNullablePaths, type PublicMetadata, type RESTFunctionDescriptor, type RequestContext, type RequestOptions, type RequestOptionsFactory, type RestModuleMeta, SERVICE_PLUGIN_ERROR_TYPE, type ServicePluginContract, ServicePluginDefinition, type ServicePluginMethodInput, type ServicePluginMethodMetadata };
+/**
+ * Constant used to indicate all applicable operators for a field type
+ */
+declare const ALL_APPLICABLE_OPERATORS: "*";
+/**
+ * Operators available for string fields
+ */
+type StringOperators = '$eq' | '$ne' | '$gt' | '$lt' | '$gte' | '$lte' | '$isEmpty' | '$exists' | '$in' | '$nin' | '$startsWith';
+/**
+ * Operators available for number fields
+ */
+type NumberOperators = '$eq' | '$ne' | '$gt' | '$lt' | '$gte' | '$lte' | '$exists' | '$in' | '$nin';
+/**
+ * Operators available for boolean fields
+ */
+type BooleanOperators = '$eq' | '$ne' | '$exists' | '$in' | '$nin';
+/**
+ * Operators available for date fields
+ */
+type DateOperators = '$eq' | '$ne' | '$gt' | '$lt' | '$gte' | '$lte' | '$exists' | '$in' | '$nin';
+/**
+ * Operators available for object fields
+ */
+type ObjectOperators = '$exists';
+/**
+ * Base operators available for all array types
+ */
+type ArrayBaseOperators = '$isEmpty' | '$exists';
+/**
+ * Operators available for arrays of primitive values
+ */
+type ArrayOfPrimitivesOperators = '$hasAll' | '$hasSome' | ArrayBaseOperators;
+/**
+ * Operators available for arrays of objects
+ */
+type ArrayOfObjectsOperators = ArrayBaseOperators | '$matchItems';
+type OperatorsWithBooleanValues = '$isEmpty' | '$exists';
+type OperatorsWithArrayValues = '$in' | '$nin' | '$hasAll' | '$hasSome';
+type OperatorForArrayFiltering = '$matchItems';
+
+/**
+ * Cursor-based paging configuration
+ */
+interface CursorPaging {
+    /** Maximum number of items to return in the results (0-100) */
+    limit?: number | null;
+    /**
+     * Pointer to the next or previous page in the results
+     * Pass the cursor token from the pagingMetadata of the previous response
+     */
+    cursor?: string | null;
+}
+/**
+ * Offset-based paging configuration
+ */
+interface OffsetPaging {
+    /** Number of items to load */
+    limit?: number | null;
+    /** Number of items to skip in the current sort order */
+    offset?: number | null;
+}
+/**
+ * Supported paging types for search APIs
+ */
+type PagingType = 'cursor' | 'offset';
+/**
+ * Paging type based on the SearchSpec's paging type
+ */
+type Paging<Spec extends {
+    paging?: PagingType;
+}> = Spec['paging'] extends 'cursor' ? {
+    cursorPaging: CursorPaging;
+} : Spec['paging'] extends 'offset' ? {
+    paging: OffsetPaging;
+} : {};
+
+/**
+ * Sort direction type for requests
+ */
+type SortOrder = 'ASC' | 'DESC';
+/**
+ * Sort capability type for defining field sort options in SearchSpec
+ */
+type SortCapability = SortOrder | 'BOTH';
+/**
+ * Constants for sort directions
+ */
+declare const SORT_DIRECTIONS: {
+    readonly ASC: "ASC";
+    readonly DESC: "DESC";
+};
+/**
+ * Constants for sort capabilities
+ */
+declare const SORT_CAPABILITIES: {
+    readonly BOTH: "BOTH";
+    readonly ASC: "ASC";
+    readonly DESC: "DESC";
+};
+/**
+ * Helper type to get the fields from a WQL group
+ * @template WQLGroup The WQL group type
+ */
+type WQLFields<WQLGroup> = WQLGroup extends {
+    fields: readonly string[];
+} ? WQLGroup['fields'][number] : never;
+/**
+ * Sorting configuration for search results
+ * @template Spec The search specification type
+ */
+type Sorting<Spec extends SearchSpec> = Spec['wql'] extends {
+    length: 0;
+} | [] ? {
+    fieldName?: string;
+    order?: SortOrder;
+    selectItemsBy?: Record<string, any>[] | null;
+} : {
+    [WQLGroupIndex in keyof Spec['wql']]: Spec['wql'][WQLGroupIndex] extends {
+        fields: readonly string[];
+        sort: infer GroupSortCapability;
+    } ? GroupSortCapability extends typeof SORT_DIRECTIONS.ASC ? {
+        fieldName: WQLFields<Spec['wql'][WQLGroupIndex]>;
+        order: typeof SORT_DIRECTIONS.ASC;
+        selectItemsBy?: Record<string, any>[] | null;
+    } : GroupSortCapability extends typeof SORT_DIRECTIONS.DESC ? {
+        fieldName: WQLFields<Spec['wql'][WQLGroupIndex]>;
+        order: typeof SORT_DIRECTIONS.DESC;
+        selectItemsBy?: Record<string, any>[] | null;
+    } : GroupSortCapability extends typeof SORT_CAPABILITIES.BOTH ? {
+        fieldName: WQLFields<Spec['wql'][WQLGroupIndex]>;
+        order: SortOrder;
+        selectItemsBy?: Record<string, any>[] | null;
+    } : never : never;
+}[keyof Spec['wql']];
+
+/**
+ * Defines a group of fields that share the same operator and sorting capabilities
+ * This is part of the Wix Query Language (WQL) specification
+ * @example
+ * const wql: WQL = {
+ *   operators: ['$eq', '$ne', '$startsWith'],
+ *   fields: ['name', 'description'],
+ *   sort: 'BOTH'
+ * };
+ */
+interface WQL {
+    /**
+     * List of operators that can be used with these fields
+     * If not specified, uses ALL_APPLICABLE_OPERATORS
+     */
+    operators?: typeof ALL_APPLICABLE_OPERATORS | readonly string[];
+    /**
+     * List of fields that share these operator capabilities
+     * These fields can be used in filters and sorting
+     */
+    fields: readonly string[];
+    /**
+     * Sort capabilities for fields in this group
+     * If omitted, sorting is not allowed for these fields
+     */
+    sort?: SortCapability;
+}
+
+/**
+ * Specification for a search API
+ * Defines what fields can be filtered, sorted, searched, and aggregated
+ * @example
+ * interface MySearchSpec extends SearchSpec {
+ *   wql: [{
+ *     operators: ['$eq', '$ne'], // or 'typeof ALL_APPLICABLE_OPERATORS' for all operators that can be used based on the field type
+ *     fields: ['id', 'title'],
+ *     sort: 'BOTH' // or 'ASC' / 'DESC' for specific sorting
+ *   }],
+ *   paging: 'offset', // or 'cursor' for cursor-based pagination
+ *   searchable: ['title', 'description'],
+ *   aggregatable: ['category', 'price']
+ * };
+ */
+interface SearchSpec {
+    /**
+     * Groups of fields with shared operator and sorting capabilities
+     * Each group defines what operations can be performed on its fields
+     */
+    wql: readonly WQL[];
+    /**
+     * Supported paging type for this search API
+     * - 'cursor': Uses cursor-based pagination
+     * - 'offset': Uses offset-based pagination
+     */
+    paging: PagingType;
+    /**
+     * Fields that can be used for full-text search
+     * If not specified, all fields are searchable
+     */
+    searchable?: readonly string[];
+    /**
+     * Fields that can be used for aggregations
+     * These fields must be searchable and not contain PII
+     */
+    aggregatable?: readonly string[];
+}
+
+/**
+ * Gets the type of a field at a nested path
+ */
+type GetNestedType<Entity, Path extends string> = Path extends keyof Entity ? Entity[Path] extends (infer ArrayElement)[] | null | undefined ? ArrayElement : Exclude<Entity[Path], null | undefined> : Path extends `${infer FirstPathPart}.${infer RemainingPath}` ? FirstPathPart extends keyof Entity ? Entity[FirstPathPart] extends (infer ArrayElement)[] | null | undefined ? GetNestedType<NonNullable<ArrayElement>, RemainingPath> : Entity[FirstPathPart] extends object | null | undefined ? GetNestedType<NonNullable<Entity[FirstPathPart]>, RemainingPath> : never : never : never;
+/**
+ * Extracts all filterable field paths from a search spec
+ * @template Spec The search specification type
+ * // Results in a union type of all field paths that can be filtered
+ */
+type FilterableFields<Spec extends SearchSpec> = Spec['wql'][number]['fields'][number];
+/**
+ * Extracts all searchable field paths from a search spec
+ * @template Spec The search specification type
+ * // Results in a union type of all field paths that can be searched
+ */
+type SearchableFields<Spec extends SearchSpec> = Spec extends {
+    searchable: readonly string[];
+} ? Spec['searchable'][number] : string;
+
+/**
+ * Determines operators applicable to a field based on its type
+ * @template Entity The entity type
+ * @template Path The field path to check
+ */
+type ApplicableOperators<Entity, Path extends string> = Path extends keyof Entity ? Entity[Path] extends string | null | undefined ? StringOperators : Entity[Path] extends number | null | undefined ? NumberOperators : Entity[Path] extends boolean | null | undefined ? BooleanOperators : Entity[Path] extends Date | null | undefined ? DateOperators : Entity[Path] extends (infer E)[] | null | undefined ? E extends object ? ArrayOfObjectsOperators : ArrayOfPrimitivesOperators : Entity[Path] extends object | null | undefined ? ObjectOperators : never : Path extends `${infer K}.${infer R}` ? K extends keyof Entity ? Entity[K] extends (infer U)[] | null | undefined ? ApplicableOperators<NonNullable<U>, R> : Entity[K] extends object | null | undefined ? ApplicableOperators<NonNullable<Entity[K]>, R> : never : never : never;
+/**
+ * Determines allowed operators for a field based on the search spec
+ * @template Entity The entity type
+ * @template Spec The search specification type
+ * @template Field The field to check
+ */
+type AllowedOperators<Entity, Spec extends SearchSpec, Field extends FilterableFields<Spec>> = Spec['wql'][number] extends infer WQLGroup ? WQLGroup extends WQL ? Field extends WQLGroup['fields'][number] ? WQLGroup['operators'] extends typeof ALL_APPLICABLE_OPERATORS ? ApplicableOperators<Entity, Field & string> : WQLGroup['operators'] extends readonly string[] ? WQLGroup['operators'][number] : never : never : never : never;
+/**
+ * Filter operations type for individual field conditions
+ * @template Entity The entity type
+ * @template Spec The search specification type
+ * @template Field The field to filter on
+ */
+type FilterOps<Entity, Spec extends SearchSpec, Field extends FilterableFields<Spec>> = Simplify<{
+    [Op in AllowedOperators<Entity, Spec, Field>]?: Op extends OperatorsWithBooleanValues ? boolean : Op extends OperatorForArrayFiltering ? JsonObject[] : Op extends OperatorsWithArrayValues ? GetNestedType<Entity, Field & string>[] : GetNestedType<Entity, Field & string>;
+}>;
+/**
+ * Filter type for building type-safe query filters
+ * @template Entity The entity type
+ * @template Spec The search specification type
+ * @example
+ * // Simple filter
+ * const filter: Filter<Product, ProductSpec> = {
+ *   name: { $eq: 'iPhone' },
+ *   price: { $gte: 100 }
+ * };
+ *
+ * // Complex filter with logical operators
+ * const filter: Filter<Product, ProductSpec> = {
+ *   $and: [
+ *     { name: { $startsWith: 'i' } },
+ *     { $or: [
+ *       { price: { $lt: 1000 } },
+ *       { onSale: { $eq: true } }
+ *     ]}
+ *   ]
+ * };
+ */
+type Filter<Entity, Spec extends SearchSpec> = Simplify<{
+    [Field in FilterableFields<Spec>]?: AllowedOperators<Entity, Spec, Field> extends infer AllowedOps ? AllowedOps extends '$eq' ? GetNestedType<Entity, Field & string> | FilterOps<Entity, Spec, Field> : FilterOps<Entity, Spec, Field> : never;
+} | {
+    $and?: Filter<Entity, Spec>[];
+    $or?: Filter<Entity, Spec>[];
+    $not?: Filter<Entity, Spec>;
+}>;
+
+/**
+ * Type of scalar aggregation to perform
+ */
+type ScalarType = 'COUNT_DISTINCT' | 'MIN' | 'MAX' | 'SUM' | 'AVG';
+/**
+ * Sort type for value aggregations
+ */
+type ValueSortType = 'COUNT' | 'VALUE';
+/**
+ * Sort direction for value aggregations
+ */
+type ValueSortDirection = 'DESC' | 'ASC';
+/**
+ * Missing values handling for value aggregations
+ */
+type MissingValues = 'EXCLUDE' | 'INCLUDE';
+/**
+ * Date histogram interval
+ */
+type DateHistogramInterval = 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND';
+/**
+ * Range bucket for range aggregations
+ */
+interface RangeBucket {
+    from?: number | null;
+    to?: number | null;
+}
+/**
+ * Value aggregation configuration
+ */
+interface ValueAggregation {
+    sortType?: ValueSortType;
+    sortDirection?: ValueSortDirection;
+    limit?: number | null;
+    missingValues?: MissingValues;
+    includeOptions?: {
+        addToBucket?: string;
+    };
+}
+/**
+ * Range aggregation configuration
+ */
+interface RangeAggregation {
+    buckets?: RangeBucket[];
+}
+/**
+ * Scalar aggregation configuration
+ */
+interface ScalarAggregation {
+    type?: ScalarType;
+}
+/**
+ * Date histogram aggregation configuration
+ */
+interface DateHistogramAggregation {
+    interval?: DateHistogramInterval;
+}
+/**
+ * Base aggregation type that can be used for both top-level and nested aggregations
+ */
+type BaseAggregation<Spec extends SearchSpec> = {
+    name?: string | null;
+    fieldPath?: AggregatableFields<Spec>;
+} & ({
+    type?: 'VALUE';
+    value?: ValueAggregation;
+} | {
+    type?: 'RANGE';
+    range?: RangeAggregation;
+} | {
+    type?: 'SCALAR';
+    scalar?: ScalarAggregation;
+} | {
+    type?: 'DATE_HISTOGRAM';
+    dateHistogram?: DateHistogramAggregation;
+});
+/**
+ * Nested aggregation item
+ */
+type NestedAggregationItem<Spec extends SearchSpec> = BaseAggregation<Spec>;
+/**
+ * Nested aggregation configuration
+ */
+interface NestedAggregation<Spec extends SearchSpec> {
+    nestedAggregations?: NestedAggregationItem<Spec>[];
+}
+/**
+ * Extracts all aggregatable field paths from a search spec
+ * @template Spec The search specification type
+ */
+type AggregatableFields<Spec extends SearchSpec> = Spec extends {
+    aggregatable: readonly string[];
+} ? Spec['aggregatable'][number] : string;
+/**
+ * Base aggregation interface
+ * @template Spec The search specification type
+ */
+type Aggregation<Spec extends SearchSpec> = BaseAggregation<Spec> | {
+    type?: 'NESTED';
+    fieldPath?: AggregatableFields<Spec>;
+    nested?: NestedAggregation<Spec>;
+};
+
+/**
+ * Configuration for full-text search functionality
+ * @template Spec The search specification type
+ * @example
+ * const search: SearchDetails<MySearchSpec> = {
+ *   expression: 'urgent task',
+ *   mode: 'AND',
+ *   fields: ['title', 'description'],
+ *   fuzzy: true
+ * };
+ */
+interface SearchDetails<Spec extends SearchSpec> {
+    /**
+     * The search query text
+     * @example 'urgent task'
+     */
+    expression?: string | null;
+    /**
+     * How to combine multiple search terms
+     * - 'AND': All terms must match
+     * - 'OR': Any term can match
+     */
+    mode?: 'AND' | 'OR';
+    /**
+     * Fields to search within
+     * If not specified, searches all searchable fields
+     */
+    fields?: SearchableFields<Spec>[];
+    /**
+     * Whether to enable fuzzy matching
+     * Fuzzy matching allows for approximate matches
+     */
+    fuzzy?: boolean;
+}
+/**
+ * Base search request without paging
+ * @template Entity The entity type being searched
+ * @template Spec The search specification type
+ */
+type BaseSearch<Entity, Spec extends SearchSpec> = {
+    /**
+     * Filter conditions for the search
+     * @example { status: { $eq: 'PUBLISHED' } }
+     */
+    filter?: Filter<Entity, Spec>;
+    /**
+     * Sorting options for the results
+     * @example [{ fieldName: 'createdAt', order: 'DESC' }]
+     */
+    sort?: Sorting<Spec>[];
+    /**
+     * Full-text search configuration
+     * @example { expression: 'urgent', mode: 'AND' }
+     */
+    search?: SearchDetails<Spec>;
+    /**
+     * Aggregations for data analysis
+     * Aggregations provide summaries about data partitions
+     */
+    aggregations?: Aggregation<Spec>[];
+    /**
+     * Timezone for date-related queries
+     * Affects how date fields are interpreted
+     */
+    timeZone?: string | null;
+};
+/**
+ * Complete search request for an entity type
+ * @template Entity The entity type being searched
+ * @template Spec The search specification type
+ * @example
+ * // Define a search type for products
+ * type SearchProducts = Search<Product, ProductSearchSpec>;
+ *
+ * // Create a search request
+ * const search: SearchProducts = {
+ *   filter: { price: { $gte: 10 } },
+ *   sort: [{ fieldName: 'price', order: 'ASC' }],
+ *   search: { expression: 'shirt', mode: 'AND' },
+ *
+ *   // For offset paging:
+ *   paging: { limit: 20, offset: 0 }
+ *
+ *   // For cursor paging:
+ *   cursorPaging: { limit: 20, cursor: "..." }
+ * };
+ */
+type Search<Entity, Spec extends SearchSpec> = BaseSearch<Entity, Spec> & Partial<Paging<Spec>>;
+
+export { type APIMetadata, type AmbassadorFactory, type AmbassadorFunctionDescriptor, type AmbassadorRequestOptions, type AuthenticationStrategy, type BaseEventMetadata, type BoundAuthenticationStrategy, type BuildAmbassadorFunction, type BuildDescriptors, type BuildEventDefinition, type BuildRESTFunction, type BuildServicePluginDefinition, type Descriptors, EventDefinition, type EventHandler, type EventIdentity, type ExposeFieldsBasedOnToggle, type HTTPMethod, type Host, type HostModule, type HostModuleAPI, type HttpClient, type HttpResponse, type MaybeContext, type Method, type NonNullablePaths, type PublicMetadata, type RESTFunctionDescriptor, type RequestContext, type RequestOptions, type RequestOptionsFactory, type RestModuleMeta, SERVICE_PLUGIN_ERROR_TYPE, type Search, type SearchSpec, type ServicePluginContract, ServicePluginDefinition, type ServicePluginMethodInput, type ServicePluginMethodMetadata };