Use Case for File Citation Formats

[ChengShi-1]

What this PR does / why we need it:

Files: Added getFileCitationByFormat use case, repository method, and FileCitationFormat enum to support Dataverse file citation exports in EndNote, RIS, BibTeX, CSL, and Internal formats.

Which issue(s) this PR closes:

• Closes Use Cases of Get File Citation In Other Formats #436

Related Dataverse PRs:

• Depends on #

Special notes for your reviewer:

Suggestions on how to test this:

Is there a release notes or changelog update needed for this change?:

Additional documentation:

[Copilot]

Pull request overview

Adds first-class support in the files domain for exporting a Dataverse file citation in multiple formats (EndNote, RIS, BibTeX, CSL, Internal) by introducing a new FileCitationFormat enum, a getFileCitationByFormat repository method, and a GetFileCitationByFormat use case, with accompanying docs and tests.

Changes:

• Introduce FileCitationFormat enum and GetFileCitationByFormat use case, and export them from the files module.
• Implement FilesRepository.getFileCitationByFormat() against /access/datafile/{id}/citation/{format} (stringifying JSON responses when needed).
• Add unit/integration/functional coverage plus docs + changelog entry.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
test/unit/files/GetFileCitationByFormat.test.ts	Unit tests for the new use case behavior (success + error propagation).
test/unit/files/FilesRepository.test.ts	Unit tests for the new repository method endpoint + response handling.
test/integration/files/FilesRepository.test.ts	Integration coverage against a running Dataverse for each citation export format.
test/functional/files/GetFileCitationByFormat.test.ts	Functional (public API) coverage for fetching citations in each format.
test/environment/.env	Changes default Dataverse image registry/tag used by the test docker-compose environment.
src/files/infra/repositories/FilesRepository.ts	Adds getFileCitationByFormat() implementation.
src/files/index.ts	Wires the new use case and exports FileCitationFormat.
src/files/domain/useCases/GetFileCitationByFormat.ts	New use case delegating to repository.
src/files/domain/repositories/IFilesRepository.ts	Extends the repository interface with getFileCitationByFormat().
src/files/domain/models/FileCitationFormat.ts	New enum defining supported export formats (API path values).
docs/useCases.md	Adds documentation section and example usage for the new use case.
CHANGELOG.md	Adds an “Added” entry describing the new feature.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

test/environment/.env is now pinned to a Dataverse PR/branch image tag (11733-api-get-file-citation-format) on GHCR. This makes integration/functional tests depend on a potentially ephemeral image and can break CI or future local runs once that tag is removed. Consider reverting to the default (docker.io + unstable) and documenting/overriding the image tag via local env/CI when testing against a Dataverse PR image.

Suggested change

	DATAVERSE_IMAGE_REGISTRY=ghcr.io
	DATAVERSE_IMAGE_TAG=11733-api-get-file-citation-format
	DATAVERSE_IMAGE_REGISTRY=docker.io
	DATAVERSE_IMAGE_TAG=unstable

[Copilot]

The docs list the allowed format values as raw strings (EndNote, RIS, etc.). Since the public API expects a FileCitationFormat enum, it would be clearer/less error-prone to document the enum members (FileCitationFormat.ENDNOTE, ...RIS, ...BIBTEX, ...CSL, ...INTERNAL) rather than (or in addition to) the underlying string values.

Suggested change

	The `format` parameter must be one of the available [FileCitationFormat](../src/files/domain/models/FileCitationFormat.ts) enum values: `EndNote`, `RIS`, `BibTeX`, `CSL`, or `Internal`.
	The `format` parameter must be one of the available [FileCitationFormat](../src/files/domain/models/FileCitationFormat.ts) enum values: `FileCitationFormat.ENDNOTE`, `FileCitationFormat.RIS`, `FileCitationFormat.BIBTEX`, `FileCitationFormat.CSL`, or `FileCitationFormat.INTERNAL`.