shared-features 0.0.6 → 0.0.8

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,5 +1,7 @@
 # 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).
 
 ---

package/dist/config/support.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Support configuration for shared-features package
+ * Help keep this package free and improving
+ */
+export declare const SUPPORT_CONFIG: {
+    readonly url: "https://aoneahsan.com/payment?project-id=shared-features&project-identifier=shared-features";
+    readonly label: "Support the Project";
+    readonly description: "Help us keep shared-features free and improving";
+};
+//# sourceMappingURL=support.d.ts.map

package/dist/config/support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support.d.ts","sourceRoot":"","sources":["../../src/config/support.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shared-features",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Shared features for Zaions projects - centralized ads, notifications, broadcasts, contacts, and more",
   "author": "Ahsan Mahmood <aoneahsan@gmail.com>",
   "license": "MIT",
@@ -58,7 +58,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "AI-INTEGRATION-GUIDE.md"
   ],
   "scripts": {
     "build": "vite build && tsc --emitDeclarationOnly",
@@ -72,7 +73,7 @@
     "@radix-ui/react-icons": ">=1.3.2",
     "@radix-ui/themes": ">=3.2.1",
     "firebase": ">=12.8.0",
-    "lucide-react": ">=0.400.0",
+    "lucide-react": ">=0.562.0",
     "react": ">=19.2.3",
     "react-dom": ">=19.2.3",
     "zustand": ">=5.0.10"
@@ -86,9 +87,12 @@
     "@capacitor/preferences": "^8.0.0",
     "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/themes": "^3.2.1",
-    "@types/react": "^19.2.8",
+    "@types/react": "^19.2.9",
     "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.53.1",
+    "@typescript-eslint/parser": "^8.53.1",
     "@vitejs/plugin-react": "^5.1.2",
+    "eslint": "^9.39.2",
     "firebase": "^12.8.0",
     "lucide-react": "^0.562.0",
     "typescript": "^5.9.3",