shared-features 0.0.4 → 0.0.6

package/README.md

@@ -1,19 +1,50 @@
 # shared-features
 
-Centralized common features for Zaions projects. Manage ads, contacts, feature requests, and more from a single admin panel at [aoneahsan.com](https://aoneahsan.com).
+Centralized common features for Zaions projects. Manage ads, notifications, contacts, and more from a single admin panel at [aoneahsan.com](https://aoneahsan.com).
+
+---
+
+## Two Core Systems
+
+This package provides **two separate systems** for cross-project communication:
+
+| System | Purpose | Firestore Collections | Admin Location |
+|--------|---------|----------------------|----------------|
+| **Advertising Campaigns** | Promote Zaions products across apps | `zaions_campaigns`, `zaions_products`, `zaions_impressions` | `/admin/campaigns` |
+| **Broadcasts/Notifications** | In-app notifications, announcements, alerts | `zaions_broadcasts`, `zaions_broadcast_events`, `zaions_notification_templates` | `/admin/notifications` |
+
+### When to Use Which?
+
+| Use Case | System |
+|----------|--------|
+| Promote ZTools in other apps | **Advertising Campaigns** |
+| Announce new feature to all users | **Broadcasts** |
+| Cross-sell products | **Advertising Campaigns** |
+| Maintenance notice | **Broadcasts** |
+| Product ads in footer/sidebar | **Advertising Campaigns** |
+| Alert banners at top of page | **Broadcasts** |
+| One-time welcome modal for products | **Advertising Campaigns** |
+| One-time announcement modal | **Broadcasts** |
+
+---
 
 ## Features
 
-- **Advertising Campaigns** - Cross-promote Zaions products across all projects
-  - 5 Ad Components (AdPanel, AdSlider, AdModal, AdUpdateModal, AdBanner)
-  - 10 Display Variants (5 small, 5 large)
-  - Frequency capping and analytics
-- **Products Catalog** - Centralized product information
-- **Contact Forms** - (Coming soon)
-- **Feature Requests** - (Coming soon)
-- **Payment Options** - (Coming soon)
-- **Social Links** - (Coming soon)
-- **Developer Info** - (Coming soon)
+### Advertising Campaigns System
+- **5 Ad Components** - AdPanel, AdSlider, AdModal, AdUpdateModal, AdBanner
+- **10 Display Variants** - 5 small (compact), 5 large (feature areas)
+- **Frequency capping** - Control how often users see ads
+- **Analytics** - Track impressions, clicks, CTR per project
+- **Project targeting** - Target specific projects or all
+
+### Broadcasts/Notifications System
+- **4 Notification Types** - Banner, Modal, Toast, Bell (notification center)
+- **Priority levels** - Low, Medium, High, Urgent
+- **Scheduling** - Immediate or scheduled delivery
+- **Templates** - Reusable notification templates
+- **Analytics** - Track views, clicks, dismissals
+
+---
 
 ## Installation
 
@@ -23,8 +54,6 @@ yarn add shared-features
 
 ## Peer Dependencies
 
-This package requires the following peer dependencies:
-
 ```bash
 yarn add react react-dom firebase @radix-ui/themes zustand lucide-react
 # Optional for mobile:
@@ -71,19 +100,39 @@ if (import.meta.env.VITE_SHARED_FEATURES_API_KEY) {
 }
 ```
 
-## Usage
+---
+
+# ADVERTISING CAMPAIGNS SYSTEM
+
+Cross-promote Zaions products (ZTools, FilesHub, etc.) across all projects.
 
-### Displaying Ads
+## Firestore Collections
+
+| Collection | Purpose | Access |
+|------------|---------|--------|
+| `zaions_products` | Product catalog (name, URL, icon, features) | Public read, Admin write |
+| `zaions_campaigns` | Campaign settings (targeting, placements, variants) | Public read, Admin write |
+| `zaions_impressions` | Analytics (impressions, clicks per campaign) | Public create, Admin read |
+
+## Displaying Ads
+
+### Simple Usage
 
 ```tsx
-import { AdPanel, useCampaigns } from 'shared-features';
+import { AdPanel, AdSlider } from 'shared-features';
 
-// Simple panel in sidebar
-function Sidebar() {
-  return <AdPanel placement="sidebar_panel" />;
-}
+// Sidebar panel
+<AdPanel placement="sidebar_panel" />
+
+// Footer slider
+<AdSlider placement="footer_slider" />
+```
+
+### Custom Implementation
+
+```tsx
+import { useCampaigns } from 'shared-features';
 
-// Custom implementation with hook
 function Footer() {
   const { campaigns, loading, recordImpression, recordClick } = useCampaigns({
     placement: 'footer_slider',
@@ -112,7 +161,7 @@ function Footer() {
 }
 ```
 
-### Available Placements
+## Ad Placements
 
 | Placement | Description | Recommended Variant |
 |-----------|-------------|-------------------|
@@ -125,7 +174,7 @@ function Footer() {
 | `sidebar_panel` | Web app sidebar | Small variants |
 | `home_banner` | Home page hero | Large variants |
 
-### Available Variants
+## Ad Variants
 
 **Small Variants (compact spaces):**
 - `small_panel_1` - Minimal
@@ -141,138 +190,242 @@ function Footer() {
 - `large_slider_4` - Comparison
 - `large_slider_5` - Video Placeholder
 
-## API Reference
-
-### `initSharedFeatures(config)`
-
-Initialize the package with your configuration.
+## Ad Components
 
-```typescript
-interface SharedFeaturesConfig {
-  firebaseConfig: FirebaseConfig;
-  projectId: string;
-  projectName: string;
-  platform: 'web' | 'android' | 'ios' | 'extension';
-  debug?: boolean;
-}
+### `AdPanel`
+Simple single-ad panel for sidebars and footers.
+```tsx
+<AdPanel placement="sidebar_panel" variant="small_panel_2" />
 ```
 
-### `useCampaigns(options)`
+### `AdSlider`
+Small promotional slider with auto-rotation.
+```tsx
+<AdSlider placement="footer_slider" />
+```
 
-Hook to fetch and manage campaigns.
+### `AdBanner`
+Permanent promotional banner with progress indicators.
+```tsx
+<AdBanner placement="home_banner" rotationInterval={10000} maxCampaigns={5} />
+```
 
-```typescript
-interface UseCampaignsOptions {
-  placement: AdPlacement;
-  maxCampaigns?: number;
-  autoFetch?: boolean;
-}
+### `AdModal`
+One-time promotional modal shown on first visit.
+```tsx
+import { AdModal, useOneTimeAdModal } from 'shared-features';
 
-interface UseCampaignsResult {
-  campaigns: CampaignWithProduct[];
-  campaign: CampaignWithProduct | null;
-  loading: boolean;
-  error: string | null;
-  refetch: () => Promise<void>;
-  recordImpression: (campaign: CampaignWithProduct) => Promise<void>;
-  recordClick: (campaign: CampaignWithProduct) => Promise<void>;
-  recordClose: (campaign: CampaignWithProduct) => Promise<void>;
+function App() {
+  const { shouldShow, markAsShown } = useOneTimeAdModal();
+  return shouldShow ? <AdModal onClose={markAsShown} /> : null;
 }
 ```
 
-### Components
-
-#### `AdPanel`
-
-Simple single-ad panel for sidebars and footers.
-
+### `AdUpdateModal`
+Carousel modal shown when app version changes.
 ```tsx
-<AdPanel placement="sidebar_panel" variant="small_panel_2" className="my-ad" />
-```
+import { AdUpdateModal, useUpdateAdModal } from 'shared-features';
 
-#### `AdSlider`
+function App() {
+  const { shouldShow, markAsShown } = useUpdateAdModal();
+  return shouldShow ? <AdUpdateModal onClose={markAsShown} /> : null;
+}
+```
 
-Small promotional slider using small panel variants.
+---
 
-```tsx
-<AdSlider placement="footer_slider" className="my-slider" />
-```
+# BROADCASTS/NOTIFICATIONS SYSTEM
 
-#### `AdBanner`
+Send in-app notifications, announcements, and alerts across all projects.
 
-Permanent promotional banner with auto-rotation and progress indicators.
+## Firestore Collections
 
-```tsx
-<AdBanner
-  placement="home_banner"
-  rotationInterval={10000}
-  maxCampaigns={5}
-/>
-```
+| Collection | Purpose | Access |
+|------------|---------|--------|
+| `zaions_broadcasts` | Notification content, targeting, scheduling | Public read, Admin write |
+| `zaions_broadcast_events` | Analytics (views, clicks, dismissals) | Public create, Admin read |
+| `zaions_notification_templates` | Reusable notification templates | Admin only |
 
-#### `AdModal`
+## Displaying Broadcasts
 
-One-time promotional modal shown on first visit.
+### Banner Notifications (Top of Page)
 
 ```tsx
-import { AdModal, useOneTimeAdModal } from 'shared-features';
+import { BroadcastBanner, useBannerBroadcasts } from 'shared-features';
 
 function App() {
-  const { shouldShow, markAsShown } = useOneTimeAdModal();
+  const { broadcasts, dismissBroadcast, trackClick } = useBannerBroadcasts();
 
   return (
     <>
-      {shouldShow && <AdModal onClose={markAsShown} />}
+      <BroadcastBanner
+        broadcasts={broadcasts}
+        onDismiss={dismissBroadcast}
+        onClick={trackClick}
+      />
       {/* Your app content */}
     </>
   );
 }
 ```
 
-#### `AdUpdateModal`
+### Modal Notifications
 
-Carousel modal shown when app version changes.
+```tsx
+import { useBroadcasts } from 'shared-features';
+
+function App() {
+  const { broadcasts, dismissBroadcast } = useBroadcasts({ variant: 'modal' });
+  const modalBroadcast = broadcasts[0];
+
+  if (!modalBroadcast) return <YourApp />;
+
+  return (
+    <Modal open onClose={() => dismissBroadcast(modalBroadcast.id)}>
+      <h2>{modalBroadcast.title}</h2>
+      <p>{modalBroadcast.message}</p>
+    </Modal>
+  );
+}
+```
+
+### Toast Notifications
 
 ```tsx
-import { AdUpdateModal, useUpdateAdModal } from 'shared-features';
+import { useBroadcasts } from 'shared-features';
 
 function App() {
-  const { shouldShow, currentVersion, markAsShown } = useUpdateAdModal();
+  const { broadcasts, dismissBroadcast } = useBroadcasts({ variant: 'toast' });
 
   return (
     <>
-      {shouldShow && <AdUpdateModal onClose={markAsShown} />}
-      {/* Your app content */}
+      <YourApp />
+      {broadcasts.map(toast => (
+        <Toast key={toast.id} onClose={() => dismissBroadcast(toast.id)}>
+          {toast.message}
+        </Toast>
+      ))}
     </>
   );
 }
 ```
 
-### Modal Hooks
+## Broadcast Variants
+
+| Variant | Use Case |
+|---------|----------|
+| `banner` | Persistent notification at top of page |
+| `modal` | Important announcement requiring attention |
+| `toast` | Brief notification that auto-dismisses |
+| `bell` | Notification center item |
+
+## Broadcast Priority
+
+| Priority | Use Case |
+|----------|----------|
+| `low` | General announcements |
+| `medium` | Feature updates, tips |
+| `high` | Important notices |
+| `urgent` | Critical alerts, maintenance |
+
+---
+
+# API REFERENCE
+
+## Initialization
+
+### `initSharedFeatures(config)`
+
+```typescript
+interface SharedFeaturesConfig {
+  firebaseConfig: FirebaseConfig;
+  projectId: string;      // e.g., 'ztools'
+  projectName: string;    // e.g., 'ZTools'
+  platform: 'web' | 'android' | 'ios' | 'extension';
+  debug?: boolean;
+}
+```
 
-#### `useOneTimeAdModal()`
+## Advertising Hooks
 
-Manages one-time modal visibility (first visit).
+### `useCampaigns(options)`
 
 ```typescript
-const { shouldShow, markAsShown } = useOneTimeAdModal();
+interface UseCampaignsOptions {
+  placement: AdPlacement;
+  maxCampaigns?: number;
+  autoFetch?: boolean;
+}
+
+interface UseCampaignsResult {
+  campaigns: CampaignWithProduct[];
+  campaign: CampaignWithProduct | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+  recordImpression: (campaign) => Promise<void>;
+  recordClick: (campaign) => Promise<void>;
+  recordClose: (campaign) => Promise<void>;
+}
 ```
 
-#### `useUpdateAdModal(currentVersion?)`
+### `useOneTimeAdModal()`
+Manages first-visit modal visibility.
+
+### `useUpdateAdModal(currentVersion?)`
+Manages version-change modal visibility.
 
-Manages update modal visibility (version change).
+## Broadcast Hooks
+
+### `useBroadcasts(options)`
 
 ```typescript
-const { shouldShow, previousVersion, currentVersion, markAsShown } = useUpdateAdModal();
+interface UseBroadcastsOptions {
+  variant?: 'banner' | 'modal' | 'toast' | 'bell';
+  maxBroadcasts?: number;
+}
+
+interface UseBroadcastsResult {
+  broadcasts: BroadcastNotification[];
+  isLoading: boolean;
+  error: Error | null;
+  dismissBroadcast: (id: string) => void;
+  trackClick: (broadcast) => Promise<void>;
+  refresh: () => Promise<void>;
+}
 ```
 
+### `useBannerBroadcasts()`
+Convenience hook for banner broadcasts.
+
+### `useModalBroadcasts()`
+Convenience hook for modal broadcasts.
+
+### `useToastBroadcasts()`
+Convenience hook for toast broadcasts.
+
+---
+
+# ADMIN PANEL
+
+Both systems are managed through the admin panel at aoneahsan.com:
+
+| System | Admin URL | What You Manage |
+|--------|-----------|-----------------|
+| Advertising | `/admin/campaigns` | Products, Campaigns, Ad targeting |
+| Notifications | `/admin/notifications` | Broadcasts, Templates, Scheduling |
+
+---
+
 ## Frequency Capping
 
-Ads automatically respect frequency capping set in the admin panel. By default, each campaign is shown to a user once every 20 days. This is tracked locally using Capacitor Preferences (mobile) or localStorage (web).
+Both systems support frequency capping:
+- **Ads**: Controlled per campaign (default: 20 days between impressions)
+- **Broadcasts**: Dismissals are tracked, won't show again until dismissed list clears
 
-## Admin Panel
+Tracking uses Capacitor Preferences (mobile) or localStorage (web).
 
-All campaigns are managed through the admin panel at [aoneahsan.com/admin/campaigns](https://aoneahsan.com/admin/campaigns). Consumer projects only need read access.
+---
 
 ## License