industrial-model 0.6.0 → 0.8.0

package/README.md

@@ -12,6 +12,9 @@ TypeScript SDK for querying [Cognite Flexible Data Models (FDM)](https://docs.co
 - **Industrial filters** - combine scalar filters, list filters, full-text search, and nested relation filters.
 - **Pagination support** - use cursors manually or fetch all root pages with `limit: -1`.
 - **Aggregation support** - count, group, list distinct values, and aggregate numeric properties.
+- **Mutation support** - upsert model-shaped node patches and delete nodes by identity.
+- **Datapoints support** - read, write, and delete time series datapoints through model-friendly option objects.
+- **Files support** - upload files and retrieve pre-signed download URLs, keyed to model node identities.
 - **Runtime validation option** - parse query results with Zod schemas derived from Cognite view metadata.
 - **CJS and ESM builds** - works in Node.js and common bundler setups.
 
@@ -518,6 +521,230 @@ const { items } = await model.query<CogniteAsset>()({
 
 Expanded relations use internal pagination as well. When a nested relation query reaches the internal page size, the client follows dependency cursors for up to 3 additional rounds.
 
+## Upsert
+
+Use `upsert()` to create or patch nodes with the same model shape you use for queries. Each item must include `space` and `externalId`; all other fields are optional and only the fields you pass are updated.
+
+```ts
+await model.upsert<CogniteAsset>()({
+  viewExternalId: "CogniteAsset",
+  items: [
+    {
+      space: "asset-space",
+      externalId: "pump-1",
+      name: "Pump 1",
+      parent: { space: "asset-space", externalId: "root" },
+    },
+  ],
+});
+```
+
+Direct relations are written as `NodeId` values. Reverse direct relations are written by patching the target nodes through the relation field defined in Cognite. For example, writing `children` on an asset updates each child asset's `parent` reference.
+
+```ts
+await model.upsert<CogniteAsset>()({
+  viewExternalId: "CogniteAsset",
+  items: [
+    {
+      space: "asset-space",
+      externalId: "parent-asset",
+      children: [{ space: "asset-space", externalId: "child-1" }],
+    },
+  ],
+});
+```
+
+Edge-backed relations need an edge ID. Provide `onEdgeCreation` for every edge connection property you write. The callback receives normalized `startNode`, `endNode`, and `edgeType` values after the SDK has applied the relation direction from the view metadata.
+
+```ts
+await model.upsert<Cognite3DObject>()({
+  viewExternalId: "Cognite3DObject",
+  items: [
+    {
+      space: "object-space",
+      externalId: "object-1",
+      images360: [{ space: "image-space", externalId: "image-1" }],
+    },
+  ],
+  onEdgeCreation: {
+    images360: ({ startNode, endNode, edgeType }) => ({
+      space: startNode.space,
+      externalId: `${startNode.externalId}:${edgeType.externalId}:${endNode.externalId}`,
+    }),
+  },
+});
+```
+
+`edgeMode` controls how edge connection properties are applied:
+
+| Mode | Behavior |
+| --- | --- |
+| `"append"` | Default. Creates the generated edges and leaves existing edges untouched. |
+| `"replace"` | Queries existing edges for the provided edge connection fields, deletes edges that were not generated by the current upsert, then applies the new edges. |
+
+To clear an edge connection for a node, include the property with an empty array and use `edgeMode: "replace"`:
+
+```ts
+await model.upsert<Cognite3DObject>()({
+  viewExternalId: "Cognite3DObject",
+  edgeMode: "replace",
+  items: [
+    {
+      space: "object-space",
+      externalId: "object-1",
+      images360: [],
+    },
+  ],
+});
+```
+
+This deletes existing `images360` edges for `object-1`. Other edge connection fields on the same node are not touched, and omitting `images360` entirely leaves its existing edges unchanged.
+
+Use `replace: true` when you want Cognite apply replace semantics for container-backed node properties.
+
+Important constraints:
+
+- Relation fields accept only `NodeId` or `NodeId[]` references. Nested node mutation is intentionally not supported.
+- Unknown fields are rejected before Cognite is called.
+- Edge connection fields require `onEdgeCreation.<property>` only when the submitted array contains edges to create.
+- Cognite apply requests are limited to 1000 writes/deletes per call. You can still pass more than 1000 upsert items or edge references; the SDK follows paginated edge-replacement queries and splits large apply payloads into multiple Cognite calls.
+- `edgeMode: "replace"` only replaces edge connection fields included in the submitted items.
+
+## Delete
+
+Use `delete()` when you only need to delete nodes by identity. The method accepts an array of values with `space` and `externalId`; any extra fields are ignored.
+
+```ts
+await model.delete([
+  { space: "asset-space", externalId: "pump-1" },
+  { space: "asset-space", externalId: "pump-2", name: "Pump 2" },
+]);
+```
+
+The delete operation is view-independent, so it does not require `viewExternalId` and is also available directly on `CogniteCoreClient`.
+
+```ts
+await core.delete([{ space: "asset-space", externalId: "pump-1" }]);
+```
+
+Deletes are sent through Cognite apply. When more than 1000 nodes are provided, the SDK splits them into multiple Cognite calls.
+
+## Datapoints
+
+Use `model.datapoints` for Cognite time series data. The public API talks in terms of `timeSeries`, ranges, and datapoint batches; the Cognite SDK `items` and `instanceId` payload shape stays internal.
+
+```ts
+const { items } = await model.datapoints.retrieve({
+  timeSeries: [{ space: "ts-space", externalId: "temperature", targetUnit: "degC" }],
+  start: new Date("2024-01-01T00:00:00.000Z"),
+  end: new Date("2024-01-02T00:00:00.000Z"),
+  limit: 100,
+});
+
+items[0]?.timeSeries.externalId;
+items[0]?.datapoints;
+items[0]?.cursor; // next cursor, or null
+```
+
+Pass `limit: -1` to follow datapoint cursors and return all pages for each requested time series.
+
+```ts
+const history = await model.datapoints.retrieve({
+  timeSeries: [{ space: "ts-space", externalId: "temperature" }],
+  start: new Date("2024-01-01T00:00:00.000Z"),
+  limit: -1,
+});
+```
+
+Read the latest datapoint before a given timestamp:
+
+```ts
+const latest = await model.datapoints.latest({
+  timeSeries: [{ space: "ts-space", externalId: "temperature" }],
+  ignoreUnknownIds: true,
+});
+```
+
+Write datapoints by passing an array of insert items directly:
+
+```ts
+await model.datapoints.insert([
+  {
+    timeSeries: { space: "ts-space", externalId: "temperature" },
+    datapoints: [{ timestamp: new Date(), value: 42 }],
+  },
+]);
+```
+
+Delete datapoints by passing an array of ranges directly:
+
+```ts
+await model.datapoints.delete([
+  {
+    timeSeries: { space: "ts-space", externalId: "temperature" },
+    start: new Date("2024-01-01T00:00:00.000Z"),
+    end: new Date("2024-01-02T00:00:00.000Z"),
+  },
+]);
+```
+
+## Files
+
+Use `model.files` to upload files to Cognite and retrieve pre-signed download URLs. Both operations use `space` and `externalId` node identities as keys; the Cognite `instanceId` payload shape stays internal.
+
+Upload a file and optionally pass the binary content as a second argument to complete the upload in one call. When content is provided, Cognite uploads it inline and `uploaded` is `true` on the result.
+
+```ts
+const result = await model.files.upload(
+  {
+    space: "file-space",
+    externalId: "report-2024",
+    name: "annual-report.pdf",
+    mimeType: "application/pdf",
+    directory: "/reports",
+    source: "erp",
+    metadata: { department: "finance", year: "2024" },
+  },
+  pdfContent, // Buffer, Blob, ArrayBuffer, ReadableStream, …
+);
+
+result.space;          // "file-space"
+result.externalId;     // "report-2024"
+result.name;           // "annual-report.pdf"
+result.uploaded;       // true — content was provided
+result.createdTime;    // Date
+result.lastUpdatedTime; // Date
+```
+
+Omit the content argument to receive a pre-signed `uploadUrl` instead. Use it to push the file binary from the client side without routing it through your server:
+
+```ts
+const result = await model.files.upload({
+  space: "file-space",
+  externalId: "report-2024",
+  name: "annual-report.pdf",
+  mimeType: "application/pdf",
+});
+
+result.uploaded;   // false — content not yet uploaded
+result.uploadUrl;  // "https://storage.example.com/…" — use to PUT the file
+```
+
+Retrieve pre-signed download URLs for one or more files by node identity:
+
+```ts
+const urls = await model.files.getDownloadUrls([
+  { space: "file-space", externalId: "report-2024" },
+  { space: "file-space", externalId: "manual-v3" },
+]);
+
+urls[0]?.downloadUrl; // pre-signed URL ready to use
+urls[0]?.space;
+urls[0]?.externalId;
+```
+
+The returned array preserves the input order. Passing an empty array returns `[]` without calling Cognite.
+
 ## Aggregation
 
 Use `aggregate()` when you need grouped counts, distinct values, or numeric summaries without loading every instance.
@@ -654,7 +881,7 @@ For applications working with the Cognite Core Data Model (`cdf_cdm/CogniteCore/
 
 ```ts
 import { CogniteClient } from "@cognite/sdk";
-import { CogniteCoreClient } from "industrial-model";
+import { CogniteCoreClient } from "industrial-model/cognite-core";
 
 const client = new CogniteClient({ ... });
 const core = new CogniteCoreClient(client);
@@ -696,6 +923,36 @@ items[0]?.group?.manufacturer;
 items[0]?.aggregate?.value;
 ```
 
+Upserts use the same pattern and infer the item shape from the view name:
+
+```ts
+await core.upsert("CogniteAsset")({
+  items: [
+    {
+      space: "asset-space",
+      externalId: "pump-1",
+      name: "Pump 1",
+      parent: { space: "asset-space", externalId: "root" },
+    },
+  ],
+});
+```
+
+Deletes are view-independent:
+
+```ts
+await core.delete([{ space: "asset-space", externalId: "pump-1" }]);
+```
+
+`core.datapoints` exposes the same executor API as `model.datapoints` on `IndustrialModelClient`:
+
+```ts
+const { items } = await core.datapoints.retrieve({
+  timeSeries: [{ space: "ts-space", externalId: "temperature" }],
+  limit: 100,
+});
+```
+
 All Cognite Core view types are exported from `industrial-model` and can be imported directly for use with `IndustrialModelClient` if needed:
 
 ```ts
@@ -849,6 +1106,18 @@ Same as `model.query<TModel>()(options)` on `IndustrialModelClient`, except the
 
 Same as `model.aggregate<TModel>()(options)` on `IndustrialModelClient`, with the view name as the first positional argument.
 
+### `core.upsert(viewExternalId)(options)`
+
+Same as `model.upsert<TModel>()(options)` on `IndustrialModelClient`, with the view name as the first positional argument. The model type is inferred from the Cognite Core view name.
+
+### `core.delete(items)`
+
+Same as `model.delete(items)` on `IndustrialModelClient`. Deletes nodes by `space` and `externalId`; no view name is required.
+
+### `core.datapoints`
+
+Same as `model.datapoints` on `IndustrialModelClient`. All four methods — `retrieve`, `latest`, `insert`, and `delete` — are available without a view name.
+
 ### `new IndustrialModelClient(client, dataModelId, options?)`
 
 | Parameter | Type | Description |
@@ -883,6 +1152,58 @@ type QueryResult<TItem> = {
 
 Each item includes instance metadata such as `space`, `externalId`, `version`, `createdTime`, `deletedTime`, and `lastUpdatedTime`, plus the selected fields.
 
+### `model.upsert<TModel>()(options)`
+
+`upsert()` uses the same model type as `query()` and accepts partial node patches. It returns the Cognite apply result items.
+
+| Option | Description |
+| --- | --- |
+| `viewExternalId` | View to create or patch. |
+| `items` | Node patches. Each item must include `space` and `externalId`. Inputs larger than Cognite's 1000-item apply limit are split into multiple calls. |
+| `replace` | Optional. Enables Cognite apply replace semantics for submitted container-backed properties. |
+| `edgeMode` | Optional. `"append"` by default; use `"replace"` to remove existing edge connection edges for submitted edge fields before applying the new references. |
+| `onEdgeCreation` | Optional map of edge connection property names to callbacks that generate edge IDs. Required for every edge connection property that creates one or more edges. |
+
+Returns:
+
+```ts
+type UpsertResult = {
+  items: Array<{
+    instanceType: "node" | "edge";
+    space: string;
+    externalId: string;
+    version?: number;
+    wasModified?: boolean;
+    createdTime?: number;
+    lastUpdatedTime?: number;
+  }>;
+};
+```
+
+### `model.delete<TItem extends NodeId>(items)`
+
+Deletes nodes by identity. Each item must include `space` and `externalId`; extra fields are ignored. Inputs larger than Cognite's 1000-item apply limit are split into multiple calls.
+
+```ts
+await model.delete([{ space: "asset-space", externalId: "pump-1" }]);
+```
+
+Returns:
+
+```ts
+type DeleteResult = {
+  items: Array<{
+    instanceType: "node";
+    space: string;
+    externalId: string;
+    version?: number;
+    wasModified?: boolean;
+    createdTime?: number;
+    lastUpdatedTime?: number;
+  }>;
+};
+```
+
 ### `model.aggregate<TModel>()(options)`
 
 | Option | Description |
@@ -903,6 +1224,50 @@ Provide at least one of `groupBy` or `aggregate`. Omit `aggregate` to fetch dist
 | `max` | `{ max: "volume" }` | Maximum numeric value. |
 | `sum` | `{ sum: "volume" }` | Sum of a numeric property. |
 
+### `model.files.upload(fileInfo, content?)`
+
+Uploads a file to Cognite. `fileInfo` fields:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `space` | `string` | Node space. |
+| `externalId` | `string` | Node external ID. |
+| `name` | `string` | File name. |
+| `mimeType` | `string` | Optional MIME type. |
+| `directory` | `string` | Optional directory path within the project. |
+| `source` | `string` | Optional source system identifier. |
+| `metadata` | `Record<string, string>` | Optional key-value metadata. |
+
+`content` accepts any value accepted by the Cognite SDK file upload (`Buffer`, `Blob`, `ArrayBuffer`, `ReadableStream`, …). When provided, the file is uploaded inline and `uploaded` is `true`. When omitted, Cognite returns a pre-signed `uploadUrl` for a separate upload and `uploaded` is `false`.
+
+Returns `FileUploadResult`:
+
+```ts
+type FileUploadResult = NodeId & {
+  name: string;
+  uploaded: boolean;
+  mimeType?: string;
+  directory?: string;
+  source?: string;
+  uploadedTime?: Date;
+  createdTime: Date;
+  lastUpdatedTime: Date;
+  uploadUrl?: string;
+};
+```
+
+### `model.files.getDownloadUrls(nodeIds)`
+
+Retrieves one pre-signed download URL per node, in the same order as the input. Passing an empty array returns `[]` without calling Cognite.
+
+Returns `FileDownloadUrl[]`:
+
+```ts
+type FileDownloadUrl = NodeId & {
+  downloadUrl: string;
+};
+```
+
 ### Filter Operators
 
 | Field type | Operators |
@@ -938,6 +1303,12 @@ Logical combinators `AND`, `OR`, and `NOT` are supported at any nesting level, i
 | `QuerySelect` | Type helper for reusable query selections. |
 | `QueryResult`, `QueryResultItem` | Query output types. |
 | `AggregateResult`, `AggregateResultItem` | Aggregate output types. |
+| `UpsertOptions`, `UpsertNode`, `UpsertProperties` | Upsert input helper types. |
+| `UpsertResult`, `UpsertResultItem` | Upsert output types. |
+| `DeleteExecutor`, `DeleteResult`, `DeleteResultItem` | Delete helper and output types. |
+| `EdgeCreationContext`, `EdgeCreationCallback`, `EdgeCreationCallbacks`, `EdgeMode` | Edge upsert helper types. |
+| `DatapointsExecutor`, `DatapointsRetrieveOptions`, `DatapointsLatestOptions`, `DatapointsLatestSeries`, `DatapointsInsertItem`, `DatapointsDeleteRange`, `DatapointsResult`, `DatapointSeriesResult`, `DatapointAggregate` | Datapoints types. |
+| `FilesExecutor`, `FileUploadInfo`, `FileUploadResult`, `FileDownloadUrl` | Files types. |
 | `IndustrialModelClientOptions` | Client configuration options. |
 
 **Cognite Core**