Tree node listing helpers + server-authoritative S3 tagging

CHANGELOG.md

@@ -18,9 +18,16 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 - Collections: Added `allowedDatasetTypes` field to the [Collection](./src/collections/domain/models/Collection.ts) model. This field is optional and only populated the feature is enabled on the installation and configured on the collection.
 - Collections: Added theme information when retrieving a collection using `getCollection`.
 - Collections: Added `setDefaultContributorRole` use case.
+- Datasets: `listDatasetTreeNode` use case and repository method backing `GET /datasets/{id}/versions/{versionId}/tree` for paginated, lazy listing of folders/files inside a dataset version. Returns `FileTreePage` with folder-first ordering, opaque keyset cursors, and per-file `downloadUrl`. The per-file `access` marker is one of `retentionExpired`, `restricted`, `embargoed`, or `public` (resolved in that order), and folder `counts` carry the matching mutually exclusive `restricted`/`embargoed`/`retentionExpired` buckets.
+- Datasets: `iterateDatasetTreeNode` async generator that walks the cursor chain so callers can consume one folder's children without driving pagination by hand.
+- Core: re-export `DataverseApiAuthMechanism` from the public surface so consumers of the standalone reusable bundles (e.g. `dv-tree-view`, `dv-uploader`) can import it without reaching into `core/...`.
+- Files: export `DirectUploadClient` and `DirectUploadClientConfig` from the public files surface so consumers can construct their own client with custom timeouts / retry counts without reaching into the SDK's `infra/` path.
 
 ### Changed
 
+- **BREAKING**: `DirectUploadClient` constructor signature changed from `(filesRepository, maxMultipartRetries = 5)` to `(filesRepository, config: DirectUploadClientConfig = {})`. `config` now holds `maxMultipartRetries` (default 5) and the new `fileUploadTimeoutMs` (default 60000). Existing TypeScript consumers passing the second argument as a number will need to migrate to `{ maxMultipartRetries: N }`; a bare number passed by plain-JS callers is still honored at runtime as `maxMultipartRetries`.
+- Files: `DirectUploadClient` now reads the `tagging` field from the upload-destination response so operators on storage that doesn't accept S3 tags can opt out per-driver via `dataverse.files.<id>.disable-tagging=true`. The default behaviour is unchanged: when the server omits the field the client still sends `x-amz-tagging: dv-state=temp` (the same tag that earlier SDK versions hard-coded), so the new SDK is backwards-compatible with Dataverse releases that predate the response field. A server that explicitly returns an empty `tagging` value tells the client to skip the header entirely. Multipart uploads never send `x-amz-tagging` on part uploads — the part URLs are not signed for the header; the matching Dataverse server applies the temporary tag itself when it initiates the multipart upload.
+
 ### Fixed
 
 ### Removed
@@ -52,7 +59,7 @@ This changelog follows the principles of [Keep a Changelog](https://keepachangel
 
 ### Changed
 
-- Add pagination query parameters to Dataset Version Summeries and File Version Summaries use cases.
+- Add pagination query parameters to Dataset Version Summaries and File Version Summaries use cases.
 - Templates: Rename `CreateDatasetTemplateDTO` to `CreateTemplateDTO`.
 - Templates: Rename `createDatasetTemplate` repository method to `createTemplate`.
 - Templates: Rename `getDatasetTemplates` repository method to `getTemplatesByCollectionId`.

docs/useCases.md

@@ -63,6 +63,8 @@ The different use cases currently available in the package are classified below,
     - [Get Dataset Available Dataset Types](#get-dataset-available-dataset-types)
     - [Get Dataset Available Dataset Type](#get-dataset-available-dataset-type)
     - [Get Dataset Upload Limits](#get-dataset-upload-limits)
+    - [List a Folder of a Dataset Version (Tree View)](#list-a-folder-of-a-dataset-version-tree-view)
+    - [Iterate a Folder of a Dataset Version (Tree View)](#iterate-a-folder-of-a-dataset-version-tree-view)
   - [Datasets write use cases](#datasets-write-use-cases)
     - [Create a Dataset](#create-a-dataset)
     - [Update a Dataset](#update-a-dataset)
@@ -1912,6 +1914,81 @@ _See [use case](../src/datasets/domain/useCases/GetDatasetUploadLimits.ts) imple
 
 If the backend does not define any quota limits for the dataset, the returned object can be empty (`{}`).
 
+#### List a Folder of a Dataset Version (Tree View)
+
+Returns a [FileTreePage](../src/datasets/domain/models/FileTreePage.ts) for the immediate children (folders and files) inside a folder of a dataset version, intended for lazy tree-view UIs that fetch each folder's children on demand.
+
+Folders come first, then files. Both are name-sorted (case-insensitive); files break ties on data file id for stability. The page carries an opaque `nextCursor` token; clients echo it back to fetch the next page and never construct one themselves.
+
+##### Example call:
+
+```typescript
+import { listDatasetTreeNode, FileTreePage } from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+listDatasetTreeNode
+  .execute({
+    datasetId,
+    datasetVersionId: '1.0',
+    path: 'data/raw',
+    limit: 100
+  })
+  .then((page: FileTreePage) => {
+    /* ... */
+  })
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/ListDatasetTreeNode.ts) implementation_.
+
+`datasetId` can be a numeric id or a persistent identifier string. `datasetVersionId` is optional and defaults to `DatasetNotNumberedVersion.LATEST`.
+
+Other optional parameters: `cursor` (opaque, from a previous response), `include` (`'all' | 'folders' | 'files'`, default `'all'`), `order` (`'NameAZ' | 'NameZA'`, default `'NameAZ'`), `includeDeaccessioned` (default `false`), and `originals` (when `true`, ingested tabular files are reported in their original-upload form: the per-file `downloadUrl` carries `?format=original`, and `checksum` and `size` reflect the saved original instead of the converted TSV).
+
+The `path` value is normalized by the server with the same rules applied to folder names at upload time (slash/backslash runs collapse, leading dots/dashes/spaces are stripped); paths emitted by the endpoint itself always round-trip, and a path that normalizes to nothing (for example `..`) is rejected with a `400` error.
+
+For published, non-deaccessioned versions the underlying API emits an `ETag` (derived from the request inputs plus the current date) and `Cache-Control: private, no-cache` headers. A released version's file list is frozen, but the response is still time-dependent — the per-file `access` marker flips when an embargo lapses or a retention period expires — so the contract is revalidate-always (`no-cache`) with a date-scoped validator: passing the ETag back in `If-None-Match` yields a body-less `304 Not Modified` while it still matches. The `private` directive keeps responses out of shared proxy caches because the route is auth-required. Drafts and deaccessioned versions emit no caching headers.
+
+#### Iterate a Folder of a Dataset Version (Tree View)
+
+Returns an async generator over [FileTreeNode](../src/datasets/domain/models/FileTreeNode.ts) values for one folder, walking the cursor chain so callers can consume the children without driving pagination by hand.
+
+##### Example call:
+
+```typescript
+import {
+  iterateDatasetTreeNode,
+  FileTreeNode,
+  isFileTreeFileNode
+} from '@iqss/dataverse-client-javascript'
+
+/* ... */
+
+const datasetId = 'doi:10.77777/FK2/AAAAAA'
+
+for await (const node of iterateDatasetTreeNode.execute({
+  datasetId,
+  datasetVersionId: '1.0',
+  path: 'data/raw'
+})) {
+  if (isFileTreeFileNode(node)) {
+    /* ... */
+  } else {
+    /* node is a folder ... */
+  }
+}
+
+/* ... */
+```
+
+_See [use case](../src/datasets/domain/useCases/IterateDatasetTreeNode.ts) implementation_.
+
+The generator stops after yielding everything in the requested folder; it does **not** descend into subfolders. Pass each subfolder's `path` back through `iterateDatasetTreeNode` if you want a recursive walk.
+
 ## Files
 
 ### Files read use cases

src/core/index.ts

@@ -1,6 +1,6 @@
 export { ReadError } from './domain/repositories/ReadError'
 export { WriteError } from './domain/repositories/WriteError'
-export { ApiConfig } from './infra/repositories/ApiConfig'
+export { ApiConfig, DataverseApiAuthMechanism } from './infra/repositories/ApiConfig'
 export { DvObjectOwnerNode, DvObjectType } from './domain/models/DvObjectOwnerNode'
 export { PublicationStatus } from './domain/models/PublicationStatus'
 export { StorageDriver } from './domain/models/StorageDriver'

src/datasets/domain/models/FileTreeNode.ts

@@ -0,0 +1,80 @@
+export enum FileTreeNodeType {
+  FOLDER = 'folder',
+  FILE = 'file'
+}
+
+export interface FileTreeFolderNode {
+  type: FileTreeNodeType.FOLDER
+  name: string
+  path: string
+  counts?: {
+    /** Total files anywhere in the folder's subtree (recursive). */
+    files: number
+    /** Immediate subfolders only. */
+    folders: number
+    /**
+     * Total size of all files in the subtree, in bytes. Uses the
+     * default-form file size — for ingested tabular files that's the
+     * converted TSV, not the original. Intended as a UX hint
+     * ("downloading this folder = N GB"); not authoritative under
+     * `originals=true`.
+     */
+    bytes: number
+    /**
+     * Files in the subtree marked restricted. Mirrors the per-file
+     * `access` resolution — the buckets are mutually exclusive: a
+     * retention-expired file counts in `retentionExpired` even if it is
+     * also restricted, and a restricted file counts here even if it
+     * also carries an embargo.
+     */
+    restricted: number
+    /**
+     * Non-restricted files in the subtree whose embargo has not yet
+     * lapsed. The "public" count is implied: `files - restricted -
+     * embargoed - retentionExpired`.
+     */
+    embargoed: number
+    /**
+     * Files in the subtree whose retention period has expired — they
+     * cannot be served at all, so this state wins over `restricted`
+     * and `embargoed` in the per-file `access` resolution.
+     */
+    retentionExpired: number
+  }
+}
+
+export interface FileTreeFileNode {
+  type: FileTreeNodeType.FILE
+  id: number
+  name: string
+  path: string
+  /**
+   * File size in bytes. For ingested tabular files this is the
+   * served-form (converted TSV) size by default; when the listing was
+   * requested with `originals=true` it is the saved original's size,
+   * matching the bytes `downloadUrl` then serves.
+   */
+  size: number
+  contentType?: string
+  /**
+   * Resolved in this order: `retentionExpired` (the file cannot be
+   * served at all), then `restricted` (even when an embargo is also
+   * active), then `embargoed`, then `public`. The embargo/retention
+   * date checks match Dataverse's download enforcement: a file whose
+   * embargo lifts today reports `public` and is downloadable.
+   */
+  access?: 'public' | 'restricted' | 'embargoed' | 'retentionExpired'
+  checksum?: {
+    type: string
+    value: string
+  }
+  downloadUrl: string
+}
+
+export type FileTreeNode = FileTreeFolderNode | FileTreeFileNode
+
+export const isFileTreeFolderNode = (node: FileTreeNode): node is FileTreeFolderNode =>
+  node.type === FileTreeNodeType.FOLDER
+
+export const isFileTreeFileNode = (node: FileTreeNode): node is FileTreeFileNode =>
+  node.type === FileTreeNodeType.FILE

src/datasets/domain/models/FileTreePage.ts

@@ -0,0 +1,28 @@
+import { FileTreeNode } from './FileTreeNode'
+
+export enum FileTreeInclude {
+  ALL = 'all',
+  FOLDERS = 'folders',
+  FILES = 'files'
+}
+
+export enum FileTreeOrder {
+  NAME_AZ = 'NameAZ',
+  NAME_ZA = 'NameZA'
+}
+
+export interface FileTreePage {
+  path: string
+  items: FileTreeNode[]
+  nextCursor: string | null
+  limit: number
+  order: FileTreeOrder
+  include: FileTreeInclude
+  /**
+   * Total folders + files at the requested path. Snapshotted on the
+   * first page of a pagination walk and carried unchanged through the
+   * cursor for the rest of the walk — on draft versions, files added
+   * mid-walk are not reflected until a new walk starts.
+   */
+  approximateCount?: number
+}

src/datasets/domain/repositories/IDatasetsRepository.ts

@@ -19,9 +19,22 @@ import { DatasetTypeDTO } from '../dtos/DatasetTypeDTO'
 import { StorageDriver } from '../../../core/domain/models/StorageDriver'
 import { DatasetUploadLimits } from '../models/DatasetUploadLimits'
 import { DatasetReview } from '../models/DatasetReview'
+import { FileTreePage, FileTreeInclude, FileTreeOrder } from '../models/FileTreePage'
 import { ExportedDatasetMetadata } from '../models/ExportedDatasetMetadata'
 import { DatasetNotNumberedVersion } from '../models/DatasetNotNumberedVersion'
 
+export interface ListDatasetTreeNodeParams {
+  datasetId: number | string
+  datasetVersionId?: string
+  path?: string
+  limit?: number
+  cursor?: string
+  include?: FileTreeInclude
+  order?: FileTreeOrder
+  includeDeaccessioned?: boolean
+  originals?: boolean
+}
+
 export interface IDatasetsRepository {
   getDataset(
     datasetId: number | string,
@@ -113,4 +126,5 @@ export interface IDatasetsRepository {
   getDatasetStorageDriver(datasetId: number | string): Promise<StorageDriver>
   getDatasetUploadLimits(datasetId: number | string): Promise<DatasetUploadLimits>
   getDatasetReviews(datasetId: number | string): Promise<DatasetReview[]>
+  listDatasetTreeNode(params: ListDatasetTreeNodeParams): Promise<FileTreePage>
 }

src/datasets/domain/useCases/IterateDatasetTreeNode.ts

@@ -0,0 +1,39 @@
+import { IDatasetsRepository, ListDatasetTreeNodeParams } from '../repositories/IDatasetsRepository'
+import { FileTreeNode } from '../models/FileTreeNode'
+
+/**
+ * Async generator that exhaustively iterates the immediate children of the
+ * given path inside a dataset version, transparently following the
+ * `nextCursor` chain.
+ *
+ * Use this when you need every direct child of a folder; it does NOT recurse
+ * into subfolders — that is the caller's responsibility (e.g. pre-download
+ * enumeration walks the tree by re-invoking this iterator with each folder
+ * path it discovers).
+ */
+export class IterateDatasetTreeNode {
+  constructor(private readonly datasetsRepository: IDatasetsRepository) {}
+
+  async *execute(params: ListDatasetTreeNodeParams): AsyncGenerator<FileTreeNode> {
+    let cursor = params.cursor
+    do {
+      const page = await this.datasetsRepository.listDatasetTreeNode({
+        ...params,
+        cursor
+      })
+      for (const item of page.items) {
+        yield item
+      }
+      const nextCursor = page.nextCursor ?? undefined
+      // A keyset cursor must always advance. A server (or intermediary
+      // cache) echoing the cursor we just sent would otherwise loop this
+      // generator forever, re-fetching and re-yielding the same page.
+      if (nextCursor !== undefined && nextCursor === cursor) {
+        throw new Error(
+          `Dataset tree pagination cursor did not advance ("${nextCursor}"); aborting iteration`
+        )
+      }
+      cursor = nextCursor
+    } while (cursor)
+  }
+}

src/datasets/domain/useCases/ListDatasetTreeNode.ts

@@ -0,0 +1,20 @@
+import { UseCase } from '../../../core/domain/useCases/UseCase'
+import { IDatasetsRepository, ListDatasetTreeNodeParams } from '../repositories/IDatasetsRepository'
+import { FileTreePage } from '../models/FileTreePage'
+
+export class ListDatasetTreeNode implements UseCase<FileTreePage> {
+  constructor(private readonly datasetsRepository: IDatasetsRepository) {}
+
+  /**
+   * Lists the immediate children of the given folder path inside a dataset
+   * version, returning a single page of folders and files.
+   *
+   * Folders are returned first, then files. Both are sorted by name. Use the
+   * returned `nextCursor` to keep paging the same folder. The cursor is
+   * opaque to callers and is server-validated; an invalid cursor yields a 400
+   * from the API.
+   */
+  async execute(params: ListDatasetTreeNodeParams): Promise<FileTreePage> {
+    return this.datasetsRepository.listDatasetTreeNode(params)
+  }
+}

src/datasets/index.ts

@@ -36,6 +36,8 @@ import { UpdateDatasetLicense } from './domain/useCases/UpdateDatasetLicense'
 import { GetDatasetStorageDriver } from './domain/useCases/GetDatasetStorageDriver'
 import { GetDatasetUploadLimits } from './domain/useCases/GetDatasetUploadLimits'
 import { GetDatasetReviews } from './domain/useCases/GetDatasetReviews'
+import { ListDatasetTreeNode } from './domain/useCases/ListDatasetTreeNode'
+import { IterateDatasetTreeNode } from './domain/useCases/IterateDatasetTreeNode'
 import { ExportDatasetMetadata } from './domain/useCases/ExportDatasetMetadata'
 
 const datasetsRepository = new DatasetsRepository()
@@ -89,6 +91,8 @@ const updateDatasetLicense = new UpdateDatasetLicense(datasetsRepository)
 const getDatasetStorageDriver = new GetDatasetStorageDriver(datasetsRepository)
 const getDatasetUploadLimits = new GetDatasetUploadLimits(datasetsRepository)
 const getDatasetReviews = new GetDatasetReviews(datasetsRepository)
+const listDatasetTreeNode = new ListDatasetTreeNode(datasetsRepository)
+const iterateDatasetTreeNode = new IterateDatasetTreeNode(datasetsRepository)
 const exportDatasetMetadata = new ExportDatasetMetadata(datasetsRepository)
 
 export {
@@ -124,6 +128,8 @@ export {
   getDatasetStorageDriver,
   getDatasetUploadLimits,
   getDatasetReviews,
+  listDatasetTreeNode,
+  iterateDatasetTreeNode,
   exportDatasetMetadata
 }
 export { DatasetNotNumberedVersion } from './domain/models/DatasetNotNumberedVersion'
@@ -170,3 +176,13 @@ export {
   DatasetReviewRubricMetadataBlock,
   DatasetReviewRubricMetadataField
 } from './domain/models/DatasetReview'
+export {
+  FileTreeNode,
+  FileTreeFolderNode,
+  FileTreeFileNode,
+  FileTreeNodeType,
+  isFileTreeFolderNode,
+  isFileTreeFileNode
+} from './domain/models/FileTreeNode'
+export { FileTreePage, FileTreeInclude, FileTreeOrder } from './domain/models/FileTreePage'
+export { ListDatasetTreeNodeParams } from './domain/repositories/IDatasetsRepository'