iTwins Client Library


A comprehensive TypeScript library for Bentley Systems' iTwins API, providing type-safe access to infrastructure digital twins, repositories, exports, and image management.

Table of Contents

- Quick Start
- Installation
- Basic Usage
- Documentation
- API Reference
- Contributing
- License

Quick Start

Get up and running with iTwins Client in just a few steps:

``bash
npm install @itwin/itwins-client
`

`typescript
import { ITwinsClient } from "@itwin/itwins-client";

const client = new ITwinsClient();
const accessToken = "your-access-token-string";
const response = await client.getITwins(accessToken, { subClass: "Project" });
console.log(Found ${response.data!.iTwins.length} iTwins);
`

Installation

`bash


Using npm

npm install @itwin/itwins-client

Using yarn

yarn add @itwin/itwins-client

Using pnpm

pnpm add @itwin/itwins-client
`

Basic Usage

$3

All API methods require an access token string. See the iTwin Platform documentation for authentication setup.

$3

Configure different deployment environments using globalThis.IMJS_URL_PREFIX:

`typescript
// Development environment
globalThis.IMJS_URL_PREFIX = "dev-";

// QA environment
globalThis.IMJS_URL_PREFIX = "qa-";

// Production (default)
globalThis.IMJS_URL_PREFIX = undefined;
`

Configure max redirect limit for federated architecture (default: 5):

`typescript
globalThis.IMJS_MAX_REDIRECTS = 10; // Increase if needed for multi-hop redirects
`

Documentation

$3

| Document | Purpose |
|----------|---------|
| Getting Started Guide | Complete setup and first steps |
| API Examples | Comprehensive usage examples |
| Migration Guide v1→v2 | Upgrading from v1.x to v2.x |
| Contributing Guide | Development and contribution workflow |
| AI Coding Instructions | Guidelines for AI assistants |

API Reference

$3

- ITwinsClient - Main client for all iTwins operations
- BaseITwinsApiClient - Base client with common HTTP functionality

$3

- ✅ Complete CRUD operations for iTwins and repositories
- ✅ HAL specification compliance for navigation links
- ✅ Image upload and processing capabilities
- ✅ Export functionality for bulk data operations

$3

`typescript
import { ITwinsClient } from "@itwin/itwins-client";
import type {
BentleyAPIResponse,
ITwinMinimal,
MultiITwinMinimalResponse
} from "@itwin/itwins-client";

const client = new ITwinsClient();
const accessToken = "your-access-token-string";

// Get iTwins
const response = await client.getITwins(accessToken, {
subClass: "Project",
top: 10,
resultMode: "minimal"
});

// Create iTwin
const newITwin = await client.createITwin(accessToken, {
displayName: "My New iTwin",
subClass: "Asset",
class: "Thing"
});

// Work with repositories
const repos = await client.getRepositories(accessToken, iTwinId);
`

About this Repository

The @itwin/itwins-client package provides a modern, type-safe interface to Bentley Systems' iTwins platform APIs. It manages infrastructure digital twins (iTwins), repositories, exports, images, and related resources.

For more information about the iTwins platform and APIs, visit:

- iTwin Developer Portal
- iTwins API Documentation
- iTwin.js Platform

Development

$3

- Node.js 18+ and pnpm
- TypeScript 4.5+
- Valid iTwin Platform credentials

$3

`bash
git clone https://github.com/iTwin/itwins-client.git
cd itwins-client
pnpm install
pnpm build
`

$3

.env file setup is required for tests view Getting Started for more information.

`bash


Run all tests

pnpm test

Run tests with coverage

pnpm test:coverage

Run linting

pnpm lint
``

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

- How to submit issues and feature requests
- Development workflow and coding standards
- Pull request process and review guidelines
- Testing requirements and conventions
- How to use changesets for versioning

$3

This project uses Changesets for version management. For more information view Contributing Guide.

License

Copyright © Bentley Systems, Incorporated. All rights reserved.

This project is licensed under the MIT License - see the LICENSE.md file for details.

---