@pixxle/oauth-ionic/readme.md

Pixxle OAuth authentication module for Ionic Angular applications - Direct implementation that works - Tested and proven

# @pixxle/oauth-ionic

Pixxle OAuth authentication module for Ionic Angular applications - Simple and working integration

## 🚀 Quick Start

### Prerequisites

1. **Create a Pixxle Login application** on the [Pixxle Developer Console](https://www.pixxle.dev)
2. Get your `client_id` and `client_secret`

### Installation

```bash
npm install @pixxle/oauth-ionic
```

### Configuration

Create `oauth.config.ts` in your app:

```typescript
export interface OAuthConfig {
  clientId: string;
  clientSecret: string;
  redirectUri: string;
  authUrl: string;
  tokenUrl: string;
  userInfoUrl: string;
  scope: string;
  authUrlFallback?: string;
  tokenUrlFallback?: string;
  userInfoUrlFallback?: string;
}

export const PIXXLE_OAUTH_CONFIG: OAuthConfig = {
  clientId: 'YOUR_CLIENT_ID', // Replace with your Pixxle client_id
  clientSecret: 'YOUR_CLIENT_SECRET', // Replace with your Pixxle client_secret
  redirectUri: 'com.pixxle.oauth://callback',
  authUrl: 'https://www.pixxle.me/oauth/v2/authorize',
  tokenUrl: 'https://www.pixxle.me/v2/oauth/token',
  userInfoUrl: 'https://api.pixxle.me/api/access/user',
  scope: 'user.full' // Choose scope based on your needs: https://www.pixxle.dev/documentation/pixxle-login-api/champs-dapplication-scopes-pour-les-connexions-oauth-pour-pixxle-login/
};
```

### Setup

Add to your `main.ts`:

```typescript
import { bootstrapApplication } from '@angular/platform-browser';
import { provideHttpClient } from '@angular/common/http';
import { providePixxleOAuth } from '@pixxle/oauth-ionic';
import { PIXXLE_OAUTH_CONFIG } from './oauth.config';

bootstrapApplication(AppComponent, {
  providers: [
    provideHttpClient(), // Required for HTTP requests
    providePixxleOAuth(PIXXLE_OAUTH_CONFIG)
  ]
});
```

## 🎯 Usage (Service Direct)

### Login Page

```typescript
// home.page.ts
import { Component, inject } from '@angular/core';
import { IonHeader, IonToolbar, IonTitle, IonContent } from '@ionic/angular/standalone';
import { PixxleOAuthService } from '@pixxle/oauth-ionic';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
  standalone: true,
  imports: [IonHeader, IonToolbar, IonTitle, IonContent]
})
export class HomePage {
  private oauthService = inject(PixxleOAuthService);

  async login() {
    try {
      await this.oauthService.login();
    } catch (error) {
      console.error('Erreur de connexion:', error);
    }
  }
}
```

```html
<!-- home.page.html -->
<ion-header [translucent]="true">
  <ion-toolbar>
    <ion-title>Blank</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content [fullscreen]="true">
  <ion-header collapse="condense">
    <ion-toolbar>
      <ion-title size="large">Blank</ion-title>
    </ion-toolbar>
  </ion-header>
  
  <div id="container">
    <strong>Ready to create an app?</strong>
    <p>Start with Ionic <a target="_blank" rel="noopener noreferrer" href="https://ionicframework.com/docs/components">UI Components</a></p>
    
    <button (click)="login()" class="pixxle-btn">
      <img src="/assets/logo-blanc.svg" alt="Pixxle" class="pixxle-icon">
      Se connecter avec Pixxle
    </button>
  </div>
</ion-content>
```

### User Profile Page

```typescript
// profile.page.ts
import { Component, inject } from '@angular/core';
import { IonHeader, IonToolbar, IonTitle, IonContent } from '@ionic/angular/standalone';
import { PixxleOAuthService, User } from '@pixxle/oauth-ionic';

@Component({
  selector: 'app-profile',
  templateUrl: 'profile.page.html',
  standalone: true,
  imports: [IonHeader, IonToolbar, IonTitle, IonContent]
})
export class ProfilePage {
  private oauthService = inject(PixxleOAuthService);
  user$ = this.oauthService.currentUser$;

  async logout() {
    await this.oauthService.logout();
  }
}
```

```html
<!-- profile.page.html -->
<ion-header [translucent]="true">
  <ion-toolbar>
    <ion-title>Profile</ion-title>
  </ion-toolbar>
</ion-header>

<ion-content [fullscreen]="true">
  <div *ngIf="user$ | async as user" class="user-profile">
    <div class="profile-header">
      <div class="avatar-container">
        <img
          [src]="getAvatarUrl(user.avatar)"
          [alt]="user.prenom + ' ' + user.nom"
          class="avatar"
          (error)="onAvatarError($event)">
      </div>
      <div class="user-info">
        <h3 class="user-name">{{ user.prenom }} {{ user.nom }}</h3>
        <p class="user-email">{{ user.email }}</p>
        <p *ngIf="user.phone" class="user-phone">{{ user.phone }}</p>
      </div>
    </div>
    <div class="profile-actions">
      <button class="logout-button" (click)="logout()">
        Se déconnecter
      </button>
    </div>
  </div>
</ion-content>
```

## 🔒 Route Protection

```typescript
// app.routes.ts
import { Routes } from '@angular/router';
import { PixxleAuthGuard } from '@pixxle/oauth-ionic';

export const routes: Routes = [
  {
    path: 'home',
    loadComponent: () => import('./home/home.page').then(m => m.HomePage),
    canActivate: [PixxleAuthGuard]
  }
];
```

## 📱 Capacitor Setup

### Android

Add to `android/app/src/main/AndroidManifest.xml`:

```xml
<activity>
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="com.pixxle.oauth" />
  </intent-filter>
</activity>
```

### iOS

Add to `ios/App/App/Info.plist`:

```xml
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.pixxle.oauth</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>com.pixxle.oauth</string>
    </array>
  </dict>
</array>
```

## 🎨 Styling with Pixxle Icon

### Installation de l'icône

L'icône Pixxle est automatiquement copiée dans votre projet lors de l'installation :

```bash
npm install @pixxle/oauth-ionic
# L'icône sera automatiquement copiée dans src/assets/logo-blanc.svg
```

Si l'icône n'est pas copiée automatiquement, copiez-la manuellement :

```bash
cp node_modules/@pixxle/oauth-ionic/templates/assets/logo-blanc.svg src/assets/
```

### Utilisation de l'icône

```html
<button (click)="login()" class="pixxle-btn">
  <img src="/assets/logo-blanc.svg" alt="Pixxle" class="pixxle-icon">
  Se connecter avec Pixxle
</button>
```

### CSS pour l'icône

Ajoutez ceci dans votre `src/global.scss` :

```scss
.pixxle-icon {
  width: 20px;
  height: 20px;
  margin-right: 8px;
}
```

### CSS complet pour le bouton

```css
.pixxle-btn {
  display: inline-flex;
  align-items: center;
  gap: 8px;
  padding: 12px 24px;
  border: none;
  border-radius: 8px;
  font-size: 16px;
  font-weight: 500;
  cursor: pointer;
  transition: all 0.2s;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  box-shadow: 0 4px 15px rgba(102, 126, 234, 0.3);
}

.pixxle-btn:hover:not(:disabled) {
  transform: translateY(-2px);
  box-shadow: 0 6px 20px rgba(102, 126, 234, 0.4);
}

.pixxle-btn:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}
```

/* User profile styles */
.user-profile {
  background: white;
  border-radius: 12px;
  padding: 24px;
  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.1);
  max-width: 400px;
  margin: 20px auto;
}

.profile-header {
  display: flex;
  align-items: center;
  gap: 16px;
  margin-bottom: 20px;
}

.avatar-container {
  flex-shrink: 0;
}

.avatar {
  width: 64px;
  height: 64px;
  border-radius: 50%;
  object-fit: cover;
  border: 3px solid #f0f0f0;
}

.user-info {
  flex: 1;
}

.user-name {
  margin: 0 0 4px 0;
  font-size: 18px;
  font-weight: 600;
  color: #333;
}

.user-email {
  margin: 0 0 2px 0;
  color: #666;
  font-size: 14px;
}

.user-phone {
  margin: 0;
  color: #888;
  font-size: 14px;
}

.profile-actions {
  text-align: center;
}

.logout-button {
  background: #dc3545;
  color: white;
  border: none;
  padding: 10px 20px;
  border-radius: 6px;
  cursor: pointer;
  font-size: 14px;
  transition: background 0.2s;
}

.logout-button:hover {
  background: #c82333;
}
```

## 🔧 API Reference

### PixxleOAuthService

```typescript
class PixxleOAuthService {
  currentUser$: Observable<User | null>;
  
  login(): Promise<void>;
  logout(): Promise<void>;
  getCurrentUser(): User | null;
}
```

### User Interface

```typescript
interface User {
  id: number;
  prenom: string;
  nom: string;
  email: string;
  phone: string;
  date_de_naissance: string;
  avatar?: string;
}
```

## 🚀 Version 2.1.4 Features

- ✅ **Service direct** - Simple and working integration
- ✅ **Route protection** - Auth guard included
- ✅ **Capacitor support** - Works on mobile
- ✅ **TypeScript support** - Full type safety
- ✅ **Pixxle icon** - 20px x 20px logo included
- ✅ **Installation automatique** - Icône copiée automatiquement

## 📦 Installation

```bash
npm install @pixxle/oauth-ionic@latest
```

## 🔗 Links

- [Pixxle Developer Console](https://www.pixxle.dev)
- [OAuth Scopes Documentation](https://www.pixxle.dev/documentation/pixxle-login-api/champs-dapplication-scopes-pour-les-connexions-oauth-pour-pixxle-login/)
- [Ionic Documentation](https://ionicframework.com/docs)
- [Capacitor Documentation](https://capacitorjs.com/docs)

## 📄 License

MIT