npm package: @archlast/client
Description: Archlast client SDK for React and API access
Latest version: 0.1.3

# @archlast/client

The Archlast client SDK provides WebSocket-based queries and mutations, React
hooks with cache integration, authentication helpers, storage utilities, admin
APIs, and optional tRPC access.

## Installation

```bash
npm install @archlast/client

# Other package managers
pnpm add @archlast/client
yarn add @archlast/client
bun add @archlast/client
```

Peer dependencies:

```bash
npm install react react-dom @tanstack/react-query
```

## Quick start

```ts
import { ArchlastClient } from "@archlast/client";
import { ArchlastProvider, useQuery, useMutation } from "@archlast/client/react";
import { api } from "./_generated/api";

const client = new ArchlastClient(
  "ws://localhost:4000/ws",
  "http://localhost:4000",
  "web"
);

function App() {
  return (
    <ArchlastProvider client={client}>
      <TodoList />
    </ArchlastProvider>
  );
}

function TodoList() {
  const tasks = useQuery(api.tasks.list, {});
  const createTask = useMutation(api.tasks.create);

  return (
    <div>
      <pre>{JSON.stringify(tasks, null, 2)}</pre>
      <button onClick={() => createTask({ text: "New task" })}>
        Add
      </button>
    </div>
  );
}
```

The `api` object is generated by the CLI in `_generated/api.ts`.

## Client configuration

Constructor signature:

```ts
new ArchlastClient(wsUrl, httpUrl?, appId?, authUrl?, options?)
```

Options:
- `autoConnect` (default true)
- `apiKey` Better Auth API key (`arch_` prefix)
- `isAdmin` subscribe to admin streams
- `betterAuthCookies` for session cookies

```ts
const client = new ArchlastClient(
  "ws://localhost:4000/ws",
  "http://localhost:4000",
  "web",
  undefined,
  { apiKey: "arch_example" }
);

client.setApiKey("arch_new_key");
client.setBetterAuthCookies({ "better-auth.session": "..." });
```

## React hooks

Available from `@archlast/client/react`:

- `useQuery` / `useMutation` for live queries and mutations
- `usePagination` for cursor based queries
- `useAuth` for Better Auth session state
- `useUpload`, `useDownload` for storage
- `useStorageList`, `useStorageMetadata`, `useStorageDeleteFile`

Example:

```ts
const items = useQuery(api.items.list, { limit: 10 });
const createItem = useMutation(api.items.create);
```

## Direct client usage

```ts
const data = await client.fetch("tasks.get", { id: "123" });
const updated = await client.mutate("tasks.update", { id: "123", text: "Hi" });
```

## Authentication

Auth uses Better Auth endpoints under `/api/auth/*`.

```ts
import { useAuth } from "@archlast/client/react";

const { signIn, signOut, isAuthenticated } = useAuth();
```

Or use the auth client directly:

```ts
import { ArchlastAuthClient } from "@archlast/client/auth";

const auth = new ArchlastAuthClient({ baseUrl: "http://localhost:4000" });
```

## Storage

```ts
const file = new File(["hello"], "hello.txt", { type: "text/plain" });
const uploaded = await client.storage.upload(file);
const list = await client.storage.list();
const { url } = await client.storage.presign(uploaded.id);
```

## Admin APIs

```ts
const profile = await client.admin.auth.getProfile();
```

## tRPC integration

```ts
import { createArchlastTRPCClient } from "@archlast/client/trpc";
import type { AppRouter } from "./_generated/rpc";

const trpc = createArchlastTRPCClient<AppRouter>({
  baseUrl: "http://localhost:4000",
  apiKey: "arch_example"
});
```

## Subpath exports

- `@archlast/client/react`
- `@archlast/client/trpc`
- `@archlast/client/auth`
- `@archlast/client/storage`
- `@archlast/client/admin`

## Troubleshooting

- WebSocket errors: use `ws://<host>/ws` and confirm CORS settings.
- Auth errors: ensure cookies or API key are configured.
- Storage uploads: use `File` or `Blob` for browser uploads.

## Publishing (maintainers)

See `docs/npm-publishing.md` for release and publish steps.