shared-features 0.0.7 → 0.1.0

package/AI-INTEGRATION-GUIDE.md

@@ -0,0 +1,315 @@
+# AI Integration Guide - shared-features
+
+Quick reference for AI development agents (Claude Code, Cursor, Copilot, etc.) to integrate shared-features into React + Capacitor projects.
+
+## Installation
+
+```bash
+yarn add shared-features
+```
+
+### Peer Dependencies
+```bash
+yarn add react react-dom firebase @radix-ui/themes zustand lucide-react
+# Optional for mobile:
+yarn add @capacitor/preferences
+```
+
+## Core Concepts
+
+shared-features provides two main systems:
+1. **Advertising Campaigns** - Cross-promotion of Zaions products
+2. **Broadcasts/Notifications** - In-app announcements and alerts
+
+## Quick Start
+
+### 1. Add Environment Variables
+
+```env
+VITE_SHARED_FEATURES_API_KEY=
+VITE_SHARED_FEATURES_AUTH_DOMAIN=
+VITE_SHARED_FEATURES_PROJECT_ID=
+VITE_SHARED_FEATURES_STORAGE_BUCKET=
+VITE_SHARED_FEATURES_MESSAGING_SENDER_ID=
+VITE_SHARED_FEATURES_APP_ID=
+VITE_SHARED_FEATURES_MEASUREMENT_ID=
+```
+
+### 2. Initialize
+
+```typescript
+// src/main.tsx
+import { initSharedFeatures } from 'shared-features';
+
+if (import.meta.env.VITE_SHARED_FEATURES_API_KEY) {
+  initSharedFeatures({
+    firebaseConfig: {
+      apiKey: import.meta.env.VITE_SHARED_FEATURES_API_KEY,
+      authDomain: import.meta.env.VITE_SHARED_FEATURES_AUTH_DOMAIN,
+      projectId: import.meta.env.VITE_SHARED_FEATURES_PROJECT_ID,
+      storageBucket: import.meta.env.VITE_SHARED_FEATURES_STORAGE_BUCKET,
+      messagingSenderId: import.meta.env.VITE_SHARED_FEATURES_MESSAGING_SENDER_ID,
+      appId: import.meta.env.VITE_SHARED_FEATURES_APP_ID,
+      measurementId: import.meta.env.VITE_SHARED_FEATURES_MEASUREMENT_ID,
+    },
+    projectId: 'your-project-id',
+    projectName: 'Your Project Name',
+    platform: 'web', // 'web' | 'android' | 'ios' | 'extension'
+    debug: import.meta.env.DEV,
+  });
+}
+```
+
+## Advertising Components
+
+### AdPanel (Recommended)
+Best for sidebars and feature areas.
+
+```tsx
+import { AdPanel } from 'shared-features';
+
+// Small variant (sidebar)
+<AdPanel variant="small" />
+
+// Large variant (feature area)
+<AdPanel variant="large" />
+```
+
+### AdSlider
+Auto-rotating carousel of ads.
+
+```tsx
+import { AdSlider } from 'shared-features';
+
+<AdSlider
+  variant="small"
+  autoRotate={true}
+  interval={5000}
+/>
+```
+
+### AdBanner
+Horizontal banner for headers/footers.
+
+```tsx
+import { AdBanner } from 'shared-features';
+
+<AdBanner />
+```
+
+### AdModal (One-time Welcome)
+Shows once per product, great for onboarding.
+
+```tsx
+import { useOneTimeAdModal } from 'shared-features';
+
+function App() {
+  const { AdModalComponent } = useOneTimeAdModal();
+
+  return (
+    <>
+      {AdModalComponent}
+      {/* rest of app */}
+    </>
+  );
+}
+```
+
+### AdUpdateModal (What's New)
+Shows once per version update.
+
+```tsx
+import { useUpdateAdModal } from 'shared-features';
+
+function App() {
+  const { UpdateModalComponent } = useUpdateAdModal();
+
+  return (
+    <>
+      {UpdateModalComponent}
+      {/* rest of app */}
+    </>
+  );
+}
+```
+
+## Broadcasts/Notifications
+
+### BroadcastBanner
+Alert banner at top of page.
+
+```tsx
+import { BroadcastBanner } from 'shared-features';
+
+<BroadcastBanner position="top" />
+```
+
+### AnnouncementModal
+Modal announcements.
+
+```tsx
+import { AnnouncementModal } from 'shared-features';
+
+<AnnouncementModal />
+```
+
+### useBroadcasts Hook
+
+```tsx
+import { useBroadcasts } from 'shared-features';
+
+function MyComponent() {
+  const { broadcasts, loading, markAsRead, dismissBroadcast } = useBroadcasts();
+
+  return broadcasts.map(broadcast => (
+    <div key={broadcast.id}>
+      <h3>{broadcast.title}</h3>
+      <p>{broadcast.message}</p>
+      <button onClick={() => dismissBroadcast(broadcast.id)}>Dismiss</button>
+    </div>
+  ));
+}
+```
+
+## Hooks Reference
+
+| Hook | Description | Returns |
+|------|-------------|---------|
+| `useCampaigns()` | Get active ad campaigns | `{ campaigns, loading, error }` |
+| `useOneTimeAdModal()` | One-time product modal | `{ AdModalComponent }` |
+| `useUpdateAdModal()` | Version update modal | `{ UpdateModalComponent }` |
+| `useBroadcasts()` | Get active broadcasts | `{ broadcasts, loading, markAsRead, dismiss }` |
+
+## Services
+
+### Analytics Tracking
+
+```typescript
+import { trackImpression, trackClick, trackDismissal } from 'shared-features';
+
+// Track ad impression
+await trackImpression(campaignId, productId);
+
+// Track ad click
+await trackClick(campaignId, productId);
+
+// Track dismissal
+await trackDismissal(campaignId);
+```
+
+### Campaigns Service
+
+```typescript
+import { getCampaigns, getCampaignById } from 'shared-features';
+
+// Get all active campaigns for current project
+const campaigns = await getCampaigns();
+
+// Get specific campaign
+const campaign = await getCampaignById('campaign-id');
+```
+
+## Types
+
+```typescript
+import type {
+  SharedFeaturesConfig,
+  Campaign,
+  Product,
+  Broadcast,
+  NotificationTemplate,
+  AdVariant,
+  Platform,
+} from 'shared-features';
+```
+
+## Configuration Interface
+
+```typescript
+interface SharedFeaturesConfig {
+  firebaseConfig: {
+    apiKey: string;
+    authDomain: string;
+    projectId: string;
+    storageBucket: string;
+    messagingSenderId: string;
+    appId: string;
+    measurementId: string;
+  };
+  projectId: string;      // Your project identifier
+  projectName: string;    // Display name
+  platform: 'web' | 'android' | 'ios' | 'extension';
+  debug?: boolean;        // Enable debug logging
+}
+```
+
+## Common Patterns
+
+### Conditional Rendering (Check Initialization)
+
+```tsx
+import { isInitialized } from 'shared-features';
+
+function AdSection() {
+  if (!isInitialized()) {
+    return null; // Don't render until initialized
+  }
+
+  return <AdPanel variant="small" />;
+}
+```
+
+### Footer Ad Integration
+
+```tsx
+import { AdBanner, isInitialized } from 'shared-features';
+
+function Footer() {
+  return (
+    <footer>
+      {isInitialized() && <AdBanner />}
+      <p>© 2026 Your Company</p>
+    </footer>
+  );
+}
+```
+
+### Sidebar with Ads
+
+```tsx
+import { AdPanel, isInitialized } from 'shared-features';
+
+function Sidebar() {
+  return (
+    <aside>
+      <nav>{/* Navigation */}</nav>
+      {isInitialized() && <AdPanel variant="small" />}
+    </aside>
+  );
+}
+```
+
+## Firestore Collections (Reference)
+
+| Collection | Purpose |
+|------------|---------|
+| `zaions_campaigns` | Ad campaigns data |
+| `zaions_products` | Products being promoted |
+| `zaions_impressions` | Ad impression analytics |
+| `zaions_broadcasts` | Broadcast messages |
+| `zaions_broadcast_events` | Broadcast analytics |
+| `zaions_notification_templates` | Reusable templates |
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Components not rendering | Check `isInitialized()` returns true |
+| Firebase errors | Verify all 7 config fields are provided |
+| No ads showing | Check projectId matches admin panel config |
+| Styles missing | Ensure `@radix-ui/themes` is imported |
+
+## Links
+
+- [Full Documentation](./README.md)
+- [Admin Panel](https://aoneahsan.com/admin)

package/README.md

@@ -1,15 +1,18 @@
 # shared-features
 
+- **[AI Integration Guide](./AI-INTEGRATION-GUIDE.md)** - Quick reference for AI development agents (Claude, Cursor, Copilot)
+
 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
+## Three Core Systems
 
-This package provides **two separate systems** for cross-project communication:
+This package provides **three systems** for cross-project feature management:
 
 | System | Purpose | Firestore Collections | Admin Location |
 |--------|---------|----------------------|----------------|
+| **Feature Flags** | Version management, feature toggles | `zaions_feature_flags` | `/admin/settings` |
 | **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` |
 
@@ -96,10 +99,154 @@ if (import.meta.env.VITE_SHARED_FEATURES_API_KEY) {
     projectName: 'Your Project Name', // e.g., 'ZTools', '2FA Studio'
     platform: 'web', // or 'android', 'ios', 'extension'
     debug: import.meta.env.DEV, // optional
+    // Optional: Lock to specific feature versions
+    featureVersions: {
+      campaigns: 1,
+      broadcasts: 1,
+    },
+  });
+}
+```
+
+---
+
+# FEATURE FLAGS SYSTEM
+
+Manage feature availability, versioning, and breaking changes across all consumer projects.
+
+## Why Feature Flags?
+
+- **Version Control**: Roll out breaking changes gradually
+- **Feature Toggles**: Enable/disable features globally
+- **Deprecation Warnings**: Warn consumers about outdated versions
+- **Maintenance Mode**: Show maintenance messages across all apps
+- **Platform/Project Targeting**: Enable features for specific platforms or projects
+
+## Firestore Collection
+
+| Collection | Purpose | Access |
+|------------|---------|--------|
+| `zaions_feature_flags` | Global feature configuration (singleton) | Public read, Admin write |
+
+## Checking Feature Availability
+
+### Check Overall Status
+
+```tsx
+import { useFeatureFlags } from 'shared-features';
+
+function App() {
+  const { status, loading, isFeatureAvailable, hasDeprecatedFeatures } = useFeatureFlags();
+
+  if (loading) return <Spinner />;
+
+  // Handle maintenance mode
+  if (status?.maintenanceMode) {
+    return <MaintenancePage message={status.maintenanceMessage} />;
+  }
+
+  // Warn about deprecated features
+  if (hasDeprecatedFeatures) {
+    console.warn('Some features are deprecated:', status?.deprecatedFeatures);
+  }
+
+  // Check specific feature
+  if (isFeatureAvailable('contactInfo')) {
+    return <ContactInfo />;
+  }
+
+  return <App />;
+}
+```
+
+### Check Single Feature
+
+```tsx
+import { useFeature } from 'shared-features';
+
+function ContactSection() {
+  const { available, loading, deprecated, deprecationWarning } = useFeature('contactInfo');
+
+  if (loading) return <Spinner />;
+  if (!available) return <LegacyContactInfo />;
+
+  if (deprecated) {
+    console.warn(deprecationWarning);
+  }
+
+  return <NewContactInfo />;
+}
+```
+
+### Conditional Rendering with Feature Gates
+
+```tsx
+import { useFeatureGate } from 'shared-features';
+
+function MyComponent() {
+  const { shouldRender, FallbackOrChildren } = useFeatureGate('socialLinks');
+
+  return (
+    <FallbackOrChildren fallback={<OldSocialLinks />}>
+      <NewSocialLinks />
+    </FallbackOrChildren>
+  );
+}
+```
+
+### Real-time Updates
+
+```tsx
+import { useFeatureFlagsSubscription } from 'shared-features';
+
+function App() {
+  useFeatureFlagsSubscription((status) => {
+    if (status?.maintenanceMode) {
+      showMaintenanceBanner(status.maintenanceMessage);
+    }
   });
+
+  return <YourApp />;
 }
 ```
 
+## Available Features
+
+| Feature ID | Description | Status |
+|------------|-------------|--------|
+| `campaigns` | Advertising campaigns | ✅ Enabled |
+| `broadcasts` | Broadcast notifications | ✅ Enabled |
+| `contactInfo` | Contact information | ⏳ Coming Soon |
+| `developerInfo` | Developer information | ⏳ Coming Soon |
+| `socialLinks` | Social media links | ⏳ Coming Soon |
+| `paymentOptions` | Payment methods | ⏳ Coming Soon |
+| `addressInfo` | Address information | ⏳ Coming Soon |
+| `services` | Professional services | ⏳ Coming Soon |
+| `skills` | Skills display | ⏳ Coming Soon |
+| `testimonials` | Client testimonials | ⏳ Coming Soon |
+| `projects` | Portfolio projects | ⏳ Coming Soon |
+
+## Feature Versioning
+
+When breaking changes are introduced:
+
+1. Admin bumps feature version in `zaions_feature_flags`
+2. Consumers using old version get deprecation warnings
+3. Once `minVersion` is bumped, old consumers get `upgradeRequired: true`
+4. Consumers update their code and bump `featureVersions` in config
+
+```typescript
+// Consumer specifies supported versions
+initSharedFeatures({
+  // ... other config
+  featureVersions: {
+    campaigns: 1,    // Using v1 API
+    broadcasts: 1,   // Using v1 API
+    contactInfo: 2,  // Updated to v2 API
+  },
+});
+```
+
 ---
 
 # ADVERTISING CAMPAIGNS SYSTEM
@@ -343,9 +490,67 @@ interface SharedFeaturesConfig {
   projectName: string;    // e.g., 'ZTools'
   platform: 'web' | 'android' | 'ios' | 'extension';
   debug?: boolean;
+  featureVersions?: ConsumerFeatureVersions; // Optional version preferences
 }
 ```
 
+## Feature Flag Hooks
+
+### `useFeatureFlags(options?)`
+
+Check overall feature flags status.
+
+```typescript
+interface UseFeatureFlagsOptions {
+  autoRefresh?: boolean;      // Auto-refresh flags periodically
+  refreshInterval?: number;   // Refresh interval in ms (default: 5 min)
+  autoFetch?: boolean;        // Fetch on mount (default: true)
+}
+
+interface UseFeatureFlagsResult {
+  status: SharedFeaturesStatus | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+  isFeatureAvailable: (featureId: FeatureId) => boolean;
+  getFeatureAvailability: (featureId: FeatureId) => FeatureAvailability | null;
+  hasDeprecatedFeatures: boolean;
+  hasUpgradeRequired: boolean;
+}
+```
+
+### `useFeature(featureId)`
+
+Check a single feature's availability.
+
+```typescript
+const {
+  available,           // Feature can be used
+  loading,             // Check in progress
+  enabled,             // Feature is enabled (but might need upgrade)
+  deprecated,          // Using deprecated version
+  upgradeRequired,     // Must upgrade to use
+  deprecationWarning,  // Warning message
+  unavailableReason,   // Why unavailable
+} = useFeature('contactInfo');
+```
+
+### `useFeatureGate(featureId)`
+
+Conditional rendering helper.
+
+```typescript
+const { shouldRender, loading, deprecated, FallbackOrChildren } = useFeatureGate('socialLinks');
+```
+
+### `useFeatureFlagsSubscription(callback)`
+
+Real-time feature flag updates.
+
+### `useSharedFeaturesOperational()`
+
+Quick check if shared-features is operational.
+
 ## Advertising Hooks
 
 ### `useCampaigns(options)`

package/dist/{admin-notifications-D9n9h-eY.cjs → admin-notifications-D1GgYCJW.cjs}

@@ -1,6 +1,6 @@
 "use strict";
 const firestore = require("firebase/firestore");
-const analytics = require("./analytics-lEzOx2vl.cjs");
+const commonFeatures = require("./commonFeatures-CiqxxOin.cjs");
 const COLLECTION_BROADCASTS = "zaions_broadcasts";
 const COLLECTION_TEMPLATES = "zaions_notification_templates";
 const COLLECTION_BROADCAST_EVENTS = "zaions_broadcast_events";
@@ -51,7 +51,7 @@ function docToTemplate(docId, data) {
   };
 }
 async function createBroadcast(input, adminUserId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const broadcastData = {
     ...input,
     status: "draft",
@@ -70,7 +70,7 @@ async function createBroadcast(input, adminUserId) {
   return docRef.id;
 }
 async function updateBroadcast(input, adminUserId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const updateData = {
     ...input,
     updatedBy: adminUserId,
@@ -86,11 +86,11 @@ async function updateBroadcast(input, adminUserId) {
   await firestore.updateDoc(firestore.doc(db, COLLECTION_BROADCASTS, input.id), updateData);
 }
 async function deleteBroadcast(broadcastId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   await firestore.deleteDoc(firestore.doc(db, COLLECTION_BROADCASTS, broadcastId));
 }
 async function getAllBroadcasts() {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const q = firestore.query(
     firestore.collection(db, COLLECTION_BROADCASTS),
     firestore.orderBy("createdAt", "desc")
@@ -99,7 +99,7 @@ async function getAllBroadcasts() {
   return snapshot.docs.map((d) => docToBroadcast(d.id, d.data()));
 }
 async function getBroadcastsByStatus(status) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const q = firestore.query(
     firestore.collection(db, COLLECTION_BROADCASTS),
     firestore.where("status", "==", status),
@@ -109,13 +109,13 @@ async function getBroadcastsByStatus(status) {
   return snapshot.docs.map((d) => docToBroadcast(d.id, d.data()));
 }
 async function getBroadcastById(broadcastId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const docSnap = await firestore.getDoc(firestore.doc(db, COLLECTION_BROADCASTS, broadcastId));
   if (!docSnap.exists()) return null;
   return docToBroadcast(docSnap.id, docSnap.data());
 }
 async function publishBroadcast(broadcastId, adminUserId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   await firestore.updateDoc(firestore.doc(db, COLLECTION_BROADCASTS, broadcastId), {
     status: "active",
     updatedBy: adminUserId,
@@ -123,7 +123,7 @@ async function publishBroadcast(broadcastId, adminUserId) {
   });
 }
 async function scheduleBroadcast(broadcastId, scheduledDate, adminUserId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   await firestore.updateDoc(firestore.doc(db, COLLECTION_BROADCASTS, broadcastId), {
     status: "scheduled",
     startDate: firestore.Timestamp.fromDate(scheduledDate),
@@ -132,7 +132,7 @@ async function scheduleBroadcast(broadcastId, scheduledDate, adminUserId) {
   });
 }
 async function pauseBroadcast(broadcastId, adminUserId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   await firestore.updateDoc(firestore.doc(db, COLLECTION_BROADCASTS, broadcastId), {
     status: "draft",
     // Move back to draft
@@ -141,7 +141,7 @@ async function pauseBroadcast(broadcastId, adminUserId) {
   });
 }
 async function endBroadcast(broadcastId, adminUserId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   await firestore.updateDoc(firestore.doc(db, COLLECTION_BROADCASTS, broadcastId), {
     status: "ended",
     endDate: firestore.serverTimestamp(),
@@ -150,7 +150,7 @@ async function endBroadcast(broadcastId, adminUserId) {
   });
 }
 async function createTemplate(input) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const templateData = {
     ...input,
     createdAt: firestore.serverTimestamp(),
@@ -163,18 +163,18 @@ async function createTemplate(input) {
   return docRef.id;
 }
 async function updateTemplate(templateId, input) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   await firestore.updateDoc(firestore.doc(db, COLLECTION_TEMPLATES, templateId), {
     ...input,
     updatedAt: firestore.serverTimestamp()
   });
 }
 async function deleteTemplate(templateId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   await firestore.deleteDoc(firestore.doc(db, COLLECTION_TEMPLATES, templateId));
 }
 async function getAllTemplates() {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const q = firestore.query(
     firestore.collection(db, COLLECTION_TEMPLATES),
     firestore.orderBy("name", "asc")
@@ -183,13 +183,13 @@ async function getAllTemplates() {
   return snapshot.docs.map((d) => docToTemplate(d.id, d.data()));
 }
 async function getTemplateById(templateId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const docSnap = await firestore.getDoc(firestore.doc(db, COLLECTION_TEMPLATES, templateId));
   if (!docSnap.exists()) return null;
   return docToTemplate(docSnap.id, docSnap.data());
 }
 async function getFirestoreTemplateByEventType(eventType) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const q = firestore.query(
     firestore.collection(db, COLLECTION_TEMPLATES),
     firestore.where("eventType", "==", eventType)
@@ -201,7 +201,7 @@ async function getFirestoreTemplateByEventType(eventType) {
   return docToTemplate(docSnap.id, docSnap.data());
 }
 async function getBroadcastAnalytics(broadcastId) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const broadcast = await getBroadcastById(broadcastId);
   if (!broadcast) return null;
   const eventsQuery = firestore.query(
@@ -264,7 +264,7 @@ async function getBroadcastAnalytics(broadcastId) {
   };
 }
 async function getOverallAnalytics(startDate, endDate) {
-  const db = analytics.getSharedFeaturesDb();
+  const db = commonFeatures.getSharedFeaturesDb();
   const eventsQuery = firestore.query(
     firestore.collection(db, COLLECTION_BROADCAST_EVENTS),
     firestore.where("timestamp", ">=", firestore.Timestamp.fromDate(startDate)),
@@ -359,4 +359,4 @@ exports.publishBroadcast = publishBroadcast;
 exports.scheduleBroadcast = scheduleBroadcast;
 exports.updateBroadcast = updateBroadcast;
 exports.updateTemplate = updateTemplate;
-//# sourceMappingURL=admin-notifications-D9n9h-eY.cjs.map
+//# sourceMappingURL=admin-notifications-D1GgYCJW.cjs.map