# @insurup/contracts

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

Latest version **0.1.42** (published 2026-06-30) · MIT license · 0 weekly downloads

## Install

```sh
npm install @insurup/contracts
pnpm add @insurup/contracts
yarn add @insurup/contracts
bun add @insurup/contracts
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.42 |
| Published | 2026-06-30 |
| First published | 2026-01-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 3.6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | InsurUp Team |
| Maintainers | kerem-acer |
| Keywords | insurup, insurance, contracts, types, typescript, policy, claims, coverage, vehicle-insurance, property-insurance |

## Links

- npm: https://www.npmjs.com/package/@insurup/contracts
- Repository: https://github.com/InsurUp/ts-toolkit
- Homepage: https://github.com/InsurUp/ts-toolkit#readme
- Issues: https://github.com/InsurUp/ts-toolkit/issues
- npm.io page: https://npm.io/package/@insurup/contracts

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.1.42 (latest) — 2026-06-30
- 0.1.40 — 2026-06-16
- 0.1.39 — 2026-06-10
- 0.1.38 — 2026-06-10
- 0.1.37 — 2026-06-10
- 0.1.36 — 2026-06-09
- 0.1.35 — 2026-06-08
- 0.1.34 — 2026-06-06
- 0.1.33 — 2026-06-05
- 0.1.32 — 2026-06-04
- 0.1.31 — 2026-05-31
- 0.1.30 — 2026-05-31
- 0.1.29 — 2026-05-30
- 0.1.28 — 2026-05-30
- 0.1.27 — 2026-05-29
- … 24 more at https://npm.io/package/@insurup/contracts/versions

## README

# InsurUp Contracts

[![npm version](https://img.shields.io/npm/v/@insurup/contracts.svg)](https://www.npmjs.com/package/@insurup/contracts)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Zero Runtime](https://img.shields.io/badge/runtime-0%20bytes-brightgreen.svg)](package.json)

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

---

## Installation

```bash
npm install @insurup/contracts
```

```bash
pnpm add @insurup/contracts
```

```bash
bun add @insurup/contracts
```

---

## Usage

### Import Types

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

### Use with Your Own API Client

```typescript
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

```typescript
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.

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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

```typescript
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:

```typescript
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`](https://www.npmjs.com/package/@insurup/sdk) — Full-featured SDK with HTTP client, GraphQL support, and error handling

---

## License

[MIT](LICENSE)

---
_Source: https://npm.io/package/@insurup/contracts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._