i2go-insurance-sdk

Official SDK for I2GO Insurance Services - Create and update insurance quotations and payment links using the Embedded API with exact interface compatibility.

Features

• 🚀 Easy Setup - Simple configuration with auth tokens and product slugs
• 🔒 Secure - Built-in authentication and error handling
• 📝 TypeScript Support - Full TypeScript definitions matching your embedded.ts
• 🎯 CRUD Operations - Both create (POST) and update (PUT) quotations
• 🏷️ Product-Based - Configure once, use everywhere
• 📚 Interface Compatibility - Exact match with your embedded.ts interfaces

Installation

npm install i2go-insurance-sdk

Quick Start

import { I2GOSDK } from 'i2go-insurance-sdk';

// Initialize the SDK
const sdk = new I2GOSDK({
    baseOrigin: 'https://api.i2go.com/',
    authToken: 'your-auth-token',
    product: 'your-product-slug',
    productPlan: 'your-plan-slug', // optional
});

// Create a quotation
const quotation = await sdk.quickCreateQuotation({
    effectiveDate: '2024-01-01',
    product: 'your-product-slug',
    plan: 'your-plan-slug',
    policyHolder: {
        category: 'Person', // Required field
        firstName: 'John',
        lastName: 'Doe',
        email: '[email protected]',
        addresses: [
            // Required field
            {
                addressType: 'DEFAULT',
                line1: '123 Main Street',
                city: 'New York',
                postalCode: '10001',
                country: 'US',
            },
        ],
    },
    insuredItems: [
        {
            name: 'Test Item',
            value: 1000,
            attributes: [
                { key: 'color', key_display: 'Color', value: 'blue', value_display: 'Blue' },
                { key: 'model', key_display: 'Model', value: 'premium', value_display: 'Premium' },
            ],
        },
    ],
    skipRating: false,
    check_business_rules: true,
    activatePolicy: false,
    sendEmail: true,
    saveToDB: true,
});

// Update a quotation
const updatedQuotation = await sdk.quickUpdateQuotation('quotation-id', {
    effectiveDate: '2024-01-01',
    product: 'your-product-slug',
    plan: 'your-plan-slug',
    policyHolder: {
        firstName: 'Jane',
        lastName: 'Doe',
        email: '[email protected]',
        addresses: [
            {
                uuid: 'existing-address-uuid',
                addressType: 'BILLING',
                line1: '456 Updated Street',
                city: 'Updated City',
                postalCode: '20002',
                country: 'US',
            },
        ],
    },
    insuredItems: [],
    skipRating: false,
    check_business_rules: true,
    activatePolicy: false,
    sendEmail: true,
    saveToDB: true,
});

// Create payment link
const paymentUrl = await sdk.quickCreatePaymentLink(quotation);
console.log('Payment URL:', paymentUrl);

Configuration

Required Configuration

| Parameter | Type | Description | | ------------ | ------ | --------------------------------------------------------- | | baseOrigin | string | Base URL for the I2GO API (e.g., 'https://api.i2go.com/') | | authToken | string | Authentication token for API access | | product | string | Product slug for insurance product |

Optional Configuration

| Parameter | Type | Default | Description | | ----------------- | ------------ | ------- | ----------------------------------------- | | productPlan | string | - | Specific product plan slug | | apiVersion | 'v1' | 'v3' | 'v3' | API version to use | | headers | object | {} | Additional headers to include in requests | | customEndpoints | object | {} | Custom endpoint configurations |

API Reference

I2GOSDK Class

Constructor

new I2GOSDK(config: I2GOSDKConfig)

interface I2GOSDKConfig {
    baseOrigin: string;
    authToken: string;
    product: string;
    productPlan?: string;
    apiVersion?: 'v1' | 'v3';
    headers?: Record<string, string>;
    customEndpoints?: Record<string, EndpointType>;
}

Methods

quickCreateQuotation(data): Promise<EmbeddedCreationResponse>

Creates an insurance quotation using the EmbeddedCreationPayload interface structure.

Required Parameters:

• effectiveDate (string): Policy effective date (YYYY-MM-DD format)
• product (string): Product slug
• plan (string): Plan slug
• policyHolder (EmbeddedBpWithAddressCreationPayload): Policy holder information
  • category (PolicyHolderCategory): Required - 'Person' | 'Group' | 'Company'
  • firstName (string): First name
  • lastName (string): Last name
  • email (string): Email address
  • addresses (EmbeddedAddressCreationPayload[]): Required - Array of address objects
    • addressType (AddressTypeArray): Array of address types (e.g., ['DEFAULT', 'BILLING'])
    • line1 (string): Primary address line
    • city (string): City
    • country (string): Country
    • postalCode (string, optional): Postal code
    • state (string, optional): State
    • district (string, optional): District
    • building (string, optional): Building name
    • unitNo (string, optional): Unit number
• insuredItems (PolicyVersionItemCreationPayload[]): Items to insure
  • name (string): Item name
  • attributes (Attribute[]): Array of attribute objects with name/value pairs
  • value (number, optional): Item value
• skipRating (boolean): Skip rating calculation
• check_business_rules (boolean): Check business rules
• activatePolicy (boolean): Activate policy immediately
• sendEmail (boolean): Send notification email
• saveToDB (boolean): Save to database

Optional Parameters:

• registrationName (string): Registration name for companies
• dob (string): Date of birth
• gender (Gender): 'Male' | 'Female' | 'Others'
• phoneMobile (string): Mobile phone number
• nationality (string): Nationality
• idType (number): ID type
• extraData (object): Additional data
• policy_attributes (Attribute[]): Policy-level attributes
• policy_headers (Attribute[]): Policy headers
• progress (number): Progress indicator
• policy_term (PolicyTerm): Policy term
• externalPolicyNumber (string): External policy number
• additionalPartners (AdditionalBusinessPartnerCreationPayload[]): Additional partners
• coverages (EmbeddedCoveragePayload[]): Coverage configurations

Returns: Promise<EmbeddedCreationResponse>

quickUpdateQuotation(quotationId, data): Promise<EmbeddedCreationResponse>

Updates an existing quotation using the same structure as creation.

Parameters:

• quotationId (string): ID of the quotation to update
• effectiveDate (string): Policy effective date (YYYY-MM-DD format)
• product (string): Product slug
• plan (string): Plan slug
• policyHolder (EmbeddedBpWithAddressUpdatePayload): Policy holder information with UUID support
• insuredItems (PolicyVersionItemUpdatePayload[]): Items to insure with UUID support
• skipRating (boolean): Skip rating calculation
• check_business_rules (boolean): Check business rules
• activatePolicy (boolean): Activate policy immediately
• sendEmail (boolean): Send notification email
• saveToDB (boolean): Save to database

Returns: Promise<EmbeddedCreationResponse>

quickCreatePaymentLink(quotation): Promise<string>

Creates a payment link for a quotation.

Parameters:

• quotation (string | EmbeddedCreationResponse): Quotation ID or response object

Returns: Promise<string> - Payment URL

TypeScript Support

The SDK includes comprehensive TypeScript definitions matching your embedded.ts exactly:

import type {
    I2GOSDKConfig,
    EmbeddedCreationPayload,
    EmbeddedCreationResponse,
    EmbeddedUpdatePayload,
    EmbeddedBpWithAddressCreationPayload,
    EmbeddedBpWithAddressUpdatePayload,
    PolicyVersionItemCreationPayload,
    PolicyVersionItemUpdatePayload,
    AdditionalBusinessPartnerCreationPayload,
    EmbeddedAddressCreationPayload,
    EmbeddedCoveragePayload,
    Attribute,
    AddressTypeArray,
    PolicyHolderCategory,
    Gender,
    PolicyTerm,
} from 'i2go-insurance-sdk';

Error Handling

The SDK provides detailed error information:

try {
    const quotation = await sdk.quickCreateQuotation(data);
    console.log('Success:', quotation);
} catch (error) {
    console.error('Error:', error.message);
    // Error includes status code and response details
    if (error.response?.status === 400) {
        console.log('Validation errors:', error.response.data);
    }
}

Complete Example

import { I2GOSDK } from 'i2go-insurance-sdk';
import type { EmbeddedCreationPayload } from 'i2go-insurance-sdk';

const sdk = new I2GOSDK({
    baseOrigin: process.env.I2GO_BASE_ORIGIN!,
    authToken: process.env.I2GO_AUTH_TOKEN!,
    product: process.env.I2GO_PRODUCT_SLUG!,
    productPlan: process.env.I2GO_PLAN_SLUG,
});

async function createAndUpdateQuotationFlow() {
    try {
        // Create quotation with complete structure
        const quotationData: EmbeddedCreationPayload = {
            effectiveDate: '2024-01-01',
            product: 'vehicle-insurance',
            plan: 'comprehensive-plan',
            policyHolder: {
                category: 'Person',
                firstName: 'John',
                lastName: 'Doe',
                email: '[email protected]',
                gender: 'Male',
                dob: '1990-01-01',
                phoneMobile: '+1234567890',
                addresses: [
                    {
                        addressType: ['DEFAULT', 'BILLING'],
                        line1: '123 Main St',
                        city: 'New York',
                        state: 'NY',
                        postalCode: '10001',
                        country: 'US',
                        unitNo: '4B',
                    },
                ],
            },
            insuredItems: [
                {
                    name: 'Vehicle',
                    value: 25000,
                    attributes: [
                        { key: 'make', key_display: 'Make', value: 'Toyota', value_display: 'Toyota' },
                        { key: 'model', key_display: 'Model', value: 'Camry', value_display: 'Camry' },
                        { key: 'year', key_display: 'Year', value: 2023, value_display: '2023' },
                        { key: 'vin', key_display: 'VIN', value: '1234567890ABCDEF', value_display: '1234567890ABCDEF' },
                    ],
                },
            ],
            additionalPartners: [
                {
                    relationType: 'BENEFICIARY',
                    category: 'Person',
                    firstName: 'Jane',
                    lastName: 'Smith',
                    email: '[email protected]',
                },
            ],
            coverages: [
                {
                    coverageType: 'comprehensive',
                    limit: 50000,
                    deductible: 500,
                },
            ],
            policy_attributes: [
                { key: 'discount_type', key_display: 'Discount Type', value: 'loyalty', value_display: 'Loyalty' },
                { key: 'payment_plan', key_display: 'Payment Plan', value: 'annual', value_display: 'Annual' },
            ],
            policy_term: 'Yearly',
            skipRating: false,
            check_business_rules: true,
            activatePolicy: false,
            sendEmail: true,
            saveToDB: true,
        };

        const quotation = await sdk.quickCreateQuotation(quotationData);
        console.log('✅ Quotation created:', quotation.self.id);

        // Update quotation with UUID support
        const updatedQuotation = await sdk.quickUpdateQuotation(quotation.self.id, {
            effectiveDate: '2024-01-01',
            product: 'vehicle-insurance',
            plan: 'comprehensive-plan',
            policyHolder: {
                firstName: 'John',
                lastName: 'Smith', // Updated last name
                email: '[email protected]',
                addresses: [
                    {
                        uuid: 'existing-address-uuid', // Include UUID for update
                        addressType: 'DEFAULT',
                        line1: '456 Updated Street',
                        city: 'New York',
                        postalCode: '10001',
                        country: 'US',
                    },
                ],
            },
            insuredItems: [],
            skipRating: false,
            check_business_rules: true,
            activatePolicy: false,
            sendEmail: true,
            saveToDB: true,
        });

        console.log('✅ Quotation updated:', updatedQuotation.self.id);

        // Create payment link
        const paymentUrl = await sdk.quickCreatePaymentLink(quotation);
        console.log('✅ Payment URL:', paymentUrl);

        return { quotation, updatedQuotation, paymentUrl };
    } catch (error) {
        console.error('❌ Error:', error.message);
        if (error.response?.data) {
            console.error('Validation errors:', error.response.data);
        }
        throw error;
    }
}

Interface Compatibility

This SDK exactly matches your embedded.ts interfaces:

Address Structure (EmbeddedAddressCreationPayload)

{
    addressType: AddressTypeArray; // string[] or string
    line1: string;
    city: string;
    country: string;
    state?: string;
    district?: string;
    postalCode?: string;
    building?: string;
    unitNo?: string;
}

Policy Holder Structure (EmbeddedBpWithAddressCreationPayload)

{
    category: PolicyHolderCategory; // Required: 'Person' | 'Group' | 'Company'
    firstName: string;
    lastName: string;
    email: string;
    addresses: EmbeddedAddressCreationPayload[]; // Required
    registrationName?: string;
    dob?: string;
    gender?: Gender; // 'Male' | 'Female' | 'Others'
    phoneMobile?: string;
    nationality?: string;
    idType?: number;
    extraData?: Record<string, any>;
}

Insured Items Structure (PolicyVersionItemCreationPayload)

{
    name: string;
    attributes: Attribute[]; // Array of {key, key_display, value, value_display} objects
    value?: number;
}

Update Support with UUIDs

// Update operations support UUID targeting for nested objects
{
    uuid?: string; // For updating existing nested objects
    // ... other fields
}