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:

npm install @itwin/itwins-client

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

# Using npm
npm install @itwin/itwins-client

# Using yarn
yarn add @itwin/itwins-client

# Using pnpm
pnpm add @itwin/itwins-client

Basic Usage

Authentication

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

Environment Configuration

Configure different deployment environments using globalThis.IMJS_URL_PREFIX:

// 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):

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

Documentation

Core Documentation

| 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

Core Classes

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

Key Features

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

Quick Reference

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

Prerequisites

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

Building from Source

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

Running Tests

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

# 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

Versioning

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.