@metrifox/angular-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Metrifox
+
+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.

package/README.md

@@ -0,0 +1,487 @@
+# @metrifox/angular-sdk
+
+A fully-configurable **Angular SDK** providing ready-to-use components for SaaS and billing platforms including customer portals, pricing tables, and more.
+
+This is the official Angular version of the Metrifox SDK, mirroring the functionality of [@metrifox/react-sdk](https://www.npmjs.com/package/@metrifox/react-sdk).
+
+[![npm version](https://img.shields.io/npm/v/@metrifox/angular-sdk.svg)](https://www.npmjs.com/package/@metrifox/angular-sdk)
+[![license](https://img.shields.io/npm/l/@metrifox/angular-sdk.svg)](https://github.com/metrifox/metrifox-angular-sdk/blob/main/LICENSE)
+
+## Features
+
+- 🎨 **Fully Customizable** - Extensive theming support to match your brand
+- 📦 **Standalone Components** - Modern Angular standalone components (no NgModule required)
+- 🔥 **TypeScript** - Full type safety with comprehensive TypeScript definitions
+- 🚀 **Easy Integration** - Simple setup with minimal configuration
+- 📱 **Responsive** - Mobile-friendly components out of the box
+- ♿ **Accessible** - WCAG compliant components
+- 🌙 **Dark Mode** - Built-in dark mode support
+- ⚡ **Tree-shakeable** - Only import what you need
+
+## Requirements
+
+- Angular 17.0.0 or higher (compatible with Angular 17, 18, and 19)
+- RxJS 7.0.0 or higher
+
+## Installation
+
+```bash
+# Using pnpm (recommended)
+pnpm add @metrifox/angular-sdk
+
+# Using npm
+npm install @metrifox/angular-sdk
+
+# Using yarn
+yarn add @metrifox/angular-sdk
+```
+
+## Quick Start
+
+### 1. Provide the SDK (required for components)
+
+For standalone apps that use `<metrifox-customer-portal>` or `<metrifox-pricing-table>`, register the SDK in your app config so the components can inject `MetrifoxService`:
+
+```typescript
+// app.config.ts (Standalone)
+import { ApplicationConfig } from "@angular/core";
+import { provideMetrifox } from "@metrifox/angular-sdk";
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideMetrifox(), // provides HttpClient + MetrifoxService
+  ],
+};
+```
+
+### 2. Initialize the SDK
+
+Initialize Metrifox before using any components (e.g. in your root component’s `ngOnInit` or in a guard):
+
+```typescript
+import { MetrifoxService } from "@metrifox/angular-sdk";
+
+MetrifoxService.initialize({
+  clientKey: "your-metrifox-client-key",
+});
+```
+
+Or using the module approach:
+
+```typescript
+// app.module.ts
+import { MetrifoxModule } from "@metrifox/angular-sdk";
+
+@NgModule({
+  imports: [
+    MetrifoxModule.forRoot({
+      clientKey: "your-metrifox-client-key",
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### 3. Import Styles
+
+Add the SDK styles to your `angular.json`:
+
+```json
+{
+  "styles": ["src/styles.css", "node_modules/@metrifox/angular-sdk/styles.css"]
+}
+```
+
+Or import in your global `styles.css`:
+
+```css
+@import "@metrifox/angular-sdk/styles.css";
+```
+
+### 4. Use Components
+
+```typescript
+import { Component } from "@angular/core";
+import { CustomerPortalComponent } from "@metrifox/angular-sdk";
+
+@Component({
+  selector: "app-billing",
+  standalone: true,
+  imports: [CustomerPortalComponent],
+  template: ` <metrifox-customer-portal [customerKey]="'cust_123'" /> `,
+})
+export class BillingComponent {}
+```
+
+## Components
+
+### CustomerPortal
+
+Displays a customizable customer dashboard with plans, subscriptions, billing, and more.
+
+```typescript
+import { CustomerPortalComponent, SectionConfig } from "@metrifox/angular-sdk";
+
+@Component({
+  standalone: true,
+  imports: [CustomerPortalComponent],
+  template: `
+    <metrifox-customer-portal
+      [customerKey]="customerKey"
+      [sectionsConfig]="sections"
+      (dataLoaded)="onDataLoaded($event)"
+      (error)="onError($event)"
+    >
+    </metrifox-customer-portal>
+  `,
+})
+export class MyComponent {
+  customerKey = "cust_123";
+
+  sections: SectionConfig[] = [
+    { key: "subscription" },
+    { key: "plan" },
+    { key: "upcomingInvoice" },
+    { key: "billingHistory" },
+    { key: "paymentOverview" },
+    { key: "entitlementUsage" },
+    { key: "walletBalance" },
+  ];
+
+  onDataLoaded(data: CustomerData) {
+    console.log("Customer data loaded:", data);
+  }
+
+  onError(error: MetrifoxErrorEvent) {
+    console.error("Error:", error);
+  }
+}
+```
+
+#### CustomerPortal Inputs
+
+| Property         | Type              | Required | Description                        |
+| ---------------- | ----------------- | -------- | ---------------------------------- |
+| `customerKey`    | `string`          | Yes      | Unique identifier for the customer |
+| `sectionsConfig` | `SectionConfig[]` | No       | Configuration for portal sections  |
+
+#### CustomerPortal Outputs
+
+| Event        | Type                 | Description                          |
+| ------------ | -------------------- | ------------------------------------ |
+| `dataLoaded` | `CustomerData`       | Emitted when customer data is loaded |
+| `error`      | `MetrifoxErrorEvent` | Emitted when an error occurs         |
+
+#### Available Sections
+
+- `subscription` - Active subscription overview
+- `plan` - Current plan details
+- `upcomingInvoice` - Next invoice details
+- `billingHistory` - List of past transactions
+- `paymentOverview` - Payment methods
+- `entitlementUsage` - Feature/resource usage
+- `walletBalance` - Credit/wallet balance
+
+### PricingTable
+
+Displays subscription plans and one-time purchases.
+
+```typescript
+import { PricingTableComponent, PlanSelectEvent } from "@metrifox/angular-sdk";
+
+@Component({
+  standalone: true,
+  imports: [PricingTableComponent],
+  template: `
+    <metrifox-pricing-table
+      [checkoutUsername]="username"
+      [productKey]="productKey"
+      [plansOnly]="false"
+      [showTabHeader]="true"
+      (planSelected)="onPlanSelect($event)"
+      (purchaseSelected)="onPurchaseSelect($event)"
+    >
+    </metrifox-pricing-table>
+  `,
+})
+export class PricingComponent {
+  username = "your-checkout-username";
+  productKey = "your-product-key";
+
+  onPlanSelect(event: PlanSelectEvent) {
+    console.log("Plan selected:", event.plan);
+    console.log("Action:", event.action); // 'upgrade' | 'downgrade' | 'new' | 'current'
+  }
+
+  onPurchaseSelect(event: PurchaseSelectEvent) {
+    console.log("Purchase selected:", event.purchase);
+  }
+}
+```
+
+#### PricingTable Inputs
+
+| Property              | Type      | Required | Default | Description                                  |
+| --------------------- | --------- | -------- | ------- | -------------------------------------------- |
+| `checkoutUsername`    | `string`  | Yes      | -       | Username for checkout                        |
+| `productKey`          | `string`  | Yes      | -       | Product identifier                           |
+| `plansOnly`           | `boolean` | No       | `false` | Show only subscription plans                 |
+| `singlePurchasesOnly` | `boolean` | No       | `false` | Show only one-time purchases                 |
+| `showTabHeader`       | `boolean` | No       | `true`  | Show tab header for switching                |
+| `customerKey`         | `string`  | No       | -       | Current customer (to highlight current plan) |
+
+#### PricingTable Outputs
+
+| Event              | Type                  | Description                         |
+| ------------------ | --------------------- | ----------------------------------- |
+| `planSelected`     | `PlanSelectEvent`     | Emitted when a plan is selected     |
+| `purchaseSelected` | `PurchaseSelectEvent` | Emitted when a purchase is selected |
+| `dataLoaded`       | `PricingData`         | Emitted when pricing data is loaded |
+| `error`            | `MetrifoxErrorEvent`  | Emitted when an error occurs        |
+
+## Theming
+
+Configure themes during initialization:
+
+```typescript
+import { MetrifoxService, MetrifoxTheme } from "@metrifox/angular-sdk";
+
+const theme: MetrifoxTheme = {
+  customerPortal: {
+    tabs: {
+      background: "#111827",
+      borderColor: "#243044",
+      activeBackground: "#1f2937",
+      activeTextColor: "#3b82f6",
+      inactiveTextColor: "#9ca3af",
+    },
+    card: {
+      titleBackground: "#1f2937",
+      contentBackground: "#111827",
+      titleColor: "#f9fafb",
+      details: {
+        labelColor: "#cbd5e1",
+        valueColor: "#ffffff",
+      },
+    },
+    button: {
+      background: "#3b82f6",
+      textColor: "#ffffff",
+    },
+  },
+  pricingTable: {
+    card: {
+      background: "#ffffff",
+      borderColor: "#e5e7eb",
+      header: {
+        textColor: "#111827",
+      },
+      price: {
+        amountColor: "#111827",
+      },
+    },
+    button: {
+      background: "#2563eb",
+      textColor: "#ffffff",
+    },
+  },
+};
+
+MetrifoxService.initialize({
+  clientKey: "your-client-key",
+  theme,
+});
+```
+
+### Dark Mode
+
+The SDK supports dark mode out of the box:
+
+1. **Automatic** - Follows system preference (`prefers-color-scheme: dark`)
+2. **Manual** - Add `metrifox-dark` class or `data-theme="dark"` attribute
+
+```html
+<!-- Manual dark mode -->
+<div class="metrifox-dark">
+  <metrifox-customer-portal [customerKey]="key" />
+</div>
+```
+
+## Using the Service Directly
+
+Access Metrifox APIs programmatically:
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { MetrifoxService } from '@metrifox/angular-sdk';
+
+@Component({ ... })
+export class MyComponent {
+  private metrifoxService = inject(MetrifoxService);
+
+  loadCustomer() {
+    this.metrifoxService.getCustomerData('cust_123').subscribe({
+      next: (data) => console.log('Customer:', data),
+      error: (err) => console.error('Error:', err)
+    });
+  }
+
+  updateSubscription() {
+    this.metrifoxService.updateSubscription('cust_123', {
+      planId: 'plan_pro',
+      proration: 'create_prorations'
+    }).subscribe({
+      next: (result) => {
+        if (result.checkoutUrl) {
+          window.location.href = result.checkoutUrl;
+        }
+      }
+    });
+  }
+
+  checkFeatureAccess() {
+    this.metrifoxService.checkAccess('cust_123', 'api_calls').subscribe({
+      next: ({ hasAccess, remaining, limit }) => {
+        console.log(`Access: ${hasAccess}, Remaining: ${remaining}/${limit}`);
+      }
+    });
+  }
+
+  recordUsage() {
+    this.metrifoxService.recordUsage('cust_123', 'api_calls', 1).subscribe({
+      next: () => console.log('Usage recorded')
+    });
+  }
+}
+```
+
+## Custom Components
+
+Replace any section with your own component:
+
+```typescript
+// my-custom-plan.component.ts
+import { Component, Input } from "@angular/core";
+import {
+  CustomSectionComponentBase,
+  CustomerData,
+} from "@metrifox/angular-sdk";
+
+@Component({
+  selector: "app-custom-plan",
+  standalone: true,
+  template: `
+    <div class="custom-plan">
+      <h3>{{ customerData?.plan?.name }}</h3>
+      <p>Custom property: {{ customProp }}</p>
+    </div>
+  `,
+})
+export class MyCustomPlanComponent implements CustomSectionComponentBase {
+  @Input() customerData?: CustomerData;
+  @Input() customerKey?: string;
+  @Input() customProp?: string;
+}
+
+// Usage
+@Component({
+  template: `
+    <metrifox-customer-portal
+      [customerKey]="'cust_123'"
+      [sectionsConfig]="sections"
+    >
+    </metrifox-customer-portal>
+  `,
+})
+export class BillingComponent {
+  sections: SectionConfig[] = [
+    { key: "subscription" },
+    {
+      key: "plan",
+      component: MyCustomPlanComponent,
+      props: { customProp: "Hello!" },
+    },
+  ];
+}
+```
+
+## TypeScript Support
+
+The SDK is fully typed. Import types as needed:
+
+```typescript
+import type {
+  // Configuration
+  MetrifoxConfig,
+  MetrifoxTheme,
+
+  // Customer Portal
+  CustomerPortalTheme,
+  SectionConfig,
+  SectionKey,
+
+  // Pricing Table
+  PricingTableTheme,
+  PlanSelectEvent,
+  PurchaseSelectEvent,
+
+  // Data Models
+  CustomerData,
+  SubscriptionData,
+  PricingData,
+  PricingPlan,
+
+  // Events
+  MetrifoxErrorEvent,
+} from "@metrifox/angular-sdk";
+```
+
+## Migration from React SDK
+
+| React                   | Angular                        |
+| ----------------------- | ------------------------------ |
+| `metrifoxInit()`        | `MetrifoxService.initialize()` |
+| `<CustomerPortal />`    | `<metrifox-customer-portal>`   |
+| `<PricingTable />`      | `<metrifox-pricing-table>`     |
+| `customerKey` prop      | `[customerKey]` input          |
+| `onPlanSelect` callback | `(planSelected)` output        |
+
+## Testing with the demo playground
+
+The [metrifox-sdk-demo](https://github.com/metrifox/metrifox-sdk-demo) repo includes an **Angular SDK demo playground** that works like the React SDK demo: sidebar (Customer Portal / Pricing Table), config panel (API keys + Theme options), and live preview.
+
+To run the package against the demo playground:
+
+1. **Build the Angular SDK** (this repo):
+
+   ```bash
+   pnpm install
+   pnpm run build
+   ```
+
+2. **Run the demo** (in [metrifox-sdk-demo/angular-sdk](https://github.com/metrifox/metrifox-sdk-demo/tree/main/angular-sdk)):
+
+   ```bash
+   cd path/to/metrifox-sdk-demo/angular-sdk
+   npm install
+   npm run dev
+   ```
+
+   The demo’s `package.json` points to `file:../../metrifox-angular-sdk/dist`, so it uses your local build. Open `http://localhost:4200` and use the config panel to set Client Key, Customer Key (for the portal), and Theme options.
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Support
+
+- 📧 Email: support@metrifox.com
+- 📚 Documentation: https://docs.metrifox.com
+- 🐛 Issues: https://github.com/metrifox/metrifox-angular-sdk/issues
+
+## License
+
+MIT © [Metrifox](https://metrifox.com)