@taphubhq/sdk-core 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TabHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @taphubhq/sdk-core
+
+Framework-agnostic TypeScript SDK for the TabHub platform.
+
+## Install
+
+```sh
+pnpm add @taphubhq/sdk-core
+```
+
+## Minimum Integration
+
+```ts
+import { TaphubClient } from '@taphubhq/sdk-core';
+
+const client = new TaphubClient({
+  agencyId: 'acme-corp',
+  // Shared API base. The SDK derives:
+  //   - grid-api    → ${endpoint}/grid-api/grid-gql
+  //   - user-service → ${endpoint}/taphub-user-service/th-user-gql
+  endpoint: 'https://builder.taptrading.net/api',
+});
+
+// Session-token login via user-service GraphQL (preferred).
+await client.auth.loginWithSession(upstreamSessionToken);
+
+const me = await client.user.me();
+```
+
+### Login methods
+
+| Method                          | Transport          | Status      |
+|---------------------------------|--------------------|-------------|
+| `loginWithSession(sessionToken)` | user-service GraphQL | **Preferred** |
+| `createDemoUser(username?)`     | grid-api GraphQL    | Active        |
+| `loginWithGoogle(idToken)`      | grid-api REST       | `@deprecated` |
+| `demoLogin(username?)`          | grid-api REST       | `@deprecated` |
+
+REST-backed methods continue to work until the gateway retires the routes in a follow-up change.
+
+## Error Handling
+
+All SDK failures throw a subclass of `TaphubError`. Use `instanceof` to discriminate.
+
+```ts
+import {
+  TaphubError,
+  TaphubAuthError,
+  TaphubNetworkError,
+  TaphubValidationError,
+  TaphubServerError,
+  TaphubSlippageError,
+} from '@taphubhq/sdk-core';
+
+try {
+  await client.bid.placeBid(input);
+} catch (e) {
+  if (e instanceof TaphubSlippageError) {
+    showSlippageBanner(e.clientCoef, e.serverCoef, e.slippage);
+  } else if (e instanceof TaphubAuthError) {
+    redirectToLogin();
+  } else if (e instanceof TaphubValidationError) {
+    showFieldError(e.code);
+  } else if (e instanceof TaphubNetworkError) {
+    showOfflineBanner();
+  }
+}
+```
+
+### Wire error code → SDK error class
+
+The GraphQL transport classifies errors by the first entry's `extensions.code` at HTTP 200 with `errors[]` (the GraphQL convention used by grid-api).
+
+| Wire `extensions.code`                                    | SDK class                | Typed fields                          |
+|-----------------------------------------------------------|--------------------------|---------------------------------------|
+| `Unauthorized`, `TokenExpired`, `NotAuthenticated`        | `TaphubAuthError`        | `code`                                |
+| `Bid_CoefficientMismatch` (with valid `meta.{clientCoef,serverCoef,slippage}`) | `TaphubSlippageError`    | `code`, `clientCoef`, `serverCoef`, `slippage`    |
+| Any other code                                            | `TaphubValidationError`  | `code`                                |
+| HTTP 5xx (any code)                                       | `TaphubServerError`      | `code`                                |
+| Fetch failure / `AbortSignal` cancellation                | `TaphubNetworkError`     | `code` (`NetworkUnreachable` / `Aborted`) |
+
+`TaphubSlippageError extends TaphubValidationError`, so existing `instanceof TaphubValidationError` catch blocks keep working. Place the `TaphubSlippageError` check first when both branches exist.
+
+### Slippage error fallback
+
+`TaphubSlippageError` is only thrown when `extensions.meta.clientCoef`, `extensions.meta.serverCoef`, and `extensions.meta.slippage` are all finite numbers. The `slippage` field is the client-submitted tolerance percent (e.g. `5` for 5%). If `meta` is missing or malformed, the SDK falls back to a generic `TaphubValidationError` with `code === 'Bid_CoefficientMismatch'`. Consumers SHOULD treat the generic fallback as the same user-facing rejection but without typed coefficient access.
+
+## Network quality
+
+The client exposes a passive network-quality monitor at `client.network`. It samples real GraphQL, REST, and MQTT traffic that the app produces and reports a smoothed quality signal.
+
+```ts
+import type { NetworkQuality } from '@taphubhq/sdk-core';
+
+const current: NetworkQuality = client.network.getCurrent();
+// → { network: 'good' | 'fair' | 'poor' | 'offline',
+//     backend: 'ok' | 'degraded' | 'down',
+//     rtt, jitter, lossRate, mqttConnected, samplesInWindow, lastUpdated }
+
+const off = client.network.subscribe(({ previous, current }) => {
+  if (current.network !== previous.network) showBanner(current.network);
+});
+// later: off();
+
+client.network.reset(); // clears window state, e.g. on sign-in
+```
+
+`network` and `backend` are independent signals. HTTP 5xx and GraphQL `errors[]` populate `backend` (`degraded` / `down`) without polluting `network`, so the UI can distinguish a weak user connection from a backend incident.
+
+The monitor is always present, even when `mqttEndpoint` is not configured. In SSR / Node environments where `navigator` is undefined, construction does not throw — only the browser fallback paths are skipped.
+
+### Caveats
+
+- Connection samples from `navigator.connection` are used only as a cold-start fallback; once 3 real samples accumulate they no longer contribute to the EMA.
+- MQTT QoS1 `puback` timing is not yet plumbed; v1 derives MQTT signal from `connect` / `reconnect` / `disconnect` events only.
+
+## License
+
+MIT