npm package: @paranexum/main
Description: Paranexum SDK for AI-powered business matching and recommendations
Author: Paranexum
Latest version: 1.1.4

# Paranexum SDK

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

## Installation

```bash
npm install paranexum-sdk
```

## Quick Start

### Vanilla JavaScript

```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

```jsx
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

```jsx
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

```jsx
'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.

```javascript
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.

```javascript
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):**
```javascript
// Only needed for vanilla JS or custom implementations
await sdk.trackClick(referenceProduct, recommendedProduct);
```

**View Your Analytics:**
```javascript
// Get aggregated analytics data
const analytics = await sdk.getUserAnalytics();
console.log(analytics);
```

## License

MIT