@wix/sdk-types 1.17.2 → 1.17.4

package/build/browser/index.d.mts

@@ -562,7 +562,7 @@ type Filter<Entity, Spec extends WQLSpec> = Simplify<{
 /**
  * Cursor-based paging configuration
  */
-interface CursorPaging {
+interface CursorPaging$1 {
     /** Maximum number of items to return in the results. */
     limit?: number | null;
     /**
@@ -576,7 +576,7 @@ interface CursorPaging {
 /**
  * Offset-based paging configuration
  */
-interface OffsetPaging {
+interface OffsetPaging$1 {
     /** Number of items to load */
     limit?: number | null;
     /** Number of items to skip in the current sort order */
@@ -592,9 +592,9 @@ type PagingType = 'cursor' | 'offset';
 type Paging<Spec extends {
     paging?: PagingType;
 }> = Spec['paging'] extends 'cursor' ? {
-    cursorPaging: CursorPaging;
+    cursorPaging: CursorPaging$1;
 } : Spec['paging'] extends 'offset' ? {
-    paging: OffsetPaging;
+    paging: OffsetPaging$1;
 } : {};
 
 /**
@@ -837,6 +837,314 @@ type BaseSearch<Entity, Spec extends SearchSpec> = {
  */
 type Search<Entity, Spec extends SearchSpec> = BaseSearch<Entity, Spec> & Partial<Paging<Spec>>;
 
+interface PagingSpec {
+    paging: PagingType;
+}
+interface CursorPaging {
+    limit: number;
+    cursor?: string;
+}
+interface OffsetPaging {
+    limit: number;
+    offset?: number;
+}
+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 WQLSpec> {
+    readonly filter: Filter<T, S>;
+}
+/**
+ * Represents a sort expression
+ */
+interface SortExpression<S extends WQLSpec> {
+    readonly sort: Sorting<S>;
+}
+/**
+ * Extract fields that support a specific operator from the spec
+ */
+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 WQLSpec, Field extends string, Op extends string> = Field extends FieldsWithOperator<S, Op> ? true : false;
+/**
+ * Extract sortable fields from the spec
+ */
+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;
+/**
+ * Chainable field filter - extends FilterExpression so it can be used directly,
+ * but also allows chaining multiple operators on the same field.
+ * @example
+ * // Single operator - returns ChainableFieldFilter which is also FilterExpression
+ * Filter('price').gt(50)
+ *
+ * // Chained operators - combines into single field filter
+ * Filter('price').gt(50).lt(100)
+ * // Produces: { price: { $gt: 50, $lt: 100 } }
+ */
+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>;
+} : {}) & (HasOperator<S, Field & string, '$gt'> extends true ? {
+    gt(value: GetNestedType<T, Field & string>): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$gte'> extends true ? {
+    gte(value: GetNestedType<T, Field & string>): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$lt'> extends true ? {
+    lt(value: GetNestedType<T, Field & string>): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$lte'> extends true ? {
+    lte(value: GetNestedType<T, Field & string>): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$startsWith'> extends true ? {
+    startsWith(value: string): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$endsWith'> extends true ? {
+    endsWith(value: string): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$contains'> extends true ? {
+    contains(value: string): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$in'> extends true ? {
+    in(values: GetNestedType<T, Field & string>[]): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$nin'> extends true ? {
+    nin(values: GetNestedType<T, Field & string>[]): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$hasSome'> extends true ? {
+    hasSome(values: GetNestedType<T, Field & string>[]): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$hasAll'> extends true ? {
+    hasAll(values: GetNestedType<T, Field & string>[]): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$exists'> extends true ? {
+    exists(value?: boolean): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$isEmpty'> extends true ? {
+    isEmpty(value?: boolean): ChainableFieldFilter<T, S, Field>;
+} : {}) & (HasOperator<S, Field & string, '$ne'> extends true ? {
+    isNotEmpty(): ChainableFieldFilter<T, S, Field>;
+} : {});
+/**
+ * Filter methods for a specific field (alias for ChainableFieldFilter)
+ * Only shows methods for operators that the field supports
+ */
+type FieldFilter<T, S extends WQLSpec, Field extends FilterableFields<S>> = ChainableFieldFilter<T, S, Field>;
+/**
+ * Sort methods for a specific field
+ */
+interface FieldSort<S extends WQLSpec> {
+    asc(): SortExpression<S>;
+    desc(): SortExpression<S>;
+}
+/**
+ * Filter factory interface - creates filter expressions
+ * @example
+ * Filter('price').gt(50)
+ * Filter.and(Filter('title').eq('Product'), Filter('price').gt(50))
+ */
+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 */
+    and(...filters: FilterExpression<T, S>[]): FilterExpression<T, S>;
+    /** Combine filters with OR logic */
+    or(...filters: FilterExpression<T, S>[]): FilterExpression<T, S>;
+    /** Negate a filter */
+    not(filter: FilterExpression<T, S>): FilterExpression<T, S>;
+}
+/**
+ * Sort factory - creates sort expressions
+ * @example
+ * Sort('price').desc()
+ */
+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
@@ -894,4 +1202,59 @@ type Query<Entity, Spec extends QuerySpec> = {
     sort?: Sorting<Spec>[];
 } & Partial<Paging<Spec>>;
 
-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 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 };
+/**
+ * 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
+ * @template S - Query spec defining filterable/sortable fields
+ * @template R - Output type from build() (defaults to QueryRequest<T, S>)
+ * @example
+ * QueryBuilder()
+ *   .withFilter(Filter.and(
+ *     Filter('title').eq('Product'),
+ *     Filter('price').gt(50)
+ *   ))
+ *   .withFields('title', 'price')
+ *   .withSorting(Sort('price').desc())
+ *   .withPaging({ limit: 20, offset: 0 })
+ *   .build()
+ */
+interface QueryBuilder<T, S extends QuerySpec, R = QueryRequest<T, S>> {
+    /** Add a filter to the query */
+    withFilter(filter: FilterExpression<T, S>): QueryBuilder<T, S, R>;
+    /** Add field projection - return only specified fields */
+    withFields(...fields: (keyof T & string)[]): QueryBuilder<T, S, R>;
+    /** Add sorting to the query */
+    withSorting(...sorts: SortExpression<S>[]): QueryBuilder<T, S, R>;
+    /** Add paging to the query */
+    withPaging(paging: PagingFor<S>): QueryBuilder<T, S, R>;
+    /** Build the final query request object */
+    build(): R;
+}
+/**
+ * Complete set of query helpers for an entity
+ * This is what gets spread into module namespaces
+ * @template T - Entity type
+ * @template S - Query spec defining filterable/sortable fields
+ * @template R - Output type from QueryBuilder.build() (defaults to QueryRequest<T, S>)
+ */
+interface QueryHelpers<T, S extends QuerySpec, R = QueryRequest<T, S>> {
+    /** QueryBuilder factory */
+    QueryBuilder: () => QueryBuilder<T, S, R>;
+    /** Filter factory - creates filter expressions */
+    Filter: FilterFactory<T, S>;
+    /** Sort factory - creates sort expressions */
+    Sort: SortFactory<S>;
+}
+
+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 };