@jayethian/axiom 0.1.0

package/.editorconfig

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

package/.gitattributes

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

package/README.md

@@ -0,0 +1 @@
+# axiom

package/dist/index.d.mts

@@ -0,0 +1,102 @@
+import React from 'react';
+
+type RequestPriority = 'urgent' | 'background';
+interface QueuedRequest {
+    id: string;
+    timestamp: number;
+    url: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    headers: Record<string, string>;
+    body?: string;
+    priority: RequestPriority;
+    retryCount: number;
+}
+interface AxiomConfig {
+    baseURL?: string;
+    defaultHeaders?: Record<string, string>;
+    maxRetries?: number;
+    onBeforeSync?: (request: QueuedRequest) => Promise<QueuedRequest>;
+    onDeadLetter?: (request: QueuedRequest, error: Error) => void;
+}
+
+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>;
+}
+
+declare class MemoryStorageAdapter implements AxiomStorageAdapter {
+    private queue;
+    save(request: QueuedRequest): Promise<void>;
+    getAll(): Promise<QueuedRequest[]>;
+    remove(id: string): Promise<void>;
+    clearAll(): Promise<void>;
+}
+
+declare class AxiomEngine {
+    private config;
+    private storage;
+    private syncManager;
+    /**
+     * Initializes the Axiom engine with your specific rules and storage.
+     */
+    create(config: AxiomConfig, storageAdapter?: AxiomStorageAdapter): void;
+    forceSync(): Promise<void>;
+    /**
+     * Generates a unique ID for queued requests.
+     */
+    private generateId;
+    /**
+     * The core POST method.
+     */
+    post<T>(url: string, data?: any, options?: {
+        priority?: RequestPriority;
+    }): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /** The core GET method.
+     * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+     */
+    get<T>(url: string, options?: {
+        priority?: RequestPriority;
+    }): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /**
+     * Internal logic to fire the request or catch the network drop.
+     */
+    private attemptFetch;
+    /**
+     * Saves the request to whatever storage adapter was provided on startup.
+     */
+    private enqueueRequest;
+}
+declare const axiom: AxiomEngine;
+
+declare 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;
+}>;
+
+declare function useAxiomQueue(): {
+    /** Boolean indicating if the device currently has an active connection */
+    isOnline: boolean;
+    /** Manually trigger the background sync manager */
+    forceSync: () => Promise<void>;
+};
+
+export { type AxiomConfig, AxiomEngine, AxiomProvider, type AxiomStorageAdapter, MemoryStorageAdapter, type QueuedRequest, type RequestPriority, axiom, useAxiomQueue };

package/dist/index.d.ts

@@ -0,0 +1,102 @@
+import React from 'react';
+
+type RequestPriority = 'urgent' | 'background';
+interface QueuedRequest {
+    id: string;
+    timestamp: number;
+    url: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    headers: Record<string, string>;
+    body?: string;
+    priority: RequestPriority;
+    retryCount: number;
+}
+interface AxiomConfig {
+    baseURL?: string;
+    defaultHeaders?: Record<string, string>;
+    maxRetries?: number;
+    onBeforeSync?: (request: QueuedRequest) => Promise<QueuedRequest>;
+    onDeadLetter?: (request: QueuedRequest, error: Error) => void;
+}
+
+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>;
+}
+
+declare class MemoryStorageAdapter implements AxiomStorageAdapter {
+    private queue;
+    save(request: QueuedRequest): Promise<void>;
+    getAll(): Promise<QueuedRequest[]>;
+    remove(id: string): Promise<void>;
+    clearAll(): Promise<void>;
+}
+
+declare class AxiomEngine {
+    private config;
+    private storage;
+    private syncManager;
+    /**
+     * Initializes the Axiom engine with your specific rules and storage.
+     */
+    create(config: AxiomConfig, storageAdapter?: AxiomStorageAdapter): void;
+    forceSync(): Promise<void>;
+    /**
+     * Generates a unique ID for queued requests.
+     */
+    private generateId;
+    /**
+     * The core POST method.
+     */
+    post<T>(url: string, data?: any, options?: {
+        priority?: RequestPriority;
+    }): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /** The core GET method.
+     * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+     */
+    get<T>(url: string, options?: {
+        priority?: RequestPriority;
+    }): Promise<{
+        data?: T;
+        status: number;
+        isQueued: boolean;
+    }>;
+    /**
+     * Internal logic to fire the request or catch the network drop.
+     */
+    private attemptFetch;
+    /**
+     * Saves the request to whatever storage adapter was provided on startup.
+     */
+    private enqueueRequest;
+}
+declare const axiom: AxiomEngine;
+
+declare 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;
+}>;
+
+declare function useAxiomQueue(): {
+    /** Boolean indicating if the device currently has an active connection */
+    isOnline: boolean;
+    /** Manually trigger the background sync manager */
+    forceSync: () => Promise<void>;
+};
+
+export { type AxiomConfig, AxiomEngine, AxiomProvider, type AxiomStorageAdapter, MemoryStorageAdapter, type QueuedRequest, type RequestPriority, axiom, useAxiomQueue };

package/dist/index.js

@@ -0,0 +1,269 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AxiomEngine: () => AxiomEngine,
+  AxiomProvider: () => AxiomProvider,
+  MemoryStorageAdapter: () => MemoryStorageAdapter,
+  axiom: () => axiom,
+  useAxiomQueue: () => useAxiomQueue
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/adapters/memory.ts
+var MemoryStorageAdapter = class {
+  constructor() {
+    this.queue = /* @__PURE__ */ new Map();
+  }
+  async save(request) {
+    this.queue.set(request.id, request);
+  }
+  async getAll() {
+    return Array.from(this.queue.values()).sort((a, b) => a.timestamp - b.timestamp);
+  }
+  async remove(id) {
+    this.queue.delete(id);
+  }
+  async clearAll() {
+    this.queue.clear();
+  }
+};
+
+// src/engine/sync.ts
+var SyncManager = class {
+  constructor(storage, config) {
+    this.storage = storage;
+    this.config = config;
+    this.isSyncing = false;
+  }
+  /**
+   * The master trigger. Call this when the OS reports network is back online.
+   */
+  async flushQueue() {
+    if (this.isSyncing) return;
+    this.isSyncing = true;
+    try {
+      const pending = await this.storage.getAll();
+      if (pending.length === 0) {
+        this.isSyncing = false;
+        return;
+      }
+      console.log(`[Axiom] Network restored. Syncing ${pending.length} queued requests...`);
+      for (const request of pending) {
+        await this.processRequest(request);
+      }
+    } finally {
+      this.isSyncing = false;
+    }
+  }
+  /**
+   * Attempts to execute a single saved request.
+   */
+  async processRequest(request) {
+    let reqToSync = request;
+    if (this.config.onBeforeSync) {
+      try {
+        reqToSync = await this.config.onBeforeSync(request);
+      } catch (error) {
+        console.error(`[Axiom] onBeforeSync failed for ${request.id}. Skipping.`);
+        return;
+      }
+    }
+    try {
+      const response = await fetch(reqToSync.url, {
+        method: reqToSync.method,
+        headers: reqToSync.headers,
+        body: reqToSync.body
+      });
+      if (response.ok || response.status >= 400 && response.status < 500) {
+        await this.storage.remove(reqToSync.id);
+        console.log(`[Axiom] Request ${reqToSync.id} synced successfully.`);
+      } else {
+        await this.handleFailure(reqToSync);
+      }
+    } catch (error) {
+      await this.handleFailure(reqToSync);
+    }
+  }
+  /**
+   * MITIGATION 2: The Dead Letter Queue logic
+   */
+  async handleFailure(request) {
+    request.retryCount += 1;
+    const maxRetries = this.config.maxRetries || 3;
+    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 {
+      await this.storage.save(request);
+    }
+  }
+};
+
+// src/engine/fetcher.ts
+var AxiomEngine = class {
+  constructor() {
+    this.config = {};
+    this.storage = new MemoryStorageAdapter();
+  }
+  /**
+   * Initializes the Axiom engine with your specific rules and storage.
+   */
+  create(config, storageAdapter) {
+    this.config = config;
+    if (storageAdapter) {
+      this.storage = storageAdapter;
+    }
+    this.syncManager = new SyncManager(this.storage, this.config);
+  }
+  async forceSync() {
+    if (!this.syncManager) {
+      console.error("[Axiom] Engine not initialized. Call axiom.create() first.");
+      return;
+    }
+    await this.syncManager.flushQueue();
+  }
+  /**
+   * Generates a unique ID for queued requests.
+   */
+  generateId() {
+    return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
+  }
+  /**
+   * The core POST method. 
+   */
+  async post(url, data, options) {
+    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
+    const request = {
+      id: this.generateId(),
+      timestamp: Date.now(),
+      url: fullUrl,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.config.defaultHeaders || {}
+      },
+      body: data ? JSON.stringify(data) : void 0,
+      priority: options?.priority || "urgent",
+      retryCount: 0
+    };
+    return this.attemptFetch(request);
+  }
+  /** The core GET method.
+   * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+   */
+  async get(url, options) {
+    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
+    const request = {
+      id: this.generateId(),
+      timestamp: Date.now(),
+      url: fullUrl,
+      method: "GET",
+      headers: {
+        ...this.config.defaultHeaders || {}
+      },
+      priority: options?.priority || "urgent",
+      retryCount: 0
+    };
+    return this.attemptFetch(request);
+  }
+  /**
+   * Internal logic to fire the request or catch the network drop.
+   */
+  async attemptFetch(request) {
+    try {
+      const response = await fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: request.body
+      });
+      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) {
+      await this.enqueueRequest(request);
+      return { status: 202, isQueued: true };
+    }
+  }
+  /**
+   * Saves the request to whatever storage adapter was provided on startup.
+   */
+  async enqueueRequest(request) {
+    console.warn(`[Axiom] Network unreachable. Queuing request ${request.id}`);
+    await this.storage.save(request);
+  }
+};
+var axiom = new AxiomEngine();
+
+// src/react/AxiomProvider.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var AxiomContext = (0, import_react.createContext)({
+  isOnline: true,
+  forceSync: async () => {
+  }
+});
+var AxiomProvider = ({ config, storageAdapter, networkListener, children }) => {
+  const [isOnline, setIsOnline] = (0, import_react.useState)(true);
+  (0, import_react.useEffect)(() => {
+    axiom.create(config, storageAdapter);
+    const unsubscribe = networkListener((onlineStatus) => {
+      setIsOnline(onlineStatus);
+      if (onlineStatus) {
+        axiom.forceSync();
+      }
+    });
+    return () => {
+      if (typeof unsubscribe === "function") {
+        unsubscribe();
+      }
+    };
+  }, [config, storageAdapter, networkListener]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AxiomContext.Provider, { value: { isOnline, forceSync: () => axiom.forceSync() }, children });
+};
+var useAxiomContext = () => (0, import_react.useContext)(AxiomContext);
+
+// src/react/useAxiomQueue.ts
+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
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AxiomEngine,
+  AxiomProvider,
+  MemoryStorageAdapter,
+  axiom,
+  useAxiomQueue
+});

package/dist/index.mjs

@@ -0,0 +1,238 @@
+// src/adapters/memory.ts
+var MemoryStorageAdapter = class {
+  constructor() {
+    this.queue = /* @__PURE__ */ new Map();
+  }
+  async save(request) {
+    this.queue.set(request.id, request);
+  }
+  async getAll() {
+    return Array.from(this.queue.values()).sort((a, b) => a.timestamp - b.timestamp);
+  }
+  async remove(id) {
+    this.queue.delete(id);
+  }
+  async clearAll() {
+    this.queue.clear();
+  }
+};
+
+// src/engine/sync.ts
+var SyncManager = class {
+  constructor(storage, config) {
+    this.storage = storage;
+    this.config = config;
+    this.isSyncing = false;
+  }
+  /**
+   * The master trigger. Call this when the OS reports network is back online.
+   */
+  async flushQueue() {
+    if (this.isSyncing) return;
+    this.isSyncing = true;
+    try {
+      const pending = await this.storage.getAll();
+      if (pending.length === 0) {
+        this.isSyncing = false;
+        return;
+      }
+      console.log(`[Axiom] Network restored. Syncing ${pending.length} queued requests...`);
+      for (const request of pending) {
+        await this.processRequest(request);
+      }
+    } finally {
+      this.isSyncing = false;
+    }
+  }
+  /**
+   * Attempts to execute a single saved request.
+   */
+  async processRequest(request) {
+    let reqToSync = request;
+    if (this.config.onBeforeSync) {
+      try {
+        reqToSync = await this.config.onBeforeSync(request);
+      } catch (error) {
+        console.error(`[Axiom] onBeforeSync failed for ${request.id}. Skipping.`);
+        return;
+      }
+    }
+    try {
+      const response = await fetch(reqToSync.url, {
+        method: reqToSync.method,
+        headers: reqToSync.headers,
+        body: reqToSync.body
+      });
+      if (response.ok || response.status >= 400 && response.status < 500) {
+        await this.storage.remove(reqToSync.id);
+        console.log(`[Axiom] Request ${reqToSync.id} synced successfully.`);
+      } else {
+        await this.handleFailure(reqToSync);
+      }
+    } catch (error) {
+      await this.handleFailure(reqToSync);
+    }
+  }
+  /**
+   * MITIGATION 2: The Dead Letter Queue logic
+   */
+  async handleFailure(request) {
+    request.retryCount += 1;
+    const maxRetries = this.config.maxRetries || 3;
+    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 {
+      await this.storage.save(request);
+    }
+  }
+};
+
+// src/engine/fetcher.ts
+var AxiomEngine = class {
+  constructor() {
+    this.config = {};
+    this.storage = new MemoryStorageAdapter();
+  }
+  /**
+   * Initializes the Axiom engine with your specific rules and storage.
+   */
+  create(config, storageAdapter) {
+    this.config = config;
+    if (storageAdapter) {
+      this.storage = storageAdapter;
+    }
+    this.syncManager = new SyncManager(this.storage, this.config);
+  }
+  async forceSync() {
+    if (!this.syncManager) {
+      console.error("[Axiom] Engine not initialized. Call axiom.create() first.");
+      return;
+    }
+    await this.syncManager.flushQueue();
+  }
+  /**
+   * Generates a unique ID for queued requests.
+   */
+  generateId() {
+    return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
+  }
+  /**
+   * The core POST method. 
+   */
+  async post(url, data, options) {
+    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
+    const request = {
+      id: this.generateId(),
+      timestamp: Date.now(),
+      url: fullUrl,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.config.defaultHeaders || {}
+      },
+      body: data ? JSON.stringify(data) : void 0,
+      priority: options?.priority || "urgent",
+      retryCount: 0
+    };
+    return this.attemptFetch(request);
+  }
+  /** The core GET method.
+   * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+   */
+  async get(url, options) {
+    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
+    const request = {
+      id: this.generateId(),
+      timestamp: Date.now(),
+      url: fullUrl,
+      method: "GET",
+      headers: {
+        ...this.config.defaultHeaders || {}
+      },
+      priority: options?.priority || "urgent",
+      retryCount: 0
+    };
+    return this.attemptFetch(request);
+  }
+  /**
+   * Internal logic to fire the request or catch the network drop.
+   */
+  async attemptFetch(request) {
+    try {
+      const response = await fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: request.body
+      });
+      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) {
+      await this.enqueueRequest(request);
+      return { status: 202, isQueued: true };
+    }
+  }
+  /**
+   * Saves the request to whatever storage adapter was provided on startup.
+   */
+  async enqueueRequest(request) {
+    console.warn(`[Axiom] Network unreachable. Queuing request ${request.id}`);
+    await this.storage.save(request);
+  }
+};
+var axiom = new AxiomEngine();
+
+// src/react/AxiomProvider.tsx
+import { createContext, useContext, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+var AxiomContext = createContext({
+  isOnline: true,
+  forceSync: async () => {
+  }
+});
+var AxiomProvider = ({ config, storageAdapter, networkListener, children }) => {
+  const [isOnline, setIsOnline] = useState(true);
+  useEffect(() => {
+    axiom.create(config, storageAdapter);
+    const unsubscribe = networkListener((onlineStatus) => {
+      setIsOnline(onlineStatus);
+      if (onlineStatus) {
+        axiom.forceSync();
+      }
+    });
+    return () => {
+      if (typeof unsubscribe === "function") {
+        unsubscribe();
+      }
+    };
+  }, [config, storageAdapter, networkListener]);
+  return /* @__PURE__ */ jsx(AxiomContext.Provider, { value: { isOnline, forceSync: () => axiom.forceSync() }, children });
+};
+var useAxiomContext = () => useContext(AxiomContext);
+
+// src/react/useAxiomQueue.ts
+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
+  };
+}
+export {
+  AxiomEngine,
+  AxiomProvider,
+  MemoryStorageAdapter,
+  axiom,
+  useAxiomQueue
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@jayethian/axiom",
+  "version": "0.1.0",
+  "maintainers": [
+    "Jayetheus"
+  ],
+  "description": "A resilient, offline-first fetch wrapper",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Jayetheus",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "react": "^19.2.6",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0"
+  },
+  "packageManager": "yarn@4.12.0"
+}

package/src/adapters/index.ts

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,131 @@
+import { AxiomConfig, 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 your specific rules and storage.
+   */
+  public create(config: AxiomConfig, storageAdapter?: AxiomStorageAdapter): void {
+    this.config = config;
+    if (storageAdapter) {
+      this.storage = storageAdapter;
+    }
+
+    this.syncManager = new SyncManager(this.storage, this.config);
+  }
+
+  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 ID for queued requests.
+   */
+  private generateId(): string {
+    return Math.random().toString(36).substring(2, 15) + Date.now().toString(36);
+  }
+
+  /**
+   * The core POST method. 
+   */
+  public async post<T>(
+    url: string, 
+    data?: any, 
+    options?: { priority?: RequestPriority }
+  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
+    
+    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
+    
+    const request: QueuedRequest = {
+      id: this.generateId(),
+      timestamp: Date.now(),
+      url: fullUrl,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(this.config.defaultHeaders || {})
+      },
+      body: data ? JSON.stringify(data) : undefined,
+      priority: options?.priority || 'urgent',
+      retryCount: 0
+    };
+
+    return this.attemptFetch<T>(request);
+  }
+
+  /** The core GET method.
+   * Note: GET requests typically don't have a body, but we still want to queue them if offline.
+   */
+  public async get<T>(
+    url: string, 
+    options?: { priority?: RequestPriority }
+  ): Promise<{ data?: T; status: number; isQueued: boolean }> {
+    
+    const fullUrl = this.config.baseURL ? `${this.config.baseURL}${url}` : url;
+    
+    const request: QueuedRequest = {
+      id: this.generateId(),
+      timestamp: Date.now(),
+      url: fullUrl,
+      method: 'GET',
+      headers: {
+        ...(this.config.defaultHeaders || {})
+      },
+      priority: options?.priority || 'urgent',
+      retryCount: 0
+    };
+
+    return this.attemptFetch<T>(request);
+  }
+
+  /**
+   * Internal logic to fire the request or catch the network drop.
+   */
+  private async attemptFetch<T>(request: QueuedRequest): Promise<{ data?: T; status: number; isQueued: boolean }> {
+    try {
+      const response = await fetch(request.url, {
+        method: request.method,
+        headers: request.headers,
+        body: request.body
+      });
+
+      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) {
+      await this.enqueueRequest(request);
+
+      return { status: 202, isQueued: true };
+    }
+  }
+
+  /**
+   * Saves the request to whatever storage adapter was provided on startup.
+   */
+  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

@@ -0,0 +1,96 @@
+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.
+   */
+  public async flushQueue(): Promise<void> {
+    // Prevent overlapping syncs if the network toggles rapidly
+    if (this.isSyncing) return;
+    this.isSyncing = true;
+
+    try {
+      const pending = await this.storage.getAll();
+      
+      if (pending.length === 0) {
+        this.isSyncing = false;
+        return;
+      }
+
+      console.log(`[Axiom] Network restored. Syncing ${pending.length} queued requests...`);
+
+      // We process sequentially to maintain the order of user actions
+      for (const request of pending) {
+        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}. Skipping.`);
+        return; 
+      }
+    }
+
+    try {
+      const response = await fetch(reqToSync.url, {
+        method: reqToSync.method,
+        headers: reqToSync.headers,
+        body: reqToSync.body
+      });
+
+      // 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) {
+      // Network dropped again mid-sync.
+      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;
+
+    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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,57 @@
+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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,20 @@
+export type RequestPriority = 'urgent' | 'background';
+
+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;
+}
+
+export interface AxiomConfig {
+  baseURL?: string;
+  defaultHeaders?: Record<string, string>;
+  maxRetries?: number;
+  onBeforeSync?: (request: QueuedRequest) => Promise<QueuedRequest>;
+  onDeadLetter?: (request: QueuedRequest, error: Error) => void;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "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"]
+}