@wix/sdk-types 1.14.0 → 1.17.0

package/build/browser/index.d.mts

@@ -58,6 +58,13 @@ type Host<Environment = unknown> = {
          */
         passThroughHeaders?: Record<string, string>;
     };
+    translations?: () => {
+        [language: string]: {
+            [namespace: string]: {
+                [key: string]: string;
+            };
+        };
+    } | undefined;
 };
 
 type HTTPMethod = 'POST' | 'GET' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
@@ -374,44 +381,6 @@ 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. */
-    limit?: number | null;
-    /**
-     * Pointer to the next or previous page in the list of results.
-     *
-     * Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response.
-     * Not relevant for the first request.
-     */
-    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
  */
@@ -444,10 +413,10 @@ type WQLFields<WQLGroup> = WQLGroup extends {
     fields: readonly string[];
 } ? WQLGroup['fields'][number] : never;
 /**
- * Sorting configuration for search results
- * @template Spec The search specification type
+ * Sorting configuration for search/query results
+ * @template Spec The WQL specification type
  */
-type Sorting<Spec extends SearchSpec> = Spec['wql'] extends {
+type Sorting<Spec extends WQLSpec> = Spec['wql'] extends {
     length: 0;
 } | [] ? {
     fieldName?: string;
@@ -505,42 +474,14 @@ interface WQL {
 }
 
 /**
- * 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']
- * };
+ * Base specification interface for APIs that support WQL (Wix Query Language)
  */
-interface SearchSpec {
+interface WQLSpec {
     /**
      * 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[];
 }
 
 /**
@@ -548,19 +489,11 @@ interface SearchSpec {
  */
 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
+ * Extracts all filterable field paths from a spec
+ * @template Spec The WQL 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;
+type FilterableFields<Spec extends WQLSpec> = Spec['wql'][number]['fields'][number];
 
 /**
  * Helper type to detect if a type is an enum-like union of string literals
@@ -575,25 +508,25 @@ type IsEnumLike<T> = T extends string | null | undefined ? string extends NonNul
  */
 type ApplicableOperators<Entity, Path extends string> = Path extends keyof Entity ? Entity[Path] extends string | null | undefined ? IsEnumLike<Entity[Path]> extends true ? EnumOperators : 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
+ * Determines allowed operators for a field based on the spec
  * @template Entity The entity type
- * @template Spec The search specification type
+ * @template Spec The WQL 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;
+type AllowedOperators<Entity, Spec extends WQLSpec, 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 Spec The WQL specification type
  * @template Field The field to filter on
  */
-type FilterOps<Entity, Spec extends SearchSpec, Field extends FilterableFields<Spec>> = Simplify<{
+type FilterOps<Entity, Spec extends WQLSpec, 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
+ * @template Spec The WQL specification type
  * @example
  * // Simple filter
  * const filter: Filter<Product, ProductSpec> = {
@@ -612,7 +545,7 @@ type FilterOps<Entity, Spec extends SearchSpec, Field extends FilterableFields<S
  *   ]
  * };
  */
-type Filter<Entity, Spec extends SearchSpec> = Simplify<{
+type Filter<Entity, Spec extends WQLSpec> = 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>[];
@@ -620,6 +553,78 @@ type Filter<Entity, Spec extends SearchSpec> = Simplify<{
     $not?: Filter<Entity, Spec>;
 }>;
 
+/**
+ * Cursor-based paging configuration
+ */
+interface CursorPaging {
+    /** Maximum number of items to return in the results. */
+    limit?: number | null;
+    /**
+     * Pointer to the next or previous page in the list of results.
+     *
+     * Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response.
+     * Not relevant for the first request.
+     */
+    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;
+} : {};
+
+/**
+ * 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 extends WQLSpec {
+    /**
+     * 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[];
+}
+
 /**
  * Type of scalar aggregation to perform
  */
@@ -727,6 +732,15 @@ type Aggregation<Spec extends SearchSpec> = BaseAggregationWithoutType<Spec> & {
     nested?: NestedAggregation<Spec>;
 };
 
+/**
+ * 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;
+
 /**
  * Configuration for full-text search functionality
  * @template Spec The search specification type
@@ -817,4 +831,61 @@ type BaseSearch<Entity, Spec extends SearchSpec> = {
  */
 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 MigrationOptions, 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 };
+/**
+ * Specification for a query API
+ * Defines what fields can be filtered and sorted
+ * @example
+ * interface MyQuerySpec extends QuerySpec {
+ *   wql: [{
+ *     operators: ['$eq', '$ne'],
+ *     fields: ['id', 'title'],
+ *     sort: 'BOTH'
+ *   }],
+ *   paging: 'offset', // or 'cursor' for cursor-based pagination
+ * };
+ */
+interface QuerySpec extends WQLSpec {
+    /**
+     * Supported paging type for this query API
+     * - 'cursor': Uses cursor-based pagination
+     * - 'offset': Uses offset-based pagination
+     */
+    paging: PagingType;
+}
+
+/**
+ * Complete query request for an entity type
+ * @template Entity The entity type being queried
+ * @template Spec The query specification type
+ * @example
+ * // Define a query type for products
+ * type QueryProducts = Query<Product, ProductQuerySpec>;
+ *
+ * // Create a query request with offset paging
+ * const query: QueryProducts = {
+ *   filter: { price: { $gte: 10 } },
+ *   sort: [{ fieldName: 'price', order: 'ASC' }],
+ *   paging: { limit: 20, offset: 0 }
+ * };
+ *
+ * // Or with cursor paging (if spec.paging = 'cursor')
+ * const query: QueryProducts = {
+ *   filter: { price: { $gte: 10 } },
+ *   sort: [{ fieldName: 'price', order: 'ASC' }],
+ *   cursorPaging: { limit: 20, cursor: "..." }
+ * };
+ */
+type Query<Entity, Spec extends QuerySpec> = {
+    /**
+     * Filter object.
+     * Learn more about the [filter section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language#the-filter-section).
+     */
+    filter?: Filter<Entity, Spec>;
+    /**
+     * List of sort objects.
+     * Learn more about the [sort section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language#the-sort-section).
+     */
+    sort?: Sorting<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 Filter, type FilterableFields, type GetNestedType, type HTTPMethod, type Host, type HostModule, type HostModuleAPI, type HttpClient, type HttpResponse, type MaybeContext, type Method, type MigrationOptions, type NonNullablePaths, type PublicMetadata, type Query, type QuerySpec, type RESTFunctionDescriptor, type RequestContext, type RequestOptions, type RequestOptionsFactory, type RestModuleMeta, SERVICE_PLUGIN_ERROR_TYPE, SORT_CAPABILITIES, SORT_DIRECTIONS, type Search, type SearchSpec, type ServicePluginContract, ServicePluginDefinition, type ServicePluginMethodInput, type ServicePluginMethodMetadata, type SortCapability, type SortOrder, type Sorting, type WQL, type WQLSpec };

package/build/browser/index.mjs

@@ -17,8 +17,21 @@ function ServicePluginDefinition(componentType, methods) {
   };
 }
 var SERVICE_PLUGIN_ERROR_TYPE = "wix_spi_error";
+
+// src/common/sort.ts
+var SORT_DIRECTIONS = {
+  ASC: "ASC",
+  DESC: "DESC"
+};
+var SORT_CAPABILITIES = {
+  ...SORT_DIRECTIONS,
+  BOTH: "BOTH",
+  NONE: "NONE"
+};
 export {
   EventDefinition,
   SERVICE_PLUGIN_ERROR_TYPE,
+  SORT_CAPABILITIES,
+  SORT_DIRECTIONS,
   ServicePluginDefinition
 };