@jayethian/axiom 0.1.1 → 0.1.2

package/README.md

@@ -1,8 +1,8 @@
 <div align="center">
-  <img src="./assets/logo.png" alt="axiom logo" width="400" />
+  <img src="https://raw.githubusercontent.com/jayethian/axiom/main/assets/logo.png" alt="axiom logo" width="400" />
   <h1>Axiom</h1>
 
-  <h3>Resilient, offline-first networking for modern React apps.</h3>
+  <h3>Resilient, offline-first networking for modern React, Next.js, and React Native apps.</h3>
   
   <p>
     <a href="https://www.npmjs.com/package/@jayethian/axiom">
@@ -21,10 +21,10 @@
 <br />
 
 ## The Problem
-Standard HTTP clients like **Axios** or **Fetch** assume a stable connection. When a user submits data in a dead zone (elevators, basements, rural areas), the request simply fails. Without a complex manual retry system, **that data is gone forever.**
+Standard HTTP clients like **Axios** or **Fetch** assume a stable connection. When a user submits data in a dead zone (elevators, basements, rural areas), the request simply fails. Without a complex, manual retry system written from scratch, **that data is gone forever.**
 
 ## The Axiom Way
-Axiom intercepts network failures and timeouts. Instead of throwing an error, it serializes the request and moves it to a persistent local queue. When the connection returns, Axiom flushes the queue automatically.
+Axiom intercepts network failures and timeouts. Instead of throwing an error, it serializes the request and safely moves it to a persistent local queue. When the connection returns, Axiom flushes the queue automatically, in the background.
 
 ```typescript
 // Standard Fetch: Fails and loses data when offline.
@@ -37,101 +37,242 @@ await axiom.post('/api/orders', data);
 
 ---
 
-## Key Features
+## Table of Contents
 
-* **📱 Mobile-First Resilience:** Specifically tuned for React Native's shaky connectivity.
+1. [Features](https://www.google.com/search?q=%23-features)
+2. [Installation](https://www.google.com/search?q=%23-installation)
+3. [React / Next.js Setup](https://www.google.com/search?q=%23-react--nextjs-setup-zero-config)
+4. [React Native Setup](https://www.google.com/search?q=%23-react-native-setup)
+5. [Vanilla JS / Node Setup](https://www.google.com/search?q=%23-vanilla-js--node-setup)
+6. [Core Hooks (`useAxiomQueue`)](https://www.google.com/search?q=%23-core-hooks)
+7. [Advanced Architecture](https://www.google.com/search?q=%23-advanced-architecture)
+* [Global Interceptors](https://www.google.com/search?q=%23global-interceptors)
+* [Priority Lanes](https://www.google.com/search?q=%23priority-lanes)
+* [Queue Inspection & "Outbox" UI](https://www.google.com/search?q=%23queue-inspection--outbox-ui)
+* [Storage Adapters (MMKV, IndexedDB)](https://www.google.com/search?q=%23storage-adapters)
+
+
+8. [API Reference](https://www.google.com/search?q=%23-api-reference)
+
+---
+
+## Features
+
+* **📱 Mobile-First Resilience:** Specifically tuned to handle spotty connectivity, aggressive timeouts, and background execution.
+* **🧠 Smart Fallback Storage:** Automatically detects your environment and falls back to the safest storage (`IndexedDB` for Web, `Memory` for SSR/React Native) without crashing.
 * **🔄 Autonomous Background Sync:** Replays the queue the moment a signal is detected.
 * **⚡ Priority Lanes:** Ensure critical data (e.g., payments) jumps to the front of the queue ahead of background tasks (e.g., analytics).
-* **🛡️ Just-In-Time Headers:** Refresh Auth Tokens immediately before syncing to prevent `401 Unauthorized` errors on old requests.
-* **💾 Storage Agnostic:** Use the high-performance storage of your choice (**MMKV**, **SQLite**, **IndexedDB**).
-* **🪦 Dead Letter Queues:** Protects your app from infinite loops by isolating permanently failing requests.
+* **🛡️ Just-In-Time Headers:** Refresh Auth Tokens immediately before syncing to prevent `401 Unauthorized` errors on delayed requests.
+* **🔌 Global Interceptors:** Catch success and error events globally, even when requests resolve in the background hours later.
+* **🪦 Dead Letter Queues:** Protects your app from infinite loops by isolating permanently failing requests and exposing them to the UI for user intervention.
 
 ---
 
 ## Installation
 
 ```bash
+npm install @jayethian/axiom
+# or
 yarn add @jayethian/axiom
 # or
-npm install @jayethian/axiom
+pnpm add @jayethian/axiom
 
 ```
 
 ---
 
-## Setup & Usage
+## React & Next.js Setup (Zero-Config)
+Axiom includes a built-in event listener that automatically binds to the browser's `window.addEventListener('online')` APIs. For Next.js and standard React Web apps, setup requires zero boilerplate.
+
+```tsx
+// App.tsx or layout.tsx
+import { AxiomProvider } from '@jayethian/axiom';
+
+export default function App({ children }) {
+  return (
+    <AxiomProvider
+      config={{ 
+        baseURL: '[https://api.myapp.com](https://api.myapp.com)', 
+        timeout: 8000 
+      }}
+      // Automatically uses IndexedDB, falls back to LocalStorage if in Private Browsing
+      fallbackAdapter="indexeddb" 
+    >
+      {children}
+    </AxiomProvider>
+  );
+}
+
+```
+
+---
 
-### 1. Initialize the Provider
+## React Native Setup
 
-Wrap your app root. Axiom doesn't force a specific network library on you—just pass in your preferred listener (like NetInfo).
+React Native does not have a native DOM `window`, so you must provide a network listener (like `@react-native-community/netinfo`) and a persistent storage adapter (like `react-native-mmkv` or `AsyncStorage`).
 
 ```tsx
 import { AxiomProvider } from '@jayethian/axiom';
 import NetInfo from '@react-native-community/netinfo';
+import { MMKVAdapter } from './my-adapters'; // See Storage Adapters below
 
-export default function App() {
+export default function App({ children }) {
   return (
     <AxiomProvider
-      config={{ baseURL: '[https://api.myapp.com](https://api.myapp.com)', timeout: 10000 }}
+      config={{ baseURL: '[https://api.myapp.com](https://api.myapp.com)' }}
+      storageAdapter={new MMKVAdapter()}
       networkListener={(callback) => {
         return NetInfo.addEventListener(state => callback(!!state.isConnected));
       }}
     >
-      <Main />
+      {children}
     </AxiomProvider>
   );
 }
 
 ```
 
-### 2. Use Hooks for Better UX
+---
+
+## Vanilla JS / Node Setup
+
+You do not need React to use Axiom. You can instantiate the engine directly and use our built-in **Event Emitter** to listen for background syncs.
+
+```typescript
+import { axiom } from '@jayethian/axiom';
+
+// 1. Initialize
+axiom.create({ baseURL: '[https://api.myapp.com](https://api.myapp.com)' });
 
-Keep your users informed when they are working offline.
+// 2. Listen to Background Events
+axiom.on('syncSuccess', (data, req) => {
+  console.log(`Background sync finished for ${req.url}`);
+});
+
+axiom.on('deadLetter', (req) => {
+  console.error(`Request permanently failed after 3 retries:`, req);
+});
+
+// 3. Make Requests
+const response = await axiom.post('/users', { name: 'John' });
+
+```
+
+---
+
+## Core Hooks
+
+The `useAxiomQueue` hook gives your UI complete visibility into the background engine. Keep your users informed when they are working offline.
 
 ```tsx
 import { axiom, useAxiomQueue } from '@jayethian/axiom';
 
-const { isOnline } = useAxiomQueue();
+export function CheckoutButton() {
+  const { isOnline, deadLetters, clearDeadLetters } = useAxiomQueue();
 
-const onSave = async (data) => {
-  const res = await axiom.post('/profile', data, { priority: 'urgent' });
-  
-  if (res.isQueued) {
-    showToast("Working offline. Your changes will sync automatically!");
-  }
-};
+  const onSave = async (data) => {
+    // If offline, returns a 202 and flags isQueued: true
+    const res = await axiom.post('/checkout', data, { priority: 'urgent' });
+    
+    if (res.isQueued) {
+      alert("Working offline. Your order will sync automatically!");
+    }
+  };
+
+  return (
+    <div>
+      {!isOnline && <Banner>You are offline. Actions will be saved.</Banner>}
+      {deadLetters.length > 0 && <ErrorBanner>Some actions failed to save.</ErrorBanner>}
+      
+      <button onClick={onSave}>Checkout</button>
+    </div>
+  );
+}
 
 ```
 
 ---
 
-## Advanced Configuration
+## Advanced Architecture
+
+### Global Interceptors
+
+Axiom allows you to intercept requests exactly like Axios, but it applies these rules to **background syncs** as well.
+
+```tsx
+<AxiomProvider
+  config={{
+    // Triggered globally whenever a request hard-fails (e.g., 500, 401)
+    onError: (status, error, request) => {
+      if (status === 401) {
+        AuthService.logout(); // Global logout on token expiration
+      }
+    },
+    // Triggered globally whenever ANY request succeeds (immediate or background)
+    onResponse: (data, status, request) => {
+      if (request.url.includes('/payment')) {
+        Analytics.track('Payment Successful');
+      }
+    }
+  }}
+>
+
+```
 
 ### Priority Lanes
 
-Prevent large background uploads from blocking small, critical API calls.
+By default, Axiom queues requests First-In-First-Out (FIFO). However, you can force critical requests to jump to the front of the line when the network returns.
 
 ```typescript
-// This stays at the back of the line
+// This stays at the back of the line (queued in the background)
 axiom.post('/analytics', logData, { priority: 'background' });
 
-// This jumps to the front
+// This jumps to the front and syncs first when the connection returns
 axiom.post('/chat/send', message, { priority: 'urgent' });
 
 ```
 
+### Queue Inspection & "Outbox" UI
+
+Give your users the ability to see what is waiting to sync, and let them cancel actions before the network returns.
+
+```tsx
+import { useAxiomQueue } from '@jayethian/axiom';
+
+export function Outbox() {
+  const { inspectQueue, cancelRequest } = useAxiomQueue();
+  const [pending, setPending] = useState([]);
+
+  useEffect(() => {
+    inspectQueue().then(setPending);
+  }, []);
+
+  return (
+    <ul>
+      {pending.map(req => (
+        <li key={req.id}>
+          Pending: {req.method} {req.url}
+          <button onClick={() => cancelRequest(req.id)}>Cancel</button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+```
+
 ### Just-In-Time Headers
 
-Refresh your JWT right before the queue fires to ensure every request is authorized.
+If a user is offline for 4 hours, their JWT will likely expire. If Axiom attempts to sync the old request, the server will reject it. `onBeforeSync` allows you to inject fresh tokens *milliseconds* before the queue flushes.
 
 ```tsx
 <AxiomProvider
   config={{
     onBeforeSync: async (request) => {
-      const token = await getFreshToken();
+      const freshToken = await getValidAuthToken(); // Your logic
       return {
         ...request,
-        headers: { ...request.headers, Authorization: `Bearer ${token}` }
+        headers: { ...request.headers, Authorization: `Bearer ${freshToken}` }
       };
     }
   }}
@@ -139,12 +280,77 @@ Refresh your JWT right before the queue fires to ensure every request is authori
 
 ```
 
+### Storage Adapters
+
+Axiom comes with `IndexedDB`, `LocalStorage`, and `Memory` adapters out of the box. For React Native, building a custom adapter using a high-performance library like MMKV is incredibly simple.
+
+```typescript
+import { MMKV } from 'react-native-mmkv';
+import { AxiomStorageAdapter, QueuedRequest } from '@jayethian/axiom';
+
+const mmkv = new MMKV();
+
+export class MMKVAdapter implements AxiomStorageAdapter {
+  private key = 'axiom_queue';
+
+  private getQ(): QueuedRequest[] {
+    const data = mmkv.getString(this.key);
+    return data ? JSON.parse(data) : [];
+  }
+
+  async save(req: QueuedRequest) { 
+    const q = this.getQ();
+    q.push(req);
+    mmkv.set(this.key, JSON.stringify(q)); 
+  }
+  
+  async getAll() { return this.getQ(); }
+  
+  async remove(id: string) { 
+    const q = this.getQ().filter(r => r.id !== id);
+    mmkv.set(this.key, JSON.stringify(q));
+  }
+  
+  async clearAll() { mmkv.delete(this.key); }
+}
+
+// Pass it to the provider:
+<AxiomProvider storageAdapter={new MMKVAdapter()} {...props} />
+
+```
+
+---
+
+## API Reference
+
+### `AxiomConfig`
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `baseURL` | `string` | `undefined` | Prepend this to all request URLs. |
+| `defaultHeaders` | `Record<string, string>` | `{}` | Global headers applied to all requests. |
+| `timeout` | `number` | `8000` | MS before a request is aborted and moved to the offline queue. |
+| `maxRetries` | `number` | `3` | Attempts before a background sync fails permanently. |
+| `fallbackAdapter` | `'indexeddb' | 'localstorage' | 'memory'` | `'memory'` | The internal adapter to use if `storageAdapter` is omitted. |
+| `debug` | `boolean` | `false` | Prints verbose engine logs to the console. |
+
+### `AxiomRequestOptions`
+
+Passed as the third parameter to `axiom.post`, `axiom.get`, etc.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `priority` | `'urgent' | 'background'` | Determines sort order when the queue flushes. |
+| `timeout` | `number` | Overrides the global timeout for this specific request. |
+| `headers` | `Record<string, string>` | Append or overwrite global headers for this request. |
+| `metadata` | `any` | Attach custom UI data to the request. Survives serialization. |
+
 ---
 
 ## Contributing
 
-We welcome contributions! Please feel free to submit a [Pull Request](https://www.google.com/search?q=https://github.com/jayethian/axiom/pulls) or report a [Bug](https://www.google.com/search?q=https://github.com/jayethian/axiom/issues).
+Contributions, issues, and feature requests are welcome! Feel free to check the [issues page](https://www.google.com/search?q=https://github.com/jayethian/axiom/issues).
 
-## License
+## 📄 License
 
-Distributed under the MIT License. See `LICENSE` for more information. Built with ⚡ by [Jayetheus](https://www.google.com/search?q=https://github.com/jayethian).
+This project is [MIT](https://opensource.org/licenses/MIT) licensed. Built with ⚡️ by [Jayetheus](https://www.google.com/search?q=https://github.com/jayethian).

package/package.json

@@ -1,13 +1,35 @@
 {
   "name": "@jayethian/axiom",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "maintainers": [
     "Jayetheus"
   ],
-  "description": "A resilient, offline-first fetch wrapper",
+  "description": "A resilient, offline-first fetch wrapper for React Native & Next.js.",
+  "keywords": [
+    "react-native",
+    "nextjs",
+    "fetch",
+    "axios",
+    "offline-first",
+    "sync",
+    "network",
+    "queue",
+    "indexeddb"
+  ],
+  "homepage": "https://github.com/jayethian/axiom#readme",
+  "bugs": {
+    "url": "https://github.com/jayethian/axiom/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jayethian/axiom.git"
+  },
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist"
+  ],
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -28,6 +50,5 @@
   },
   "peerDependencies": {
     "react": ">=17.0.0"
-  },
-  "packageManager": "yarn@4.12.0"
-}
+  }
+}

package/.editorconfig

@@ -1,8 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-indent_size = 2
-indent_style = space
-insert_final_newline = true

package/.gitattributes

@@ -1,4 +0,0 @@
-/.yarn/**            linguist-vendored
-/.yarn/releases/*    binary
-/.yarn/plugins/**/*  binary
-/.pnp.*              binary linguist-generated

package/src/adapters/index.ts

@@ -1,15 +0,0 @@
-import { QueuedRequest } from '../types';
-
-export interface AxiomStorageAdapter {
-  /** Saves a request to the persistent queue */
-  save(request: QueuedRequest): Promise<void>;
-  
-  /** Retrieves all pending requests, usually ordered by timestamp */
-  getAll(): Promise<QueuedRequest[]>;
-  
-  /** Removes a specific request after it successfully syncs */
-  remove(id: string): Promise<void>;
-  
-  /** Wipes the queue entirely (useful for user logout) */
-  clearAll(): Promise<void>;
-}

package/src/adapters/memory.ts

@@ -1,22 +0,0 @@
-import { AxiomStorageAdapter } from './index';
-import { QueuedRequest } from '../types';
-
-export class MemoryStorageAdapter implements AxiomStorageAdapter {
-  private queue: Map<string, QueuedRequest> = new Map();
-
-  async save(request: QueuedRequest): Promise<void> {
-    this.queue.set(request.id, request);
-  }
-
-  async getAll(): Promise<QueuedRequest[]> {
-    return Array.from(this.queue.values()).sort((a, b) => a.timestamp - b.timestamp);
-  }
-
-  async remove(id: string): Promise<void> {
-    this.queue.delete(id);
-  }
-
-  async clearAll(): Promise<void> {
-    this.queue.clear();
-  }
-}

package/src/engine/fetcher.ts

@@ -1,197 +0,0 @@
-import { AxiomConfig, AxiomRequestOptions, QueuedRequest, RequestPriority } from '../types';
-import { AxiomStorageAdapter } from '../adapters';
-import { MemoryStorageAdapter } from '../adapters/memory';
-import { SyncManager } from './sync';
-
-export class AxiomEngine {
-  private config: AxiomConfig = {};
-  private storage: AxiomStorageAdapter = new MemoryStorageAdapter(); 
-  private syncManager!: SyncManager;
-
-  /**
-   * Initializes the Axiom engine with global configuration and a storage adapter.
-   * This must be called before making any requests to enable persistence.
-   * * @param config - Global configuration (baseURL, timeouts, custom headers, etc.)
-   * @param storageAdapter - Optional custom adapter (e.g., MMKV). Defaults to in-memory storage.
-   */
-  public create(config: AxiomConfig, storageAdapter?: AxiomStorageAdapter): void {
-    this.config = config;
-    if (storageAdapter) {
-      this.storage = storageAdapter;
-    }
-
-    this.syncManager = new SyncManager(this.storage, this.config);
-  }
-
-  /**
-   * Manually triggers the background sync manager to flush all pending queued requests.
-   * Note: This is automatically handled by `AxiomProvider` when the network reconnects.
-   */
-  public async forceSync(): Promise<void> {
-    if (!this.syncManager) {
-      console.error("[Axiom] Engine not initialized. Call axiom.create() first.");
-      return;
-    }
-    await this.syncManager.flushQueue();
-  }
-
-  /**
-   * Generates a unique collision-resistant ID for queued requests.
-   */
-  private generateId(): string {
-    return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
-  }
-
-  /**
-   * Executes an HTTP GET request. 
-   * If the network is unavailable or times out, the request is safely queued.
-   * * @param url - The endpoint URL (appended to baseURL if configured).
-   * @param options - Request-specific options (priority lanes, timeout overrides).
-   * @returns A promise resolving to the response data, status code, and queue state.
-   */
-  public async get<T>(
-    url: string, 
-    options?: AxiomRequestOptions
-  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
-    return this.prepareRequest<T>('GET', url, undefined, options);
-  }
-
-  /**
-   * Executes an HTTP POST request.
-   * If the network is unavailable or times out, the payload is safely queued.
-   * * @param url - The endpoint URL.
-   * @param data - The payload object to be serialized and sent.
-   * @param options - Request-specific options.
-   */
-  public async post<T>(
-    url: string, 
-    data?: any, 
-    options?: AxiomRequestOptions
-  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
-    return this.prepareRequest<T>('POST', url, data, options);
-  }
-
-  /**
-   * Executes an HTTP PUT request to entirely replace a resource.
-   * * @param url - The endpoint URL.
-   * @param data - The payload object to be serialized and sent.
-   * @param options - Request-specific options.
-   */
-  public async put<T>(
-    url: string, 
-    data?: any, 
-    options?: AxiomRequestOptions
-  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
-    return this.prepareRequest<T>('PUT', url, data, options);
-  }
-
-  /**
-   * Executes an HTTP PATCH request to partially update a resource.
-   * * @param url - The endpoint URL.
-   * @param data - The partial payload object to be serialized and sent.
-   * @param options - Request-specific options.
-   */
-  public async patch<T>(
-    url: string, 
-    data?: any, 
-    options?: AxiomRequestOptions
-  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
-    return this.prepareRequest<T>('PATCH', url, data, options);
-  }
-
-  /**
-   * Executes an HTTP DELETE request.
-   * * @param url - The endpoint URL.
-   * @param options - Request-specific options.
-   */
-  public async delete<T>(
-    url: string, 
-    options?: AxiomRequestOptions
-  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
-    return this.prepareRequest<T>('DELETE', url, undefined, options);
-  }
-
-  /**
-   * Internal helper to consolidate request preparation and keep the engine DRY.
-   */
-  private async prepareRequest<T>(
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH',
-    url: string,
-    data?: any,
-    options?: AxiomRequestOptions
-  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
-    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
-    
-    const headers: Record<string, string> = { ...(this.config.defaultHeaders || {}) };
-    if (options?.headers) {
-      Object.assign(headers, options.headers);
-    }
-    
-    const request: QueuedRequest = {
-      id: this.generateId(),
-      timestamp: Date.now(),
-      url: fullUrl,
-      method,
-      headers,
-      body: data ? JSON.stringify(data) : undefined,
-      priority: options?.priority || 'urgent',
-      retryCount: 0
-    };
-
-    const timeoutMs = options?.timeout || this.config.timeout || 8000;
-
-    return this.attemptFetch<T>(request, timeoutMs);
-  }
-
-  /**
-   * Internal logic to fire the request or catch the network drop.
-   * Handles timeout cancellations via AbortController.
-   */
-  private async attemptFetch<T>(request: QueuedRequest, timeoutMs: number): Promise<{ data?: T; status: number; isQueued: boolean }> {
-      const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-
-    try {
-      const response = await fetch(request.url, {
-        method: request.method,
-        headers: request.headers,
-        body: request.body,
-        signal: controller.signal
-      });
-
-      clearTimeout(timeoutId);
-
-      if (response.ok) {
-        const responseData = await response.json().catch(() => null);
-        return { data: responseData, status: response.status, isQueued: false };
-      }
-
-      if (response.status >= 500) {
-        throw new Error('Server Error');
-      }
-
-      return { status: response.status, isQueued: false };
-
-    } catch (error: any) {
-        clearTimeout(timeoutId);
-
-        if(error.name === 'AbortError') {
-          console.warn(`[Axiom] Request to ${request.url} timed out after ${timeoutMs}ms. Queuing for retry.`);
-        }
-        
-        await this.enqueueRequest(request);
-
-        return { status: 202, isQueued: true };
-    }
-  }
-
-  /**
-   * Saves the request to the configured storage adapter.
-   */
-  private async enqueueRequest(request: QueuedRequest): Promise<void> {
-    console.warn(`[Axiom] Network unreachable. Queuing request ${request.id}`);
-    await this.storage.save(request);
-  }
-}
-
-export const axiom = new AxiomEngine();

package/src/engine/sync.ts

@@ -1,112 +0,0 @@
-import { AxiomStorageAdapter } from '../adapters';
-import { AxiomConfig, QueuedRequest } from '../types';
-
-export class SyncManager {
-  private isSyncing = false;
-
-  constructor(
-    private storage: AxiomStorageAdapter,
-    private config: AxiomConfig
-  ) {}
-
-  /**
-   * The master trigger. Call this when the OS reports network is back online.
-   * Automatically sorts requests so 'urgent' items bypass 'background' items.
-   */
-  public async flushQueue(): Promise<void> {
-    if (this.isSyncing) return;
-    this.isSyncing = true;
-
-    try {
-      const pending = await this.storage.getAll();
-      
-      if (pending.length === 0) {
-        return;
-      }
-
-      console.log(`[Axiom] Network restored. Syncing ${pending.length} queued requests...`);
-
-      // MITIGATION 3: Priority Lanes (Urgent requests jump the line)
-      // If priorities match, it falls back to timestamp (FIFO) to maintain action order.
-      const sortedQueue = pending.sort((a, b) => {
-        if (a.priority === 'urgent' && b.priority !== 'urgent') return -1;
-        if (a.priority !== 'urgent' && b.priority === 'urgent') return 1;
-        return a.timestamp - b.timestamp;
-      });
-
-      for (const request of sortedQueue) {
-        await this.processRequest(request);
-      }
-      
-    } finally {
-      this.isSyncing = false;
-    }
-  }
-
-  /**
-   * Attempts to execute a single saved request.
-   */
-  private async processRequest(request: QueuedRequest): Promise<void> {
-    let reqToSync = request;
-
-    // MITIGATION 1: Just-in-Time Headers (Refresh Auth Tokens)
-    if (this.config.onBeforeSync) {
-      try {
-        reqToSync = await this.config.onBeforeSync(request);
-      } catch (error) {
-        console.error(`[Axiom] onBeforeSync failed for ${request.id}. Marking as failure.`);
-        await this.handleFailure(request); // FIX: Ensure we increment retry count if this fails
-        return; 
-      }
-    }
-
-    // Apply the global timeout to background syncing as well
-    const controller = new AbortController();
-    const timeoutMs = this.config.timeout || 10000; // Default 10s for background syncs
-    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-
-    try {
-      const response = await fetch(reqToSync.url, {
-        method: reqToSync.method,
-        headers: reqToSync.headers,
-        body: reqToSync.body,
-        signal: controller.signal
-      });
-
-      clearTimeout(timeoutId);
-
-      // If it's a success OR a permanent 400 error (like bad data), remove it.
-      if (response.ok || (response.status >= 400 && response.status < 500)) {
-        await this.storage.remove(reqToSync.id);
-        console.log(`[Axiom] Request ${reqToSync.id} synced successfully.`);
-      } else {
-        // It's a 500 Server Error. Treat as a failure and retry later.
-        await this.handleFailure(reqToSync);
-      }
-    } catch (error) {
-      clearTimeout(timeoutId);
-      // Network dropped again mid-sync or timeout was reached.
-      await this.handleFailure(reqToSync);
-    }
-  }
-
-  /**
-   * MITIGATION 2: The Dead Letter Queue logic
-   */
-  private async handleFailure(request: QueuedRequest): Promise<void> {
-    request.retryCount += 1;
-    const maxRetries = this.config.maxRetries ?? 3; // Use nullish coalescing so 0 is valid
-
-    if (request.retryCount >= maxRetries) {
-      console.warn(`[Axiom] Request ${request.id} failed ${maxRetries} times. Moving to Dead Letter.`);
-      await this.storage.remove(request.id);
-      
-      if (this.config.onDeadLetter) {
-        this.config.onDeadLetter(request, new Error('Max retries exceeded'));
-      }
-    } else {
-      // Save the updated retry count back to storage
-      await this.storage.save(request);
-    }
-  }
-}

package/src/index.ts

@@ -1,6 +0,0 @@
-export * from './types';
-export * from './adapters';
-export * from './adapters/memory';
-export { axiom, AxiomEngine } from './engine/fetcher';
-export { AxiomProvider } from './react/AxiomProvider';
-export { useAxiomQueue } from './react/useAxiomQueue';

package/src/react/AxiomProvider.tsx

@@ -1,57 +0,0 @@
-import React, { createContext, useContext, useEffect, useState } from 'react';
-import { axiom } from '../engine/fetcher';
-import { AxiomConfig } from '../types';
-import { AxiomStorageAdapter } from '../adapters';
-
-interface AxiomContextType {
-  isOnline: boolean;
-  forceSync: () => Promise<void>;
-}
-
-// Create a safe default context
-const AxiomContext = createContext<AxiomContextType>({
-  isOnline: true,
-  forceSync: async () => {},
-});
-
-export const AxiomProvider: React.FC<{
-  config: AxiomConfig;
-  storageAdapter?: AxiomStorageAdapter;
-  /** * A function that takes a callback, calls it whenever network state changes, 
-   * and returns an unsubscribe function.
-   */
-  networkListener: (callback: (isOnline: boolean) => void) => any;
-  children: React.ReactNode;
-}> = ({ config, storageAdapter, networkListener, children }) => {
-  const [isOnline, setIsOnline] = useState(true);
-
-  useEffect(() => {
-    // 1. Boot up the Axiom engine
-    axiom.create(config, storageAdapter);
-
-    // 2. Attach the OS-level network listener
-    const unsubscribe = networkListener((onlineStatus) => {
-      setIsOnline(onlineStatus);
-      
-      // 3. The Magic: If the internet comes back, automatically flush the queue
-      if (onlineStatus) {
-        axiom.forceSync();
-      }
-    });
-
-    // Cleanup listener on unmount
-    return () => {
-      if (typeof unsubscribe === 'function') {
-        unsubscribe();
-      }
-    };
-  }, [config, storageAdapter, networkListener]);
-
-  return (
-    <AxiomContext.Provider value={{ isOnline, forceSync: () => axiom.forceSync() }}>
-      {children}
-    </AxiomContext.Provider>
-  );
-};
-
-export const useAxiomContext = () => useContext(AxiomContext);

package/src/react/useAxiomQueue.ts

@@ -1,12 +0,0 @@
-import { useAxiomContext } from './AxiomProvider';
-
-export function useAxiomQueue() {
-  const { isOnline, forceSync } = useAxiomContext();
-
-  return {
-    /** Boolean indicating if the device currently has an active connection */
-    isOnline,
-    /** Manually trigger the background sync manager */
-    forceSync,
-  };
-}

package/src/types.ts

@@ -1,45 +0,0 @@
-/** * Defines how the request should be treated when the queue flushes. 
- * Urgent requests bypass the background queue entirely if the network is active.
- */
-export type RequestPriority = 'urgent' | 'background';
-
-/** * Represents a serialized HTTP request frozen in offline storage. 
- */
-export interface QueuedRequest {
-  id: string;
-  timestamp: number;
-  url: string;
-  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-  headers: Record<string, string>;
-  body?: string; 
-  priority: RequestPriority;
-  retryCount: number;
-}
-
-/** * Global configuration for the Axiom engine initialized on startup. 
- */
-export interface AxiomConfig {
-  /** The base URL prepended to all request paths. */
-  baseURL?: string;
-  /** Global headers applied to every request (e.g., Auth tokens). */
-  defaultHeaders?: Record<string, string>;
-  /** The maximum number of times a queued request will attempt to sync before failing permanently. */
-  maxRetries?: number;
-  /** Global timeout in milliseconds before a request is aborted and queued. */
-  timeout?: number;
-  /** Middleware hook triggered immediately before a queued request is synced. Ideal for refreshing Auth tokens. */
-  onBeforeSync?: (request: QueuedRequest) => Promise<QueuedRequest>;
-  /** Callback triggered when a request exceeds maxRetries and is permanently removed from the queue. */
-  onDeadLetter?: (request: QueuedRequest, error: Error) => void;
-}
-
-/** * Per-request configuration options that override the global configuration. 
- */
-export interface AxiomRequestOptions {
-  /** Overrides the queue sorting behavior for this specific request. */
-  priority?: RequestPriority;
-  /** Overrides the global timeout limit for this specific request. */
-  timeout?: number;
-  /** Specific headers to append to this single request (e.g., custom Content-Type). */
-  headers?: Record<string, string>;
-}

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "jsx": "react-jsx",
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "declaration": true,
-    "ignoreDeprecations": "6.0"
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "tests"]
-}