npm package: @insure-os/client
Description: InsureOS JavaScript client library for quote flow integration
Author: InsureOS Team
Latest version: 0.0.62

# @insure-os/scripts

A lightweight JavaScript client library for integrating InsureOS quote functionality into external websites. This library provides two simple integration methods: script tag with auto-initialization or NPM import with programmatic control.

---

## 🚀 Quick Start for Developers

### Publishing to NPM + CDN

```bash
# Publish to both NPM and CDN in one command
pnpm release
```

This will:
1. Bump patch version (0.0.0 → 0.0.1)
2. Build production bundles
3. Deploy to CDN: `https://cdn.os.insure`
4. Publish to NPM: `@insure-os/scripts`

**NPM Package:**
- Install: `npm install @insure-os/scripts`
- View: https://www.npmjs.com/package/@insure-os/scripts

**CDN URLs:**
- Versioned: `https://cdn.os.insure/v{version}/insureos.min.js`
- Major version: `https://cdn.os.insure/v{major}/insureos.min.js`
- Latest: `https://cdn.os.insure/latest/insureos.min.js`

📖 **Full guides:**
- [DEPLOYMENT.md](./DEPLOYMENT.md) - Quick deployment reference
- [NPM_PUBLISHING.md](./NPM_PUBLISHING.md) - NPM publishing guide
- [CDN_SETUP.md](./CDN_SETUP.md) - CDN configuration
- [DOCS_INDEX.md](./DOCS_INDEX.md) - All documentation

---

## Features

- 🚀 **Simple Integration** - Two easy ways to integrate: script tag or NPM import
- 🎯 **Auto-initialization** - Script tag automatically creates quote intents and renders buttons
- 🎨 **Customizable Styling** - Well-named CSS classes for easy styling
- 🔒 **Secure Authentication** - Built-in organization-based authentication
- ⚡ **Lightweight** - Minimal bundle size with essential functionality only

## Installation & Usage

### Method 1: Script Tag (CDN - Recommended for external sites)

Add a script tag from our CDN. This is the easiest way for external websites to integrate InsureOS.

```html
<!DOCTYPE html>
<html>
    <head>
        <title>Insurance Quote</title>
        <style>
            /* Style the button with well-named CSS classes */
            .insureos-submit-btn {
                background-color: #007bff;
                color: white;
                border: none;
                padding: 12px 24px;
                font-size: 16px;
                border-radius: 6px;
                cursor: pointer;
                font-family: system-ui, sans-serif;
            }

            .insureos-submit-btn:hover:not(:disabled) {
                background-color: #0056b3;
            }

            .insureos-loading {
                background-color: #6c757d;
                cursor: not-allowed;
            }

            .insureos-error {
                color: #dc3545;
                padding: 12px;
                border: 1px solid #dc3545;
                border-radius: 4px;
                background-color: #f8d7da;
            }
        </style>
    </head>
    <body>
        <h1>Get Your Insurance Quote</h1>

        <!-- Load InsureOS from CDN (use specific version for production) -->
        <script
            src="https://cdn.os.insure/v0.0.0/insureos.min.js"
            integrity="sha384-x6rqyvqpRkF+stuy4Ydnp+gou2baQOQFXkfw7bt/NVtF2I0VJiXV8neu2iIDSLzf"
            crossorigin="anonymous">
        </script>

        <script>
            // Initialize InsureOS and mount to container
            const client = new InsureOSScripts.InsureOS({
                apiKey: 'your-api-key',
                environment: 'production',
            });

            client.mount('#insureos-container', {
                quoteIntentId: 'your-quote-intent-id',
            });
        </script>
    </body>
</html>
```

### Method 2: NPM Import with mount()

Install the package and use the `InsureOS.mount()` method for programmatic control.

```bash
npm install @insure-os/scripts
```

```javascript
import { InsureOS } from "@insure-os/scripts";

// Mount to a specific DOM element
const container = document.getElementById("quote-container");
InsureOS.mount(container, {
    orgId: "your-org-id",
});
```

```html
<!DOCTYPE html>
<html>
    <head>
        <title>Insurance Quote</title>
        <style>
            .insureos-submit-btn {
                background-color: #007bff;
                color: white;
                border: none;
                padding: 12px 24px;
                font-size: 16px;
                border-radius: 6px;
                cursor: pointer;
            }
        </style>
    </head>
    <body>
        <h1>Get Your Insurance Quote</h1>
        <div id="quote-container"></div>

        <script type="module" src="./main.js"></script>
    </body>
</html>
```

## API Reference

### InsureOS.mount()

Mounts InsureOS quote functionality to a DOM element.

```typescript
InsureOS.mount(element: HTMLElement, config: MountConfig): Promise<void>
```

**Parameters:**

- `element` - DOM element to mount the quote button to
- `config` - Configuration object

**MountConfig:**

```typescript
interface MountConfig {
    orgId: string; // Required: Your organization ID
    apiBaseUrl?: string; // Optional: Custom API base URL (defaults to https://api.os.insure)
}
```

**Example:**

```javascript
import { InsureOS } from "@insure-os/scripts";

// Basic usage
InsureOS.mount(document.getElementById("quote-btn"), {
    orgId: "123",
});

// With custom API URL (for development)
InsureOS.mount(document.getElementById("quote-btn"), {
    orgId: "123",
    apiBaseUrl: "http://localhost:3000/dev",
});
```

## How It Works

1. **Initialization**: The library initializes with your organization ID
2. **Quote Intent Creation**: Automatically creates a blank quote intent via API call
3. **Button Rendering**: Renders a submit button with loading states
4. **User Interaction**: When clicked, redirects user to the signed quote URL

## CSS Classes for Styling

The library uses well-named CSS classes that you can style:

- `.insureos-submit-btn` - Main submit button
- `.insureos-loading` - Loading state (added to button)
- `.insureos-error` - Error message display

## Examples

### React Integration

```jsx
import React, { useEffect, useRef } from "react";
import { InsureOS } from "@insure-os/scripts";

function QuoteButton({ orgId }) {
    const containerRef = useRef(null);

    useEffect(() => {
        if (containerRef.current) {
            InsureOS.mount(containerRef.current, { orgId });
        }
    }, [orgId]);

    return <div ref={containerRef} />;
}
```

### Vue.js Integration

```vue
<template>
    <div ref="quoteContainer"></div>
</template>

<script>
import { InsureOS } from "@insure-os/scripts";

export default {
    props: ["orgId"],
    mounted() {
        InsureOS.mount(this.$refs.quoteContainer, {
            orgId: this.orgId,
        });
    },
};
</script>
```

### Multiple Buttons

```javascript
import { InsureOS } from "@insure-os/scripts";

// Mount multiple buttons for different organizations
InsureOS.mount(document.getElementById("quote-1"), { orgId: "123" });
InsureOS.mount(document.getElementById("quote-2"), { orgId: "456" });
InsureOS.mount(document.getElementById("quote-3"), { orgId: "789" });
```

## Error Handling

The library handles errors gracefully:

- **Network errors**: Shows error message with retry capability
- **API errors**: Displays user-friendly error messages
- **Configuration errors**: Clear error messages for missing orgId

Errors are displayed using the `.insureos-error` CSS class.

## Browser Support

- **Modern Browsers**: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
- **Required Features**: Fetch API, Promises, ES2017 syntax

## TypeScript Support

Full TypeScript definitions are included:

```typescript
import { InsureOS, MountConfig, QuoteIntentResponse } from "@insure-os/scripts";

const config: MountConfig = {
    orgId: "your-org-id",
    apiBaseUrl: "https://api.os.insure",
};

InsureOS.mount(element, config);
```

## License

MIT License - see [LICENSE](LICENSE) file for details.