@storystick/client 0.0.0-stage → 0.2.0-rc.1

package/dist/query-builder.d.ts

@@ -0,0 +1,225 @@
+import type { Client } from './query-client.js';
+import type { DocumentLocaleRouting } from './locale-routing.js';
+import type { DeliveryDocumentV1 } from '@storystick/types/delivery-contract';
+import { type CompiledQueryV2, type KernelFilterExprV1, type QueryPageInfo, type QueryResult as QueryResultV2 } from '@storystick/types/query-contract';
+import type { QueryFieldMap, QueryFieldType, QuerySchemaDefinition, QueryStoryMap, QueryStoryType, QueryStoriesOf } from './query-schema.js';
+export interface QueryExecuteOptions {
+    readonly deliveryCache?: 'default' | 'bypass';
+    readonly signal?: AbortSignal;
+    readonly cache?: 'force-cache' | 'no-store';
+    readonly next?: {
+        readonly revalidate?: number | false;
+        readonly tags?: readonly string[];
+    };
+}
+export interface QueryExecutionHost {
+    readonly client?: Client;
+    readonly schema: QuerySchemaDefinition;
+    readonly defaultLocale?: string;
+    executeCompiled<TData, TPageInfo extends QueryPageInfo | null>(compiled: CompiledQueryV2, canonical: string, options?: QueryExecuteOptions): Promise<QueryResultV2<TData, TPageInfo>>;
+}
+export interface InternalExecutableQueryDescriptor {
+    readonly host: QueryExecutionHost;
+}
+/** Internal framework seam. Executable queries retain their owning Client. */
+export declare function getExecutableQueryDescriptor(query: object): InternalExecutableQueryDescriptor;
+type FieldsOf<TStory> = TStory extends QueryStoryType<unknown, infer TFields> ? TFields : never;
+type DocumentOf<TStory> = TStory extends QueryStoryType<infer TDocument, object> ? TDocument : never;
+type ValueOf<TField> = TField extends {
+    readonly value: infer TValue;
+} ? TValue : never;
+type ChildrenOf<TField> = TField extends QueryFieldType<unknown, never, false, false, false, infer TChildren> ? TChildren : TField extends {
+    readonly children: infer TChildren;
+} ? TChildren : never;
+type TargetsOf<TField> = TField extends {
+    readonly targets: infer TTargets;
+} ? TTargets : never;
+type IsArray<TField> = TField extends {
+    readonly array: infer TArray;
+} ? TArray : false;
+type IsOptional<TField> = TField extends {
+    readonly optional: infer TOptional;
+} ? TOptional : false;
+type TargetSelection<TTargets> = TTargets extends object ? QuerySelectionInput<FieldsOf<TTargets[keyof TTargets]>> | {
+    readonly on: {
+        readonly [K in keyof TTargets]?: QuerySelectionInput<FieldsOf<TTargets[K]>>;
+    };
+} : never;
+export type QuerySelectionInput<TFields extends object> = {
+    readonly [K in keyof TFields]?: true | (ChildrenOf<TFields[K]> extends QueryFieldMap ? QuerySelectionInput<ChildrenOf<TFields[K]>> : never) | (TargetsOf<TFields[K]> extends QueryStoryMap ? {
+        readonly resolve: TargetSelection<TargetsOf<TFields[K]>>;
+    } : never);
+};
+type SelectedTarget<TTargets, TSelection> = TTargets extends object ? TSelection extends {
+    readonly on: infer TOn;
+} ? {
+    [K in keyof TTargets & keyof TOn]: TOn[K] extends QuerySelectionInput<FieldsOf<TTargets[K]>> ? SelectedDocument<TTargets[K], TOn[K]> : never;
+}[keyof TTargets & keyof TOn] : TSelection extends QuerySelectionInput<FieldsOf<TTargets[keyof TTargets]>> ? SelectedDocument<TTargets[keyof TTargets], TSelection> : never : never;
+type SelectedFieldValue<TField, TSelection> = TSelection extends true ? ValueOf<TField> : TSelection extends {
+    readonly resolve: infer TResolve;
+} ? IsArray<TField> extends true ? readonly (SelectedTarget<TargetsOf<TField>, TResolve> | null)[] : SelectedTarget<TargetsOf<TField>, TResolve> | null : TSelection extends QuerySelectionInput<Extract<ChildrenOf<TField>, QueryFieldMap>> ? IsArray<TField> extends true ? readonly SelectedFields<Extract<ChildrenOf<TField>, QueryFieldMap>, TSelection>[] : SelectedFields<Extract<ChildrenOf<TField>, QueryFieldMap>, TSelection> : never;
+type RequiredSelectedFields<TFields extends object, TSelection> = {
+    readonly [K in keyof TFields & keyof TSelection as IsOptional<TFields[K]> extends true ? never : K]: SelectedFieldValue<TFields[K], TSelection[K]>;
+};
+type OptionalSelectedFields<TFields extends object, TSelection> = {
+    readonly [K in keyof TFields & keyof TSelection as IsOptional<TFields[K]> extends true ? K : never]?: SelectedFieldValue<TFields[K], TSelection[K]>;
+};
+export type SelectedFields<TFields extends object, TSelection> = RequiredSelectedFields<TFields, TSelection> & OptionalSelectedFields<TFields, TSelection>;
+export type SelectedDocument<TStory, TSelection> = Omit<DeliveryDocumentV1, 'fields'> & {
+    readonly _localeRouting?: DocumentLocaleRouting;
+    readonly fields: TSelection extends 'all' ? DocumentOf<TStory> : SelectedFields<FieldsOf<TStory>, TSelection>;
+};
+type OperatorNames<TField> = TField extends {
+    readonly operators: infer TOperators;
+} ? TOperators : never;
+type OperatorValue<TField> = Exclude<ValueOf<TField>, undefined> extends readonly (infer TElement)[] ? TElement : Exclude<ValueOf<TField>, undefined>;
+type OperatorMethods<TField> = ('is' extends OperatorNames<TField> ? {
+    is(value: OperatorValue<TField>): KernelFilterExprV1;
+} : {}) & ('isNot' extends OperatorNames<TField> ? {
+    isNot(value: OperatorValue<TField>): KernelFilterExprV1;
+} : {}) & ('isAnyOf' extends OperatorNames<TField> ? {
+    isAnyOf(values: readonly OperatorValue<TField>[]): KernelFilterExprV1;
+} : {}) & ('startsWith' extends OperatorNames<TField> ? {
+    startsWith(value: string): KernelFilterExprV1;
+} & ('contains' extends OperatorNames<TField> ? {
+    contains(value: string): KernelFilterExprV1;
+} : {}) : {}) & ('gt' extends OperatorNames<TField> ? {
+    gt(value: number): KernelFilterExprV1;
+} : {}) & ('lt' extends OperatorNames<TField> ? {
+    lt(value: number): KernelFilterExprV1;
+} : {}) & ('after' extends OperatorNames<TField> ? {
+    after(value: string | Date): KernelFilterExprV1;
+} : {}) & ('before' extends OperatorNames<TField> ? {
+    before(value: string | Date): KernelFilterExprV1;
+} : {}) & ('between' extends OperatorNames<TField> ? {
+    between(min: number, max: number): KernelFilterExprV1;
+} : {}) & ('isEmpty' extends OperatorNames<TField> ? {
+    isEmpty(): KernelFilterExprV1;
+} : {}) & ('isNotEmpty' extends OperatorNames<TField> ? {
+    isNotEmpty(): KernelFilterExprV1;
+} : {}) & ('hasAny' extends OperatorNames<TField> ? {
+    hasAny(values: readonly OperatorValue<TField>[]): KernelFilterExprV1;
+} : {}) & ('hasAll' extends OperatorNames<TField> ? {
+    hasAll(values: readonly OperatorValue<TField>[]): KernelFilterExprV1;
+} : {}) & ('doesNotInclude' extends OperatorNames<TField> ? {
+    doesNotInclude(values: readonly OperatorValue<TField>[]): KernelFilterExprV1;
+} : {});
+export interface QueryRoutePathAccessor {
+    is(value: string): KernelFilterExprV1;
+    isNot(value: string): KernelFilterExprV1;
+    isAnyOf(values: readonly string[]): KernelFilterExprV1;
+    isEmpty(): KernelFilterExprV1;
+    isNotEmpty(): KernelFilterExprV1;
+}
+export interface QueryRouteAccessors {
+    readonly pathname: QueryRoutePathAccessor & {
+        startsWith(value: string): KernelFilterExprV1;
+        inSection(value: string): KernelFilterExprV1;
+        notInSection(value: string): KernelFilterExprV1;
+    };
+    readonly parent: QueryRoutePathAccessor;
+    readonly depth: {
+        is(value: number): KernelFilterExprV1;
+        isNot(value: number): KernelFilterExprV1;
+        gt(value: number): KernelFilterExprV1;
+        lt(value: number): KernelFilterExprV1;
+        between(min: number, max: number): KernelFilterExprV1;
+        isEmpty(): KernelFilterExprV1;
+        isNotEmpty(): KernelFilterExprV1;
+    };
+}
+type ChildAccessors<TField> = ChildrenOf<TField> extends object ? {
+    readonly [K in keyof ChildrenOf<TField>]: FieldAccessor<ChildrenOf<TField>[K]>;
+} : {};
+export type FieldAccessor<TField> = OperatorMethods<TField> & ChildAccessors<TField> & (IsArray<TField> extends true ? {
+    readonly elements: OperatorMethods<TField> & ChildAccessors<TField>;
+} : {});
+export type QueryFieldAccessors<TFields extends object> = {
+    readonly [K in keyof TFields]: FieldAccessor<TFields[K]>;
+};
+declare const sortFieldBrand: unique symbol;
+export interface QuerySortField<TField> {
+    readonly descriptorId: string;
+    readonly [sortFieldBrand]: TField;
+}
+export type QuerySortAccessors<TFields extends object> = {
+    readonly [K in keyof TFields as TFields[K] extends {
+        readonly sortable: true;
+    } ? K : never]: QuerySortField<TFields[K]>;
+};
+export interface QuerySortClause {
+    readonly descriptorId: string;
+    readonly direction: 'asc' | 'desc';
+}
+export type QuerySortTuple = readonly [
+    QuerySortClause,
+    QuerySortClause?,
+    QuerySortClause?,
+    QuerySortClause?
+];
+type QueryAddress<TStory> = {
+    readonly id: string;
+    readonly slug?: never;
+    readonly pathname?: never;
+} | (TStory extends {
+    readonly slug: true;
+} ? {
+    readonly id?: never;
+    readonly slug: string;
+    readonly pathname?: never;
+} : never) | (TStory extends {
+    readonly pathname: true;
+} ? {
+    readonly id?: never;
+    readonly slug?: never;
+    readonly pathname: string | readonly string[] | undefined;
+} : never);
+export interface QueryCompileResult {
+    readonly query: CompiledQueryV2;
+    readonly canonical: string;
+}
+interface SelectedQueryCommon<TStory, TSelection> {
+    locale(code: string): this;
+    compile(): QueryCompileResult;
+}
+export interface AddressedQuery<TStory, TSelection> extends SelectedQueryCommon<TStory, TSelection> {
+    fetch(options?: QueryExecuteOptions): Promise<SelectedDocument<TStory, TSelection> | null>;
+    execute(options?: QueryExecuteOptions): Promise<QueryResultV2<SelectedDocument<TStory, TSelection> | null, null>>;
+}
+export interface SingletonQuery<TStory, TSelection> extends AddressedQuery<TStory, TSelection> {
+}
+export interface PagedQuery<TStory, TSelection> extends SelectedQueryCommon<TStory, TSelection> {
+    publicationFallback(policy: 'none' | 'configured'): this;
+    fetch(options?: QueryExecuteOptions): Promise<readonly SelectedDocument<TStory, TSelection>[]>;
+    execute(options?: QueryExecuteOptions): Promise<QueryResultV2<readonly SelectedDocument<TStory, TSelection>[], QueryPageInfo>>;
+}
+export interface CollectionQuery<TStory, TSelection, TOrdered extends boolean = false> extends SelectedQueryCommon<TStory, TSelection> {
+    /** Allow published fallback languages for this collection only. */
+    publicationFallback(policy: 'none' | 'configured'): this;
+    where(callback: (fields: QueryFieldAccessors<FieldsOf<TStory>>, helpers: {
+        readonly route: TStory extends {
+            readonly pathname: true;
+        } ? QueryRouteAccessors : never;
+        and(...children: readonly KernelFilterExprV1[]): KernelFilterExprV1;
+        or(...children: readonly KernelFilterExprV1[]): KernelFilterExprV1;
+    }) => KernelFilterExprV1): CollectionQuery<TStory, TSelection, TOrdered>;
+    orderBy: TOrdered extends true ? never : (callback: (fields: QuerySortAccessors<FieldsOf<TStory>>, helpers: {
+        asc(field: QuerySortField<unknown>): QuerySortClause;
+        desc(field: QuerySortField<unknown>): QuerySortClause;
+    }) => QuerySortTuple) => CollectionQuery<TStory, TSelection, true>;
+    page(input: {
+        readonly first: number;
+        readonly after?: string;
+    }): PagedQuery<TStory, TSelection>;
+    by(address: QueryAddress<TStory>): AddressedQuery<TStory, TSelection>;
+}
+type SelectedQuery<TStory, TSelection> = TStory extends {
+    readonly singleton: true;
+} ? SingletonQuery<TStory, TSelection> : CollectionQuery<TStory, TSelection>;
+export interface UnselectedQuery<TStory> {
+    select<const TSelection extends QuerySelectionInput<FieldsOf<TStory>>>(selection: TSelection): SelectedQuery<TStory, TSelection>;
+    selectAll(): SelectedQuery<TStory, 'all'>;
+}
+export type QueryForSchema<TSchema extends QuerySchemaDefinition, TStoryName extends keyof QueryStoriesOf<TSchema>> = UnselectedQuery<QueryStoriesOf<TSchema>[TStoryName]>;
+export declare function createUnselectedQuery<TStory>(host: QueryExecutionHost, storyType: string): UnselectedQuery<TStory>;
+export {};

package/dist/query-builder.js

@@ -0,0 +1,294 @@
+import { PATHNAME_QUERY_OPERATORS, isValidPathnameQueryClause, normalizeQueryPathname, } from '@storystick/types/pathname-query';
+import { decodeQueryCursorV2, } from '@storystick/types/query-contract';
+import { assertExactQueryResult } from './errors.js';
+import { normalizePathname } from './normalize-pathname.js';
+import { compileQueryState } from './query-compiler.js';
+const EXECUTABLE_QUERY_HOSTS = new WeakMap();
+/** Internal framework seam. Executable queries retain their owning Client. */
+export function getExecutableQueryDescriptor(query) {
+    const host = EXECUTABLE_QUERY_HOSTS.get(query);
+    if (!host) {
+        throw new TypeError('storystick/QUERY_INVALID: Expected a query created by createClient().');
+    }
+    return { host };
+}
+export function createUnselectedQuery(host, storyType) {
+    return new RuntimeQuery(host, {
+        storyType,
+        cardinality: 'many',
+        locale: {
+            code: host.defaultLocale ?? 'default',
+            fallback: 'configured',
+        },
+    });
+}
+class RuntimeQuery {
+    host;
+    state;
+    constructor(host, state) {
+        this.host = host;
+        this.state = state;
+        EXECUTABLE_QUERY_HOSTS.set(this, host);
+    }
+    select(selection) {
+        if (!selection || Object.keys(selection).length === 0)
+            throw queryInvalid('select requires at least one field.');
+        return this.with({ selection: compileSelection(selection) });
+    }
+    selectAll() {
+        return this.with({ selection: { mode: 'all' } });
+    }
+    where(callback) {
+        this.requireSelection();
+        const filter = callback(fieldProxy(this.state.storyType, ''), { and, or, route: routeAccessors() });
+        return this.with({ filter: this.state.filter ? and(this.state.filter, filter) : filter });
+    }
+    orderBy(callback) {
+        this.requireSelection();
+        if (this.state.sort)
+            throw queryInvalid('orderBy can be called only once.');
+        const sort = callback(sortProxy(this.state.storyType), { asc, desc });
+        if (!Array.isArray(sort) || sort.length < 1 || sort.length > 4)
+            throw queryInvalid('orderBy requires one to four clauses.');
+        return this.with({ sort: [...sort] });
+    }
+    page(input) {
+        this.requireSelection();
+        if (!Number.isSafeInteger(input.first) || input.first < 1 || input.first > 100) {
+            throw queryInvalid('page.first must be an integer between 1 and 100.');
+        }
+        if (input.after !== undefined)
+            decodeQueryCursorV2(input.after);
+        return this.with({ page: { first: input.first, ...(input.after ? { after: input.after } : {}) } });
+    }
+    by(address) {
+        this.requireSelection();
+        const entries = Object.entries(address).filter(([, value]) => value !== undefined);
+        if (entries.length !== 1)
+            throw queryInvalid('by requires exactly one address.');
+        const [kind, raw] = entries[0];
+        if (kind !== 'id' && kind !== 'slug' && kind !== 'pathname')
+            throw queryInvalid('Unknown query address.');
+        if (kind === 'pathname' && typeof raw !== 'string' && !(Array.isArray(raw) && raw.every(part => typeof part === 'string'))) {
+            throw queryInvalid('by.pathname requires a string or an array of string segments.');
+        }
+        const value = kind === 'pathname'
+            ? normalizePathname(raw)
+            : raw;
+        if (typeof value !== 'string' || (kind !== 'pathname' && value.length === 0))
+            throw queryInvalid(`by.${kind} requires a value.`);
+        const runtime = this.host.schema.stories[this.state.storyType];
+        if (!runtime?.addresses.includes(kind))
+            throw queryInvalid(`Address ${kind} is not available for ${this.state.storyType}.`);
+        return this.with({ cardinality: 'one', address: { kind, value } });
+    }
+    locale(code) {
+        this.requireSelection();
+        const normalized = code.trim();
+        if (!normalized)
+            throw queryInvalid('locale requires a non-empty code.');
+        return this.with({ locale: { code: normalized, fallback: 'configured' } });
+    }
+    publicationFallback(policy) {
+        this.requireSelection();
+        if (policy !== 'none' && policy !== 'configured')
+            throw queryInvalid('Invalid publication fallback policy.');
+        return this.with({ publicationFallback: policy });
+    }
+    compile() {
+        this.requireSelection();
+        const runtime = this.host.schema.stories[this.state.storyType];
+        const singleton = runtime?.singleton === true;
+        const cardinality = singleton ? 'one' : this.state.cardinality;
+        if (cardinality !== 'many' && this.state.publicationFallback !== undefined) {
+            throw queryInvalid('Publication fallback applies only to a collection.');
+        }
+        if (cardinality === 'many' && !this.state.page)
+            throw queryInvalid('Collection queries require page().');
+        const query = {
+            version: 2,
+            target: { kind: 'documents', storyType: this.state.storyType },
+            selection: this.state.selection,
+            ...(this.state.filter ? { filter: this.state.filter } : {}),
+            ...(this.state.sort ? { sort: this.state.sort } : {}),
+            cardinality,
+            ...(singleton ? { address: { kind: 'singleton' } } : this.state.address ? { address: this.state.address } : {}),
+            ...(this.state.page ? { page: this.state.page } : {}),
+            ...(this.state.publicationFallback ? { publicationFallback: this.state.publicationFallback } : {}),
+            locale: this.state.locale,
+            generatedSchemaFingerprint: this.host.schema.fingerprint,
+        };
+        return compileQueryState(this, query);
+    }
+    async fetch(options) {
+        const result = await this.execute(options);
+        assertExactQueryResult(result);
+        return result.data;
+    }
+    execute(options) {
+        const { query, canonical } = this.compile();
+        return this.host.executeCompiled(query, canonical, options);
+    }
+    with(patch) {
+        return new RuntimeQuery(this.host, Object.freeze({ ...this.state, ...patch }));
+    }
+    requireSelection() {
+        if (!this.state.selection)
+            throw queryInvalid('select() or selectAll() is required.');
+    }
+}
+function compileSelection(input, base = '') {
+    const fields = [];
+    for (const [key, value] of Object.entries(input).sort(([a], [b]) => a.localeCompare(b))) {
+        const path = base ? `${base}.${key}` : key;
+        if (value === true) {
+            fields.push({ kind: 'field', path });
+            continue;
+        }
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw queryInvalid(`Invalid selection at ${path}.`);
+        if ('resolve' in value) {
+            const resolve = value.resolve;
+            if (!resolve || typeof resolve !== 'object' || Array.isArray(resolve))
+                throw queryInvalid(`Invalid relation selection at ${path}.`);
+            if ('on' in resolve) {
+                const rawOn = resolve.on;
+                if (!rawOn || typeof rawOn !== 'object' || Array.isArray(rawOn))
+                    throw queryInvalid(`Invalid polymorphic selection at ${path}.`);
+                const on = {};
+                for (const [story, selection] of Object.entries(rawOn)) {
+                    if (!selection || typeof selection !== 'object' || Array.isArray(selection))
+                        throw queryInvalid(`Invalid polymorphic selection at ${path}.`);
+                    on[story] = compileSelection(selection);
+                }
+                fields.push({ kind: 'relation', path, on });
+            }
+            else {
+                fields.push({ kind: 'relation', path, selection: compileSelection(resolve) });
+            }
+            continue;
+        }
+        const nested = compileSelection(value, path);
+        fields.push(...(nested.mode === 'select' ? nested.fields : []));
+    }
+    if (fields.length === 0)
+        throw queryInvalid('select requires at least one field.');
+    return { mode: 'select', fields };
+}
+function fieldProxy(storyType, base) {
+    const callable = () => undefined;
+    return new Proxy(callable, {
+        get(_target, property) {
+            if (typeof property !== 'string')
+                return undefined;
+            if (property === 'elements')
+                return fieldProxy(storyType, `${base}[]`);
+            if (OPERATOR_MAP[property]) {
+                return (...values) => clause(storyType, base, OPERATOR_MAP[property], normalizeOperatorValue(property, values));
+            }
+            return fieldProxy(storyType, base ? `${base}.${property}` : property);
+        },
+    });
+}
+const OPERATOR_MAP = {
+    is: 'is', isNot: 'is_not', isAnyOf: 'is_any_of', startsWith: 'starts_with', contains: 'contains',
+    inSection: 'in_section', notInSection: 'not_in_section',
+    gt: 'gt', lt: 'lt', after: 'after', before: 'before', between: 'between',
+    isEmpty: 'empty', isNotEmpty: 'not_empty', hasAny: 'has_any', hasAll: 'has_all',
+    doesNotInclude: 'does_not_include',
+};
+function routeAccessors() {
+    function accessor(field) {
+        return Object.fromEntries(Object.entries(OPERATOR_MAP)
+            .filter(([, op]) => PATHNAME_QUERY_OPERATORS[field].includes(op))
+            .map(([name, op]) => [
+            name,
+            (...values) => {
+                const value = normalizeOperatorValue(name, values);
+                if (!isValidPathnameQueryClause(field, op, value))
+                    throw queryInvalid(`Invalid ${field} filter.`);
+                const canonical = typeof value === 'string'
+                    ? normalizeQueryPathname(value)
+                    : Array.isArray(value)
+                        ? value.map((entry) => typeof entry === 'string' ? normalizeQueryPathname(entry) : entry)
+                        : value;
+                return {
+                    kind: 'clause',
+                    clause: {
+                        descriptorId: `system.documents.${field}`,
+                        op,
+                        ...(canonical === undefined ? {} : { value: canonical }),
+                    },
+                };
+            },
+        ]));
+    }
+    return {
+        pathname: accessor('resolvedPathname'),
+        parent: accessor('pathnameParent'),
+        depth: accessor('pathnameDepth'),
+    };
+}
+function normalizeOperatorValue(operator, values) {
+    if (operator === 'isEmpty' || operator === 'isNotEmpty')
+        return undefined;
+    if (operator === 'between')
+        return values.map(normalizeScalar);
+    return normalizeScalar(values[0]);
+}
+function normalizeScalar(value) {
+    if (value instanceof Date) {
+        if (!Number.isFinite(value.getTime()))
+            throw queryInvalid('Invalid date value.');
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            throw queryInvalid('Operator arrays cannot be empty.');
+        return value.map(normalizeScalar);
+    }
+    if (typeof value === 'number' && !Number.isFinite(value))
+        throw queryInvalid('Query numbers must be finite.');
+    return value;
+}
+function clause(storyType, path, op, value) {
+    if (!path)
+        throw queryInvalid('A filter operator must target a field.');
+    const booleanOp = op === 'is' && typeof value === 'boolean' ? (value ? 'is_true' : 'is_false') : op;
+    return {
+        kind: 'clause',
+        clause: {
+            descriptorId: `field.${storyType}.${path}`,
+            op: booleanOp,
+            ...(booleanOp === 'is_true' || booleanOp === 'is_false' || value === undefined ? {} : { value }),
+        },
+    };
+}
+function and(...children) {
+    if (children.length === 0)
+        throw queryInvalid('and requires at least one child.');
+    return { kind: 'group', op: 'and', children: [...children] };
+}
+function or(...children) {
+    if (children.length === 0)
+        throw queryInvalid('or requires at least one child.');
+    return { kind: 'group', op: 'or', children: [...children] };
+}
+function sortProxy(storyType) {
+    return new Proxy({}, {
+        get(_target, property) {
+            return typeof property === 'string'
+                ? { descriptorId: `field.${storyType}.${property}` }
+                : undefined;
+        },
+    });
+}
+function asc(field) {
+    return { descriptorId: field.descriptorId, direction: 'asc' };
+}
+function desc(field) {
+    return { descriptorId: field.descriptorId, direction: 'desc' };
+}
+function queryInvalid(message) {
+    return new TypeError(`storystick/QUERY_INVALID: ${message}`);
+}

package/dist/query-client.d.ts

@@ -0,0 +1,54 @@
+import type { PreviewReadContext } from '@storystick/types/preview-query-targeting';
+import type { ClientAuth, DefaultRequestOptions, RequestContext, Transport, PublicTransport } from './types.js';
+import { type QueryExecutionHost, type QueryForSchema } from './query-builder.js';
+import type { QuerySchemaDefinition, QueryStoriesOf } from './query-schema.js';
+import { type LocaleRoutingSettings } from './locale-routing.js';
+export type ClientOptions<TSchema extends QuerySchemaDefinition> = ClientAuth & {
+    readonly schema: TSchema;
+    readonly projectId: string;
+    readonly endpoint?: string;
+    /** Explicit public Query V2 gateway; control and Preview keep endpoint. */
+    readonly deliveryEndpoint?: string;
+    /** Customer application build identity for generation-paired reads. */
+    readonly applicationBuildId?: string;
+    readonly transport?: PublicTransport;
+    readonly defaults?: DefaultRequestOptions;
+    /** Routing metadata carried by returned documents across rendering boundaries. */
+    readonly localeRouting?: LocaleRoutingSettings;
+};
+export interface Client<TSchema extends QuerySchemaDefinition = QuerySchemaDefinition> {
+    readonly schema: TSchema;
+    readonly defaultLocale?: string;
+    readonly projectId: string;
+    query<TStoryName extends keyof QueryStoriesOf<TSchema> & string>(storyType: TStoryName): QueryForSchema<TSchema, TStoryName>;
+}
+export type InternalClientOptions<TSchema extends QuerySchemaDefinition> = ClientOptions<TSchema> & {
+    readonly requestContext?: RequestContext;
+};
+export interface InternalClientRuntime {
+    readonly contextEpoch: string;
+    readonly executionHost: QueryExecutionHost;
+    readonly transport: Transport;
+    readonly requestContext: RequestContext | undefined;
+    readonly defaults: DefaultRequestOptions | undefined;
+    readonly localeRouting: LocaleRoutingSettings | undefined;
+}
+export interface InternalPreviewAuthorityScope {
+    readonly readContext?: PreviewReadContext | null;
+    readonly projectId: string;
+    readonly previewSessionId: string;
+    readonly previewObservationId: string;
+    readonly previewToken: string;
+    readonly variantId: string | null;
+    readonly releaseId: string | null;
+}
+export declare function getInternalClientRuntime(client: Client): InternalClientRuntime;
+/** Compare private Preview authority in memory without returning or serializing it. */
+export declare function clientMatchesPreviewAuthority(authority: Client, expected: InternalPreviewAuthorityScope): boolean;
+/**
+ * Internal adapter primitive: keep a trusted client's transport authority and
+ * request scope while replacing only its generated schema surface.
+ */
+export declare function bindClientSchemaToAuthority<const TSchema extends QuerySchemaDefinition>(authority: Client, schema: TSchema): Client<TSchema>;
+export declare function createClient<const TSchema extends QuerySchemaDefinition>(options: ClientOptions<TSchema>): Client<TSchema>;
+export declare function createInternalClient<const TSchema extends QuerySchemaDefinition>(options: InternalClientOptions<TSchema>): Client<TSchema>;