@spec access_status(binary()) :: DSpace.API.Operation.JSON.t()

Fetches the access status of a file.

@spec clear_primary(binary()) :: DSpace.API.Operation.JSON.t()

Removes the primary-file designation from a file bundle.

This does not delete the file or remove it from the bundle; it only clears the "primary" designation.

@spec create_bundle(
  map(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Creates a new file bundle.

A file bundle must have an item parent.

Parameters

• bundle - bundle attributes as a map. Supports "name" (defaults to "ORIGINAL") and "metadata".
• options - keyword list of options

Options

• :parent - UUID of the parent item (required)

@spec create_in_bundle(binary(), upload(), keyword()) :: DSpace.API.Operation.JSON.t()

Uploads a new file binary into a bundle.

Parameters

• bundle_uuid - UUID of the bundle the file is created in
• file - the file to upload, see upload/0
• options - keyword list of options

Options

• properties - optional properties map. Supports "name" (stored filename) and "metadata". If "name" is absent, the upload's filename is used.

Note: If the payload is passed in form of a path to a file on disk, the file will only be read from disk when the request is actually sent with DSpace.API.request/3, not when calling this function.

Examples

# From a path on disk
File.create_in_bundle(bundle_uuid, "files/test.pdf")

# From in-memory content with metadata
File.create_in_bundle(bundle_uuid, {"report.pdf", pdf_binary, "application/pdf"}, %{
  "metadata" => %{"dc.description" => [%{"value" => "Final report"}]}
})

@spec delete(
  binary() | [binary()],
  keyword()
) :: DSpace.API.Operation.JSON.t()

Deletes one or more files.

All files in a bulk delete must be attached to an item.

@spec delete_bundle(binary()) :: DSpace.API.Operation.JSON.t()

Deletes a file bundle.

Executing this operation also deletes all files in the bundle.

@spec download(
  binary(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Downloads a file binary.

Restricted files require a short-lived authentication token passed as an option (see DSpace.API.Auth.fetch_short_lived_token/0).

Executing this operation will return the bytes verbatim regardless of the file's content type.

Streaming to disk

Req supports streaming the response body straight to disk which is useful especially for large files. If you use a Req-based HTTP adapter (which is this library's default), passing :into as an override option to DSpace.API.request/3 will stream the body to disk:

uuid
|> File.download()
|> DSpace.API.request(client, into: File.stream!("myfile.pdf"))

Options

• :auth_token - short-lived token granting access to a restricted file

@spec fetch(
  binary(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Fetches a single file by UUID.

@spec fetch_bundle(binary()) :: DSpace.API.Operation.JSON.t()

Fetches a file bundle by UUID.

@spec fetch_by_item_handle(
  binary(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Fetches a single file via its parent item's handle.

Either :sequence or :file_name option must be given.

Options

• :sequence - the file's sequence id as an integer
• :file_name - the file's name as a string

@spec fetch_primary_from_bundle(binary()) :: DSpace.API.Operation.JSON.t()

Fetches the primary file of a file bundle.

@spec find_by_item(binary(), binary(), keyword()) :: DSpace.API.Operation.JSON.t()

Finds the files of an item within a bundle.

This operation can be streamed.

Parameters

• item_uuid - UUID of the item
• bundle_name - name of the bundle (e.g. "ORIGINAL")
• options - keyword list of options

Options

• :filters - list of {metadata_field, value} tuples to filter by
• :exclude_hidden - when true, excludes files flagged with the bitstream.hide metadata (default: false)
• :page - Page number (0-based)
• :size - Items per page

@spec format(binary()) :: DSpace.API.Operation.JSON.t()

Fetches the format of a file.

@spec list(keyword()) :: DSpace.API.Operation.JSON.t()

Lists files within a bundle.

The main "bitstreams" endpoint is not browsable, so listing is always bundle-scoped. Equivalent to list_in_bundle/2.

This operation can be streamed.

Options

• :bundle - Required. UUID of the bundle to list files from
• :page - Page number (0-based)
• :size - Items per page

@spec list_in_bundle(
  binary(),
  keyword()
) :: DSpace.API.Operation.JSON.t()

Lists the files within a bundle.

This operation can be streamed.

## Options

• :page - Page number (0-based)
• :size - Items per page

@spec make_primary(binary(), binary()) :: DSpace.API.Operation.JSON.t()

Makes the file the primary file of a bundle.

Executing this operation changes the primary file of a bundle that already has one. Use set_primary/2 when the bundle has no primary file yet.

@spec move(binary(), binary()) :: DSpace.API.Operation.JSON.t()

Moves a file to another bundle.

@spec reorder(binary(), [map()]) :: DSpace.API.Operation.JSON.t()

Reorders the files within a bundle.

Takes the raw list of move operations, e.g. to move the file at index 1 to the front:

File.reorder(bundle_uuid, [
  %{
    "op" => "move",
    "from" => "/_links/bitstreams/1/href",
    "path" => "/_links/bitstreams/0/href"
  }
])

@spec set_format(binary(), integer() | binary()) :: DSpace.API.Operation.JSON.t()

Assigns a registered format to a file.

Parameters

• uuid - the UUID of the file
• format_id - the integer id of a format in the "format registry" (see DSpace.API.File.FormatRegistry).

@spec set_primary(binary(), binary()) :: DSpace.API.Operation.JSON.t()

Sets the file as the primary file of a bundle.

Use this when the bundle has no primary file yet; use make_primary/2 to change an existing one.

@spec thumbnail(binary()) :: DSpace.API.Operation.JSON.t()

Fetches the thumbnail of a file.

Note: Thumbnails are usually only available for files in the ORIGINAL bundle.

@spec update(binary(), [DSpace.API.Operation.JSON.t()], keyword()) ::
  DSpace.API.Operation.JSON.t()

Updates a file's metadata.

@spec upload(
  upload(),
  keyword()
) :: DSpace.API.Operation.t()

Uploads a file to an item.

A file must always be created inside a "bundle", so adding a file to an item is really two API requests: (1) create the target bundle with create_bundle/2, then (2) create_in_bundle/3 the file into it. Executing this operation chains both steps: it creates a bundle on the parent item and then creates the file inside it, returning the created file.

Parameters

• file - the file to upload, see upload/0
• options - keyword list of options

Options

• :parent - UUID of the parent item (required)
• :bundle - optional bundle attributes map, see create_bundle/2
• :properties - optional file properties map, see create_in_bundle/3

Examples

File.upload("files/test.pdf", parent: item_uuid)

File.upload({"report.pdf", pdf_binary, "application/pdf"},
  parent: item_uuid,
  bundle: %{"name" => "ORIGINAL"},
  properties: %{"metadata" => %{"dc.description" => [%{"value" => "Final report"}]}}
)