@metigan/angular 1.0.2 → 1.0.3

package/.gitattributes

@@ -0,0 +1,31 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# Source files - ensure LF line endings
+*.ts text eol=lf
+*.js text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+
+# Compiled JavaScript files - ensure LF line endings
+*.mjs text eol=lf
+*.d.ts text eol=lf
+
+# Config files - ensure LF line endings
+.npmignore text eol=lf
+*.npmignore text eol=lf
+yarn.lock text eol=lf
+package-lock.json text eol=lf
+
+# Binary files
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary

package/README.md

@@ -1,46 +1,94 @@
 # Metigan Angular SDK
 
-Official Metigan SDK for Angular. Send emails, manage forms, contacts, and audiences with ease in your Angular applications.
+[![npm version](https://img.shields.io/npm/v/@metigan/angular)](https://www.npmjs.com/package/@metigan/angular)
+[![npm downloads](https://img.shields.io/npm/dm/@metigan/angular)](https://www.npmjs.com/package/@metigan/angular)
+[![License](https://img.shields.io/npm/l/@metigan/angular)](LICENSE)
+
+Official Angular SDK for the Metigan API. Send emails, manage contacts, audiences, templates, and forms with ease in your Angular applications.
+
+## ✨ Features
+
+- 📧 **Send Emails** - Send HTML emails with attachments, CC, BCC, and templates
+- 👥 **Manage Contacts** - Create, update, list, and manage contact subscriptions
+- 🎯 **Audiences** - Organize contacts into audiences and track statistics
+- 📝 **Forms** - Submit and manage form data
+- 🎨 **Templates** - Use email templates with dynamic variables
+- 🔄 **RxJS Observables** - All methods return Observables for reactive programming
+- ⚡ **TypeScript** - Full TypeScript support with type definitions
+- 🛡️ **Error Handling** - Comprehensive error handling with typed exceptions
+- 🔌 **Angular 15+** - Supports Angular 15, 16, 17, 18, 19, 20, and 21
+- 📦 **Standalone Support** - Works with both NgModules and Standalone Components
+
+## 📋 Requirements
+
+- **Angular**: 15.0.0 or higher (15, 16, 17, 18, 19, 20, 21)
+- **RxJS**: 7.0.0 or higher
+- **TypeScript**: 4.9.0 or higher
 
 ## 📦 Installation
 
+Install via npm:
+
 ```bash
 npm install @metigan/angular
-# or
+```
+
+Or via yarn:
+
+```bash
 yarn add @metigan/angular
 ```
 
+## 🔑 Getting Your API Key
+
+Get your API key from the [Metigan Dashboard](https://app.metigan.com/api-keys).
+
+1. Sign in to your Metigan account
+2. Navigate to **Settings** → **API Keys**
+3. Create a new API key or use an existing one
+4. Copy the API key and use it in your application
+
+> ⚠️ **Security Note**: Never expose your API key in client-side code. For client-side usage, consider using environment-specific keys or implementing a proxy server.
+
 ## 🚀 Quick Start
 
-### 1. Import the Module
+### Using NgModules (Angular 15+)
+
+#### 1. Import the Module
 
 In your `app.module.ts`:
 
 ```typescript
 import { NgModule } from '@angular/core';
+import { BrowserModule } from '@angular/platform-browser';
 import { MetiganModule } from '@metigan/angular';
 
+import { AppComponent } from './app.component';
+
 @NgModule({
+  declarations: [AppComponent],
   imports: [
+    BrowserModule,
     MetiganModule.forRoot({
       apiKey: 'your-api-key'
     })
-  ]
+  ],
+  bootstrap: [AppComponent]
 })
 export class AppModule { }
 ```
 
-### 2. Use in Components
+#### 2. Use in Components
 
 ```typescript
-import { Component, OnInit } from '@angular/core';
+import { Component } from '@angular/core';
 import { MetiganService } from '@metigan/angular';
 
 @Component({
   selector: 'app-my-component',
   template: '<button (click)="sendEmail()">Send Email</button>'
 })
-export class MyComponent implements OnInit {
+export class MyComponent {
   constructor(private metigan: MetiganService) {}
 
   sendEmail() {
@@ -62,19 +110,22 @@ export class MyComponent implements OnInit {
 }
 ```
 
-### Alternative: Manual Initialization
+### Using Standalone Components (Angular 17+)
+
+For Standalone Components, use manual initialization:
 
-If you prefer to initialize manually (useful for dynamic API keys):
+For Standalone Components, you can initialize manually:
 
 ```typescript
 import { Component, OnInit } from '@angular/core';
 import { MetiganService } from '@metigan/angular';
 
 @Component({
-  selector: 'app-my-component',
-  template: ''
+  selector: 'app-root',
+  standalone: true,
+  template: '<button (click)="sendEmail()">Send Email</button>'
 })
-export class MyComponent implements OnInit {
+export class AppComponent implements OnInit {
   constructor(private metigan: MetiganService) {}
 
   ngOnInit() {
@@ -85,6 +136,18 @@ export class MyComponent implements OnInit {
       retryCount: 3
     });
   }
+
+  sendEmail() {
+    this.metigan.email.sendEmail({
+      from: 'sender@example.com',
+      recipients: ['recipient@example.com'],
+      subject: 'Hello!',
+      content: '<h1>Welcome</h1><p>Thank you for signing up.</p>'
+    }).subscribe({
+      next: (response) => console.log('Sent:', response),
+      error: (error) => console.error('Error:', error)
+    });
+  }
 }
 ```
 
@@ -146,7 +209,11 @@ this.metigan.email.sendEmail({
   from: 'sender@example.com',
   recipients: ['recipient@example.com'],
   subject: 'Welcome Email',
-  templateId: 'template-123'
+  templateId: 'template-123',
+  variables: {
+    name: 'John Doe',
+    company: 'Acme Inc'
+  }
 }).subscribe({
   next: (response) => console.log('Sent'),
   error: (error) => console.error('Error:', error)
@@ -419,7 +486,7 @@ this.metigan.audiences.merge(
 });
 ```
 
-## 📧 Templates Module
+## 🎨 Templates Module
 
 ### List Templates
 
@@ -448,15 +515,14 @@ this.metigan.templates.get('template-123').subscribe({
 
 ## ⚙️ Configuration
 
-### Module Configuration
+### Module Configuration (NgModules)
 
 ```typescript
 MetiganModule.forRoot({
   apiKey: 'your-api-key',
-  userId: 'user-123',              // Optional: User ID for logging
-  timeout: 60000,                  // Optional: Request timeout in ms
-  retryCount: 5,                   // Optional: Number of retries
-  retryDelay: 2000,                // Optional: Delay between retries in ms
+  timeout: 60000,                  // Optional: Request timeout in ms (default: 30000)
+  retryCount: 5,                   // Optional: Number of retries (default: 3)
+  retryDelay: 2000,                // Optional: Delay between retries in ms (default: 2000)
   apiUrl: 'https://api.metigan.com' // Optional: Custom API URL
 })
 ```
@@ -473,53 +539,30 @@ this.metigan.initialize({
 });
 ```
 
-## 🛡️ Error Handling
+### Environment Configuration
 
-All services return RxJS Observables, so use standard error handling:
+For better security, use environment variables:
 
+**environment.ts**:
 ```typescript
-import { MetiganError, ValidationError, ApiError } from '@metigan/angular';
-
-this.metigan.email.sendEmail(options).subscribe({
-  next: (response) => {
-    // Success
-  },
-  error: (error) => {
-    if (error instanceof ValidationError) {
-      console.error('Invalid data:', error.message);
-    } else if (error instanceof ApiError) {
-      console.error(`API error (${error.statusCode}):`, error.message);
-    } else if (error instanceof MetiganError) {
-      console.error('Metigan error:', error.message);
-    } else {
-      console.error('Unknown error:', error);
-    }
-  }
-});
+export const environment = {
+  production: false,
+  metiganApiKey: 'your-api-key'
+};
 ```
 
-## 📝 Using Individual Services
-
-If you only need a specific service:
-
+**app.module.ts**:
 ```typescript
-import { MetiganEmailService } from '@metigan/angular';
+import { environment } from './environments/environment';
 
-constructor(private emailService: MetiganEmailService) {}
-
-ngOnInit() {
-  this.emailService.initialize('your-api-key');
-  
-  this.emailService.sendEmail({
-    from: 'sender@example.com',
-    recipients: ['recipient@example.com'],
-    subject: 'Test',
-    content: '<p>Hello</p>'
-  }).subscribe({
-    next: (response) => console.log('Sent'),
-    error: (error) => console.error('Error:', error)
-  });
-}
+@NgModule({
+  imports: [
+    MetiganModule.forRoot({
+      apiKey: environment.metiganApiKey
+    })
+  ]
+})
+export class AppModule { }
 ```
 
 ## 🔄 RxJS Observables
@@ -554,7 +597,12 @@ export class MyComponent implements OnDestroy {
   private subscription = new Subscription();
 
   sendEmail() {
-    const sub = this.metigan.email.sendEmail(options).subscribe({
+    const sub = this.metigan.email.sendEmail({
+      from: 'sender@example.com',
+      recipients: ['recipient@example.com'],
+      subject: 'Test',
+      content: '<p>Hello</p>'
+    }).subscribe({
       next: (response) => console.log('Sent'),
       error: (error) => console.error('Error:', error)
     });
@@ -568,6 +616,203 @@ export class MyComponent implements OnDestroy {
 }
 ```
 
+### Using takeUntil Pattern
+
+```typescript
+import { Component, OnDestroy } from '@angular/core';
+import { Subject } from 'rxjs';
+import { takeUntil } from 'rxjs/operators';
+
+export class MyComponent implements OnDestroy {
+  private destroy$ = new Subject<void>();
+
+  loadTemplates() {
+    this.metigan.templates.list()
+      .pipe(takeUntil(this.destroy$))
+      .subscribe({
+        next: (response) => console.log('Templates:', response),
+        error: (error) => console.error('Error:', error)
+      });
+  }
+
+  ngOnDestroy() {
+    this.destroy$.next();
+    this.destroy$.complete();
+  }
+}
+```
+
+## 🛡️ Error Handling
+
+All services return RxJS Observables, so use standard error handling:
+
+```typescript
+import { MetiganError, ValidationError, ApiError } from '@metigan/angular';
+
+this.metigan.email.sendEmail(options).subscribe({
+  next: (response) => {
+    // Success
+    console.log('Email sent successfully');
+  },
+  error: (error) => {
+    if (error instanceof ValidationError) {
+      console.error('Invalid data:', error.message);
+      // Handle validation errors
+    } else if (error instanceof ApiError) {
+      console.error(`API error (${error.statusCode}):`, error.message);
+      // Handle API errors (4xx, 5xx)
+      if (error.statusCode === 401) {
+        // Unauthorized - check API key
+      } else if (error.statusCode === 429) {
+        // Rate limited - retry after delay
+      }
+    } else if (error instanceof MetiganError) {
+      console.error('Metigan error:', error.message);
+      // Handle general Metigan errors
+    } else {
+      console.error('Unknown error:', error);
+      // Handle unexpected errors
+    }
+  }
+});
+```
+
+## 📝 Using Individual Services
+
+If you only need a specific service, you can inject it directly:
+
+```typescript
+import { MetiganEmailService } from '@metigan/angular';
+
+@Component({
+  selector: 'app-email',
+  template: ''
+})
+export class EmailComponent {
+  constructor(private emailService: MetiganEmailService) {}
+
+  ngOnInit() {
+    // Initialize the service
+    this.emailService.initialize('your-api-key');
+    
+    // Use the service
+    this.emailService.sendEmail({
+      from: 'sender@example.com',
+      recipients: ['recipient@example.com'],
+      subject: 'Test',
+      content: '<p>Hello</p>'
+    }).subscribe({
+      next: (response) => console.log('Sent'),
+      error: (error) => console.error('Error:', error)
+    });
+  }
+}
+```
+
+Available services:
+- `MetiganEmailService`
+- `MetiganFormsService`
+- `MetiganContactsService`
+- `MetiganAudiencesService`
+- `MetiganTemplatesService`
+
+## 🧪 Testing
+
+When testing components that use Metigan services, you can mock the services:
+
+```typescript
+import { TestBed } from '@angular/core/testing';
+import { of, throwError } from 'rxjs';
+import { MetiganService } from '@metigan/angular';
+
+describe('MyComponent', () => {
+  let mockMetiganService: jasmine.SpyObj<MetiganService>;
+
+  beforeEach(() => {
+    mockMetiganService = jasmine.createSpyObj('MetiganService', ['email']);
+    mockMetiganService.email = jasmine.createSpyObj('email', ['sendEmail']);
+    
+    TestBed.configureTestingModule({
+      providers: [
+        { provide: MetiganService, useValue: mockMetiganService }
+      ]
+    });
+  });
+
+  it('should send email', () => {
+    mockMetiganService.email.sendEmail.and.returnValue(
+      of({ success: true, message: 'Email sent' })
+    );
+    
+    // Test your component
+  });
+});
+```
+
+## 🐛 Troubleshooting
+
+### "API key is required" Error
+
+Make sure you've initialized the service with an API key:
+
+```typescript
+// For NgModules
+MetiganModule.forRoot({ apiKey: 'your-api-key' })
+
+// For manual initialization
+this.metigan.initialize({ apiKey: 'your-api-key' })
+```
+
+### Observable Not Subscribing
+
+Make sure you're subscribing to the Observable:
+
+```typescript
+// ❌ Wrong - nothing happens
+this.metigan.email.sendEmail(options);
+
+// ✅ Correct - subscribes to the Observable
+this.metigan.email.sendEmail(options).subscribe({
+  next: (response) => console.log('Sent'),
+  error: (error) => console.error('Error:', error)
+});
+```
+
+### Memory Leaks
+
+Always unsubscribe from Observables to prevent memory leaks:
+
+```typescript
+// Using async pipe (recommended)
+templates$ = this.metigan.templates.list();
+
+// Using takeUntil pattern
+private destroy$ = new Subject<void>();
+this.metigan.templates.list()
+  .pipe(takeUntil(this.destroy$))
+  .subscribe(...);
+
+// Using Subscription
+private subscription = new Subscription();
+this.subscription.add(
+  this.metigan.email.sendEmail(...).subscribe(...)
+);
+```
+
+### TypeScript Errors
+
+Make sure you have TypeScript 4.9.0 or higher and Angular 15+ installed:
+
+```bash
+npm install typescript@^4.9.0 --save-dev
+```
+
+## 📚 Additional Resources
+
+- [Angular Documentation](https://angular.io/docs)
+- [RxJS Documentation](https://rxjs.dev/)
+- [TypeScript Documentation](https://www.typescriptlang.org/docs/)
+
 ## 📄 License
 
 MIT © Metigan
@@ -577,8 +822,12 @@ MIT © Metigan
 - [Documentation](https://docs.metigan.com)
 - [Dashboard](https://app.metigan.com)
 - [API Reference](https://docs.metigan.com/api)
-- [GitHub](https://github.com/metigan/angular)
+- [GitHub Repository](https://github.com/metigan/angular)
+- [Issue Tracker](https://github.com/metigan/angular/issues)
+
+## 💬 Support
 
-# angular
-
-
+For support, please:
+- Check the [Documentation](https://docs.metigan.com)
+- Open an issue on [GitHub](https://github.com/metigan/angular/issues)
+- Contact support at support@metigan.com

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metigan/angular",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Official Metigan SDK for Angular - Email, Forms, Contacts, and Audiences management",
   "author": "Metigan <support@metigan.com>",
   "license": "MIT",

package/dist/LICENSE

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Metigan
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-