import { type ArrayOrValue, type Maybe } from '@dereekb/util';
import { type DocumentReferenceRef } from '../firestore/reference';
import { type FirestoreModelKey, type FirestoreModelType, type FirestoreModelTypeRef } from '../firestore/collection/collection';
/**
 * Standard CRUD call types used by the `callModel` Firebase function pattern.
 */
export type KnownOnCallFunctionType = 'create' | 'read' | 'update' | 'delete' | 'query';
/**
 * Call type identifier — one of the standard CRUD types or a custom string.
 */
export type OnCallFunctionType = KnownOnCallFunctionType | string;
/**
 * Parameters for a typed model call through the `callModel` Firebase function.
 *
 * Combines the target model type, CRUD call type, optional specifier for sub-operations,
 * and the call payload. This is the standard envelope format for all model API calls.
 *
 * @template T - the call data payload type
 */
export interface OnCallTypedModelParams<T = unknown> extends FirestoreModelTypeRef {
    /**
     * CRUD call type (create, read, update, delete) or a custom action type.
     */
    readonly call?: Maybe<OnCallFunctionType>;
    /**
     * Sub-function specifier for distinguishing different operations within the same call type.
     */
    readonly specifier?: string;
    /**
     * The call payload data.
     */
    readonly data: T;
}
/**
 * Function that creates {@link OnCallTypedModelParams} for a given model type, pre-configured with a call type.
 */
export type OnCallTypeModelParamsFunction = <T>(modelTypeInput: FirestoreModelType | FirestoreModelTypeRef, data: T, specifier?: string) => OnCallTypedModelParams<T>;
/**
 * Creates an {@link OnCallTypeModelParamsFunction} pre-configured with the given call type.
 *
 * The returned function builds {@link OnCallTypedModelParams} for any model type.
 *
 * @param call - the CRUD call type to embed in generated params
 * @returns an {@link OnCallTypeModelParamsFunction} pre-configured with the given call type
 * @throws {Error} When `modelType` is not provided or empty.
 *
 * @example
 * ```ts
 * const createParams = onCallTypedModelParamsFunction('create');
 * const params = createParams('notification', { title: 'Hello' });
 * // params === { call: 'create', modelType: 'notification', data: { title: 'Hello' } }
 * ```
 */
export declare function onCallTypedModelParamsFunction(call?: Maybe<OnCallFunctionType>): OnCallTypeModelParamsFunction;
/**
 * Creates OnCallTypedModelParams for the input.
 *
 * Convenience function for calling onCallTypedModelParamsFunction and executing it with the input.
 *
 * @deprecated Move towards using onCallTypedModelParamsFunction directly with the call type instead of using this function. Will not be removed in the future.
 *
 * @param modelTypeInput - the model type string or ref
 * @param data - the call payload
 * @param specifier - optional sub-function specifier
 * @param call - the CRUD call type
 * @returns the constructed {@link OnCallTypedModelParams}
 */
export declare function onCallTypedModelParams<T>(modelTypeInput: FirestoreModelType | FirestoreModelTypeRef, data: T, specifier?: string, call?: OnCallFunctionType): OnCallTypedModelParams<T>;
/**
 * Pre-configured OnCallTypedModelParamsFunctions for 'create'
 */
export declare const onCallCreateModelParams: OnCallTypeModelParamsFunction;
/**
 * Pre-configured OnCallTypedModelParamsFunctions for 'read'
 */
export declare const onCallReadModelParams: OnCallTypeModelParamsFunction;
/**
 * Pre-configured OnCallTypedModelParamsFunctions for 'update'
 */
export declare const onCallUpdateModelParams: OnCallTypeModelParamsFunction;
/**
 * Pre-configured OnCallTypedModelParamsFunctions for 'delete'
 */
export declare const onCallDeleteModelParams: OnCallTypeModelParamsFunction;
/**
 * Pre-configured OnCallTypedModelParamsFunctions for 'query'
 */
export declare const onCallQueryModelParams: OnCallTypeModelParamsFunction;
/**
 * Key used on the front-end and backend that refers to the call function.
 */
export declare const CALL_MODEL_APP_FUNCTION_KEY = "callModel";
/**
 * OnCallTypedModelParams for Create calls.
 */
export type OnCallCreateModelParams<T = unknown> = OnCallTypedModelParams<T>;
/**
 * OnCallTypedModelParams for Read calls.
 */
export type OnCallReadModelParams<T = unknown> = OnCallTypedModelParams<T>;
/**
 * OnCallTypedModelParams for Update calls.
 */
export type OnCallUpdateModelParams<T = unknown> = OnCallTypedModelParams<T>;
/**
 * OnCallTypedModelParams for Delete calls.
 */
export type OnCallDeleteModelParams<T = unknown> = OnCallTypedModelParams<T>;
/**
 * OnCallTypedModelParams for Query calls.
 */
export type OnCallQueryModelParams<T extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams> = OnCallTypedModelParams<T>;
/**
 * Default maximum items per page for query operations.
 */
export declare const DEFAULT_ON_CALL_QUERY_MODEL_LIMIT = 50;
/**
 * Absolute maximum items per page for query operations. Prevents unbounded queries.
 */
export declare const MAX_ON_CALL_QUERY_MODEL_LIMIT = 200;
/**
 * Base request parameters that all query handler input types must include.
 *
 * Provides cursor-based pagination fields. Custom query handlers extend this
 * with additional filter fields specific to their model type.
 *
 * @example
 * ```typescript
 * interface QueryGuestbooksParams extends OnCallQueryModelRequestParams {
 *   readonly name?: string;
 *   readonly published?: boolean;
 * }
 * ```
 */
export interface OnCallQueryModelRequestParams {
    /**
     * Maximum number of items to return per page.
     *
     * Clamped server-side to {@link MAX_ON_CALL_QUERY_MODEL_LIMIT}.
     * Defaults to {@link DEFAULT_ON_CALL_QUERY_MODEL_LIMIT} when omitted.
     */
    readonly limit?: number;
    /**
     * Firestore model key of the last document from the previous page.
     *
     * When provided, the query resumes after the document at this key.
     * Obtained from {@link OnCallQueryModelResult.cursorDocumentKey}.
     */
    readonly cursorDocumentKey?: FirestoreModelKey;
}
/**
 * Standard result returned by model query operations.
 *
 * Includes the matched documents and cursor information for pagination.
 *
 * @typeParam T - The document data type.
 */
export interface OnCallQueryModelResult<T = unknown> {
    /**
     * The matched documents' data for this page.
     */
    readonly results: readonly T[];
    /**
     * The keys of the matched documents, in the same order as {@link results}.
     */
    readonly keys: readonly FirestoreModelKey[];
    /**
     * Total number of results returned in this page.
     */
    readonly count: number;
    /**
     * Firestore model key of the last document in this page.
     *
     * Pass this value as the `cursorDocumentKey` field in the next query request to fetch the next page.
     * Undefined when there are no more results.
     */
    readonly cursorDocumentKey?: FirestoreModelKey;
    /**
     * Whether there are more results after this page.
     */
    readonly hasMore: boolean;
}
/**
 * Standard result returned by model create operations, containing the key(s) of the created document(s).
 */
export interface OnCallCreateModelResult {
    /**
     * Key(s)/Paths of the created object(s)
     */
    readonly modelKeys: ArrayOrValue<FirestoreModelKey>;
}
/**
 * Creates an {@link OnCallCreateModelResult} from document references by extracting their paths as model keys.
 *
 * @param result - document reference(s) from a create operation
 * @returns an {@link OnCallCreateModelResult} with model keys extracted from document paths
 *
 * @example
 * ```ts
 * const result = onCallCreateModelResultWithDocs(createdDocs);
 * // result.modelKeys === ['notifications/abc123']
 * ```
 */
export declare function onCallCreateModelResultWithDocs(result: ArrayOrValue<DocumentReferenceRef<unknown>>): OnCallCreateModelResult;
/**
 * Creates an {@link OnCallCreateModelResult} from model key(s), normalizing to an array.
 *
 * @param modelKeys - the model key(s) of the created document(s)
 * @returns an {@link OnCallCreateModelResult} containing the keys as an array
 */
export declare function onCallCreateModelResult(modelKeys: ArrayOrValue<FirestoreModelKey>): OnCallCreateModelResult;