atlas_rb 1.25.0 → 1.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2274a10469db90f642ca79a877ab37f9db69c294c55737a28824885249ef6220
-  data.tar.gz: c16a9865aa30a521823c17587e80179e681fab4a9c3747957ab0b943e8591548
+  metadata.gz: 74f74d6af596e2f817ba6991018efd21cb158f897efa39ffc572367a27a3c968
+  data.tar.gz: 26b52d5a67e30cac921695e31aba127338fe77095218a1277f6c04049c1dde5e
 SHA512:
-  metadata.gz: fbf77b86e3b695401be85f2f913d4c71820ae2e1c2078884d6b13038d46cca749aaafaf7ef588e9f742db01e8b53b5375734893572430a9ccc7adbfed5444e50
-  data.tar.gz: baf502af151908b4da14e4e51597d60f7c88b90d7659deac2731bd44dc317376dce11bbb8e2c2e9f3d7fbfc33adc0e8b6572124769651e7917bfb51eaaac76b5
+  metadata.gz: 692f82797f41797a10b06b1c6fb79624a03437711c1781afd3e7a0d1f8711eb5964c42197dd6b411e4c1b0df84115a609c7f26091d736f02faacb72a40dc22f3
+  data.tar.gz: fffef87ace94444d2f9b82f5347ad342e8a908f05541fd4c4b4feced02b63cc6ecc5eff57ca2c0824439fb5c133fa3a4389655c157e8809aafc472236fc9eb60

data/.version

@@ -1 +1 @@
-1.25.0
+1.26.0

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.26.0
+
+These bindings need Atlas 0.6.221 or later.
+
+### Added — Darwin Core records
+
+```ruby
+AtlasRb::Work.dwc(id, kind = "xml")             # "xml", "json" or "html"; nil on 404
+AtlasRb::Resource.put_dwc(id, xml_path, origin: nil)
+AtlasRb::Resource.delete_dwc(id)                # true; raises NotFoundError on 404
+AtlasRb::Resource.dwc_versions(id)
+AtlasRb::Resource.dwc_version(id, version_id)
+```
+
+A Work can hold one Simple Darwin Core record. `Work.dwc` returns the stored
+XML by default, the display block for `"html"`, and the Work unwrapped from
+`"work"` for `"json"`, with the terms under `"dwc"`. `put_dwc` replaces the
+whole record and raises `ResourceError` on Atlas's `422` when the document
+breaks a shape rule. `delete_dwc` withdraws the record without purging it, so
+the next `put_dwc` restores it. The version calls mirror `mods_versions` and
+`mods_version`.
+
+### Documented — `metadata_formats` on the Work
+
+`Work.find` results now carry `metadata_formats`, the additional records the
+Work holds, such as `["dwc"]`. No code changed: the gem passes the whole Work
+through.
+
 ## 1.25.0
 
 These bindings need Atlas 0.6.214 or later.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (1.25.0)
+    atlas_rb (1.26.0)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -38,10 +38,13 @@ GEM
       base64
     logger (1.7.0)
     multipart-post (2.4.1)
-    net-http (0.9.1)
+    net-http (0.10.0)
+      net-protocol (>= 0.3.0)
       uri (>= 0.11.1)
     net-http-persistent (4.0.8)
       connection_pool (>= 2.2.4, < 4)
+    net-protocol (0.4.0)
+      timeout
     rake (13.2.1)
     rspec (3.13.0)
       rspec-core (~> 3.13.0)
@@ -56,7 +59,8 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.3)
-    uri (1.1.1)
+    timeout (0.6.1)
+    uri (1.1.2)
     yard (0.9.43)
 
 PLATFORMS

data/README.md

@@ -527,6 +527,35 @@ array (mirroring `Collection.children`); the two mutations return the list
 Resolving those Collections' full contents is a Cerberus/Solr concern —
 this gem never queries the index.
 
+### Darwin Core records
+
+A Work can hold one Simple Darwin Core record beside its MODS. The Work's
+`metadata_formats` says whether it does, so check that before reading:
+
+```ruby
+work = AtlasRb::Work.find("w-789")
+if work["metadata_formats"].include?("dwc")
+  AtlasRb::Work.dwc("w-789", "html")                         # the display block
+  AtlasRb::Work.dwc("w-789", "json")["dwc"]["catalogNumber"]  # => "S27880"
+  AtlasRb::Work.dwc("w-789")                                 # the stored XML
+end
+
+AtlasRb::Resource.put_dwc("w-789", "/tmp/dwc.xml", origin: "xml_loader")
+AtlasRb::Resource.delete_dwc("w-789")   # withdraws; the next put_dwc restores
+
+history = AtlasRb::Resource.dwc_versions("w-789")
+AtlasRb::Resource.dwc_version("w-789", history["versions"].last["version_id"])
+```
+
+`Work.dwc` answers `nil` when the Work holds no record. `put_dwc` raises
+`ResourceError` on a refused document; its body's `error` names the rule
+(`malformed_xml`, `invalid_root`, `record_count` or `duplicate_term`). Atlas
+checks shape only, so validate against `tdwg_dwc_simple.xsd` before you call.
+`delete_dwc` purges nothing: Atlas keeps the document and its history.
+
+The two version calls behave as `mods_versions` and `mods_version` do, under
+the same admin gate.
+
 The two mutations raise the same way `reparent` does — `LinkedMemberError`
 on a structural `422` (carrying the envelope's `error` code as `#code`) and
 `ForbiddenError` on a `403` — instead of swallowing the envelope.
@@ -540,6 +569,8 @@ write. The whole surface:
 | Call | Endpoint |
 |---|---|
 | `Resource.put_mods(id, xml_path, origin:)` | `PUT /resources/{id}/mods` |
+| `Resource.put_dwc(id, xml_path, origin:)` | `PUT /resources/{id}/dwc` (Works only) |
+| `Resource.delete_dwc(id)` | `DELETE /resources/{id}/dwc` (Works only) |
 | `Resource.set_permissions(id, acl)` | `PATCH /resources/{id}/permissions` |
 | `Resource.set_thumbnails(id, thumbnail:, thumbnail_2x:, preview:)` | `PATCH /resources/{id}/thumbnails` |
 | `Resource.reparent(id, parent_id)` | `PATCH /resources/{id}/parent` |

data/lib/atlas_rb/resource.rb

@@ -419,6 +419,47 @@ module AtlasRb
                ))
     end
 
+    # List the retained versions of a Work's Darwin Core record.
+    #
+    # The same envelope as {mods_versions}, under the same admin gate, with
+    # attribution drawn from the Darwin Core edits only. A Work with no record,
+    # or an id that is not a Work, comes back as `{ "versions" => [] }`.
+    #
+    # @param id [String] the Work's NOID.
+    # @param nuid [String, nil] optional acting user's NUID.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header.
+    # @return [AtlasRb::Mash, nil] the envelope, with `"resource_id"` and a
+    #   newest-first `"versions"` array; `nil` on a `404`.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`,
+    #   including the `403` a non-admin caller gets.
+    # @example
+    #   AtlasRb::Resource.dwc_versions("w-789")["versions"].first["source"] # => "dwc"
+    def self.dwc_versions(id, nuid: nil, on_behalf_of: nil)
+      read_body(connection({}, nuid, on_behalf_of: on_behalf_of)
+                  .get('/resources/' + id + '/dwc/versions')) { |body| AtlasRb::Mash.new(body) }
+    end
+
+    # Fetch a Work's Darwin Core document as of a specific version.
+    #
+    # XML only, because Atlas overwrites the JSON access copy in place. Pass a
+    # `version_id` from {dwc_versions}.
+    #
+    # @param id [String] the Work's NOID.
+    # @param version_id [String] an OCFL version label, e.g. `"v3"`.
+    # @param nuid [String, nil] optional acting user's NUID.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header.
+    # @return [String, nil] the raw XML; `nil` on a `404` (unknown version, or
+    #   no record ever written).
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`.
+    # @example
+    #   AtlasRb::Resource.dwc_version("w-789", "v3")
+    def self.dwc_version(id, version_id, nuid: nil, on_behalf_of: nil)
+      read_raw(connection({}, nuid, on_behalf_of: on_behalf_of)
+                 .get('/resources/' + id + '/dwc/versions/' + version_id))
+    end
+
     # Shared read path behind every typed `find`: perform a single-resource
     # `GET` and hand the response to {AtlasRb::FaradayHelper#read_body}, which
     # owns the status mapping (`404` → `nil`, `410` → the tombstone body, any
@@ -485,21 +526,25 @@ module AtlasRb
     # @raise [AtlasRb::ResourceError] on any other non-2xx except `410`.
     # @api private
     def self.write_resource(resp)
+      guard_write(resp)
+      JSON.parse(resp.body)
+    end
+    private_class_method :write_resource
+
+    # The status half of {write_resource}, for a write that answers with no
+    # body, such as a `204`.
+    def self.guard_write(resp)
       if resp.status == 404
         raise AtlasRb::NotFoundError.new("#{request_target(resp)} → 404 (no such resource)", response: resp)
       end
+      return if resp.success? || resp.status == 410
 
-      unless resp.success? || resp.status == 410
-        raise AtlasRb::ResourceError.new("#{request_target(resp)} → #{resp.status}: #{resp.body}", response: resp)
-      end
-
-      JSON.parse(resp.body)
+      raise AtlasRb::ResourceError.new("#{request_target(resp)} → #{resp.status}: #{resp.body}", response: resp)
     end
-    private_class_method :write_resource
+    private_class_method :guard_write
 
-    # The multipart body behind {Work.update} / {Collection.update} /
-    # {Community.update}: the MODS document, plus the optional `origin` tag
-    # naming the surface that produced the edit.
+    # The multipart body behind {put_mods} and {put_dwc}: the XML document,
+    # plus the optional `origin` tag naming the surface that produced the edit.
     #
     # Atlas records `origin` verbatim on the audit event and never branches on
     # it, so a host names its own surfaces (Cerberus sends `metadata_form`,
@@ -512,13 +557,13 @@ module AtlasRb
     # @param origin [String, nil] the edit-origin tag, or `nil` to send none.
     # @return [Hash] the multipart payload.
     # @api private
-    def self.mods_upload_payload(xml_path, origin)
+    def self.xml_upload_payload(xml_path, origin)
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
                                                            File.basename(xml_path)) }
       payload[:origin] = origin.to_s unless origin.nil? || origin.to_s.empty?
       payload
     end
-    private_class_method :mods_upload_payload
+    private_class_method :xml_upload_payload
   end
 end

data/lib/atlas_rb/resource_writes.rb

@@ -52,10 +52,61 @@ module AtlasRb
     def self.put_mods(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
       unwrap(write_resource(
                multipart(nuid, on_behalf_of: on_behalf_of)
-                 .put('/resources/' + id + '/mods', mods_upload_payload(xml_path, origin))
+                 .put('/resources/' + id + '/mods', xml_upload_payload(xml_path, origin))
              ))
     end
 
+    # Replace a Work's Darwin Core record.
+    #
+    # `PUT`: the document replaces the whole record. The first call creates it,
+    # and a call after {delete_dwc} restores it. Each call appends a version.
+    # Atlas checks the document's shape; validating it against
+    # `tdwg_dwc_simple.xsd` is the caller's job.
+    #
+    # @param id [String] the Work's NOID.
+    # @param xml_path [String] path to the Simple Darwin Core XML to upload.
+    # @param nuid [String, nil] optional acting user's NUID.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header.
+    # @param origin [String, nil] the editing surface to record on the audit
+    #   event, e.g. `"xml_loader"`. Omitted from the body when nil.
+    # @return [AtlasRb::Mash] the Work's `id` and its terms under `"dwc"`.
+    # @raise [AtlasRb::NotFoundError] on `404` — no such id, or not a Work.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx. A refused document
+    #   is a `422` whose body names the rule in `error`: `malformed_xml`,
+    #   `invalid_root`, `record_count` or `duplicate_term`.
+    #
+    # @example
+    #   AtlasRb::Resource.put_dwc("xsj3xmz", "/tmp/dwc.xml", origin: "xml_loader")
+    def self.put_dwc(id, xml_path, nuid: nil, on_behalf_of: nil, origin: nil)
+      unwrap(write_resource(
+               multipart(nuid, on_behalf_of: on_behalf_of)
+                 .put('/resources/' + id + '/dwc', xml_upload_payload(xml_path, origin))
+             ))
+    end
+
+    # Withdraw a Work's Darwin Core record.
+    #
+    # Nothing is purged: Atlas keeps the document and its version history, and
+    # the next {put_dwc} restores the record. Until then {Work.dwc} answers
+    # `nil` and the Work's `metadata_formats` leaves out `"dwc"`.
+    #
+    # @param id [String] the Work's NOID.
+    # @param nuid [String, nil] optional acting user's NUID.
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header.
+    # @return [true] when the record was withdrawn.
+    # @raise [AtlasRb::NotFoundError] on `404` — the Work holds no record, or
+    #   the id is not a Work.
+    # @raise [AtlasRb::ResourceError] on any other non-2xx.
+    #
+    # @example
+    #   AtlasRb::Resource.delete_dwc("xsj3xmz")
+    def self.delete_dwc(id, nuid: nil, on_behalf_of: nil)
+      guard_write(connection({}, nuid, on_behalf_of: on_behalf_of).delete('/resources/' + id + '/dwc'))
+      true
+    end
+
     # Adjust a resource's ACL.
     #
     # `PATCH`, and every key merges: a key you omit keeps its stored value.

data/lib/atlas_rb/work.rb

@@ -613,6 +613,39 @@ module AtlasRb
                ))
     end
 
+    # Fetch the Work's Darwin Core record in the requested format.
+    #
+    # A Work holds a record only when its `metadata_formats` includes `"dwc"`,
+    # so check that before calling: a Work with no record answers `nil` here.
+    #
+    # @param id [String] the Work ID.
+    # @param kind [String] one of `"xml"` (default), `"json"` or `"html"`.
+    #   `"xml"` is the stored Simple Darwin Core document, byte for byte, for a
+    #   standalone download. `"html"` is the display block, the counterpart of
+    #   `Work.mods(id, "html")`; each `<dt>` names its term in `data-term`.
+    # @param nuid [String, nil] optional acting user's NUID. On the relay-signing
+    #   path it is signed into the assertion `sub`; on the BYO-JWT (`ATLAS_JWT`)
+    #   path it is ignored (identity lives in the token).
+    # @param on_behalf_of [String, nil] optional NUID for the `On-Behalf-Of`
+    #   header. Falls through to {AtlasRb.config}.default_on_behalf_of when
+    #   omitted.
+    # @return [String, AtlasRb::Mash, nil] the raw body for `"xml"` and
+    #   `"html"`; for `"json"`, the Work unwrapped from its `"work"` key, with
+    #   the terms under `"dwc"`.
+    #
+    #   `nil` when Atlas answers `404` — the Work holds no record (or it was
+    #   withdrawn), or the id is not a Work.
+    # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410`,
+    #   such as the `403` for a Work the caller may not read.
+    # @example
+    #   AtlasRb::Work.dwc("w-789", "json")["dwc"]["catalogNumber"] # => "S27880"
+    def self.dwc(id, kind = 'xml', nuid: nil, on_behalf_of: nil)
+      body = read_raw(connection({}, nuid, on_behalf_of: on_behalf_of).get(ROUTE + id + "/dwc.#{kind}"))
+      return body unless kind.to_s == 'json' && body
+
+      AtlasRb::Mash.new(JSON.parse(body))['work']
+    end
+
     # List the Collections a Work is a *linked* member of.
     #
     # Wraps `GET /works/<id>/linked_members`. Linked membership is the DAG

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.25.0
+  version: 1.26.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday