@alpha07/time-control

Time Access Control

A powerful React component for implementing time-based access control in frontend applications. Perfect for trial periods, subscription management, and access restrictions.

🚀 Quick Start

npm install time-control

import { TimeAccessControl } from 'time-control';

function App() {
  return (
    <>
      <TimeAccessControl 
        expiryDays={7}
        secretKey="your-secure-key"
      />
      <YourAppContent />
    </>
  );
}

✨ Features

• 🔒 Secure Time Tracking
  • AES encryption for data storage
  • Tamper-resistant implementation
  • Domain validation
• 🌐 Remote Management
  • Dynamic configuration
  • Remote kill switch
  • Custom messaging
• 🛡️ Robust Error Handling
  • Multiple fallback modes
  • Graceful degradation
  • Automatic recovery
• 🎨 Highly Customizable
  • Custom overlay components
  • Styling options
  • Event callbacks

📖 Usage Examples

Basic Implementation

import { TimeAccessControl } from 'time-control';

function App() {
  return (
    <div>
      <TimeAccessControl
        expiryDays={30}
        message="Your trial has expired. Please upgrade to continue."
        secretKey="your-secure-key-here"
      />
      <YourAppContent />
    </div>
  );
}

Advanced Implementation with Remote Control

import { TimeAccessControl } from 'time-control';

function App() {
  const handleExpiry = () => {
    analytics.track('trial_expired');
    showUpgradeModal();
  };

  return (
    <div>
      <TimeAccessControl
        remoteConfigUrl="https://api.example.com/access-config"
        fallbackMode="warn"
        onExpiry={handleExpiry}
        secretKey={process.env.REACT_APP_ACCESS_KEY}
        customComponent={
          <div className="custom-paywall">
            <h2>Trial Expired</h2>
            <button onClick={handleUpgrade}>
              Upgrade Now
            </button>
          </div>
        }
      />
      <YourAppContent />
    </div>
  );
}

Using Utility Functions

import { resetTimer, getTimeRemaining } from 'time-control';

// Reset trial period
function handleSubscriptionPurchase() {
  if (resetTimer('custom-key', 'secret-key')) {
    console.log('Trial period reset successfully');
  }
}

// Check remaining time
function DisplayTimeRemaining() {
  const daysLeft = getTimeRemaining('custom-key', 'secret-key', 30);
  
  return (
    <div>
      {daysLeft > 0 ? (
        <p>{daysLeft.toFixed(1)} days remaining in trial</p>
      ) : (
        <p>Trial expired</p>
      )}
    </div>
  );
}

🔧 Configuration

Component Props

Prop	Type	Default	Description
expiryDays	number	7	Duration of the trial period
message	string	"Trial period..."	Message shown on expiry
backgroundColor	string	"#ffffff"	Overlay background color
textColor	string	"#000000"	Overlay text color
storageKey	string	access..."	Local storage key
secretKey	string	"default..."	Encryption key
remoteConfigUrl	string	undefined	Remote config endpoint
fallbackMode	"block" | "warn" | "allow"	"block"	Error handling behavior
onExpiry	() => void	undefined	Expiry callback function
customComponent	ReactNode	undefined	Custom overlay component

Remote Configuration

Set up a JSON endpoint that returns:

{
  "isEnabled": true,
  "expiryDays": 14,
  "message": "Custom expiry message",
  "allowedDomains": ["example.com", "app.example.com"]
}

🔐 Security Best Practices

1. Secure Key Management

// DON'T: Expose keys in code
const secretKey = "1234567890";

// DO: Use environment variables
const secretKey = process.env.REACT_APP_ACCESS_KEY;

2. Domain Validation

{
  "allowedDomains": [
    "yourdomain.com",
    "app.yourdomain.com",
    "staging.yourdomain.com"
  ]
}

3. Error Handling

<TimeAccessControl
  fallbackMode="warn"  // Options: "block", "warn", "allow"
  onExpiry={() => {
    // Log error
    errorTracking.log('Trial expired');
    
    // Show upgrade modal
    showUpgradeModal();
    
    // Track analytics
    analytics.track('trial_expired');
  }}
/>

🚨 Error Handling

Fallback Modes

• block: Shows overlay on errors (default)
• warn: Logs warnings but allows access
• allow: Silently continues on errors

<TimeAccessControl
  fallbackMode="warn"
  onExpiry={() => {
    console.error('Access expired');
  }}
/>

🔄 Remote Management

Configuration Endpoint

Your API endpoint should return:

{
  "isEnabled": true,        // Master switch
  "expiryDays": 14,        // Override local settings
  "message": "Custom message",
  "allowedDomains": [      // Domain whitelist
    "example.com",
    "*.example.com"
  ]
}

Implementation

<TimeAccessControl
  remoteConfigUrl="https://api.example.com/access-config"
  fallbackMode="warn"
  onExpiry={() => {
    // Handle expiry
  }}
/>

🎨 Customization

Custom Overlay

function CustomOverlay() {
  return (
    <div className="custom-paywall">
      <h2>Premium Features Locked</h2>
      <p>Your trial period has expired.</p>
      <div className="pricing-plans">
        {/* Your pricing plans */}
      </div>
      <button onClick={handleUpgrade}>
        Upgrade Now
      </button>
    </div>
  );
}

<TimeAccessControl
  customComponent={<CustomOverlay />}
/>

Styling

<TimeAccessControl
  backgroundColor="rgba(0, 0, 0, 0.9)"
  textColor="#ffffff"
  customComponent={
    <div className="styled-overlay">
      {/* Custom styled content */}
    </div>
  }
/>

🔍 Troubleshooting

Common Issues

1. Timer Not Resetting

   • Check secretKey consistency
   • Verify localStorage access
   • Clear browser cache

2. Remote Config Failed

   • Verify endpoint URL
   • Check CORS settings
   • Validate JSON format

3. Domain Validation Issues

   • Update allowedDomains list
   • Check subdomain handling
   • Verify domain format

Debug Mode

<TimeAccessControl
  fallbackMode="warn"
  onExpiry={(error) => {
    console.log('Debug info:', {
      error,
      timeRemaining: getTimeRemaining(),
      localStorage: localStorage.getItem('time-control-start')
    });
  }}
/>

📦 API Reference

TimeAccessControl Component

interface TimeAccessControlProps {
  expiryDays?: number;
  message?: string;
  backgroundColor?: string;
  textColor?: string;
  storageKey?: string;
  secretKey?: string;
  remoteConfigUrl?: string;
  fallbackMode?: 'block' | 'warn' | 'allow';
  onExpiry?: () => void;
  customComponent?: React.ReactNode;
}

Utility Functions

function resetTimer(
  storageKey?: string,
  secretKey?: string
): boolean;

function getTimeRemaining(
  storageKey?: string,
  secretKey?: string,
  expiryDays?: number
): number;

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

📄 License

MIT License - see LICENSE file for details