featurely-site-manager 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-14
+
+### Added
+
+- Initial release of @featurely/site-manager
+- Maintenance mode with default and custom pages
+- Expected restoration time display
+- Status page link support
+- Whitelist system (localStorage keys, emails, custom functions)
+- Status messages/banners
+- Message types: info, warning, error, success
+- Message positioning: top, bottom banners and toast notifications
+- Message scheduling (start/end times)
+- Page targeting (URL patterns)
+- Dismissible messages with localStorage persistence
+- Call-to-action buttons in messages
+- Auto-polling configuration updates (default: 60s)
+- Comprehensive TypeScript support
+- Mobile-responsive designs
+- Zero dependencies
+- Callbacks for all major events
+- React, Next.js, and Vue integration examples

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Featurely
+
+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,447 @@
+# @featurely/site-manager
+
+Powerful site management SDK for controlling maintenance mode, displaying status messages, and managing site-wide features from your Featurely dashboard.
+
+## 📦 Installation
+
+```bash
+npm install @featurely/site-manager
+```
+
+## 🚀 Quick Start
+
+```typescript
+import { SiteManager } from "@featurely/site-manager";
+
+const siteManager = new SiteManager({
+  apiKey: "your-featurely-api-key",
+  projectId: "your-project-id",
+});
+
+siteManager.init();
+```
+
+## ✨ Features
+
+### 🔧 Maintenance Mode
+
+- **Default** or **custom** maintenance pages
+- Expected restoration time countdown
+- Status page links
+- Smart whitelist system:
+  - localStorage keys
+  - Email addresses
+  - Custom bypass functions
+
+### 📢 Status Messages
+
+- Multiple message types: info, warning, error, success
+- Flexible positioning: top, bottom banners or toast notifications
+- Dismissible messages with persistence
+- Scheduled messages (start/end times)
+- Page targeting (show on specific URLs)
+- Call-to-action buttons
+- Auto-expire functionality
+
+## 📖 Usage
+
+### Basic Setup
+
+```typescript
+const manager = new SiteManager({
+  apiKey: "ft_live_your_api_key",
+  projectId: "proj_your_project_id",
+});
+
+manager.init();
+```
+
+### With User Context
+
+```typescript
+const manager = new SiteManager({
+  apiKey: "ft_live_your_api_key",
+  projectId: "proj_your_project_id",
+  userEmail: "user@example.com", // For whitelist checks
+});
+
+manager.init();
+
+// Update user later
+manager.setUser("newuser@example.com");
+```
+
+### With Callbacks
+
+```typescript
+const manager = new SiteManager({
+  apiKey: "ft_live_your_api_key",
+  projectId: "proj_your_project_id",
+
+  onMaintenanceEnabled: (config) => {
+    console.log("Maintenance mode enabled:", config);
+    // Track in analytics
+  },
+
+  onMaintenanceDisabled: () => {
+    console.log("Site is back online!");
+  },
+
+  onMessageReceived: (message) => {
+    console.log("New message:", message);
+  },
+
+  onError: (error) => {
+    console.error("Site Manager error:", error);
+  },
+});
+
+manager.init();
+```
+
+### Custom Maintenance Bypass
+
+```typescript
+const manager = new SiteManager({
+  apiKey: "ft_live_your_api_key",
+  projectId: "proj_your_project_id",
+
+  bypassCheck: () => {
+    // Custom logic - e.g., check if user is admin
+    return window.location.search.includes("admin=true");
+  },
+});
+
+manager.init();
+```
+
+### Custom Poll Interval
+
+```typescript
+const manager = new SiteManager({
+  apiKey: "ft_live_your_api_key",
+  projectId: "proj_your_project_id",
+  pollInterval: 30000, // Check every 30 seconds instead of default 60s
+});
+
+manager.init();
+```
+
+## 🔧 Configuration
+
+### SiteManagerConfig
+
+| Option                  | Type            | Required | Default                   | Description                   |
+| ----------------------- | --------------- | -------- | ------------------------- | ----------------------------- |
+| `apiKey`                | `string`        | ✅       | -                         | Your Featurely API key        |
+| `projectId`             | `string`        | ✅       | -                         | Your Featurely project ID     |
+| `apiUrl`                | `string`        | ❌       | `'https://featurely.com'` | Custom API endpoint           |
+| `pollInterval`          | `number`        | ❌       | `60000`                   | Polling interval in ms        |
+| `userEmail`             | `string`        | ❌       | -                         | User email for whitelist      |
+| `bypassCheck`           | `() => boolean` | ❌       | -                         | Custom bypass function        |
+| `onMaintenanceEnabled`  | `function`      | ❌       | -                         | Maintenance enabled callback  |
+| `onMaintenanceDisabled` | `function`      | ❌       | -                         | Maintenance disabled callback |
+| `onMessageReceived`     | `function`      | ❌       | -                         | Message received callback     |
+| `onMessageDismissed`    | `function`      | ❌       | -                         | Message dismissed callback    |
+| `onError`               | `function`      | ❌       | -                         | Error callback                |
+
+## 🎯 API Methods
+
+### `init()`
+
+Initialize and start the site manager.
+
+```typescript
+await manager.init();
+```
+
+### `setUser(email: string)`
+
+Update user email for whitelist checks.
+
+```typescript
+manager.setUser("user@example.com");
+```
+
+### `refresh()`
+
+Manually refresh configuration from server.
+
+```typescript
+await manager.refresh();
+```
+
+### `destroy()`
+
+Stop the manager and clean up.
+
+```typescript
+manager.destroy();
+```
+
+## 🎨 Maintenance Mode
+
+### Default Page
+
+The SDK includes a beautiful default maintenance page with:
+
+- Professional gradient background
+- Maintenance icon
+- Customizable messages
+- Expected restoration time
+- Optional status page link
+
+### Custom Page
+
+Provide your own HTML:
+
+```typescript
+// Set in Featurely dashboard:
+{
+  "type": "custom",
+  "customHtml": "<div>Your custom HTML here</div>"
+}
+```
+
+### Whitelist System
+
+**localStorage Keys:**
+Users with specific localStorage keys bypass maintenance.
+
+```typescript
+// In Featurely dashboard, set whitelist keys: ['featurely_admin', 'bypass_key']
+// Users can set: localStorage.setItem('featurely_admin', 'true');
+```
+
+**Email Addresses:**
+Specific users bypass maintenance.
+
+```typescript
+// In Featurely dashboard: ['admin@company.com', 'support@company.com']
+const manager = new SiteManager({
+  apiKey: "ft_live_...",
+  projectId: "proj_...",
+  userEmail: "admin@company.com", // This user bypasses
+});
+```
+
+**Custom Function:**
+Complex bypass logic.
+
+```typescript
+const manager = new SiteManager({
+  apiKey: "ft_live_...",
+  projectId: "proj_...",
+  bypassCheck: () => {
+    // E.g., check if admin query param is present
+    return new URLSearchParams(window.location.search).get("admin") === "true";
+  },
+});
+```
+
+## 📢 Status Messages
+
+Messages are managed from your Featurely dashboard and automatically displayed based on:
+
+- Start/end times
+- Target pages (URL patterns)
+- Message type and priority
+
+### Message Types
+
+- **info** (blue) - Informational messages
+- **warning** (orange) - Warnings and alerts
+- **error** (red) - Critical errors
+- **success** (green) - Success notifications
+
+### Message Styles
+
+- **banner** - Full-width top or bottom banner
+- **toast** - Small notification in corner
+
+### Example Message Configuration
+
+```json
+{
+  "id": "msg_123",
+  "type": "warning",
+  "title": "Scheduled Maintenance",
+  "message": "We'll be performing maintenance tonight at 3 AM EST.",
+  "position": "top",
+  "style": "banner",
+  "dismissible": true,
+  "startsAt": "2026-03-14T10:00:00Z",
+  "expiresAt": "2026-03-15T03:00:00Z",
+  "cta": {
+    "text": "Learn More",
+    "url": "/maintenance-info"
+  }
+}
+```
+
+## 🌐 Framework Integration
+
+### React
+
+```tsx
+import { useEffect } from "react";
+import { SiteManager } from "@featurely/site-manager";
+
+function App() {
+  useEffect(() => {
+    const manager = new SiteManager({
+      apiKey: process.env.REACT_APP_FEATURELY_API_KEY!,
+      projectId: process.env.REACT_APP_FEATURELY_PROJECT_ID!,
+    });
+
+    manager.init();
+
+    return () => manager.destroy();
+  }, []);
+
+  return <div>Your app</div>;
+}
+```
+
+### Next.js
+
+```tsx
+// app/layout.tsx
+"use client";
+
+import { useEffect } from "react";
+import { SiteManager } from "@featurely/site-manager";
+
+export default function RootLayout({ children }) {
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+
+    const manager = new SiteManager({
+      apiKey: process.env.NEXT_PUBLIC_FEATURELY_API_KEY!,
+      projectId: process.env.NEXT_PUBLIC_FEATURELY_PROJECT_ID!,
+    });
+
+    manager.init();
+
+    return () => manager.destroy();
+  }, []);
+
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### Vue
+
+```vue
+<script setup>
+import { onMounted, onUnmounted } from "vue";
+import { SiteManager } from "@featurely/site-manager";
+
+let manager = null;
+
+onMounted(() => {
+  manager = new SiteManager({
+    apiKey: import.meta.env.VITE_FEATURELY_API_KEY,
+    projectId: import.meta.env.VITE_FEATURELY_PROJECT_ID,
+  });
+
+  manager.init();
+});
+
+onUnmounted(() => {
+  manager?.destroy();
+});
+</script>
+```
+
+## 🌐 Environment Variables
+
+**React/Vite:**
+
+```env
+VITE_FEATURELY_API_KEY=ft_live_your_key
+VITE_FEATURELY_PROJECT_ID=proj_your_id
+```
+
+**Next.js:**
+
+```env
+NEXT_PUBLIC_FEATURELY_API_KEY=ft_live_your_key
+NEXT_PUBLIC_FEATURELY_PROJECT_ID=proj_your_id
+```
+
+## 🎨 Styling
+
+The SDK injects minimal, scoped styles. All classes are prefixed with `featurely-` to avoid conflicts.
+
+### Custom Styling
+
+Override default styles:
+
+```css
+/* Customize maintenance page */
+.featurely-maintenance-overlay {
+  background: linear-gradient(to right, #your #colors) !important;
+}
+
+/* Customize messages */
+.featurely-message-info {
+  background: #your-color !important;
+}
+```
+
+## 📊 Dashboard Management
+
+Manage all settings from your Featurely dashboard at:
+`https://featurely.com/dashboard/settings` → Site Management tab
+
+### Maintenance Mode Panel
+
+- Toggle on/off
+- Set expected restoration time
+- Configure whitelist (emails, localStorage keys)
+- Choose default or custom page
+- Add status page link
+
+### Status Messages Panel
+
+- Create new messages
+- Set type, title, and content
+- Schedule start/end times
+- Target specific pages
+- Add CTA buttons
+- Set priority
+
+## 🔒 Security
+
+- API keys should be environment variables
+- All requests use HTTPS
+- Whitelist checks happen client-side (easily bypassable - use for convenience, not security)
+- For true access control, implement server-side authentication
+
+## 📱 Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🔗 Links
+
+- [Featurely](https://featurely.com)
+- [Documentation](https://docs.featurely.com)
+- [npm](https://www.npmjs.com/package/@featurely/site-manager)
+
+## 💬 Support
+
+- Open a GitHub issue
+- Contact support@featurely.com
+- Check the [documentation](https://docs.featurely.com)

package/dist/index.d.mts

@@ -0,0 +1,124 @@
+type MessageType = "info" | "warning" | "error" | "success";
+type MessagePosition = "top" | "bottom";
+type MessageStyle = "banner" | "toast";
+interface StatusMessage {
+    id: string;
+    type: MessageType;
+    title: string;
+    message: string;
+    icon?: string;
+    dismissible: boolean;
+    position: MessagePosition;
+    style: MessageStyle;
+    expiresAt?: string;
+    startsAt?: string;
+    targetPages?: string[];
+    cta?: {
+        text: string;
+        url: string;
+        action?: string;
+    };
+    priority?: number;
+}
+interface FeatureFlag {
+    id: string;
+    key: string;
+    name: string;
+    description?: string;
+    enabled: boolean;
+    rolloutPercentage?: number;
+    targetEmails?: string[];
+    excludeEmails?: string[];
+    variants?: {
+        key: string;
+        name: string;
+        weight: number;
+    }[];
+    defaultVariant?: string;
+}
+interface MaintenanceConfig {
+    enabled: boolean;
+    type: "default" | "custom";
+    customHtml?: string;
+    expectedRestoration?: string;
+    showStatusLink: boolean;
+    statusPageUrl?: string;
+    whitelist: {
+        localStorageKeys?: string[];
+        emails?: string[];
+        ips?: string[];
+    };
+}
+interface SiteConfig {
+    maintenance: MaintenanceConfig;
+    messages: StatusMessage[];
+    featureFlags: FeatureFlag[];
+    lastUpdated: string;
+}
+interface SiteManagerConfig {
+    apiKey: string;
+    projectId: string;
+    apiUrl?: string;
+    pollInterval?: number;
+    userEmail?: string;
+    bypassCheck?: () => boolean;
+    onMaintenanceEnabled?: (config: MaintenanceConfig) => void;
+    onMaintenanceDisabled?: () => void;
+    onMessageReceived?: (message: StatusMessage) => void;
+    onMessageDismissed?: (messageId: string) => void;
+    onFeatureFlagsUpdated?: (flags: FeatureFlag[]) => void;
+    userId?: string;
+    enableAnalytics?: boolean;
+    analyticsFlushInterval?: number;
+    onError?: (error: Error) => void;
+}
+declare class SiteManager {
+    private config;
+    private siteConfig;
+    private pollIntervalId;
+    private messageContainers;
+    private dismissedMessages;
+    private featureFlagBuckets;
+    private analyticsQueue;
+    private analyticsFlushIntervalId;
+    private sessionId;
+    constructor(config: SiteManagerConfig);
+    init(): Promise<void>;
+    destroy(): void;
+    setUser(email: string, userId?: string): void;
+    isFeatureEnabled(flagKey: string): boolean;
+    getFeatureVariant(flagKey: string): string | null;
+    getAllFeatureFlags(): FeatureFlag[];
+    getEnabledFeatures(): string[];
+    refresh(): Promise<void>;
+    trackEvent(eventName: string, properties?: Record<string, string | number | boolean>): void;
+    private fetchConfig;
+    private startPolling;
+    private stopPolling;
+    private startAnalyticsFlushing;
+    private stopAnalyticsFlushing;
+    private flushAnalytics;
+    private generateSessionId;
+    private evaluateFeatureFlag;
+    private getUserBucket;
+    private simpleHash;
+    private getAnonymousId;
+    private checkMaintenanceMode;
+    private enableMaintenanceMode;
+    private disableMaintenanceMode;
+    private shouldBypassMaintenance;
+    private showMaintenancePage;
+    private hideMaintenancePage;
+    private getDefaultMaintenanceHtml;
+    private updateMessages;
+    private showMessage;
+    private dismissMessage;
+    private clearMessages;
+    private handleMessageAction;
+    private getDefaultIcon;
+    private loadDismissedMessages;
+    private saveDismissedMessages;
+    private injectStyles;
+}
+
+export { type FeatureFlag, type MaintenanceConfig, type MessagePosition, type MessageStyle, type MessageType, type SiteConfig, SiteManager, type SiteManagerConfig, type StatusMessage, SiteManager as default };