@insurup/contracts

InsurUp Contracts

Type-safe TypeScript contracts and type definitions for the InsurUp insurance platform. Use standalone for custom implementations or alongside @insurup/sdk.

---

Installation

npm install @insurup/contracts

pnpm add @insurup/contracts

bun add @insurup/contracts

---

Usage

Import Types

import type {
  Customer,
  CustomerType,
  Policy,
  PolicyState,
  ProductBranch,
  Vehicle,
  Property,
  Case,
  CaseState,
} from '@insurup/contracts';

Use with Your Own API Client

import type { Customer, CreateCustomerRequest, CustomerResponse } from '@insurup/contracts';

async function createCustomer(data: CreateCustomerRequest): Promise<Customer> {
  const response = await fetch('/api/customers', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data),
  });

  const result: CustomerResponse = await response.json();
  return result.data;
}

Type Guards and Validation

import { CustomerType, PolicyState } from '@insurup/contracts';

function isIndividualCustomer(type: CustomerType): boolean {
  return type === CustomerType.Individual;
}

function isPolicyActive(state: PolicyState): boolean {
  return state === PolicyState.Active;
}

GraphQL Query Types

Every entity exposes three input types and one sort type per resource:

• Query<Entity>FilterInput — the wire shape of the filtering_* GraphQL input (server-side only; consumers rarely construct this directly).
• Query<Entity>SearchInput — the wire shape of searching_* (same).
• Query<Entity>UnifiedFilterInput — the consumer-facing unified shape; per-field map where entries with $search: true route to the search slot. This is what you build.
• Query<Entity>SortInput — sort field map.

Plus SortEnumType and PageInfo from common.

import {
  CustomerType,
  SortEnumType,
  type QueryCustomerModelUnifiedFilterInput,
  type QueryCustomerModelSortInput,
  type PageInfo,
} from '@insurup/contracts';

// Unified filter — `$search: true` promotes a per-field entry to the
// server's search slot when used through @insurup/sdk or the table adapter.
const filter: QueryCustomerModelUnifiedFilterInput = {
  type: { eq: CustomerType.Individual },
  createdAt: { gte: '2024-01-01' },
  name: { $search: true, textSearch: 'ali' },
};

const order: QueryCustomerModelSortInput[] = [{ createdAt: SortEnumType.DESC }];

Runtime introspection

Every entity also ships a generated Query<Entity>Meta const (per-field type, nullability, filter/search operator lists). Useful for dynamic filter UIs:

import { QueryCustomerModelMeta } from '@insurup/contracts';

QueryCustomerModelMeta.name.filterable; // true
QueryCustomerModelMeta.name.filterOperators;
// ['eq','neq','in','nin','contains','notContains','startsWith','notStartsWith','endsWith','notEndsWith']
QueryCustomerModelMeta.name.searchable; // true
QueryCustomerModelMeta.type.values; // ['INDIVIDUAL','COMPANY','FOREIGN']

---

Available Types

Core Domains

Module	Description	Key Types
Customers	Customer profiles and contact info	Customer, CustomerType, CreateCustomerRequest, UpdateCustomerRequest
Policies	Insurance policies and documents	Policy, PolicyState, PolicyDocument, PolicyRepresentative
Proposals	Insurance quotes and comparisons	Proposal, ProposalComparison, CreateProposalRequest
Vehicles	Vehicle data and lookups	Vehicle, VehicleBrand, VehicleModel, UsageType
Properties	Property and DASK insurance	Property, PropertyType, DaskPolicy
Cases	Claims, complaints, service requests	Case, CaseState, CaseType, CasePriority
Coverage	Coverage configuration	Coverage, CoverageGroup, CoverageDefinition

Agent & Organization

Module	Description	Key Types
Agents	Insurance agents and companies	Agent, AgentProfile, AgentCompanyConnection
Agent Branches	Branch management	AgentBranch, CreateBranchRequest
Agent Users	Staff and access control	AgentUser, AgentRole, Permission

Platform

Module	Description	Key Types
Insurance	Companies and products	InsuranceCompany, InsuranceProduct, ResourceKey
Webhooks	Event notifications	Webhook, WebhookEvent, WebhookDelivery
Files	Document management	FileUpload, FileMetadata
Templates	Document templates	Template, TemplateType
Languages	Localization	Language, TranslationKey

Common Types

Type	Description
DateTime	ISO 8601 date-time string
DateOnly	ISO 8601 date string (YYYY-MM-DD)
Money	Monetary value with currency
Address	Structured address
PhoneNumber	Phone with country code
ProductBranch	Insurance product categories (Traffic, Casco, Health, etc.)

GraphQL Types

For building GraphQL queries with filtering, sorting, and pagination:

import type {
  // Pagination
  GraphQLPageInfo,
  GraphQLConnection,

  // Filtering
  CustomerFilterInput,
  PolicyFilterInput,
  CaseFilterInput,
  StringOperationFilterInput,
  IntOperationFilterInput,
  DateTimeOperationFilterInput,

  // Sorting
  CustomerSortInput,
  PolicySortInput,
  SortEnumType,

  // Search
  CustomerSearchInput,
  SearchTextInput,
} from '@insurup/contracts';

---

Runtime Field Metadata

Every Query*Model / Query*Result interface has an auto-generated runtime metadata object that describes its fields -- their types, nullability, and enum values. Useful for building dynamic UIs, filters, column configuration, and validation without hard-coding field info.

Using getModelMeta

Look up any model's metadata by name with full autocomplete and type safety:

import { getModelMeta } from '@insurup/contracts';

const meta = getModelMeta('QueryCustomerModel');

meta.id.type; // "string"
meta.createdAt.type; // "DateTime"
meta.gender.type; // "enum"
meta.gender.values; // readonly ["UNKNOWN", "MALE", "FEMALE", "OTHER"]
meta.gender.nullable; // true

Importing Individual Meta Objects

import { QueryCustomerModelMeta, QueryPoliciesResultMeta } from '@insurup/contracts';

// Check if a field is an enum
if (QueryCustomerModelMeta.type.type === 'enum') {
  console.log(QueryCustomerModelMeta.type.values);
  // ["INDIVIDUAL", "COMPANY", "FOREIGN"]
}

Available Meta Objects

Meta Object	Source Interface
QueryCustomerModelMeta	QueryCustomerModel
QueryCustomerConsentModelMeta	QueryCustomerConsentModel
QueryCaseModelMeta	QueryCaseModel
QueryPoliciesResultMeta	QueryPoliciesResult
QueryProposalsResultMeta	QueryProposalsResult
QueryAgentUserResultMeta	QueryAgentUserResult
QueryWebhookDeliveryResultMeta	QueryWebhookDeliveryResult
QueryPolicyTransfersResultMeta	QueryPolicyTransfersResult
QueryFilePolicyTransfersResultMeta	QueryFilePolicyTransfersResult

Field Types

Each field in a meta object has a type discriminant:

type	Description	Extra Properties
"string"	String field	nullable?
"number"	Number field	nullable?
"boolean"	Boolean field	nullable?
"DateTime"	ISO 8601 date-time	nullable?
"DateOnly"	Date-only (YYYY-MM-DD)	nullable?
"enum"	Enum field	values, nullable?

Note: Meta objects are auto-generated from interfaces marked with @meta JSDoc tags. Object and array properties are excluded -- only primitive, date, and enum fields are included.

---

Enums

All enums are exported as both types and runtime values:

import {
  CustomerType, // Enum value
  PolicyState, // Enum value
  ProductBranch, // Enum value
  CaseState, // Enum value
  CasePriority, // Enum value
} from '@insurup/contracts';

// Use as values
const type = CustomerType.Individual;
const state = PolicyState.Active;
const branch = ProductBranch.Traffic;

// Use as types
function handlePolicy(state: PolicyState): void {
  switch (state) {
    case PolicyState.Active:
      // ...
      break;
    case PolicyState.Cancelled:
      // ...
      break;
  }
}

Key Enums

Enum	Values
CustomerType	Individual, Corporate
PolicyState	Active, Cancelled, Expired, Pending
ProductBranch	Traffic, Casco, Health, Dask, Travel, Liability, ...
CaseState	Open, InProgress, Resolved, Closed
CasePriority	Low, Medium, High, Critical
CaseType	Claim, Complaint, ServiceRequest, Inquiry
SortEnumType	Asc, Desc

---

When to Use This Package

Scenario	Recommendation
Building a full application with InsurUp	Use @insurup/sdk (includes all types)
Custom HTTP client implementation	Use @insurup/contracts
Shared library with InsurUp types	Use @insurup/contracts
Backend validation schemas	Use @insurup/contracts
Type-only imports (no runtime)	Use @insurup/contracts

---

Compatibility

Environment	Support
Node.js	18+
Browsers	ES2022+
Bun	1.0+
Deno	1.0+

Dual ESM/CJS builds included. Full tree-shaking support.

---

Related Packages

• @insurup/sdk — Full-featured SDK with HTTP client, GraphQL support, and error handling

---

License

MIT