@tour-kit/license API

import { LicenseProvider } from '@tour-kit/license';

<LicenseProvider
  licenseKey={process.env.NEXT_PUBLIC_TOURKIT_LICENSE_KEY!}
  organizationId={process.env.NEXT_PUBLIC_POLAR_ORG_ID}
  onValidate={(state) => console.log('License:', state.status)}
  onError={(err) => console.error(err)}
>
  {children}
</LicenseProvider>

import { LicenseGate } from '@tour-kit/license';

<LicenseGate
  require="pro"
  fallback={<UpgradePrompt />}
  loading={<Skeleton />}
>
  <AdoptionDashboard />
</LicenseGate>

import { ProGate } from '@tour-kit/license';

<ProGate package="@your-org/private-pro-pkg">
  <YourProComponent />
</ProGate>

import { LicenseWatermark } from '@tour-kit/license';

{isUnlicensed && <LicenseWatermark />}

import { LicenseWarning } from '@tour-kit/license';

<LicenseWarning />

import { useLicense } from '@tour-kit/license';

const { state, refresh, isGated, isLoading, gracePeriodActive } = useLicense();

import { useIsPro } from '@tour-kit/license';

const isPro = useIsPro();

import { useLicenseGate } from '@tour-kit/license';

const { isGated, isLoading } = useLicenseGate();
if (isGated) return <UnlicensedPlaceholder />;
if (isLoading) return null;

import { validateLicenseKey } from '@tour-kit/license';

const state = await validateLicenseKey({ key: 'TOURKIT-...', organizationId: '...' });
if (state.status !== 'valid') throw new Error('License invalid');

import { getCurrentDomain } from '@tour-kit/license';

const domain = getCurrentDomain(); // 'app.example.com' | null

import { isDevEnvironment } from '@tour-kit/license';

if (isDevEnvironment()) {
  console.log('Skipping license check in dev');
}

type LicenseTier = 'free' | 'pro';

type LicenseState = {
  status: 'valid' | 'invalid' | 'expired' | 'revoked' | 'loading' | 'error';
  tier: LicenseTier;
  activations: number;
  maxActivations: number;
  domain: string | null;
  expiresAt: string | null;
  validatedAt: number;
  renderKey: string | undefined;
};

type LicenseCache = {
  state: LicenseState;
  cachedAt: number;
  domain: string;
  keyHash?: string;
};

type LicenseActivation = {
  id: string;
  licenseKeyId: string;
  label: string;
  createdAt: string;
  modifiedAt: string | null;
};

type LicenseError =
  | 'invalid_key'
  | 'network_error'
  | 'parse_error'
  | 'activation_limit_reached'
  | 'domain_mismatch';

type LicenseConfig = {
  key: string;
  organizationId: string;
};

type LicenseContextValue = {
  state: LicenseState;
  refresh: () => Promise<void>;
  isGated: boolean;
  isLoading: boolean;
  gracePeriodActive: boolean;
};

type LicenseGateResult = {
  isGated: boolean;
  isLoading: boolean;
};

type LicenseProviderProps = {
  licenseKey: string;
  organizationId?: string;
  children: React.ReactNode;
  onValidate?: (state: LicenseState) => void;
  onError?: (error: Error) => void;
};

type LicenseGateProps = {
  require: 'pro';
  children: React.ReactNode;
  fallback?: React.ReactNode;
  loading?: React.ReactNode;
};

type ProGateProps = {
  package: string;
  children: React.ReactNode;
};

type LicenseWarningProps = {
  message?: string;
  pricingUrl?: string;
  dismissible?: boolean;
  onDismiss?: () => void;
  className?: string;
};

interface TrialConfig {
  durationDays: number;
  startsAt?: Date;             // defaults to first activation
  /** Optional grace window after expiry before gating closes */
  graceDays?: number;
  /** Storage namespace; defaults to '@tour-kit/license:trial' */
  storageKey?: string;
}

interface TrialContextValue {
  isTrialing: boolean;
  daysRemaining: number;
  expiresAt: Date | null;
  isExpired: boolean;
  start: () => void;
  end: () => void;
}

interface TrialBadgeRenderProps {
  daysRemaining: number;
  isExpired: boolean;
  expiresAt: Date | null;
}

interface TrialBadgeProps {
  className?: string;
  pricingUrl?: string;
  /** Render-prop override for custom badge UI */
  children?: (state: TrialBadgeRenderProps) => React.ReactNode;
}

interface LicenseDebugPanelProps {
  /** Position the floating panel; defaults to 'bottom-right' */
  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
  className?: string;
}

interface LicenseTestModeProps {
  /** Force a tier without making network calls (dev only) */
  forceTier?: 'free' | 'pro';
  children: React.ReactNode;
}

type PolarValidateResponse = {
  id: string;
  organizationId: string;
  status: 'granted' | 'revoked' | 'disabled';
  key: string;
  limitActivations: number | null;
  usage: number;
  validations: number;
  lastValidatedAt: string;
  expiresAt: string | null;
  activation: {
    id: string;
    licenseKeyId: string;
    label: string;
    meta: Record<string, unknown>;
    createdAt: string;
    modifiedAt: string | null;
  } | null;
};

type PolarActivateResponse = {
  id: string;
  licenseKeyId: string;
  label: string;
  meta: Record<string, unknown>;
  createdAt: string;
  modifiedAt: string | null;
  licenseKey: {
    id: string;
    organizationId: string;
    status: 'granted' | 'revoked' | 'disabled';
    limitActivations: number | null;
    usage: number;
    limitUsage: number | null;
    validations: number;
    lastValidatedAt: string;
    expiresAt: string | null;
  };
};