# Masheev API client

`@masheev/client` provides typed tRPC clients and Better Auth integrations.
Developer tooling is beta. Confirm the installed version's exports and verify an
organization read before using it for provisioning.

## Choose an entry point

| Import                     | Exports / purpose                                       |
| -------------------------- | ------------------------------------------------------- |
| `@masheev/client`          | `apiClient`, `authClient` for direct calls              |
| `@masheev/client/react`    | Direct typed `apiClient` and React-capable `authClient` |
| `@masheev/client/server`   | `serverApi`, `createServerApiClients`                   |
| `@masheev/client/tanstack` | TanStack Start integration; not a Next.js adapter       |
| `@masheev/client/native`   | React Native client factory and authentication bridge   |
| `@masheev/client/types`    | Type-only imports                                       |

```bash
pnpm add @masheev/client
```

The `/react` API client is a direct tRPC client: use `.query()` and `.mutate()`.
It does not turn endpoint methods into `.useQuery()` or `.useMutation()` hooks.
Wrap direct calls with your application's query library when needed.

## Expo and React Native prerequisites

`@masheev/client/native` is an Expo / React Native entry point, not a Node entry
point. Use your application's supported Expo SDK and its matching React Native
version. Its authentication bridge uses Better Auth's Expo integration, which
requires the following optional peers when you import the native entry:

- `expo-constants` >=17, `expo-linking` >=7 and `expo-network` >=8.0.7.
- `expo-secure-store` >=12.5 and `expo-web-browser` >=14.
- React and React Native from your application's Expo SDK.

Install SDK-compatible module versions through Expo, rather than choosing
independent native library versions:

```bash
npx expo install expo-constants expo-linking expo-network expo-secure-store expo-web-browser
```

Pass your application's SecureStore adapter to `createNativeMasheevClient`.
These peers are optional for the web and server entries.
`@masheev/client/copilot/native` accepts injected storage, AppState and WebSocket
adapters and has no direct React Native or Expo runtime import.

## Server integrations: current limitation

The reviewed server factory accepts `baseURL`, `apiToken` and `apiKey`, but its
current implementation configures the auth client without forwarding the custom
URL or key into the tRPC transport. Do not rely on those options for backend
provisioning until your installed release passes a credential/origin test.
`apiClient` is not an export of `/server`.

For backend integration today, use the documented [REST authentication example](https://docs.masheev.com/authentication.md)
and exact operations from [OpenAPI](https://docs.masheev.com/openapi.json). The current org-key header is
`X-API-Key`, with explicit matching `orgId` and permitted actions. Do not substitute
Bearer auth for an organization key.

## Call a supported operation

A signed-in Masheev browser session can use the direct client:

```ts
import { apiClient } from "@masheev/client";

const { inboxes } = await apiClient.inboxes.list.query({ orgId });
```

This is not a way to authenticate your own customers to the management API.
Use [signed widget identity](https://docs.masheev.com/authentication.md#signed-widget-identity) for customer
conversations and your own backend for business operations.

## Discover exact schemas

Read [API reference](https://docs.masheev.com/api-reference.md) or download [openapi.json](https://docs.masheev.com/openapi.json).
Use the installed package's TypeScript declarations for tRPC method names.
Before a mutation, inspect the full required input and response shape. Inbox
creation, for example, requires channel-specific configuration in addition to a
name and channel; do not build requests from abbreviated examples.

List and reuse resources before creating them. Store the returned IDs with the
organization. After a timed-out create, reconcile with a read before retrying.
Do not assume all mutations support an idempotency header.

## Errors and retries

| Result             | Next action                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| 400 / BAD_REQUEST  | Check required fields and types in the current schema                     |
| 401 / UNAUTHORIZED | Check key header, credential expiry and selected auth method              |
| 403 / FORBIDDEN    | Check organization, action permissions, account approval and feature gate |
| 404 / NOT_FOUND    | Check the endpoint and resource ID within the same organization           |
| 409 / CONFLICT     | Read current state/version before retrying                                |
| 429                | Respect Retry-After when supplied; use bounded backoff for safe retries   |
| Timeout / 5xx      | Bound retries; reconcile mutations before another write                   |

## Supported scope

Only implemented, authorized operations are available. A listed schema is not an
availability guarantee. Generic durable outgoing webhooks and several connectors
are off; see [availability](https://docs.masheev.com/capabilities.md). Configure integrations through supported
APIs or the dashboard instead of inventing endpoint paths or copying legacy examples.