@insure-os/client

v0.0.53

Published

2 days ago

InsureOS JavaScript client library for quote flow integration

0High
0Medium
0Low

alexclark

nzbasic

insurance quote client javascript typescript insure-os embedded widget integration

@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

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

This will:

Bump patch version (0.0.0 → 0.0.1)
Build production bundles
Deploy to CDN: https://cdn.os.insure
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 - Quick deployment reference
NPM_PUBLISHING.md - NPM publishing guide
CDN_SETUP.md - CDN configuration
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.

<!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.

npm install @insure-os/scripts

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",
});

<!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.

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

Parameters:

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

MountConfig:

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

Example:

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

Initialization: The library initializes with your organization ID
Quote Intent Creation: Automatically creates a blank quote intent via API call
Button Rendering: Renders a submit button with loading states
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

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

<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

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:

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 file for details.