apexa 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to Apexa are documented here.
+
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Class-based HTTP client API.
+- Typed request and response contracts.
+- Request and response interceptors.
+- Per-request overrides for client configuration.
+- Configurable adapters and response interpreters.
+- Timeout, cancellation, CSRF, and retry options.
+
+### Before the first release
+- Confirm the final package name and version.
+- Run type checking and automated tests.
+- Verify ESM exports and generated declaration files.
+- Test the packed tarball in a clean consumer project.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Apexa contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,275 @@
-# Temporary Holding Version
+# Apexa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A configurable, TypeScript-first HTTP client built on the Fetch API.**
+
+Apexa provides a small class-based API for HTTP requests, request and response interceptors, per-request configuration overrides, custom adapters, response parsing, cancellation, timeouts, CSRF handling, and opt-in retries.
+
+> **Release status:** Review and test the implementation before publishing. The documentation and release scaffold do not certify the current source code as production-ready.
+
+## Features
+
+- TypeScript-first API with generic response types.
+- Instance defaults with per-request overrides, including `baseUrl` and `basePath`.
+- Familiar `get`, `post`, `put`, `patch`, `delete`, `head`, `options`, and `request` methods.
+- Query parameter serialization.
+- JSON request-body serialization and content-type-aware response parsing.
+- Request and response interceptors.
+- Custom Fetch-compatible adapters and response interpreters.
+- Request cancellation with `AbortSignal`.
+- Request timeouts and minimum request duration.
+- Optional CSRF token handling.
+- Opt-in retry configuration for safe methods.
+- Structured errors with stable error codes.
+
+## Requirements
+
+- A supported Node.js release or a modern browser with the Fetch API.
+- TypeScript 5.x or later if consuming TypeScript declarations directly.
+
+The default Fetch adapter requires absolute URLs in environments where Fetch does not resolve relative URLs (for example, Node.js). Configure `baseUrl` or provide a custom adapter.
+
+## Installation
+
+```bash
+npm install apexa
+```
+
+If the unscoped `apexa` name is unavailable, install the published scoped name chosen by the maintainers instead.
+
+## Quick start
+
+```ts
+import Apexa from "apexa";
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+const api = new Apexa({
+  baseUrl: "https://api.example.com",
+  basePath: "/api/v1",
+  timeout: 10_000,
+  headers: {
+    Accept: "application/json",
+  },
+});
+
+const response = await api.get<User>("/users/123");
+
+console.log(response.status);
+console.log(response.data.name);
+```
+
+The generic type passed to `get<T>()` is a compile-time expectation. It does **not** validate untrusted server data at runtime. Validate API payloads with a runtime schema when that guarantee is required.
+
+## Override settings for one request
+
+Request-level options override the instance defaults.
+
+```ts
+const response = await api.get<User>("/users/123", {
+  baseUrl: "https://staging.example.com",
+  basePath: "/api/v2",
+  timeout: 5_000,
+  credentials: "same-origin",
+  headers: {
+    Authorization: "Bearer YOUR_TOKEN",
+  },
+  query: {
+    include: ["profile", "roles"],
+    active: true,
+  },
+});
+```
+
+An absolute URL passed as the `url` argument bypasses `baseUrl` and `basePath`.
+
+## Send JSON
+
+```ts
+interface CreateUserInput {
+  name: string;
+  email: string;
+}
+
+const response = await api.post<User>("/users", {
+  name: "Ada Lovelace",
+  email: "ada@example.com",
+});
+```
+
+Plain objects and arrays are serialized as JSON by the default adapter. Use `FormData`, `Blob`, `URLSearchParams`, or another supported `BodyInit` value for non-JSON payloads. Do not manually set a multipart `Content-Type` header for `FormData`; the runtime must generate the boundary.
+
+## Interceptors
+
+```ts
+const requestInterceptorId = api.interceptors.request.use((config) => {
+  config.headers.set("X-Client", "Apexa");
+  return config;
+});
+
+const responseInterceptorId = api.interceptors.response.use(
+  (response) => response,
+  (error: unknown) => {
+    console.error("Request failed", error);
+    throw error;
+  },
+);
+
+// Remove interceptors when no longer needed.
+api.interceptors.request.eject(requestInterceptorId);
+api.interceptors.response.eject(responseInterceptorId);
+```
+
+Request interceptors execute in reverse registration order. Response interceptors execute in registration order. An interceptor should return the updated configuration or response unless it intentionally rejects the chain.
+
+## Error handling
+
+```ts
+import Apexa, { ApexaError } from "apexa";
+
+const api = new Apexa({ baseUrl: "https://api.example.com" });
+
+try {
+  await api.get("/private");
+} catch (error: unknown) {
+  if (error instanceof ApexaError) {
+    console.error(error.code);
+    console.error(error.message);
+    console.error(error.response?.status);
+  } else {
+    throw error;
+  }
+}
+```
+
+Errors may expose a stable `code`, request `config`, response metadata, and the original `cause` where available. See [API reference](./docs/API.md) for the error code list.
+
+## Cancellation
+
+```ts
+const controller = new AbortController();
+
+const request = api.get<User>("/users/123", {
+  signal: controller.signal,
+});
+
+// Cancel whenever appropriate.
+controller.abort();
+
+await request;
+```
+
+The request rejects when aborted. Handle the rejection at the call site.
+
+## Timeout and minimum duration
+
+```ts
+const response = await api.get<User>("/users/123", {
+  timeout: 8_000,
+  minimumTime: 250,
+});
+```
+
+`timeout: 0` disables the timeout. `minimumTime` requests that the total request operation take at least the specified number of milliseconds; it is not a server-side processing guarantee.
+
+## CSRF
+
+CSRF handling is disabled by default. Enable it only when it matches the security model of your application.
+
+```ts
+const api = new Apexa({
+  baseUrl: "https://app.example.com",
+  csrf: {
+    enabled: true,
+    cookieName: "csrf-token",
+    headerName: "X-CSRF-Token",
+    required: true,
+  },
+});
+```
+
+By default, the implementation looks for a readable cookie. `HttpOnly` cookies cannot be read by JavaScript; use `tokenProvider` or another server/application-specific mechanism when needed. CSRF tokens do not replace authorization, secure cookie settings, or server-side CSRF validation.
+
+## Retries
+
+Retries are disabled by default. Enable them deliberately:
+
+```ts
+const response = await api.get("/status", {
+  retry: {
+    enabled: true,
+    retries: 2,
+    delay: 300,
+    maxDelay: 5_000,
+    backoff: 2,
+  },
+});
+```
+
+The default adapter should retry only operations safe to repeat. Do not automatically retry non-idempotent mutations unless your API supports idempotency keys and you have deliberately designed for duplicate delivery.
+
+## Custom response interpreter
+
+```ts
+const api = new Apexa({
+  baseUrl: "https://api.example.com",
+  interpreter: async (response) => {
+    if (response.status === 204) return undefined;
+    return response.json() as Promise<unknown>;
+  },
+});
+```
+
+The interpreter parses response data; it does not validate the returned payload's shape.
+
+## Custom adapter
+
+```ts
+import type { HttpAdapter } from "apexa";
+
+const adapter: HttpAdapter = async (config) => {
+  return fetch(config.url, {
+    method: config.method,
+    headers: config.headers,
+    signal: config.signal,
+    credentials: config.credentials,
+  });
+};
+
+const api = new Apexa({
+  baseUrl: "https://api.example.com",
+  adapter,
+});
+```
+
+A custom adapter must honor the contract expected by Apexa and return a native `Response`. If it needs to support additional HTTP methods or runtime-specific behavior, document and test those guarantees.
+
+## API reference
+
+See [docs/API.md](./docs/API.md) for the public configuration, methods, interceptors, errors, and defaults.
+
+## Browser and server environments
+
+- The default adapter uses the platform Fetch API.
+- Cookie-based CSRF token lookup requires a browser environment with `document.cookie`.
+- Browser CORS rules and server-side networking restrictions still apply.
+- In Node.js, set an absolute `baseUrl` for relative endpoint paths.
+- Do not put secrets in client-side bundles or request metadata.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm pack --dry-run
+```
+
+Before publishing, verify the package contents and test installation from the generated tarball.
+
+## License
+
+MIT. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Apexa — configurable, strongly typed HTTP client.
+ *
+ * @packageDocumentation
+ */
+import type { ApiResponse, ApexaConfig, ApexaErrorCode, ApexaErrorOptions, ApexaRequestMethods, HttpAdapter, InternalRequestConfig, InterceptorId, RequestBody, RequestOptions, ResponseInterpreter } from "./types.js";
+/**
+ * Standardized error thrown by Apexa.
+ *
+ * Use `code` for programmatic handling and `response` to inspect an HTTP
+ * response when one was received.
+ */
+export declare class ApexaError extends Error {
+    /** Stable error code. */
+    readonly code: ApexaErrorCode;
+    /** Request configuration, when available. */
+    readonly config?: InternalRequestConfig;
+    /** Parsed response, when available. */
+    readonly response?: ApiResponse<unknown>;
+    /**
+     * Create an Apexa error.
+     *
+     * @param message - Human-readable error message.
+     * @param options - Error code and optional diagnostic context.
+     */
+    constructor(message: string, options: ApexaErrorOptions);
+}
+/** Alias for applications that prefer the name `ApiError`. */
+export { ApexaError as ApiError };
+interface InterceptorHandler<F, R> {
+    readonly id: InterceptorId;
+    readonly fulfilled?: F;
+    readonly rejected?: R;
+}
+/**
+ * Manages registration, removal, and snapshotting of interceptors.
+ *
+ * Interceptor identifiers remain stable until removed. Removing an interceptor
+ * does not alter requests that have already taken their snapshot.
+ */
+declare class InterceptorManager<F, R> {
+    private handlers;
+    private nextId;
+    /**
+     * Register a fulfilled and/or rejected callback.
+     *
+     * @returns An identifier for later removal with `eject`.
+     */
+    use(fulfilled?: F, rejected?: R): InterceptorId;
+    /** Remove a registered interceptor. Unknown IDs are ignored. */
+    eject(id: InterceptorId): void;
+    /** Remove all interceptors from this manager. */
+    clear(): void;
+    /** Return a stable snapshot of the current handlers. */
+    snapshot(): ReadonlyArray<InterceptorHandler<F, R>>;
+}
+/**
+ * Public request and response interceptor registry.
+ *
+ * Request interceptors execute in reverse registration order.
+ * Response interceptors execute in registration order.
+ */
+export declare class InterceptorRegistry {
+    /** Request interceptors. */
+    readonly request: InterceptorManager<(config: InternalRequestConfig) => InternalRequestConfig | Promise<InternalRequestConfig>, (error: unknown) => unknown>;
+    /** Response interceptors. */
+    readonly response: InterceptorManager<(response: ApiResponse<unknown>) => ApiResponse<unknown> | Promise<ApiResponse<unknown>>, (error: unknown) => unknown>;
+}
+/**
+ * Default response interpreter.
+ *
+ * JSON content types are parsed as JSON. Other content types are returned
+ * as text. Empty and bodyless responses return `undefined`.
+ */
+export declare const defaultInterpreter: ResponseInterpreter;
+/**
+ * Default Fetch-based transport adapter.
+ *
+ * It sends the normalized request configuration and returns the native
+ * `Response`. Response parsing and HTTP status handling are performed by Apexa.
+ */
+export declare const fetchAdapter: HttpAdapter;
+/**
+ * Configurable HTTP client with typed response methods and interceptors.
+ *
+ * Instance defaults can be overridden on each request, including `baseUrl`
+ * and `basePath`.
+ *
+ * @example
+ * ```ts
+ * const api = new Apexa({
+ *   baseUrl: "https://api.example.com",
+ *   basePath: "/api/v1",
+ *   timeout: 10_000,
+ * });
+ *
+ * const response = await api.get<User>("/users/123");
+ * console.log(response.data);
+ *
+ * // Override both URL settings for one request.
+ * const other = await api.get<User>("/users/123", {
+ *   baseUrl: "https://other.example.com",
+ *   basePath: "/v2",
+ * });
+ * ```
+ */
+export declare class Apexa implements ApexaRequestMethods {
+    /** Request and response interceptors. */
+    readonly interceptors: InterceptorRegistry;
+    private readonly defaults;
+    /**
+     * Create an Apexa instance.
+     *
+     * @param config - Default options used by requests.
+     */
+    constructor(config?: ApexaConfig);
+    /**
+     * Execute a request using the configured request pipeline.
+     *
+     * @typeParam T - Expected response data type.
+     * @param url - Absolute URL or relative endpoint path.
+     * @param options - Per-request overrides.
+     * @returns Parsed response and request metadata.
+     */
+    request<T = unknown>(url: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /** Execute a GET request. */
+    get<T = unknown>(url: string, options?: Omit<RequestOptions, "method" | "body">): Promise<ApiResponse<T>>;
+    /** Execute a DELETE request. */
+    delete<T = unknown>(url: string, options?: Omit<RequestOptions, "method" | "body">): Promise<ApiResponse<T>>;
+    /** Execute a HEAD request. */
+    head(url: string, options?: Omit<RequestOptions, "method" | "body">): Promise<ApiResponse<undefined>>;
+    /** Execute an OPTIONS request. */
+    options<T = unknown>(url: string, options?: Omit<RequestOptions, "method" | "body">): Promise<ApiResponse<T>>;
+    /** Execute a POST request. */
+    post<T = unknown>(url: string, body?: RequestBody, options?: Omit<RequestOptions, "method" | "body">): Promise<ApiResponse<T>>;
+    /** Execute a PUT request. */
+    put<T = unknown>(url: string, body?: RequestBody, options?: Omit<RequestOptions, "method" | "body">): Promise<ApiResponse<T>>;
+    /** Execute a PATCH request. */
+    patch<T = unknown>(url: string, body?: RequestBody, options?: Omit<RequestOptions, "method" | "body">): Promise<ApiResponse<T>>;
+    private applyCsrf;
+    private performWithRetry;
+    private runResponseFulfillmentChain;
+    private runResponseRejectionChain;
+}
+/** Default export for convenient imports. */
+export default Apexa;
+/** Re-export the public types from the package entry point. */
+export type { ApiResponse, ApexaConfig, ApexaErrorCode, ApexaErrorOptions, ApexaRequestMethods, ClientOptions, CsrfOptions, CredentialsMode, FetchOptions, HttpAdapter, HttpMethod, InternalRequestConfig, InterceptorId, QueryParams, QueryScalar, QueryValue, RequestBody, RequestMetadata, RequestOptions, ResponseInterpreter, RetryOptions, RetryStatus, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EAEnB,WAAW,EAEX,qBAAqB,EACrB,aAAa,EACb,WAAW,EACX,cAAc,EACd,mBAAmB,EAEpB,MAAM,YAAY,CAAC;AAmCpB;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,yBAAyB;IACzB,SAAgB,IAAI,EAAE,cAAc,CAAC;IAErC,6CAA6C;IAC7C,SAAgB,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAE/C,uCAAuC;IACvC,SAAgB,QAAQ,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAEhD;;;;;OAKG;IACH,YAAmB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,EAS7D;CACF;AAED,8DAA8D;AAC9D,OAAO,EAAE,UAAU,IAAI,QAAQ,EAAE,CAAC;AAMlC,UAAU,kBAAkB,CAAC,CAAC,EAAE,CAAC;IAC/B,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;CACvB;AAED;;;;;GAKG;AACH,cAAM,kBAAkB,CAAC,CAAC,EAAE,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,MAAM,CAAK;IAEnB;;;;OAIG;IACI,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,aAAa,CAUrD;IAED,gEAAgE;IACzD,KAAK,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,CAEpC;IAED,iDAAiD;IAC1C,KAAK,IAAI,IAAI,CAEnB;IAED,wDAAwD;IACjD,QAAQ,IAAI,aAAa,CAAC,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAEzD;CACF;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,4BAA4B;IAC5B,SAAgB,OAAO,8BAEX,qBAAqB,KAC1B,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,UACnD,OAAO,KAAK,OAAO,EACzB;IAEJ,6BAA6B;IAC7B,SAAgB,QAAQ,gCAEV,WAAW,CAAC,OAAO,CAAC,KAC3B,WAAW,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,UACjD,OAAO,KAAK,OAAO,EACzB;CACL;AAsMD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,mBA6BhC,CAAC;AAqBF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,WAoC1B,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,KAAM,YAAW,mBAAmB;IAC/C,yCAAyC;IACzC,SAAgB,YAAY,sBAA6B;IAEzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IAEvC;;;;OAIG;IACH,YAAmB,MAAM,GAAE,WAAgB,EAQ1C;IAED;;;;;;;OAOG;IACU,OAAO,CAAC,CAAC,GAAG,OAAO,EAC9B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAkOzB;IAED,6BAA6B;IACtB,GAAG,CAAC,CAAC,GAAG,OAAO,EACpB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,MAAM,CAAM,GACpD,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAEzB;IAED,gCAAgC;IACzB,MAAM,CAAC,CAAC,GAAG,OAAO,EACvB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,MAAM,CAAM,GACpD,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAEzB;IAED,8BAA8B;IACvB,IAAI,CACT,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,MAAM,CAAM,GACpD,OAAO,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAEjC;IAED,kCAAkC;IAC3B,OAAO,CAAC,CAAC,GAAG,OAAO,EACxB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,MAAM,CAAM,GACpD,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAEzB;IAED,8BAA8B;IACvB,IAAI,CAAC,CAAC,GAAG,OAAO,EACrB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,MAAM,CAAM,GACpD,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAMzB;IAED,6BAA6B;IACtB,GAAG,CAAC,CAAC,GAAG,OAAO,EACpB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,MAAM,CAAM,GACpD,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAMzB;IAED,+BAA+B;IACxB,KAAK,CAAC,CAAC,GAAG,OAAO,EACtB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,MAAM,CAAM,GACpD,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAMzB;YAEa,SAAS;YA0BT,gBAAgB;YAuDhB,2BAA2B;YAgB3B,yBAAyB;CAcxC;AAED,6CAA6C;eAC9B,KAAK;AAEpB,+DAA+D;AAC/D,YAAY,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,WAAW,EACX,eAAe,EACf,YAAY,EACZ,WAAW,EACX,UAAU,EACV,qBAAqB,EACrB,aAAa,EACb,WAAW,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC"}