@lumnsh/react 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +72 -0
  2. package/dist/index.d.mts +151 -0
  3. package/dist/index.d.ts +151 -0
  4. package/dist/index.js +697 -0
  5. package/dist/index.mjs +661 -0
  6. package/package.json +65 -0
package/README.md ADDED
@@ -0,0 +1,72 @@
1
+ # @lumnsh/react
2
+
3
+ Lumn React SDK — entitlements, pricing, and checkout components.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ pnpm add @lumnsh/react @lumnsh/node
9
+ ```
10
+
11
+ ## LumnProvider
12
+
13
+ Wrap your app with `LumnProvider`. In Next.js App Router, add it to your root layout:
14
+
15
+ ```tsx
16
+ // app/layout.tsx
17
+ import { LumnProvider } from '@lumnsh/react';
18
+
19
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
20
+ return (
21
+ <html>
22
+ <body>
23
+ <LumnProvider apiKey={process.env.NEXT_PUBLIC_LUMN_PUBLISHABLE_KEY!} baseUrl="https://app.lumn.dev">
24
+ {children}
25
+ </LumnProvider>
26
+ </body>
27
+ </html>
28
+ );
29
+ }
30
+ ```
31
+
32
+ Place `LumnProvider` as close to the root as needed—it must wrap any component that uses `useLumnContext`, `useEntitlements`, `useSubscriptions`, `usePricing`, `LumnGate`, `LumnCheckout`, or `LumnPricing`.
33
+
34
+ ## Next.js App Router
35
+
36
+ All SDK components and hooks are client components (`'use client'`). Import them directly; no `dynamic(..., { ssr: false })` needed.
37
+
38
+ ```tsx
39
+ // app/dashboard/page.tsx
40
+ 'use client';
41
+
42
+ import { LumnGate, LumnPricing } from '@lumnsh/react';
43
+
44
+ export default function DashboardPage() {
45
+ return (
46
+ <>
47
+ <LumnGate feature="pro" customerId="cus_xxx" loadingFallback={<div>Loading…</div>}>
48
+ <ProFeature />
49
+ </LumnGate>
50
+ <LumnPricing customerId="cus_xxx" />
51
+ </>
52
+ );
53
+ }
54
+ ```
55
+
56
+ ## SSR behavior
57
+
58
+ | Component / Hook | SSR | Hydration |
59
+ |------------------|-----|-----------|
60
+ | LumnProvider | Renders children as-is | No API calls |
61
+ | LumnGate | Renders `loadingFallback` or `null` | `useEffect` fetches entitlement after mount; updates UI when result arrives |
62
+ | LumnPricing | Renders `loadingComponent` or "Loading…" | `usePricing` fetches products on mount |
63
+ | LumnCheckout | Renders placeholder | Checkout session created on user action |
64
+ | useEntitlements / useSubscriptions / usePricing | N/A (hooks) | Call API when invoked on the client |
65
+
66
+ `LumnGate` does not block SSR; it shows `loadingFallback` (or nothing) until the client hydrates and the entitlement API returns. Use `loadingFallback` to avoid layout shift.
67
+
68
+ ## Exports
69
+
70
+ - **Provider:** `LumnProvider`, `useLumnContext`
71
+ - **Components:** `LumnGate`, `LumnCheckout`, `LumnPricing`
72
+ - **Hooks:** `useEntitlements`, `useSubscriptions`, `useLumn` (entitlements + subscriptions), `usePricing`
package/dist/index.d.mts ADDED
@@ -0,0 +1,151 @@
1
+ import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import * as react from 'react';
3
+ import { ReactNode } from 'react';
4
+ import { Lumn, Product, EntitlementCheck, Subscription } from '@lumnsh/node';
5
+
6
+ type LumnTheme = 'dark' | 'light';
7
+ /** User-facing environment. Maps to DB: sandbox→development, live→production. */
8
+ type LumnEnvironment = 'sandbox' | 'live';
9
+ interface LumnContextValue {
10
+ /** Shared Lumn client instance. Use in hooks instead of creating new ones. */
11
+ lumn: Lumn;
12
+ /** Internal DB value (development/production). Use from LumnProvider env prop (sandbox/live). */
13
+ environment?: 'development' | 'production';
14
+ /** Accent color for buttons, highlights (default #22c55e). */
15
+ accentColor?: string;
16
+ theme?: LumnTheme;
17
+ }
18
+ interface LumnProviderProps {
19
+ apiKey: string;
20
+ baseUrl?: string;
21
+ /** User-facing: sandbox (test) or live (production). */
22
+ environment?: LumnEnvironment;
23
+ /** Accent color for LumnPricing CTA, IntervalSwitcher (default #22c55e). */
24
+ accentColor?: string;
25
+ /** Theme for LumnPricing (default dark). */
26
+ theme?: LumnTheme;
27
+ children: ReactNode;
28
+ }
29
+
30
+ declare function LumnProvider({ apiKey, baseUrl, environment, accentColor, theme, children, }: LumnProviderProps): react_jsx_runtime.JSX.Element;
31
+ declare function useLumnContext(): LumnContextValue;
32
+
33
+ type PricingInterval = 'monthly' | 'quarterly' | 'yearly';
34
+ interface FormatIntervalPriceOptions {
35
+ /** BCP 47 locale (e.g. 'en-US', 'zh-CN'). Default 'en-US'. */
36
+ locale?: string;
37
+ }
38
+ interface LumnPricingSelectPlanParams {
39
+ product: Product;
40
+ interval: PricingInterval;
41
+ checkout: () => void;
42
+ }
43
+ interface LumnPricingProps {
44
+ customerId?: string;
45
+ products?: Product[];
46
+ intervals?: PricingInterval[];
47
+ defaultInterval?: PricingInterval;
48
+ /** BCP 47 locale for formatIntervalPrice (e.g. 'zh-CN'). Ignored if formatPrice is custom. */
49
+ locale?: string;
50
+ onSelectPlan?: (params: LumnPricingSelectPlanParams) => void;
51
+ renderCard?: (product: Product, interval: PricingInterval) => ReactNode;
52
+ formatPrice?: (plan: {
53
+ amount?: number;
54
+ currency?: string;
55
+ tiers?: Array<{
56
+ unitAmount: number;
57
+ }>;
58
+ }, interval: string) => string;
59
+ loadingComponent?: ReactNode;
60
+ emptyComponent?: ReactNode;
61
+ errorComponent?: (error: Error) => ReactNode;
62
+ className?: string;
63
+ }
64
+
65
+ interface CheckoutBranding {
66
+ background_color?: string;
67
+ button_color?: string;
68
+ font_family?: string;
69
+ border_style?: 'pill' | 'rectangular' | 'rounded';
70
+ }
71
+ interface LumnCheckoutProps {
72
+ customerId: string;
73
+ /** Product slug (e.g. pro-plan), not Lumn product id. */
74
+ productSlug: string;
75
+ priceInterval?: PricingInterval;
76
+ /** Stripe Checkout iframe branding (background, button, font). Passed when creating session. */
77
+ branding?: CheckoutBranding;
78
+ onComplete?: () => void;
79
+ className?: string;
80
+ }
81
+
82
+ declare function LumnCheckout({ customerId, productSlug, priceInterval, branding, onComplete, className, }: LumnCheckoutProps): react_jsx_runtime.JSX.Element;
83
+
84
+ declare function LumnPricing({ customerId, products: productsProp, intervals, defaultInterval, locale, onSelectPlan, renderCard, formatPrice, loadingComponent, emptyComponent, errorComponent, className, }: LumnPricingProps): react_jsx_runtime.JSX.Element;
85
+
86
+ interface LumnGateUsageData {
87
+ used: number;
88
+ remaining: number;
89
+ reset_at: string;
90
+ }
91
+ interface LumnGateProps {
92
+ feature: string;
93
+ customerId?: string;
94
+ fallback?: ReactNode;
95
+ /** Rendered while entitlement check is loading. Reduces layout shift when provided. */
96
+ loadingFallback?: ReactNode;
97
+ /** When provided, renders used / remaining / reset_at from checkEntitlement (when available). */
98
+ renderUsage?: (data: LumnGateUsageData) => ReactNode;
99
+ children: ReactNode;
100
+ }
101
+
102
+ declare function LumnGate({ feature, customerId, fallback, loadingFallback, renderUsage, children, }: LumnGateProps): string | number | bigint | boolean | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null;
103
+
104
+ /** Usage balance from entitlements.check (limit, used, remaining, reset_at for quota display). */
105
+ type UsageBalance = Pick<EntitlementCheck, 'entitled' | 'feature_key' | 'limit' | 'unit_price_cents' | 'feature_type' | 'used' | 'remaining' | 'reset_at'>;
106
+ interface UseEntitlementsResult {
107
+ /** Check if customer has access to a feature. */
108
+ checkEntitlement: (featureKey: string, customerId?: string) => Promise<EntitlementCheck>;
109
+ /** Get feature usage balance (limit for quota display, unit_price for metered). */
110
+ getUsageBalance: (featureKey: string, customerId?: string) => Promise<UsageBalance>;
111
+ }
112
+ interface UseSubscriptionsResult {
113
+ /** List subscriptions by customer id (and optional product id). */
114
+ getSubscriptionState: (customerId: string, productId?: string) => Promise<Subscription[]>;
115
+ }
116
+ /** Options for getSubscriptionState (e.g. filter by product). Prefer getSubscriptionState(customerId, productId). */
117
+ interface LoadSubscriptionsOptions {
118
+ product_id?: string;
119
+ }
120
+ interface UseLumnResult {
121
+ checkEntitlement: (featureKey: string, customerId?: string) => Promise<EntitlementCheck>;
122
+ getUsageBalance: (featureKey: string, customerId?: string) => Promise<UsageBalance>;
123
+ getSubscriptionState: (customerId: string, productId?: string) => Promise<Subscription[]>;
124
+ }
125
+ interface UsePricingResult {
126
+ products: Product[];
127
+ isLoading: boolean;
128
+ error: Error | null;
129
+ refetch: () => void;
130
+ }
131
+
132
+ /** Convenience hook combining useEntitlements + useSubscriptions. Prefer useEntitlements or useSubscriptions when you only need one. */
133
+ declare function useLumn(): UseLumnResult;
134
+
135
+ declare function useEntitlements(): UseEntitlementsResult;
136
+
137
+ declare function useSubscriptions(): UseSubscriptionsResult;
138
+
139
+ interface IntervalPlan {
140
+ amount?: number;
141
+ currency?: string;
142
+ tiers?: Array<{
143
+ unitAmount: number;
144
+ }>;
145
+ }
146
+ declare function formatIntervalPrice(plan: IntervalPlan, _interval: string, options?: FormatIntervalPriceOptions): string;
147
+ declare function usePricing(options?: {
148
+ skip?: boolean;
149
+ }): UsePricingResult;
150
+
151
+ export { type CheckoutBranding, type FormatIntervalPriceOptions, type LoadSubscriptionsOptions, LumnCheckout, type LumnCheckoutProps, type LumnContextValue, type LumnEnvironment, LumnGate, type LumnGateProps, type LumnGateUsageData, LumnPricing, type LumnPricingProps, type LumnPricingSelectPlanParams, LumnProvider, type LumnProviderProps, type LumnTheme, type PricingInterval, type UsageBalance, type UseEntitlementsResult, type UseLumnResult, type UsePricingResult, type UseSubscriptionsResult, formatIntervalPrice, useEntitlements, useLumn, useLumnContext, usePricing, useSubscriptions };
package/dist/index.d.ts ADDED
@@ -0,0 +1,151 @@
1
+ import * as react_jsx_runtime from 'react/jsx-runtime';
2
+ import * as react from 'react';
3
+ import { ReactNode } from 'react';
4
+ import { Lumn, Product, EntitlementCheck, Subscription } from '@lumnsh/node';
5
+
6
+ type LumnTheme = 'dark' | 'light';
7
+ /** User-facing environment. Maps to DB: sandbox→development, live→production. */
8
+ type LumnEnvironment = 'sandbox' | 'live';
9
+ interface LumnContextValue {
10
+ /** Shared Lumn client instance. Use in hooks instead of creating new ones. */
11
+ lumn: Lumn;
12
+ /** Internal DB value (development/production). Use from LumnProvider env prop (sandbox/live). */
13
+ environment?: 'development' | 'production';
14
+ /** Accent color for buttons, highlights (default #22c55e). */
15
+ accentColor?: string;
16
+ theme?: LumnTheme;
17
+ }
18
+ interface LumnProviderProps {
19
+ apiKey: string;
20
+ baseUrl?: string;
21
+ /** User-facing: sandbox (test) or live (production). */
22
+ environment?: LumnEnvironment;
23
+ /** Accent color for LumnPricing CTA, IntervalSwitcher (default #22c55e). */
24
+ accentColor?: string;
25
+ /** Theme for LumnPricing (default dark). */
26
+ theme?: LumnTheme;
27
+ children: ReactNode;
28
+ }
29
+
30
+ declare function LumnProvider({ apiKey, baseUrl, environment, accentColor, theme, children, }: LumnProviderProps): react_jsx_runtime.JSX.Element;
31
+ declare function useLumnContext(): LumnContextValue;
32
+
33
+ type PricingInterval = 'monthly' | 'quarterly' | 'yearly';
34
+ interface FormatIntervalPriceOptions {
35
+ /** BCP 47 locale (e.g. 'en-US', 'zh-CN'). Default 'en-US'. */
36
+ locale?: string;
37
+ }
38
+ interface LumnPricingSelectPlanParams {
39
+ product: Product;
40
+ interval: PricingInterval;
41
+ checkout: () => void;
42
+ }
43
+ interface LumnPricingProps {
44
+ customerId?: string;
45
+ products?: Product[];
46
+ intervals?: PricingInterval[];
47
+ defaultInterval?: PricingInterval;
48
+ /** BCP 47 locale for formatIntervalPrice (e.g. 'zh-CN'). Ignored if formatPrice is custom. */
49
+ locale?: string;
50
+ onSelectPlan?: (params: LumnPricingSelectPlanParams) => void;
51
+ renderCard?: (product: Product, interval: PricingInterval) => ReactNode;
52
+ formatPrice?: (plan: {
53
+ amount?: number;
54
+ currency?: string;
55
+ tiers?: Array<{
56
+ unitAmount: number;
57
+ }>;
58
+ }, interval: string) => string;
59
+ loadingComponent?: ReactNode;
60
+ emptyComponent?: ReactNode;
61
+ errorComponent?: (error: Error) => ReactNode;
62
+ className?: string;
63
+ }
64
+
65
+ interface CheckoutBranding {
66
+ background_color?: string;
67
+ button_color?: string;
68
+ font_family?: string;
69
+ border_style?: 'pill' | 'rectangular' | 'rounded';
70
+ }
71
+ interface LumnCheckoutProps {
72
+ customerId: string;
73
+ /** Product slug (e.g. pro-plan), not Lumn product id. */
74
+ productSlug: string;
75
+ priceInterval?: PricingInterval;
76
+ /** Stripe Checkout iframe branding (background, button, font). Passed when creating session. */
77
+ branding?: CheckoutBranding;
78
+ onComplete?: () => void;
79
+ className?: string;
80
+ }
81
+
82
+ declare function LumnCheckout({ customerId, productSlug, priceInterval, branding, onComplete, className, }: LumnCheckoutProps): react_jsx_runtime.JSX.Element;
83
+
84
+ declare function LumnPricing({ customerId, products: productsProp, intervals, defaultInterval, locale, onSelectPlan, renderCard, formatPrice, loadingComponent, emptyComponent, errorComponent, className, }: LumnPricingProps): react_jsx_runtime.JSX.Element;
85
+
86
+ interface LumnGateUsageData {
87
+ used: number;
88
+ remaining: number;
89
+ reset_at: string;
90
+ }
91
+ interface LumnGateProps {
92
+ feature: string;
93
+ customerId?: string;
94
+ fallback?: ReactNode;
95
+ /** Rendered while entitlement check is loading. Reduces layout shift when provided. */
96
+ loadingFallback?: ReactNode;
97
+ /** When provided, renders used / remaining / reset_at from checkEntitlement (when available). */
98
+ renderUsage?: (data: LumnGateUsageData) => ReactNode;
99
+ children: ReactNode;
100
+ }
101
+
102
+ declare function LumnGate({ feature, customerId, fallback, loadingFallback, renderUsage, children, }: LumnGateProps): string | number | bigint | boolean | Iterable<react.ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<react.ReactNode> | null | undefined> | react_jsx_runtime.JSX.Element | null;
103
+
104
+ /** Usage balance from entitlements.check (limit, used, remaining, reset_at for quota display). */
105
+ type UsageBalance = Pick<EntitlementCheck, 'entitled' | 'feature_key' | 'limit' | 'unit_price_cents' | 'feature_type' | 'used' | 'remaining' | 'reset_at'>;
106
+ interface UseEntitlementsResult {
107
+ /** Check if customer has access to a feature. */
108
+ checkEntitlement: (featureKey: string, customerId?: string) => Promise<EntitlementCheck>;
109
+ /** Get feature usage balance (limit for quota display, unit_price for metered). */
110
+ getUsageBalance: (featureKey: string, customerId?: string) => Promise<UsageBalance>;
111
+ }
112
+ interface UseSubscriptionsResult {
113
+ /** List subscriptions by customer id (and optional product id). */
114
+ getSubscriptionState: (customerId: string, productId?: string) => Promise<Subscription[]>;
115
+ }
116
+ /** Options for getSubscriptionState (e.g. filter by product). Prefer getSubscriptionState(customerId, productId). */
117
+ interface LoadSubscriptionsOptions {
118
+ product_id?: string;
119
+ }
120
+ interface UseLumnResult {
121
+ checkEntitlement: (featureKey: string, customerId?: string) => Promise<EntitlementCheck>;
122
+ getUsageBalance: (featureKey: string, customerId?: string) => Promise<UsageBalance>;
123
+ getSubscriptionState: (customerId: string, productId?: string) => Promise<Subscription[]>;
124
+ }
125
+ interface UsePricingResult {
126
+ products: Product[];
127
+ isLoading: boolean;
128
+ error: Error | null;
129
+ refetch: () => void;
130
+ }
131
+
132
+ /** Convenience hook combining useEntitlements + useSubscriptions. Prefer useEntitlements or useSubscriptions when you only need one. */
133
+ declare function useLumn(): UseLumnResult;
134
+
135
+ declare function useEntitlements(): UseEntitlementsResult;
136
+
137
+ declare function useSubscriptions(): UseSubscriptionsResult;
138
+
139
+ interface IntervalPlan {
140
+ amount?: number;
141
+ currency?: string;
142
+ tiers?: Array<{
143
+ unitAmount: number;
144
+ }>;
145
+ }
146
+ declare function formatIntervalPrice(plan: IntervalPlan, _interval: string, options?: FormatIntervalPriceOptions): string;
147
+ declare function usePricing(options?: {
148
+ skip?: boolean;
149
+ }): UsePricingResult;
150
+
151
+ export { type CheckoutBranding, type FormatIntervalPriceOptions, type LoadSubscriptionsOptions, LumnCheckout, type LumnCheckoutProps, type LumnContextValue, type LumnEnvironment, LumnGate, type LumnGateProps, type LumnGateUsageData, LumnPricing, type LumnPricingProps, type LumnPricingSelectPlanParams, LumnProvider, type LumnProviderProps, type LumnTheme, type PricingInterval, type UsageBalance, type UseEntitlementsResult, type UseLumnResult, type UsePricingResult, type UseSubscriptionsResult, formatIntervalPrice, useEntitlements, useLumn, useLumnContext, usePricing, useSubscriptions };