@sometic/http

Fetch-first HTTP client with interceptors, retry, dedupe, and optional auth refresh for Sometic.

createHttp wraps fetch with a typed client (get / post / put / patch / delete), request/response/error interceptors, retry helpers, safe URL joining, and optional response size limits. It is designed for browser and SSR environments that already have fetch, not as an Axios reimplementation with a custom XHR stack.

Why it exists: portable apps need one HTTP layer that can attach auth headers, single-flight refresh on 401, and replay the original request after session epoch checks. That logic lives in @sometic/http/auth (createAuthInterceptor) and cooperates with @sometic/auth without forcing auth as a hard dependency.

Standout features include interceptor composition, createMockFetcher for tests, retry utilities (computeRetryDelay, shouldRetryDefault), URL safety (assertSafeRequestUrl), and policy interceptors under @sometic/http/auth. Pair with @sometic/query via createHttpQueryFn for cached server state.

Ecosystem: depends on @sometic/core; optional peer @sometic/auth; composed by @sometic/app-shell. Docs: introduction and HTTP utilities.

Install

pnpm add @sometic/http

npm install @sometic/http

yarn add @sometic/http

Optional auth refresh:

pnpm add @sometic/auth

Usage

Create a client and call JSON APIs:

import { createHttp } from "@sometic/http";

const http = createHttp({
    baseUrl: "https://api.example.com",
    headers: { Accept: "application/json" },
});

const { data } = await http.get<{ id: string }>("/users/me");
await http.post("/items", JSON.stringify({ title: "Notebook" }), {
    headers: { "Content-Type": "application/json" },
});

Attach auth refresh via the auth interceptor:

import { createHttp } from "@sometic/http";
import { createAuthInterceptor } from "@sometic/http/auth";
import type { AuthController } from "@sometic/auth";

function createAuthedHttp(auth: AuthController) {
    return createHttp({
        baseUrl: "https://api.example.com",
        interceptors: [createAuthInterceptor({ auth })],
    });
}

CDN

Docs: https://sometic.dev/utilities/http.

Simple script

<script src="https://cdn.jsdelivr.net/npm/@sometic/[email protected]/dist/cdn/sometic-http.iife.js"></script>
<script>
    const http = SometicHttp.createHttp({ baseUrl: "/api" });
    http.get("/me").then((me) => {
        console.log(me);
    });
</script>

Module script

<script type="module">
    import { createHttp } from "https://cdn.jsdelivr.net/npm/@sometic/[email protected]/dist/cdn/sometic-http.esm.js";

    const http = createHttp({ baseUrl: "/api" });
    const me = await http.get("/me");
</script>

Peers / when not to use

Optional peer: @sometic/auth (for @sometic/http/auth). Depends on @sometic/core.

Prefer the platform fetch alone for one-off calls with no interceptors/retry. Prefer TanStack Query / SWR only as cache layers; you can still use this client underneath via @sometic/query. Do not treat this package as a GraphQL client.

Docs

• Introduction
• HTTP utilities
• HTTP package
• Authentication / token refresh
• App shell

License

MIT