@twinfinity/twin 0.0.0-feature.31596

package/README.md

@@ -0,0 +1,277 @@
+# @twinfinity/twin
+
+TypeScript client for the Twinfinity Twin Service API. Provides typed access to twins, assets, and twin files with optimistic concurrency control and structured error handling.
+
+## Installation
+
+```bash
+bun add @twinfinity/twin
+```
+
+### Peer Dependencies
+
+- `@twinfinity/authentication` - provides `TwinfinityHttpClient` for authenticated HTTP requests
+- `@twinfinity/t8-client-model` - provides T8 client model types used by `loadTwin` / `loadGeometryInfo`
+
+## Usage
+
+### Creating a Client
+
+```typescript
+import { TwinClient } from '@twinfinity/twin';
+
+const client = new TwinClient(baseUrl, httpClient);
+```
+
+The `baseUrl` is the API root (e.g. `https://api.twinfinity.com`). The client appends `/_ps/twins` internally.
+
+### Twin Operations
+
+```typescript
+// List twins (paginated)
+const page = await client.listTwins();
+
+// List all twins (auto-paginates)
+const allTwins = await client.listAllTwins();
+
+// Get a specific twin
+const twin = await client.getTwin('twin-id');
+
+// Get a specific version
+const twinV2 = await client.getTwin({ id: 'twin-id', version: 2 });
+
+// Create or update
+const updated = await client.createOrUpdateTwin('twin-id', {
+  relatedContainerIds: ['container-1'],
+  rootEntity: '0Site00000000000000000',
+  entities: {
+    sites: {
+      '0Site00000000000000000': { id: '0Site00000000000000000', name: 'My site' }
+    }
+  },
+  etag: twin.etag // required for updates
+});
+
+// Soft-delete and restore
+const deleted = await client.deleteTwin('twin-id', twin.etag);
+const restored = await client.restoreTwin('twin-id', deleted.etag);
+```
+
+#### Nesting twins
+
+A twin can nest other twins as children. Declare each child in `entities.twinReferences`
+and place it under a site via that site's `aggregatedTwinReferences`:
+
+```typescript
+await client.createOrUpdateTwin('parent-id', {
+  relatedContainerIds: ['container-1'],
+  rootEntity: '0Site00000000000000000',
+  entities: {
+    sites: {
+      '0Site00000000000000000': {
+        id: '0Site00000000000000000',
+        name: 'Campus site',
+        aggregatedTwinReferences: ['ref-a']
+      }
+    },
+    twinReferences: {
+      'ref-a': { twin: 'child-id' } // id of the nested twin
+    }
+  }
+  // Omit `etag` when creating; supply the current twin's etag only when updating.
+});
+
+// The parent/child edge is computed and read back on the twin:
+const parent = await client.getTwin('parent-id');
+parent.aggregatedTwins; // ['child-id'] — twins this twin parents
+const child = await client.getTwin('child-id');
+child.parentTwin; // 'parent-id' — the twin that references this one
+```
+
+`aggregatedTwins` and `parentTwin` are computed by the service, not authored — sending
+them in a write has no effect. A twin may have at most one parent, may not reference
+itself, and references may not form a cycle. Adding a reference requires `View` on the
+referenced twin (in addition to `Edit` on the twin being written); a referenced twin you
+cannot read is reported as not found. See
+[Twin Management → Nested Twins](../../docs/specs/backend/services/twin/twin-management.md#nested-twins-twin-references)
+for the full rules.
+
+### Loading Twin Models
+
+The client can download and deserialize processed twin content (T8CM/T8GI formats):
+
+```typescript
+// Load client model with default types
+const { id, version, model } = await client.loadTwin('twin-id');
+
+// Load with custom factory functions for domain-specific types
+const custom = await client.loadTwinWithFactories(
+  'twin-id',
+  myProjectFactory,
+  myProductFactory,
+  myEntityTypeFactory,
+  myUnitFactory,
+  myConnectProject,
+  myConnectProduct
+);
+
+// Load geometry info
+const geometry = await client.loadGeometryInfo('twin-id');
+
+// Load client model with geometry combined
+const withGeometry = await client.loadTwinWithGeometry('twin-id');
+```
+
+When no version is specified, the client searches versions (newest first) for one that has the requested content format.
+
+### Asset Operations
+
+```typescript
+// List assets in a twin
+const assets = await client.listAssets('twin-id');
+
+// Include soft-deleted assets
+const allAssets = await client.listAssets('twin-id', 0, 100, { includeDeleted: true });
+
+// Create assets
+const created = await client.createAssets('twin-id', [{ name: 'Pump A', category: 'HVAC', type: 'Pump' }]);
+
+// Update with optimistic concurrency
+const updated = await client.updateAsset('twin-id', 'asset-id', {
+  etag: asset.etag,
+  name: 'Pump A (Updated)'
+});
+
+// Batch operations (atomic - all succeed or all roll back)
+const result = await client.batchAssets('twin-id', [
+  { operation: 'upsert', id: 'asset-1', item: { name: 'New Asset' } },
+  { operation: 'delete', id: 'asset-2', item: { etag: 'etag-2' } },
+  { operation: 'restore', id: 'asset-3', item: { etag: 'etag-3' } }
+]);
+
+// Batch get multiple assets by ID
+const fetched = await client.batchGetAssets('twin-id', ['id-1', 'id-2']);
+```
+
+### Twin File Operations
+
+```typescript
+// List files (with filtering)
+const files = await client.listTwinFiles('twin-id', { checkedIn: true });
+
+// Create or update a file
+const file = await client.createOrUpdateTwinFile('twin-id', 'file-id', {
+  source: { changeId: 'doc-id', changeVersion: 1, sourceType: 'DocumentChange' },
+  name: 'model.ifc',
+  quality: 100
+});
+
+// Download file content
+const blob = await client.getTwinFileContent('twin-id', 'file-id');
+```
+
+## Error Handling
+
+All methods throw typed errors for specific HTTP failure codes. Unexpected status codes throw a generic `Error`.
+
+### Error Classes
+
+| Error                     | HTTP Status | Context Attached               |
+| ------------------------- | ----------- | ------------------------------ |
+| `TwinValidationError`     | 400         | `errorBody?: TwinErrorBody`    |
+| `TwinNotFoundError`       | 404         | `errorBody?: TwinErrorBody`    |
+| `TwinConflictError`       | 409         | `currentTwin: TwinGet`         |
+| `AssetValidationError`    | 400         | `errorBody?: TwinErrorBody`    |
+| `AssetForbiddenError`     | 403         | -                              |
+| `AssetNotFoundError`      | 404         | -                              |
+| `AssetConflictError`      | 409         | `currentAsset: AssetGet`       |
+| `AssetBatchError`         | 404, 409    | `response: AssetBatchResponse` |
+| `TwinFileValidationError` | 400         | `errorBody?: TwinErrorBody`    |
+| `TwinFileNotFoundError`   | 404         | -                              |
+| `TwinFileConflictError`   | 409         | `currentTwinFile: TwinFileGet` |
+| `ProcessorNotFoundError`  | 404         | -                              |
+
+Twin-scoped permissions (`/twins/{twinId}/permissions`, `/twins/{twinId}/groups`):
+
+| Error                                   | HTTP Status | Context Attached                                          |
+| --------------------------------------- | ----------- | --------------------------------------------------------- |
+| `TwinPermissionsForbiddenError`         | 403         | `errorBody?: TwinErrorBody`                               |
+| `TwinPrincipalNotFoundError`            | 404         | `errorBody?: TwinErrorBody`                               |
+| `TwinPermissionsConflictError`          | 409         | `conflictCause`, `currentState?`, `errorBody`             |
+| `TwinTemporarilyUnavailableError`       | 503         | `errorBody?: TwinErrorBody`, `retryAfterSeconds?: number` |
+
+`TwinPermissionsConflictError` names the conflict on `conflictCause` rather than on `cause`, leaving
+the standard `Error.cause` free: `EtagMismatch` is retried by re-reading, `EtagRequired` by reading
+at all, and `ScopesNotProvisioned` is not retryable. `currentState` carries the entry as the server
+holds it, including the etag to retry with.
+
+Asset-domain permissions (`/twins/permissions`, `/twins/groups`) reuse the errors above, except that
+a 409 arrives as `AssetPermissionsConflictError` — the same shape, but its `currentState` is an
+`AssetPrincipalPermissionsGet` rather than a twin's entry, and `ScopesNotProvisioned` never occurs
+because the domain's scope is seeded once per customer rather than provisioned per resource.
+
+### Conflict Handling
+
+Conflict errors (409) carry the current server-side state, enabling retry logic:
+
+```typescript
+import { TwinConflictError } from '@twinfinity/twin';
+
+try {
+  await client.createOrUpdateTwin('twin-id', twinData);
+} catch (e) {
+  if (e instanceof TwinConflictError) {
+    // e.currentTwin contains the server's current version
+    // Use it to merge changes and retry
+    const merged = mergeChanges(twinData, e.currentTwin);
+    await client.createOrUpdateTwin('twin-id', {
+      ...merged,
+      etag: e.currentTwin.etag
+    });
+  }
+}
+```
+
+### Validation Error Body
+
+`TwinValidationError`, `TwinFileValidationError`, and `AssetValidationError` may include a structured error body:
+
+```typescript
+interface TwinErrorBody {
+  detail: string;
+  cause: string;
+  item?: {
+    kind: string;
+    id: string;
+    version?: number;
+    field?: string;
+  };
+}
+```
+
+### Batch Error Handling
+
+`AssetBatchError` carries the full batch response with per-item results, including which operations were reverted:
+
+```typescript
+import { AssetBatchError } from '@twinfinity/twin';
+
+try {
+  await client.batchAssets('twin-id', operations);
+} catch (e) {
+  if (e instanceof AssetBatchError) {
+    for (const result of e.response.results) {
+      if (result.status === 'conflicted') {
+        console.log(`Item ${result.index} conflicted: ${result.error?.detail}`);
+      }
+    }
+  }
+}
+```
+
+## Exports
+
+The package has two export paths:
+
+- `@twinfinity/twin` - Public API: `TwinClient`, `ITwinClient`, all types, all error classes
+- `@twinfinity/twin/internal/*` - Internal modules (no stability guarantees)

package/dist/BuildInfo.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Represents either production or development build type
+ */
+export type BuildType = 'Dev' | 'Prod';
+/**
+ * Contains property metadata for the Twinfinity build
+ */
+export interface BuildInfo {
+    /** Major version number */
+    readonly major: number;
+    /** Minor version number */
+    readonly minor: number;
+    /** Patch version number */
+    readonly patch: number;
+    /** Unique build id */
+    readonly id: number;
+    /** The commit checksum */
+    readonly commit: string;
+    /** String that uniquely identifies the current version */
+    readonly version: string;
+    /** The build type */
+    readonly buildType: BuildType;
+}
+export declare const BUILD_INFO: Readonly<BuildInfo>;
+//# sourceMappingURL=BuildInfo.d.ts.map

package/dist/BuildInfo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuildInfo.d.ts","sourceRoot":"","sources":["../src/BuildInfo.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;AAEvC;;GAEG;AACH,MAAM,WAAW,SAAS;IACtB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qBAAqB;IACrB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CACjC;AAiBD,eAAO,MAAM,UAAU,qBAAqB,CAAC"}

package/dist/BuildInfo.js

@@ -0,0 +1,15 @@
+const gBi = {
+    major: 0,
+    minor: 0,
+    patch: 0,
+    id: 31596,
+    commit: 'b8846e12b',
+    version: '',
+    buildType: 'Prod'
+};
+gBi.version = `${gBi.major}.${gBi.minor}.${gBi.patch}.${gBi.id}-[${gBi.commit}]`;
+if (gBi.commit === 'unknownCommit') {
+    gBi.buildType = 'Dev';
+}
+export const BUILD_INFO = Object.freeze(gBi);
+//# sourceMappingURL=BuildInfo.js.map

package/dist/BuildInfo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuildInfo.js","sourceRoot":"","sources":["../src/BuildInfo.ts"],"names":[],"mappings":"AAyBA,MAAM,GAAG,GAAc;IACnB,KAAK,EAAE,MAAM;IACb,KAAK,EAAE,MAAM;IACb,KAAK,EAAE,MAAM;IACb,EAAE,EAAE,MAAM;IACV,MAAM,EAAE,eAAe;IACvB,OAAO,EAAE,EAAE;IACX,SAAS,EAAE,MAAM;CACpB,CAAC;AAED,GAAG,CAAC,OAAkB,GAAG,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC;AAC7F,IAAI,GAAG,CAAC,MAAM,KAAK,eAAe,EAAE,CAAC;IAChC,GAAG,CAAC,SAAuB,GAAG,KAAK,CAAC;AACzC,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC"}