hanzio 1.0.10 → 1.2.0

package/dist/src/api-wrapper/index.js

@@ -1,250 +1,1132 @@
-// src/api-wrapper/index.ts
+// src/api-wrapper/headers.ts
+var CANONICAL_HEADER_NAMES = {
+  "content-type": "Content-Type",
+  authorization: "Authorization",
+  accept: "Accept",
+  "user-agent": "User-Agent",
+  "x-request-id": "X-Request-Id",
+  "x-correlation-id": "X-Correlation-Id"
+};
+function normalizeHeaders(headers) {
+  const result = {};
+  const lowerToCanonical = new Map;
+  for (const [key, value] of Object.entries(headers)) {
+    const lower = key.toLowerCase();
+    const canonical = CANONICAL_HEADER_NAMES[lower] ?? key;
+    const existing = lowerToCanonical.get(lower);
+    if (existing && existing !== canonical)
+      delete result[existing];
+    lowerToCanonical.set(lower, canonical);
+    result[canonical] = value;
+  }
+  return result;
+}
+function getHeader(headers, name) {
+  const lower = name.toLowerCase();
+  const canonical = CANONICAL_HEADER_NAMES[lower];
+  if (canonical !== undefined) {
+    if (headers[canonical] !== undefined)
+      return headers[canonical];
+  }
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === lower)
+      return v;
+  }
+  return;
+}
+function hasJsonContentType(headers) {
+  const ct = getHeader(headers, "content-type") ?? "";
+  return ct.includes("application/json");
+}
+function buildFetchBody(body, headers, configError) {
+  if (body === undefined || body === null)
+    return;
+  if (body instanceof FormData || body instanceof Blob)
+    return body;
+  if (hasJsonContentType(headers))
+    return JSON.stringify(body);
+  if (typeof body === "object" && (Object.getPrototypeOf(body) === Object.prototype || Object.getPrototypeOf(body) === null) && configError) {
+    throw configError("Request body is a plain object but Content-Type is not application/json");
+  }
+  return body;
+}
+function getHeadersAsObject(headers) {
+  const result = {};
+  headers.forEach((value, key) => {
+    result[key] = value;
+  });
+  return result;
+}
+
+// src/api-wrapper/zod-issues.ts
 import { ZodError } from "zod";
+function formatZodIssues(error, rawData) {
+  return error.issues.map((issue) => {
+    const pathArray = [...issue.path];
+    const path = formatIssuePath(pathArray);
+    const value = getValueAtPath(rawData, pathArray);
+    const valuePreview = value === undefined ? undefined : previewValue(value);
+    const raw = issue;
+    const expected = typeof raw.expected === "string" ? raw.expected : undefined;
+    const received = typeof raw.received === "string" ? raw.received : value !== undefined ? typeofVerbose(value) : undefined;
+    const known = new Set([
+      "code",
+      "path",
+      "message",
+      "expected",
+      "received",
+      "fatal"
+    ]);
+    const extra = {};
+    for (const [k, v] of Object.entries(raw)) {
+      if (!known.has(k) && v !== undefined)
+        extra[k] = v;
+    }
+    return {
+      path,
+      pathArray,
+      code: issue.code,
+      message: issue.message,
+      expected,
+      received,
+      value,
+      valuePreview,
+      extra: Object.keys(extra).length > 0 ? extra : undefined
+    };
+  });
+}
+function renderIssueSummary(issues) {
+  if (issues.length === 0)
+    return "(no issues reported)";
+  return issues.map((issue, idx) => {
+    const parts = [];
+    parts.push(`  [${idx + 1}] ${issue.path}: ${issue.message}`);
+    if (issue.expected || issue.received) {
+      const exp = issue.expected ? `expected ${issue.expected}` : "";
+      const rec = issue.received ? `received ${issue.received}` : "";
+      parts.push(`      (${[exp, rec].filter(Boolean).join(", ")})`);
+    }
+    if (issue.valuePreview !== undefined) {
+      parts.push(`      value: ${issue.valuePreview}`);
+    }
+    if (issue.extra) {
+      for (const [k, v] of Object.entries(issue.extra)) {
+        parts.push(`      ${k}: ${previewValue(v, 120)}`);
+      }
+    }
+    return parts.join(`
+`);
+  }).join(`
+`);
+}
+function formatIssuePath(pathArray) {
+  if (pathArray.length === 0)
+    return "<root>";
+  let out = "";
+  for (const segment of pathArray) {
+    if (typeof segment === "number") {
+      out += `[${segment}]`;
+    } else if (/^[A-Za-z_$][\w$]*$/.test(segment)) {
+      out += out === "" ? segment : `.${segment}`;
+    } else {
+      out += `[${JSON.stringify(segment)}]`;
+    }
+  }
+  return out;
+}
+function getValueAtPath(data, pathArray) {
+  let current = data;
+  for (const segment of pathArray) {
+    if (current === null || current === undefined)
+      return;
+    if (typeof current !== "object")
+      return;
+    current = current[segment];
+  }
+  return current;
+}
+function typeofVerbose(value) {
+  if (value === null)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  return typeof value;
+}
+function previewValue(value, maxLen = 200) {
+  let str;
+  try {
+    if (value === undefined)
+      str = "undefined";
+    else if (typeof value === "string")
+      str = JSON.stringify(value);
+    else
+      str = JSON.stringify(value);
+  } catch {
+    str = String(value);
+  }
+  if (str === undefined)
+    str = String(value);
+  if (str.length > maxLen)
+    str = `${str.slice(0, maxLen)}…`;
+  return str;
+}
+function makeJsonParseZodError(error, text) {
+  const message = error instanceof Error ? `Response body was not valid JSON: ${error.message}` : "Response body was not valid JSON";
+  const preview = text.length > 200 ? `${text.slice(0, 200)}…` : text;
+  return new ZodError([
+    {
+      code: "custom",
+      path: [],
+      message: `${message} (body preview: ${JSON.stringify(preview)})`,
+      input: text
+    }
+  ]);
+}
+function tryParseJson(body) {
+  if (!body)
+    return;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return;
+  }
+}
 
-class ResponseValidationError extends Error {
+// src/api-wrapper/errors.ts
+var MAX_BODY_PREVIEW = 500;
+
+class ApiError extends Error {
+  context;
+  cause;
+  constructor(message, context, options) {
+    super(message);
+    this.name = "ApiError";
+    this.context = context;
+    this.cause = options?.cause;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      context: this.context
+    };
+  }
+}
+
+class HttpResponseError extends ApiError {
+  status;
+  body;
+  bodyJson;
+  responseHeaders;
+  requestId;
+  constructor(status, body, responseHeaders, context) {
+    const preview = body.length > MAX_BODY_PREVIEW ? `${body.slice(0, MAX_BODY_PREVIEW)}…` : body;
+    super(`HTTP ${status} ${context.method} ${context.url} - ${preview}`, context);
+    this.name = "HttpResponseError";
+    this.status = status;
+    this.body = body;
+    this.responseHeaders = responseHeaders;
+    this.requestId = getHeader(responseHeaders, "x-request-id") ?? getHeader(responseHeaders, "x-correlation-id");
+    this.bodyJson = tryParseJson(body);
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      status: this.status,
+      body: this.body,
+      bodyJson: this.bodyJson,
+      requestId: this.requestId,
+      responseHeaders: this.responseHeaders
+    };
+  }
+}
+
+class ResponseValidationError extends ApiError {
   zodError;
   rawResponse;
+  issues;
   validationIssues;
-  constructor(zodError, rawResponse) {
-    const issues = zodError.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
-    super(`Response validation failed: ${issues}`);
+  constructor(zodError, rawResponse, context) {
+    const issues = formatZodIssues(zodError, rawResponse);
+    const summary = renderIssueSummary(issues);
+    super(`Response validation failed (${context.method} ${context.url}):
+${summary}`, context, { cause: zodError });
     this.name = "ResponseValidationError";
     this.zodError = zodError;
     this.rawResponse = rawResponse;
-    this.validationIssues = issues;
+    this.issues = issues;
+    this.validationIssues = issues.map((i) => `${i.path}: ${i.message}`).join("; ");
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      issues: this.issues,
+      validationIssues: this.validationIssues,
+      rawResponsePreview: previewValue(this.rawResponse, 1000)
+    };
   }
 }
 
-class HttpResponseError extends Error {
-  status;
-  body;
-  constructor(status, body) {
-    super(`HTTP error: ${status} - ${body}`);
-    this.name = "HttpResponseError";
-    this.status = status;
-    this.body = body;
+class RequestValidationError extends ApiError {
+  zodError;
+  target;
+  rawInput;
+  issues;
+  validationIssues;
+  constructor(zodError, target, rawInput, context) {
+    const issues = formatZodIssues(zodError, rawInput);
+    const summary = renderIssueSummary(issues);
+    super(`Request ${target} validation failed (${context.method} ${context.url}):
+${summary}`, context, { cause: zodError });
+    this.name = "RequestValidationError";
+    this.zodError = zodError;
+    this.target = target;
+    this.rawInput = rawInput;
+    this.issues = issues;
+    this.validationIssues = issues.map((i) => `${i.path}: ${i.message}`).join("; ");
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      target: this.target,
+      issues: this.issues,
+      validationIssues: this.validationIssues
+    };
   }
 }
-function createApiClient(apiConfig) {
-  const request = async (endpointKey, input = {}) => {
-    const endpoint = apiConfig.endpoints[endpointKey];
-    if (!endpoint) {
-      throw new Error(`Unknown API endpoint: ${String(endpointKey)}`);
+
+class RequestTimeoutError extends ApiError {
+  timeoutMs;
+  constructor(timeoutMs, context) {
+    super(`Request timed out after ${timeoutMs}ms: ${context.method} ${context.url}`, context);
+    this.name = "RequestTimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+class NetworkError extends ApiError {
+  constructor(message, context, cause) {
+    super(message, context, { cause });
+    this.name = "NetworkError";
+  }
+}
+
+class RequestAbortedError extends ApiError {
+  constructor(context, cause) {
+    super(`Request aborted: ${context.method} ${context.url}`, context, {
+      cause
+    });
+    this.name = "RequestAbortedError";
+  }
+}
+
+class ConfigError extends ApiError {
+  constructor(message, context) {
+    super(message, context);
+    this.name = "ConfigError";
+  }
+}
+
+class ActionError extends ApiError {
+  constructor(message, context, cause) {
+    super(message, context, { cause });
+    this.name = "ActionError";
+  }
+}
+var isApiError = (e) => e instanceof ApiError;
+var isHttpResponseError = (e) => e instanceof HttpResponseError;
+var isResponseValidationError = (e) => e instanceof ResponseValidationError;
+var isRequestValidationError = (e) => e instanceof RequestValidationError;
+var isRequestTimeoutError = (e) => e instanceof RequestTimeoutError;
+var isNetworkError = (e) => e instanceof NetworkError;
+var isRequestAbortedError = (e) => e instanceof RequestAbortedError;
+var isConfigError = (e) => e instanceof ConfigError;
+var isActionError = (e) => e instanceof ActionError;
+function isNonRetryableApiError(error) {
+  return error instanceof HttpResponseError || error instanceof ResponseValidationError || error instanceof RequestValidationError || error instanceof ConfigError || error instanceof RequestAbortedError;
+}
+// src/api-wrapper/builders.ts
+import { ZodError as ZodError2 } from "zod";
+function formatQueryString(queryParams, doNotEncode) {
+  if (Object.keys(queryParams).length === 0)
+    return "";
+  return doNotEncode ? Object.entries(queryParams).map(([key, value]) => `${key}=${value}`).join("&") : new URLSearchParams(queryParams).toString();
+}
+function buildUrl(options) {
+  const {
+    endpoint,
+    params,
+    queryParams,
+    baseApiUrls,
+    defaultBaseApiUrl,
+    url,
+    doNotEncodeQueryParams,
+    configError
+  } = options;
+  let finalUrl;
+  if (url) {
+    finalUrl = replacePathParams(url, params, configError);
+  } else {
+    const defaultBaseUrl = defaultBaseApiUrl ?? Object.keys(baseApiUrls)[0];
+    if (!defaultBaseUrl) {
+      throw configError("At least one base API URL is required");
     }
-    const { finalUrl, fullUrl } = buildUrl(endpoint, input.reqParams, input.reqQuery, apiConfig.baseApiUrls, apiConfig.defaultBaseApiUrl, input.url);
-    const endpointName = apiConfig.name ? `${apiConfig.name}.${String(endpointKey)}` : String(endpointKey);
-    const startedAt = Date.now();
-    let retryCount = 0;
-    let httpStatus = 0;
-    apiConfig.onRequestStart?.({ endpoint: endpointName, url: fullUrl });
+    const baseUrlKey = endpoint.baseApiUrl ?? defaultBaseUrl;
+    const configBaseUrl = baseApiUrls[baseUrlKey];
+    if (!configBaseUrl) {
+      throw configError(`Unknown base API URL: ${baseUrlKey}`);
+    }
+    const baseUrl = typeof configBaseUrl === "function" ? configBaseUrl() : configBaseUrl;
+    const path = typeof endpoint.path === "function" ? endpoint.path(baseUrl) : endpoint.path;
+    finalUrl = `${baseUrl}${replacePathParams(path, params, configError)}`;
+  }
+  const queryString = formatQueryString(queryParams, doNotEncodeQueryParams);
+  return {
+    finalUrl,
+    fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
+  };
+}
+function buildPathParams(endpoint, params, ctx) {
+  if (!endpoint.reqParamsSchema)
+    return params;
+  try {
+    return endpoint.reqParamsSchema.parse(params);
+  } catch (error) {
+    if (error instanceof ZodError2) {
+      throw new RequestValidationError(error, "params", params, ctx());
+    }
+    throw error;
+  }
+}
+function buildQueryParams(endpoint, query, ctx) {
+  const defaultParams = endpoint.reqDefaultQueryParams ?? {};
+  let parsedQuery;
+  if (endpoint.reqQuerySchema) {
     try {
-      const config = {
-        method: endpoint.method,
-        url: finalUrl,
-        queryParams: buildQueryParams(endpoint, input.reqQuery),
-        body: buildRequestBody(endpoint, input.reqBody),
-        headers: buildHeaders(endpoint, input.reqHeaders, apiConfig.defaultHeaders ?? {}),
-        doNotEncodeQueryParams: endpoint.doNotEncodeQueryParams,
-        timeoutMs: apiConfig.timeoutMs,
-        fetchFn: apiConfig.fetch ?? fetch
-      };
-      const result = await makeRequestWithRetry(config, apiConfig.retries ?? 3, apiConfig.retryDelayMs ?? 300, (response) => validateAndTransformResponse(endpoint, response), apiConfig.shouldRetry ?? defaultShouldRetry, apiConfig.logger);
-      retryCount = result.retryCount;
-      httpStatus = result.httpStatus;
-      const responseTimeMs = Date.now() - startedAt;
-      const responseSizeMb = calculateSizeInMb(result.validatedData);
-      const requestSizeMb = calculateSizeInMb({
-        method: config.method,
-        url: fullUrl,
-        body: config.body,
-        headers: config.headers
-      });
-      apiConfig.onRequestEnd?.({
-        endpoint: endpointName,
-        url: fullUrl,
-        status: httpStatus,
-        retryCount,
-        responseTimeMs
-      });
-      return {
-        data: result.validatedData,
-        requestSizeMb,
-        responseSizeMb,
-        requestSizeTotalMb: requestSizeMb + responseSizeMb,
-        responseTimeMs,
-        httpStatus,
-        retryCount
-      };
+      parsedQuery = endpoint.reqQuerySchema.parse(query);
+    } catch (error) {
+      if (error instanceof ZodError2) {
+        throw new RequestValidationError(error, "query", query, ctx());
+      }
+      throw error;
+    }
+  } else {
+    parsedQuery = query ?? {};
+  }
+  const merged = { ...defaultParams, ...parsedQuery };
+  return Object.fromEntries(Object.entries(merged).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+}
+function buildRequestBody(endpoint, body, ctx) {
+  if (!endpoint.reqBodySchema)
+    return body;
+  let parsedBody;
+  try {
+    parsedBody = endpoint.reqBodySchema.parse(body);
+  } catch (error) {
+    if (error instanceof ZodError2) {
+      throw new RequestValidationError(error, "body", body, ctx());
+    }
+    throw error;
+  }
+  if (endpoint.reqBodyFormat !== "form-data") {
+    return parsedBody;
+  }
+  const formData = new FormData;
+  for (const [key, value] of Object.entries(parsedBody)) {
+    if (value == null)
+      continue;
+    formData.set(key, value instanceof Blob ? value : String(value));
+  }
+  return formData;
+}
+function buildHeaders(endpoint, headers, defaultHeaders, ctx) {
+  const contentType = endpoint.reqBodyFormat === "json" ? "application/json" : undefined;
+  let parsedHeaders;
+  if (endpoint.reqHeadersSchema) {
+    try {
+      parsedHeaders = endpoint.reqHeadersSchema.parse(headers);
+    } catch (error) {
+      if (error instanceof ZodError2) {
+        throw new RequestValidationError(error, "headers", headers, ctx());
+      }
+      throw error;
+    }
+  } else {
+    parsedHeaders = headers ?? {};
+  }
+  return normalizeHeaders({
+    ...defaultHeaders,
+    ...contentType && { "Content-Type": contentType },
+    ...endpoint.defaultHeaders,
+    ...parsedHeaders
+  });
+}
+function replacePathParams(path, params, configError) {
+  return path.replace(/:(\w+)/g, (_, key) => {
+    const value = params?.[key];
+    if (value === undefined) {
+      throw configError(`Missing required path parameter: ${key}`);
+    }
+    return encodeURIComponent(String(value));
+  });
+}
+
+// src/api-wrapper/actions-impl.ts
+function createActionCache() {
+  const store = new Map;
+  const isExpired = (entry) => entry.expiresAt !== undefined && entry.expiresAt <= Date.now();
+  const cache = async (key, fn, options) => {
+    const existing = store.get(key);
+    if (existing && !isExpired(existing)) {
+      if (existing.inflight)
+        return existing.inflight;
+      if (existing.hasValue)
+        return existing.value;
+    }
+    const promise = (async () => fn())();
+    const entry = {
+      hasValue: false,
+      inflight: promise,
+      expiresAt: options?.ttlMs !== undefined ? Date.now() + options.ttlMs : undefined
+    };
+    store.set(key, entry);
+    try {
+      const value = await promise;
+      entry.value = value;
+      entry.hasValue = true;
+      entry.inflight = undefined;
+      return value;
     } catch (error) {
-      apiConfig.logger?.error?.(error);
+      store.delete(key);
       throw error;
     }
   };
-  return { request };
+  cache.get = (key) => {
+    const entry = store.get(key);
+    if (!entry || !entry.hasValue)
+      return;
+    if (isExpired(entry)) {
+      store.delete(key);
+      return;
+    }
+    return entry.value;
+  };
+  cache.set = (key, value, options) => {
+    store.set(key, {
+      value,
+      hasValue: true,
+      expiresAt: options?.ttlMs !== undefined ? Date.now() + options.ttlMs : undefined
+    });
+  };
+  cache.invalidate = (key) => {
+    store.delete(key);
+  };
+  cache.clear = () => {
+    store.clear();
+  };
+  return cache;
 }
-var createApiWrapper = createApiClient;
-async function validateResponse(schema, data) {
+function makeDefineAction() {
+  function defineAction(...args) {
+    if (args.length === 0) {
+      return (def) => ({
+        ...def,
+        noRuntimeInput: false
+      });
+    }
+    const def = args[0];
+    return {
+      ...def,
+      noRuntimeInput: true
+    };
+  }
+  return defineAction;
+}
+var defineAction = makeDefineAction();
+
+// src/api-wrapper/redaction.ts
+var SENSITIVE_HEADER_KEYS = new Set([
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "x-auth-token"
+]);
+var SENSITIVE_BODY_KEYS = new Set([
+  "password",
+  "token",
+  "accesstoken",
+  "access_token",
+  "refreshtoken",
+  "refresh_token",
+  "secret",
+  "client_secret",
+  "clientsecret",
+  "apikey",
+  "api_key"
+]);
+function redactHeaders(headers) {
+  if (!headers)
+    return;
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (SENSITIVE_HEADER_KEYS.has(k.toLowerCase())) {
+      out[k] = "[REDACTED]";
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+function redactBody(body) {
+  if (body === null || body === undefined)
+    return body;
+  if (typeof body !== "object" || Array.isArray(body)) {
+    return body;
+  }
+  const rec = body;
+  const out = { ...rec };
+  for (const key of Object.keys(out)) {
+    if (SENSITIVE_BODY_KEYS.has(key.toLowerCase())) {
+      out[key] = "[REDACTED]";
+    }
+  }
+  return out;
+}
+function defaultRedactContext(ctx) {
+  return {
+    ...ctx,
+    requestHeaders: redactHeaders(ctx.requestHeaders),
+    requestBody: redactBody(ctx.requestBody),
+    meta: ctx.meta
+  };
+}
+
+// src/api-wrapper/error-reporting.ts
+function applyErrorContextRedaction(ctx, config) {
+  const base = defaultRedactContext(ctx);
+  return config.redact ? config.redact(base) : base;
+}
+async function reportApiError(err, config) {
+  err.context = applyErrorContextRedaction(err.context, config);
+  try {
+    await config.onError?.(err);
+  } catch {}
+  config.logger?.error?.(err);
+  return err;
+}
+
+// src/api-wrapper/size.ts
+function calculateSizeInMb(data) {
+  let bytes;
+  if (data === undefined || data === null) {
+    bytes = 0;
+  } else if (data instanceof Blob) {
+    bytes = data.size;
+  } else if (typeof FormData !== "undefined" && data instanceof FormData) {
+    bytes = 0;
+    data.forEach((value) => {
+      if (value instanceof Blob)
+        bytes += value.size;
+      else
+        bytes += new TextEncoder().encode(String(value)).length;
+    });
+  } else if (typeof data === "string") {
+    bytes = new TextEncoder().encode(data).length;
+  } else {
+    bytes = new TextEncoder().encode(JSON.stringify(data) ?? "").length;
+  }
+  return bytes / (1024 * 1024);
+}
+
+// src/api-wrapper/transport.ts
+import { ZodError as ZodError3 } from "zod";
+async function validateResponse(schema, data, ctx) {
   try {
     return await schema.parseAsync(data);
   } catch (error) {
-    if (error instanceof ZodError) {
-      throw new ResponseValidationError(error, data);
+    if (error instanceof ZodError3) {
+      throw new ResponseValidationError(error, data, ctx());
     }
     throw error;
   }
 }
-async function httpRequest(config) {
-  const queryString = config.doNotEncodeQueryParams ? Object.entries(config.queryParams).map(([key, value]) => `${key}=${value}`).join("&") : new URLSearchParams(config.queryParams).toString();
-  const fullUrl = queryString ? `${config.url}?${queryString}` : config.url;
-  const abortController = new AbortController;
-  const timeout = config.timeoutMs === undefined ? undefined : setTimeout(() => abortController.abort(), config.timeoutMs);
+async function httpRequest(config, ctx) {
+  const timeoutController = new AbortController;
+  const timeout = config.timeoutMs === undefined ? undefined : setTimeout(() => timeoutController.abort(), config.timeoutMs);
+  const signal = mergeSignals(timeoutController.signal, config.userSignal);
   try {
-    return await config.fetchFn(fullUrl, {
+    return await config.fetchFn(config.fullUrl, {
       method: config.method,
       headers: config.headers,
-      body: buildFetchBody(config.body, config.headers),
-      signal: abortController.signal
+      body: buildFetchBody(config.body, config.headers, (msg) => new ConfigError(msg, ctx())),
+      signal
     });
+  } catch (error) {
+    if (isDomAbortError(error)) {
+      if (config.userSignal?.aborted) {
+        throw new RequestAbortedError(ctx(), error);
+      }
+      if (timeoutController.signal.aborted && config.timeoutMs !== undefined) {
+        throw new RequestTimeoutError(config.timeoutMs, ctx());
+      }
+      throw new RequestAbortedError(ctx(), error);
+    }
+    if (error instanceof ConfigError)
+      throw error;
+    throw new NetworkError(error instanceof Error ? error.message : String(error), ctx(), error);
   } finally {
     if (timeout)
       clearTimeout(timeout);
   }
 }
-async function makeRequestWithRetry(config, maxRetries, retryDelayMs, validateFn, shouldRetry, logger) {
+function isDomAbortError(error) {
+  return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
+}
+function mergeSignals(a, b) {
+  if (!b)
+    return a;
+  const anyFn = AbortSignal.any;
+  if (typeof anyFn === "function")
+    return anyFn([a, b]);
+  const controller = new AbortController;
+  const onAbort = () => controller.abort();
+  if (a.aborted)
+    controller.abort();
+  else
+    a.addEventListener("abort", onAbort, { once: true });
+  if (b.aborted)
+    controller.abort();
+  else
+    b.addEventListener("abort", onAbort, { once: true });
+  return controller.signal;
+}
+async function readErrorResponse(response) {
+  const body = await response.text();
+  return {
+    body,
+    headers: getHeadersAsObject(response.headers),
+    status: response.status
+  };
+}
+function getRetryDelay(params) {
+  const maxDelay = params.maxRetryDelayMs ?? 30000;
+  const { retryDelay, attempt, response } = params;
+  if (response && (response.status === 429 || response.status === 503)) {
+    const retryAfter = response.headers.get("retry-after");
+    if (retryAfter) {
+      const seconds = Number(retryAfter);
+      if (Number.isFinite(seconds)) {
+        return Math.min(Math.max(0, seconds * 1000), maxDelay);
+      }
+      const dateMs = Date.parse(retryAfter);
+      if (!Number.isNaN(dateMs)) {
+        return Math.min(Math.max(0, dateMs - Date.now()), maxDelay);
+      }
+    }
+  }
+  const delayMs = typeof retryDelay === "function" ? retryDelay(attempt) : retryDelay;
+  return Math.min(delayMs, maxDelay);
+}
+function shouldAttemptRetryOnError(error) {
+  return !isNonRetryableApiError(error);
+}
+function shouldAttemptRetryOnHttp(retryCtx) {
+  const { error, response } = retryCtx;
+  if (error)
+    return shouldAttemptRetryOnError(error);
+  return response ? response.status >= 500 || response.status === 429 : false;
+}
+async function makeRequestWithRetry(args) {
+  const {
+    config,
+    maxRetries,
+    retryDelay,
+    maxRetryDelayMs,
+    validateFn,
+    shouldRetry,
+    logger,
+    ctx,
+    endpointName,
+    method,
+    fullUrl,
+    meta,
+    onResponse,
+    onRetry
+  } = args;
   let retryCount = 0;
   while (true) {
+    let response;
     try {
       logger?.debug?.("API request", config);
-      const response = await httpRequest(config);
+      response = await httpRequest(config, (over) => ctx({ attempt: retryCount, ...over }));
+      await onResponse?.({
+        endpoint: endpointName,
+        method,
+        url: fullUrl,
+        response: response.clone(),
+        attempt: retryCount,
+        meta
+      });
       if (response.status >= 400) {
-        if (retryCount < maxRetries && shouldRetry({ response, retryCount, maxRetries })) {
+        const retryCtx = {
+          response,
+          retryCount,
+          maxRetries,
+          endpoint: endpointName,
+          method,
+          url: fullUrl
+        };
+        if (retryCount < maxRetries && shouldRetry(retryCtx)) {
+          const delayMs = getRetryDelay({
+            retryDelay,
+            attempt: retryCount,
+            response,
+            maxRetryDelayMs
+          });
+          await onRetry?.({
+            ...retryCtx,
+            delayMs,
+            nextAttempt: retryCount + 1
+          });
           retryCount++;
-          await delay(retryDelayMs);
+          await delay(delayMs);
           continue;
         }
-        throw new HttpResponseError(response.status, await response.text());
+        const { body, headers: responseHeaders } = await readErrorResponse(response);
+        throw new HttpResponseError(response.status, body, responseHeaders, ctx({ attempt: retryCount }));
       }
       return {
-        validatedData: await validateFn(response),
+        validatedData: await validateFn(response, retryCount),
         retryCount,
         httpStatus: response.status
       };
     } catch (error) {
-      if (error instanceof HttpResponseError)
+      if (isNonRetryableApiError(error)) {
         throw error;
-      if (retryCount >= maxRetries || !shouldRetry({ error, retryCount, maxRetries })) {
+      }
+      const retryCtx = {
+        error,
+        retryCount,
+        maxRetries,
+        endpoint: endpointName,
+        method,
+        url: fullUrl
+      };
+      if (retryCount >= maxRetries || !shouldRetry(retryCtx)) {
         throw error;
       }
+      const delayMs = getRetryDelay({
+        retryDelay,
+        attempt: retryCount,
+        response: undefined,
+        maxRetryDelayMs
+      });
+      await onRetry?.({
+        ...retryCtx,
+        delayMs,
+        nextAttempt: retryCount + 1
+      });
       retryCount++;
-      await delay(retryDelayMs);
+      await delay(delayMs);
     }
   }
 }
-async function validateAndTransformResponse(endpoint, response) {
+async function validateAndTransformResponse(endpoint, response, ctx) {
   const responseHeaders = getHeadersAsObject(response.headers);
-  const contentType = responseHeaders["content-type"] ?? "";
-  const responseData = contentType.includes("application/json") ? await response.json() : await response.text();
+  const text = await response.text();
+  const responseSizeBytes = new TextEncoder().encode(text).length;
+  let responseData;
+  if (hasJsonContentType(responseHeaders)) {
+    try {
+      responseData = text === "" ? undefined : JSON.parse(text);
+    } catch (error) {
+      throw new ResponseValidationError(makeJsonParseZodError(error, text), text, ctx());
+    }
+  } else {
+    responseData = text;
+  }
   const transformedData = endpoint.resFormatter ? endpoint.resFormatter(responseData, responseHeaders) : responseData;
-  return validateResponse(endpoint.resSchema, transformedData);
+  const data = await validateResponse(endpoint.resSchema, transformedData, ctx);
+  return { data, responseSizeBytes };
 }
-function buildUrl(endpoint, params, reqQuery, baseApiUrls, defaultBaseApiUrl, url) {
-  if (url) {
-    const finalUrl2 = replacePathParams(url, params);
-    const queryString2 = new URLSearchParams(buildQueryParams(endpoint, reqQuery)).toString();
-    return {
-      finalUrl: finalUrl2,
-      fullUrl: queryString2 ? `${finalUrl2}?${queryString2}` : finalUrl2
-    };
+function defaultShouldRetry(ctx) {
+  if (ctx.error)
+    return shouldAttemptRetryOnError(ctx.error);
+  return shouldAttemptRetryOnHttp(ctx);
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/api-wrapper/create-client.ts
+function isActionInvokeOptionsOnly(value) {
+  if (value === null || value === undefined)
+    return false;
+  if (typeof value !== "object" || Array.isArray(value))
+    return false;
+  return Object.keys(value).every((k) => k === "signal" || k === "meta");
+}
+function resolveActionInvocation(action, actionName, first, second) {
+  if (!action.noRuntimeInput) {
+    return { input: first, options: second ?? {} };
   }
-  const defaultBaseUrl = defaultBaseApiUrl ?? Object.keys(baseApiUrls)[0];
-  if (!defaultBaseUrl) {
-    throw new Error("At least one base API URL is required");
+  if (first === undefined || first === null) {
+    return { input: undefined, options: second ?? {} };
   }
-  const baseUrlKey = endpoint.baseApiUrl ?? defaultBaseUrl;
-  const configBaseUrl = baseApiUrls[baseUrlKey];
-  if (!configBaseUrl) {
-    throw new Error(`Unknown base API URL: ${baseUrlKey}`);
+  if (second !== undefined) {
+    return { input: undefined, options: second };
   }
-  const baseUrl = typeof configBaseUrl === "function" ? configBaseUrl() : configBaseUrl;
-  const path = typeof endpoint.path === "function" ? endpoint.path(baseUrl) : endpoint.path;
-  const finalUrl = replacePathParams(`${baseUrl}${path}`, params);
-  const queryString = new URLSearchParams(buildQueryParams(endpoint, reqQuery)).toString();
-  return {
-    finalUrl,
-    fullUrl: queryString ? `${finalUrl}?${queryString}` : finalUrl
-  };
-}
-function buildQueryParams(endpoint, query) {
-  const defaultParams = endpoint.reqDefaultQueryParams ?? {};
-  const parsedQuery = endpoint.reqQuerySchema ? endpoint.reqQuerySchema.parse(query) : query ?? {};
-  const merged = { ...defaultParams, ...parsedQuery };
-  return Object.fromEntries(Object.entries(merged).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+  if (isActionInvokeOptionsOnly(first)) {
+    return { input: undefined, options: first };
+  }
+  throw new ConfigError(`Action "${actionName}" does not accept input; pass only optional { signal, meta }`, {
+    endpoint: actionName,
+    method: "GET",
+    url: "",
+    attempt: 0,
+    maxRetries: 0,
+    elapsedMs: 0
+  });
 }
-function buildRequestBody(endpoint, body) {
-  if (!endpoint.reqBodySchema)
-    return body;
-  const parsedBody = endpoint.reqBodySchema.parse(body);
-  if (endpoint.reqBodyFormat !== "form-data") {
-    return parsedBody;
+function createApiClientImpl(apiConfig) {
+  let actions = {};
+  const cache = createActionCache();
+  const invokeEndpoint = async (endpointKey, input = {}) => {
+    const endpoint = apiConfig.endpoints[endpointKey];
+    const rawInput = input;
+    const endpointName = apiConfig.name ? `${apiConfig.name}.${String(endpointKey)}` : String(endpointKey);
+    const startedAt = Date.now();
+    const maxRetries = input.retries ?? apiConfig.retries ?? 3;
+    const baseContext = {
+      endpoint: endpointName,
+      method: endpoint?.method ?? "GET",
+      url: "",
+      attempt: 0,
+      maxRetries,
+      elapsedMs: 0,
+      meta: input.meta
+    };
+    const elapsed = () => Date.now() - startedAt;
+    const ctx = (over = {}) => ({
+      ...baseContext,
+      elapsedMs: elapsed(),
+      ...over
+    });
+    if (!endpoint) {
+      throw await reportApiError(new ConfigError(`Unknown API endpoint: ${String(endpointKey)}`, ctx()), apiConfig);
+    }
+    baseContext.method = endpoint.method;
+    let pathParams;
+    let queryParams;
+    let body;
+    let headers;
+    try {
+      pathParams = buildPathParams(endpoint, rawInput.reqParams, ctx);
+      queryParams = buildQueryParams(endpoint, rawInput.reqQuery, ctx);
+      body = buildRequestBody(endpoint, rawInput.reqBody, ctx);
+      headers = buildHeaders(endpoint, rawInput.reqHeaders, apiConfig.defaultHeaders ?? {}, ctx);
+    } catch (e) {
+      if (e instanceof ApiError)
+        throw await reportApiError(e, apiConfig);
+      throw e;
+    }
+    let fullUrl;
+    try {
+      const built = buildUrl({
+        endpoint,
+        params: pathParams,
+        queryParams,
+        baseApiUrls: apiConfig.baseApiUrls,
+        defaultBaseApiUrl: apiConfig.defaultBaseApiUrl,
+        url: input.url,
+        doNotEncodeQueryParams: endpoint.doNotEncodeQueryParams,
+        configError: (msg) => new ConfigError(msg, ctx())
+      });
+      fullUrl = built.fullUrl;
+    } catch (e) {
+      if (e instanceof ApiError)
+        throw await reportApiError(e, apiConfig);
+      throw e;
+    }
+    baseContext.url = fullUrl;
+    baseContext.requestHeaders = headers;
+    baseContext.requestBody = body;
+    if (apiConfig.onRequest) {
+      try {
+        const result = await apiConfig.onRequest({
+          endpoint: endpointName,
+          method: endpoint.method,
+          url: fullUrl,
+          headers,
+          body,
+          meta: input.meta
+        });
+        if (result?.headers)
+          headers = result.headers;
+        if (result && "body" in result)
+          body = result.body;
+      } catch (e) {
+        if (e instanceof ApiError)
+          throw await reportApiError(e, apiConfig);
+        throw e;
+      }
+    }
+    const config = {
+      method: endpoint.method,
+      fullUrl,
+      body,
+      headers,
+      timeoutMs: input.timeoutMs ?? apiConfig.timeoutMs,
+      fetchFn: input.fetch ?? apiConfig.fetch ?? fetch,
+      userSignal: input.signal
+    };
+    try {
+      const result = await makeRequestWithRetry({
+        config,
+        maxRetries,
+        retryDelay: apiConfig.retryDelayMs ?? 300,
+        maxRetryDelayMs: apiConfig.maxRetryDelayMs,
+        validateFn: (response, attempt) => validateAndTransformResponse(endpoint, response, (over) => ctx({ attempt, ...over })),
+        shouldRetry: apiConfig.shouldRetry ?? defaultShouldRetry,
+        logger: apiConfig.logger,
+        ctx,
+        endpointName,
+        method: endpoint.method,
+        fullUrl,
+        meta: input.meta,
+        onResponse: apiConfig.onResponse,
+        onRetry: apiConfig.onRetry
+      });
+      const responseTimeMs = elapsed();
+      const responseSizeMb = result.validatedData.responseSizeBytes / (1024 * 1024);
+      const requestBodySizeMb = calculateSizeInMb(config.body);
+      return {
+        data: result.validatedData.data,
+        requestBodySizeMb,
+        responseSizeMb,
+        responseTimeMs,
+        httpStatus: result.httpStatus,
+        retryCount: result.retryCount
+      };
+    } catch (error) {
+      if (error instanceof ApiError)
+        throw await reportApiError(error, apiConfig);
+      throw error;
+    }
+  };
+  async function invokeAction(name, rawInput, options = {}) {
+    const action = actions[name];
+    const inputForHandler = action.noRuntimeInput ? undefined : rawInput;
+    const actionName = apiConfig.name ? `${apiConfig.name}.${name}` : name;
+    const startedAt = Date.now();
+    const baseContext = {
+      endpoint: actionName,
+      method: "GET",
+      url: "",
+      attempt: 0,
+      maxRetries: 0,
+      elapsedMs: 0,
+      meta: options.meta,
+      requestBody: action.noRuntimeInput ? undefined : rawInput
+    };
+    const ctx = (over = {}) => ({
+      ...baseContext,
+      elapsedMs: Date.now() - startedAt,
+      ...over
+    });
+    apiConfig.logger?.debug?.("Action start", { action: actionName });
+    try {
+      const result = await action.handler({
+        input: inputForHandler,
+        api: proxy,
+        signal: options.signal,
+        meta: options.meta,
+        logger: apiConfig.logger,
+        cache
+      });
+      apiConfig.logger?.debug?.("Action end", {
+        action: actionName,
+        elapsedMs: Date.now() - startedAt
+      });
+      return result;
+    } catch (error) {
+      if (error instanceof ApiError) {
+        throw await reportApiError(error, apiConfig);
+      }
+      const wrapped = new ActionError(`Action ${actionName} failed: ${error instanceof Error ? error.message : String(error)}`, ctx(), error);
+      throw await reportApiError(wrapped, apiConfig);
+    }
   }
-  const formData = new FormData;
-  for (const [key, value] of Object.entries(parsedBody)) {
-    if (value == null)
-      continue;
-    formData.set(key, value instanceof Blob ? value : String(value));
+  async function dispatchAction(name, first, second) {
+    const action = actions[name];
+    const { input, options } = resolveActionInvocation(action, name, first, second);
+    return invokeAction(name, input, options);
   }
-  return formData;
-}
-function buildHeaders(endpoint, headers, defaultHeaders) {
-  const contentType = endpoint.reqBodyFormat === "json" ? "application/json" : undefined;
-  const parsedHeaders = endpoint.reqHeadersSchema ? endpoint.reqHeadersSchema.parse(headers) : headers ?? {};
-  return {
-    ...defaultHeaders,
-    ...contentType && { "Content-Type": contentType },
-    ...endpoint.defaultHeaders,
-    ...parsedHeaders
+  const request = async (key, input, options) => {
+    if (key in actions) {
+      return dispatchAction(key, input, options);
+    }
+    return invokeEndpoint(key, input ?? {});
   };
-}
-function buildFetchBody(body, headers) {
-  if (body === undefined || body === null)
-    return;
-  if (body instanceof FormData || body instanceof Blob)
-    return body;
-  if (headers["Content-Type"] === "application/json")
-    return JSON.stringify(body);
-  return body;
-}
-function replacePathParams(path, params) {
-  return path.replace(/:(\w+)/g, (_, key) => {
-    const value = params?.[key];
-    if (value === undefined) {
-      throw new Error(`Missing required path parameter: ${key}`);
+  const client = { request, cache };
+  const proxy = new Proxy(client, {
+    get(target, prop, receiver) {
+      if (prop in target || typeof prop !== "string") {
+        return Reflect.get(target, prop, receiver);
+      }
+      if (prop in apiConfig.endpoints) {
+        return (input) => invokeEndpoint(prop, input ?? {});
+      }
+      if (prop in actions) {
+        return (first, second) => dispatchAction(prop, first, second);
+      }
+      return;
     }
-    return encodeURIComponent(String(value));
   });
+  const rawActions = apiConfig.actions;
+  if (typeof rawActions === "function") {
+    actions = rawActions({
+      api: proxy,
+      defineAction: makeDefineAction()
+    });
+  } else if (rawActions) {
+    actions = rawActions;
+  }
+  const collisions = Object.keys(actions).filter((key) => (key in apiConfig.endpoints));
+  if (collisions.length > 0) {
+    throw new ConfigError(`Action name(s) collide with endpoint name(s): ${collisions.join(", ")}`, {
+      endpoint: collisions[0],
+      method: "GET",
+      url: "",
+      attempt: 0,
+      maxRetries: 0,
+      elapsedMs: 0
+    });
+  }
+  return proxy;
 }
-function getHeadersAsObject(headers) {
-  const result = {};
-  headers.forEach((value, key) => {
-    result[key] = value;
-  });
-  return result;
-}
-function calculateSizeInMb(data) {
-  const sizeInBytes = new TextEncoder().encode(JSON.stringify(data)).length;
-  return sizeInBytes / (1024 * 1024);
-}
-function defaultShouldRetry({ error, response }) {
-  if (error)
-    return true;
-  return response ? response.status >= 500 : false;
-}
-function delay(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
+var createApiClient = (apiConfig) => createApiClientImpl(apiConfig);
 export {
-  createApiWrapper,
-  createApiClient,
+  ActionError,
+  ApiError,
+  ConfigError,
+  HttpResponseError,
+  NetworkError,
+  RequestAbortedError,
+  RequestTimeoutError,
+  RequestValidationError,
   ResponseValidationError,
-  HttpResponseError
+  createApiClient,
+  defineAction,
+  isActionError,
+  isApiError,
+  isConfigError,
+  isHttpResponseError,
+  isNetworkError,
+  isNonRetryableApiError,
+  isRequestAbortedError,
+  isRequestTimeoutError,
+  isRequestValidationError,
+  isResponseValidationError
 };