> ## Documentation Index
> Fetch the complete documentation index at: https://confect.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP

> Call your Confect functions over HTTP from any JavaScript runtime.

`HttpClient` is an [Effect service](https://effect.website/docs/requirements-management/services/) that wraps Convex's [`ConvexHttpClient`](https://docs.convex.dev/api/classes/browser.ConvexHttpClient). It provides `query`, `mutation`, and `action` methods that accept refs and automatically encode args and decode return values through the schemas defined in your function specs. It works in any JavaScript runtime that supports `fetch`.

## Setup

Create the `HttpClient` layer by passing your Convex deployment URL.

```ts theme={null}
import { HttpClient } from "@confect/js";
import * as Effect from "effect/Effect";

const HttpClientLive = HttpClient.layer("https://example-123.convex.cloud");
```

The layer can then be provided to any Effect that uses the `HttpClient` service.

## Calling functions

Use the `HttpClient` service inside `Effect.gen` to call your functions with refs, the same way you would with `@confect/react` hooks or `@confect/test`.

```ts theme={null}
import { HttpClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const program = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  const notes = yield* client.query(refs.public.notes.list);

  const noteId = yield* client.mutation(refs.public.notes.insert, {
    text: "Hello from the server",
  });

  const result = yield* client.action(refs.public.random.getNumber);
});
```

Each method returns an `Effect` that can fail with `HttpClientError` (wrapping transport-level errors) or `ParseResult.ParseError` (if schema encoding or decoding fails).

## Typed errors

When a ref's spec declares an `error` schema, the decoded error is added to the returned `Effect`'s error channel alongside `HttpClientError` and `ParseError`. See [Error Handling](/server/error-handling) for how to declare error schemas.

```ts theme={null}
import { HttpClient } from "@confect/js";
import * as Effect from "effect/Effect";

import refs from "./confect/_generated/refs";

const lookup = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  return yield* client.query(refs.public.notes.getOrFail, { noteId });
});
// Effect.Effect<Note, NoteNotFound | HttpClientError | ParseError, HttpClient.HttpClient>
```

Recover from a typed failure with `Effect.catchTag` (or any other `Effect` error combinator).

```ts theme={null}
lookup.pipe(
  Effect.catchTag("NoteNotFound", (error) =>
    Effect.succeed(`Note ${error.noteId} not found.`),
  ),
);
```

## Authentication

Set or clear the auth token before making authenticated requests.

```ts theme={null}
Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  yield* client.setAuth(token);

  const identity = yield* client.query(refs.public.auth.getIdentity);

  yield* client.clearAuth;
});
```

## Running programs

Provide the `HttpClient` layer when running your program.

```ts theme={null}
import { HttpClient } from "@confect/js";
import * as Console from "effect/Console";
import * as Effect from "effect/Effect";

const HttpClientLive = HttpClient.layer("https://example-123.convex.cloud");

const program = Effect.gen(function* () {
  const client = yield* HttpClient.HttpClient;

  const notes = yield* client.query(refs.public.notes.list);
  yield* Console.log(notes);
});

Effect.runPromise(program.pipe(Effect.provide(HttpClientLive)));
```

## Differences from `ConvexHttpClient`

| `ConvexHttpClient`                       | `HttpClient`                                                    |
| ---------------------------------------- | --------------------------------------------------------------- |
| Functions referenced via `api.module.fn` | Functions referenced via `refs`                                 |
| Args passed directly to Convex as-is     | Args are schema-encoded from `Type` to `Encoded` before sending |
| Return values received directly as-is    | Return values are schema-decoded from `Encoded` to `Type`       |
| Methods return `Promise`                 | Methods return `Effect` with typed errors                       |