Client API

Spoosh Class

The primary way to create a Spoosh instance with full plugin support. Use this with @spoosh/angular injection functions.

import { Spoosh } from "@spoosh/core";
import { cachePlugin } from "@spoosh/plugin-cache";
import { invalidationPlugin } from "@spoosh/plugin-invalidation";

const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
  invalidationPlugin(),
]);

Constructor Parameters

Parameter	Type	Required	Description
`baseUrl`	`string`	Yes	Base URL for all API requests
`defaultOptions`	`SpooshOptionsInput`	No	Default options (headers, credentials, transport, etc.)

Type Parameters

new Spoosh<TSchema, TError>(baseUrl, defaultOptions);

Parameter	Description
`TSchema`	Your API schema type
`TError`	Default error type (e.g., `Error`)

Adding Plugins

Use the .use() method to add plugins:

const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
  invalidationPlugin(),
  retryPlugin({ retries: 3 }),
]);

With Angular

src/api/client.ts

import { Spoosh } from "@spoosh/core";
import { create } from "@spoosh/angular";
import { cachePlugin } from "@spoosh/plugin-cache";
import { invalidationPlugin } from "@spoosh/plugin-invalidation";
import type { ApiSchema } from "./schema";

const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
  cachePlugin({ staleTime: 5000 }),
  invalidationPlugin(),
]);

export const { injectRead, injectWrite, injectPages, injectQueue } =
  create(spoosh);

Request Options

All API calls accept optional request configuration:

const { data } = await api("users").GET({
  query: { page: 1, limit: 10 },
  headers: { Authorization: "Bearer token" },
});

Option	Description
`query`	Query parameters
`body`	Request body (POST, PUT, PATCH). Use `form()` / `json()` / `urlencoded()` wrappers for explicit serialization.
`params`	Path parameters
`headers`	Additional headers

Per-Request Headers

const { data } = await api("users").GET({
  headers: {
    Authorization: `Bearer ${token}`,
    "X-Custom-Header": "value",
  },
});

Default Options

const spoosh = new Spoosh<ApiSchema, Error>("/api", {
  credentials: "include",
  headers: {
    "Content-Type": "application/json",
  },
}).use([cachePlugin(), invalidationPlugin()]);

You can set transport: "xhr" to use XMLHttpRequest instead of the Fetch API. When using XHR transport, TypeScript narrows the available options to only XHR-compatible fields.

const spoosh = new Spoosh<ApiSchema, Error>("/api", {
  transport: "xhr",
  credentials: "include",
}).use([cachePlugin(), invalidationPlugin()]);

createClient

A lightweight client without plugin support. Use this for server-side data fetching or simple scripts.

import { createClient } from "@spoosh/core";

const api = createClient<ApiSchema>(process.env.API_URL!);

const { data } = await api("users").GET();

Parameters

Parameter	Type	Required	Description
`baseUrl`	`string`	Yes	Base URL for all API requests
`defaultOptions`	`SpooshOptionsInput`	No	Default options (headers, credentials, transport, etc.)

With Custom Options

const api = createClient<ApiSchema>(process.env.API_URL!, {
  headers: { Authorization: "Bearer token" },
  credentials: "include",
});

On this page