@wix/sdk-types 1.17.3 → 1.17.5

package/build/browser/index.d.mts

@@ -73,7 +73,12 @@ interface HttpClient {
     request<TResponse, TData = any>(req: RequestOptionsFactory<TResponse, TData>): Promise<HttpResponse<TResponse>>;
     fetchWithAuth: typeof fetch;
     wixAPIFetch: (relativeUrl: string, options: RequestInit) => Promise<Response>;
+    /** Returns the current access token synchronously, if available. */
     getActiveToken?: () => string | undefined;
+    /** Returns auth headers (may trigger token refresh). Prefer this over getActiveToken when making authenticated requests. */
+    getAuthHeaders?: () => Promise<{
+        headers: Record<string, string>;
+    }>;
 }
 type RequestOptionsFactory<TResponse = any, TData = any> = (context: any) => RequestOptions<TResponse, TData>;
 type HttpResponse<T = any> = {
@@ -837,63 +842,9 @@ type BaseSearch<Entity, Spec extends SearchSpec> = {
  */
 type Search<Entity, Spec extends SearchSpec> = BaseSearch<Entity, Spec> & Partial<Paging<Spec>>;
 
-/**
- * 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
-     */
+interface PagingSpec {
     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>>;
-
 interface CursorPaging {
     limit: number;
     cursor?: string;
@@ -902,42 +853,31 @@ interface OffsetPaging {
     limit: number;
     offset?: number;
 }
-type PagingFor<S extends QuerySpec> = S['paging'] extends 'cursor' ? CursorPaging : OffsetPaging;
-/**
- * The output type from QueryBuilder.build()
- * This is a plain object ready to be sent to an API
- */
-interface QueryRequest<T, S extends QuerySpec> {
-    filter?: Filter<T, S>;
-    sort?: Sorting<S>[];
-    paging?: PagingFor<S>;
-    /** Field projection - return only specified fields */
-    fields?: string[];
-}
+type PagingFor<S extends PagingSpec> = S['paging'] extends 'cursor' ? CursorPaging : OffsetPaging;
 /**
  * Represents a filter expression that can be combined with other filters
  */
-interface FilterExpression<T, S extends QuerySpec> {
+interface FilterExpression<T, S extends WQLSpec> {
     readonly filter: Filter<T, S>;
 }
 /**
  * Represents a sort expression
  */
-interface SortExpression<S extends QuerySpec> {
+interface SortExpression<S extends WQLSpec> {
     readonly sort: Sorting<S>;
 }
 /**
  * Extract fields that support a specific operator from the spec
  */
-type FieldsWithOperator<S extends QuerySpec, Op extends string> = S['wql'][number] extends infer Group ? Group extends WQL ? Group['operators'] extends readonly string[] ? Op extends Group['operators'][number] ? Group['fields'][number] : never : Group['fields'][number] : never : never;
+type FieldsWithOperator<S extends WQLSpec, Op extends string> = S['wql'][number] extends infer Group ? Group extends WQL ? Group['operators'] extends readonly string[] ? Op extends Group['operators'][number] ? Group['fields'][number] : never : Group['fields'][number] : never : never;
 /**
  * Check if a specific field supports a specific operator
  */
-type HasOperator<S extends QuerySpec, Field extends string, Op extends string> = Field extends FieldsWithOperator<S, Op> ? true : false;
+type HasOperator<S extends WQLSpec, Field extends string, Op extends string> = Field extends FieldsWithOperator<S, Op> ? true : false;
 /**
  * Extract sortable fields from the spec
  */
-type SortableFields<S extends QuerySpec> = S['wql'][number] extends infer Group ? Group extends {
+type SortableFields<S extends WQLSpec> = S['wql'][number] extends infer Group ? Group extends {
     fields: readonly string[];
     sort: 'ASC' | 'DESC' | 'BOTH';
 } ? Group['fields'][number] : never : never;
@@ -952,7 +892,7 @@ type SortableFields<S extends QuerySpec> = S['wql'][number] extends infer Group
  * Filter('price').gt(50).lt(100)
  * // Produces: { price: { $gt: 50, $lt: 100 } }
  */
-type ChainableFieldFilter<T, S extends QuerySpec, Field extends FilterableFields<S>> = FilterExpression<T, S> & (HasOperator<S, Field & string, '$eq'> extends true ? {
+type ChainableFieldFilter<T, S extends WQLSpec, Field extends FilterableFields<S>> = FilterExpression<T, S> & (HasOperator<S, Field & string, '$eq'> extends true ? {
     eq(value: GetNestedType<T, Field & string>): ChainableFieldFilter<T, S, Field>;
 } : {}) & (HasOperator<S, Field & string, '$ne'> extends true ? {
     ne(value: GetNestedType<T, Field & string>): ChainableFieldFilter<T, S, Field>;
@@ -989,11 +929,11 @@ type ChainableFieldFilter<T, S extends QuerySpec, Field extends FilterableFields
  * Filter methods for a specific field (alias for ChainableFieldFilter)
  * Only shows methods for operators that the field supports
  */
-type FieldFilter<T, S extends QuerySpec, Field extends FilterableFields<S>> = ChainableFieldFilter<T, S, Field>;
+type FieldFilter<T, S extends WQLSpec, Field extends FilterableFields<S>> = ChainableFieldFilter<T, S, Field>;
 /**
  * Sort methods for a specific field
  */
-interface FieldSort<S extends QuerySpec> {
+interface FieldSort<S extends WQLSpec> {
     asc(): SortExpression<S>;
     desc(): SortExpression<S>;
 }
@@ -1003,7 +943,7 @@ interface FieldSort<S extends QuerySpec> {
  * Filter('price').gt(50)
  * Filter.and(Filter('title').eq('Product'), Filter('price').gt(50))
  */
-interface FilterFactory<T, S extends QuerySpec> {
+interface FilterFactory<T, S extends WQLSpec> {
     /** Create a field-specific filter */
     <Field extends FilterableFields<S>>(field: Field): FieldFilter<T, S, Field>;
     /** Combine filters with AND logic */
@@ -1018,7 +958,266 @@ interface FilterFactory<T, S extends QuerySpec> {
  * @example
  * Sort('price').desc()
  */
-type SortFactory<S extends QuerySpec> = <Field extends SortableFields<S>>(field: Field) => FieldSort<S>;
+type SortFactory<S extends WQLSpec> = <Field extends SortableFields<S>>(field: Field) => FieldSort<S>;
+
+/**
+ * The output type from SearchBuilder.build()
+ * This is a plain object ready to be sent to an API
+ */
+interface SearchRequest<T, S extends SearchSpec> {
+    /** Filter object */
+    filter?: Filter<T, S>;
+    /** List of sort objects */
+    sort?: Sorting<S>[];
+    /** Full-text search parameters */
+    search?: SearchDetails<S>;
+    /** Aggregations to compute */
+    aggregations?: Aggregation<S>[];
+    /** Paging configuration */
+    paging?: PagingFor<S>;
+    /** Time zone for date operations */
+    timeZone?: string;
+}
+/**
+ * Represents a search expression that can be used in SearchBuilder
+ */
+interface SearchExpression<S extends SearchSpec> {
+    readonly search: SearchDetails<S>;
+}
+/**
+ * Represents an aggregation expression that can be used in SearchBuilder
+ */
+interface AggregationExpression<S extends SearchSpec> {
+    readonly aggregation: Aggregation<S>;
+}
+/**
+ * Builder for constructing search parameters
+ * @example
+ * SearchParams('dark shoes')
+ *   .mode('AND')
+ *   .fields(['productName', 'description'])
+ *   .fuzzy(true)
+ */
+interface SearchParamsBuilder<S extends SearchSpec> extends SearchExpression<S> {
+    /** Set the search expression/query string */
+    expression(expr: string): SearchParamsBuilder<S>;
+    /** Set the search mode (how to combine multiple terms) */
+    mode(mode: 'AND' | 'OR'): SearchParamsBuilder<S>;
+    /** Set the fields to search in */
+    fields(fields: SearchableFields<S>[]): SearchParamsBuilder<S>;
+    /** Enable or disable fuzzy matching */
+    fuzzy(enabled?: boolean): SearchParamsBuilder<S>;
+}
+/**
+ * Factory function for creating SearchParamsBuilder
+ * @param expression - Optional search expression to initialize with
+ */
+type SearchParamsFactory<S extends SearchSpec> = (expression?: string) => SearchParamsBuilder<S>;
+/**
+ * Sort configuration for value aggregations
+ */
+interface ValueAggregationSort {
+    sortBy(type: 'COUNT' | 'VALUE', direction: 'ASC' | 'DESC'): this;
+}
+/**
+ * Builder for VALUE type aggregations
+ */
+interface ValueAggregationBuilder<S extends SearchSpec> extends AggregationExpression<S>, ValueAggregationSort {
+    /** Set maximum number of buckets to return */
+    limit(count: number): ValueAggregationBuilder<S>;
+    /** Exclude documents with missing values */
+    excludeMissingValues(): ValueAggregationBuilder<S>;
+    /** Include documents with missing values */
+    includeMissingValues(): ValueAggregationBuilder<S>;
+    /** Include specific values in their own bucket */
+    includeValues(addToBucket: string): ValueAggregationBuilder<S>;
+}
+/**
+ * Builder for RANGE type aggregations
+ */
+interface RangeAggregationBuilder<S extends SearchSpec> extends AggregationExpression<S> {
+    /** Set the range buckets */
+    withBuckets(...buckets: {
+        from?: number | null;
+        to?: number | null;
+    }[]): RangeAggregationBuilder<S>;
+}
+/**
+ * Builder for DATE_HISTOGRAM type aggregations
+ */
+interface DateHistogramAggregationBuilder<S extends SearchSpec> extends AggregationExpression<S> {
+    /** Set the interval for date histogram buckets */
+    interval(interval: 'YEAR' | 'MONTH' | 'WEEK' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND'): DateHistogramAggregationBuilder<S>;
+}
+/**
+ * Builder for SCALAR type aggregations
+ */
+interface ScalarAggregationBuilder<S extends SearchSpec> extends AggregationExpression<S> {
+    /** Set the scalar aggregation type */
+    type(scalarType: 'COUNT_DISTINCT' | 'MIN' | 'MAX' | 'SUM' | 'AVG'): ScalarAggregationBuilder<S>;
+}
+/**
+ * Builder for NESTED type aggregations
+ */
+interface NestedAggregationBuilder<S extends SearchSpec> extends AggregationExpression<S> {
+    /** Add a nested aggregation */
+    addNestedAggregation(aggregation: AggregationExpression<S>): NestedAggregationBuilder<S>;
+}
+/**
+ * Aggregation type configuration
+ */
+type AggregationType = 'VALUE' | 'RANGE' | 'DATE_HISTOGRAM' | 'SCALAR' | 'NESTED';
+/**
+ * Builder for constructing aggregations
+ * @example
+ * Aggregation('status_count')
+ *   .ofType('VALUE')
+ *   .onField('status')
+ *   .asValueAggregation()
+ *   .sortBy('COUNT', 'DESC')
+ *   .limit(10)
+ */
+interface AggregationBuilder<S extends SearchSpec> extends AggregationExpression<S> {
+    /** Set the aggregation type */
+    ofType(type: AggregationType): AggregationBuilder<S>;
+    /** Set the field to aggregate on */
+    onField(field: AggregatableFields<S>): AggregationBuilder<S>;
+    /** Configure as a value aggregation */
+    asValueAggregation(): ValueAggregationBuilder<S>;
+    /** Configure as a range aggregation */
+    asRangeAggregation(): RangeAggregationBuilder<S>;
+    /** Configure as a date histogram aggregation */
+    asDateHistogramAggregation(): DateHistogramAggregationBuilder<S>;
+    /** Configure as a scalar aggregation */
+    asScalarAggregation(): ScalarAggregationBuilder<S>;
+    /** Configure as a nested aggregation */
+    asNestedAggregation(): NestedAggregationBuilder<S>;
+}
+/**
+ * Factory function for creating AggregationBuilder
+ */
+type AggregationFactory<S extends SearchSpec> = (name: string) => AggregationBuilder<S>;
+/**
+ * Search builder interface for constructing search requests
+ * @template T - Entity type
+ * @template S - Search spec defining filterable/sortable/searchable/aggregatable fields
+ * @template R - Output type from build() (defaults to SearchRequest<T, S>)
+ * @example
+ * SearchBuilder()
+ *   .withFilter(Filter.and(
+ *     Filter('title').eq('Product'),
+ *     Filter('price').gt(50)
+ *   ))
+ *   .withSearchClause(SearchParams('shoes').fuzzy(true))
+ *   .withAggregation(Aggregation('status_count').ofType('VALUE').onField('status'))
+ *   .withSorting(Sort('price').desc())
+ *   .withPaging({ limit: 20 })
+ *   .build()
+ */
+interface SearchBuilder<T, S extends SearchSpec, R = SearchRequest<T, S>> {
+    /** Add a filter to the search */
+    withFilter(filter: FilterExpression<T, S>): SearchBuilder<T, S, R>;
+    /** Add a search clause for full-text search */
+    withSearchClause(search: SearchExpression<S>): SearchBuilder<T, S, R>;
+    /** Add sorting to the search */
+    withSorting(...sorts: SortExpression<S>[]): SearchBuilder<T, S, R>;
+    /** Add aggregations to the search */
+    withAggregation(...aggregations: AggregationExpression<S>[]): SearchBuilder<T, S, R>;
+    /** Add paging to the search */
+    withPaging(paging: PagingFor<S>): SearchBuilder<T, S, R>;
+    /** Set the time zone for date operations */
+    withTimeZone(timeZone: string): SearchBuilder<T, S, R>;
+    /** Build the final search request object */
+    build(): R;
+}
+/**
+ * Complete set of search helpers for an entity
+ * This is what gets spread into module namespaces
+ * @template T - Entity type
+ * @template S - Search spec defining filterable/sortable/searchable/aggregatable fields
+ * @template R - Output type from SearchBuilder.build() (defaults to SearchRequest<T, S>)
+ */
+interface SearchHelpers<T, S extends SearchSpec, R = SearchRequest<T, S>> {
+    /** SearchBuilder factory */
+    SearchBuilder: () => SearchBuilder<T, S, R>;
+    /** Filter factory - creates filter expressions (reused from query) */
+    Filter: FilterFactory<T, S>;
+    /** Sort factory - creates sort expressions (reused from query) */
+    Sort: SortFactory<S>;
+    /** Search params factory - creates search expressions */
+    SearchParams: SearchParamsFactory<S>;
+    /** Aggregation factory - creates aggregation expressions */
+    Aggregation: AggregationFactory<S>;
+}
+
+/**
+ * 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>>;
+
+/**
+ * The output type from QueryBuilder.build()
+ * This is a plain object ready to be sent to an API
+ */
+interface QueryRequest<T, S extends QuerySpec> {
+    filter?: Filter<T, S>;
+    sort?: Sorting<S>[];
+    paging?: PagingFor<S>;
+    /** Field projection - return only specified fields */
+    fields?: string[];
+}
 /**
  * Query builder interface
  * @template T - Entity type
@@ -1063,4 +1262,4 @@ interface QueryHelpers<T, S extends QuerySpec, R = QueryRequest<T, S>> {
     Sort: SortFactory<S>;
 }
 
-export { type APIMetadata, type AccountInfo, type AmbassadorFactory, type AmbassadorFunctionDescriptor, type AmbassadorRequestOptions, type AuthenticationStrategy, type BaseEventMetadata, type BoundAuthenticationStrategy, type BuildAmbassadorFunction, type BuildDescriptors, type BuildEventDefinition, type BuildRESTFunction, type BuildServicePluginDefinition, type CursorPaging, type Descriptors, EventDefinition, type EventHandler, type EventIdentity, type ExposeFieldsBasedOnToggle, type FieldFilter, type FieldSort, type Filter, type FilterExpression, type FilterFactory, 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 OffsetPaging, type PagingFor, type PublicMetadata, type Query, type QueryBuilder, type QueryHelpers, type QueryRequest, 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 SortExpression, type SortFactory, type SortOrder, type Sorting, type WQL, type WQLSpec };
+export { type APIMetadata, type AccountInfo, type AggregatableFields, type Aggregation, type AggregationBuilder, type AggregationExpression, type AggregationFactory, type AggregationType, type AmbassadorFactory, type AmbassadorFunctionDescriptor, type AmbassadorRequestOptions, type AuthenticationStrategy, type BaseEventMetadata, type BoundAuthenticationStrategy, type BuildAmbassadorFunction, type BuildDescriptors, type BuildEventDefinition, type BuildRESTFunction, type BuildServicePluginDefinition, type CursorPaging, type DateHistogramAggregationBuilder, type Descriptors, EventDefinition, type EventHandler, type EventIdentity, type ExposeFieldsBasedOnToggle, type FieldFilter, type FieldSort, type Filter, type FilterExpression, type FilterFactory, type FilterableFields, type GetNestedType, type HTTPMethod, type Host, type HostModule, type HostModuleAPI, type HttpClient, type HttpResponse, type MaybeContext, type Method, type MigrationOptions, type NestedAggregationBuilder, type NonNullablePaths, type OffsetPaging, type PagingFor, type PublicMetadata, type Query, type QueryBuilder, type QueryHelpers, type QueryRequest, type QuerySpec, type RESTFunctionDescriptor, type RangeAggregationBuilder, type RequestContext, type RequestOptions, type RequestOptionsFactory, type RestModuleMeta, SERVICE_PLUGIN_ERROR_TYPE, SORT_CAPABILITIES, SORT_DIRECTIONS, type ScalarAggregationBuilder, type Search, type SearchBuilder, type SearchDetails, type SearchExpression, type SearchHelpers, type SearchParamsBuilder, type SearchParamsFactory, type SearchRequest, type SearchSpec, type SearchableFields, type ServicePluginContract, ServicePluginDefinition, type ServicePluginMethodInput, type ServicePluginMethodMetadata, type SortCapability, type SortExpression, type SortFactory, type SortOrder, type Sorting, type ValueAggregationBuilder, type ValueAggregationSort, type WQL, type WQLSpec };