@cesdk/node 1.76.0-nightly.20260521 → 1.76.0-nightly.20260522

package/index.d.ts

@@ -899,6 +899,35 @@ export declare interface AssetEnumProperty {
     options: string[];
 }
 
+/**
+ * Filter expression — predicate or logical combinator. Combinators nest
+ * arbitrarily. The union is mutually exclusive: an object with both
+ * `and` and `or`, or with `property` next to a combinator key, is
+ * rejected at the type level.
+ *
+ * Missing-key semantics for `not`: a predicate is `false` on an asset
+ * that lacks the targeted field, so a negated `meta.foo === 'x'` matches
+ * assets where `meta.foo !== 'x'` **and** assets that lack `meta.foo`
+ * entirely.
+ * @public
+ */
+export declare type AssetFilter = AssetPropertyFilter | {
+    and: AssetFilter[];
+    or?: never;
+    not?: never;
+    property?: never;
+} | {
+    or: AssetFilter[];
+    and?: never;
+    not?: never;
+    property?: never;
+} | {
+    not: AssetFilter;
+    and?: never;
+    or?: never;
+    property?: never;
+};
+
 /**
  * Asset transform preset payload fixed aspect ratio
  * @public
@@ -1007,6 +1036,39 @@ export declare interface AssetPayload {
  */
 export declare type AssetProperty = AssetBooleanProperty | AssetColorProperty | AssetEnumProperty | AssetNumberProperty | AssetStringProperty;
 
+/**
+ * A single property predicate. Exactly one of `contains` (case-insensitive
+ * substring) or `equals` (case-insensitive equality) must be set — the
+ * type forbids passing both or neither. On a string-array property
+ * (`tags`, `groups`), the operator matches if any element matches.
+ *
+ * `meta.<key>` values are flat strings in the engine; if a meta value
+ * was originally serialized as a number or boolean, stringify it the
+ * same way before comparing.
+ * @public
+ */
+export declare type AssetPropertyFilter = {
+    property: AssetPropertyPath;
+} & ({
+    contains: string;
+    equals?: never;
+} | {
+    equals: string;
+    contains?: never;
+});
+
+/**
+ * Dot-path against the resolved asset that a property predicate targets:
+ * `label`, `id`, `tags`, `groups`, or `meta.<key>` (one segment — meta
+ * values in the engine are flat strings).
+ *
+ * The template literal accepts `'meta.'` (empty key) because TypeScript's
+ * `${string}` includes the empty string; the engine rejects this at
+ * runtime with an explanatory error.
+ * @public
+ */
+export declare type AssetPropertyPath = 'label' | 'tags' | 'id' | 'groups' | `meta.${string}`;
+
 /**
  * Defines a request for querying assets
  * @public
@@ -1053,6 +1115,34 @@ export declare interface AssetQueryData {
      * Sort assets that are marked as active first.
      */
     sortActiveFirst?: boolean;
+    /**
+     * Optional structured filter, AND-combined with the result of `query` /
+     * `tags` / `groups` / `excludeGroups`. The top-level array is an implicit
+     * AND of its entries. Each entry is either a property predicate
+     * (`{ property, contains?, equals? }`) or a logical combinator
+     * (`{ and: [...] }`, `{ or: [...] }`, `{ not: ... }`). Combinators nest.
+     *
+     * **When to use `filter` vs `tags` / `groups` / `excludeGroups`:**
+     * The legacy `tags` / `groups` / `excludeGroups` fields remain
+     * supported and are equivalent to filter predicates with `equals` and
+     * implicit AND. Prefer `filter` for anything beyond a plain include/
+     * exclude list — case-insensitive substrings, `meta.<key>` matches,
+     * `or` / `not` combinators — and reach for the legacy fields only
+     * when you want their case-sensitive exact-match semantics.
+     *
+     * Malformed filters reject the returned promise with the engine's
+     * parse-error message (e.g. `"Unknown asset property '…'"`).
+     *
+     * @example
+     * ```ts
+     * filter: [
+     *   { property: 'label',          contains: 'Roboto' },
+     *   { property: 'meta.languages', contains: 'de' },
+     *   { not: { property: 'meta.legacy', equals: 'true' } }
+     * ]
+     * ```
+     */
+    filter?: AssetFilter[];
 }
 
 /**
@@ -8120,6 +8210,7 @@ declare interface FindAssetsQuery {
     sortingOrder: SortingOrder;
     sortKey: string;
     sortActiveFirst: boolean;
+    filter: AssetFilter[];
 }
 
 /**