sponsored-messaging-sdk/README.md

SDK for integrating sponsored content into chat applications

# Sponsored Messaging SDK

SDK for interacting with the Sponsored Messaging API, with support for multiple JavaScript frameworks.

## Installation

```bash
npm install sponsored-messaging-sdk
# or
yarn add sponsored-messaging-sdk
```

## Usage

### Vanilla JavaScript

#### ES Module Import

```javascript
import SponsoredMessaging from 'sponsored-messaging-sdk';

const sdk = new SponsoredMessaging({
  apiBaseUrl: 'https://your-api-url.com',
  sourceAppId: 'your-app-id',
  chatContainerId: 'chatArea',
  sponsorshipMode: 'chat' // or 'message'
});

// Check sponsorship for a message
async function checkMessageSponsorship(userMessage, aiResponse) {
  try {
    const result = await sdk.checkSponsorship({
      userMessage,
      aiResponse
    });
    
    console.log('Is sponsored:', result.isSponsored);
    if (result.isSponsored) {
      console.log('Sponsor details:', result.sponsorDetails);
    }
    
    return result;
  } catch (error) {
    console.error('Error checking sponsorship:', error);
    return { isSponsored: false };
  }
}
```

#### Script Tag (UMD)

```html
<script src="https://cdn.example.com/sponsored-messaging-sdk.umd.min.js"></script>
<script>
  const sdk = new SponsoredMessaging({
    apiBaseUrl: 'https://your-api-url.com',
    sourceAppId: 'your-app-id',
    chatContainerId: 'chatArea',
    sponsorshipMode: 'chat'
  });
  
  // Use the SDK as needed
</script>
```

### React Integration

```jsx
import React from 'react';
import { SponsoredMessagingProvider, useSponsoredMessaging } from 'sponsored-messaging-sdk';

// Wrap your app or component with the provider
function App() {
  return (
    <SponsoredMessagingProvider
      apiBaseUrl="https://your-sponsorship-api.com"
      sourceAppId="my-react-app"
      chatContainerId="chat-container"
      sponsorshipMode="message"
    >
      <ChatComponent />
    </SponsoredMessagingProvider>
  );
}

// Use the SDK in any child component
function ChatComponent() {
  const sdk = useSponsoredMessaging();
  const [messages, setMessages] = useState([]);
  
  const sendMessage = async (userMessage) => {
    // Add user message to chat
    setMessages(prev => [...prev, { type: 'user', content: userMessage }]);
    
    // Simulate AI response
    const aiResponse = `This is a response about "${userMessage}"`;
    
    try {
      // Check sponsorship
      const result = await sdk.checkSponsorship({
        userMessage,
        aiResponse,
        userSessionId: localStorage.getItem('user_session_id')
      });
      
      // Handle the result
      if (result.isSponsored) {
        setMessages(prev => [...prev, { 
          type: 'sponsored', 
          content: result.rawContent,
          sponsorData: result
        }]);
      } else {
        setMessages(prev => [...prev, { 
          type: 'ai', 
          content: result.rawContent || aiResponse 
        }]);
      }
    } catch (error) {
      console.error('Error checking sponsorship:', error);
      setMessages(prev => [...prev, { type: 'ai', content: aiResponse }]);
    }
  };
  
  return (
    <div id="chat-container">
      {/* Chat UI */}
    </div>
  );
}
```

## API Reference

### `new SponsoredMessaging(options)`

Initializes the SDK.

-   `options` (Object): Configuration options.
    -   `apiBaseUrl` (String, required): The base URL for the Sponsored Messaging API.
    -   `sourceAppId` (String, required): Identifier for the source application using the SDK.
    -   `chatContainerId` (String, required): The ID of the HTML element containing chat messages.
    -   `sponsorshipMode` (String, optional): How to display sponsorship ('message' or 'chat'). Defaults to 'message'.

### `checkSponsorship(options)`

Checks if a given AI response should be replaced with sponsored content.

-   `options` (Object): Details for the sponsorship check.
    -   `userMessage` (String, required): The user's input message.
    -   `aiResponse` (String, required): The AI's generated response.
    -   `userSessionId` (String, optional): A unique identifier for the user's session.
    -   `sourceAppId` (String, optional): An identifier for the application using the SDK.
-   **Returns**: `Promise<Object>` - Resolves with the API response or a default object `{ isSponsored: false, rawContent: aiResponse }` on failure.

### `trackClick(options)`

Tracks a user click on sponsored content.

-   `options` (Object): Details for tracking the click.
    -   `campaignId` (String, required): The ID of the campaign associated with the clicked content.
    -   `userSessionId` (String, optional): A unique identifier for the user's session.
    -   `sourceAppId` (String, optional): An identifier for the application using the SDK.
-   **Returns**: `Promise<void>` - Resolves when the tracking request is sent. Errors are logged silently.

## React Components

### `<SponsoredMessagingProvider>`

React context provider that initializes the SDK and makes it available to child components.

- Props:
  - `apiBaseUrl` (String, required): The base URL for the Sponsored Messaging API.
  - `sourceAppId` (String, required): Identifier for the source application using the SDK.
  - `chatContainerId` (String, required): The ID of the HTML element containing chat messages.
  - `sponsorshipMode` (String, optional): How to display sponsorship ('message' or 'chat'). Defaults to 'message'.
  - `children` (ReactNode): Child components that will have access to the SDK.

### `useSponsoredMessaging()`

React hook to access the SDK instance from any component within a `SponsoredMessagingProvider`.

- Returns: The initialized `SponsoredMessaging` instance.

## Build Formats

The SDK is available in multiple formats:

- **ESM** (`dist/sponsored-messaging-sdk.esm.js`): For modern bundlers and environments that support ES modules.
- **CommonJS** (`dist/sponsored-messaging-sdk.cjs.js`): For Node.js and bundlers that support CommonJS.
- **UMD** (`dist/sponsored-messaging-sdk.umd.js`): For direct use in browsers via script tags.
- **UMD (minified)** (`dist/sponsored-messaging-sdk.umd.min.js`): Minified version for production use in browsers.