@relyio/sdk 0.11.0 → 0.12.0

package/dist/{index-C73cK2Tt.d.ts → index-B9RfZVF1.d.ts}

@@ -1,4 +1,5 @@
-import { aJ as paths, Q as EntryMetadata, aK as components } from './define-content-type-ENAod5Ve.js';
+import './rich-text.d-rKmpgdGd.js';
+import { aW as paths, a5 as EntryMetadata, aX as components } from './include-paths-CrJNTsMl.js';
 
 /**
  * Where the SDK's transport gets its truth.
@@ -579,7 +580,7 @@ type DeclaresNoField<T> = [Exclude<keyof T, '_metadata'>] extends [never] ? true
  * Not the field's read type. The REST dialect (`fromRestWhere` in `@relyio/entry-reads`) reads a
  * bare value as `eq`, an array as `in` and an object as operators — refusing an object with none —
  * and drops `null`. So a list field (`tags`) is matched by one of its items, a reference by the
- * target's id, and a component or an expanded entry is never a value to send.
+ * target's id, and an object's value or an expanded entry is never a value to send.
  */
 type WhereScalar<V> = Exclude<V extends readonly (infer Item)[] ? Item : V, null | undefined | object>;
 /** One field's condition: a value (`eq`), a list of values (`in`), or operators. */

package/dist/{index-MLAFUuco.d.cts → index-BrvEg6-A.d.cts}

@@ -1,6 +1,6 @@
-import { K as MergedRelyIOConfig, A as ApiPath, c as ApiMethod, N as PathParamsOf, w as ApiResponse, W as Wire, v as RequestConfig, B as BaseContent, h as WhereClause, Q as QueryOptions, j as SortOptions, k as ContentQueryResult, C as CreateInput, U as UpdateInput, S as SDKError, H as BaseValidationError, G as ValidationViolation, R as RelyIOConfig, a as RelyIOConfigUpdate } from './index-BM42r4yg.cjs';
-import { aK as components, aJ as paths, W as InferContentType, aa as InferAssetType, a3 as InferSingleton } from './define-content-type-ENAod5Ve.cjs';
-import { a as SchemaDefinition, b as SchemaContentTypeNames, j as SchemaEntryOf, ax as FilterOperator, h as SchemaAssetTypeNames, c as SchemaSingletonNames, g as SchemaSettingsGroupNames, I as InferSettingsGroup, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-DqpipEHv.cjs';
+import { K as MergedRelyIOConfig, A as ApiPath, c as ApiMethod, N as PathParamsOf, w as ApiResponse, W as Wire, v as RequestConfig, B as BaseContent, h as WhereClause, Q as QueryOptions, j as SortOptions, k as ContentQueryResult, C as CreateInput, U as UpdateInput, S as SDKError, H as BaseValidationError, G as ValidationViolation, R as RelyIOConfig, a as RelyIOConfigUpdate } from './index-b-AkfTUv.cjs';
+import { W as Reading, _ as UntypedReading, M as CheckedIncludes, X as ReadWith, aX as components, aY as CheckedInclude, aW as paths, a6 as InferContentType, P as ContentReading, an as InferAssetType, J as AssetReading, ae as InferSingleton, Z as SingletonReading, aj as InferSettingsGroup, Y as SettingsReading } from './include-paths-CL4gHv6I.cjs';
+import { a as SchemaDefinition, b as SchemaContentTypeNames, j as SchemaEntryOf, al as FilterOperator, h as SchemaAssetTypeNames, c as SchemaSingletonNames, g as SchemaSettingsGroupNames, e as SchemaQueryNames, f as SchemaLocaleCodes } from './define-schema-DgctHlI2.cjs';
 import { VisitorResyncReason } from './live-visitor.js';
 import { DevUnreadableReason } from './dev-handshake/index.cjs';
 
@@ -288,7 +288,7 @@ type ExtendedQueryResult<T extends BaseContent = BaseContent> = ContentQueryResu
  *   .execute()
  * ```
  */
-declare class ContentQueryBuilder<T extends BaseContent = BaseContent, F extends BaseContent = T> {
+declare class ContentQueryBuilder<T extends BaseContent = BaseContent, F extends BaseContent = T, R extends Reading = UntypedReading<T>, I extends string = never> {
     private readonly httpClient;
     private readonly contentType;
     private queryOptions;
@@ -332,9 +332,14 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent, F extends
      */
     select(fields: NonNullable<QueryOptions<T, F>['select']>): this;
     /**
-     * Include related content in the response
+     * Expand references into the entries they point at: one include path per element (REL-1801).
+     * A path names fields through lists, page builders, objects and references —
+     * `'sections.features'`, `'sections.customers.logo'` — and may pick the fields each entry returns,
+     * `'sections.features(name,slug)'`. Each is checked against the schema: a path that holds no
+     * reference does not compile, and the read's type follows the paths — an expanded reference is the
+     * entry, every other one its id.
      */
-    include(relations: string[]): this;
+    include<const P extends readonly string[]>(paths: CheckedIncludes<R, P>): ContentQueryBuilder<Extract<ReadWith<R, I | P[number]>, BaseContent>, F, R, I | P[number]>;
     /**
      * Add sorting to the query
      *
@@ -477,7 +482,7 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent, F extends
     /**
      * Clone the query builder
      */
-    clone(): ContentQueryBuilder<T, F>;
+    clone(): ContentQueryBuilder<T, F, R, I>;
     /**
      * Get the current query options
      */
@@ -514,7 +519,7 @@ declare class ContentQueryBuilder<T extends BaseContent = BaseContent, F extends
 /**
  * Specialized query builder for finding by ID
  */
-declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
+declare class ContentByIdBuilder<T extends BaseContent = BaseContent, R extends Reading = UntypedReading<T>, I extends string = never> {
     private readonly httpClient;
     private readonly contentType;
     private readonly id;
@@ -541,9 +546,14 @@ declare class ContentByIdBuilder<T extends BaseContent = BaseContent> {
      */
     fresh(position: string): this;
     /**
-     * Include related content in the response
+     * Expand references into the entries they point at: one include path per element (REL-1801).
+     * A path names fields through lists, page builders, objects and references —
+     * `'sections.features'`, `'sections.customers.logo'` — and may pick the fields each entry returns,
+     * `'sections.features(name,slug)'`. Each is checked against the schema: a path that holds no
+     * reference does not compile, and the read's type follows the paths — an expanded reference is the
+     * entry, every other one its id. A second call adds to the first.
      */
-    include(relations: string[]): this;
+    include<const P extends readonly string[]>(paths: CheckedIncludes<R, P>): ContentByIdBuilder<Extract<ReadWith<R, I | P[number]>, BaseContent>, R, I | P[number]>;
     /**
      * Set locale for localized content
      * @param locale - Locale code (e.g., 'en-US', 'de-DE', 'fr-FR')
@@ -656,8 +666,11 @@ interface ContentFetchOptions<T extends BaseContent = BaseContent> {
     offset?: number;
     /** Sort configuration */
     sort?: Record<string, 'asc' | 'desc'>;
-    /** Reference fields to populate */
-    include?: string[];
+    /**
+     * Include paths: the references to expand (REL-1801) — see `ContentQueryBuilder.include`. Typed
+     * where `fetch` is called with them inline.
+     */
+    include?: readonly string[];
     /** Locale for localized content */
     locale?: string;
     /** Fields to select (projection) */
@@ -685,7 +698,7 @@ interface ContentFetchOptions<T extends BaseContent = BaseContent> {
  * const all = await products.fetchAll()
  * ```
  */
-declare class ContentClient<T extends BaseContent = BaseContent> {
+declare class ContentClient<T extends BaseContent = BaseContent, R extends Reading = UntypedReading<T>> {
     private readonly httpClient;
     private readonly contentType;
     /** The client's locale, asked on every call rather than copied when this client was taken. */
@@ -698,11 +711,11 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
     /**
      * Create a new query builder for this content type
      */
-    query(): ContentQueryBuilder<T>;
+    query(): ContentQueryBuilder<T, T, R>;
     /**
      * Find content by ID with fluent options
      */
-    findById(id: string): ContentByIdBuilder<T>;
+    findById(id: string): ContentByIdBuilder<T, R>;
     /**
      * Fetch all content items
      * @param locale - Optional locale for localized content
@@ -711,15 +724,22 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
     /**
      * Fetch content with query options
      */
-    fetch(options?: ContentFetchOptions<T>): Promise<T[]>;
+    fetch<const P extends readonly string[]>(options: Omit<ContentFetchOptions<T>, 'include'> & {
+        include: CheckedIncludes<R, P>;
+    }): Promise<Array<ReadWith<R, P[number]>>>;
+    fetch(options?: Omit<ContentFetchOptions<T>, 'include'>): Promise<T[]>;
     /**
      * Fetch a single content item by ID
      * @param id - Entry ID or slug
      * @param options - Fetch options (include, locale, and `headers` this one request adds — e.g.
      *   `{ 'X-RelyIO-Dataset': 'staging' }` to read a dataset other than the client's)
      */
+    fetchOne<const P extends readonly string[]>(id: string, options: {
+        include: CheckedIncludes<R, P>;
+        locale?: string;
+        headers?: Record<string, string>;
+    }): Promise<ReadWith<R, P[number]> | null>;
     fetchOne(id: string, options?: {
-        include?: string[];
         locale?: string;
         headers?: Record<string, string>;
     }): Promise<T | null>;
@@ -741,8 +761,15 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
      * whether the entry, the content type or the schema was missing. `headers`
      * are the ones this read adds, as for `fetchOne`.
      */
+    fetchOneWithTag<const P extends readonly string[]>(id: string, options: {
+        include: CheckedIncludes<R, P>;
+        locale?: string;
+        headers?: Record<string, string>;
+    }): Promise<{
+        entry: ReadWith<R, P[number]>;
+        entityTag?: string;
+    }>;
     fetchOneWithTag(id: string, options?: {
-        include?: string[];
         locale?: string;
         headers?: Record<string, string>;
     }): Promise<{
@@ -853,7 +880,7 @@ declare class ContentClient<T extends BaseContent = BaseContent> {
      * Create a new ContentClient with a different default locale, fixed: an update of the client's
      * locale (`updateConfig({ locale })`) does not reach it
      */
-    withLocale(locale: string): ContentClient<T>;
+    withLocale(locale: string): ContentClient<T, R>;
     /**
      * Get the default locale as it is now: the client's, or the one `withLocale()` fixed
      */
@@ -1292,7 +1319,15 @@ declare class AssetUploadBuilder<T extends BaseContent = BaseContent> {
  * over the same dynamic `/{assetType}` routes — assets are `entryType: 'asset'`
  * entries) and adds the `file(uid)` sub-resource builder + an `upload()` helper.
  */
-declare class AssetClient<T extends BaseContent = BaseContent> {
+/**
+ * An asset read typed by the asset type's reading `R`: what the type's include paths make of its
+ * fields, beside the `file` and `urls` blocks every asset read carries (REL-1801).
+ */
+interface AssetResponseReading<R extends Reading> extends Reading {
+    readonly read: AssetEntryResponse<Extract<ReadWith<R, this['include']>, BaseContent>>;
+    readonly checked: CheckedInclude<R, this['path']>;
+}
+declare class AssetClient<T extends BaseContent = BaseContent, R extends Reading = UntypedReading<T>> {
     private readonly httpClient;
     private readonly assetType;
     /** The client's locale, asked on every call rather than copied when this client was taken. */
@@ -1306,12 +1341,15 @@ declare class AssetClient<T extends BaseContent = BaseContent> {
      * Create a query builder for this asset type. It resolves asset reads; its conditions name the
      * asset type's fields, which the `file` and `urls` blocks are not.
      */
-    query(): ContentQueryBuilder<AssetEntryResponse<T>, T>;
+    query(): ContentQueryBuilder<AssetEntryResponse<T>, T, AssetResponseReading<R>>;
     /** Find an asset entry by id (or slug) with fluent options. */
-    findById(id: string): ContentByIdBuilder<AssetEntryResponse<T>>;
+    findById(id: string): ContentByIdBuilder<AssetEntryResponse<T>, AssetResponseReading<R>>;
     /** Fetch a single asset entry by id (or slug), or `null` if not found. */
+    fetchOne<const P extends readonly string[]>(id: string, options: {
+        include: CheckedIncludes<R, P>;
+        locale?: string;
+    }): Promise<ReadWith<AssetResponseReading<R>, P[number]> | null>;
     fetchOne(id: string, options?: {
-        include?: string[];
         locale?: string;
     }): Promise<AssetEntryResponse<T> | null>;
     /** Fetch the first asset entry matching the conditions, or `null`. */
@@ -1369,8 +1407,11 @@ type PopulatedAssetReference<T extends BaseContent = BaseContent> = AssetEntryRe
 interface SingletonFetchOptions {
     /** Locale for localized content */
     locale?: string;
-    /** Reference fields to populate */
-    include?: string[];
+    /**
+     * Include paths: the references to expand (REL-1801), added to the ones `include()` named — see
+     * `include()`. Typed where the call names them inline.
+     */
+    include?: readonly string[];
     /**
      * The feed position this read follows — a change's `fresh` (`FeedChange`), or a resync's. Sent as
      * `?_fresh`: no cache holds an answer for it from before that position, so the read is answered
@@ -1395,7 +1436,7 @@ interface SingletonFetchOptions {
  *   .fetch()
  * ```
  */
-declare class SingletonClient<T = unknown> {
+declare class SingletonClient<T = unknown, R extends Reading = UntypedReading<T>, I extends string = never> {
     private httpClient;
     private singletonKey;
     private includeFields?;
@@ -1408,10 +1449,14 @@ declare class SingletonClient<T = unknown> {
      */
     constructor(httpClient: HttpClient, singletonKey: string, locale?: ClientLocale);
     /**
-     * Include reference fields in the response
-     * @param fields - Reference field names to populate
+     * Expand references into the entries they point at: one include path per element (REL-1801).
+     * A path names fields through lists, objects and references — `'hero.media.image'`,
+     * `'featured.author'` — and may pick the fields each entry returns, `'featured(title,slug)'`.
+     * Each is checked against the schema: a path that holds no reference does not compile, and the
+     * read's type follows the paths — an expanded reference is the entry, every other one its id. A
+     * second call adds to the first.
      */
-    include(fields: string[]): this;
+    include<const P extends readonly string[]>(paths: CheckedIncludes<R, P>): SingletonClient<ReadWith<R, I | P[number]>, R, I | P[number]>;
     /**
      * Set locale for localized content
      * @param locale - Locale code (e.g., 'en', 'de', 'fr')
@@ -1421,7 +1466,10 @@ declare class SingletonClient<T = unknown> {
      * Fetch the singleton content
      * @param options - Optional fetch options (alternative to fluent methods)
      */
-    fetch(options?: SingletonFetchOptions): Promise<T | null>;
+    fetch<const P extends readonly string[]>(options: Omit<SingletonFetchOptions, 'include'> & {
+        include: CheckedIncludes<R, P>;
+    }): Promise<ReadWith<R, I | P[number]> | null>;
+    fetch(options?: Omit<SingletonFetchOptions, 'include'>): Promise<T | null>;
     /**
      * Fetch the singleton **and the entity tag that read served**, which is what
      * `update`'s `ifMatch` takes (`INV-API-CONDITIONAL-WRITE-IS-REACHABLE`).
@@ -1479,7 +1527,7 @@ declare class SingletonClient<T = unknown> {
     /**
      * Reset fluent options for reuse
      */
-    reset(): this;
+    reset(): SingletonClient<ReadWith<R, never>, R>;
 }
 
 /**
@@ -1488,8 +1536,11 @@ declare class SingletonClient<T = unknown> {
 interface SettingsFetchOptions {
     /** Locale for localized settings */
     locale?: string;
-    /** Reference fields to populate */
-    include?: string[];
+    /**
+     * Include paths: the references to expand (REL-1801), added to the ones `include()` named — see
+     * `include()`. Typed where the call names them inline.
+     */
+    include?: readonly string[];
 }
 /**
  * Settings client for managing settings group operations
@@ -1508,7 +1559,7 @@ interface SettingsFetchOptions {
  *   .fetch()
  * ```
  */
-declare class SettingsClient<T = unknown> {
+declare class SettingsClient<T = unknown, R extends Reading = UntypedReading<T>, I extends string = never> {
     private readonly httpClient;
     private readonly groupId;
     private includeFields?;
@@ -1521,10 +1572,14 @@ declare class SettingsClient<T = unknown> {
      */
     constructor(httpClient: HttpClient, groupId: string, locale?: ClientLocale);
     /**
-     * Include reference fields in the response
-     * @param fields - Reference field names to populate
+     * Expand references into the entries they point at: one include path per element (REL-1801).
+     * A path names fields through lists, objects and references — `'hero.media.image'`,
+     * `'featured.author'` — and may pick the fields each entry returns, `'featured(title,slug)'`.
+     * Each is checked against the schema: a path that holds no reference does not compile, and the
+     * read's type follows the paths — an expanded reference is the entry, every other one its id. A
+     * second call adds to the first.
      */
-    include(fields: string[]): this;
+    include<const P extends readonly string[]>(paths: CheckedIncludes<R, P>): SettingsClient<ReadWith<R, I | P[number]>, R, I | P[number]>;
     /**
      * Set locale for localized settings
      * @param locale - Locale code (e.g., 'en', 'de', 'fr')
@@ -1534,7 +1589,10 @@ declare class SettingsClient<T = unknown> {
      * Fetch the settings group
      * @param options - Optional fetch options (alternative to fluent methods)
      */
-    fetch(options?: SettingsFetchOptions): Promise<T | null>;
+    fetch<const P extends readonly string[]>(options: Omit<SettingsFetchOptions, 'include'> & {
+        include: CheckedIncludes<R, P>;
+    }): Promise<ReadWith<R, I | P[number]> | null>;
+    fetch(options?: Omit<SettingsFetchOptions, 'include'>): Promise<T | null>;
     /**
      * Update settings group
      *
@@ -1605,12 +1663,12 @@ declare class SettingsClient<T = unknown> {
     /**
      * Reset fluent options for reuse
      */
-    resetOptions(): this;
+    resetOptions(): SettingsClient<ReadWith<R, never>, R>;
 }
 
 /**
  * Any schema the client can be typed by. `any` is deliberate: the client accepts whatever content
- * types, components, singletons, queries and settings groups a customer declares.
+ * types, singletons, queries and settings groups a customer declares.
  *
  * This is the constraint `TypedRelyIOClient`'s `TSchema` carries, so `RegisteredSchema` is inferred
  * against the same one — `createClient` returns `TypedRelyIOClient<RegisteredSchema>`, and a schema
@@ -1666,9 +1724,12 @@ type SearchHitSystemFields = Pick<components['schemas']['SearchHit'], '_metadata
  * `_metadata`, and the score annotations the request asked for. There is no per-item `data` wrapper.
  *
  * `T`'s `_metadata` is replaced, not kept: `T` is an entry type, and a hit is not an entry read.
- * Distributes over a union of entry types, so a search across two types keeps each one's fields.
+ * Every field is optional, a required one too: a `fields` projection names only some of them, and a
+ * hit is built from the search row, not by the read that fills a required field a draft holds empty
+ * (REL-1795). Distributes over a union of entry types, so a search across two types keeps each
+ * one's fields.
  */
-type SearchResultItem<T = unknown> = T extends unknown ? Omit<T, '_metadata'> & SearchHitSystemFields : never;
+type SearchResultItem<T = unknown> = T extends unknown ? Partial<Omit<T, '_metadata'>> & SearchHitSystemFields : never;
 /**
  * Search response from API
  */
@@ -3203,7 +3264,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .execute()
      * ```
      */
-    content<K extends TSchema extends AnySchemaDefinition ? SchemaContentTypeNames<TSchema> : string>(contentType: K): TSchema extends AnySchemaDefinition ? ContentClient<InferContentType<TSchema['contentTypes'][K & keyof TSchema['contentTypes']], TSchema>> : ContentClient<BaseContent>;
+    content<K extends TSchema extends AnySchemaDefinition ? SchemaContentTypeNames<TSchema> : string>(contentType: K): TSchema extends AnySchemaDefinition ? ContentClient<InferContentType<TSchema['contentTypes'][K & keyof TSchema['contentTypes']], TSchema>, ContentReading<TSchema['contentTypes'][K & keyof TSchema['contentTypes']], TSchema>> : ContentClient<BaseContent>;
     /**
      * Get an asset client for a specific asset type.
      *
@@ -3222,7 +3283,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      * const heroUrl = await relyio.asset('productPhoto').file(photo._metadata.id).url({ variantId: 'hero' })
      * ```
      */
-    asset<K extends TSchema extends AnySchemaDefinition ? SchemaAssetTypeNames<TSchema> : string>(assetType: K): TSchema extends AnySchemaDefinition ? AssetClient<InferAssetType<NonNullable<TSchema['assetTypes']>[K & keyof NonNullable<TSchema['assetTypes']>], TSchema>> : AssetClient<BaseContent>;
+    asset<K extends TSchema extends AnySchemaDefinition ? SchemaAssetTypeNames<TSchema> : string>(assetType: K): TSchema extends AnySchemaDefinition ? AssetClient<InferAssetType<NonNullable<TSchema['assetTypes']>[K & keyof NonNullable<TSchema['assetTypes']>], TSchema>, AssetReading<NonNullable<TSchema['assetTypes']>[K & keyof NonNullable<TSchema['assetTypes']>], TSchema>> : AssetClient<BaseContent>;
     /**
      * Get a singleton client for a specific singleton key
      * Type-safe when schema is provided: autocompletes singleton names AND field names
@@ -3235,7 +3296,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .fetch()
      * ```
      */
-    singleton<K extends TSchema extends AnySchemaDefinition ? SchemaSingletonNames<TSchema> : string>(key: K): TSchema extends AnySchemaDefinition ? SingletonClient<InferSingleton<TSchema['singletonContentTypes'][K & keyof TSchema['singletonContentTypes']], TSchema>> : SingletonClient<unknown>;
+    singleton<K extends TSchema extends AnySchemaDefinition ? SchemaSingletonNames<TSchema> : string>(key: K): TSchema extends AnySchemaDefinition ? SingletonClient<InferSingleton<TSchema['singletonContentTypes'][K & keyof TSchema['singletonContentTypes']], TSchema>, SingletonReading<TSchema['singletonContentTypes'][K & keyof TSchema['singletonContentTypes']], TSchema>> : SingletonClient<unknown>;
     /**
      * Get a settings client for a specific settings group
      * Type-safe when schema is provided: autocompletes settings group names AND field names
@@ -3247,7 +3308,7 @@ declare class TypedRelyIOClient<TSchema extends AnySchemaDefinition | undefined
      *   .fetch()
      * ```
      */
-    settings<K extends TSchema extends AnySchemaDefinition ? SchemaSettingsGroupNames<TSchema> : string>(groupId: K): TSchema extends AnySchemaDefinition ? SettingsClient<InferSettingsGroup<NonNullable<TSchema['settingsGroups']>[K & keyof NonNullable<TSchema['settingsGroups']>], TSchema>> : SettingsClient<unknown>;
+    settings<K extends TSchema extends AnySchemaDefinition ? SchemaSettingsGroupNames<TSchema> : string>(groupId: K): TSchema extends AnySchemaDefinition ? SettingsClient<InferSettingsGroup<NonNullable<TSchema['settingsGroups']>[K & keyof NonNullable<TSchema['settingsGroups']>], TSchema>, SettingsReading<NonNullable<TSchema['settingsGroups']>[K & keyof NonNullable<TSchema['settingsGroups']>], TSchema>> : SettingsClient<unknown>;
     /**
      * Start a search query with full-text, semantic, or hybrid search.
      *