iTwins client for the iTwin platform
npm install @itwin/itwins-client
A comprehensive TypeScript library for Bentley Systems' iTwins API, providing type-safe access to infrastructure digital twins, repositories, exports, and image management.
- Quick Start
- Installation
- Basic Usage
- Documentation
- API Reference
- Contributing
- License
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);`
`bashUsing npm
npm install @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 testRun tests with coverage
pnpm test:coverageRun linting
pnpm lint
``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
This project uses Changesets for version management. For more information view Contributing Guide.
Copyright © Bentley Systems, Incorporated. All rights reserved.
This project is licensed under the MIT License - see the LICENSE.md file for details.
---