@subscribe.dev/react

@subscribe.dev/react

React hooks and components for SubscribeDev - provides context and hooks for managing AI predictions with billing and rate limiting.

Installation

npm install @subscribe.dev/react
# or
yarn add @subscribe.dev/react
# or
pnpm add @subscribe.dev/react
# or
bun add @subscribe.dev/react

Peer Dependencies

This package requires the following peer dependencies:

npm install react @clerk/clerk-react @tanstack/react-query

• React: ^18.0.0 || ^19.0.0
• @clerk/clerk-react: ^4.0.0 || ^5.0.0 (optional for authentication)
• @tanstack/react-query: ^5.0.0 (optional for query management)

Quick Start

1. Setup the Provider

Wrap your app with the SubscribeDevProvider:

import { SubscribeDevProvider } from '@subscribe.dev/react';

function App() {
  return (
    <SubscribeDevProvider
      projectToken="pub_your_project_token_here"
      clerkPublishableKey="pk_your_clerk_key_here"
      baseUrl="https://api.subscribe.dev" // optional
    >
      <YourAppContent />
    </SubscribeDevProvider>
  );
}

2. Use the Hooks

import { useSubscribeDev, useSubscribeDevAuth } from '@subscribe.dev/react';

function MyComponent() {
  const { client, token, isSignedIn } = useSubscribeDev();
  const { subscribe, isSubscribed } = useSubscribeDevAuth();

  if (!isSignedIn) {
    return <div>Please sign in</div>;
  }

  if (!isSubscribed) {
    return (
      <button onClick={subscribe}>
        Subscribe to continue
      </button>
    );
  }

  return (
    <div>
      <p>Ready to use AI services!</p>
    </div>
  );
}

API Reference

Components

SubscribeDevProvider

The main provider component that sets up authentication, query client, and SubscribeDev client.

Props:

• children: React.ReactNode - Child components
• projectToken: string - Your SubscribeDev project token (starts with pub_)
• clerkPublishableKey: string - Your Clerk publishable key
• baseUrl?: string - Optional API base URL (defaults to SubscribeDev API)

Authentication Components

SignIn

Iframe-compatible Clerk SignIn component with proper redirect handling.

import { SignIn } from '@subscribe.dev/react';

<SignIn />

SignInButton

Iframe-compatible Clerk SignInButton component.

import { SignInButton } from '@subscribe.dev/react';

<SignInButton>Sign In</SignInButton>

UserButton

Iframe-compatible Clerk UserButton component.

import { UserButton } from '@subscribe.dev/react';

<UserButton />

Hooks

useSubscribeDev()

Main hook providing access to client, authentication state, and storage utilities.

Returns:

{
  client: SubscribeDevClient | null;
  token: string | null;
  isSignedIn: boolean;
  subscribe: () => void;
  isSubscribed: boolean;
  subscriptionStatus: any;
  subscriptionLoading: boolean;
  refreshSubscriptionStatus: () => Promise<void>;
  useStorage: <T>(key: string, initialValue: T) => [T, (value: T) => void, SyncStatus];
}

useSubscribeDevAuth()

Authentication and subscription management hook.

Returns:

{
  isSignedIn: boolean;
  token: string | null;
  isSubscribed: boolean;
  subscribe: () => void;
  subscriptionStatus: any;
  subscriptionLoading: boolean;
  refreshSubscriptionStatus: () => Promise<void>;
}

useSubscribeDevStorage<T>(key: string, initialValue: T)

Persistent storage hook that syncs data between local storage and remote SubscribeDev storage.

Parameters:

• key: string - Storage key identifier
• initialValue: T - Default value if no stored data exists

Returns:

[
  T,                    // Current stored value
  (value: T) => void,   // Setter function
  SyncStatus           // Sync status: 'local' | 'syncing' | 'synced' | 'error'
]

Example:

function MyComponent() {
  const [userPrefs, setUserPrefs, syncStatus] = useSubscribeDevStorage('preferences', {
    theme: 'light',
    language: 'en'
  });

  return (
    <div>
      <p>Sync Status: {syncStatus}</p>
      <button onClick={() => setUserPrefs({ ...userPrefs, theme: 'dark' })}>
        Toggle Theme
      </button>
    </div>
  );
}

useClerkAuth()

Low-level Clerk authentication hook.

Returns:

{
  token: string | null;
  isSignedIn: boolean;
}

useStorage()

Low-level storage operations hook.

Returns:

{
  get: (key: string) => Promise<string | null>;
  set: (key: string, value: string) => Promise<void>;
  remove: (key: string) => Promise<void>;
}

Utilities

syncSession()

Hook for syncing session data between local and remote storage.

function MyComponent() {
  const sync = syncSession();
  
  useEffect(() => {
    sync(); // Sync session on mount
  }, [sync]);
}

Storage System

The package provides a robust storage system that automatically syncs data between:

• Local Storage - Browser-based storage for immediate access
• Remote Storage - SubscribeDev cloud storage for persistence across devices

Storage Features

• Automatic Sync: Data is automatically synchronized between local and remote storage
• Conflict Resolution: Remote data takes precedence during sync conflicts
• Error Handling: Graceful fallback to local storage if remote operations fail
• Type Safety: Full TypeScript support with generic types
• Real-time Status: Track sync status (local, syncing, synced, error)

Storage Example

import { useSubscribeDevStorage } from '@subscribe.dev/react';

function UserSettings() {
  const [settings, setSettings, syncStatus] = useSubscribeDevStorage('user-settings', {
    notifications: true,
    autoSave: false,
    theme: 'system'
  });

  const updateNotifications = (enabled: boolean) => {
    setSettings({
      ...settings,
      notifications: enabled
    });
  };

  return (
    <div>
      <div>Sync Status: {syncStatus}</div>
      <label>
        <input
          type="checkbox"
          checked={settings.notifications}
          onChange={(e) => updateNotifications(e.target.checked)}
        />
        Enable Notifications
      </label>
    </div>
  );
}

Subscription Management

The package includes built-in subscription management with modal-based upgrade flows.

Subscription Features

• Status Checking: Real-time subscription status monitoring
• Upgrade Flow: Integrated subscription modal with Stripe checkout
• Event Handling: Automatic refresh after subscription changes
• iframe Support: Optimized for iframe-based integrations

Subscription Example

import { useSubscribeDevAuth } from '@subscribe.dev/react';

function FeatureGate({ children }) {
  const { isSubscribed, subscribe, subscriptionLoading } = useSubscribeDevAuth();

  if (subscriptionLoading) {
    return <div>Loading subscription status...</div>;
  }

  if (!isSubscribed) {
    return (
      <div>
        <h3>Premium Feature</h3>
        <p>This feature requires a subscription.</p>
        <button onClick={subscribe}>
          Subscribe Now
        </button>
      </div>
    );
  }

  return <>{children}</>;
}

TypeScript Support

This package is written in TypeScript and provides comprehensive type definitions.

Type Definitions

type SyncStatus = 'local' | 'syncing' | 'synced' | 'error';

interface SubscribeDevContextValue {
  client: SubscribeDevClient | null;
  token: string | null;
  isSignedIn: boolean;
  queryClient: QueryClient;
  subscriptionModalUrl: string | null;
  setSubscriptionModalUrl: (url: string | null) => void;
}

Development

Building

bun run build          # Build for development
bun run build:publish  # Build for publishing

Development Mode

bun run dev           # Build in watch mode

Testing

bun run test          # Run tests
bun run typecheck     # Type checking only

Linting

bun run lint          # Lint source code

Requirements

• Node.js: >=18
• React: ^18.0.0 || ^19.0.0
• TypeScript: ^5.0.0 (for development)

License

MIT

Repository

This package is part of the SubscribeDev monorepo:

• Repository: https://github.com/volter-ai/remetricate
• Directory: packages/react

Related Packages

• @subscribe.dev/client: Core TypeScript client for SubscribeDev API
• API: SubscribeDev API server
• Frontend: SubscribeDev dashboard application