s4kit 0.0.1 → 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,1175 @@
+/**
+ * SDK configuration options
+ */
+interface S4KitConfig {
+    apiKey: string;
+    baseUrl?: string;
+    connection?: string;
+    service?: string;
+    timeout?: number;
+    retries?: number;
+    debug?: boolean;
+}
+/**
+ * Complete OData query options with full type safety
+ * @template T - Entity type for type-safe field selection
+ */
+interface QueryOptions<T = any> {
+    /** Select specific fields - type-safe when T is provided */
+    select?: Array<keyof T & string>;
+    /**
+     * Filter expression - supports multiple formats:
+     * - String: `"Name eq 'John'"` (raw OData)
+     * - Object: `{ Name: 'John' }` (eq implied) or `{ Price: { gt: 100 } }`
+     * - Array: `[{ Category: 'A' }, { Price: { gt: 100 } }]` (AND)
+     */
+    filter?: Filter<T>;
+    /** Maximum number of results to return */
+    top?: number;
+    /** Number of results to skip (for pagination) */
+    skip?: number;
+    /**
+     * Sort expression - supports multiple formats:
+     * - String: `"Name desc"` or `"Price asc, Name desc"`
+     * - Object: `{ Name: 'desc' }` (type-safe)
+     * - Array: `[{ Price: 'desc' }, { Name: 'asc' }]`
+     */
+    orderBy?: OrderBy<T>;
+    /**
+     * Expand navigation properties - supports multiple formats:
+     * - Array: `['Products', 'Category']`
+     * - Object: `{ Products: true }` or `{ Products: { select: ['Name'], top: 5 } }`
+     */
+    expand?: Expand<T>;
+    /** Request inline count of total matching entities */
+    count?: boolean;
+    /** Full-text search query */
+    search?: string;
+    /** Override connection for this request */
+    connection?: string;
+    /** Override service for this request */
+    service?: string;
+    /** Get raw OData response with metadata (default: false) */
+    raw?: boolean;
+}
+/**
+ * Sort direction
+ */
+type OrderDirection = 'asc' | 'desc';
+/**
+ * Type-safe orderBy object
+ * @example { Name: 'desc' } or { Price: 'asc', Name: 'desc' }
+ */
+type OrderByObject<T = any> = {
+    [K in keyof T & string]?: OrderDirection;
+};
+/**
+ * All supported orderBy formats
+ * @example
+ * ```ts
+ * // String (simple)
+ * orderBy: 'Name desc'
+ * orderBy: 'Price asc, Name desc'
+ *
+ * // Object (type-safe, recommended)
+ * orderBy: { Name: 'desc' }
+ * orderBy: { Price: 'asc' }
+ *
+ * // Array of objects (multiple sort criteria)
+ * orderBy: [{ Price: 'desc' }, { Name: 'asc' }]
+ * ```
+ */
+type OrderBy<T = any> = string | OrderByObject<T> | Array<OrderByObject<T>>;
+/**
+ * Filter comparison operators
+ */
+type FilterComparisonOperator = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le';
+/**
+ * Filter string operators
+ */
+type FilterStringOperator = 'contains' | 'startswith' | 'endswith';
+/**
+ * Filter condition with operator
+ * @example { gt: 100 } or { contains: 'Pro' }
+ */
+type FilterCondition = {
+    [K in FilterComparisonOperator]?: string | number | boolean | null | Date;
+} | {
+    [K in FilterStringOperator]?: string;
+} | {
+    in?: (string | number)[];
+} | {
+    between?: [number, number] | [Date, Date];
+};
+/**
+ * Filter value - either direct value (eq implied) or condition object
+ * @example 'John' (equals 'John') or { gt: 100 } (greater than 100)
+ */
+type FilterValue = string | number | boolean | null | Date | FilterCondition;
+/**
+ * Type-safe filter object
+ * @example
+ * ```ts
+ * // Simple equality (eq implied)
+ * filter: { Name: 'John' }
+ * filter: { Active: true, Category: 'Electronics' }
+ *
+ * // With operators
+ * filter: { Price: { gt: 100 } }
+ * filter: { Name: { contains: 'Pro' } }
+ * filter: { Status: { in: ['active', 'pending'] } }
+ *
+ * // Combined
+ * filter: { Category: 'Electronics', Price: { gt: 100, lt: 500 } }
+ * ```
+ */
+type FilterObject<T = any> = {
+    [K in keyof T & string]?: FilterValue;
+};
+/**
+ * Logical operators for complex filters
+ * @example
+ * ```ts
+ * // OR conditions
+ * filter: { $or: [{ Status: 'active' }, { Role: 'admin' }] }
+ *
+ * // NOT condition
+ * filter: { $not: { Status: 'deleted' } }
+ *
+ * // Combined
+ * filter: {
+ *   Category: 'Electronics',
+ *   $or: [{ Price: { lt: 100 } }, { OnSale: true }]
+ * }
+ * ```
+ */
+interface FilterLogical<T = any> {
+    /** OR - any condition matches */
+    $or?: FilterExpression<T>[];
+    /** AND - all conditions match (explicit, fields are implicitly ANDed) */
+    $and?: FilterExpression<T>[];
+    /** NOT - negate the condition */
+    $not?: FilterExpression<T>;
+}
+/**
+ * Complete filter expression (fields + logical operators)
+ */
+type FilterExpression<T = any> = FilterObject<T> & FilterLogical<T>;
+/**
+ * All supported filter formats
+ * @example
+ * ```ts
+ * // String (OData syntax)
+ * filter: "Name eq 'John' and Price gt 100"
+ *
+ * // Object (type-safe, recommended)
+ * filter: { Name: 'John' }                    // eq implied
+ * filter: { Price: { gt: 100 } }              // with operator
+ * filter: { Category: 'A', Price: { lt: 50 }} // multiple (AND)
+ *
+ * // Array (multiple conditions, AND implied)
+ * filter: [
+ *   { Category: 'Electronics' },
+ *   { Price: { gt: 100 } }
+ * ]
+ *
+ * // OR conditions
+ * filter: { $or: [{ Status: 'active' }, { Role: 'admin' }] }
+ *
+ * // NOT condition
+ * filter: { $not: { Status: 'deleted' } }
+ *
+ * // Complex nested
+ * filter: {
+ *   Category: 'Electronics',
+ *   $or: [
+ *     { Price: { lt: 100 } },
+ *     { $and: [{ OnSale: true }, { Stock: { gt: 0 } }] }
+ *   ]
+ * }
+ * ```
+ */
+type Filter<T = any> = string | FilterExpression<T> | FilterExpression<T>[];
+/**
+ * Expand nested options (for object syntax)
+ * @example { select: ['Name'], filter: { Active: true }, top: 10 }
+ */
+interface ExpandNestedOptions {
+    /** Select specific fields from expanded entity */
+    select?: string[];
+    /** Filter expanded entities */
+    filter?: Filter<any>;
+    /** Limit expanded results */
+    top?: number;
+    /** Skip expanded results */
+    skip?: number;
+    /** Order expanded results */
+    orderBy?: OrderBy<any>;
+    /** Nested expand */
+    expand?: Expand<any>;
+}
+/**
+ * Expand value - true for simple include, or options object
+ */
+type ExpandValue = true | ExpandNestedOptions;
+/**
+ * Object-style expand (Prisma-like)
+ * @example { Products: true } or { Products: { select: ['Name'], top: 5 } }
+ */
+type ExpandObject = Record<string, ExpandValue>;
+/**
+ * All supported expand formats
+ * @example
+ * ```ts
+ * // Simple array
+ * expand: ['Products', 'Category']
+ *
+ * // Object with boolean (simple include)
+ * expand: { Products: true, Category: true }
+ *
+ * // Object with options
+ * expand: {
+ *   Products: {
+ *     select: ['Name', 'Price'],
+ *     filter: { Active: true },
+ *     top: 10,
+ *     orderBy: { Name: 'asc' }
+ *   }
+ * }
+ *
+ * // Nested expand
+ * expand: {
+ *   Products: {
+ *     select: ['Name'],
+ *     expand: { Supplier: true }
+ *   }
+ * }
+ * ```
+ */
+type Expand<T = any> = string[] | ExpandObject;
+/**
+ * List response with optional count
+ */
+interface ListResponse<T> {
+    /** The data items */
+    value: T[];
+    /** Total count (when count: true is requested) */
+    count?: number;
+}
+/**
+ * Response with both data and metadata
+ */
+interface ODataResponse<T> {
+    value: T;
+    '@odata.context'?: string;
+    '@odata.count'?: number;
+    '@odata.nextLink'?: string;
+}
+/**
+ * Complete entity handler with all OData operations
+ */
+interface EntityHandler<T = any> {
+    /**
+     * List entities with optional query options
+     * @example
+     * ```ts
+     * const items = await client.sap.Products.list({ top: 10 });
+     * ```
+     */
+    list(options?: QueryOptions<T>): Promise<T[]>;
+    /**
+     * List entities with count
+     * @example
+     * ```ts
+     * const { value, count } = await client.sap.Products.listWithCount({ top: 10 });
+     * console.log(`Showing ${value.length} of ${count} total`);
+     * ```
+     */
+    listWithCount(options?: QueryOptions<T>): Promise<ListResponse<T>>;
+    /**
+     * Get single entity by key
+     * @example
+     * ```ts
+     * const product = await client.sap.Products.get(1);
+     * const partner = await client.sap.A_BusinessPartner.get('BP001');
+     * ```
+     */
+    get(id: EntityKey, options?: QueryOptions<T>): Promise<T>;
+    /**
+     * Count matching entities
+     * @example
+     * ```ts
+     * const total = await client.sap.Products.count({ filter: "Price gt 100" });
+     * ```
+     */
+    count(options?: Omit<QueryOptions<T>, 'top' | 'skip' | 'select'>): Promise<number>;
+    /**
+     * Create a new entity (POST)
+     * @example
+     * ```ts
+     * const created = await client.sap.Products.create({ Name: 'Widget', Price: 9.99 });
+     * ```
+     */
+    create(data: Partial<T> | T, options?: QueryOptions<T>): Promise<T>;
+    /**
+     * Create with related entities (deep insert)
+     * @example
+     * ```ts
+     * const order = await client.sap.Orders.createDeep({
+     *   OrderID: '001',
+     *   Items: [{ Product: 'A', Quantity: 10 }]
+     * });
+     * ```
+     */
+    createDeep(data: DeepInsertData<T>, options?: QueryOptions<T>): Promise<T>;
+    /**
+     * Partial update (PATCH) - only updates specified fields
+     * @example
+     * ```ts
+     * const updated = await client.sap.Products.update(1, { Price: 12.99 });
+     * ```
+     */
+    update(id: EntityKey, data: Partial<T>, options?: QueryOptions<T>): Promise<T>;
+    /**
+     * Full replacement (PUT) - replaces entire entity
+     * @example
+     * ```ts
+     * const replaced = await client.sap.Products.replace(1, fullProductData);
+     * ```
+     */
+    replace(id: EntityKey, data: T, options?: QueryOptions<T>): Promise<T>;
+    /**
+     * Upsert - create or update based on key
+     * @example
+     * ```ts
+     * const result = await client.sap.Products.upsert({ ID: 1, Name: 'Widget', Price: 9.99 });
+     * ```
+     */
+    upsert(data: T, options?: QueryOptions<T>): Promise<T>;
+    /**
+     * Delete entity by key
+     * @example
+     * ```ts
+     * await client.sap.Products.delete(1);
+     * ```
+     */
+    delete(id: EntityKey, options?: QueryOptions<T>): Promise<void>;
+    /**
+     * Access navigation property (related entities)
+     * @example
+     * ```ts
+     * const items = await client.sap.Orders.nav(1, 'Items').list();
+     * ```
+     */
+    nav<R = any>(id: EntityKey, property: string): EntityHandler<R>;
+    /**
+     * Call an OData function (GET operation)
+     * @example
+     * ```ts
+     * const result = await client.sap.Products.func('GetTopSelling', { count: 10 });
+     * ```
+     */
+    func<R = any>(name: string, params?: Record<string, any>): Promise<R>;
+    /**
+     * Call an OData action (POST operation)
+     * @example
+     * ```ts
+     * await client.sap.Orders.action('Approve', { orderId: '001' });
+     * ```
+     */
+    action<R = any>(name: string, params?: Record<string, any>): Promise<R>;
+    /**
+     * Call bound function on specific entity
+     * @example
+     * ```ts
+     * const total = await client.sap.Orders.boundFunc(1, 'CalculateTotal');
+     * ```
+     */
+    boundFunc<R = any>(id: EntityKey, name: string, params?: Record<string, any>): Promise<R>;
+    /**
+     * Call bound action on specific entity
+     * @example
+     * ```ts
+     * await client.sap.Orders.boundAction('001', 'Submit');
+     * ```
+     */
+    boundAction<R = any>(id: EntityKey, name: string, params?: Record<string, any>): Promise<R>;
+    /**
+     * Paginate through all entities with automatic page handling
+     * @example
+     * ```ts
+     * // Iterate through all pages
+     * for await (const page of client.sap.Products.paginate({ top: 100 })) {
+     *   console.log(`Processing ${page.value.length} items`);
+     *   for (const product of page.value) {
+     *     // process product
+     *   }
+     * }
+     *
+     * // Or collect all items
+     * const all = await client.sap.Products.all({ filter: "Active eq true" });
+     * ```
+     */
+    paginate(options?: PaginateOptions<T>): AsyncIterable<ListResponse<T>>;
+    /**
+     * Get all entities (automatically handles pagination)
+     * @example
+     * ```ts
+     * const allProducts = await client.sap.Products.all({ filter: "Active eq true" });
+     * ```
+     */
+    all(options?: PaginateOptions<T>): Promise<T[]>;
+}
+/**
+ * Pagination options (extends QueryOptions)
+ */
+interface PaginateOptions<T = any> extends Omit<QueryOptions<T>, 'skip'> {
+    /** Page size (default: 100) */
+    pageSize?: number;
+    /** Maximum number of items to retrieve (default: unlimited) */
+    maxItems?: number;
+}
+/**
+ * Entity key type - supports string, number, or composite keys
+ */
+type EntityKey = string | number | CompositeKey;
+/**
+ * Composite key for entities with multiple key fields
+ * @example
+ * ```ts
+ * const item = await client.sap.OrderItems.get({ OrderID: '001', ItemNo: 10 });
+ * ```
+ */
+type CompositeKey = Record<string, string | number>;
+/**
+ * Deep insert data type
+ */
+type DeepInsertData<T> = T & {
+    [K in string]?: any[] | any;
+};
+/**
+ * Batch operation types
+ */
+type BatchOperation<T = any> = BatchGet<T> | BatchCreate<T> | BatchUpdate<T> | BatchDelete;
+interface BatchGet<T = any> {
+    method: 'GET';
+    entity: string;
+    id?: EntityKey;
+    options?: QueryOptions<T>;
+}
+interface BatchCreate<T = any> {
+    method: 'POST';
+    entity: string;
+    data: Partial<T>;
+}
+interface BatchUpdate<T = any> {
+    method: 'PATCH' | 'PUT';
+    entity: string;
+    id: EntityKey;
+    data: Partial<T>;
+}
+interface BatchDelete {
+    method: 'DELETE';
+    entity: string;
+    id: EntityKey;
+}
+interface BatchResult<T = any> {
+    success: boolean;
+    status: number;
+    data?: T;
+    error?: ODataError;
+}
+interface Changeset {
+    operations: Array<BatchCreate<any> | BatchUpdate<any> | BatchDelete>;
+}
+interface ODataError {
+    code: string;
+    message: string;
+    target?: string;
+    details?: ODataErrorDetail[];
+    innererror?: {
+        message?: string;
+        type?: string;
+        stacktrace?: string;
+    };
+}
+interface ODataErrorDetail {
+    code: string;
+    message: string;
+    target?: string;
+}
+interface RequestInterceptor {
+    (request: InterceptedRequest): InterceptedRequest | Promise<InterceptedRequest>;
+}
+interface ResponseInterceptor {
+    (response: InterceptedResponse): InterceptedResponse | Promise<InterceptedResponse>;
+}
+interface ErrorInterceptor {
+    (error: IS4KitError): IS4KitError | Promise<IS4KitError>;
+}
+interface InterceptedRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: any;
+    searchParams?: Record<string, string>;
+}
+interface InterceptedResponse {
+    status: number;
+    headers: Record<string, string>;
+    data: any;
+}
+interface IS4KitError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly odataError?: ODataError;
+    readonly request?: InterceptedRequest;
+    readonly suggestion?: string;
+    readonly friendlyMessage: string;
+    readonly help: string;
+    readonly details: ODataErrorDetail[];
+    hasCode(code: string): boolean;
+    toJSON(): Record<string, any>;
+}
+type FilterOperator = 'eq' | 'ne' | 'gt' | 'ge' | 'lt' | 'le' | 'contains' | 'startswith' | 'endswith' | 'in' | 'has';
+type LogicalOperator = 'and' | 'or' | 'not';
+interface FluentQuery<T> {
+    select<K extends keyof T>(...fields: K[]): FluentQuery<Pick<T, K>>;
+    filter(expression: string): FluentQuery<T>;
+    where<K extends keyof T>(field: K, operator: FilterOperator, value: any): FluentQuery<T>;
+    and<K extends keyof T>(field: K, operator: FilterOperator, value: any): FluentQuery<T>;
+    or<K extends keyof T>(field: K, operator: FilterOperator, value: any): FluentQuery<T>;
+    orderBy<K extends keyof T>(field: K, direction?: 'asc' | 'desc'): FluentQuery<T>;
+    expand(property: string, nested?: (q: FluentQuery<any>) => FluentQuery<any>): FluentQuery<T>;
+    top(count: number): FluentQuery<T>;
+    skip(count: number): FluentQuery<T>;
+    search(term: string): FluentQuery<T>;
+    count(): FluentQuery<T>;
+    execute(): Promise<T[]>;
+    executeWithCount(): Promise<ListResponse<T>>;
+    first(): Promise<T | undefined>;
+    single(): Promise<T>;
+}
+
+interface RequestOptions {
+    connection?: string;
+    service?: string;
+    raw?: boolean;
+    headers?: Record<string, string>;
+}
+interface HttpClientConfig extends S4KitConfig {
+    onRequest?: RequestInterceptor[];
+    onResponse?: ResponseInterceptor[];
+    onError?: ErrorInterceptor[];
+}
+declare class HttpClient {
+    private client;
+    private config;
+    private requestInterceptors;
+    private responseInterceptors;
+    private errorInterceptors;
+    private debug;
+    constructor(config: HttpClientConfig);
+    /**
+     * Add a request interceptor
+     * @example
+     * ```ts
+     * client.onRequest((req) => {
+     *   console.log(`${req.method} ${req.url}`);
+     *   return req;
+     * });
+     * ```
+     */
+    onRequest(interceptor: RequestInterceptor): this;
+    /**
+     * Add a response interceptor
+     * @example
+     * ```ts
+     * client.onResponse((res) => {
+     *   console.log(`Response: ${res.status}`);
+     *   return res;
+     * });
+     * ```
+     */
+    onResponse(interceptor: ResponseInterceptor): this;
+    /**
+     * Add an error interceptor
+     * @example
+     * ```ts
+     * client.onError((err) => {
+     *   if (err.status === 401) {
+     *     // Refresh token logic
+     *   }
+     *   return err;
+     * });
+     * ```
+     */
+    onError(interceptor: ErrorInterceptor): this;
+    private log;
+    private buildHeaders;
+    private executeRequest;
+    get<T>(path: string, searchParams?: Record<string, any>, options?: RequestOptions): Promise<T>;
+    post<T>(path: string, json: any, options?: RequestOptions): Promise<T>;
+    put<T>(path: string, json: any, options?: RequestOptions): Promise<T>;
+    patch<T>(path: string, json: any, options?: RequestOptions): Promise<T>;
+    delete(path: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Execute multiple operations in a single batch request
+     * @example
+     * ```ts
+     * const results = await client.batch([
+     *   { method: 'GET', entity: 'Products', id: 1 },
+     *   { method: 'POST', entity: 'Products', data: { Name: 'New' } },
+     *   { method: 'DELETE', entity: 'Products', id: 2 },
+     * ]);
+     * ```
+     */
+    batch<T = any>(operations: BatchOperation<T>[], options?: RequestOptions): Promise<BatchResult<T>[]>;
+    /**
+     * Execute operations in an atomic changeset (all succeed or all fail)
+     * @example
+     * ```ts
+     * const results = await client.changeset({
+     *   operations: [
+     *     { method: 'POST', entity: 'Orders', data: orderData },
+     *     { method: 'POST', entity: 'OrderItems', data: itemData },
+     *   ]
+     * });
+     * ```
+     */
+    changeset<T = any>(changeset: Changeset, options?: RequestOptions): Promise<BatchResult<T>[]>;
+    private buildBatchBody;
+    private buildChangesetBody;
+    private buildBatchPart;
+    private formatKey;
+    private parseBatchResponse;
+}
+
+/**
+ * S4Kit client methods (interceptors, batch operations)
+ */
+interface S4KitMethods {
+    onRequest(interceptor: RequestInterceptor): S4KitClient;
+    onResponse(interceptor: ResponseInterceptor): S4KitClient;
+    onError(interceptor: ErrorInterceptor): S4KitClient;
+    batch<T = any>(operations: BatchOperation<T>[]): Promise<BatchResult<T>[]>;
+    changeset<T = any>(changeset: Changeset): Promise<BatchResult<T>[]>;
+}
+/**
+ * Augmentable interface for typed entity access.
+ * Generated type files augment this interface to provide type-safe entity properties.
+ *
+ * @example
+ * ```ts
+ * // In generated types file:
+ * declare module 's4kit' {
+ *   interface S4KitClient {
+ *     Customers: EntityHandler<Customer>;
+ *   }
+ * }
+ * // Now client.Customers.list() returns Customer[]
+ * ```
+ */
+interface S4KitClient extends S4KitMethods {
+}
+/**
+ * S4Kit client type with dynamic entity access.
+ * Combines the augmentable interface with an index signature for runtime flexibility.
+ *
+ * @example client.Products.list() or client.A_BusinessPartner.get('123')
+ */
+type S4KitClientWithDynamicAccess = S4KitClient & {
+    /** Access any entity by name (fallback for non-augmented entities) */
+    [entityName: string]: EntityHandler<any>;
+};
+/**
+ * S4Kit - The simplest way to integrate with SAP S/4HANA
+ *
+ * @example
+ * ```ts
+ * import { S4Kit } from 's4kit';
+ *
+ * const client = new S4Kit({
+ *   apiKey: 'sk_live_xxx',
+ * });
+ *
+ * // List entities - clean, simple API
+ * const partners = await client.A_BusinessPartner.list({
+ *   top: 10,
+ *   select: ['BusinessPartner', 'BusinessPartnerFullName'],
+ * });
+ *
+ * // Get single entity
+ * const partner = await client.A_BusinessPartner.get('BP001');
+ *
+ * // Create entity
+ * const created = await client.A_BusinessPartner.create({
+ *   BusinessPartnerFullName: 'Acme Corp',
+ * });
+ *
+ * // Update entity
+ * const updated = await client.A_BusinessPartner.update('BP001', {
+ *   BusinessPartnerFullName: 'Acme Corporation',
+ * });
+ *
+ * // Delete entity
+ * await client.A_BusinessPartner.delete('BP001');
+ * ```
+ */
+declare class S4KitBase {
+    protected httpClient: HttpClient;
+    constructor(config: S4KitConfig | HttpClientConfig);
+    /**
+     * Add a request interceptor
+     * @example
+     * ```ts
+     * client.onRequest((req) => {
+     *   console.log(`${req.method} ${req.url}`);
+     *   return req;
+     * });
+     * ```
+     */
+    onRequest(interceptor: RequestInterceptor): this;
+    /**
+     * Add a response interceptor
+     * @example
+     * ```ts
+     * client.onResponse((res) => {
+     *   console.log(`Response: ${res.status}`);
+     *   return res;
+     * });
+     * ```
+     */
+    onResponse(interceptor: ResponseInterceptor): this;
+    /**
+     * Add an error interceptor
+     * @example
+     * ```ts
+     * client.onError((err) => {
+     *   console.error(`Error: ${err.message}`);
+     *   return err;
+     * });
+     * ```
+     */
+    onError(interceptor: ErrorInterceptor): this;
+    /**
+     * Execute multiple operations in a single batch request
+     *
+     * @example
+     * ```ts
+     * const results = await client.batch([
+     *   { method: 'GET', entity: 'Products', id: 1 },
+     *   { method: 'POST', entity: 'Products', data: { Name: 'New Product' } },
+     *   { method: 'PATCH', entity: 'Products', id: 2, data: { Price: 29.99 } },
+     *   { method: 'DELETE', entity: 'Products', id: 3 },
+     * ]);
+     *
+     * // Check results
+     * for (const result of results) {
+     *   if (result.success) {
+     *     console.log('Success:', result.data);
+     *   } else {
+     *     console.error('Failed:', result.error);
+     *   }
+     * }
+     * ```
+     */
+    batch<T = any>(operations: BatchOperation<T>[]): Promise<BatchResult<T>[]>;
+    /**
+     * Execute operations in an atomic changeset (all succeed or all fail)
+     *
+     * @example
+     * ```ts
+     * // All operations succeed or all fail together
+     * const results = await client.changeset({
+     *   operations: [
+     *     { method: 'POST', entity: 'Orders', data: orderData },
+     *     { method: 'POST', entity: 'OrderItems', data: item1Data },
+     *     { method: 'POST', entity: 'OrderItems', data: item2Data },
+     *   ]
+     * });
+     * ```
+     */
+    changeset<T = any>(changeset: Changeset): Promise<BatchResult<T>[]>;
+}
+/**
+ * Create S4Kit client with dynamic entity access
+ * Allows: client.Products.list() instead of client.sap.Products.list()
+ *
+ * Returns S4KitClientWithDynamicAccess which:
+ * - Without generated types: allows any entity access (returns EntityHandler<any>)
+ * - With generated types: provides full type inference for known entities
+ */
+declare function S4Kit(config: S4KitConfig | HttpClientConfig): S4KitClientWithDynamicAccess;
+declare namespace S4Kit {
+    var prototype: S4KitBase;
+}
+/**
+ * Create an S4Kit client instance
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 's4kit';
+ *
+ * const client = createClient({
+ *   apiKey: 'sk_live_xxx',
+ * });
+ *
+ * const products = await client.Products.list({ top: 10 });
+ * ```
+ */
+declare function createClient(config: S4KitConfig): S4KitClientWithDynamicAccess;
+
+/**
+ * Base S4Kit error class with enhanced OData support
+ */
+declare class S4KitError extends Error implements IS4KitError {
+    readonly status?: number;
+    readonly code?: string;
+    readonly odataError?: ODataError;
+    readonly request?: InterceptedRequest;
+    readonly suggestion?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        odataError?: ODataError;
+        request?: InterceptedRequest;
+        cause?: Error;
+        suggestion?: string;
+    });
+    /**
+     * Get a user-friendly error message with context
+     */
+    get friendlyMessage(): string;
+    /**
+     * Get actionable help text
+     */
+    get help(): string;
+    private extractEntityFromUrl;
+    /**
+     * Get all error details (for validation errors with multiple issues)
+     */
+    get details(): ODataErrorDetail[];
+    /**
+     * Check if this is a specific OData error code
+     */
+    hasCode(code: string): boolean;
+    /**
+     * Convert to a plain object for logging
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        status: number | undefined;
+        code: string | undefined;
+        odataError: ODataError | undefined;
+        request: {
+            method: string;
+            url: string;
+        } | undefined;
+    };
+}
+/**
+ * Network/connection error
+ */
+declare class NetworkError extends S4KitError {
+    constructor(message: string, options?: {
+        cause?: Error;
+        request?: InterceptedRequest;
+    });
+}
+/**
+ * Request timeout error
+ */
+declare class TimeoutError extends S4KitError {
+    constructor(timeout: number, options?: {
+        request?: InterceptedRequest;
+    });
+}
+/**
+ * Authentication error (401)
+ */
+declare class AuthenticationError extends S4KitError {
+    constructor(message?: string, options?: {
+        odataError?: ODataError;
+        request?: InterceptedRequest;
+    });
+}
+/**
+ * Authorization error (403)
+ */
+declare class AuthorizationError extends S4KitError {
+    constructor(message?: string, options?: {
+        odataError?: ODataError;
+        request?: InterceptedRequest;
+    });
+}
+/**
+ * Resource not found error (404)
+ */
+declare class NotFoundError extends S4KitError {
+    constructor(entity?: string, id?: string | number, options?: {
+        odataError?: ODataError;
+        request?: InterceptedRequest;
+    });
+}
+/**
+ * Validation error (400) with field-level details
+ */
+declare class ValidationError extends S4KitError {
+    readonly fieldErrors: Map<string, string>;
+    constructor(message: string, options?: {
+        odataError?: ODataError;
+        request?: InterceptedRequest;
+    });
+    /**
+     * Get error for a specific field
+     */
+    getFieldError(field: string): string | undefined;
+    /**
+     * Check if a specific field has an error
+     */
+    hasFieldError(field: string): boolean;
+}
+/**
+ * Conflict error (409) - e.g., optimistic locking failure
+ */
+declare class ConflictError extends S4KitError {
+    constructor(message?: string, options?: {
+        odataError?: ODataError;
+        request?: InterceptedRequest;
+    });
+}
+/**
+ * Rate limit exceeded error (429)
+ */
+declare class RateLimitError extends S4KitError {
+    readonly retryAfter?: number;
+    constructor(retryAfter?: number, options?: {
+        odataError?: ODataError;
+        request?: InterceptedRequest;
+    });
+}
+/**
+ * Server error (5xx)
+ */
+declare class ServerError extends S4KitError {
+    constructor(message?: string, status?: number, options?: {
+        odataError?: ODataError;
+        request?: InterceptedRequest;
+    });
+}
+/**
+ * Batch operation error with per-request results
+ */
+declare class BatchError extends S4KitError {
+    readonly results: Array<{
+        success: boolean;
+        error?: S4KitError;
+        index: number;
+    }>;
+    constructor(message: string, results: Array<{
+        success: boolean;
+        error?: S4KitError;
+        index: number;
+    }>);
+    /**
+     * Get all failed operations
+     */
+    get failures(): {
+        success: boolean;
+        error?: S4KitError;
+        index: number;
+    }[];
+    /**
+     * Get all successful operations
+     */
+    get successes(): {
+        success: boolean;
+        error?: S4KitError;
+        index: number;
+    }[];
+}
+/**
+ * Parse an HTTP response into the appropriate S4Kit error
+ */
+declare function parseHttpError(status: number, body: any, request?: InterceptedRequest): S4KitError;
+/**
+ * Parse OData error format from response body
+ */
+declare function parseODataError(body: any): ODataError | undefined;
+/**
+ * Check if an error is retryable
+ */
+declare function isRetryable(error: Error): boolean;
+/**
+ * Type guard: Check if error is an S4KitError
+ */
+declare function isS4KitError(error: unknown): error is S4KitError;
+
+/**
+ * Build OData query parameters from QueryOptions
+ */
+declare function buildQuery(options?: QueryOptions<any>): Record<string, string>;
+/**
+ * Build $filter string from various formats
+ * @example
+ * - String: "Name eq 'John'" → "Name eq 'John'"
+ * - Object: { Name: 'John' } → "Name eq 'John'"
+ * - Object: { Price: { gt: 100 } } → "Price gt 100"
+ * - Object: { Name: 'John', Active: true } → "Name eq 'John' and Active eq true"
+ * - Array: [{ Name: 'John' }, { Age: { gt: 18 } }] → "Name eq 'John' and Age gt 18"
+ * - OR: { $or: [{ A: 1 }, { B: 2 }] } → "(A eq 1 or B eq 2)"
+ * - NOT: { $not: { Status: 'deleted' } } → "not (Status eq 'deleted')"
+ * - Complex: { A: 1, $or: [{ B: 2 }, { C: 3 }] } → "A eq 1 and (B eq 2 or C eq 3)"
+ */
+declare function buildFilter(filter: Filter<any>): string;
+/**
+ * Create a fluent filter builder for type-safe filter construction
+ *
+ * @example
+ * ```ts
+ * const filter = createFilter<Product>()
+ *   .where('Price', 'gt', 100)
+ *   .and('Category', 'eq', 'Electronics')
+ *   .or('Name', 'contains', 'Pro')
+ *   .build();
+ * // Returns: "Price gt 100 and Category eq 'Electronics' or contains(Name,'Pro')"
+ * ```
+ */
+declare function createFilter<T = any>(): FilterBuilder<T>;
+declare class FilterBuilder<T = any> {
+    private parts;
+    /**
+     * Add a filter condition
+     */
+    where<K extends keyof T>(field: K, operator: FilterOperator, value: any): this;
+    /**
+     * Add AND condition
+     */
+    and<K extends keyof T>(field: K, operator: FilterOperator, value: any): this;
+    /**
+     * Add OR condition
+     */
+    or<K extends keyof T>(field: K, operator: FilterOperator, value: any): this;
+    /**
+     * Add NOT condition
+     */
+    not<K extends keyof T>(field: K, operator: FilterOperator, value: any): this;
+    /**
+     * Group conditions with parentheses
+     */
+    group(fn: (builder: FilterBuilder<T>) => FilterBuilder<T>): this;
+    /**
+     * Add raw filter expression
+     */
+    raw(expression: string): this;
+    /**
+     * Build the final filter string
+     */
+    build(): string;
+    /**
+     * Build a single condition
+     */
+    private buildCondition;
+    /**
+     * Format a value for OData filter
+     */
+    private formatValue;
+}
+
+/**
+ * Create a fluent query builder for an entity
+ *
+ * @example
+ * ```ts
+ * const products = await query(client.sap.Products)
+ *   .select('Name', 'Price')
+ *   .where('Price', 'gt', 100)
+ *   .orderBy('Name', 'asc')
+ *   .top(10)
+ *   .execute();
+ * ```
+ */
+declare function query<T>(handler: EntityHandler<T>): QueryBuilder<T>;
+declare class QueryBuilder<T> implements FluentQuery<T> {
+    private handler;
+    private options;
+    private filterParts;
+    constructor(handler: EntityHandler<T>);
+    /**
+     * Select specific fields
+     */
+    select<K extends keyof T>(...fields: K[]): QueryBuilder<Pick<T, K>>;
+    /**
+     * Add raw filter expression
+     */
+    filter(expression: string): this;
+    /**
+     * Add type-safe filter condition
+     */
+    where<K extends keyof T>(field: K, operator: FilterOperator, value: any): this;
+    /**
+     * Add AND condition
+     */
+    and<K extends keyof T>(field: K, operator: FilterOperator, value: any): this;
+    /**
+     * Add OR condition
+     */
+    or<K extends keyof T>(field: K, operator: FilterOperator, value: any): this;
+    /**
+     * Order by field
+     */
+    orderBy<K extends keyof T>(field: K, direction?: 'asc' | 'desc'): this;
+    /**
+     * Expand navigation property with optional nested query
+     */
+    expand(property: string, nested?: (q: FluentQuery<any>) => FluentQuery<any>): this;
+    /**
+     * Limit results
+     */
+    top(count: number): this;
+    /**
+     * Skip results (pagination)
+     */
+    skip(count: number): this;
+    /**
+     * Full-text search
+     */
+    search(term: string): this;
+    /**
+     * Request inline count
+     */
+    count(): this;
+    /**
+     * Execute query and return results
+     */
+    execute(): Promise<T[]>;
+    /**
+     * Execute query with inline count
+     */
+    executeWithCount(): Promise<ListResponse<T>>;
+    /**
+     * Execute and return first result (or undefined)
+     */
+    first(): Promise<T | undefined>;
+    /**
+     * Execute and return single result (throws if not exactly one)
+     */
+    single(): Promise<T>;
+    /**
+     * Build final query options
+     */
+    buildOptions(): QueryOptions<T>;
+}
+/**
+ * Format entity key for URL path
+ * Supports simple keys (string/number) and composite keys
+ */
+declare function formatKey(key: string | number | Record<string, string | number>): string;
+/**
+ * Build function/action parameters for URL
+ */
+declare function buildFunctionParams(params?: Record<string, any>): string;
+
+export { AuthenticationError, AuthorizationError, type BatchCreate, type BatchDelete, BatchError, type BatchGet, type BatchOperation, type BatchResult, type BatchUpdate, type Changeset, type CompositeKey, ConflictError, type DeepInsertData, type EntityHandler, type EntityKey, type ErrorInterceptor, type Expand, type ExpandNestedOptions, type ExpandObject, type ExpandValue, type Filter, FilterBuilder, type FilterComparisonOperator, type FilterCondition, type FilterExpression, type FilterLogical, type FilterObject, type FilterOperator, type FilterStringOperator, type FilterValue, type FluentQuery, type IS4KitError, type InterceptedRequest, type InterceptedResponse, type ListResponse, type LogicalOperator, NetworkError, NotFoundError, type ODataError, type ODataErrorDetail, type ODataResponse, type OrderBy, type OrderByObject, type OrderDirection, type PaginateOptions, QueryBuilder, type QueryOptions, RateLimitError, type RequestInterceptor, type ResponseInterceptor, S4Kit, type S4KitClient, type S4KitClientWithDynamicAccess, type S4KitConfig, S4KitError, ServerError, TimeoutError, ValidationError, buildFilter, buildFunctionParams, buildQuery, createClient, createFilter, formatKey, isRetryable, isS4KitError, parseHttpError, parseODataError, query };