@molecule/app-http 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/client.d.ts

@@ -0,0 +1,99 @@
+/**
+ * HTTP client interface definitions.
+ *
+ * Defines the contract that all HTTP client implementations must follow.
+ *
+ * @module
+ */
+import type { ErrorInterceptor, RequestInterceptor, ResponseInterceptor } from './interceptors.js';
+import type { FullRequestConfig, HttpResponse, RequestConfig } from './types.js';
+/**
+ * HTTP client interface.
+ *
+ * All HTTP providers must implement this interface.
+ */
+export interface HttpClient {
+    /**
+     * Base URL for all requests.
+     */
+    baseURL: string;
+    /**
+     * Default headers for all requests.
+     */
+    defaultHeaders: Record<string, string>;
+    /**
+     * Makes a generic HTTP request.
+     */
+    request<T = unknown>(config: FullRequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Makes a GET request.
+     */
+    get<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Makes a POST request.
+     */
+    post<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Makes a PUT request.
+     */
+    put<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Makes a PATCH request.
+     */
+    patch<T = unknown>(url: string, data?: unknown, config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Makes a DELETE request.
+     */
+    delete<T = unknown>(url: string, config?: RequestConfig): Promise<HttpResponse<T>>;
+    /**
+     * Adds a request interceptor.
+     * Returns a function to remove the interceptor.
+     */
+    addRequestInterceptor(interceptor: RequestInterceptor): () => void;
+    /**
+     * Adds a response interceptor.
+     * Returns a function to remove the interceptor.
+     */
+    addResponseInterceptor(interceptor: ResponseInterceptor): () => void;
+    /**
+     * Adds an error interceptor.
+     * Returns a function to remove the interceptor.
+     */
+    addErrorInterceptor(interceptor: ErrorInterceptor): () => void;
+    /**
+     * Sets the authorization token.
+     */
+    setAuthToken(token: string | null): void;
+    /**
+     * Returns the current authorization token, or `null` if not set.
+     */
+    getAuthToken(): string | null;
+    /**
+     * Registers a handler for authentication errors (401).
+     *
+     * @returns An unsubscribe function.
+     */
+    onAuthError(handler: () => void): () => void;
+}
+/**
+ * HTTP client configuration.
+ */
+export interface HttpClientConfig {
+    /**
+     * Base URL for all requests.
+     */
+    baseURL?: string;
+    /**
+     * Default headers for all requests.
+     */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Default timeout in milliseconds.
+     */
+    timeout?: number;
+    /**
+     * Whether to include credentials by default.
+     */
+    withCredentials?: boolean;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAEhF;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAA;IAEf;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEtC;;OAEG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAEzE;;OAEG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAE/E;;OAEG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAEhG;;OAEG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAE/F;;OAEG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAEjG;;OAEG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;IAElF;;;OAGG;IACH,qBAAqB,CAAC,WAAW,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAAA;IAElE;;;OAGG;IACH,sBAAsB,CAAC,WAAW,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAAA;IAEpE;;;OAGG;IACH,mBAAmB,CAAC,WAAW,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAAA;IAE9D;;OAEG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAExC;;OAEG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI,CAAA;IAE7B;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEvC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B"}

package/dist/client.js

@@ -0,0 +1,9 @@
+/**
+ * HTTP client interface definitions.
+ *
+ * Defines the contract that all HTTP client implementations must follow.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Client HTTP interface for molecule.dev.
+ *
+ * Provides a unified HTTP client API that works across different
+ * HTTP libraries (fetch, axios, ky, etc.).
+ *
+ * @example
+ * ```tsx
+ * // In a React component, get the configured client from context and call it.
+ * // The hook is exported by the framework binding (@molecule/app-react), not
+ * // this core package — never construct your own fetch/axios client.
+ * import { useHttpClient } from '@molecule/app-react'
+ *
+ * function Plants() {
+ *   const http = useHttpClient()
+ *   const load = async () => {
+ *     const res = await http.get<Plant[]>('/plants')   // baseURL ('/api') is prepended
+ *     setPlants(res.data)
+ *   }
+ *   // http.post(url, body), http.put, http.delete are also available.
+ * }
+ * ```
+ *
+ * @remarks
+ * Make ALL API calls through this client (via the framework hook `useHttpClient()` in
+ * React / the Vue composable) — it carries the configured `baseURL`, auth headers, and
+ * interceptors. Do NOT call `fetch()` / `axios` directly in components — that bypasses auth
+ * + base-URL config and breaks when the transport is swapped.
+ *
+ * Two mistakes that break in preview/production (seen in real imported apps):
+ * - **Pass RELATIVE paths; never a hardcoded host.** Use `'/plants'` (the `baseURL` `'/api'`
+ *   is prepended), NOT `'/api/plants'`, and NEVER an absolute dev URL like
+ *   `'http://localhost:4000/api/…'`. A hardcoded `localhost`/host works on the author's
+ *   machine, then fails cross-origin (CORS) in the preview and points at the wrong server in
+ *   production. The base URL is configured ONCE (via `setClient`), not per call.
+ * - **The client is PUBLIC — never put a secret in it.** Anything the browser sends (an API
+ *   key, a service-role / `sk_…` key, a signing secret) is visible to every user. Secrets
+ *   stay in YOUR API; the browser calls your API and the API uses the secret server-side.
+ *   Only a publishable/public key may ever be client-side.
+ *
+ * Auth (the bearer token / session cookie) is attached by the client's interceptors — do not
+ * read a token from `localStorage` or hand-attach it (the token is memory-only; see the user
+ * resource).
+ *
+ * @module
+ */
+export * from './client.js';
+export * from './interceptors.js';
+export * from './provider.js';
+export * from './types.js';
+export * from './unwrap.js';
+export * from './utilities.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * Client HTTP interface for molecule.dev.
+ *
+ * Provides a unified HTTP client API that works across different
+ * HTTP libraries (fetch, axios, ky, etc.).
+ *
+ * @example
+ * ```tsx
+ * // In a React component, get the configured client from context and call it.
+ * // The hook is exported by the framework binding (@molecule/app-react), not
+ * // this core package — never construct your own fetch/axios client.
+ * import { useHttpClient } from '@molecule/app-react'
+ *
+ * function Plants() {
+ *   const http = useHttpClient()
+ *   const load = async () => {
+ *     const res = await http.get<Plant[]>('/plants')   // baseURL ('/api') is prepended
+ *     setPlants(res.data)
+ *   }
+ *   // http.post(url, body), http.put, http.delete are also available.
+ * }
+ * ```
+ *
+ * @remarks
+ * Make ALL API calls through this client (via the framework hook `useHttpClient()` in
+ * React / the Vue composable) — it carries the configured `baseURL`, auth headers, and
+ * interceptors. Do NOT call `fetch()` / `axios` directly in components — that bypasses auth
+ * + base-URL config and breaks when the transport is swapped.
+ *
+ * Two mistakes that break in preview/production (seen in real imported apps):
+ * - **Pass RELATIVE paths; never a hardcoded host.** Use `'/plants'` (the `baseURL` `'/api'`
+ *   is prepended), NOT `'/api/plants'`, and NEVER an absolute dev URL like
+ *   `'http://localhost:4000/api/…'`. A hardcoded `localhost`/host works on the author's
+ *   machine, then fails cross-origin (CORS) in the preview and points at the wrong server in
+ *   production. The base URL is configured ONCE (via `setClient`), not per call.
+ * - **The client is PUBLIC — never put a secret in it.** Anything the browser sends (an API
+ *   key, a service-role / `sk_…` key, a signing secret) is visible to every user. Secrets
+ *   stay in YOUR API; the browser calls your API and the API uses the secret server-side.
+ *   Only a publishable/public key may ever be client-side.
+ *
+ * Auth (the bearer token / session cookie) is attached by the client's interceptors — do not
+ * read a token from `localStorage` or hand-attach it (the token is memory-only; see the user
+ * resource).
+ *
+ * @module
+ */
+export * from './client.js';
+export * from './interceptors.js';
+export * from './provider.js';
+export * from './types.js';
+export * from './unwrap.js';
+export * from './utilities.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,cAAc,aAAa,CAAA;AAC3B,cAAc,mBAAmB,CAAA;AACjC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA"}

package/dist/interceptors.d.ts

@@ -0,0 +1,27 @@
+/**
+ * HTTP interceptor type definitions.
+ *
+ * Interceptors allow modification of requests and responses
+ * at various stages of the HTTP lifecycle.
+ *
+ * @module
+ */
+import type { FullRequestConfig, HttpError, HttpResponse } from './types.js';
+/**
+ * Intercepts outgoing requests to modify headers, URL, or body
+ * before the request is sent.
+ *
+ * @param config - The full request configuration to transform.
+ */
+export type RequestInterceptor = (config: FullRequestConfig) => FullRequestConfig | Promise<FullRequestConfig>;
+/**
+ * Intercepts incoming responses to transform data, check status,
+ * or perform side effects before the response reaches the caller.
+ */
+export type ResponseInterceptor<T = unknown> = (response: HttpResponse<T>) => HttpResponse<T> | Promise<HttpResponse<T>>;
+/**
+ * Intercepts HTTP errors to transform, retry, or rethrow them.
+ * Throwing from this interceptor propagates the error to the caller.
+ */
+export type ErrorInterceptor = (error: HttpError) => HttpError | Promise<HttpError> | never;
+//# sourceMappingURL=interceptors.d.ts.map

package/dist/interceptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptors.d.ts","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,MAAM,EAAE,iBAAiB,KACtB,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;AAEnD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,GAAG,OAAO,IAAI,CAC7C,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,KACtB,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA;AAE/C;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,GAAG,KAAK,CAAA"}

package/dist/interceptors.js

@@ -0,0 +1,10 @@
+/**
+ * HTTP interceptor type definitions.
+ *
+ * Interceptors allow modification of requests and responses
+ * at various stages of the HTTP lifecycle.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=interceptors.js.map

package/dist/interceptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptors.js","sourceRoot":"","sources":["../src/interceptors.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/provider.d.ts

@@ -0,0 +1,20 @@
+/**
+ * HTTP client provider implementations.
+ *
+ * Contains concrete implementations of the HttpClient interface.
+ *
+ * @module
+ */
+import type { HttpClient, HttpClientConfig } from './client.js';
+/**
+ * Creates a fetch-based HTTP client using the native Fetch API.
+ *
+ * Supports request/response/error interceptors, automatic JSON
+ * serialization, auth token injection, timeout via AbortController,
+ * and 401 error handler hooks.
+ *
+ * @param config - Client configuration including baseURL, default headers, timeout, and credentials.
+ * @returns A fully configured `HttpClient` instance.
+ */
+export declare const createFetchClient: (config?: HttpClientConfig) => HttpClient;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAK/D;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAQ,gBAAqB,KAAG,UAwVjE,CAAA"}