@arsedizioni/ars-utils 22.5.14 → 22.5.16

package/types/arsedizioni-ars-utils-clipper.common.d.ts

@@ -201,6 +201,19 @@ interface ClipperUserInfo {
 interface ClipperLoginResult extends LoginResult<ClipperUserInfo> {
     settings?: ClipperChannelSettings[];
 }
+/**
+ * Answer of `GET /session/status`: whether this browser holds a live session towards the Clipper API.
+ *
+ * This is the probe behind the link state. The auth cookie is HttpOnly and belongs to the API's
+ * host, so nothing here can read it, and its presence would prove nothing anyway — the session also
+ * lives server-side and may have been revoked or evicted. The endpoint never answers 401, which is
+ * what makes it safe to call with no session at all: a probe that failed with a status code would be
+ * reported by the interceptor as an expired session.
+ */
+interface ClipperSessionStatus {
+    /** True when the cookie this browser presented resolves to a live, validated session. */
+    connected: boolean;
+}
 interface ClipperLoginInfo {
     context?: ClipperUserInfo;
     channels?: ClipperChannelSettings[];
@@ -1005,12 +1018,22 @@ declare class ClipperLoginService {
     /** Whether {@link initialize} has already run. */
     private initialized;
     /**
-     * Validates a context that survived a page refresh before trusting it.
+     * Gets the signed-in account.
+     * @returns The current {@link ClipperUserInfo}, or `undefined` when there is no session.
+     */
+    get user(): ClipperUserInfo | undefined;
+    /**
+     * Establishes the session state at bootstrap by asking the API — the only party that can read the
+     * HttpOnly cookie — whether this browser still holds one.
      *
      * Called by `ClipperService.initialize`, right after `ClipperCoreService.initialize`, so a
-     * consumer gets the restore for free and never has to know this method exists. The auth cookie is
-     * HttpOnly and may have expired while the stored context lived on, so a stored context only ever
-     * means "there WAS a session" — this is what turns it into "there is one".
+     * consumer gets the restore for free and never has to know this method exists.
+     *
+     * The probe now runs UNCONDITIONALLY, where it used to run only when a stored context existed.
+     * The stored context is just a hint — "this browser signed in at some point" — and the cookie can
+     * outlive it: local storage cleared while the month-long cookie stayed put made this library
+     * declare "no link" with a perfectly valid session in the browser. The API is the only source of
+     * truth on the matter, so it is asked every time.
      *
      * A host application that drives its own return from an external provider, or that starts on its
      * own sign-in page, should call `core.setLoggedIn(false)` before bootstrapping rather than let
@@ -1019,12 +1042,17 @@ declare class ClipperLoginService {
      */
     initialize(): void;
     /**
-     * Asks `/session/me` whether the restored session is still alive. On success the login is
-     * finalised from the current claims; on a dead session the interceptor's 401 handling takes over.
+     * Asks `/session/status` whether this browser holds a live session, and hydrates the context
+     * through {@link me} when it does.
+     *
+     * The probe is silent by construction: `/session/status` never answers 401, so a visitor who
+     * never signed in — or a cookie whose session has died — comes back as `connected: false` with no
+     * error broadcast and no dialog. Only then is the stale stored context cleared, so the `loggedIn`
+     * signal tells the truth at every bootstrap.
      *
-     * Nothing is cleared on failure, and that is deliberate: a failure here is not proof of a dead
-     * session — the API may be unreachable, the proxy may have answered 502, the device may be
-     * offline. Clearing on any of those would sign the user out with a perfectly valid cookie.
+     * Nothing is cleared on a transport failure, and that is deliberate: an unreachable API is not
+     * proof of a dead session — the proxy may have answered 502, the device may be offline — and
+     * clearing on any of those would sign the user out with a perfectly valid cookie.
      * @returns void
      */
     private restoreSession;
@@ -1057,6 +1085,15 @@ declare class ClipperLoginService {
      * @returns An observable that emits once the logout has been processed.
      */
     logout(): Observable<ApiResult<unknown>>;
+    /**
+     * Asks the API whether this browser holds a live session, without ever failing with a 401: the
+     * route is anonymous and answers `connected: false` to a caller with no session. This is the one
+     * honest way to know the link state — the auth cookie is HttpOnly and belongs to the API's host,
+     * so it cannot be read from here, and its presence would prove nothing anyway, since the session
+     * also lives server-side and may have been revoked or evicted.
+     * @returns An observable emitting the API result wrapping the session status.
+     */
+    status(): Observable<ApiResult<ClipperSessionStatus>>;
     /**
      * Reads the current session from the server, which resolves it from the auth cookie claims
      * without touching the database. Used to restore the state after a page refresh instead of
@@ -1125,6 +1162,8 @@ declare class ClipperService {
     get flags(): ClipperServiceFlags;
     /** @returns The current login context, or `undefined` if not authenticated. */
     get loginInfo(): ClipperLoginInfo | undefined;
+    /** @returns The signed-in account, or `undefined` when there is no session. */
+    get user(): ClipperUserInfo | undefined;
     /** @returns A read-only signal indicating whether the user is logged in. */
     get loggedIn(): Signal<boolean>;
     /** @returns A signal indicating whether a login is in progress. */
@@ -1199,6 +1238,11 @@ declare class ClipperCoreService {
      * @returns The current login context, or `undefined` if not authenticated.
      */
     get loginInfo(): ClipperLoginInfo | undefined;
+    /**
+     * Gets the signed-in account.
+     * @returns The current {@link ClipperUserInfo}, or `undefined` when there is no session.
+     */
+    get user(): ClipperUserInfo | undefined;
     /**
      * Seeded from the stored context, which is the only trace a session leaves on this device: the
      * auth cookie is HttpOnly and unreadable from here. It means "there WAS a session", never "there
@@ -1287,4 +1331,4 @@ declare class ClipperCoreService {
 }
 
 export { ClipperAccountService, ClipperAuthors, ClipperCalendarSearchParams, ClipperCalendarState, ClipperCalendarStates, ClipperChannel, ClipperChannelSettings, ClipperChannels, ClipperCoreService, ClipperDashboard, ClipperDocumentChangeReasons, ClipperDocumentContainer, ClipperDocumentsService, ClipperExportDocumentsFormat, ClipperFacet, ClipperLoginService, ClipperMessages, ClipperModel, ClipperModels, ClipperModule, ClipperModuleGroup, ClipperModuleGroups, ClipperModules, ClipperQueryDocumentFlags, ClipperQueryReferencesMode, ClipperRegions, ClipperSearchCalendarSnapshotResult, ClipperSearchFacetsSnapshot, ClipperSearchParams, ClipperSearchResult, ClipperSearchUtils, ClipperSectorTypes, ClipperSectors, ClipperSelectionMode, ClipperService, ClipperServiceFlags, ClipperSort, ClipperSources, ClipperUtils, clipperAuthInterceptor };
-export type { ClipperAvailableChannel, ClipperChannelSettingsItem, ClipperDashboardItem, ClipperDashboardModelItem, ClipperDeleteWorkingDocumentsParams, ClipperDocumentAnchorInfo, ClipperDocumentInfo, ClipperDocumentNote, ClipperDocumentNoteTracking, ClipperDocumentRelevantChunkHit, ClipperDocumentRelevants, ClipperDocumentStructure, ClipperDocumentUpdateStateParams, ClipperExportDocumentsParams, ClipperLoginInfo, ClipperLoginResult, ClipperOTPInfo, ClipperReferencesSearchParams, ClipperSearchCalendarSnapshotMonth, ClipperSearchFacet, ClipperSearchFacetGroup, ClipperSearchFacetsResult, ClipperSearchFilter, ClipperSendDocumentsByEmailParams, ClipperTaxonomyParams, ClipperTopicInfo, ClipperUserChannelInfo, ClipperUserInfo, ClipperUserSearch, ClipperUserTrialInfo, ClipperUserWorkingDocument, EditedEventArgs, SectorInfo };
+export type { ClipperAvailableChannel, ClipperChannelSettingsItem, ClipperDashboardItem, ClipperDashboardModelItem, ClipperDeleteWorkingDocumentsParams, ClipperDocumentAnchorInfo, ClipperDocumentInfo, ClipperDocumentNote, ClipperDocumentNoteTracking, ClipperDocumentRelevantChunkHit, ClipperDocumentRelevants, ClipperDocumentStructure, ClipperDocumentUpdateStateParams, ClipperExportDocumentsParams, ClipperLoginInfo, ClipperLoginResult, ClipperOTPInfo, ClipperReferencesSearchParams, ClipperSearchCalendarSnapshotMonth, ClipperSearchFacet, ClipperSearchFacetGroup, ClipperSearchFacetsResult, ClipperSearchFilter, ClipperSendDocumentsByEmailParams, ClipperSessionStatus, ClipperTaxonomyParams, ClipperTopicInfo, ClipperUserChannelInfo, ClipperUserInfo, ClipperUserSearch, ClipperUserTrialInfo, ClipperUserWorkingDocument, EditedEventArgs, SectorInfo };

package/types/arsedizioni-ars-utils-evolution.common.d.ts

@@ -46,6 +46,20 @@ interface EvolutionLoginResult {
      */
     requiresPasswordChange?: boolean;
 }
+/**
+ * Answer of `GET /session/status`: whether this browser holds a live session towards the Evolution
+ * API.
+ *
+ * This is the probe behind the link state. The auth cookie is HttpOnly and belongs to the API's
+ * host, so nothing here can read it, and its presence would prove nothing anyway — the session also
+ * lives server-side and may have been revoked or evicted. The endpoint never answers 401, which is
+ * what makes it safe to call with no session at all: a probe that failed with a status code would be
+ * reported by the interceptor as an expired session.
+ */
+interface EvolutionSessionStatus {
+    /** True when the cookie this browser presented resolves to a live, validated session. */
+    connected: boolean;
+}
 /**
  * The session as this library holds it, persisted so a page refresh has something to validate.
  *
@@ -957,8 +971,8 @@ declare class LoginService {
      */
     clear(): void;
     /**
-     * Initialises the service with the back-end URI and optional feature flags, and revalidates a
-     * session that survived a page refresh instead of assuming it is still there.
+     * Initialises the service with the back-end URI and optional feature flags, and asks the API — the
+     * only party that can read the HttpOnly cookie — whether this browser still holds a session.
      *
      * Must be called once during application bootstrap, before any other method. What it used to do
      * on a refresh was announce `LOGIN_COMPLETED` on the strength of a value in local storage; the
@@ -1009,6 +1023,15 @@ declare class LoginService {
      * @returns An observable that emits the `ApiResult<EvolutionLoginResult>`.
      */
     confirmIdentity(code: string, email?: string): Observable<ApiResult<EvolutionLoginResult>>;
+    /**
+     * Asks the API whether this browser holds a live session, without ever failing with a 401: the
+     * route is anonymous and answers `connected: false` to a caller with no session. This is the one
+     * honest way to know the link state -- the auth cookie is HttpOnly and belongs to the API's host,
+     * so it cannot be read from here, and its presence would prove nothing anyway, since the session
+     * also lives server-side and may have been revoked or evicted.
+     * @returns An observable that emits the `ApiResult<EvolutionSessionStatus>`.
+     */
+    status(): Observable<ApiResult<EvolutionSessionStatus>>;
     /**
      * Reads the current session from the server, which resolves it from the auth cookie's claims.
      * Used to restore the state after a page refresh instead of trusting what local storage holds.
@@ -1020,13 +1043,17 @@ declare class LoginService {
      */
     me(): Observable<ApiResult<EvolutionLoginResult>>;
     /**
-     * Asks `/session/me` whether the restored session is still alive, and announces the login when it
-     * is.
+     * Asks `/session/status` whether this browser holds a live session, and hydrates the context
+     * through {@link me} when it does.
+     *
+     * The probe is silent by construction: `/session/status` never answers 401, so a visitor who
+     * never signed in -- or a cookie whose session has died -- comes back as `connected: false` with
+     * no error broadcast and no dialog. Only then is the stale stored context cleared, so the
+     * `loggedIn` signal tells the truth at every bootstrap.
      *
-     * Nothing is cleared on failure, and that is deliberate: a failure here is not proof of a dead
-     * session -- the API may be unreachable, the proxy may have answered 502, the device may be
-     * offline -- and clearing on any of those would sign the user out with a perfectly valid cookie.
-     * A genuine 401 is a different matter and the interceptor has already reported it.
+     * Nothing is cleared on a transport failure, and that is deliberate: an unreachable API is not
+     * proof of a dead session -- the proxy may have answered 502, the device may be offline -- and
+     * clearing on any of those would sign the user out with a perfectly valid cookie.
      * @returns void
      */
     private restoreSession;
@@ -1239,8 +1266,9 @@ declare class EvolutionService {
     get user(): EvolutionUserInfo | undefined;
     /**
      * `true` when this browser has a session the API has accepted. It starts from the stored context
-     * and is confirmed -- or left to the interceptor's 401 handling -- by the `/session/me` call
-     * {@link initialize} makes.
+     * and is settled -- raised or cleared -- by the silent `/session/status` probe {@link initialize}
+     * makes, which is the one honest way to read a state that lives in an HttpOnly cookie plus a
+     * server-side lease. This signal IS the link state: bind it, do not poll it.
      */
     get loggedIn(): Signal<boolean>;
     /** `true` while an authentication is in flight. */
@@ -1262,4 +1290,4 @@ declare class EvolutionService {
 }
 
 export { AccountService, ComplianceService, ERPComplianceActivityState, ERPComplianceLawOrigin, ERPComplianceLawState, ERPComplianceLawsSelectionType, ERPComplianceNotificationLimit, ERPComplianceProfileFlags, ERPComplianceProfileRole, ERPComplianceRegisterNotificationType, ERPComplianceRegisterSiteImportOptions, ERPComplianceScope, ERPExportFormat, ERPExportPart, ERPExportSource, ERPExportType, ERPModule, ERPPlace, ERPPlacePermission, ERPRecurrenceFrequencyType, EVOLUTION_ACTIVE_ACCOUNT_KEY, EvolutionComplianceActivityStates, EvolutionComplianceContextInfo, EvolutionComplianceLawChangeStates, EvolutionComplianceLawOrigins, EvolutionComplianceLawStates, EvolutionComplianceNotificationLimits, EvolutionComplianceNotifications, EvolutionComplianceObligationAuthorities, EvolutionComplianceObligationTypes, EvolutionComplianceProfileFlags, EvolutionComplianceProfileRoles, EvolutionComplianceScopes, EvolutionMessages, EvolutionRecurrenceFrequencyTypes, EvolutionService, EvolutionServiceFlags, LoginService, evolutionAuthInterceptor };
-export type { ComplianceRegisterUsersResultModel, EvolutionChangeContextModel, EvolutionChangeContextResultModel, EvolutionComplianceActivitiesAddParams, EvolutionComplianceActivity, EvolutionComplianceLaswExportParams, EvolutionComplianceLaw, EvolutionComplianceLawDocumentInfo, EvolutionComplianceLawReference, EvolutionComplianceLawsAddParams, EvolutionComplianceRegister, EvolutionComplianceRegisterProfile, EvolutionComplianceRegisterSite, EvolutionContextInfo, EvolutionExportModel, EvolutionLicenceModuleInfo, EvolutionLoginInfo, EvolutionLoginResult, EvolutionPermission, EvolutionPlacePermission, EvolutionPlaceable, EvolutionQueryRegisterProfilesModel, EvolutionRecoverPasswordModel, EvolutionRegisterProfileSiteInfo, EvolutionRegisterProfileUserInfo, EvolutionResetPasswordModel, EvolutionUpdateUserSettingsModel, EvolutionUserInfo, EvolutionUserLink, EvolutionUserModuleInfo };
+export type { ComplianceRegisterUsersResultModel, EvolutionChangeContextModel, EvolutionChangeContextResultModel, EvolutionComplianceActivitiesAddParams, EvolutionComplianceActivity, EvolutionComplianceLaswExportParams, EvolutionComplianceLaw, EvolutionComplianceLawDocumentInfo, EvolutionComplianceLawReference, EvolutionComplianceLawsAddParams, EvolutionComplianceRegister, EvolutionComplianceRegisterProfile, EvolutionComplianceRegisterSite, EvolutionContextInfo, EvolutionExportModel, EvolutionLicenceModuleInfo, EvolutionLoginInfo, EvolutionLoginResult, EvolutionPermission, EvolutionPlacePermission, EvolutionPlaceable, EvolutionQueryRegisterProfilesModel, EvolutionRecoverPasswordModel, EvolutionRegisterProfileSiteInfo, EvolutionRegisterProfileUserInfo, EvolutionResetPasswordModel, EvolutionSessionStatus, EvolutionUpdateUserSettingsModel, EvolutionUserInfo, EvolutionUserLink, EvolutionUserModuleInfo };