syzygy-services-rn 1.0.0 → 1.2.0

package/.eslintrc.json

@@ -0,0 +1,47 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module",
+    "ecmaFeatures": { "jsx": true }
+  },
+  "plugins": ["@typescript-eslint", "react", "react-hooks", "react-native", "import"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:react/recommended",
+    "plugin:react-hooks/recommended",
+    // Must always be last: disables ESLint formatting rules that would
+    // otherwise conflict with Prettier's output.
+    "eslint-config-prettier"
+  ],
+  "env": {
+    "es6": true,
+    "node": true,
+    "react-native/react-native": true
+  },
+  "settings": {
+    "react": { "version": "detect" }
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": [
+      "warn",
+      { "argsIgnorePattern": "^_", "varsIgnorePattern": "^_" }
+    ],
+    "@typescript-eslint/no-explicit-any": "warn",
+    "react/prop-types": "off",
+    "react/react-in-jsx-scope": "off",
+    "react-native/no-inline-styles": "warn",
+    "react-native/no-unused-styles": "warn",
+    "import/order": [
+      "warn",
+      {
+        "groups": ["builtin", "external", "internal", "parent", "sibling", "index"],
+        "alphabetize": { "order": "asc", "caseInsensitive": true },
+        "newlines-between": "always"
+      }
+    ]
+  },
+  "ignorePatterns": ["dist", "node_modules", "lib", "build"]
+}

package/.github/workflows/release.yml

@@ -21,10 +21,17 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
+      - name: Set up Node
+        uses: actions/setup-node@v4
         with:
           node-version: '24'
-          registry-url: 'https://registry.npmjs.org'
-          package-manager-cache: false
-      - run: npm ci
-      - run: npm publish --access=public --provenance
+      - name: Install dependencies
+        run: npm ci
+      - name: Lint
+        run: npm run lint
+      - name: Type check
+        run: npm run typecheck
+      - name: Test
+        run: npm test
+      - name: Publish to npm
+        run: npm publish --access=public --provenance

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 100,
+  "arrowParens": "always"
+}

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.2.0] - 2026-09-19
+
+### Fixed
+- `DeviceProvider`: concurrent `getDeviceId()` calls now share one UUID generation via single-flight Promise memoization
+
+### Changed
+- npm publish gated behind lint + typecheck + test in release.yml
+- `StorageProvider.set(value, key)` argument order documented — Foundation v1.2.0 TODO noted
+- Canonical backoff policy: 500ms base, 2.0× multiplier, full jitter, 8 000ms cap, max 3 retries
+- Foundation dependency updated to ^1.2.0
+
+## [1.1.0] - 2026-09-13
+
+### Added
+
+- DeviceServices: `NodeDeviceProvider` now uses storage key `"syzygy.device.uuid"` (was `"syzygy.device.id"`) — UUID is generated once and persisted via `StorageProvider`, never regenerated if already stored
+- Persistence: `InMemoryStorageProvider.get()` now throws `TypeError` with a descriptive message (key name, stored type, requested type) when the stored value's type does not match the key's declared type; type detection uses `defaultValue` as a runtime type hint
+- Networking: `FetchNetworkClient` accepts an optional `logger?: LoggerProtocol` — logs outgoing request (method, URL, safe headers, body size), successful response (status, elapsed ms, body size), and errors; `undefined` logger incurs zero overhead
+- Analytics: `ConsoleAnalyticsProvider` and `InMemoryAnalyticsProvider` now inject `sessionId` into every tracked event's `properties`; session ID resets on `reset()`
+- CrashReporting: `CrashReporter` interface and all implementations gain `leaveBreadcrumb(message, metadata?)` and `clearBreadcrumbs()`; `InMemoryCrashReporter` stores up to 20 breadcrumbs in a circular buffer and includes a snapshot in every `CrashRecord`
+- WebSocket: `onBinaryMessage(handler)` callback on `WebSocketProvider` interface and `InMemoryWebSocketProvider`, returning `Uint8Array` frames — aligns with Android `binaryMessages: Flow<ByteArray>` contract
+- WebSocket: `simulateBinaryMessage(data)` helper on `InMemoryWebSocketProvider` for test-time binary frame injection
+- WebSocket: binary stream tests covering `onBinaryMessage` delivery, unsubscribe, multi-handler fan-out, empty frames, and mixed text+binary ordering (Android parity)
+- Networking: injectable `backoffClock: BackoffClock` option on `FetchNetworkClient` so retry back-off timing is deterministic in tests without global `setTimeout` stubbing — mirrors Android injectable-clock pattern
+- Networking: deterministic retry backoff tests using injectable `backoffClock` (exact delay values, partial recovery, no-sleep on first attempt, no-sleep on 4xx)
+- Networking retry integration tests with injectable `backoffClock`/timer
+- Auth: real token-refresh flow wired to NetworkClient with auto-refresh on expired JWT
+- RemoteConfig: cache TTL (cacheTtlSeconds, default 3600) for NetworkRemoteConfigProvider
+- WebSocket binary send tests (ArrayBuffer, binary receive callback, mixed text+binary)
+- PushNotifications: JSDoc FCM/APNs integration guide and NotificationPayload factory helpers
+- PushNotifications: README section with FCM/APNs integration steps and factory helper examples
+- Contract compliance tests verifying every service implements its Foundation protocol
+- Networking: `FetchNetworkClient.dispose()` — marks the client as disposed; subsequent `execute()` calls throw `NetworkError` (code `unknown`); calling `dispose()` multiple times is a safe no-op
+- WebSocket: `dispose(): void` added to `WebSocketProvider` interface, `NativeWebSocketProvider`, and `InMemoryWebSocketProvider` — closes the connection, clears all registered handlers, and prevents further `connect()` / `send()` / `sendBinary()` calls (each throws `WebSocketError`); calling `dispose()` multiple times is a safe no-op
+- Added `canUseBiometric()` and `authenticateWithBiometric(reason)` stub methods to `JWTAuthProvider` — returns `false`/`AuthState.Unauthenticated` with doc comments explaining real platform wiring (react-native-biometrics)
+- Added `CONTRACT_TESTS.md` — canonical set of behaviour assertions every Services implementation must satisfy, organised by module
+
+### Changed
+
+- SleepFn renamed to BackoffClock for cross-platform naming consistency
+
+### Fixed
+
+- README version badge corrected to 1.1.0
+- README banner updated to match cross-repo standard
+
 ## [1.0.0] - 2026-09-12
 
 ### Added
@@ -20,4 +68,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CrashReporter interface and console crash logging stub
 - WebSocketProvider interface and native WebSocket implementation stub
 
+[Unreleased]: https://github.com/Syzygy-Hub/syzygy-services-rn/compare/1.2.0...HEAD
+[1.2.0]: https://github.com/Syzygy-Hub/syzygy-services-rn/compare/1.1.0...1.2.0
+[1.1.0]: https://github.com/Syzygy-Hub/syzygy-services-rn/compare/1.0.0...1.1.0
 [1.0.0]: https://github.com/Syzygy-Hub/syzygy-services-rn/releases/tag/1.0.0

package/CONTRACT_TESTS.md

@@ -0,0 +1,118 @@
+# Syzygy Services — Contract Tests Reference
+
+This document defines the canonical set of behaviour assertions every Syzygy Services
+implementation must satisfy. It serves as the source of truth for cross-platform contract
+compliance.
+
+## How to use this document
+
+Each section lists the minimum test cases required per module. Tests marked ✅ are already
+implemented in this repo's test suite; tests marked 🔲 are not yet implemented.
+
+---
+
+## Networking
+
+| Test | Status |
+|------|--------|
+| Successful GET request returns 200 body | ✅ |
+| Retries on 5xx responses up to maxRetries | ✅ |
+| Does NOT retry on 4xx responses | ✅ |
+| Retry delays use injected BackoffClock (not real sleep) | ✅ |
+| Recovers on Nth attempt after N-1 failures | ✅ |
+| Logger receives request method, URL, headers (Authorization stripped) | ✅ |
+| Logger receives response status, body size, elapsed time | ✅ |
+| dispose() cancels in-flight requests | ✅ |
+| dispose() is idempotent | ✅ |
+
+## Persistence
+
+| Test | Status |
+|------|--------|
+| Stores and retrieves a value by key | ✅ |
+| Returns undefined for missing key | ✅ |
+| Type mismatch throws descriptive error with key name, stored type, requested type | ✅ |
+| Secure storage stores and retrieves | ✅ |
+
+## Auth
+
+| Test | Status |
+|------|--------|
+| Initial state is unauthenticated | ✅ |
+| setToken() transitions to authenticated | ✅ |
+| clearTokens() transitions to unauthenticated | ✅ |
+| refresh() POSTs to refreshUrl, updates stored tokens | ✅ |
+| refresh() on expired JWT auto-refreshes before request | ✅ |
+| refresh() failure transitions to unauthenticated | ✅ |
+| canUseBiometric() returns false on stub | ✅ |
+| authenticateWithBiometric() returns unauthenticated on stub | ✅ |
+
+## FileManagement
+
+| Test | Status |
+|------|--------|
+| Writes and reads a file | ✅ |
+| Returns null for missing file | ✅ |
+| Deletes a file | ✅ |
+
+## PushNotifications
+
+| Test | Status |
+|------|--------|
+| Registers for notifications without throwing | ✅ |
+| createAlertNotification() creates correct payload | ✅ |
+| createSilentNotification() creates correct payload | ✅ |
+
+## DeviceServices
+
+| Test | Status |
+|------|--------|
+| deviceId() returns consistent UUID across calls | ✅ |
+| deviceId() is stored under key "syzygy.device.uuid" | ✅ |
+
+## RemoteConfig
+
+| Test | Status |
+|------|--------|
+| fetchConfig() returns values | ✅ |
+| Cache hit: second fetch within TTL does not call network | ✅ |
+| Cache miss: fetch after TTL calls network | ✅ |
+
+## Analytics
+
+| Test | Status |
+|------|--------|
+| track() records event | ✅ |
+| Session ID injected into every event | ✅ |
+| reset() regenerates session ID | ✅ |
+
+## CrashReporting
+
+| Test | Status |
+|------|--------|
+| recordCrash() records crash | ✅ |
+| leaveBreadcrumb() records breadcrumb | ✅ |
+| Breadcrumb buffer limited to 20 | ✅ |
+| clearBreadcrumbs() empties buffer | ✅ |
+| Breadcrumbs included in crash record | ✅ |
+
+## WebSocket
+
+| Test | Status |
+|------|--------|
+| Connects successfully | ✅ |
+| Sends and receives text messages | ✅ |
+| onBinaryMessage() callback accessible via interface type | ✅ |
+| simulateBinaryMessage() emits to binary callback | ✅ |
+| dispose() closes connection | ✅ |
+| dispose() is idempotent | ✅ |
+
+## Idempotency Tests
+
+| Module | Scenario | Status |
+|--------|----------|--------|
+| networking | `dispose()` called twice does not throw | ❌ (test not yet implemented) |
+| websocket | `disconnect()` called before `connect()` does not throw | ❌ (test not yet implemented) |
+| websocket | `disconnect()` called twice does not throw | ❌ (test not yet implemented) |
+| auth | `signOut()` called when already signed out does not throw | ❌ (test not yet implemented) |
+| persistence | `clear()` called on empty store does not throw | ❌ (test not yet implemented) |

package/README.md

@@ -1,12 +1,8 @@
-![CI](https://github.com/Syzygy-Hub/syzygy-services-rn/actions/workflows/ci.yml/badge.svg)
-![version](https://img.shields.io/badge/version-1.0.0-blue)
-![platform](https://img.shields.io/badge/platform-React%20Native%20%7C%20TypeScript-61DAFB)
-![license](https://img.shields.io/badge/license-MIT-green)
+[![React Native](https://img.shields.io/badge/React%20Native-TypeScript-61DAFB?style=flat)](https://reactnative.dev) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-3178C6?logo=typescript&logoColor=white&style=flat)](https://www.typescriptlang.org) [![CI](https://img.shields.io/github/actions/workflow/status/Syzygy-Hub/syzygy-services-rn/ci.yml?label=ci&style=flat)](https://github.com/Syzygy-Hub/syzygy-services-rn/actions/workflows/ci.yml) [![Version](https://img.shields.io/badge/version-1.2.0-D85A30?style=flat)](https://github.com/Syzygy-Hub/syzygy-services-rn/releases) [![License](https://img.shields.io/badge/License-MIT-green?style=flat)](LICENSE)
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Syzygy-Hub/.github/main/assets/syzygy-banner-dark.png">
-  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Syzygy-Hub/.github/main/assets/syzygy-banner-light.png">
-  <img alt="Syzygy Banner" src="https://raw.githubusercontent.com/Syzygy-Hub/.github/main/assets/syzygy-banner-light.png">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Syzygy-Hub/.github/main/brand/assets/banners/syzygy-banner-dark-1200.png">
+  <img src="https://raw.githubusercontent.com/Syzygy-Hub/.github/main/brand/assets/banners/syzygy-banner-light-1200.png" alt="Syzygy" width="600">
 </picture>
 
 # syzygy-services-rn
@@ -19,14 +15,14 @@ Concrete I/O service implementations for the Syzygy React Native ecosystem — n
 |--------|-----------|----------------|-------------|
 | `networking` | `NetworkClient` | `FetchNetworkClient` | HTTP GET/POST via global `fetch` |
 | `persistence` | `StorageProvider` | `InMemoryStorageProvider` | Key-value storage (swap with AsyncStorage) |
-| `auth` | `AuthProvider` | `JWTAuthProvider` | JWT token storage and refresh stub |
+| `auth` | `AuthProvider` | `JWTAuthProvider` | JWT token storage and refresh |
 | `filemanagement` | `FileProvider` | `NodeFileProvider` | File read/write/delete (swap with RNFS) |
-| `pushnotifications` | `PushProvider` | `InMemoryPushProvider` | Push token registration stub |
+| `pushnotifications` | `PushProvider` | `InMemoryPushProvider` | Push token registration |
 | `deviceservices` | `DeviceProvider` | `NodeDeviceProvider` | Hostname, platform, OS version |
-| `remoteconfig` | `RemoteConfigProvider` | `InMemoryRemoteConfigProvider` | In-memory remote config store |
-| `analytics` | `AnalyticsProvider` | `ConsoleAnalyticsProvider` | Console-based event logging stub |
-| `crashreporting` | `CrashReporter` | `ConsoleCrashReporter` | Console-based crash/error logging stub |
-| `websocket` | `WebSocketProvider` | `NativeWebSocketProvider` | Native WebSocket implementation stub |
+| `remoteconfig` | `RemoteConfigProvider` | `InMemoryRemoteConfigProvider`, `NetworkRemoteConfigProvider` | In-memory remote config store |
+| `analytics` | `ExtendedAnalyticsProvider` | `ConsoleAnalyticsProvider`, `InMemoryAnalyticsProvider` | Console-based event logging |
+| `crashreporting` | `CrashReporter` | `ConsoleCrashReporter`, `InMemoryCrashReporter` | Console-based crash/error logging |
+| `websocket` | `WebSocketProvider` | `NativeWebSocketProvider`, `InMemoryWebSocketProvider` | Native WebSocket implementation |
 
 ## Installation
 
@@ -42,7 +38,7 @@ npm install syzygy-services-rn
 
 ## Dependencies
 
-- `syzygy-foundation-rn` ^1.1.0
+- `syzygy-foundation-rn` ^1.2.0
 
 ## Ecosystem
 
@@ -53,6 +49,72 @@ npm install syzygy-services-rn
 | `syzygy-foundation-rn` | foundation | Primitives, utilities, base types |
 | `syzygy-services-rn` | services | I/O service interfaces and implementations |
 
+## Push Notifications
+
+`syzygy-services-rn` ships `InMemoryPushProvider` as a zero-dependency stub and documents the steps required to wire up a real FCM/APNs push layer.
+
+### FCM (Android + iOS via Firebase Cloud Messaging)
+
+1. Install `@react-native-firebase/app` and `@react-native-firebase/messaging`.
+2. Add `google-services.json` (Android) and `GoogleService-Info.plist` (iOS) to your project roots following the Firebase Console setup wizard.
+3. Request permission and register the token:
+   ```ts
+   import messaging from '@react-native-firebase/messaging';
+
+   const granted = await messaging().requestPermission();
+   if (granted) {
+     const token = await messaging().getToken();
+     pushProvider.registerToken(token);
+   }
+   ```
+4. Handle foreground messages:
+   ```ts
+   messaging().onMessage(async (remoteMessage) => {
+     const payload = createNotificationPayload(
+       remoteMessage.notification?.title ?? '',
+       remoteMessage.notification?.body ?? '',
+       remoteMessage.data ?? {},
+     );
+     pushProvider.simulateNotification(payload); // or forward to your UI
+   });
+   ```
+5. Handle background / quit-state messages with `messaging().setBackgroundMessageHandler()`.
+
+### APNs (iOS native push)
+
+1. Enable the **Push Notifications** capability in Xcode (Signing & Capabilities tab).
+2. Create an APNs Authentication Key (.p8) or APNs certificate in the Apple Developer portal and upload it to your backend or Firebase console.
+3. Retrieve the APNs device token:
+   ```ts
+   import { getAPNSToken } from '@react-native-firebase/messaging';
+   const apnsToken = await getAPNSToken();
+   ```
+4. Exchange the APNs token for an FCM token when using Firebase as the delivery layer.
+5. Handle incoming APNs notifications via `UNUserNotificationCenterDelegate` (native) or the Firebase `onMessage` / `onNotificationOpenedApp` callbacks.
+
+### Notification payload factory helpers
+
+```ts
+import {
+  createNotificationPayload,
+  createAlertNotification,
+  createMessageNotification,
+  createSilentNotification,
+} from 'syzygy-services-rn';
+
+// Generic payload
+const payload = createNotificationPayload('Title', 'Body', { key: 'value' });
+
+// Alert notification
+const alert = createAlertNotification('Alert', 'Something happened');
+
+// Chat message notification with deep-link thread id
+const msg = createMessageNotification('Alice', 'Hey!', 'thread-42');
+
+// Silent (data-only) push for background processing
+const silent = createSilentNotification({ action: 'sync' });
+```
+
 ## License
 
 MIT

package/dist/__tests__/ContractCompliance.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Contract compliance tests.
+ *
+ * Verifies that every concrete service class:
+ * 1. Can be instantiated without throwing.
+ * 2. Implements (structurally) the expected Foundation protocol.
+ * 3. Returns the expected type from its primary method.
+ *
+ * These tests are intentionally lightweight — they guard against accidental
+ * API breakage rather than testing behaviour (covered by the per-module suites).
+ */
+export {};
+//# sourceMappingURL=ContractCompliance.test.d.ts.map

package/dist/__tests__/ContractCompliance.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContractCompliance.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/ContractCompliance.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}