Angular SDK Quickstart

npm install @hawcx/angular

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideHawcx } from '@hawcx/angular';
import { routes } from './app.routes';

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

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

export const routes: Routes = [
  { path: 'dashboard', loadComponent: () => import('./dashboard.component').then(m => m.DashboardComponent), canActivate: [authGuard()] },
  { path: 'login', loadComponent: () => import('./login.component').then(m => m.LoginComponent), canActivate: [guestGuard()] },
];

provideHawcx({
  configId: 'YOUR_CONFIG_ID',
  interceptor: { excludeUrls: [/^\/api\/public/, /^https:\/\/cdn\./] },
  // interceptor: false,  // register it yourself instead
});

providers: [
  provideHawcxService({ configId: 'YOUR_CONFIG_ID' }),
  provideHttpClient(withInterceptors([myInterceptor, hawcxInterceptor()])),
]

import { Component, inject } from '@angular/core';
import { AsyncPipe } from '@angular/common';
import { HawcxService } from '@hawcx/angular';

@Component({
  standalone: true,
  selector: 'app-login',
  imports: [AsyncPipe],
  template: `
    @if (hawcx.state$ | async; as state) {
      @switch (state.status) {
        @case ('idle') {
          <button (click)="hawcx.start('[email protected]')">Sign in</button>
        }
        @case ('loading') {
          <p>Loading...</p>
        }
        @case ('step') {
          <p>Step: {{ state.step.type }}</p>
        }
        @case ('completed') {
          <p>Signed in.</p>
        }
        @case ('error') {
          <p>{{ state.error.message }}</p>
          <button (click)="hawcx.reset()">Try again</button>
        }
      }
    }
  `,
})
export class LoginComponent {
  readonly hawcx = inject(HawcxService);
}

import { Component, inject } from '@angular/core';
import { Router } from '@angular/router';
import { HawcxAuthComponent } from '@hawcx/angular';
import type { AuthResult, AuthError } from '@hawcx/angular';

@Component({
  standalone: true,
  selector: 'app-login',
  imports: [HawcxAuthComponent],
  template: `
    <hawcx-auth
      flowType="signin"
      [identifier]="email"
      (authSuccess)="onSuccess($event)"
      (authError)="onError($event)"
      (cancelled)="onCancelled()">
    </hawcx-auth>
  `,
})
export class LoginComponent {
  private readonly router = inject(Router);
  email = '';

  // This is Angular's own AuthResult, not core's. See Backend Exchange below.
  onSuccess(result: AuthResult) {
    if (result.tokens) {
      // tokenEndpoint was configured and autoExchangeToken was left on,
      // so your backend has already returned tokens.access_token.
      this.router.navigateByUrl('/dashboard');
      return;
    }
    // Otherwise redeem result.authCode + result.codeVerifier yourself.
  }

  // Only fatal errors reach this output; retryable ones are handled in-component.
  onError(err: AuthError) {
    console.error(err.code, err.message);
  }

  onCancelled() {
    this.email = '';
  }
}

// Throws if the flow has not completed.
const result = await this.hawcx.completeAuth();

if (result.tokens) {
  // completeAuth() POSTed { code, code_verifier } to your tokenEndpoint,
  // and result.tokens is the TokenResponse your backend returned.
  // The access token is now stored and attached to outgoing requests.
}

import { Component, inject } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { Router } from '@angular/router';
import { HawcxService } from '@hawcx/angular';
import { filter, take } from 'rxjs/operators';

@Component({
  standalone: true,
  selector: 'app-exchange',
  template: `<p>Finishing sign-in...</p>`,
})
export class ExchangeComponent {
  private readonly hawcx = inject(HawcxService);
  private readonly http = inject(HttpClient);
  private readonly router = inject(Router);

  constructor() {
    // take(1) completes the stream, so this subscription needs no teardown.
    this.hawcx.completion$
      .pipe(filter(Boolean), take(1))
      .subscribe((completion) => {
        // completion is CoreAuthResult
        this.http
          .post('/api/hawcx/exchange-manual', {
            authCode: completion.authCode,
            codeVerifier: completion.codeVerifier,
          })
          .subscribe(() => this.router.navigateByUrl('/'));
      });
  }
}

import { Component, inject } from '@angular/core';
import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
import { AuthErrorCategory, HawcxService } from '@hawcx/angular';

@Component({
  standalone: true,
  selector: 'app-login-errors',
  template: `<p>{{ message }}</p>`,
})
export class LoginErrorsComponent {
  private readonly hawcx = inject(HawcxService);
  message = '';

  constructor() {
    // error$ never completes, so it needs teardown. takeUntilDestroyed() has to
    // run in an injection context, and a field initialiser or constructor is one.
    this.hawcx.error$.pipe(takeUntilDestroyed()).subscribe((error) => {
      if (!error) {
        this.message = '';
        return;
      }

      switch (error.category) {
        case AuthErrorCategory.RETRYABLE:
          // Transient. Retry the same action.
          this.message = 'Something went wrong. Try that again.';
          break;
        case AuthErrorCategory.USER_ACTION:
          // The user has to fix something (wrong code, bad phone number).
          this.message = error.message;
          break;
        case AuthErrorCategory.FATAL:
          // Unrecoverable. Start over.
          this.hawcx.reset();
          this.message = 'Sign-in failed. Please start again.';
          break;
      }
    });
  }
}