@hawcx/angular

Angular SDK for Hawcx passwordless authentication. A thin, standalone-friendly wrapper around @hawcx/core providing a provider function, an injectable service, route guards, an HTTP interceptor, and drop-in UI components.

⚠️ Not yet published to public npm — do not run npm publish yet. This package depends on @hawcx/[email protected], which currently exists only in Hawcx's private CodeArtifact registry (public npm has @hawcx/core up to 3.0.0). Publishing to public npm now would produce a package that fails to install for every public consumer. Publishing is gated on the v3 web SDK line going public first — tracked in sdk_docs#56 (Workstream C/D).

Installation

npm install @hawcx/angular

@hawcx/core is a runtime dependency and is installed alongside this package. Requires Angular 17+ (@angular/common, @angular/core, @angular/forms, @angular/router) and rxjs 7.

Quick start

1. Register the providers

import { ApplicationConfig } from '@angular/core';
import { provideHawcx } from '@hawcx/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideHawcx({
      configId: 'YOUR_CONFIG_ID',
      tokenEndpoint: '/api/hawcx/exchange', // your backend endpoint that redeems the auth code
    }),
  ],
};

provideHawcx(options) wires HawcxService, the HAWCX_CONFIG token, and provideHttpClient(withInterceptors([hawcxInterceptor])) unless you pass interceptor: false. Options: configId (required), apiBase?, timeout?, tokenEndpoint?, debug?, interceptor?. Use provideHawcxService(config) if you want the service only, without the HTTP client / interceptor.

2. Drop in the auth component

<hawcx-auth
  flowType="signin"
  [identifier]="email"
  (authSuccess)="onSuccess($event)"
  (authError)="onError($event)">
</hawcx-auth>

3. Protect routes

import { authGuard, guestGuard } from '@hawcx/angular';

export const routes: Routes = [
  { path: 'dashboard', component: Dashboard, canActivate: [authGuard()] },        // requires auth
  { path: 'login', component: Login, canActivate: [guestGuard()] },               // only when signed out
];

authGuard(options?) / guestGuard(options?) accept { redirectTo } (defaults: /login and /).

HawcxService

Inject it for programmatic control. Methods (all return Promise<AuthState> unless noted):

| Method | Description | |---|---| | start(identifier, flowType?, device?) | Begin signin / signup / account_manage. flowType defaults to auto-detect. | | selectMethod(methodId) | Choose a method at the select_method step. | | submitCode(code) | Submit an email/SMS OTP. | | submitTotp(code) | Submit an authenticator code. | | submitPhone(phone) | Submit a phone number (E.164) during SMS enrollment. | | resend() | Resend the current OTP. | | cancel() / reset() | Cancel the flow / reset to idle (reset returns void). | | signOut() | Clear the access token and stored session (void). | | exchangeToken() | POST { code, code_verifier } to config.tokenEndpoint. |

Observables: state$, completion$, accessToken$, isAuthenticated$, isLoading$, error$, stepType$, notice$. Sync getters: getState(), getCompletion(), getAccessToken(), isAuthenticated().

Components

All standalone, prefixed hawcx-: hawcx-auth, hawcx-method-selector, hawcx-otp-input, hawcx-totp-setup, hawcx-phone-input, hawcx-await-approval.

HTTP interceptor

hawcxInterceptor(options?) attaches Authorization: Bearer <token> to outgoing requests and signs out on 401. Registered automatically by provideHawcx unless interceptor: false. Options: excludeUrls, signOutOn401, headerName, tokenPrefix.

License

MIT