dhomie-app 0.0.1 → 0.0.4

package/README.md

@@ -1,63 +1,250 @@
-# MicroApp
+# dhomie-app
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.3.0.
+A self-contained Angular micro-app library that handles OIDC authentication (PKCE) and the DHomie feature set. It works in both a Capacitor native shell (iOS / Android) and a plain web shell.
 
-## Code scaffolding
+The library ships with OIDC credentials and API URLs **baked in** at publish time — no runtime configuration is required from the consumer.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+---
+
+## Table of Contents
+
+1. [Requirements](#1-requirements)
+2. [Installation](#2-installation)
+3. [Register the micro route in the shell app](#3-register-the-micro-route-in-the-shell-app)
+4. [Add the cold-start deep link handler (Capacitor only)](#4-add-the-cold-start-deep-link-handler-capacitor-only)
+5. [Register the custom URL scheme (Capacitor native only)](#5-register-the-custom-url-scheme-capacitor-native-only)
+6. [Making API requests inside micro components](#6-making-api-requests-inside-micro-components)
+7. [How authentication works](#7-how-authentication-works)
+8. [Baked-in configuration reference](#8-baked-in-configuration-reference)
+9. [Publishing a new version](#9-publishing-a-new-version)
+
+---
+
+## 1. Requirements
+
+| Peer dependency         | Version  |
+|-------------------------|----------|
+| `@angular/common`       | `^20.3.0` |
+| `@angular/core`         | `^20.3.0` |
+| `@angular/router`       | `^20.3.0` |
+| `@capacitor/app`        | `^7.0.0`  |
+| `@capacitor/browser`    | `^7.0.0`  |
+| `@capacitor/core`       | `^7.0.0`  |
+| `@capacitor/preferences`| `^7.0.0`  |
+| `@ionic/angular`        | `^8.0.0`  |
+| `angular-oauth2-oidc`   | `^20.0.0` |
+
+---
+
+## 2. Installation
 
 ```bash
-ng generate component component-name
+npm install dhomie-app
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+Then install all peer dependencies that your shell app does not already have:
 
 ```bash
-ng generate --help
+npm install @angular/common @angular/core @angular/router \
+  @capacitor/app @capacitor/browser @capacitor/core @capacitor/preferences \
+  @ionic/angular angular-oauth2-oidc
+```
+
+---
+
+## 3. Register the micro route in the shell app
+
+Add a lazy-loaded `micro` route that delegates to `MICRO_ROUTES`. The library self-registers all of its providers (HttpClient, OAuthService, storage, interceptors) inside a child `EnvironmentInjector` — no call to `provideMicroApp()` is needed in the shell.
+
+```ts
+// src/app/app.routes.ts
+import { Routes } from '@angular/router';
+import { MICRO_ROUTES } from 'dhomie-app';  // ← named export from the library
+
+export const routes: Routes = [
+  {
+    path: 'home',
+    loadComponent: () => import('./home/home.page').then((m) => m.HomePage),
+  },
+  {
+    path: 'micro',
+    loadChildren: () => import('dhomie-app').then((m) => m.MICRO_ROUTES),
+  },
+  {
+    path: '',
+    redirectTo: 'home',
+    pathMatch: 'full',
+  },
+];
+```
+
+That is all the routing setup you need. The library exposes these internal routes under `/micro`:
+
+| URL                 | Purpose                                      |
+|---------------------|----------------------------------------------|
+| `/micro`            | Redirects to `/micro/home`                   |
+| `/micro/home`       | Main micro-app view (guarded — login required) |
+| `/micro/callback`   | OAuth PKCE callback (no guard)               |
+
+---
+
+## 4. Add the cold-start deep link handler (Capacitor only)
+
+When the OS kills the app while the in-app browser is open (cold-start scenario), the guard's `appUrlOpen` listener is gone. The shell's `AppComponent` must register its own listener to catch the returning callback URL and navigate to `/micro/callback`.
+
+```ts
+// src/app/app.component.ts
+import { Component, inject, OnInit } from '@angular/core';
+import { Router } from '@angular/router';
+import { App } from '@capacitor/app';
+import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: 'app.component.html',
+  imports: [IonApp, IonRouterOutlet],
+})
+export class AppComponent implements OnInit {
+  private readonly router = inject(Router);
+
+  ngOnInit(): void {
+    App.addListener('appUrlOpen', (event) => {
+      // Only handle the DHomie custom scheme.
+      if (!event.url.startsWith('thehoodapp://')) {
+        return;
+      }
+
+      // Parse query params from the custom-scheme callback URL.
+      // e.g. com.thehood.app://micro/callback?code=abc&state=xyz
+      const callbackUrl = new URL(event.url);
+      const queryParams: Record<string, string> = {};
+      callbackUrl.searchParams.forEach((value, key) => {
+        queryParams[key] = value;
+      });
+
+      this.router.navigate(['/micro/callback'], { queryParams });
+    });
+  }
+}
 ```
 
-## Building
+> **Note on cold-start**: if the OS killed the app during the browser session, the PKCE `code_verifier` stored in RAM is lost. The callback component's error handler catches the failed token exchange and redirects to `/micro/home`, which restarts the login flow from scratch. This is the expected and accepted behavior for cold-start.
 
-To build the library, run:
+---
 
-```bash
-ng build micro-app
+## 5. Register the custom URL scheme (Capacitor native only)
+
+The mobile OAuth redirect URI is `com.thehood.app://micro/callback`. You must register this scheme in both native projects.
+
+### iOS — `ios/App/App/Info.plist`
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>com.thehood.app</string>
+    </array>
+  </dict>
+</array>
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+### Android — `android/app/src/main/AndroidManifest.xml`
 
-### Publishing the Library
+Inside the main `<activity>` tag:
 
-Once the project is built, you can publish your library by following these steps:
+```xml
+<intent-filter>
+  <action android:name="android.intent.action.VIEW" />
+  <category android:name="android.intent.category.DEFAULT" />
+  <category android:name="android.intent.category.BROWSABLE" />
+  <data android:scheme="com.thehood.app" />
+</intent-filter>
+```
 
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/micro-app
-   ```
+---
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+## 6. Making API requests inside micro components
 
-## Running unit tests
+The library provides its own child-scoped `HttpClient`. Use the `IS_MICRO_API` context token on every request so the micro interceptor can:
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+- Prepend the API base URL to relative paths.
+- Attach the Bearer token.
+- Handle 401 errors with an automatic token refresh.
 
-```bash
-ng test
+```ts
+import { HttpClient, HttpContext } from '@angular/common/http';
+import { inject } from '@angular/core';
+import { IS_MICRO_API } from 'dhomie-app';
+
+// Inside a micro component or service:
+const http = inject(HttpClient);
+
+http.get('/properties', {
+  context: new HttpContext().set(IS_MICRO_API, true),
+});
+// → sends GET https://api.dhomie.com/v1/properties
+//   with Authorization: Bearer <current_token>
 ```
 
-## Running end-to-end tests
+> Requests made **without** `IS_MICRO_API` (or with it set to `false`) pass through unchanged — parent-app interceptors are not involved in micro-app calls, and vice versa.
+
+---
+
+## 7. How authentication works
+
+The guard (`microAuthGuard`) runs before every protected route under `/micro/home`.
+
+**Step-by-step sequence:**
+
+1. **Hydrate storage** — token data is loaded from `@capacitor/preferences` into RAM. This is memoized and instant on repeat navigations.
+2. **Check token** — if `hasValidAccessToken()` returns `true`, navigation is allowed immediately.
+3. **Load discovery document** — the OIDC `.well-known` endpoint is fetched once and cached.
+4. **Platform split:**
+   - **Native (Capacitor)** — generates a PKCE authorization URL, registers an `appUrlOpen` listener, then opens the URL in the system browser via `@capacitor/browser`. Returns `false` (blocks navigation).
+   - **Web** — calls `initCodeFlow()` which redirects `window.location` to the authorization endpoint. Returns `false`.
+5. **Callback** — when the auth server redirects back, `MicroCallbackComponent` (at `/micro/callback`) calls `tryLoginCodeFlow()`, exchanges the code for tokens, and stores them via `CapacitorOAuthStorage`.
+6. **Token refresh** — `MicroRefreshSchedulerService` proactively refreshes tokens before expiry. `MicroTokenRefreshService` handles concurrent 401s with a shared refresh lock.
 
-For end-to-end (e2e) testing, run:
+---
+
+## 8. Baked-in configuration reference
+
+All OIDC credentials and API URLs are inlined into the published FESM bundle at build time. No runtime configuration is needed. The values correspond to `env.prod.ts`:
+
+| Field                       | Baked-in value                              |
+|-----------------------------|---------------------------------------------|
+| `oidc.issuer`               | `https://auth.dhomie.com`                   |
+| `oidc.clientId`             | `dhomie-micro-client`                       |
+| `oidc.scope`                | `openid profile email offline_access`       |
+| `oidc.redirectUri` (web)    | `https://app.dhomie.com/micro/callback`     |
+| `oidc.mobileRedirectUri`    | `com.thehood.app://micro/callback`          |
+| `oidc.responseType`         | `code` (PKCE)                               |
+| `microApiBaseUrl`           | `https://api.dhomie.com/v1`                 |
+
+---
+
+## 9. Publishing a new version
+
+Run the publish script from the **project root**:
 
 ```bash
-ng e2e
+# Without 2FA OTP
+npm run publish:dhomie-app
+
+# With 2FA OTP
+npm run publish:dhomie-app -- 123456
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+The script performs these steps automatically:
 
-## Additional Resources
+| Step | Action |
+|------|--------|
+| 0 | Bumps the **patch** version in `projects/dhomie-app/package.json` |
+| 1 | Builds the library in production mode (`ng build dhomie-app --configuration production`) |
+| 2 | Inlines the `env.prod.ts` values into the FESM bundle (replaces the `dhomie-env` virtual import) |
+| 3 | Removes the stale source map and any `.npmrc` copied into `dist/dhomie-app` |
+| 4 | Publishes `./dist/dhomie-app` to npm with `--access public` |
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+To bump the **minor** or **major** version instead, edit `projects/dhomie-app/package.json` manually before running the script.

package/fesm2022/dhomie-app.mjs

@@ -6,18 +6,18 @@ import { Browser } from '@capacitor/browser';
 import { Capacitor } from '@capacitor/core';
 import { OAuthService, OAuthStorage, provideOAuthClient } from 'angular-oauth2-oidc';
 const env = {
-  production: true,
-  oidc: {
-    issuer: 'https://auth.dhomie.com',
-    clientId: 'dhomie-micro-client',
-    scope: 'openid profile email offline_access',
-    redirectUri: 'https://app.dhomie.com/micro/callback',
-    mobileRedirectUri: 'com.thehood.app://micro/callback',
-    responseType: 'code',
-    showDebugInformation: false,
-    useSilentRefresh: false,
+  "production": true,
+  "oidc": {
+    "issuer": "https://thehood-dev-uae-api.azurewebsites.net",
+    "clientId": "ios",
+    "scope": "openid profile offline_access app",
+    "redirectUri": "https://thehood-dev-uae-api.azurewebsites.net/login-callback",
+    "mobileRedirectUri": "thehoodapp:/callback",
+    "responseType": "code",
+    "showDebugInformation": true,
+    "useSilentRefresh": false
   },
-  microApiBaseUrl: 'https://api.dhomie.com/v1',
+  "microApiBaseUrl": "https://api.dhomie.com/v1"
 };
 import { Preferences } from '@capacitor/preferences';
 import { IonContent, IonSpinner, IonButton, IonButtons, IonHeader, IonItem, IonLabel, IonList, IonTitle, IonToolbar } from '@ionic/angular/standalone';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dhomie-app",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "peerDependencies": {
     "@angular/common": "^20.3.0",
     "@angular/core": "^20.3.0",