@clientloop/client

The ClientLoop API client. A typed GQty client for the ClientLoop GraphQL API, plus thin helper functions and the shared validation schemas.

Installation

npm install @clientloop/client
# or
pnpm add @clientloop/client

react / react-dom are optional peer dependencies, required only when using the @clientloop/client/react entry point.

Versioning

This package follows semantic versioning. Depend on it with a caret range so you automatically pick up backward-compatible patch and minor releases, while breaking changes (a new major) require an explicit opt-in:

{
  "dependencies": {
    "@clientloop/client": "^1.0.0"
  }
}

pnpm add @clientloop/client writes a caret range by default. Note that a plain pnpm install honors the lockfile and won't move an already-resolved version; run pnpm update @clientloop/client to pull the newest release within the range.

Usage

Create a client, then query the API through it. The client is a GQty client — select the fields you want inside client.resolve and they are fetched for you:

import { createClient } from '@clientloop/client';

// Pass your API key — it is sent as an `Authorization: Bearer <apiKey>`
// header on every request.
const client = createClient({ apiKey: process.env.CLIENTLOOP_API_KEY });

const region = await client.resolve(({ query: { info } }) => info.region);

createClient(config?) accepts an optional config:

• url (optional) — the ClientLoop API endpoint. Defaults to the production API, so you usually don't need to set it.
• apiKey (optional) — sent as a Bearer token on every request.
• locale (optional) — sets the locale used for this package's validation messages.

React

The @clientloop/client/react entry wraps a client in GQty React hooks. Create the client and hooks once (at module scope), then use useQuery in your components — selected fields are fetched and the component re-renders when they arrive:

import { createClient } from '@clientloop/client';
import { createReactGqtyClient } from '@clientloop/client/react';

const { useQuery } = createReactGqtyClient(createClient());

export function Region() {
  const query = useQuery();
  const region = query.info.region;

  if (query.$state.isLoading) {
    return <p>Loading…</p>;
  }
  return <p>Region: {region}</p>;
}

react and react-dom must be installed (they are optional peer dependencies of this package).

Entry points

| Import | Contents | | --- | --- | | @clientloop/client | createClient, the Client type, and Locale. | | @clientloop/client/core | Helper functions (e.g. getInfo, getApplyConfiguration, applySessionCreate, contactCreateIdvSession), the generated schema types, and the shared validation schemas/validators (CommonSchema, safeValidateFirstError, isPoBoxOrPmbAddress, the apply input-schema factories, …). | | @clientloop/client/react | createReactGqtyClient and the ReactGqtyHooks type for using the client with React. |

Validation schemas

The /core entry exports the valibot schemas and validators used by ClientLoop's apply and checkout forms, so client-side form validation matches what the API enforces.

License

See the LICENSE file.