# `@orderlyshop/core-client`

TypeScript client for the Orderly core gRPC API.

The package is generated from the protobuf contracts in `../../../../interface` and supports:

- binary gRPC in Node.js
- gRPC-web in browsers
- API key, bearer token, and browser cookie-backed authentication flows
- memory-only token storage by default
- non-secret browser identity hints in localStorage

## Install

```sh
npm install @orderlyshop/core-client
```

## Browser gRPC-web

```ts
import { createOrderlyWebClient } from "@orderlyshop/core-client/web";

const orderly = createOrderlyWebClient({
  baseUrl: "https://api.orderly.example"
});

await orderly.auth.authenticateWithSmsChallenge({
  phoneNumber: { CountryCode: "45", Number: "12345678" },
  code: "123456"
});

const login = await orderly.getCurrentLogin();
```

Browser clients use `credentials: "include"` by default. If the backend sets an `HttpOnly; Secure; SameSite=None; Partitioned` cookie in a gRPC-web auth response, the browser can persist the server session without exposing the cookie to JavaScript. The client library does not read or manage that cookie.

The cookie value should be an opaque server-side session key, not an OAuth token. A recommended server cookie shape is:

```http
Set-Cookie: __Host-Http-orderly_session=<opaque-session-id>; Path=/; Secure; HttpOnly; SameSite=None; Partitioned; Max-Age=...
```

CHIPS cookie persistence depends on browser support. Recent Chrome, Edge, Firefox, and iOS Safari 26.2+ have strong support, but older browsers may fall back to page-lifetime bearer auth unless the application provides its own `TokenStore`.

## Node binary gRPC

```ts
import { createOrderlyNodeClient } from "@orderlyshop/core-client/node";

const orderly = createOrderlyNodeClient({
  baseUrl: "https://api.orderly.example",
  auth: { type: "apiKey", apiKey: process.env.ORDERLY_API_KEY! }
});

const login = await orderly.getCurrentLogin();
```

## Authentication Storage

The default `TokenStore` is memory-only. It does not persist access tokens, refresh tokens, API keys, or full OAuth responses to Web Storage, IndexedDB, cookies, files, or logs.

You can provide a custom token store when you intentionally accept the persistence tradeoff:

```ts
import type { TokenStore } from "@orderlyshop/core-client";

const tokenStore: TokenStore = {
  get: async () => undefined,
  set: async (token) => {
    // Store only in an application-owned secure location.
  },
  clear: async () => {}
};
```

Browser identity hints are separate from authentication. The default browser identity store may cache only:

- `userId`
- `displayName`
- `updatedAt`

This cache is for UI only. It must not be used as proof of authentication; call `getCurrentLogin()` or another protected RPC to verify the server session.

`clearAuth()` clears the configured token store and identity store. It cannot clear server-managed `HttpOnly` cookies from JavaScript; use a server-side logout endpoint or RPC when that feature is available.

## Updating Protobuf Contracts

Regenerate generated TypeScript and bump the package minor version:

```sh
npm run update:proto
```

Preview the update without mutating package metadata:

```sh
npm run update:proto -- --dry-run
```

For breaking contract releases:

```sh
npm run update:proto -- --major
```
