@metrifox/angular-sdk 0.0.2-beta.1 → 0.0.2-beta.2

package/README.md

@@ -1,46 +1,44 @@
-# @metrifox/angular-sdk
+# 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)
+## ⚠️ Version notice – breaking changes
 
-## Features
+**If you are upgrading from an earlier version of the SDK, please read this.**
 
-- 🎨 **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
+This release introduces a **new theme structure** for both **Customer Portal** and **Pricing Table**. The theme API has been reorganized and is **not backward compatible** with previous versions.
 
-## Requirements
+- **Theme is now a single object** passed via `MetrifoxService.initialize({ theme })` with two keys: `customerPortal` and `pricingTable`. The previous top-level `pricingTableTheme` option is **deprecated**; use `theme.pricingTable` instead.
+- **Customer Portal theme** uses a new grouped shape: `general`, `tabs`, `sections`, `buttons`, `lineItems`, `tables`, `modals`, and `plans`. Property names and nesting have changed from older versions.
+- **Pricing Table theme** now strictly follows the same nested structure as Customer Portal: all plan-related keys must be under `plans` (e.g. `plans.planCards`, `plans.planToggle`). Top-level plan keys are no longer supported.
+- **Both components** accept an optional `theme` input per instance to override or extend the global theme from `MetrifoxService.initialize`.
 
-- Angular 17.0.0 or higher (compatible with Angular 17, 18, and 19)
-- RxJS 7.0.0 or higher
+If you were using custom themes before, you will need to **migrate your theme objects** to the new structure. Omit any keys you don't need; the SDK merges your values with defaults. See the [Styling](#styling) section below for the full theme shapes and examples.
+
+---
 
 ## Installation
 
 ```bash
-# Using pnpm (recommended)
-pnpm add @metrifox/angular-sdk
-
-# Using npm
+# using npm
 npm install @metrifox/angular-sdk
 
-# Using yarn
+# or pnpm
+pnpm add @metrifox/angular-sdk
+
+# or yarn
 yarn add @metrifox/angular-sdk
 ```
 
-## Quick Start
+---
+
+## Setup
 
-### 1. Provide the SDK (required for components)
+### 1. Provide the SDK
 
-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`:
+Register the SDK providers in your app config:
 
 ```typescript
 // app.config.ts (Standalone)
@@ -56,7 +54,7 @@ export const appConfig: ApplicationConfig = {
 
 ### 2. Initialize the SDK
 
-Initialize Metrifox before using any components (e.g. in your root component’s `ngOnInit` or in a guard):
+Before using any components, initialize the SDK once with your Client key:
 
 ```typescript
 import { MetrifoxService } from "@metrifox/angular-sdk";
@@ -66,22 +64,6 @@ MetrifoxService.initialize({
 });
 ```
 
-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`:
@@ -98,345 +80,343 @@ Or import in your global `styles.css`:
 @import "@metrifox/angular-sdk/styles.css";
 ```
 
-### 4. Use Components
+> Compatible with **Angular 17, 18, and 19**. All components are standalone (no NgModule required).
 
-```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
+## Widgets
 
-### CustomerPortal
+## `CustomerPortal`
 
-Displays a customizable customer dashboard with plans, subscriptions, billing, and more.
+Displays a customizable customer dashboard with plans, subscriptions, billing, credits, and more.
 
 ```typescript
+import { Component } from "@angular/core";
 import { CustomerPortalComponent, SectionConfig } from "@metrifox/angular-sdk";
 
 @Component({
+  selector: "app-billing",
   standalone: true,
   imports: [CustomerPortalComponent],
   template: `
     <metrifox-customer-portal
-      [customerKey]="customerKey"
+      [customerKey]="'your-customer-key'"
       [sectionsConfig]="sections"
-      (dataLoaded)="onDataLoaded($event)"
-      (error)="onError($event)"
-    >
-    </metrifox-customer-portal>
+    />
   `,
 })
-export class MyComponent {
-  customerKey = "cust_123";
-
+export class BillingComponent {
   sections: SectionConfig[] = [
     { key: "subscription" },
     { key: "plan" },
-    { key: "upcomingInvoice" },
-    { key: "billingHistory" },
-    { key: "paymentOverview" },
-    { key: "entitlementUsage" },
-    { key: "walletBalance" },
+    { key: "billingHistory", hidden: true },
   ];
-
-  onDataLoaded(data: CustomerData) {
-    console.log("Customer data loaded:", data);
-  }
-
-  onError(error: MetrifoxErrorEvent) {
-    console.error("Error:", error);
-  }
 }
 ```
 
-#### CustomerPortal Inputs
+Optional **`theme`** input: pass a `CustomerPortalTheme` object to override or extend the global theme from `MetrifoxService.initialize` for this instance only.
+
+#### Section Configuration
+
+The `sectionsConfig` input controls what appears in the portal.
+
+| Property    | Type              | Description                                         |
+| ----------- | ----------------- | --------------------------------------------------- |
+| `key`       | `SectionKey`      | Unique key of the section (see list below)          |
+| `hidden`    | `boolean`         | Hide this section when `true`                       |
+| `component` | `Type<any>`       | Replace the default section with your own component |
+| `props`     | `Record<string, unknown>` | Extra props passed to the custom or default section |
 
-| Property         | Type              | Required | Description                        |
-| ---------------- | ----------------- | -------- | ---------------------------------- |
-| `customerKey`    | `string`          | Yes      | Unique identifier for the customer |
-| `sectionsConfig` | `SectionConfig[]` | No       | Configuration for portal sections  |
+#### Built-in Section Keys
 
-#### CustomerPortal Outputs
+| Key                | Description                   |
+| ------------------ | ----------------------------- |
+| `upcomingInvoice`  | Displays next invoice details |
+| `subscription`     | Active subscription overview  |
+| `creditBalance`    | Shows user wallet balance     |
+| `entitlementUsage` | Displays resource usage       |
+| `paymentOverview`  | Payment summary and methods   |
+| `billingHistory`   | List of past transactions     |
+| `plan`             | Current plan details          |
 
-| Event        | Type                 | Description                          |
-| ------------ | -------------------- | ------------------------------------ |
-| `dataLoaded` | `CustomerData`       | Emitted when customer data is loaded |
-| `error`      | `MetrifoxErrorEvent` | Emitted when an error occurs         |
+#### Section Anchors
 
-#### Available Sections
+Each portal section renders inside a `<section id="...">` wrapper so you can link directly to segments of a customer portal view. The default anchor IDs are:
 
-- `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
+| Anchor ID            | Section Key        |
+| -------------------- | ------------------ |
+| `#upcoming-invoice`  | `upcomingInvoice`  |
+| `#subscription`      | `subscription`     |
+| `#credit-balance`    | `creditBalance`    |
+| `#entitlement-usage` | `entitlementUsage` |
+| `#payment-overview`  | `paymentOverview`  |
+| `#billing-history`   | `billingHistory`   |
+| `#plan`              | `plan`             |
 
-### PricingTable
+Use these anchors when embedding the SDK or sharing deep links (e.g., `https://app.example.com/portal#billing-history`).
 
-Displays subscription plans and one-time purchases.
+---
+
+## Pricing Table
+
+Displays subscription plans and one-time purchases in a configurable pricing table component.
 
 ```typescript
-import { PricingTableComponent, PlanSelectEvent } from "@metrifox/angular-sdk";
+import { Component } from "@angular/core";
+import { PricingTableComponent } from "@metrifox/angular-sdk";
 
 @Component({
+  selector: "app-pricing",
   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>
+      [checkoutUsername]="'your-checkout-username'"
+      [productKey]="'your-product-key'"
+    />
   `,
 })
-export class PricingComponent {
-  username = "your-checkout-username";
-  productKey = "your-product-key";
+export class PricingComponent {}
+```
 
-  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);
-  }
+#### Props
+
+The inputs control how the pricing table is configured.
+
+| Property              | Type               | Required | Default | Description                                                                      |
+| --------------------- | ------------------ | -------- | ------- | -------------------------------------------------------------------------------- |
+| `checkoutUsername`    | `string`           | Yes      | —       | Unique username used for checkout. This can be found in **Settings → Checkout**. |
+| `productKey`          | `string`           | Yes      | —       | Unique product identifier. This can be found on the product page.                |
+| `plansOnly`           | `boolean`          | No       | `false` | Controls whether only subscription plans are rendered.                           |
+| `singlePurchasesOnly` | `boolean`          | No       | `false` | Controls whether only single purchases are rendered.                             |
+| `showTabHeader`       | `boolean`          | No       | `true`  | Controls whether the tab header for switching between offerings is rendered.     |
+| `theme`               | `PricingTableTheme`| No       | —       | Optional theme override for this instance (merged with global theme from `MetrifoxService.initialize`). |
+
+> **Note:** If both `plansOnly` and `singlePurchasesOnly` are `false` or undefined, both plans and single purchases are displayed.
+
+## Styling
+
+Import the SDK's global styles (see [Setup](#setup) step 3).
+
+> This is required for proper styling of all components.
+
+### Theme configuration (new structure)
+
+Theming is driven by a single `theme` object passed to `MetrifoxService.initialize`. It has two top-level keys: `customerPortal` and `pricingTable`. Any value you omit falls back to the SDK default. You can also pass an optional `theme` input to `<metrifox-customer-portal>` or `<metrifox-pricing-table>` to override or extend the global theme for that instance.
+
+```typescript
+// Passed to MetrifoxService.initialize({ theme })
+theme?: {
+  customerPortal?: CustomerPortalTheme
+  pricingTable?: PricingTableTheme
 }
 ```
 
-#### PricingTable Inputs
+> **Deprecated:** The previous root-level `pricingTableTheme` option is no longer supported. Use `theme.pricingTable` instead.
 
-| 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
+### Customer Portal theme (`CustomerPortalTheme`)
 
-| 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        |
+All properties are optional. The shape is grouped by area of the UI:
 
-## Theming
+| Group | Description |
+| ----- | ----------- |
+| `general` | Page-level: link color, background, border radius, font family, container padding |
+| `tabs` | Tab bar (e.g. Wallet balance tabs): background, border, active/inactive states |
+| `sections` | Section cards: background, padding, borders, content/summaryBalance sub-styles, header/label/value typography, usage bars, empty text |
+| `buttons` | Primary and secondary buttons: background, border (color/width/radius), typography |
+| `lineItems` | Subscription line items: parentRow/childRow background, border, typography (label/quantity) |
+| `tables` | Tables (e.g. billing history): header/row colors, border, cell padding, expand icon, typography |
+| `modals` | Modal overlay, background, border, close button; header/title/description typography; footer primary/secondary buttons |
+| `plans` | Plan cards when shown in portal: currentPlanCard, planCards (border as `{ color, width, radius }`), planFeatures, planButton, planToggle, planTags |
 
-Configure themes during initialization:
+**Example – minimal override:**
 
 ```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",
-    },
+customerPortal: {
+  general: { linkColor: "#2563eb", backgroundColor: "#ffffff" },
+  tabs: {
+    tabBackground: "#ffffff",
+    tabBorderColor: "#e5e7eb",
+    activeTabBackground: "#2563eb",
+    activeTabTextColor: "#ffffff",
+    inactiveTabTextColor: "#6b7280",
   },
-  pricingTable: {
-    card: {
+  sections: {
+    background: "#ffffff",
+    content: { background: "#f4f4f5", borderRadius: "8px" },
+    header: { fontSize: "16px", fontWeight: "600", color: "#52525b" },
+    label: { fontSize: "13px", color: "#71717a" },
+    value: { fontSize: "16px", color: "#52525b" },
+  },
+  buttons: {
+    primary: { backgroundColor: "#2563eb", border: { radius: "8px" }, typography: { color: "#ffffff" } },
+    secondary: { backgroundColor: "#e4e4e7", typography: { color: "#3f3f46" } },
+  },
+  plans: {
+    planCards: {
       background: "#ffffff",
-      borderColor: "#e5e7eb",
-      header: {
-        textColor: "#111827",
-      },
-      price: {
-        amountColor: "#111827",
-      },
-    },
-    button: {
-      background: "#2563eb",
-      textColor: "#ffffff",
+      border: { color: "#e5e7eb", width: "1px", radius: "8px" },
+      header: { background: "#e5e7eb", textColor: "#111827" },
+      description: { textColor: "#6b7280", textButtonColor: "#2563eb" },
+      price: { amountColor: "#111827", primaryTextColor: "#6b7280", secondaryTextColor: "#9ca3af" },
     },
+    planButton: { background: "#2563eb", textColor: "#ffffff" },
+    planToggle: { background: "#e5e7eb", activeBackground: "#1f2937", activeText: "#ffffff", inactiveText: "#6b7280" },
   },
-};
-
-MetrifoxService.initialize({
-  clientKey: "your-client-key",
-  theme,
-});
+}
 ```
 
-### Dark Mode
+---
+
+### Font customization
 
-The SDK supports dark mode out of the box:
+The SDK accepts **any font-family string** in your theme. The SDK applies it via CSS, but **your app must load the font** (Google Fonts, @font-face, etc.) before the SDK renders.
 
-1. **Automatic** - Follows system preference (`prefers-color-scheme: dark`)
-2. **Manual** - Add `metrifox-dark` class or `data-theme="dark"` attribute
+**How it works:**
+
+1. **Load the font in your app** (HTML, CSS, or framework-specific):
 
 ```html
-<!-- Manual dark mode -->
-<div class="metrifox-dark">
-  <metrifox-customer-portal [customerKey]="key" />
-</div>
+<!-- Option A: Google Fonts in your index.html <head> -->
+<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600&display=swap" rel="stylesheet">
 ```
 
-## Using the Service Directly
+```css
+/* Option B: @font-face in your global CSS */
+@font-face {
+  font-family: 'MyCustomFont';
+  src: url('/fonts/custom.woff2') format('woff2');
+}
+```
 
-Access Metrifox APIs programmatically:
+2. **Pass the font-family to the SDK theme:**
 
 ```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;
-        }
+MetrifoxService.initialize({
+  clientKey: "your-client-key",
+  theme: {
+    customerPortal: {
+      general: {
+        // Any font-family string works
+        fontFamily: '"Space Grotesk", "Inter", sans-serif'
+        // or: 'MyCustomFont, sans-serif'
+        // or: 'system-ui, -apple-system, sans-serif'
       }
-    });
+    }
   }
+});
+```
 
-  checkFeatureAccess() {
-    this.metrifoxService.checkAccess('cust_123', 'api_calls').subscribe({
-      next: ({ hasAccess, remaining, limit }) => {
-        console.log(`Access: ${hasAccess}, Remaining: ${remaining}/${limit}`);
-      }
-    });
-  }
+If no `fontFamily` is provided, the SDK inherits the font from the host page. This means the SDK works with whatever font your app already uses — no extra configuration needed.
 
-  recordUsage() {
-    this.metrifoxService.recordUsage('cust_123', 'api_calls', 1).subscribe({
-      next: () => console.log('Usage recorded')
-    });
-  }
-}
-```
+> **Important:** When using Google Fonts or custom fonts, load them in your app **before** the SDK initializes to prevent flash of unstyled text (FOUT).
 
-## Custom Components
+---
 
-Replace any section with your own component:
+### Pricing Table theme (`PricingTableTheme`)
 
-```typescript
-// my-custom-plan.component.ts
-import { Component, Input } from "@angular/core";
-import {
-  CustomSectionComponentBase,
-  CustomerData,
-} from "@metrifox/angular-sdk";
+The Pricing Table theme follows the same nested structure as Customer Portal. All plan-related keys must be nested under `plans`.
 
-@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;
-}
+| Key | Description |
+| --- | ----------- |
+| `plans` | Container for all plan-related styling |
+| `plans.currentPlanCard` | Current-plan highlight: header (background, textColor), gradientColor, description, borderRadius |
+| `plans.planCards` | Card style: background, border (`{ color, width, radius }`), header, description (textColor, textButtonColor), price (amountColor, primaryTextColor, secondaryTextColor, textButtonColor, background, borderColor) |
+| `plans.planFeatures` | Feature list: textColor, iconColor |
+| `plans.planButton` | CTA button: background, textColor; optional secondaryBackground, secondaryTextColor, textButtonColor |
+| `plans.planToggle` | Monthly/Yearly toggle: background, activeBackground, activeText, inactiveText |
+| `plans.planTags` | Tags (e.g. free trial): freeTrialBackground, freeTrialText |
+| `tabs` | Tabs (e.g. Plans vs Single purchases): inactiveText, activeText, indicator, borderColor |
+| `checkoutBar` | Bottom checkout bar: background, borderColor, textColor, buttonBackground, buttonTextColor |
 
-// 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!" },
+**Example – minimal override:**
+
+```typescript
+pricingTable: {
+  plans: {
+    planCards: {
+      background: "#ffffff",
+      border: { color: "#e5e7eb", width: "1px", radius: "8px" },
+      header: { background: "#e5e7eb", textColor: "#111827" },
+      description: { textColor: "#6b7280", textButtonColor: "#2563eb" },
+      price: { amountColor: "#111827", primaryTextColor: "#6b7280", secondaryTextColor: "#9ca3af" },
     },
-  ];
+    planButton: { background: "#2563eb", textColor: "#ffffff" },
+    planToggle: { background: "#e5e7eb", activeBackground: "#1f2937", activeText: "#ffffff", inactiveText: "#6b7280" },
+  },
+  tabs: { activeText: "#2563eb", indicator: "#2563eb", borderColor: "#9ca3af" },
+  checkoutBar: {
+    background: "#f9fafb",
+    borderColor: "#e5e7eb",
+    textColor: "#3f3f46",
+    buttonBackground: "#2563eb",
+    buttonTextColor: "#ffffff",
+  },
 }
 ```
 
-## TypeScript Support
+When the Pricing Table is embedded inside the Customer Portal, it automatically uses `theme.customerPortal.plans` for plan styling so both components stay consistent.
+
+---
 
-The SDK is fully typed. Import types as needed:
+### Full example
 
 ```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";
+import { MetrifoxService } from "@metrifox/angular-sdk";
+
+MetrifoxService.initialize({
+  clientKey: "your-client-key",
+  theme: {
+    customerPortal: {
+      general: { linkColor: "#2563eb", backgroundColor: "#ffffff" },
+      tabs: {
+        tabBackground: "#ffffff",
+        activeTabBackground: "#2563eb",
+        activeTabTextColor: "#ffffff",
+        inactiveTabTextColor: "#6b7280",
+      },
+      sections: {
+        background: "#ffffff",
+        content: { background: "#f4f4f5", borderRadius: "8px" },
+      },
+      buttons: {
+        primary: { backgroundColor: "#2563eb", typography: { color: "#ffffff" } },
+      },
+    },
+    pricingTable: {
+      plans: {
+        planCards: { background: "#ffffff", border: { color: "#e5e7eb", radius: "8px" } },
+        planButton: { background: "#2563eb", textColor: "#ffffff" },
+      },
+      tabs: { activeText: "#2563eb", indicator: "#2563eb" },
+      checkoutBar: { buttonBackground: "#2563eb", buttonTextColor: "#ffffff" },
+    },
+  },
+});
+```
+
+Per-component overrides (optional):
+
+```html
+<metrifox-customer-portal
+  [customerKey]="'cust_123'"
+  [theme]="{ general: { linkColor: '#1d4ed8' } }"
+/>
+
+<metrifox-pricing-table
+  [checkoutUsername]="'checkout_user'"
+  [productKey]="'prod_key'"
+  [theme]="{ plans: { planCards: { background: '#f8fafc' } } }"
+/>
 ```
 
-## Migration from React SDK
+---
+
+### Migration from React SDK
 
 | React                   | Angular                        |
 | ----------------------- | ------------------------------ |
@@ -445,43 +425,53 @@ import type {
 | `<PricingTable />`      | `<metrifox-pricing-table>`     |
 | `customerKey` prop      | `[customerKey]` input          |
 | `onPlanSelect` callback | `(planSelected)` output        |
+| `theme` prop            | `[theme]` input                |
+
+---
 
-## Testing with the demo playground
+## Local Development
 
-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.
+### Using [yalc](https://github.com/wclr/yalc)
 
-To run the package against the demo playground:
+For local SDK testing:
 
-1. **Build the Angular SDK** (this repo):
+```bash
+# In SDK project
+pnpm build
+npx yalc publish
+
+# In consuming app
+npx yalc add @metrifox/angular-sdk
+npm install
+```
 
-   ```bash
-   pnpm install
-   pnpm run build
-   ```
+#### Auto-update during development
 
-2. **Run the demo** (in [metrifox-sdk-demo/angular-sdk](https://github.com/metrifox/metrifox-sdk-demo/tree/main/angular-sdk)):
+```bash
+# In SDK project
+pnpm build        # rebuild
+npx yalc publish  # re-publish to yalc
 
-   ```bash
-   cd path/to/metrifox-sdk-demo/angular-sdk
-   npm install
-   npm run dev
-   ```
+# In consuming project
+npx yalc update @metrifox/angular-sdk
+```
 
-   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.
+#### Clean up
 
-## Browser Support
+```bash
+npx yalc remove @metrifox/angular-sdk
+npm install
+```
 
-- 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
+📘 **Full Documentation:**
+For detailed guides, API references, and live examples, visit [docs.metrifox.com](https://docs.metrifox.com).
+
+---
 
-## License
+## 📄 License
 
-MIT © [Metrifox](https://metrifox.com)
+MIT © [MetriFox](https://metrifox.com)