valtech-components 2.0.724 → 2.0.726

package/lib/services/auth/handoff.service.d.ts

@@ -0,0 +1,149 @@
+import { HttpClient } from '@angular/common/http';
+import { Router } from '@angular/router';
+import { Observable } from 'rxjs';
+import { AuthService } from './auth.service';
+import { ValtechAuthConfig } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Name of the query param that carries the handoff token. Apps may override
+ * via `detectAndExchangeHandoff({ tokenParam })` but the default keeps the
+ * convention consistent across the factory.
+ */
+export declare const HANDOFF_TOKEN_PARAM = "handoff";
+/**
+ * Name of the query param that carries the post-exchange route.
+ */
+export declare const HANDOFF_ROUTE_PARAM = "route";
+/**
+ * Options for `HandoffService.detectAndExchangeHandoff`.
+ */
+export interface DetectAndExchangeOptions {
+    /** Override the query param name. Default: `'handoff'`. */
+    tokenParam?: string;
+    /** Override the route param name. Default: `'route'`. */
+    routeParam?: string;
+    /** Where to navigate if no route param is present. Default: `'/'`. */
+    defaultRoute?: string;
+    /** Where to navigate on exchange error. Default: app's configured `loginRoute`. */
+    errorRoute?: string;
+}
+/**
+ * Request body for `POST /v2/auth/handoff`.
+ *
+ * Both fields are optional and stored for audit only — the exchange step
+ * does not enforce that the redeeming app matches `targetAppId`.
+ */
+export interface HandoffCreateRequest {
+    /** Target app the handoff is intended for (e.g. `"myvaltech"`). Audit-only. */
+    targetAppId?: string;
+    /** Route the target app should navigate to after exchange. Echoed back. */
+    route?: string;
+}
+/**
+ * Response body from `POST /v2/auth/handoff`.
+ */
+export interface HandoffCreateResponse {
+    operationId: string;
+    /** Raw token to embed in the redirect URL as `?handoff=<token>`. 30s TTL, single-use. */
+    token: string;
+    /** RFC3339 expiration timestamp. */
+    expiresAt: string;
+    /** Echoed `route` from the request, when provided. */
+    route?: string;
+}
+/**
+ * Response body from `POST /v2/auth/handoff/exchange`.
+ *
+ * Same shape as `SigninResponse` — installable via `AuthService.setExternalAuth`.
+ */
+export interface HandoffExchangeResponse {
+    operationId: string;
+    accessToken: string;
+    refreshToken: string;
+    firebaseToken?: string;
+    expiresIn: number;
+    tokenType: string;
+    userId: string;
+}
+/**
+ * HandoffService — cross-app session transfer.
+ *
+ * Implements the OAuth Authorization Code pattern, applied internally between
+ * apps that share the same backend.
+ *
+ * **Origin app (user is authenticated):**
+ *
+ * ```typescript
+ * const { token, route } = await firstValueFrom(
+ *   handoff.createHandoff({ targetAppId: 'myvaltech', route: '/app/dashboard' })
+ * );
+ * window.location.href = `https://myvaltech.app/?handoff=${token}&route=${encodeURIComponent(route ?? '/')}`;
+ * ```
+ *
+ * **Target app (boot):** call `exchangeHandoff(token)`. On success, the session
+ * is installed (`AuthService.setExternalAuth`) and the user is authenticated.
+ * See `detectAndExchangeHandoff` helper for the typical bootstrap pattern.
+ *
+ * Security notes:
+ * - Token is single-use and short-lived (30s) — enforced server-side.
+ * - Token in URL must be removed from history after exchange to avoid log leakage.
+ * - The exchange endpoint is public; do NOT add auth header. The
+ *   `HttpClient` request below avoids triggering the auth interceptor since the
+ *   user isn't logged in yet on the target app.
+ */
+export declare class HandoffService {
+    private config;
+    private http;
+    private auth;
+    private router;
+    private detected;
+    constructor(config: ValtechAuthConfig, http: HttpClient, auth: AuthService, router: Router);
+    /**
+     * Create a handoff token. Caller must be authenticated.
+     *
+     * @param request Optional metadata: target app id and intended route.
+     * @returns Observable emitting `{ token, expiresAt, route? }`.
+     */
+    createHandoff(request?: HandoffCreateRequest): Observable<HandoffCreateResponse>;
+    /**
+     * Exchange a handoff token for a session and install it.
+     *
+     * On success, the response is piped through `AuthService.setExternalAuth`
+     * so the user becomes authenticated. Subsequent navigation can proceed.
+     *
+     * On failure, the observable errors. The caller is responsible for
+     * showing an error and routing to `/login`.
+     *
+     * @param token Raw handoff token read from the URL.
+     */
+    exchangeHandoff(token: string): Observable<HandoffExchangeResponse>;
+    /**
+     * Bootstrap helper — reads the handoff token from the current URL, exchanges
+     * it for a session, and navigates to the intended route with the token
+     * stripped from history.
+     *
+     * Idempotent: subsequent calls are no-ops. Wire from an
+     * `APP_INITIALIZER`/`provideAppInitializer` factory in `main.ts`.
+     *
+     * ```typescript
+     * // main.ts
+     * provideAppInitializer(() => inject(HandoffService).detectAndExchangeHandoff())
+     * ```
+     *
+     * On error (expired/used/invalid token), redirects to `errorRoute` (default:
+     * the app's configured `loginRoute`). The URL is always cleaned, even on
+     * error, so the token cannot be retried by refreshing the page.
+     *
+     * @returns `true` if a handoff was detected and processed (success or fail).
+     *          `false` if no token was present (cold boot, normal flow).
+     */
+    detectAndExchangeHandoff(options?: DetectAndExchangeOptions): Promise<boolean>;
+    /**
+     * Persist the session in `AuthService`. Mirrors the install flow used by
+     * the normal signin path so timers, Firebase, and tab-sync all kick in.
+     */
+    private installSession;
+    private get baseUrl();
+    static ɵfac: i0.ɵɵFactoryDeclaration<HandoffService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<HandoffService>;
+}

package/lib/services/auth/index.d.ts

@@ -81,3 +81,7 @@ export { DeviceService } from './device.service';
 export { SessionService } from './session.service';
 export { OAuthService } from './oauth.service';
 export { OAuthCallbackComponent } from './oauth-callback.component';
+export { HandoffService, HANDOFF_TOKEN_PARAM, HANDOFF_ROUTE_PARAM } from './handoff.service';
+export type { HandoffCreateRequest, HandoffCreateResponse, HandoffExchangeResponse, DetectAndExchangeOptions, } from './handoff.service';
+export { OrgSwitchService } from './org-switch.service';
+export type { OrgChangedEvent, SwitchOrgOptions } from './org-switch.service';

package/lib/services/auth/org-switch.service.d.ts

@@ -0,0 +1,127 @@
+import { Observable } from 'rxjs';
+import { AuthService } from './auth.service';
+import * as i0 from "@angular/core";
+/**
+ * Event emitted when the active organization changes.
+ */
+export interface OrgChangedEvent {
+    /** Org the user was on before the switch. May be empty on first sign-in. */
+    previousOrg: string;
+    /** Org the user just switched to. */
+    newOrg: string;
+}
+/**
+ * Options for `OrgSwitchService.switchTo`.
+ */
+export interface SwitchOrgOptions {
+    /**
+     * If `true`, after the switch succeeds the page is fully reloaded via
+     * `window.location.reload()`. Useful for apps with significant in-memory
+     * state tied to the previous org that's hard to invalidate piece by piece.
+     *
+     * Trade-off: reload loses all in-memory state (forms, scroll position).
+     * Default: `false` — relies on `orgChanged$` and `auth.user()` signal
+     * propagation for components to react.
+     */
+    reload?: boolean;
+}
+/**
+ * OrgSwitchService — orchestrates active organization changes across the app.
+ *
+ * Built on top of `AuthService.switchOrg`, which already:
+ * - Hits `POST /v2/auth/switch-org` and receives a new Firebase custom token.
+ * - Re-authenticates Firebase Auth with the new token (RBAC claims update).
+ * - Broadcasts `ORG_SWITCH` to other tabs via `AuthSyncService` (multi-tab sync).
+ *
+ * What this service adds on top:
+ * - A `switching` signal so the UI can show a loading indicator (1-2s switch).
+ * - An `orgChanged$` Observable that components subscribe to in order to
+ *   invalidate their org-scoped caches (e.g. drop old query results, reset
+ *   page state) without a full page reload.
+ * - Optional `reload: true` for apps where invalidating in-memory state piece
+ *   by piece is impractical.
+ *
+ * **What this service does NOT do automatically:**
+ *
+ * 1. **Teardown Firestore listeners.** Listeners are owned by their subscribing
+ *    components (typically via `takeUntilDestroyed` or async pipe). When the
+ *    component re-renders or unsubscribes, the listener disposes. If a
+ *    component does NOT unsubscribe on org change, its listener will keep
+ *    pointing at the previous org's path and may start failing rules. The fix
+ *    is component-level: subscribe to `orgChanged$` and reset state, or use
+ *    the `reload: true` option.
+ *
+ * 2. **Re-instantiate routed components.** Angular keeps mounted components
+ *    alive across navigations. If you need fresh state, either subscribe to
+ *    `orgChanged$` in the component, or use `reload: true`.
+ *
+ * @example Basic switch with loading state
+ * ```typescript
+ * private orgSwitch = inject(OrgSwitchService);
+ *
+ * async onSwitchOrg(orgId: string) {
+ *   await this.orgSwitch.switchTo(orgId);
+ *   // Components subscribed to orgChanged$ have already reset their state.
+ * }
+ *
+ * // In template:
+ * @if (orgSwitch.switching()) { <val-loading /> }
+ * ```
+ *
+ * @example Component reacting to org change
+ * ```typescript
+ * private orgSwitch = inject(OrgSwitchService);
+ *
+ * constructor() {
+ *   this.orgSwitch.orgChanged$
+ *     .pipe(takeUntilDestroyed())
+ *     .subscribe(() => this.resetState());
+ * }
+ * ```
+ *
+ * @example Brutal reload mode
+ * ```typescript
+ * await this.orgSwitch.switchTo(orgId, { reload: true });
+ * // window.location.reload() — clean slate, loses scroll position
+ * ```
+ */
+export declare class OrgSwitchService {
+    private auth;
+    private readonly _switching;
+    private readonly _orgChanged;
+    /**
+     * `true` while a switch is in flight. UI should disable interactions
+     * with org-scoped data and show a loading indicator.
+     */
+    readonly switching: import("@angular/core").Signal<boolean>;
+    /**
+     * Fires after a successful switch, with the previous and new org ids.
+     * Components subscribe to invalidate caches / reset state.
+     *
+     * Fires AFTER the Firebase re-auth completes — listeners attached here
+     * see the updated Firebase user / activeOrg claim.
+     */
+    readonly orgChanged$: Observable<OrgChangedEvent>;
+    constructor(auth: AuthService);
+    /**
+     * Switch the user's active organization.
+     *
+     * Re-entrant safe: while a switch is in flight, additional calls are
+     * rejected silently (returns immediately). Inspect `switching()` to gate UI.
+     *
+     * @param orgId Target organization id. Must be one the user has a role in
+     *              — backend rejects otherwise with `PERMISSION_DENIED`.
+     * @param options See `SwitchOrgOptions`.
+     *
+     * @throws The error from `auth.switchOrg` if the backend call fails.
+     *         `switching` returns to `false` before the error propagates.
+     */
+    switchTo(orgId: string, options?: SwitchOrgOptions): Promise<void>;
+    /**
+     * Read the current `activeOrg` from the auth user signal.
+     * Falls back to empty string if the user isn't loaded yet.
+     */
+    private currentActiveOrg;
+    static ɵfac: i0.ɵɵFactoryDeclaration<OrgSwitchService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<OrgSwitchService>;
+}

package/lib/services/firebase/firestore-collection.d.ts

@@ -16,6 +16,17 @@ export interface CollectionOptions {
      * Default: true
      */
     timestamps?: boolean;
+    /**
+     * Si true, el path se trata como global y NO se prefija con `apps/{appId}/`.
+     *
+     * Usar para colecciones cross-app a nivel user/global, p.ej.
+     * `users/{uid}/notifications` (inbox global), `profiles/{uid}` o `public/...`.
+     *
+     * Las reglas de Firestore deben permitir el path absoluto correspondiente.
+     *
+     * Default: false (path prefijado a `apps/{appId}/...`).
+     */
+    skipAppPrefix?: boolean;
 }
 /**
  * Referencia a una sub-colección tipada.
@@ -73,8 +84,8 @@ export declare class FirestoreCollectionFactory {
  */
 export declare class TypedCollection<T extends FirestoreDocument> {
     private firestore;
-    private collectionPath;
     private readonly options;
+    private readonly collectionPath;
     constructor(firestore: FirestoreService, collectionPath: string, options?: CollectionOptions);
     /**
      * Obtiene un documento por ID.

package/lib/services/firebase/firestore.service.d.ts

@@ -2,6 +2,19 @@ import { Firestore, FieldValue } from '@angular/fire/firestore';
 import { Observable } from 'rxjs';
 import { FirestoreDocument, PaginatedResult, QueryOptions } from './types';
 import * as i0 from "@angular/core";
+/**
+ * Internal sentinel used to mark a collection path as global cross-app —
+ * i.e. it should NOT be prefixed with `apps/{appId}/`.
+ *
+ * Apps consume this via `CollectionOptions.skipAppPrefix`; the sentinel
+ * stays in `TypedCollection` and is stripped here before Firestore sees it.
+ *
+ * Format keeps it impossible to collide with a real Firestore path (`:` is
+ * not allowed in collection segments).
+ *
+ * @internal
+ */
+export declare const ABS_PATH_SENTINEL = "__abs__:";
 /**
  * Servicio para operaciones CRUD en Firestore.
  *
@@ -43,6 +56,11 @@ export declare class FirestoreService {
      * Prefija el path de colección con el appId si está configurado.
      * Si no hay appId, retorna el path sin modificar (backward compatible).
      *
+     * Si el path empieza con `ABS_PATH_SENTINEL` (`__abs__:`), se asume que el
+     * caller quiere un path global cross-app (ej. `users/{uid}/notifications` —
+     * el inbox global de notificaciones). El sentinel se strippea y el resto
+     * del path se pasa verbatim, sin prefijo `apps/{appId}/`.
+     *
      * @internal
      */
     private prefixCollectionPath;

package/lib/services/firebase/shared-config.d.ts

@@ -9,54 +9,87 @@ import { AppId, EmulatorConfig, FirebaseConfig, ValtechFirebaseConfig } from './
 import type { AnalyticsConfig } from './analytics-types';
 export type { AppId } from './types';
 /**
- * Genera paths de Storage con namespace por app.
+ * Genera paths de Storage alineados con storage.rules.
+ *
+ * Convenciones (ver frontend/firebase/storage.rules):
+ * - Avatar global del user (cross-app): /users/{uid}/avatar.jpg
+ * - Files privados del user (cross-app): /users/{uid}/files/{path}
+ * - Avatar per-app del user: /apps/{appId}/users/{uid}/avatar.jpg
+ * - Files per-app del user: /apps/{appId}/users/{uid}/files/{path}
+ * - Public per-app: /apps/{appId}/public/{path}
+ * - Shared per-app (auth-only): /apps/{appId}/shared/{path}
+ * - Public global: /public/{path}
  *
  * @example
- * // Path específico de la app
- * storagePaths.forApp('showcase', 'uploads', 'image.jpg')
- * // => 'showcase/uploads/image.jpg'
+ * storagePaths.forApp('showcase', 'public', 'banner.jpg')
+ * // => 'apps/showcase/public/banner.jpg'
+ *
+ * storagePaths.userAvatar('user123')
+ * // => 'users/user123/avatar.jpg'
  *
- * // Path compartido
- * storagePaths.shared.profilePhoto('user123', 'avatar.jpg')
- * // => 'profile-photos/user123/avatar.jpg'
+ * storagePaths.appUserFile('showcase', 'user123', 'doc.pdf')
+ * // => 'apps/showcase/users/user123/files/doc.pdf'
  */
 export declare const storagePaths: {
-    /** Carpeta específica de la app: {appId}/{...paths} */
+    /** Path per-app: apps/{appId}/{...paths} */
     forApp: (appId: AppId, ...paths: string[]) => string;
-    /** Carpetas compartidas (sin namespace) */
-    shared: {
-        /** Foto de perfil de usuario */
-        profilePhoto: (userId: string, fileName: string) => string;
-        /** Archivos públicos accesibles sin autenticación */
-        public: (...paths: string[]) => string;
-    };
+    /** Avatar global del user (cross-app) */
+    userAvatar: (userId: string) => string;
+    /** Thumbnail global del user (cross-app) */
+    userThumb: (userId: string) => string;
+    /** File privado global del user (cross-app) */
+    userFile: (userId: string, ...paths: string[]) => string;
+    /** Avatar per-app del user */
+    appUserAvatar: (appId: AppId, userId: string) => string;
+    /** File per-app del user */
+    appUserFile: (appId: AppId, userId: string, ...paths: string[]) => string;
+    /** Public global (acceso sin auth, write admin-only) */
+    public: (...paths: string[]) => string;
 };
 /**
- * Genera paths de colecciones con namespace por app.
+ * Genera paths de colecciones alineados con firestore.rules.
  *
- * IMPORTANTE: La estructura es /apps/{appId}/{collection}/{docId}
- * Firestore requiere número impar de segmentos para paths de colección.
+ * Convenciones (ver frontend/firebase/firestore.rules):
+ * - Cross-app shared:
+ *   /users/{uid} (privado), /profiles/{uid} (público global),
+ *   /users/{uid}/notifications (INBOX GLOBAL cross-app cross-org)
+ * - Per-app:
+ *   /apps/{appId}/{collection}, /apps/{appId}/profiles/{uid}
+ * - Per-app per-user (notifications NO viven aquí):
+ *   /apps/{appId}/users/{uid}/{collection}
+ * - Per-app per-org:
+ *   /apps/{appId}/orgs/{orgId}/{collection}
  *
  * @example
- * // Colección específica de la app
  * collections.forApp('showcase', 'items')
  * // => 'apps/showcase/items'
  *
- * // Colección compartida
- * collections.shared.users
- * // => 'users'
+ * collections.appUser('showcase', 'user123', 'drafts')
+ * // => 'apps/showcase/users/user123/drafts'
+ *
+ * collections.appOrg('showcase', 'org_abc', 'posts')
+ * // => 'apps/showcase/orgs/org_abc/posts'
+ *
+ * collections.userNotifications('user123')
+ * // => 'users/user123/notifications'
  */
 export declare const collections: {
-    /** Colección específica de la app: apps/{appId}/{collection} */
+    /** Per-app cross-user: apps/{appId}/{collection} */
     forApp: (appId: AppId, collectionName: string) => string;
-    /** Colecciones compartidas (sin namespace, nivel raíz) */
+    /** Per-app per-user: apps/{appId}/users/{uid}/{collection} */
+    appUser: (appId: AppId, userId: string, collectionName: string) => string;
+    /** Per-app per-org: apps/{appId}/orgs/{orgId}/{collection} */
+    appOrg: (appId: AppId, orgId: string, collectionName: string) => string;
+    /** Per-app perfil público del user: apps/{appId}/profiles/{uid} */
+    appProfile: (appId: AppId, userId: string) => string;
+    /** Inbox global del user (cross-app cross-org) */
+    userNotifications: (userId: string) => string;
+    /** Cross-app shared (sin namespace, nivel raíz) */
     shared: {
-        /** Usuarios del sistema */
+        /** Doc privado del user — /users/{uid} */
         users: string;
-        /** Perfiles públicos */
+        /** Perfiles públicos globales — /profiles/{uid} */
         profiles: string;
-        /** Notificaciones de usuarios */
-        notifications: string;
     };
 };
 /**

package/lib/version.d.ts

@@ -2,4 +2,4 @@
  * Current version of valtech-components.
  * This is automatically updated during the publish process.
  */
-export declare const VERSION = "2.0.724";
+export declare const VERSION = "2.0.726";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "valtech-components",
-  "version": "2.0.724",
+  "version": "2.0.726",
   "private": false,
   "bin": {
     "valtech-firebase-config": "./src/lib/services/firebase/scripts/generate-sw-config.js"