s4kit 0.0.1 → 0.1.1

package/dist/index.js

@@ -0,0 +1,1600 @@
+// src/http-client.ts
+import ky from "ky";
+
+// src/errors.ts
+var S4KitError = class extends Error {
+  status;
+  code;
+  odataError;
+  request;
+  suggestion;
+  constructor(message, options) {
+    super(message, { cause: options?.cause });
+    this.name = "S4KitError";
+    this.status = options?.status;
+    this.code = options?.code;
+    this.odataError = options?.odataError;
+    this.request = options?.request;
+    this.suggestion = options?.suggestion;
+  }
+  /**
+   * Get a user-friendly error message with context
+   */
+  get friendlyMessage() {
+    const parts = [];
+    if (this.request?.url) {
+      const entity = this.extractEntityFromUrl(this.request.url);
+      if (entity) {
+        parts.push(`[${entity}]`);
+      }
+    }
+    parts.push(this.odataError?.message ?? this.message);
+    return parts.join(" ");
+  }
+  /**
+   * Get actionable help text
+   */
+  get help() {
+    if (this.suggestion) return this.suggestion;
+    return getSuggestionForError(this);
+  }
+  extractEntityFromUrl(url) {
+    const match = url.match(/\/([A-Z][A-Za-z_]+)(?:\(|$|\?)/);
+    return match?.[1] ?? null;
+  }
+  /**
+   * Get all error details (for validation errors with multiple issues)
+   */
+  get details() {
+    return this.odataError?.details ?? [];
+  }
+  /**
+   * Check if this is a specific OData error code
+   */
+  hasCode(code) {
+    return this.code === code || this.odataError?.code === code;
+  }
+  /**
+   * Convert to a plain object for logging
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      code: this.code,
+      odataError: this.odataError,
+      request: this.request ? {
+        method: this.request.method,
+        url: this.request.url
+      } : void 0
+    };
+  }
+};
+var NetworkError = class extends S4KitError {
+  constructor(message, options) {
+    super(message, { ...options, code: "NETWORK_ERROR" });
+    this.name = "NetworkError";
+  }
+};
+var TimeoutError = class extends S4KitError {
+  constructor(timeout, options) {
+    super(`Request timed out after ${timeout}ms`, { ...options, code: "TIMEOUT" });
+    this.name = "TimeoutError";
+  }
+};
+var AuthenticationError = class extends S4KitError {
+  constructor(message = "Authentication failed", options) {
+    super(message, { ...options, status: 401, code: "UNAUTHORIZED" });
+    this.name = "AuthenticationError";
+  }
+};
+var AuthorizationError = class extends S4KitError {
+  constructor(message = "Access denied", options) {
+    super(message, { ...options, status: 403, code: "FORBIDDEN" });
+    this.name = "AuthorizationError";
+  }
+};
+var NotFoundError = class extends S4KitError {
+  constructor(entity, id, options) {
+    const message = entity && id ? `${entity}(${id}) not found` : entity ? `${entity} not found` : "Resource not found";
+    super(message, { ...options, status: 404, code: "NOT_FOUND" });
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends S4KitError {
+  fieldErrors;
+  constructor(message, options) {
+    super(message, { ...options, status: 400, code: "VALIDATION_ERROR" });
+    this.name = "ValidationError";
+    this.fieldErrors = /* @__PURE__ */ new Map();
+    if (options?.odataError?.details) {
+      for (const detail of options.odataError.details) {
+        if (detail.target) {
+          this.fieldErrors.set(detail.target, detail.message);
+        }
+      }
+    }
+  }
+  /**
+   * Get error for a specific field
+   */
+  getFieldError(field) {
+    return this.fieldErrors.get(field);
+  }
+  /**
+   * Check if a specific field has an error
+   */
+  hasFieldError(field) {
+    return this.fieldErrors.has(field);
+  }
+};
+var ConflictError = class extends S4KitError {
+  constructor(message = "Resource conflict", options) {
+    super(message, { ...options, status: 409, code: "CONFLICT" });
+    this.name = "ConflictError";
+  }
+};
+var RateLimitError = class extends S4KitError {
+  retryAfter;
+  constructor(retryAfter, options) {
+    super(
+      retryAfter ? `Rate limit exceeded. Retry after ${retryAfter} seconds` : "Rate limit exceeded",
+      { ...options, status: 429, code: "RATE_LIMIT_EXCEEDED" }
+    );
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var ServerError = class extends S4KitError {
+  constructor(message = "Internal server error", status = 500, options) {
+    super(message, { ...options, status, code: "SERVER_ERROR" });
+    this.name = "ServerError";
+  }
+};
+var BatchError = class extends S4KitError {
+  results;
+  constructor(message, results) {
+    super(message, { code: "BATCH_ERROR" });
+    this.name = "BatchError";
+    this.results = results;
+  }
+  /**
+   * Get all failed operations
+   */
+  get failures() {
+    return this.results.filter((r) => !r.success);
+  }
+  /**
+   * Get all successful operations
+   */
+  get successes() {
+    return this.results.filter((r) => r.success);
+  }
+};
+function parseHttpError(status, body, request) {
+  const odataError = parseODataError(body);
+  const message = odataError?.message ?? getDefaultMessage(status);
+  switch (status) {
+    case 400:
+      return new ValidationError(message, { odataError, request });
+    case 401:
+      return new AuthenticationError(message, { odataError, request });
+    case 403:
+      return new AuthorizationError(message, { odataError, request });
+    case 404:
+      return new NotFoundError(void 0, void 0, { odataError, request });
+    case 409:
+      return new ConflictError(message, { odataError, request });
+    case 429:
+      return new RateLimitError(void 0, { odataError, request });
+    default:
+      if (status >= 500) {
+        return new ServerError(message, status, { odataError, request });
+      }
+      return new S4KitError(message, { status, odataError, request });
+  }
+}
+function parseODataError(body) {
+  if (!body) return void 0;
+  if (body.error?.message?.value) {
+    return {
+      code: body.error.code ?? "UNKNOWN",
+      message: body.error.message.value
+    };
+  }
+  if (body.error) {
+    return {
+      code: body.error.code ?? "UNKNOWN",
+      message: body.error.message ?? "Unknown error",
+      target: body.error.target,
+      details: body.error.details,
+      innererror: body.error.innererror
+    };
+  }
+  if (body["odata.error"]) {
+    return {
+      code: body["odata.error"].code ?? "UNKNOWN",
+      message: body["odata.error"].message?.value ?? "Unknown error"
+    };
+  }
+  return void 0;
+}
+function getDefaultMessage(status) {
+  const messages = {
+    400: "Bad request",
+    401: "Authentication required",
+    403: "Access denied",
+    404: "Resource not found",
+    405: "Method not allowed",
+    409: "Resource conflict",
+    429: "Too many requests",
+    500: "Internal server error",
+    502: "Bad gateway",
+    503: "Service unavailable",
+    504: "Gateway timeout"
+  };
+  return messages[status] ?? `HTTP error ${status}`;
+}
+function isRetryable(error) {
+  if (error instanceof NetworkError) return true;
+  if (error instanceof TimeoutError) return true;
+  if (error instanceof RateLimitError) return true;
+  if (error instanceof ServerError && error.status !== 501) return true;
+  return false;
+}
+function isS4KitError(error) {
+  return error instanceof S4KitError;
+}
+function getSuggestionForError(error) {
+  if (error instanceof AuthenticationError) {
+    return "Check that your API key is valid and not expired. Get a new key from the S4Kit dashboard.";
+  }
+  if (error instanceof AuthorizationError) {
+    return "Your API key may not have permission for this operation. Check your key permissions in the dashboard.";
+  }
+  if (error instanceof NotFoundError) {
+    const entity = error.request?.url?.match(/\/([A-Z][A-Za-z_]+)/)?.[1];
+    if (entity) {
+      return `Verify that "${entity}" exists and the ID is correct. Use .list() to see available entities.`;
+    }
+    return "The requested resource was not found. Verify the entity name and ID.";
+  }
+  if (error instanceof ValidationError) {
+    if (error.fieldErrors.size > 0) {
+      const fields = Array.from(error.fieldErrors.keys()).join(", ");
+      return `Fix the following fields: ${fields}`;
+    }
+    return "Check the request data for missing or invalid fields.";
+  }
+  if (error instanceof RateLimitError) {
+    if (error.retryAfter) {
+      return `Wait ${error.retryAfter} seconds before retrying. Consider implementing request throttling.`;
+    }
+    return "You have exceeded the rate limit. Implement exponential backoff or reduce request frequency.";
+  }
+  if (error instanceof NetworkError) {
+    return "Check your network connection. If the problem persists, the S4Kit API may be temporarily unavailable.";
+  }
+  if (error instanceof TimeoutError) {
+    return "The request timed out. Try increasing the timeout or reducing the amount of data requested.";
+  }
+  if (error instanceof ServerError) {
+    return "This is a server-side issue. If it persists, contact S4Kit support with the error details.";
+  }
+  return "See the error details for more information.";
+}
+
+// src/http-client.ts
+function generateUUID() {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+var HttpClient = class {
+  client;
+  config;
+  requestInterceptors = [];
+  responseInterceptors = [];
+  errorInterceptors = [];
+  debug;
+  constructor(config) {
+    this.config = config;
+    this.debug = config.debug ?? false;
+    if (config.onRequest) this.requestInterceptors = [...config.onRequest];
+    if (config.onResponse) this.responseInterceptors = [...config.onResponse];
+    if (config.onError) this.errorInterceptors = [...config.onError];
+    this.client = ky.create({
+      prefixUrl: config.baseUrl || "https://api.s4kit.com/api/proxy",
+      timeout: config.timeout ?? 3e4,
+      retry: config.retries ?? 0,
+      headers: {
+        "Authorization": `Bearer ${config.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      hooks: {
+        beforeError: [
+          async (error) => {
+            const request = {
+              url: error.request?.url ?? "",
+              method: error.request?.method ?? "UNKNOWN",
+              headers: Object.fromEntries(error.request?.headers?.entries() ?? [])
+            };
+            let s4kitError;
+            if (error.name === "TimeoutError") {
+              s4kitError = new TimeoutError(this.config.timeout ?? 3e4, { request });
+            } else if (error.response) {
+              const body = await error.response.json().catch(() => ({}));
+              s4kitError = parseHttpError(error.response.status, body, request);
+            } else {
+              s4kitError = new NetworkError(error.message, { cause: error, request });
+            }
+            let finalError = s4kitError;
+            for (const interceptor of this.errorInterceptors) {
+              const result = await interceptor(finalError);
+              if (result instanceof S4KitError) {
+                finalError = result;
+              }
+            }
+            throw finalError;
+          }
+        ]
+      }
+    });
+  }
+  // ==========================================================================
+  // Interceptor Management
+  // ==========================================================================
+  /**
+   * Add a request interceptor
+   * @example
+   * ```ts
+   * client.onRequest((req) => {
+   *   console.log(`${req.method} ${req.url}`);
+   *   return req;
+   * });
+   * ```
+   */
+  onRequest(interceptor) {
+    this.requestInterceptors.push(interceptor);
+    return this;
+  }
+  /**
+   * Add a response interceptor
+   * @example
+   * ```ts
+   * client.onResponse((res) => {
+   *   console.log(`Response: ${res.status}`);
+   *   return res;
+   * });
+   * ```
+   */
+  onResponse(interceptor) {
+    this.responseInterceptors.push(interceptor);
+    return this;
+  }
+  /**
+   * Add an error interceptor
+   * @example
+   * ```ts
+   * client.onError((err) => {
+   *   if (err.status === 401) {
+   *     // Refresh token logic
+   *   }
+   *   return err;
+   * });
+   * ```
+   */
+  onError(interceptor) {
+    this.errorInterceptors.push(interceptor);
+    return this;
+  }
+  // ==========================================================================
+  // Debug Logging
+  // ==========================================================================
+  log(message, data) {
+    if (!this.debug) return;
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const prefix = `[s4kit ${timestamp}]`;
+    if (data !== void 0) {
+      console.log(prefix, message, data);
+    } else {
+      console.log(prefix, message);
+    }
+  }
+  // ==========================================================================
+  // Header Building
+  // ==========================================================================
+  buildHeaders(options) {
+    const headers = {};
+    const conn = options?.connection || this.config.connection;
+    const svc = options?.service || this.config.service;
+    if (conn) headers["X-S4Kit-Connection"] = conn;
+    if (svc) headers["X-S4Kit-Service"] = svc;
+    if (options?.raw) headers["X-S4Kit-Raw"] = "true";
+    if (options?.headers) {
+      Object.assign(headers, options.headers);
+    }
+    return headers;
+  }
+  // ==========================================================================
+  // Request Execution
+  // ==========================================================================
+  async executeRequest(method, path, options = {}, requestOptions) {
+    const startTime = Date.now();
+    const headers = this.buildHeaders(requestOptions);
+    let request = {
+      url: path,
+      method,
+      headers: { ...headers },
+      body: options.json,
+      searchParams: options.searchParams
+    };
+    for (const interceptor of this.requestInterceptors) {
+      request = await interceptor(request);
+    }
+    this.log(`\u2192 ${method} ${path}`, request.searchParams ? `?${new URLSearchParams(request.searchParams)}` : "");
+    if (request.body) {
+      this.log("  Body:", request.body);
+    }
+    const response = await this.client(request.url, {
+      method: request.method,
+      headers: request.headers,
+      json: request.body,
+      searchParams: request.searchParams
+    });
+    const duration = Date.now() - startTime;
+    const data = await response.json();
+    this.log(`\u2190 ${response.status} (${duration}ms)`);
+    if (this.debug && data) {
+      const preview = JSON.stringify(data).slice(0, 200);
+      this.log("  Data:", preview + (preview.length >= 200 ? "..." : ""));
+    }
+    let interceptedResponse = {
+      status: response.status,
+      headers: Object.fromEntries(response.headers.entries()),
+      data
+    };
+    for (const interceptor of this.responseInterceptors) {
+      interceptedResponse = await interceptor(interceptedResponse);
+    }
+    return interceptedResponse.data;
+  }
+  // ==========================================================================
+  // HTTP Methods
+  // ==========================================================================
+  async get(path, searchParams, options) {
+    return this.executeRequest("GET", path, { searchParams }, options);
+  }
+  async post(path, json, options) {
+    return this.executeRequest("POST", path, { json }, options);
+  }
+  async put(path, json, options) {
+    return this.executeRequest("PUT", path, { json }, options);
+  }
+  async patch(path, json, options) {
+    return this.executeRequest("PATCH", path, { json }, options);
+  }
+  async delete(path, options) {
+    await this.executeRequest("DELETE", path, {}, options);
+  }
+  // ==========================================================================
+  // Batch Operations
+  // ==========================================================================
+  /**
+   * 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 },
+   * ]);
+   * ```
+   */
+  async batch(operations, options) {
+    const boundary = `batch_${generateUUID()}`;
+    const body = this.buildBatchBody(operations, boundary);
+    const headers = {
+      ...this.buildHeaders(options),
+      "Content-Type": `multipart/mixed; boundary=${boundary}`
+    };
+    const response = await this.client.post("$batch", {
+      body,
+      headers
+    });
+    return this.parseBatchResponse(await response.text());
+  }
+  /**
+   * 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 },
+   *   ]
+   * });
+   * ```
+   */
+  async changeset(changeset, options) {
+    const batchBoundary = `batch_${generateUUID()}`;
+    const changesetBoundary = `changeset_${generateUUID()}`;
+    const body = this.buildChangesetBody(changeset, batchBoundary, changesetBoundary);
+    const headers = {
+      ...this.buildHeaders(options),
+      "Content-Type": `multipart/mixed; boundary=${batchBoundary}`
+    };
+    const response = await this.client.post("$batch", {
+      body,
+      headers
+    });
+    return this.parseBatchResponse(await response.text());
+  }
+  buildBatchBody(operations, boundary) {
+    const parts = [];
+    for (const op of operations) {
+      parts.push(`--${boundary}`);
+      parts.push("Content-Type: application/http");
+      parts.push("Content-Transfer-Encoding: binary");
+      parts.push("");
+      parts.push(this.buildBatchPart(op));
+    }
+    parts.push(`--${boundary}--`);
+    return parts.join("\r\n");
+  }
+  buildChangesetBody(changeset, batchBoundary, changesetBoundary) {
+    const parts = [];
+    parts.push(`--${batchBoundary}`);
+    parts.push(`Content-Type: multipart/mixed; boundary=${changesetBoundary}`);
+    parts.push("");
+    for (const op of changeset.operations) {
+      parts.push(`--${changesetBoundary}`);
+      parts.push("Content-Type: application/http");
+      parts.push("Content-Transfer-Encoding: binary");
+      parts.push("");
+      parts.push(this.buildBatchPart(op));
+    }
+    parts.push(`--${changesetBoundary}--`);
+    parts.push(`--${batchBoundary}--`);
+    return parts.join("\r\n");
+  }
+  buildBatchPart(op) {
+    const lines = [];
+    let path;
+    switch (op.method) {
+      case "GET":
+        path = op.id ? `${op.entity}(${this.formatKey(op.id)})` : op.entity;
+        lines.push(`GET ${path} HTTP/1.1`);
+        lines.push("Accept: application/json");
+        break;
+      case "POST":
+        lines.push(`POST ${op.entity} HTTP/1.1`);
+        lines.push("Content-Type: application/json");
+        lines.push("");
+        lines.push(JSON.stringify(op.data));
+        break;
+      case "PATCH":
+      case "PUT":
+        path = `${op.entity}(${this.formatKey(op.id)})`;
+        lines.push(`${op.method} ${path} HTTP/1.1`);
+        lines.push("Content-Type: application/json");
+        lines.push("");
+        lines.push(JSON.stringify(op.data));
+        break;
+      case "DELETE":
+        path = `${op.entity}(${this.formatKey(op.id)})`;
+        lines.push(`DELETE ${path} HTTP/1.1`);
+        break;
+    }
+    return lines.join("\r\n");
+  }
+  formatKey(key) {
+    if (typeof key === "number") return String(key);
+    if (typeof key === "string") return `'${key}'`;
+    return Object.entries(key).map(([k, v]) => `${k}=${typeof v === "string" ? `'${v}'` : v}`).join(",");
+  }
+  parseBatchResponse(responseText) {
+    const results = [];
+    const parts = responseText.split(/--batch_[a-f0-9-]+/);
+    for (const part of parts) {
+      if (!part.trim() || part.trim() === "--") continue;
+      const statusMatch = part.match(/HTTP\/1\.1 (\d+)/);
+      if (!statusMatch || !statusMatch[1]) continue;
+      const status = parseInt(statusMatch[1], 10);
+      const jsonMatch = part.match(/\{[\s\S]*\}/);
+      if (status >= 200 && status < 300) {
+        results.push({
+          success: true,
+          status,
+          data: jsonMatch ? JSON.parse(jsonMatch[0]) : void 0
+        });
+      } else {
+        results.push({
+          success: false,
+          status,
+          error: jsonMatch ? { code: "BATCH_ERROR", message: JSON.parse(jsonMatch[0])?.error?.message ?? "Unknown error" } : { code: "BATCH_ERROR", message: "Unknown error" }
+        });
+      }
+    }
+    return results;
+  }
+};
+
+// src/query-builder.ts
+function getExpandSelectPaths(expand) {
+  const paths = [];
+  if (Array.isArray(expand)) {
+    for (const item of expand) {
+      paths.push(item);
+    }
+    return paths;
+  }
+  for (const [property, value] of Object.entries(expand)) {
+    if (value === true) {
+      paths.push(property);
+    } else if (isExpandNestedOptions(value)) {
+      if (value.select?.length) {
+        for (const field of value.select) {
+          paths.push(`${property}/${field}`);
+        }
+      } else {
+        paths.push(property);
+      }
+    }
+  }
+  return paths;
+}
+function buildQuery(options) {
+  if (!options) return {};
+  const params = {};
+  let selectFields = options.select ? [...options.select] : [];
+  if (options.expand) {
+    const isArrayWithLength = Array.isArray(options.expand) && options.expand.length > 0;
+    const isObjectWithKeys = !Array.isArray(options.expand) && typeof options.expand === "object" && Object.keys(options.expand).length > 0;
+    if (isArrayWithLength || isObjectWithKeys) {
+      params["$expand"] = buildExpand(options.expand);
+      if (selectFields.length > 0) {
+        const expandPaths = getExpandSelectPaths(options.expand);
+        for (const path of expandPaths) {
+          if (!selectFields.includes(path)) {
+            selectFields.push(path);
+          }
+        }
+      }
+    }
+  }
+  if (selectFields.length > 0) {
+    params["$select"] = selectFields.join(",");
+  }
+  if (options.filter !== void 0 && options.filter !== null) {
+    const filterStr = buildFilter(options.filter);
+    if (filterStr) {
+      params["$filter"] = filterStr;
+    }
+  }
+  if (options.top !== void 0) {
+    params["$top"] = String(options.top);
+  }
+  if (options.skip !== void 0) {
+    params["$skip"] = String(options.skip);
+  }
+  if (options.orderBy) {
+    params["$orderby"] = buildOrderBy(options.orderBy);
+  }
+  if (options.count) {
+    params["$count"] = "true";
+  }
+  if (options.search) {
+    params["$search"] = options.search;
+  }
+  return params;
+}
+function buildOrderBy(orderBy) {
+  if (typeof orderBy === "string") {
+    return orderBy;
+  }
+  if (Array.isArray(orderBy)) {
+    return orderBy.map((obj) => buildOrderByObject(obj)).join(",");
+  }
+  return buildOrderByObject(orderBy);
+}
+function buildOrderByObject(obj) {
+  return Object.entries(obj).map(([field, direction]) => `${field}${direction ? " " + direction : ""}`).join(",");
+}
+function formatFilterValue(value) {
+  if (value === null) return "null";
+  if (typeof value === "string") return `'${value.replace(/'/g, "''")}'`;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") return String(value);
+  if (value instanceof Date) return value.toISOString();
+  return String(value);
+}
+function isFilterCondition(value) {
+  if (value === null || typeof value !== "object" || value instanceof Date) {
+    return false;
+  }
+  const operators = ["eq", "ne", "gt", "ge", "lt", "le", "contains", "startswith", "endswith", "in", "between"];
+  return Object.keys(value).some((key) => operators.includes(key));
+}
+function buildFieldConditions(field, value) {
+  if (!isFilterCondition(value)) {
+    return [`${field} eq ${formatFilterValue(value)}`];
+  }
+  const conditions = [];
+  const condition = value;
+  for (const [op, val] of Object.entries(condition)) {
+    if (val === void 0) continue;
+    switch (op) {
+      case "eq":
+      case "ne":
+      case "gt":
+      case "ge":
+      case "lt":
+      case "le":
+        conditions.push(`${field} ${op} ${formatFilterValue(val)}`);
+        break;
+      case "contains":
+        conditions.push(`contains(${field},${formatFilterValue(val)})`);
+        break;
+      case "startswith":
+        conditions.push(`startswith(${field},${formatFilterValue(val)})`);
+        break;
+      case "endswith":
+        conditions.push(`endswith(${field},${formatFilterValue(val)})`);
+        break;
+      case "in":
+        if (Array.isArray(val)) {
+          const inValues = val.map((v) => formatFilterValue(v)).join(",");
+          conditions.push(`${field} in (${inValues})`);
+        }
+        break;
+      case "between":
+        if (Array.isArray(val) && val.length === 2) {
+          conditions.push(`${field} ge ${formatFilterValue(val[0])} and ${field} le ${formatFilterValue(val[1])}`);
+        }
+        break;
+    }
+  }
+  return conditions;
+}
+var LOGICAL_OPERATORS = ["$or", "$and", "$not"];
+function isLogicalOperator(key) {
+  return LOGICAL_OPERATORS.includes(key);
+}
+function buildFilterExpression(filter) {
+  const parts = [];
+  const fieldConditions = [];
+  for (const [key, value] of Object.entries(filter)) {
+    if (value === void 0) continue;
+    if (isLogicalOperator(key)) continue;
+    fieldConditions.push(...buildFieldConditions(key, value));
+  }
+  if (fieldConditions.length > 0) {
+    if (fieldConditions.length === 1) {
+      parts.push(fieldConditions[0]);
+    } else {
+      parts.push(fieldConditions.join(" and "));
+    }
+  }
+  if (filter.$and && Array.isArray(filter.$and)) {
+    const andParts = filter.$and.map((expr) => buildFilterExpression(expr)).filter((s) => Boolean(s));
+    if (andParts.length > 0) {
+      const andStr = andParts.length === 1 ? andParts[0] : `(${andParts.join(" and ")})`;
+      parts.push(andStr);
+    }
+  }
+  if (filter.$or && Array.isArray(filter.$or)) {
+    const orParts = filter.$or.map((expr) => buildFilterExpression(expr)).filter((s) => Boolean(s));
+    if (orParts.length > 0) {
+      const orStr = orParts.length === 1 ? orParts[0] : `(${orParts.join(" or ")})`;
+      parts.push(orStr);
+    }
+  }
+  if (filter.$not) {
+    const notExpr = buildFilterExpression(filter.$not);
+    if (notExpr) {
+      parts.push(`not (${notExpr})`);
+    }
+  }
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0];
+  return parts.join(" and ");
+}
+function buildFilter(filter) {
+  if (typeof filter === "string") {
+    return filter;
+  }
+  if (Array.isArray(filter)) {
+    const parts = filter.map((f) => buildFilterExpression(f)).filter((s) => Boolean(s));
+    if (parts.length === 0) return "";
+    if (parts.length === 1) return parts[0];
+    return parts.join(" and ");
+  }
+  return buildFilterExpression(filter);
+}
+function isExpandNestedOptions(value) {
+  if (value === true || value === null || typeof value !== "object") {
+    return false;
+  }
+  const optionKeys = ["select", "filter", "top", "skip", "orderBy", "expand"];
+  return Object.keys(value).some((key) => optionKeys.includes(key));
+}
+function buildNestedExpandOptions(options) {
+  const parts = [];
+  if (options.filter !== void 0 && options.filter !== null) {
+    const filterStr = typeof options.filter === "string" ? options.filter : buildFilter(options.filter);
+    if (filterStr) {
+      parts.push(`$filter=${filterStr}`);
+    }
+  }
+  if (options.top !== void 0) {
+    parts.push(`$top=${options.top}`);
+  }
+  if (options.skip !== void 0) {
+    parts.push(`$skip=${options.skip}`);
+  }
+  if (options.orderBy) {
+    const orderByStr = typeof options.orderBy === "string" ? options.orderBy : buildOrderBy(options.orderBy);
+    parts.push(`$orderby=${orderByStr}`);
+  }
+  if (options.expand) {
+    parts.push(`$expand=${buildExpand(options.expand)}`);
+  }
+  return parts.length > 0 ? `(${parts.join(";")})` : "";
+}
+function buildExpand(expand) {
+  if (Array.isArray(expand)) {
+    return expand.join(",");
+  }
+  return Object.entries(expand).map(([property, value]) => {
+    if (value === true) {
+      return property;
+    }
+    if (isExpandNestedOptions(value)) {
+      return property + buildNestedExpandOptions(value);
+    }
+    return property;
+  }).filter(Boolean).join(",");
+}
+function createFilter() {
+  return new FilterBuilder();
+}
+var FilterBuilder = class _FilterBuilder {
+  parts = [];
+  /**
+   * Add a filter condition
+   */
+  where(field, operator, value) {
+    this.parts.push(this.buildCondition(String(field), operator, value));
+    return this;
+  }
+  /**
+   * Add AND condition
+   */
+  and(field, operator, value) {
+    if (this.parts.length > 0) {
+      this.parts.push("and");
+    }
+    this.parts.push(this.buildCondition(String(field), operator, value));
+    return this;
+  }
+  /**
+   * Add OR condition
+   */
+  or(field, operator, value) {
+    if (this.parts.length > 0) {
+      this.parts.push("or");
+    }
+    this.parts.push(this.buildCondition(String(field), operator, value));
+    return this;
+  }
+  /**
+   * Add NOT condition
+   */
+  not(field, operator, value) {
+    this.parts.push(`not ${this.buildCondition(String(field), operator, value)}`);
+    return this;
+  }
+  /**
+   * Group conditions with parentheses
+   */
+  group(fn) {
+    const nested = fn(new _FilterBuilder());
+    const nestedFilter = nested.build();
+    if (nestedFilter) {
+      this.parts.push(`(${nestedFilter})`);
+    }
+    return this;
+  }
+  /**
+   * Add raw filter expression
+   */
+  raw(expression) {
+    this.parts.push(expression);
+    return this;
+  }
+  /**
+   * Build the final filter string
+   */
+  build() {
+    return this.parts.join(" ");
+  }
+  /**
+   * Build a single condition
+   */
+  buildCondition(field, operator, value) {
+    const formattedValue = this.formatValue(value);
+    switch (operator) {
+      case "eq":
+      case "ne":
+      case "gt":
+      case "ge":
+      case "lt":
+      case "le":
+        return `${field} ${operator} ${formattedValue}`;
+      case "contains":
+        return `contains(${field},${formattedValue})`;
+      case "startswith":
+        return `startswith(${field},${formattedValue})`;
+      case "endswith":
+        return `endswith(${field},${formattedValue})`;
+      case "in":
+        if (!Array.isArray(value)) {
+          throw new Error('Value for "in" operator must be an array');
+        }
+        const inValues = value.map((v) => this.formatValue(v)).join(",");
+        return `${field} in (${inValues})`;
+      case "has":
+        return `${field} has ${formattedValue}`;
+      default:
+        throw new Error(`Unknown operator: ${operator}`);
+    }
+  }
+  /**
+   * Format a value for OData filter
+   */
+  formatValue(value) {
+    if (value === null) return "null";
+    if (typeof value === "string") return `'${value.replace(/'/g, "''")}'`;
+    if (typeof value === "boolean") return value ? "true" : "false";
+    if (typeof value === "number") return String(value);
+    if (value instanceof Date) return value.toISOString();
+    if (typeof value === "object") return JSON.stringify(value);
+    return String(value);
+  }
+};
+function query(handler) {
+  return new QueryBuilder(handler);
+}
+var QueryBuilder = class _QueryBuilder {
+  handler;
+  options = {};
+  filterParts = [];
+  constructor(handler) {
+    this.handler = handler;
+  }
+  /**
+   * Select specific fields
+   */
+  select(...fields) {
+    this.options.select = fields;
+    return this;
+  }
+  /**
+   * Add raw filter expression
+   */
+  filter(expression) {
+    this.filterParts.push(expression);
+    return this;
+  }
+  /**
+   * Add type-safe filter condition
+   */
+  where(field, operator, value) {
+    const condition = new FilterBuilder().where(field, operator, value).build();
+    this.filterParts.push(condition);
+    return this;
+  }
+  /**
+   * Add AND condition
+   */
+  and(field, operator, value) {
+    if (this.filterParts.length === 0) {
+      return this.where(field, operator, value);
+    }
+    const condition = new FilterBuilder().where(field, operator, value).build();
+    const last = this.filterParts.pop();
+    this.filterParts.push(`${last} and ${condition}`);
+    return this;
+  }
+  /**
+   * Add OR condition
+   */
+  or(field, operator, value) {
+    if (this.filterParts.length === 0) {
+      return this.where(field, operator, value);
+    }
+    const condition = new FilterBuilder().where(field, operator, value).build();
+    const last = this.filterParts.pop();
+    this.filterParts.push(`${last} or ${condition}`);
+    return this;
+  }
+  /**
+   * Order by field
+   */
+  orderBy(field, direction = "asc") {
+    const current = this.options.orderBy;
+    if (typeof current === "string" && current) {
+      this.options.orderBy = `${current},${String(field)} ${direction}`;
+    } else {
+      this.options.orderBy = `${String(field)} ${direction}`;
+    }
+    return this;
+  }
+  /**
+   * Expand navigation property with optional nested query
+   */
+  expand(property, nested) {
+    if (!this.options.expand || Array.isArray(this.options.expand)) {
+      const existing = this.options.expand;
+      this.options.expand = {};
+      if (existing) {
+        for (const prop of existing) {
+          this.options.expand[prop] = true;
+        }
+      }
+    }
+    if (nested) {
+      const nestedBuilder = new _QueryBuilder({ list: async () => [] });
+      nested(nestedBuilder);
+      const nestedOptions = nestedBuilder.buildOptions();
+      this.options.expand[property] = {
+        select: nestedOptions.select,
+        filter: nestedOptions.filter,
+        top: nestedOptions.top,
+        orderBy: nestedOptions.orderBy
+      };
+    } else {
+      this.options.expand[property] = true;
+    }
+    return this;
+  }
+  /**
+   * Limit results
+   */
+  top(count) {
+    this.options.top = count;
+    return this;
+  }
+  /**
+   * Skip results (pagination)
+   */
+  skip(count) {
+    this.options.skip = count;
+    return this;
+  }
+  /**
+   * Full-text search
+   */
+  search(term) {
+    this.options.search = term;
+    return this;
+  }
+  /**
+   * Request inline count
+   */
+  count() {
+    this.options.count = true;
+    return this;
+  }
+  /**
+   * Execute query and return results
+   */
+  async execute() {
+    return this.handler.list(this.buildOptions());
+  }
+  /**
+   * Execute query with inline count
+   */
+  async executeWithCount() {
+    return this.handler.listWithCount(this.buildOptions());
+  }
+  /**
+   * Execute and return first result (or undefined)
+   */
+  async first() {
+    this.options.top = 1;
+    const results = await this.execute();
+    return results[0];
+  }
+  /**
+   * Execute and return single result (throws if not exactly one)
+   */
+  async single() {
+    this.options.top = 2;
+    const results = await this.execute();
+    if (results.length === 0) {
+      throw new Error("No results found");
+    }
+    if (results.length > 1) {
+      throw new Error("Multiple results found, expected exactly one");
+    }
+    return results[0];
+  }
+  /**
+   * Build final query options
+   */
+  buildOptions() {
+    if (this.filterParts.length > 0) {
+      this.options.filter = this.filterParts.join(" and ");
+    }
+    return { ...this.options };
+  }
+};
+function formatKey(key) {
+  if (typeof key === "number") {
+    return String(key);
+  }
+  if (typeof key === "string") {
+    if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(key)) {
+      return key;
+    }
+    return `'${key.replace(/'/g, "''")}'`;
+  }
+  const parts = Object.entries(key).map(([k, v]) => `${k}=${typeof v === "string" ? `'${v.replace(/'/g, "''")}'` : v}`).join(",");
+  return parts;
+}
+function buildFunctionParams(params) {
+  if (!params || Object.keys(params).length === 0) {
+    return "";
+  }
+  const formatted = Object.entries(params).map(([key, value]) => {
+    if (typeof value === "string") {
+      return `${key}='${value.replace(/'/g, "''")}'`;
+    }
+    if (value === null) {
+      return `${key}=null`;
+    }
+    if (typeof value === "boolean") {
+      return `${key}=${value}`;
+    }
+    if (value instanceof Date) {
+      return `${key}=${value.toISOString()}`;
+    }
+    return `${key}=${value}`;
+  }).join(",");
+  return formatted;
+}
+
+// src/proxy.ts
+function extractRequestOptions(options) {
+  if (!options) return void 0;
+  const { connection, service, raw } = options;
+  if (!connection && !service && !raw) return void 0;
+  return { connection, service, raw };
+}
+function formatId(id) {
+  return formatKey(id);
+}
+function extractData(response) {
+  if (Array.isArray(response)) return response;
+  if (response?.data && Array.isArray(response.data)) return response.data;
+  if (response?.value && Array.isArray(response.value)) return response.value;
+  if (response?.d?.results && Array.isArray(response.d.results)) return response.d.results;
+  return [];
+}
+function extractSingle(response) {
+  if (response?.data && !Array.isArray(response.data)) return response.data;
+  if (response?.d) return response.d;
+  return response;
+}
+function extractCount(response) {
+  if (response?.count !== void 0) return Number(response.count);
+  if (response?.["@odata.count"] !== void 0) return response["@odata.count"];
+  if (response?.["odata.count"] !== void 0) return parseInt(response["odata.count"], 10);
+  if (response?.__count !== void 0) return parseInt(response.__count, 10);
+  if (response?.d?.__count !== void 0) return parseInt(response.d.__count, 10);
+  return void 0;
+}
+function createEntityHandler(client, entityName) {
+  const basePath = entityName;
+  return {
+    // ==========================================================================
+    // READ Operations
+    // ==========================================================================
+    /**
+     * List entities with optional query options
+     */
+    async list(options) {
+      const response = await client.get(
+        basePath,
+        buildQuery(options),
+        extractRequestOptions(options)
+      );
+      return extractData(response);
+    },
+    /**
+     * List entities with count
+     */
+    async listWithCount(options) {
+      const queryOptions = { ...options, count: true };
+      const response = await client.get(
+        basePath,
+        buildQuery(queryOptions),
+        extractRequestOptions(options)
+      );
+      return {
+        value: extractData(response),
+        count: extractCount(response)
+      };
+    },
+    /**
+     * Get single entity by key
+     */
+    async get(id, options) {
+      const response = await client.get(
+        `${basePath}(${formatId(id)})`,
+        buildQuery(options),
+        extractRequestOptions(options)
+      );
+      return extractSingle(response);
+    },
+    /**
+     * Count matching entities
+     */
+    async count(options) {
+      const response = await client.get(
+        `${basePath}/$count`,
+        buildQuery(options),
+        extractRequestOptions(options)
+      );
+      return typeof response === "number" ? response : parseInt(String(response), 10);
+    },
+    // ==========================================================================
+    // CREATE Operations
+    // ==========================================================================
+    /**
+     * Create a new entity (POST)
+     */
+    async create(data, options) {
+      const response = await client.post(
+        basePath,
+        data,
+        extractRequestOptions(options)
+      );
+      return extractSingle(response);
+    },
+    /**
+     * Create with related entities (deep insert)
+     */
+    async createDeep(data, options) {
+      const response = await client.post(
+        basePath,
+        data,
+        extractRequestOptions(options)
+      );
+      return extractSingle(response);
+    },
+    // ==========================================================================
+    // UPDATE Operations
+    // ==========================================================================
+    /**
+     * Partial update (PATCH) - only updates specified fields
+     */
+    async update(id, data, options) {
+      const response = await client.patch(
+        `${basePath}(${formatId(id)})`,
+        data,
+        extractRequestOptions(options)
+      );
+      return extractSingle(response);
+    },
+    /**
+     * Full replacement (PUT) - replaces entire entity
+     */
+    async replace(id, data, options) {
+      const response = await client.put(
+        `${basePath}(${formatId(id)})`,
+        data,
+        extractRequestOptions(options)
+      );
+      return extractSingle(response);
+    },
+    /**
+     * Upsert - create or update based on key
+     * Uses PUT to create or replace
+     */
+    async upsert(data, options) {
+      const key = data.ID ?? data.id ?? data.Id;
+      if (!key) {
+        throw new Error("Upsert requires an ID field in the data");
+      }
+      return this.replace(key, data, options);
+    },
+    // ==========================================================================
+    // DELETE Operations
+    // ==========================================================================
+    /**
+     * Delete entity by key
+     */
+    async delete(id, options) {
+      await client.delete(
+        `${basePath}(${formatId(id)})`,
+        extractRequestOptions(options)
+      );
+    },
+    // ==========================================================================
+    // Navigation Properties
+    // ==========================================================================
+    /**
+     * Access navigation property (related entities)
+     */
+    nav(id, property) {
+      const navPath = `${basePath}(${formatId(id)})/${property}`;
+      return createEntityHandler(client, navPath);
+    },
+    // ==========================================================================
+    // OData Functions & Actions
+    // ==========================================================================
+    /**
+     * Call an OData function (GET operation)
+     * Unbound function on the entity set
+     */
+    async func(name, params) {
+      const paramStr = buildFunctionParams(params);
+      const path = paramStr ? `${basePath}/${name}(${paramStr})` : `${basePath}/${name}()`;
+      return client.get(path);
+    },
+    /**
+     * Call an OData action (POST operation)
+     * Unbound action on the entity set
+     */
+    async action(name, params) {
+      return client.post(`${basePath}/${name}`, params ?? {});
+    },
+    /**
+     * Call bound function on specific entity
+     */
+    async boundFunc(id, name, params) {
+      const paramStr = buildFunctionParams(params);
+      const path = paramStr ? `${basePath}(${formatId(id)})/${name}(${paramStr})` : `${basePath}(${formatId(id)})/${name}()`;
+      return client.get(path);
+    },
+    /**
+     * Call bound action on specific entity
+     */
+    async boundAction(id, name, params) {
+      return client.post(`${basePath}(${formatId(id)})/${name}`, params ?? {});
+    },
+    // ==========================================================================
+    // Pagination
+    // ==========================================================================
+    /**
+     * Paginate through all entities with automatic page handling
+     */
+    paginate(options) {
+      const pageSize = options?.pageSize ?? options?.top ?? 100;
+      const maxItems = options?.maxItems;
+      const queryOptions = { ...options, top: pageSize };
+      const self = this;
+      return {
+        [Symbol.asyncIterator]() {
+          let skip = 0;
+          let totalFetched = 0;
+          let done = false;
+          return {
+            async next() {
+              if (done) {
+                return { done: true, value: void 0 };
+              }
+              let pageTop = pageSize;
+              if (maxItems !== void 0) {
+                const remaining = maxItems - totalFetched;
+                if (remaining <= 0) {
+                  done = true;
+                  return { done: true, value: void 0 };
+                }
+                pageTop = Math.min(pageSize, remaining);
+              }
+              const response = await self.listWithCount({
+                ...queryOptions,
+                top: pageTop,
+                skip
+              });
+              const items = response.value;
+              totalFetched += items.length;
+              skip += items.length;
+              if (items.length < pageTop) {
+                done = true;
+              }
+              if (maxItems !== void 0 && totalFetched >= maxItems) {
+                done = true;
+              }
+              return {
+                done: false,
+                value: {
+                  value: items,
+                  count: response.count
+                }
+              };
+            }
+          };
+        }
+      };
+    },
+    /**
+     * Get all entities (automatically handles pagination)
+     */
+    async all(options) {
+      const result = [];
+      for await (const page of this.paginate(options)) {
+        result.push(...page.value);
+      }
+      return result;
+    }
+  };
+}
+
+// src/client.ts
+var S4KitBase = class {
+  httpClient;
+  constructor(config) {
+    this.httpClient = new HttpClient(config);
+  }
+  // ==========================================================================
+  // Interceptors
+  // ==========================================================================
+  /**
+   * Add a request interceptor
+   * @example
+   * ```ts
+   * client.onRequest((req) => {
+   *   console.log(`${req.method} ${req.url}`);
+   *   return req;
+   * });
+   * ```
+   */
+  onRequest(interceptor) {
+    this.httpClient.onRequest(interceptor);
+    return this;
+  }
+  /**
+   * Add a response interceptor
+   * @example
+   * ```ts
+   * client.onResponse((res) => {
+   *   console.log(`Response: ${res.status}`);
+   *   return res;
+   * });
+   * ```
+   */
+  onResponse(interceptor) {
+    this.httpClient.onResponse(interceptor);
+    return this;
+  }
+  /**
+   * Add an error interceptor
+   * @example
+   * ```ts
+   * client.onError((err) => {
+   *   console.error(`Error: ${err.message}`);
+   *   return err;
+   * });
+   * ```
+   */
+  onError(interceptor) {
+    this.httpClient.onError(interceptor);
+    return this;
+  }
+  // ==========================================================================
+  // Batch Operations
+  // ==========================================================================
+  /**
+   * 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);
+   *   }
+   * }
+   * ```
+   */
+  async batch(operations) {
+    return this.httpClient.batch(operations);
+  }
+  /**
+   * 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 },
+   *   ]
+   * });
+   * ```
+   */
+  async changeset(changeset) {
+    return this.httpClient.changeset(changeset);
+  }
+};
+var RESERVED_METHODS = /* @__PURE__ */ new Set([
+  "onRequest",
+  "onResponse",
+  "onError",
+  "batch",
+  "changeset",
+  "constructor",
+  "httpClient",
+  // Internal properties
+  "then",
+  "catch",
+  "finally"
+]);
+function S4Kit(config) {
+  const base = new S4KitBase(config);
+  return new Proxy(base, {
+    get(target, prop) {
+      if (typeof prop === "symbol") {
+        return target[prop];
+      }
+      if (RESERVED_METHODS.has(prop) || prop in target) {
+        const value = target[prop];
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      }
+      return createEntityHandler(target["httpClient"], prop);
+    }
+  });
+}
+S4Kit.prototype = S4KitBase.prototype;
+function createClient(config) {
+  return S4Kit(config);
+}
+export {
+  AuthenticationError,
+  AuthorizationError,
+  BatchError,
+  ConflictError,
+  FilterBuilder,
+  NetworkError,
+  NotFoundError,
+  QueryBuilder,
+  RateLimitError,
+  S4Kit,
+  S4KitError,
+  ServerError,
+  TimeoutError,
+  ValidationError,
+  buildFilter,
+  buildFunctionParams,
+  buildQuery,
+  createClient,
+  createFilter,
+  formatKey,
+  isRetryable,
+  isS4KitError,
+  parseHttpError,
+  parseODataError,
+  query
+};