@orderlyshop/core-client 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# `@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
+```