@ratespecial/logto-angular 1.0.0

package/types/ratespecial-logto-angular.d.ts

@@ -0,0 +1,270 @@
+import LogtoClient, { AccessTokenClaims, IdTokenClaims, LogtoConfig } from '@logto/browser';
+import { Observable } from 'rxjs';
+import * as i0 from '@angular/core';
+import { InjectionToken, EnvironmentProviders, OnInit } from '@angular/core';
+import { Routes, CanActivateFn } from '@angular/router';
+import { HttpInterceptorFn } from '@angular/common/http';
+
+/**
+ * Angular-friendly facade over the promise-based `@logto/browser` client. Owns the
+ * authenticated-state signal, sign-in/out, and resource-scoped token access.
+ */
+declare class AuthService {
+    private router;
+    private client;
+    private routing;
+    private logoutHooks;
+    private authenticated$;
+    /**
+     * Authenticated state as a stream. Backed by a `BehaviorSubject`, so it replays the current
+     * value on subscribe (order-independent for late subscribers) and only emits on change.
+     */
+    readonly isAuthenticated$: Observable<boolean>;
+    /**
+     * Re-reads the client's authenticated state (checks for a stored session; no network) and
+     * pushes it to the stream. Returns the resolved value.
+     */
+    refreshAuthState(): Promise<boolean>;
+    /** Begin a sign-in flow with Logto (full-page redirect to the hosted UI). */
+    signIn(redirectUri?: string): void;
+    /** Complete the OAuth callback, then refresh local auth state. */
+    handleCallback(callbackUri: string): Promise<void>;
+    /**
+     * Fetch a resource-scoped JWT. The client refreshes/caches transparently, so this is safe to
+     * call on every request. Omit `resource` for an opaque (userinfo) token.
+     */
+    getAccessToken(resource?: string): Promise<string>;
+    /** Decoded claims of the resource-scoped access token (e.g. to inspect `scope`). */
+    getAccessTokenClaims(resource?: string): Promise<AccessTokenClaims>;
+    /**
+     * Decoded claims of the ID token (e.g. `sub`, `name`, `email`, `picture`). Reads the token
+     * already in storage and decodes it locally — no network call.
+     */
+    getIdTokenClaims(): Promise<IdTokenClaims>;
+    /** Sign out via Logto and reset local state. */
+    logout(): void;
+    protected fireLogoutHooks(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AuthService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AuthService>;
+}
+
+/**
+ * Facade for tracking the last visited route, used to restore navigation after login.
+ * Backed by sessionStorage so the value is scoped to the browser session.
+ */
+declare class HistoryService {
+    setLastVisitedRoute(route: string): void;
+    getLastVisitedRoute(): string | null;
+    clearLastVisitedRoute(): void;
+    consumeLastVisitedRoute(): string | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<HistoryService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<HistoryService>;
+}
+
+/**
+ * Maps outgoing request URLs to the Logto API resource whose access token the HTTP
+ * interceptor should attach. This is the one piece `@logto/browser` does not model —
+ * the SDK issues per-resource tokens but has no concept of which requests need them.
+ */
+interface SecureRouteMapping {
+    /** Logto API resource indicator to fetch a token for. */
+    resource: string;
+    /** Request URL prefixes (matched with `startsWith`) that require this resource's token. */
+    routes: string[];
+}
+/**
+ * App-level routing/behavior config that sits alongside the native `LogtoConfig`.
+ */
+interface LogtoRoutingConfig {
+    /** Path Logto redirects back to after sign-in. Used by `signIn()` and the route helper. */
+    callbackPath: string;
+    /** Path shown after sign-out. Used by `logout()` and the route helper. */
+    signedOutPath: string;
+    /**
+     * The primary API resource — used where a specific resource token is needed outside the
+     * interceptor (e.g. the Echo/Pusher auth header) and for the post-callback access gate.
+     * Defaults to the first `secureRoutes` resource when omitted.
+     */
+    primaryResource?: string;
+    /** Maps request URLs to the resource token the interceptor attaches. */
+    secureRoutes: SecureRouteMapping[];
+}
+/**
+ * Full auth configuration: `@logto/browser`'s native `LogtoConfig` (endpoint, appId,
+ * scopes, resources, prompt, …) plus the app-level `routing` addon this library needs.
+ * Provided app-wide under the `LOGTO_AUTH_CONFIG` token.
+ */
+interface LogtoAuthConfig extends LogtoConfig {
+    routing: LogtoRoutingConfig;
+    /** Message shown when an authenticated user has no scopes on the primary resource. */
+    noAccessMessage?: string;
+}
+
+/**
+ * The resolved auth configuration (native Logto config + `routing` addon). Every part of
+ * the library reads from this token, so nothing depends on the consuming app's environment.
+ */
+declare const LOGTO_AUTH_CONFIG: InjectionToken<LogtoAuthConfig>;
+/**
+ * The single, app-wide `@logto/browser` client. One client handles every resource:
+ * `getAccessToken(resource)` exchanges the shared refresh token for a resource-scoped JWT
+ * on demand and caches it.
+ */
+declare const LOGTO_CLIENT: InjectionToken<LogtoClient>;
+/**
+ * The primary API resource (`routing.primaryResource`, or the first secure-route resource).
+ * Used where a specific resource token is needed outside the HTTP interceptor — e.g. the
+ * Echo/Pusher auth header and the post-callback access gate.
+ */
+declare const PRIMARY_RESOURCE: InjectionToken<string>;
+/**
+ * A side-effect callback the library runs at the start of `AuthService.logout()`, before the
+ * sign-out redirect. Use for app teardown such as clearing client-side state or flushing caches.
+ *
+ * Return `void` for synchronous work or an `Observable` for async work. Async hooks are
+ * fire-and-forget — the library does not wait for them before logging the user off.
+ */
+type AuthLogoutHook = () => void | Observable<unknown>;
+/**
+ * Multi-provider token that collects `AuthLogoutHook` callbacks invoked during logout.
+ *
+ * Ordering between hooks follows Angular DI registration order. Register one hook per concern
+ * (state reset, cache flush, telemetry, …) rather than bundling them.
+ *
+ * Prefer registering hooks via `provideLogtoAuth({ logoutHookFactories: [...] })` over wiring
+ * this token directly — the factory form runs inside an injection context so the hook can
+ * use `inject()`.
+ *
+ * @example
+ * ```ts
+ * provideLogtoAuth({
+ *   endpoint: environment.logto.endpoint,
+ *   appId: environment.logto.appId,
+ *   routing: environment.logto.routing,
+ *   logoutHookFactories: [
+ *     () => {
+ *       const store = inject(Store);
+ *       return () => store.dispatch(new ClearState());
+ *     },
+ *   ],
+ * })
+ * ```
+ */
+declare const AUTH_LOGOUT_HOOK: InjectionToken<AuthLogoutHook[]>;
+
+/**
+ * Configuration passed to `provideLogtoAuth()`: the native `LogtoConfig` fields plus the
+ * `routing` addon, with optional logout hooks.
+ */
+interface LogtoAuthOptions extends LogtoAuthConfig {
+    /**
+     * Factories that produce `AuthLogoutHook` callbacks. Each factory runs inside an injection
+     * context, so it may use `inject()` to obtain app services (e.g. an NGXS `Store`) when
+     * building its hook. The hooks run at the start of `AuthService.logout()`.
+     *
+     * @example
+     * ```ts
+     * logoutHookFactories: [
+     *   () => {
+     *     const store = inject(Store);
+     *     return () => store.dispatch(new ClearState());
+     *   },
+     * ]
+     * ```
+     */
+    logoutHookFactories?: (() => AuthLogoutHook)[];
+}
+/**
+ * Wires up the auth library: provides the resolved config, constructs the single
+ * `@logto/browser` client, resolves the primary resource, contributes any
+ * `logoutHookFactories` to the `AUTH_LOGOUT_HOOK` multi-provider, and hydrates the
+ * authenticated-state signal from any existing session before the first guard runs.
+ *
+ * Returned providers are environment-scoped — call this once at the root provider list.
+ *
+ * @example
+ * ```ts
+ * providers: [
+ *   provideLogtoAuth({
+ *     ...environment.logto,
+ *     logoutHookFactories: [
+ *       () => {
+ *         const store = inject(Store);
+ *         return () => store.dispatch(new ClearState());
+ *       },
+ *     ],
+ *   }),
+ * ]
+ * ```
+ */
+declare function provideLogtoAuth(options: LogtoAuthOptions): EnvironmentProviders;
+
+/**
+ * Returns the auth routes (callback + signed-out landing) for the configured paths. Spread the
+ * result into the app's top-level `Routes`. Passing the same `routing` config used by
+ * `provideLogtoAuth()` keeps the route definitions and the redirect URIs from drifting apart.
+ *
+ * @example
+ * ```ts
+ * export const routes: Routes = [
+ *   {path: '', pathMatch: 'full', redirectTo: '/dashboard'},
+ *   ...getAuthRoutes(environment.logto.routing),
+ *   // ...app routes
+ * ];
+ * ```
+ */
+declare function getAuthRoutes(routing: Pick<LogtoRoutingConfig, 'callbackPath' | 'signedOutPath'>): Routes;
+
+/**
+ * Replaces `autoLoginPartialRoutesGuard`. Allows activation when a Logto session
+ * exists; otherwise records the attempted route and kicks off a sign-in redirect.
+ */
+declare const authGuard: CanActivateFn;
+
+/**
+ * Picks the configured resource whose `routes` match a request URL, so the interceptor can
+ * fetch the correct resource-scoped token. Returns `undefined` when no resource matches (the
+ * request goes out without an Authorization header).
+ */
+declare function resourceForUrl(url: string, secureRoutes: SecureRouteMapping[]): string | undefined;
+/**
+ * Matches the outgoing URL against each configured resource's `routes`; on a match it fetches
+ * that resource's access token (cached/refreshed by the Logto client) and attaches it as a
+ * Bearer header. Requests that match no resource pass through unauthenticated.
+ */
+declare const logtoTokenInterceptor: HttpInterceptorFn;
+
+/**
+ * If any /api call returns 401, sign the user out and send them to the login page.
+ */
+declare const logoutOnUnauthInterceptor: HttpInterceptorFn;
+
+/**
+ * Initializer that tracks the last visited route.
+ * Excludes auth routes (/auth/*) to prevent redirect loops.
+ */
+declare function initializeRouteTracking(): () => void;
+
+declare class CallbackComponent implements OnInit {
+    private authService;
+    private router;
+    private historyService;
+    private primaryResource;
+    private noAccessMessage;
+    loading: i0.WritableSignal<boolean>;
+    error: i0.WritableSignal<string | null>;
+    ngOnInit(): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CallbackComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CallbackComponent, "lib-callback", never, {}, {}, never, never, true, never>;
+}
+
+declare class SignedOutComponent {
+    private authService;
+    /** Restart the Logto sign-in flow (redirects to the hosted UI). */
+    signIn(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SignedOutComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<SignedOutComponent, "lib-signed-out", never, {}, {}, never, never, true, never>;
+}
+
+export { AUTH_LOGOUT_HOOK, AuthService, CallbackComponent, HistoryService, LOGTO_AUTH_CONFIG, LOGTO_CLIENT, PRIMARY_RESOURCE, SignedOutComponent, authGuard, getAuthRoutes, initializeRouteTracking, logoutOnUnauthInterceptor, logtoTokenInterceptor, provideLogtoAuth, resourceForUrl };
+export type { AuthLogoutHook, LogtoAuthConfig, LogtoAuthOptions, LogtoRoutingConfig, SecureRouteMapping };