feat(angular): rebuild SDK on browser client (#1165)

* feat(angular): rebuild SDK on browser client

* fix(angular): refine authentication lifecycle

* refactor(angular): simplify initialization cleanup

* fix(angular): address initialization review feedback

Author: charIeszhao

.changeset/major-dolls-repeat.md

@@ -0,0 +1,5 @@
+---
+"@logto/angular": major
+---
+
+rebuild the Angular SDK on the Logto Browser client

packages/angular/README.md

@@ -1,3 +1,134 @@
-# Logto Angular helper
+# Logto Angular SDK
 
-This package provides a helper for Angular to use Logto.
+The Logto SDK for Angular applications. It is built on `@logto/browser` and exposes Angular-native dependency injection and Signals.
+
+## Installation
+
+```sh
+pnpm add @logto/angular
+```
+
+## Configuration
+
+Register Logto in the application config:
+
+```ts
+import { type ApplicationConfig } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { provideLogto, UserScope } from '@logto/angular';
+
+import { routes } from './app.routes';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideLogto({
+      endpoint: 'https://your-tenant.logto.app',
+      appId: 'your-app-id',
+      scopes: [UserScope.Email, UserScope.Organizations],
+      resources: ['https://api.example.com'],
+    }),
+    provideRouter(routes),
+  ],
+};
+```
+
+## Sign in and sign out
+
+Inject `LogtoService` and read its Signals directly from the template:
+
+```ts
+import { Component, inject } from '@angular/core';
+import { LogtoService } from '@logto/angular';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    @if (logto.isLoading()) {
+    <p>Loading…</p>
+    } @else if (logto.isAuthenticated()) {
+    <button type="button" (click)="signOut()">Sign out</button>
+    } @else {
+    <button type="button" (click)="signIn()">Sign in</button>
+    }
+  `,
+})
+export class AppComponent {
+  readonly logto = inject(LogtoService);
+
+  async signIn() {
+    await this.logto.signIn({
+      redirectUri: `${window.location.origin}/callback`,
+      postRedirectUri: window.location.origin,
+    });
+  }
+
+  async signOut() {
+    await this.logto.signOut(window.location.origin);
+  }
+}
+```
+
+## Handle the callback
+
+Register a dedicated callback route and complete the sign-in flow after browser rendering:
+
+```ts
+import { afterNextRender, Component, inject } from '@angular/core';
+import { LogtoService } from '@logto/angular';
+
+@Component({
+  standalone: true,
+  template: '<p>Completing sign-in…</p>',
+})
+export class CallbackComponent {
+  private readonly logto = inject(LogtoService);
+
+  constructor() {
+    afterNextRender(() => {
+      void (async () => {
+        const callbackUri = window.location.href;
+
+        if (await this.logto.isSignInRedirected(callbackUri)) {
+          await this.logto.handleSignInCallback(callbackUri);
+        }
+      })().catch(() => undefined);
+    });
+  }
+}
+```
+
+`LogtoService` also exposes resource-aware access tokens, organization tokens, ID-token claims, userinfo, token clearing, and an `error` Signal. See the [Angular sample](../angular-sample/) for a complete integration.
+
+## Server-side rendering
+
+Authentication state is restored from browser storage after the first browser render. Tokens are not exposed during server rendering. Use a server or BFF SDK when authenticated data is required while rendering on the server.
+
+## Migrating from v1
+
+Version 2 replaces the `angular-auth-oidc-client` configuration helper with a first-party Logto SDK:
+
+- Replace `provideAuth({ config: buildAngularAuthConfig(...) })` with `provideLogto(...)`.
+- Replace `OidcSecurityService` with `LogtoService`.
+- Pass redirect URIs to `signIn()` and `signOut()` instead of provider configuration.
+- Add a callback route that calls `handleSignInCallback()`.
+- Read `isLoading()`, `isAuthenticated()`, and `error()` Signals instead of subscribing to `checkAuth()`.
+
+Version 1 accepted only one `resource` string. Applications that needed multiple resources sometimes used a comma-separated workaround:
+
+```ts
+buildAngularAuthConfig({
+  // ...
+  resource: 'com.company.resource1,com.company.resource2',
+});
+```
+
+Version 2 supports the Logto resource array directly. Replace the workaround with separate array entries:
+
+```ts
+provideLogto({
+  // ...
+  resources: ['com.company.resource1', 'com.company.resource2'],
+});
+```
+
+Existing third-party session data is not migrated; users need to sign in once after upgrading.

packages/angular/package.json

@@ -23,30 +23,27 @@
     "precommit": "lint-staged",
     "check": "tsc --noEmit",
     "build": "rm -rf lib/ && tsc -p tsconfig.build.json --noEmit && rollup -c",
-    "lint": "eslint --ext .ts --ext .tsx src",
-    "prepack": "pnpm build"
+    "lint": "eslint --ext .ts src",
+    "test": "vitest",
+    "test:coverage": "vitest --silent --coverage",
+    "prepack": "pnpm build && pnpm test"
   },
   "dependencies": {
-    "@logto/js": "workspace:^",
-    "@silverhand/essentials": "^2.9.3"
+    "@logto/browser": "workspace:^"
   },
   "devDependencies": {
     "@silverhand/eslint-config": "^6.0.1",
-    "@silverhand/eslint-config-react": "^6.0.2",
     "@silverhand/ts-config": "^6.0.0",
-    "@silverhand/ts-config-react": "^6.0.0",
-    "angular-auth-oidc-client": "^20.0.3",
+    "@vitest/coverage-v8": "3.2.6",
     "eslint": "^8.57.0",
+    "happy-dom": "^20.0.8",
     "lint-staged": "^15.0.0",
     "prettier": "^3.0.0",
     "typescript": "^5.3.3",
     "vitest": "^3.2.6"
   },
   "peerDependencies": {
-    "rxjs": "^6.5.3 || ^7.4.0",
-    "@angular/core": "^20.0.0",
-    "@angular/common": "^20.0.0",
-    "@angular/router": "^20.0.0"
+    "@angular/core": "^20.0.0"
   },
   "eslintConfig": {
     "extends": "@silverhand"

packages/angular/src/index.ts

@@ -1,167 +1,32 @@
-import { Prompt, QueryKey, type SignInUriParameters, withReservedScopes } from '@logto/js';
-import { conditional } from '@silverhand/essentials';
-import { type OpenIdConfiguration } from 'angular-auth-oidc-client';
+export type {
+  AccessTokenClaims,
+  ClientAdapter,
+  IdTokenClaims,
+  InteractionMode,
+  LogtoClientErrorCode,
+  LogtoConfig,
+  LogtoErrorCode,
+  SignInOptions,
+  Storage,
+  UserInfoResponse,
+} from '@logto/browser';
 
-/** The Logto configuration object for Angular apps. */
-export type LogtoAngularConfig = {
-  /**
-   * The endpoint for the Logto server, you can get it from the integration guide
-   * or the team settings page of the Logto Console.
-   *
-   * @example https://foo.logto.app
-   */
-  endpoint: string;
-  /**
-   * The client ID of your application, you can get it from the integration guide
-   * or the application details page of the Logto Console.
-   */
-  appId: string;
-  /**
-   * The scopes (permissions) that your application needs to access.
-   * Scopes that will be added by default: `openid`, `offline_access` and `profile`.
-   */
-  scopes?: string[];
-  /**
-   * The API resource that your application needs to access.
-   *
-   * @see {@link https://docs.logto.io/docs/recipes/rbac/ | RBAC} to learn more about how to use
-   * role-based access control (RBAC) to protect API resources.
-   */
-  resource?: string;
-  /**
-   * @param redirectUri The redirect URI that the user will be redirected to after the sign-in flow
-   * is completed.
-   */
-  redirectUri: string;
-  /**
-   * @param postLogoutRedirectUri The URI that the user will be redirected to after the sign-out
-   * flow is completed.
-   */
-  postLogoutRedirectUri?: string;
-  /**
-   * The prompt parameter to be used for the authorization request.
-   *
-   * @default Prompt.Consent
-   */
-  prompt?: Prompt | Prompt[];
-  /**
-   * Whether to include reserved scopes (`openid`, `offline_access` and `profile`) in the scopes.
-   *
-   * @default true
-   */
-  includeReservedScopes?: boolean;
-  /**
-   * Login hint indicates the current user (usually an email address or a phone number).
-   *
-   * @link SignInUriParameters.loginHint
-   */
-  loginHint?: SignInUriParameters['loginHint'];
-  /**
-   * The first screen to be shown in the sign-in experience.
-   *
-   * @link SignInUriParameters.firstScreen
-   */
-  firstScreen?: SignInUriParameters['firstScreen'];
-  /**
-   * Identifiers used in the identifier sign-in, identifier register or reset password pages.
-   *
-   * Note: This parameter is applicable only when the `firstScreen` is set to either`identifierSignIn`
-   * or `identifierRegister`.
-   *
-   * @link SignInUriParameters.identifiers
-   */
-  identifiers?: SignInUriParameters['identifiers'];
-  /**
-   * Direct sign-in options.
-   *
-   * @link SignInUriParameters.directSignIn
-   */
-  directSignIn?: SignInUriParameters['directSignIn'];
-  /**
-   * Extra parameters to be appended to the sign-in URI.
-   *
-   * Note: The parameters should be supported by the authorization server.
-   *
-   * @link SignInUriParameters.extraParams
-   */
-  extraParams?: SignInUriParameters['extraParams'];
-};
+export {
+  BrowserStorage,
+  LogtoClientError,
+  LogtoError,
+  LogtoRequestError,
+  OidcError,
+  PersistKey,
+  Prompt,
+  ReservedResource,
+  ReservedScope,
+  UserScope,
+  buildOrganizationUrn,
+  getOrganizationIdFromUrn,
+  isLogtoRequestError,
+  organizationUrnPrefix,
+} from '@logto/browser';
 
-/**
- * A helper function to build the OpenID Connect configuration for `angular-auth-oidc-client`
- * using a Logto-friendly way.
- *
- * @example
- * ```ts
- * // A minimal example
- * import { buildAngularAuthConfig } from '@logto/js';
- * import { provideAuth } from 'angular-auth-oidc-client';
- *
- * provideAuth({
- *   config: buildAngularAuthConfig({
- *     endpoint: '<your-logto-endpoint>',
- *     appId: '<your-app-id>',
- *     redirectUri: '<your-app-redirect-uri>',
- *   }),
- * });
- * ```
- *
- * @param logtoConfig The Logto configuration object for Angular apps.
- * @returns The OpenID Connect configuration for `angular-auth-oidc-client`.
- * @see {@link https://angular-auth-oidc-client.com/ | angular-auth-oidc-client} to learn more
- * about how to use the library.
- */
-export const buildAngularAuthConfig = (logtoConfig: LogtoAngularConfig): OpenIdConfiguration => {
-  const {
-    endpoint,
-    appId: clientId,
-    scopes,
-    resource,
-    redirectUri: redirectUrl,
-    postLogoutRedirectUri,
-    prompt = Prompt.Consent,
-    includeReservedScopes = true,
-    loginHint,
-    identifiers,
-    firstScreen,
-    directSignIn,
-    extraParams,
-  } = logtoConfig;
-  const scope = includeReservedScopes ? withReservedScopes(scopes) : scopes?.join(' ');
-  const customParameters = {
-    ...conditional(resource && { [QueryKey.Resource]: resource }),
-    ...conditional(loginHint && { [QueryKey.LoginHint]: loginHint }),
-    ...conditional(firstScreen && { [QueryKey.FirstScreen]: firstScreen }),
-    ...conditional(identifiers && { [QueryKey.Identifier]: identifiers.join(' ') }),
-    ...conditional(
-      directSignIn && { [QueryKey.DirectSignIn]: `${directSignIn.method}:${directSignIn.target}` }
-    ),
-    ...extraParams,
-  };
-
-  return {
-    authority: new URL('/oidc', endpoint).href,
-    redirectUrl,
-    postLogoutRedirectUri,
-    clientId,
-    scope,
-    responseType: 'code',
-    autoUserInfo: !resource,
-    renewUserInfoAfterTokenRenew: !resource,
-    silentRenew: true,
-    useRefreshToken: true,
-    customParamsAuthRequest: {
-      prompt: Array.isArray(prompt) ? prompt.join(' ') : prompt,
-      ...customParameters,
-    },
-    customParamsCodeRequest: {
-      ...customParameters,
-    },
-    customParamsRefreshTokenRequest: {
-      ...customParameters,
-    },
-  };
-};
-
-export type { UserInfoResponse } from '@logto/js';
-export { UserScope } from '@logto/js';
+export { LOGTO_CLIENT, provideLogto, type LogtoAngularOptions } from './provider.js';
+export { LogtoService } from './service.js';