@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

npm install @orderlyshop/core-client

Browser gRPC-web

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:

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

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:

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:

npm run update:proto

Preview the update without mutating package metadata:

npm run update:proto -- --dry-run

For breaking contract releases:

npm run update:proto -- --major