atlas_rb 1.25.0 → 1.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2274a10469db90f642ca79a877ab37f9db69c294c55737a28824885249ef6220
-  data.tar.gz: c16a9865aa30a521823c17587e80179e681fab4a9c3747957ab0b943e8591548
+  metadata.gz: 40ea8cbef3fa493fefcf29c0dd15a4d7edf72efb58134f8d21050421517ef05f
+  data.tar.gz: 36a4eb18338f27da7ee744233e7b54fd6eb20faa76201e907f94703b8c6583e2
 SHA512:
-  metadata.gz: fbf77b86e3b695401be85f2f913d4c71820ae2e1c2078884d6b13038d46cca749aaafaf7ef588e9f742db01e8b53b5375734893572430a9ccc7adbfed5444e50
-  data.tar.gz: baf502af151908b4da14e4e51597d60f7c88b90d7659deac2731bd44dc317376dce11bbb8e2c2e9f3d7fbfc33adc0e8b6572124769651e7917bfb51eaaac76b5
+  metadata.gz: d33812411e71cfa8bf0031fae4f81b735d598b75cb31f099e0c67a31d8dc0e4cc9c193524443f8dce983f87f96add5c9cc82c6de8c3d1d4211e69611254d4cc6
+  data.tar.gz: f287d655a86594da49f54caa8cb505277577b3b81284e313cf956ee6424fd09f3bdf0085ae51fae14420468c386626eba3c300be3f41e5762d57c65de5938213

data/.version

@@ -1 +1 @@
-1.25.0
+1.27.0

data/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 1.27.0
+
+### Removed — `Resource.class_for` and `Resource::TYPE_MAP`
+
+Callers no longer turn a type string into a class themselves. Replace
+
+```ruby
+AtlasRb::Resource.class_for(found.klass)
+```
+
+with
+
+```ruby
+found.resource_class
+```
+
+The lookup no longer accepts `"File_set"`, the spelling `find` emitted
+before 1.17.0, or `"compilation"` / `"Compilation"`, which no Atlas payload
+reports: the resolver covers Valkyrie-backed types only. Each now raises
+`ArgumentError`. `lib/atlas_rb/resource_types.rb` is gone.
+
+### Added — `Mash#resource_class`
+
+```ruby
+AtlasRb::Resource.find(id).resource_class                # => AtlasRb::FileSet
+AtlasRb::Resource.search("whaling").results.first.resource_class
+```
+
+Every Atlas payload that names a type carries it as `"klass"`, so the method
+lives on the shared `Mash` and covers `find`, `find_many`, `ancestors` nodes
+and the Solr digests. `klass` itself is unchanged.
+
+### Added — `Resource.unresolvable!`
+
+Every `Resource` subclass now registers itself when it is defined, under its
+class name and its snake-cased wire key. A subclass that Atlas never names in
+a payload opts out by calling `unresolvable!` in its body. `Compilation` is
+the only one.
+
+### Added — `mods_editable?`
+
+`true` for `Work`, `Collection` and `Community`, `false` for every other
+type. It matches Atlas's `ResourcesController::TYPED_IVARS`, which Atlas
+does not expose on the wire.
+
+## 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.27.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` |
@@ -584,34 +615,37 @@ Writes that address something only one type has stay typed — `create`, the
 Work-only lifecycle and derivative writes, `Collection.set_featured`, and the
 FileSet, Blob and Compilation writes.
 
-### Resolving one id of unknown type (`Resource.find` and `Resource.class_for`)
+### Resolving one id of unknown type (`Resource.find` and `resource_class`)
 
 When a NOID arrives as runtime data and you do not know its type, resolve
 it generically and dispatch on the reported type:
 
 ```ruby
 found = AtlasRb::Resource.find("b8gtjvk")
-found["klass"]                                   # => "FileSet"
-klass = AtlasRb::Resource.class_for(found["klass"])  # => AtlasRb::FileSet
-klass.find(found["resource"]["id"])
-```
-
-`class_for` is the supported way to turn a type string into a class. Do not
-`const_get` into the `AtlasRb` namespace: the mapping is a stated, closed
-set (`Resource::TYPE_MAP`), not a naming rule — `Blob`'s route is `/files/`,
-and a wire key like `file_set` is not the class name.
-
-It accepts every spelling the DRS stack produces for a type, because a
-caller cannot tell which one it is holding:
-
-| Spelling      | Where it comes from                        |
-|---------------|--------------------------------------------|
-| `"file_set"`  | Atlas's JSON wire key                      |
-| `"FileSet"`   | Solr's `internal_resource`, and `find`'s `"klass"` |
-| `"File_set"`  | a `"klass"` read from a gem before 1.17.0  |
-
-An unknown type raises `ArgumentError` rather than returning `nil`, so a
-type this gem does not model fails where the cause is.
+found.klass                             # => "FileSet"
+found.resource_class                    # => AtlasRb::FileSet
+found.resource_class.find(found.resource.id)
+```
+
+`resource_class` is the supported way to get from a result to its class.
+It works on every Atlas payload that carries a `"klass"`: `find`,
+`find_many`, `ancestors` nodes, and the `search`, `descendant_works` and
+`Compilation.contents` digests. Keep `klass` when the type has to be
+serialized — a job argument, a log line — and use `resource_class` when
+you act on it. Do not `const_get` into the `AtlasRb` namespace.
+
+Every `Resource` subclass registers itself when it is defined, under its
+class name and the key Atlas wraps its JSON in (`FileSet` → `"file_set"`).
+`Compilation` opts out with `unresolvable!`, because the resolver never
+returns one.
+A row naming a type no class registers raises `ArgumentError` rather than
+returning `nil`, so a type this gem does not model fails where the cause
+is.
+
+To ask whether a type has an editable MODS document, use
+`mods_editable?`: it is true for `Work`, `Collection` and `Community` only.
+`Resource.mods` answers for every type, so a successful read does not mean
+a write will be accepted.
 
 **What the resolver covers.** Atlas answers `/resources/:id` for its
 Valkyrie-backed types only: `Work`, `Collection`, `Community`, `FileSet`,
@@ -651,7 +685,7 @@ result = AtlasRb::Resource.search("whaling logbook", type: "Work", per_page: 50)
 result.pagination.total                 # => 12
 hit = result.results.first
 hit.title                               # => "Whaling logbook, 1851"
-AtlasRb::Resource.class_for(hit.klass).find(hit.noid)
+hit.resource_class.find(hit.noid)
 ```
 
 It searches Works, Collections, Communities and People, most relevant first.

data/lib/atlas_rb/collection.rb

@@ -16,6 +16,11 @@ module AtlasRb
     # @api private
     ROUTE = "/collections/"
 
+    # Atlas accepts a MODS write for this type. See {Resource.mods_editable?}.
+    def self.mods_editable?
+      true
+    end
+
     # Fetch a single Collection by ID.
     #
     # @param id [String] the Collection ID.

data/lib/atlas_rb/community.rb

@@ -14,6 +14,11 @@ module AtlasRb
     # @api private
     ROUTE = "/communities/"
 
+    # Atlas accepts a MODS write for this type. See {Resource.mods_editable?}.
+    def self.mods_editable?
+      true
+    end
+
     # Fetch a single Community by ID.
     #
     # @param id [String] the Community ID.

data/lib/atlas_rb/compilation.rb

@@ -24,6 +24,9 @@ module AtlasRb
     # Atlas REST endpoint prefix for this resource.
     # @api private
     ROUTE = "/compilations/"
+    # Atlas's resolver covers Valkyrie-backed types only, and a Compilation is
+    # an ActiveRecord row there, so no Atlas payload names one as its klass.
+    unresolvable!
 
     # Fetch a single Compilation by ID.
     #

data/lib/atlas_rb/mash.rb

@@ -12,5 +12,23 @@ module AtlasRb
   # `type`, `id`).
   class Mash < Hashie::Mash
     disable_warnings
+
+    # The AtlasRb class named by this row's `"klass"`.
+    #
+    # Every Atlas payload that names a type carries it as `"klass"`, in the
+    # class-name spelling: {Resource.find}, {Resource.find_many}, `ancestors`
+    # nodes, and the Solr digests from {Resource.search},
+    # {Resource.descendant_works} and {Compilation.contents}. Nested hashes
+    # are Mashes too, so an `ancestors` node answers this as well.
+    #
+    # @return [Class] the AtlasRb resource class.
+    # @raise [ArgumentError] when the row has no `"klass"`, or names a type
+    #   this gem does not register.
+    # @example Load a search hit as its full resource
+    #   hit = AtlasRb::Resource.search("whaling").results.first
+    #   hit.resource_class.find(hit.noid)
+    def resource_class
+      Resource.resolve_type(self["klass"])
+    end
   end
 end

data/lib/atlas_rb/resource.rb

@@ -18,6 +18,73 @@ module AtlasRb
   class Resource
     extend AtlasRb::FaradayHelper
 
+    # Every type the Atlas resolver can answer with, filled by {inherited} as
+    # each subclass loads and frozen in `atlas_rb.rb` once they all have. Keyed
+    # by both spellings Atlas produces: the wire key (`"file_set"`) and the
+    # class name Solr indexes as `internal_resource` (`"FileSet"`).
+    # @api private
+    TYPES = {}
+
+    # Registers every subclass as a type the resolver can answer with, unless
+    # it opts out with {unresolvable!}.
+    #
+    # The wire key is the class name in snake case, which is the root key
+    # Atlas wraps the type's JSON in (`json.file_set do`). That holds for every
+    # type today; a type whose wire name ever differs would need a way to say
+    # so.
+    #
+    # An anonymous class, or one defined after the gem has loaded, is not
+    # registered: the set of Atlas types is the gem's, and `TYPES` is frozen
+    # by then.
+    #
+    # @api private
+    # @return [void]
+    def self.inherited(subclass)
+      super
+      return if subclass.name.nil? || TYPES.frozen?
+
+      class_name = subclass.name.split("::").last
+      TYPES[class_name.gsub(/(?<!\A)([A-Z])/, '_\1').downcase] = subclass
+      TYPES[class_name] = subclass
+    end
+
+    # Removes this class from the types the resolver can answer with. For a
+    # subclass that Atlas never names in a payload.
+    #
+    # @return [void]
+    def self.unresolvable!
+      TYPES.delete_if { |_, klass| klass == self }
+    end
+
+    # The class registered for a type string, in either spelling.
+    #
+    # An unknown type raises rather than answering `nil`, so a caller holding a
+    # type this gem does not define hears about it here instead of at a
+    # `NoMethodError` a few frames later.
+    #
+    # @api private
+    # @param name [String, Symbol] a wire key or class name.
+    # @return [Class]
+    # @raise [ArgumentError] when no class is registered for that type.
+    def self.resolve_type(name)
+      TYPES.fetch(name.to_s) do
+        raise ArgumentError, "unknown Atlas resource type: #{name.inspect}"
+      end
+    end
+
+    # Whether Atlas accepts a MODS write for this type.
+    #
+    # {Resource.mods} is defined here on the base class, so every type answers
+    # the read — a FileSet's succeeds and returns nothing a curator can edit.
+    # Only {Work}, {Collection} and {Community} take a write, the same set as
+    # Atlas's `ResourcesController::TYPED_IVARS`. Atlas does not expose that
+    # set on the wire, so it is stated here.
+    #
+    # @return [Boolean]
+    def self.mods_editable?
+      false
+    end
+
     # Resolve any Atlas resource by ID without knowing its type up front.
     #
     # The Atlas server returns a single-key JSON object whose key names the
@@ -45,12 +112,12 @@ module AtlasRb
     #   when the id resolves to nothing (`404`):
     #   - `"klass"` — the resource type as its class name, e.g. `"Work"`,
     #     `"FileSet"`. That is the spelling Solr carries as
-    #     `internal_resource`, and {Resource.class_for} turns it into the class.
+    #     `internal_resource`, and {Mash#resource_class} turns it into the class.
     #   - `"resource"` — the resource payload as a Hash.
     # @raise [AtlasRb::ResourceError] on any non-2xx other than `404` / `410` (e.g. an
     #   auth/validation error envelope), carrying Atlas's status + body.
-    # @raise [ArgumentError] when Atlas names a type this gem defines no class
-    #   for. See {Resource.class_for}.
+    # @raise [ArgumentError] when Atlas names a type this gem registers no class
+    #   for. See {Resource.inherited}.
     #
     # @example Polymorphic lookup
     #   AtlasRb::Resource.find("abc123")
@@ -62,7 +129,7 @@ module AtlasRb
       # The class's own name, never `capitalize` over the wire key: `capitalize`
       # answers `"File_set"` for a `file_set`, which is not a constant in this
       # namespace, and callers resolve this string to a class.
-      AtlasRb::Mash.new("klass" => class_for(result.first[0]).name.split("::").last,
+      AtlasRb::Mash.new("klass" => resolve_type(result.first[0]).name.split("::").last,
                         "resource" => result.first[1])
     end
 
@@ -167,8 +234,8 @@ module AtlasRb
     # Each row is a digest read off Solr, not a resource: `{ "id", "noid",
     # "klass", "title", "creators", "year", "thumbnail", "in_progress",
     # "embargoed", "incomplete" }`. `klass` is one of the four type names
-    # above, which {class_for} accepts, so a caller loads the full resource
-    # with `class_for(hit.klass).find(hit.noid)`.
+    # above, so a caller loads the full resource with
+    # `hit.resource_class.find(hit.noid)`.
     #
     # @param query [String, nil] the search text. Omit or pass blank to browse
     #   everything the user may read, newest first.
@@ -189,7 +256,7 @@ module AtlasRb
     # @example Find a Work by a word in its title, then load it
     #   result = AtlasRb::Resource.search("whaling logbook", type: "Work")
     #   hit    = result.results.first
-    #   AtlasRb::Resource.class_for(hit.klass).find(hit.noid)
+    #   hit.resource_class.find(hit.noid)
     # @example Page through every match
     #   (1..AtlasRb::Resource.search("whaling").pagination.pages).flat_map do |page|
     #     AtlasRb::Resource.search("whaling", page: page).results
@@ -419,6 +486,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 +593,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 +624,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

@@ -5,9 +5,7 @@ module AtlasRb
   # as a verb on the `/resources/{id}` sub-resource that already serves its
   # `GET`, so a caller holding only a NOID never resolves the type first.
   #
-  # Loaded after the subclasses because the typed writes delegate here, and
-  # because {Resource::TYPE_MAP} in `resource_types.rb` has the same ordering
-  # requirement.
+  # Loaded after the subclasses because the typed writes delegate here.
   #
   # **The names are deliberately not `update` and `metadata`.** Neither typed
   # name says which document it writes, and `Resource.mods` / `.permissions`
@@ -52,10 +50,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

@@ -13,6 +13,11 @@ module AtlasRb
     # @api private
     ROUTE = "/works/"
 
+    # Atlas accepts a MODS write for this type. See {Resource.mods_editable?}.
+    def self.mods_editable?
+      true
+    end
+
     # Fetch a single Work by ID.
     #
     # @param id [String] the Work ID.
@@ -613,6 +618,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

data/lib/atlas_rb.rb

@@ -33,9 +33,9 @@ require_relative "atlas_rb/blob"
 require_relative "atlas_rb/delegate"
 require_relative "atlas_rb/compilation"
 require_relative "atlas_rb/person"
-# Must follow every Resource subclass above: it names them in a map.
-require_relative "atlas_rb/resource_types"
-# Same ordering requirement as resource_types: the typed writes delegate here.
+# Every resolvable type has registered itself by now.
+AtlasRb::Resource::TYPES.freeze
+# Must follow every Resource subclass above: the typed writes delegate here.
 require_relative "atlas_rb/resource_writes"
 require_relative "atlas_rb/user"
 require_relative "atlas_rb/admin"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 1.25.0
+  version: 1.27.0
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -178,7 +178,6 @@ files:
 - lib/atlas_rb/middleware/raise_on_stale_resource.rb
 - lib/atlas_rb/person.rb
 - lib/atlas_rb/resource.rb
-- lib/atlas_rb/resource_types.rb
 - lib/atlas_rb/resource_writes.rb
 - lib/atlas_rb/system.rb
 - lib/atlas_rb/system/token.rb

data/lib/atlas_rb/resource_types.rb

@@ -1,60 +0,0 @@
-# frozen_string_literal: true
-
-module AtlasRb
-  # Reopens {Resource} with the resource-type vocabulary. This lives in its own
-  # file, required after the eight subclasses, because the map holds the classes
-  # themselves and every one of them subclasses {Resource} — so none of them is
-  # defined yet while `resource.rb` is loading.
-  class Resource
-    # Every type the Atlas resolver can answer with, keyed by each spelling the
-    # DRS stack produces for it: Atlas's wire key (`"file_set"`), the Ruby class
-    # name Solr indexes as `internal_resource` (`"FileSet"`), and the
-    # capitalize-of-the-wire-key form (`"File_set"`) that a caller can still be
-    # holding from a value this gem emitted before {Resource.class_for} existed.
-    # A caller cannot tell which of the three it holds, so all three resolve.
-    #
-    # Stated rather than derived: {Blob}'s `ROUTE` is `/files/`, so nothing in
-    # the routes turns a type into its class either.
-    TYPE_MAP = {
-      "work" => Work, "Work" => Work,
-      "collection" => Collection, "Collection" => Collection,
-      "community" => Community, "Community" => Community,
-      "compilation" => Compilation, "Compilation" => Compilation,
-      "file_set" => FileSet, "FileSet" => FileSet, "File_set" => FileSet,
-      "blob" => Blob, "Blob" => Blob,
-      "delegate" => Delegate, "Delegate" => Delegate,
-      "person" => Person, "Person" => Person
-    }.freeze
-
-    # Resolve a resource-type string to the class that models it.
-    #
-    # Use this on any type that arrives as runtime data — {Resource.find}'s
-    # `"klass"`, a Solr `internal_resource` value, or Atlas's wire key — rather
-    # than reaching into this namespace with `const_get`. The set is closed and
-    # stated in {TYPE_MAP}; it is not a naming rule.
-    #
-    # An unrecognized type raises instead of resolving to `nil` or to whatever
-    # constant happens to bear that name. A caller holding a type this gem does
-    # not define has to hear about it here, where the cause is, rather than at
-    # the `NoMethodError` a few frames later.
-    #
-    # @param name [String, Symbol] a resource type in any of the three
-    #   spellings {TYPE_MAP} accepts.
-    # @return [Class] the AtlasRb class for that type.
-    # @raise [ArgumentError] when the gem defines no class for that type.
-    #
-    # @example Dispatching on a type that arrives as data
-    #   found = AtlasRb::Resource.find("b8gtjvk")
-    #   AtlasRb::Resource.class_for(found["klass"]).find(found["resource"]["id"])
-    #
-    # @example Every spelling of one type
-    #   AtlasRb::Resource.class_for("file_set") # => AtlasRb::FileSet
-    #   AtlasRb::Resource.class_for("FileSet")  # => AtlasRb::FileSet
-    #   AtlasRb::Resource.class_for("File_set") # => AtlasRb::FileSet
-    def self.class_for(name)
-      TYPE_MAP.fetch(name.to_s) do
-        raise ArgumentError, "unknown Atlas resource type: #{name.inspect}"
-      end
-    end
-  end
-end