@capivv/web-sdk

Capivv Web SDK for JavaScript/TypeScript applications with Stripe integration.

Installation

npm install @capivv/web-sdk
# or
yarn add @capivv/web-sdk
# or
pnpm add @capivv/web-sdk

Quick Start

Core SDK

import { Capivv } from '@capivv/web-sdk';

// Configure the SDK
Capivv.configure({
  apiKey: 'your-api-key',
  debug: true, // Optional: enable debug logging
});

// Identify a user
const { user, entitlements } = await Capivv.identify('user-123', {
  email: '[email protected]',
});

// Check entitlements
if (Capivv.hasEntitlement('premium')) {
  // Show premium features
}

// Get available offerings
const { current, all } = await Capivv.getOfferings();

// Purchase with Stripe
await Capivv.purchaseWithStripe({
  product: current.products[0],
  successUrl: 'https://example.com/success',
  cancelUrl: 'https://example.com/cancel',
});

React Integration

import { CapivvProvider, Paywall, useEntitlements } from '@capivv/web-sdk/react';

function App() {
  return (
    <CapivvProvider
      config={{ apiKey: 'your-api-key' }}
      userId="user-123"
      userAttributes={{ email: '[email protected]' }}
    >
      <YourApp />
    </CapivvProvider>
  );
}

function UpgradePage() {
  const { hasEntitlement } = useEntitlements();

  if (hasEntitlement('premium')) {
    return <div>You have premium access!</div>;
  }

  return (
    <Paywall
      title="Upgrade to Premium"
      subtitle="Get access to all features"
      features={['Unlimited access', 'Priority support', 'No ads']}
      ctaText="Subscribe Now"
      successUrl="/purchase/success"
      cancelUrl="/purchase/cancel"
    />
  );
}

Vanilla JavaScript

<script src="https://cdn.capivv.com/capivv.min.js"></script>
<div id="paywall-container"></div>
<script>
  Capivv.configure({ apiKey: 'your-api-key' });

  // Identify user
  Capivv.identify('user-123').then(function(result) {
    console.log('User:', result.user);

    // Mount paywall
    Capivv.mountPaywall('#paywall-container', {
      title: 'Upgrade to Premium',
      features: ['Unlimited access', 'Priority support'],
      successUrl: '/success',
    });
  });
</script>

Web Components

<script src="https://cdn.capivv.com/capivv.min.js"></script>
<script>
  Capivv.configure({ apiKey: 'your-api-key' });
  Capivv.identify('user-123');
</script>

<capivv-paywall
  title="Upgrade to Premium"
  subtitle="Get access to all features"
  features="Unlimited access,Priority support,No ads"
  cta-text="Subscribe Now"
  success-url="/success"
></capivv-paywall>

API Reference

Core SDK

Capivv.configure(config)

Configure the SDK with your API key.

Capivv.configure({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.capivv.com', // Optional
  debug: false, // Optional
  cacheEnabled: true, // Optional
  cacheTTL: 300000, // Optional: 5 minutes
});

Capivv.identify(userId, attributes?)

Identify a user and sync their entitlements.

const { user, entitlements, isNewUser } = await Capivv.identify('user-123', {
  email: '[email protected]',
  displayName: 'John Doe',
});

Capivv.hasEntitlement(identifier)

Check if the current user has a specific entitlement.

if (Capivv.hasEntitlement('premium')) {
  // User has premium access
}

Capivv.getOfferings()

Get available product offerings.

const { current, all } = await Capivv.getOfferings();
console.log('Current offering:', current);
console.log('All offerings:', all);

Capivv.purchaseWithStripe(params)

Initiate a Stripe checkout session.

const result = await Capivv.purchaseWithStripe({
  product: selectedProduct,
  successUrl: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancelUrl: 'https://example.com/cancel',
});

Capivv.verifyStripePurchase(sessionId)

Verify a Stripe checkout session after redirect.

// On success page
const params = new URLSearchParams(window.location.search);
const sessionId = params.get('session_id');

if (sessionId) {
  const result = await Capivv.verifyStripePurchase(sessionId);
  if (result.success) {
    console.log('Purchase verified!', result.entitlements);
  }
}

Capivv.openCustomerPortal(returnUrl?)

Open Stripe customer portal for subscription management.

await Capivv.openCustomerPortal('/account');

React Hooks

useCapivv()

Access the full Capivv context.

const { user, entitlements, isLoading, identify, logout } = useCapivv();

useEntitlements()

Access entitlement state and methods.

const { entitlements, hasEntitlement, refreshEntitlements, isLoading } = useEntitlements();

useEntitlement(identifier)

Check a specific entitlement.

const { isEntitled, isLoading } = useEntitlement('premium');

useOfferings()

Fetch and manage offerings.

const { offerings, currentOffering, isLoading, error, refetch } = useOfferings();

usePurchase()

Handle purchases.

const { purchase, isLoading, error } = usePurchase();

const handlePurchase = async (product) => {
  const result = await purchase(product, { successUrl: '/success' });
  if (result.success) {
    // Purchase initiated
  }
};

useCustomerPortal()

Manage customer portal.

const { open, isLoading, error } = useCustomerPortal();

<button onClick={() => open('/account')}>Manage Subscription</button>

React Components

<CapivvProvider>

Wrap your app to provide Capivv context.

<CapivvProvider
  config={{ apiKey: 'your-api-key' }}
  userId="user-123"
  userAttributes={{ email: '[email protected]' }}
>
  <App />
</CapivvProvider>

<Paywall>

Display a paywall with product selection.

<Paywall
  title="Choose Your Plan"
  subtitle="Select a plan that works for you"
  features={['Feature 1', 'Feature 2']}
  ctaText="Subscribe"
  successUrl="/success"
  cancelUrl="/cancel"
  onPurchaseComplete={(success) => console.log('Purchase:', success)}
/>

<PaywallModal>

Display a paywall in a modal dialog.

<PaywallModal
  isOpen={showPaywall}
  onClose={() => setShowPaywall(false)}
  title="Upgrade to Premium"
  features={['Unlimited access']}
/>

<EntitlementGate>

Conditionally render content based on entitlements.

<EntitlementGate
  entitlement="premium"
  fallback={<UpgradePrompt />}
  loading={<Spinner />}
>
  <PremiumFeature />
</EntitlementGate>

Stripe Helpers

import { StripeService, getSessionIdFromUrl, handleStripeSuccess } from '@capivv/web-sdk/stripe';

// Create a Stripe service instance
const stripe = new StripeService('pk_live_xxx');

// Create checkout session
await stripe.checkout({
  product: selectedProduct,
  successUrl: '/success',
});

// On success page
const result = await handleStripeSuccess();
if (result?.success) {
  console.log('Purchase verified!');
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions.

import type {
  CapivvConfig,
  User,
  Entitlement,
  Product,
  Offering,
  PurchaseResult,
} from '@capivv/web-sdk';

Browser Support

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

License

MIT