Paranexum SDK

AI-powered business matching and recommendation SDK for JavaScript and React.

Installation

npm install paranexum-sdk

Quick Start

Vanilla JavaScript

import ParanexumSDK from 'paranexum';

const sdk = new ParanexumSDK('YOUR_API_KEY');

// Get recommendations (impressions are auto-tracked)
const recommendations = await sdk.getRecommendations({
  name: 'Product Name',
  description: 'Product description'
});

// Handle clicks (auto-tracked by React components)
// For vanilla JS, you can manually track clicks:
await sdk.trackClick(referenceProduct, recommendations.recommendation);

React with Banner Ad

import React, { useState } from 'react';
import { BannerAd } from 'paranexum/react';

function App() {
  const referenceProduct = { name: 'Laptop', description: 'Gaming laptop' };

  return (
    <BannerAd 
      apiKey="YOUR_API_KEY"
      referenceProduct={referenceProduct}
      width="100%"
      height="300px"
      onRecommendationClick={(rec) => console.log('Clicked:', rec)}
      // Impressions and clicks are auto-tracked!
    />
  );
}

export default App;

React with Checkout Ad

import React, { useState } from 'react';
import { CheckoutAd } from 'paranexum/react';

function Checkout() {
  const [showAd, setShowAd] = useState(true);
  const referenceProduct = { name: 'Laptop', description: 'Gaming laptop' };

  return (
    <>
      <h1>Checkout</h1>
      <CheckoutAd
        apiKey="YOUR_API_KEY"
        referenceProduct={referenceProduct}
        isOpen={showAd}
        onClose={() => setShowAd(false)}
        onBuyClick={(rec) => console.log('Add to cart:', rec)}
        // Impressions and clicks are auto-tracked!
      />
    </>
  );
}

export default Checkout;

Next.js with Hooks

'use client'; // Next.js 13+ App Router

import { useRecommendations, useAnalytics } from 'paranexum/nextjs';

export default function ProductPage() {
  const referenceProduct = { name: 'Laptop', description: 'Gaming laptop' };
  
  const { recommendation, isLoading, error } = useRecommendations(
    'YOUR_API_KEY',
    referenceProduct
  );
  
  const { trackClick } = useAnalytics('YOUR_API_KEY');

  const handleClick = async () => {
    if (recommendation) {
      await trackClick(referenceProduct, recommendation);
    }
  };

  if (isLoading) return <div>Loading recommendations...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!recommendation) return <div>No recommendations available</div>;

  return (
    <div onClick={handleClick} style={{ cursor: 'pointer', padding: '20px', border: '1px solid #ddd' }}>
      <h2>{recommendation.name}</h2>
      <p>{recommendation.description}</p>
      <p>Match Score: {(recommendation.matchScore * 100).toFixed(0)}%</p>
    </div>
  );
}

API Reference

ParanexumSDK

constructor(apiKey, options)

• apiKey (string): Your Paranexum API key (format: pk_BUSINESSID_RANDOM)
• options.baseUrl (string): Custom API endpoint (default: 'https://cdd1c127-1cfb-4fc0-901b-2ca43e10daf6-00-1ixvmejt0mwfv.janeway.replit.dev')

Note: Business ID is automatically extracted from your API key, so you don't need to provide it separately.

getRecommendations(product)

Get AI-powered product recommendations.

• product (object): Product with name and description
• Returns: Promise with recommendation and allRecommendations

trackImpression(referenceProduct, recommendedProduct)

Track when a recommendation is shown.

trackClick(referenceProduct, recommendedProduct)

Track when a recommendation is clicked.

getUserAnalytics()

Get your analytics data.

Next.js Hooks

useRecommendations

Fetch AI-powered recommendations with auto-impression tracking.

const { recommendation, allRecommendations, isLoading, error } = useRecommendations(
  apiKey,
  referenceProduct,
  { baseUrl: 'https://cdd1c127-1cfb-4fc0-901b-2ca43e10daf6-00-1ixvmejt0mwfv.janeway.replit.dev' } // optional
);

useAnalytics

Track clicks and impressions.

const { trackClick, trackImpression } = useAnalytics(
  apiKey,
  { baseUrl: 'https://cdd1c127-1cfb-4fc0-901b-2ca43e10daf6-00-1ixvmejt0mwfv.janeway.replit.dev' } // optional
);

React Components

BannerAd

Display recommendations as a promotional banner.

Props:

• apiKey (string): Your Paranexum API key
• referenceProduct (object): Product with name/description
• width (string): CSS width (default: '100%')
• height (string): CSS height (default: '300px')
• onRecommendationClick (function): Click handler
• loading (boolean): Show loading state

CheckoutAd

Display recommendations in a modal/popup style.

Props:

• apiKey (string): Your Paranexum API key
• referenceProduct (object): Product with name/description
• isOpen (boolean): Show/hide modal
• onClose (function): Close handler
• onBuyClick (function): Buy click handler

How Analytics Works

Automatic Tracking:

• Impressions are automatically tracked when getRecommendations() is called
• Clicks are automatically tracked when users click on recommendations in React components

Manual Tracking (if needed):

// Only needed for vanilla JS or custom implementations
await sdk.trackClick(referenceProduct, recommendedProduct);

View Your Analytics:

// Get aggregated analytics data
const analytics = await sdk.getUserAnalytics();
console.log(analytics);

License

MIT