🪐 orbit-http

A lightweight, Axios-like HTTP client purpose-built for the TitanPL Gravity Runtime.

Orbit-http brings the developer experience you already know and love from ecosystem giants like Axios, but relies entirely on TitanPL's native fetch API. It acts perfectly synchronized with Titan's highly-optimized async orchestration (the drift() boundary engine).

Zero callbacks. Zero async/await noise. Just clean code.

npm install orbit-http @titanpl/native @titanpl/node

Requirements: Your Titan project must have @titanpl/node/globals active in your build.

🔥 Features at a Glance

• Titan-Native: Preserves the __SUSPEND__ signaling mechanism used by Titan's execution engine boundary, making background tasks run properly.
• Axios Ergonomics: Exact same feel. Define instance configs, request methods (.get, .post), and interceptors.
• Auto-JSON Serialization: Objects in the data body are automatically serialized, and the correct Content-Type is set.
• Auto-JSON Parsing: Securely detects application/json responses from the Headers dictionary and deserializes .data for you seamlessly.
• Query Parameters: Easily append to URLs with a clean .params object.
• Automatic Retries: Ships with an exponential backoff engine under the hood, utilizing Titan's native t.time.sleep() algorithm when dealing with 5xx servers or network drops.
• Full TypeScript Support: Shipped with complete JSDoc .d.ts types to give your IDE powerful intellisense!

⚡ Quick Start

import "@titanpl/node/globals"; // Required for runtime polyfills
import { log } from "@titanpl/native";
import http from "orbit-http";

const res = http.get("https://jsonplaceholder.typicode.com/users/1");

log("Profile Name:", res.data.name);      // JSON is already unwrapped
log("Status Code:", res.status);          // 200
log("Headers map:", res.headers);         // Plain JS dictionary, all lowercased

🏗️ Managing Instances

Don't repeat yourself. Use http.create() to generate standard instances across your action endpoints:

import "@titanpl/node/globals";
import http from "orbit-http";

const github = http.create({
  baseURL: "https://api.github.com",
  headers: {
    "User-Agent": "orbit-titan",
    "Accept": "application/vnd.github.v3+json"
  },
  timeout: 5000 // In milliseconds
});

export function fetchActivity() {
  const pullRequests = github.get("/repos/titan-dev/orbit/pulls", {
    params: { state: "open", per_page: 5 }
  });
  
  return pullRequests.data;
}

📡 Request Methods

Orbit supports all modern methods. Every method produces a standardized response object.

// HTTP GET
http.get(url, config?);

// HTTP POST
http.post(url, data?, config?);

// HTTP PUT / PATCH
http.put(url, data?, config?);
http.patch(url, data?, config?);

// HTTP DELETE
http.delete(url, config?);

// OR LOW LEVEL
http.request({
    method: "POST",
    url: "/logs",
    baseURL: "...",
    data: { error: true }
});

Response Object Signature:

When data returns, Orbit guarantees this standard structure.

{
  data: any | string,         // Parsed Javascript object OR plain text based on content-type
  status: number,             // E.g. 200, 404, 500
  headers: Record<string, string>, // All header keys are guaranteed to be lowercase
  ok: boolean                 // True if status is 200-299 range
}

🛡️ Automatic Retries

Network unreliability is real. Let Orbit do the backoff for you using Titan's native thread-blocking delay t.time.sleep(ms).

orbitApi.get("/flaky/server", {
    retry: 3 
});

How does retrying work?

• If the network fails entirely, or if a 5xx HTTP Response (500, 502, 503...) is returned, it waits and tries again.
• It will NOT retry client errors like 404 Not Found or 401 Unauthorized to save cycles.
• It utilizes an exponential backoff timing map (e.g. 1s -> 2s -> 4s), capping at a maximum block duration of 10,000ms.

🛠️ Interceptors

Take total control over requests before they are sent and responses before your apps read them.

Request Interceptors

Automatically attach dynamic tokens or signature headers across the board:

const api = http.create({ baseURL: "https://api.my-app.com" });

api.interceptors.request.use((config) => {
    // Modify config right before the network layer uses it
    config.headers["X-Trace-Id"] = t.crypto.uuid();
    config.headers.Authorization = `Bearer ${t.ls.get("auth_session")}`;
    
    return config;
});

Response Interceptors

Filter or unpack the exact shape you actually want:

// Automatically unwrap `.data` from all payload responses globally!
api.interceptors.response.use((res) => {
    return res.data;
});

// Now, your action logic gets extremely clean:
const usersList = api.get("/users"); // You get the array directly, not the `{ data, status }` container!

🧩 TypeScript / JSDoc Native

When you install orbit-http, you immediately get deep autocomplete inside IDEs. Your config options, default defaults, instance chaining tools, and data payload templates are fully strictly typed inside src/index.d.ts. No extra @types/orbit-http download required!

📄 License & Mission

Orbit-Http is a community package made for the Titan ecosystem. It is actively maintained to be under 300 source lines of code.

Available completely open-source under the MIT License.