atlas_rb 0.0.81 → 0.0.83

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4041d1c545afb6a983fbedda8d91fd2f36abdc15480d551e0156e34b23828ec3
-  data.tar.gz: 0317b9b4967fed169c969196d9fa6dc35a83b081a58bfb03ad8ff72239c73cfa
+  metadata.gz: 0a7a8531fb28a840a529a888d8d5b789ea9ba69aed95fa59d5899f4aea42afd8
+  data.tar.gz: 2f545fdddc0d22cdb3def311ed73abcb946524bffb0a3d55952e1cee9226eb10
 SHA512:
-  metadata.gz: 76227a82a7a1d1afd5b99cbbf258f3376780fb43993008e513a85b898f0b9699b89c8512256bb7d10ded352de295669439ad09fdbf1fc672cf6c041e6dafdbe8
-  data.tar.gz: 97222b89cf90ac7fcf8132c7a380baa569d6a8ce908b9bd041c36b2fb6bfb66cbcb9e81c018613316d6088bd967fc5c6f0201c6959440283981d3622faff8c7f
+  metadata.gz: 5fbc732c7f405ffe14c22169a38e8037eec302a4572f691ca41e2ebd8f5450aad5c33eab8d0b712dacf9295b62d364178ace4caa9af5d932c65f6f2ca04e9044
+  data.tar.gz: 4454c5562263f3401d9cf10764594b7acaf8d978f6264d6738d8f9324abe8b1e9542ce009559c59e3ee31ac36e2fee4a32222912efd43c6fdc06c798d8105a0e

data/.version

@@ -1 +1 @@
-0.0.81
+0.0.83

data/.yardopts

@@ -0,0 +1,8 @@
+--readme README.md
+--markup markdown
+--output-dir doc
+--no-private
+--protected
+lib/**/*.rb
+-
+LICENSE.txt

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    atlas_rb (0.0.81)
+    atlas_rb (0.0.83)
       faraday (~> 2.7)
       faraday-follow_redirects (~> 0.3.0)
       faraday-multipart (~> 1)
@@ -40,6 +40,7 @@ GEM
       rspec-support (~> 3.13.0)
     rspec-support (3.13.3)
     uri (1.1.1)
+    yard (0.9.43)
 
 PLATFORMS
   x86_64-linux
@@ -48,6 +49,7 @@ DEPENDENCIES
   atlas_rb!
   rake (~> 13.0)
   rspec (~> 3.0)
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.2.33

data/README.md

@@ -1,39 +1,132 @@
-# AtlasRb
+# atlas_rb
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/atlas_rb`. To experiment with that code, run `bin/console` for an interactive prompt.
+Ruby client for the **Atlas** API — Northeastern University's institutional
+digital repository.
 
-TODO: Delete this and the text above, and describe your gem
+The gem wraps Atlas's REST endpoints in a small set of class-method-only
+modules, one per resource type. There is no client object to instantiate;
+calls are made directly on the resource class:
+
+```ruby
+AtlasRb::Work.find("w-789")
+```
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
-gem 'atlas_rb'
+gem "atlas_rb"
 ```
 
-And then execute:
+Then `bundle install`, or install standalone with `gem install atlas_rb`.
+
+## Configuration
 
-    $ bundle install
+Every request reads two environment variables:
 
-Or install it yourself as:
+| Variable      | Purpose                                                       |
+|---------------|---------------------------------------------------------------|
+| `ATLAS_URL`   | Base URL of the Atlas API (e.g. `https://atlas.example.edu`). |
+| `ATLAS_TOKEN` | Bearer token used in the `Authorization` header.             |
 
-    $ gem install atlas_rb
+User-scoped calls (currently only `AtlasRb::Authentication`) additionally
+accept an NUID — the Northeastern University ID — which is forwarded in a
+`User: NUID <nuid>` header.
 
-## Usage
+```ruby
+ENV["ATLAS_URL"]   = "https://atlas.example.edu"
+ENV["ATLAS_TOKEN"] = "..."
+```
 
-TODO: Write usage instructions here
+## Resource hierarchy
 
-## Development
+```
+Community  →  Collection  →  Work
+                              ↓
+                            FileSet
+                              ↓
+                             Blob
+```
+
+| Class                  | Represents                                                                |
+|------------------------|---------------------------------------------------------------------------|
+| `AtlasRb::Community`   | Top-level org unit; may nest sub-Communities.                             |
+| `AtlasRb::Collection`  | Holds Works; lives directly under a Community.                            |
+| `AtlasRb::Work`        | Bibliographic unit (article, thesis, dataset…); MODS metadata lives here. |
+| `AtlasRb::FileSet`     | Classified slot under a Work (e.g. `"primary"`, `"supplemental"`).        |
+| `AtlasRb::Blob`        | The binary bytes; supports streaming downloads.                           |
+| `AtlasRb::Authentication` | NUID → user record / group lookup.                                     |
+| `AtlasRb::Resource`    | Generic resolver and permissions lookup.                                  |
+| `AtlasRb::Reset`       | Test-only — wipes Atlas state via `GET /reset`.                           |
+
+### A note on `create` argument shapes
+
+The CRUD-twin classes look the same but pass different parent IDs:
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```ruby
+AtlasRb::Community.create(nil)             # top-level community (parent_id: nil)
+AtlasRb::Community.create("c-123")         # sub-community of c-123
+AtlasRb::Collection.create("c-123")        # collection under community c-123
+AtlasRb::Work.create("col-456")            # work under collection col-456 (collection_id, not parent_id)
+AtlasRb::FileSet.create("w-789", "primary") # file_set under work w-789, classification "primary"
+AtlasRb::Blob.create("w-789", path, name)  # blob under work w-789 with original filename preserved
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+## End-to-end example
+
+```ruby
+require "atlas_rb"
 
-## Contributing
+ENV["ATLAS_URL"]   = "https://atlas.example.edu"
+ENV["ATLAS_TOKEN"] = "..."
+
+# 1. Build the org structure (each create can optionally seed MODS metadata).
+community  = AtlasRb::Community.create(nil,             "/tmp/community-mods.xml")
+collection = AtlasRb::Collection.create(community["id"], "/tmp/coll-mods.xml")
+work       = AtlasRb::Work.create(collection["id"],      "/tmp/work-mods.xml")
+
+# 2. Upload a binary attached to the work, preserving the user-facing filename.
+blob = AtlasRb::Blob.create(work["id"], "/tmp/upload.tmp", "thesis.pdf")
+
+# 3. List everything attached to the work.
+AtlasRb::Work.files(work["id"])
+
+# 4. Stream the binary back without buffering it in memory.
+File.open("out.pdf", "wb") do |f|
+  headers = AtlasRb::Blob.content(blob["id"]) { |chunk| f.write(chunk) }
+  puts headers["content-type"]
+end
+
+# 5. Look up the acting user and their groups.
+AtlasRb::Authentication.login("001234567")
+AtlasRb::Authentication.groups("001234567")
+```
+
+## Generated documentation
+
+Full API reference, including `@param` / `@return` / `@example` for every
+method, is generated with [YARD](https://yardoc.org/):
+
+```bash
+bundle exec yard doc
+open doc/index.html
+```
+
+`yard stats --list-undoc` should report 100% coverage.
+
+## Development
+
+```bash
+bin/setup            # install dependencies
+bin/console          # IRB with atlas_rb loaded
+bundle exec rspec    # run tests
+bundle exec rubocop  # lint
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/atlas_rb.
+To cut a release, bump the version in `.version` (which `lib/atlas_rb/version.rb`
+reads at load time) and run `bundle exec rake release`.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/atlas_rb/authentication.rb

@@ -1,15 +1,49 @@
 # frozen_string_literal: true
 
 module AtlasRb
+  # User-facing identity lookups against the Atlas API.
+  #
+  # Unlike the resource classes, {Authentication} threads a real NUID into the
+  # `User` header via {FaradayHelper#connection}'s second positional argument.
+  # The Atlas server uses that NUID — combined with the bearer token from
+  # `ATLAS_TOKEN` — to resolve the acting user and their group memberships.
+  #
+  # No login round-trip happens here today; the bearer token is assumed to be
+  # already provisioned out-of-band. The commented-out code in this file
+  # reflects an older flow where a `/token` endpoint exchanged an NUID for a
+  # session token.
   class Authentication
     extend AtlasRb::FaradayHelper
 
+    # Look up the Atlas user record for an NUID.
+    #
+    # @param nuid [String] the user's Northeastern University ID.
+    # @return [Hash] the user record returned by `GET /user`, including at
+    #   minimum `"id"`, `"name"`, and `"groups"`.
+    # @raise [JSON::ParserError] if the response body is not valid JSON
+    #   (typically caused by an auth failure returning HTML).
+    #
+    # @example
+    #   AtlasRb::Authentication.login("001234567")
+    #   # => { "id" => 42, "name" => "Jane Doe", "groups" => [...] }
     def self.login(nuid)
       # JSON.parse(connection({ nuid: nuid }).post('/token')&.body)["token"]
       # need hash - id, name, token => ...
       JSON.parse(connection({}, nuid).get('/user')&.body)
     end
 
+    # Fetch only the group memberships for an NUID.
+    #
+    # Convenience wrapper around the same `GET /user` call as {.login}; useful
+    # when authorization checks only need group names.
+    #
+    # @param nuid [String] the user's Northeastern University ID.
+    # @return [Array<Hash>] the `"groups"` array from the user record.
+    # @raise [JSON::ParserError] if the response body is not valid JSON.
+    #
+    # @example
+    #   AtlasRb::Authentication.groups("001234567")
+    #   # => [{ "id" => 7, "name" => "Library Staff" }, ...]
     def self.groups(nuid)
       # user_details = login(nuid)
       # token = user_details[:token] ...

data/lib/atlas_rb/blob.rb

@@ -1,13 +1,75 @@
 # frozen_string_literal: true
 
 module AtlasRb
+  # The binary content backing a {FileSet} (or attached directly to a {Work}).
+  #
+  # Blobs are the bytes-on-disk layer of the hierarchy. Operations on this
+  # class deal with raw octet streams: uploading new content, replacing
+  # content on an existing Blob, and **streaming** downloads via a chunk
+  # handler so very large files don't have to be buffered in memory.
+  #
+  # See also: {Work}, {FileSet}.
   class Blob < Resource
+    # Atlas REST endpoint prefix for this resource.
+    # @api private
     ROUTE = "/files/"
 
+    # Fetch a single Blob's metadata record (not its bytes — see {.content}).
+    #
+    # @param id [String] the Blob ID.
+    # @return [Hash] the `"blob"` object, already unwrapped — typically
+    #   includes `"id"`, `"original_filename"`, `"size"`, and a download URL.
+    #
+    # @example
+    #   AtlasRb::Blob.find("b-321")
+    #   # => { "id" => "b-321", "original_filename" => "scan.pdf", ... }
     def self.find(id)
       JSON.parse(connection({}).get(ROUTE + id)&.body)['blob']
     end
 
+    # Stream the Blob's binary content through a caller-supplied block.
+    #
+    # The body is **not** buffered — each chunk Faraday receives is yielded
+    # to `chunk_handler` immediately, making this safe for files larger than
+    # available memory. The first chunk's response headers are captured and
+    # returned so callers can inspect `Content-Type`, `Content-Length`, etc.
+    #
+    # @param id [String] the Blob ID.
+    # @yieldparam chunk [String] the next chunk of binary data.
+    # @return [Hash] the response headers from `GET /files/<id>/content`.
+    #
+    # @example Stream to disk
+    #   File.open("/tmp/out.pdf", "wb") do |f|
+    #     headers = AtlasRb::Blob.content("b-321") { |chunk| f.write(chunk) }
+    #     puts headers["content-type"]
+    #   end
+    def self.content(id, &chunk_handler)
+      headers = {}
+      connection({}).get("#{ROUTE}#{id}/content") do |req|
+        req.options.on_data = proc do |chunk, _bytes_received, env|
+          headers = env.response_headers if headers.empty? && env
+          chunk_handler.call(chunk)
+        end
+      end
+      headers
+    end
+
+    # Upload a new Blob attached to a Work.
+    #
+    # `original_filename` is preserved separately from the upload's
+    # `File.basename(blob_path)` because the on-disk path is often a temp
+    # file name (`RackMultipart...tmp`) — Atlas needs the user-facing name
+    # for download UX.
+    #
+    # @param id [String] the parent Work ID.
+    # @param blob_path [String] path to the binary file on disk to upload.
+    # @param original_filename [String] the user-facing filename Atlas
+    #   should record (e.g. `"final_thesis.pdf"`).
+    # @return [Hash] the created `"blob"` payload, including its `"id"`.
+    #
+    # @example
+    #   AtlasRb::Blob.create("w-789", "/tmp/upload.tmp", "final_thesis.pdf")
+    #   # => { "id" => "b-321", "original_filename" => "final_thesis.pdf", ... }
     def self.create(id, blob_path, original_filename)
       payload = { work_id: id,
                   original_filename: original_filename,
@@ -18,10 +80,29 @@ module AtlasRb
       JSON.parse(multipart({}).post(ROUTE, payload)&.body)['blob']
     end
 
+    # Delete a Blob (the bytes *and* the metadata record).
+    #
+    # @param id [String] the Blob ID.
+    # @return [Faraday::Response] the raw delete response.
+    #
+    # @example
+    #   AtlasRb::Blob.destroy("b-321")
     def self.destroy(id)
       connection({}).delete(ROUTE + id)
     end
 
+    # Replace the bytes of an existing Blob in-place.
+    #
+    # The Blob ID is preserved; only the underlying content changes. The
+    # original filename is *not* updated by this call — use a new
+    # {.create} if you need a different `original_filename`.
+    #
+    # @param id [String] the Blob ID.
+    # @param blob_path [String] path to the replacement binary on disk.
+    # @return [Hash] the parsed JSON response from the patch.
+    #
+    # @example
+    #   AtlasRb::Blob.update("b-321", "/tmp/revised.pdf")
     def self.update(id, blob_path)
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(blob_path),
                                                           "application/octet-stream",

data/lib/atlas_rb/collection.rb

@@ -1,13 +1,46 @@
 # frozen_string_literal: true
 
 module AtlasRb
+  # A grouping of {Work}s within a {Community}.
+  #
+  # Collections are the leaf containers in the organizational tree — they hold
+  # Works directly and cannot contain other Collections. Every Collection has
+  # exactly one parent Community.
+  #
+  # See also: {Community}, {Work}.
   class Collection < Resource
+    # Atlas REST endpoint prefix for this resource.
+    # @api private
     ROUTE = "/collections/"
 
+    # Fetch a single Collection by ID.
+    #
+    # @param id [String] the Collection ID.
+    # @return [Hash] the `"collection"` object, already unwrapped from the
+    #   JSON response.
+    #
+    # @example
+    #   AtlasRb::Collection.find("col-456")
+    #   # => { "id" => "col-456", "title" => "Faculty Publications", ... }
     def self.find(id)
       JSON.parse(connection({}).get(ROUTE + id)&.body)["collection"]
     end
 
+    # Create a new Collection under an existing Community.
+    #
+    # **Note**: unlike {Community.create}, the `id` parameter here is the
+    # parent **Community** ID (not a parent Collection ID — Collections do
+    # not nest).
+    #
+    # @param id [String] the parent Community ID.
+    # @param xml_path [String, nil] optional path to a MODS XML file used to
+    #   seed metadata. When given, the Collection is created and immediately
+    #   patched with the metadata in the file.
+    # @return [Hash] the created Collection payload (post-update if
+    #   `xml_path` was supplied).
+    #
+    # @example
+    #   AtlasRb::Collection.create("c-123", "/tmp/collection-mods.xml")
     def self.create(id, xml_path = nil)
       result = JSON.parse(connection({ parent_id: id }).post(ROUTE)&.body)["collection"]
       return result unless xml_path.present?
@@ -16,14 +49,36 @@ module AtlasRb
       find(result["id"])
     end
 
+    # Delete a Collection.
+    #
+    # @param id [String] the Collection ID.
+    # @return [Faraday::Response] the raw delete response.
+    #
+    # @example
+    #   AtlasRb::Collection.destroy("col-456")
     def self.destroy(id)
       connection({}).delete(ROUTE + id)
     end
 
+    # List the Works in a Collection.
+    #
+    # @param id [String] the Collection ID.
+    # @return [Hash] the child listing from `GET /collections/<id>/children`.
+    #
+    # @example
+    #   AtlasRb::Collection.children("col-456")
     def self.children(id)
       JSON.parse(connection({}).get(ROUTE + id + '/children')&.body)
     end
 
+    # Replace a Collection's metadata by uploading a MODS XML document.
+    #
+    # @param id [String] the Collection ID.
+    # @param xml_path [String] path to a MODS XML file on disk.
+    # @return [Hash] the parsed JSON response from the patch.
+    #
+    # @example
+    #   AtlasRb::Collection.update("col-456", "/tmp/collection-mods.xml")
     def self.update(id, xml_path)
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
@@ -31,10 +86,27 @@ module AtlasRb
       JSON.parse(multipart({}).patch(ROUTE + id, payload)&.body)
     end
 
+    # Patch individual metadata fields without uploading a full MODS document.
+    #
+    # @param id [String] the Collection ID.
+    # @param values [Hash] field-level metadata updates.
+    # @return [Hash] the parsed JSON response.
+    #
+    # @example
+    #   AtlasRb::Collection.metadata("col-456", title: "Renamed Collection")
     def self.metadata(id, values)
       JSON.parse(connection({ metadata: values }).patch(ROUTE + id)&.body)
     end
 
+    # Fetch the Collection's MODS representation in the requested format.
+    #
+    # @param id [String] the Collection ID.
+    # @param kind [String, nil] one of `"json"` (default), `"html"`, or
+    #   `"xml"`.
+    # @return [String] the raw response body in the requested format.
+    #
+    # @example
+    #   AtlasRb::Collection.mods("col-456", "xml")
     def self.mods(id, kind = nil)
       # json default, html, xml
       connection({}).get(

data/lib/atlas_rb/community.rb

@@ -1,13 +1,50 @@
 # frozen_string_literal: true
 
 module AtlasRb
+  # A top-level grouping in the Atlas hierarchy.
+  #
+  # Communities are organizational containers — they hold {Collection}s and,
+  # optionally, sub-Communities. Most institutional structure (departments,
+  # programs, projects) is modeled as a tree of Communities with Collections
+  # at the leaves.
+  #
+  # See also: {Collection}, {Work}.
   class Community < Resource
+    # Atlas REST endpoint prefix for this resource.
+    # @api private
     ROUTE = "/communities/"
 
+    # Fetch a single Community by ID.
+    #
+    # @param id [String] the Community ID.
+    # @return [Hash] the `"community"` object from the JSON response,
+    #   already unwrapped.
+    #
+    # @example
+    #   AtlasRb::Community.find("c-123")
+    #   # => { "id" => "c-123", "title" => "College of Engineering", ... }
     def self.find(id)
       JSON.parse(connection({}).get(ROUTE + id)&.body)["community"]
     end
 
+    # Create a new Community, optionally seeded with MODS metadata.
+    #
+    # Pass `id = nil` to create a top-level Community; pass a Community ID to
+    # nest the new Community beneath an existing one.
+    #
+    # @param id [String, nil] the parent Community ID, or `nil` for a
+    #   top-level Community.
+    # @param xml_path [String, nil] optional path to a MODS XML file. When
+    #   given, the Community is created and immediately patched with the
+    #   metadata in the file; the returned Hash reflects the patched state.
+    # @return [Hash] the created Community payload (post-update if `xml_path`
+    #   was supplied).
+    #
+    # @example Top-level community, no metadata
+    #   AtlasRb::Community.create(nil)
+    #
+    # @example Sub-community seeded from MODS
+    #   AtlasRb::Community.create("c-parent", "/tmp/dept-mods.xml")
     def self.create(id = nil, xml_path = nil)
       result = JSON.parse(connection({ parent_id: id }).post(ROUTE)&.body)["community"]
       return result unless xml_path.present?
@@ -16,14 +53,36 @@ module AtlasRb
       find(result["id"])
     end
 
+    # Delete a Community.
+    #
+    # @param id [String] the Community ID.
+    # @return [Faraday::Response] the raw delete response.
+    #
+    # @example
+    #   AtlasRb::Community.destroy("c-123")
     def self.destroy(id)
       connection({}).delete(ROUTE + id)
     end
 
+    # List the immediate children (sub-Communities and Collections) of a Community.
+    #
+    # @param id [String] the parent Community ID.
+    # @return [Hash] the child listing from `GET /communities/<id>/children`.
+    #
+    # @example
+    #   AtlasRb::Community.children("c-123")
     def self.children(id)
       JSON.parse(connection({}).get(ROUTE + id + '/children')&.body)
     end
 
+    # Replace a Community's metadata by uploading a MODS XML document.
+    #
+    # @param id [String] the Community ID.
+    # @param xml_path [String] path to a MODS XML file on disk.
+    # @return [Hash] the parsed JSON response from the patch.
+    #
+    # @example
+    #   AtlasRb::Community.update("c-123", "/tmp/community-mods.xml")
     def self.update(id, xml_path)
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
@@ -31,10 +90,30 @@ module AtlasRb
       JSON.parse(multipart({}).patch(ROUTE + id, payload)&.body)
     end
 
+    # Patch individual metadata fields without uploading a full MODS document.
+    #
+    # @param id [String] the Community ID.
+    # @param values [Hash] field-level metadata updates (shape determined by
+    #   the Atlas server, typically a mapping from MODS field name to value).
+    # @return [Hash] the parsed JSON response.
+    #
+    # @example
+    #   AtlasRb::Community.metadata("c-123", title: "New Name")
     def self.metadata(id, values)
       JSON.parse(connection({ metadata: values }).patch(ROUTE + id)&.body)
     end
 
+    # Fetch the Community's MODS representation in the requested format.
+    #
+    # @param id [String] the Community ID.
+    # @param kind [String, nil] one of `"json"` (default when omitted),
+    #   `"html"`, or `"xml"`. When `nil`, Atlas returns its default
+    #   representation.
+    # @return [String] the raw response body (JSON, HTML, or XML serialized
+    #   as a string).
+    #
+    # @example HTML rendering for display
+    #   AtlasRb::Community.mods("c-123", "html")
     def self.mods(id, kind = nil)
       # json default, html, xml
       connection({}).get(

data/lib/atlas_rb/faraday_helper.rb

@@ -1,7 +1,33 @@
 # frozen_string_literal: true
 
 module AtlasRb
+  # HTTP transport helpers shared by every resource class.
+  #
+  # Every Atlas request reads two environment variables:
+  #
+  # - `ATLAS_URL`   — base URL of the Atlas API (e.g. `https://atlas.example.edu`).
+  # - `ATLAS_TOKEN` — bearer token used in the `Authorization` header.
+  #
+  # Most calls also identify the acting user via a `User: NUID <nuid>` header.
+  # Resource classes typically pass `nuid = nil` (anonymous / system context);
+  # {AtlasRb::Authentication} is the only place where a real NUID is currently
+  # threaded through.
+  #
+  # The module is mixed in via `extend`, so its methods become class methods on
+  # the host (e.g. `AtlasRb::Work.connection({})`).
   module FaradayHelper
+    # Build a JSON-content Faraday connection to the Atlas API.
+    #
+    # @param params [Hash] query-string / body params to attach to the request.
+    #   Resource classes use this to pass things like `parent_id:`, `work_id:`,
+    #   or `metadata:` without manually serializing.
+    # @param nuid [String, nil] optional Northeastern University ID to send in
+    #   the `User` header. Defaults to `nil` (no NUID context).
+    # @return [Faraday::Connection] a connection that follows redirects and
+    #   uses Faraday's default adapter.
+    #
+    # @example Fetching a community
+    #   AtlasRb::Community.connection({}).get('/communities/abc123')
     def connection(params, nuid=nil)
       Faraday.new(
         url: ENV.fetch("ATLAS_URL", nil),
@@ -17,6 +43,24 @@ module AtlasRb
       end
     end
 
+    # Build a multipart Faraday connection used for binary and XML uploads.
+    #
+    # The same `ATLAS_URL` / `ATLAS_TOKEN` env vars apply. Unlike {#connection},
+    # the `Content-Type` is set automatically by the multipart middleware, and
+    # callers pass a payload hash whose values may include
+    # `Faraday::Multipart::FilePart` instances.
+    #
+    # @param nuid [String, nil] optional NUID for the `User` header.
+    # @return [Faraday::Connection] a multipart-aware connection.
+    #
+    # @example Posting a binary blob
+    #   payload = {
+    #     work_id: "w-123",
+    #     binary: Faraday::Multipart::FilePart.new(File.open("scan.pdf"),
+    #                                               "application/octet-stream",
+    #                                               "scan.pdf")
+    #   }
+    #   AtlasRb::Blob.multipart({}).post('/files/', payload)
     def multipart(nuid=nil)
       Faraday.new(
         url: ENV.fetch("ATLAS_URL", nil),

data/lib/atlas_rb/file_set.rb

@@ -1,21 +1,70 @@
 # frozen_string_literal: true
 
 module AtlasRb
+  # An ordered, classified slot under a {Work} that holds a {Blob}.
+  #
+  # FileSets give a Work multiple distinct files (e.g. a primary PDF, a
+  # supplemental dataset, a thumbnail) and tag each with a `classification`
+  # so the UI knows how to display it. The actual binary content lives on
+  # the associated {Blob}.
+  #
+  # See also: {Work}, {Blob}.
   class FileSet < Resource
+    # Atlas REST endpoint prefix for this resource.
+    # @api private
     ROUTE = "/file_sets/"
 
+    # Fetch a single FileSet by ID.
+    #
+    # @param id [String] the FileSet ID.
+    # @return [Hash] the `"file_set"` object, already unwrapped.
+    #
+    # @example
+    #   AtlasRb::FileSet.find("fs-001")
     def self.find(id)
       JSON.parse(connection({}).get(ROUTE + id)&.body)["file_set"]
     end
 
+    # Create a new FileSet under a Work.
+    #
+    # @param id [String] the parent Work ID.
+    # @param classification [String] role tag for the FileSet — e.g.
+    #   `"primary"`, `"supplemental"`, `"thumbnail"`. The exact set is
+    #   defined by the Atlas server.
+    # @return [Hash] the created `"file_set"` payload, including its `"id"`
+    #   which can then be passed to {.update} to attach a binary.
+    #
+    # @example
+    #   fs = AtlasRb::FileSet.create("w-789", "primary")
+    #   AtlasRb::FileSet.update(fs["id"], "/tmp/article.pdf")
     def self.create(id, classification)
       JSON.parse(connection({ work_id: id, classification: classification }).post(ROUTE)&.body)["file_set"]
     end
 
+    # Delete a FileSet.
+    #
+    # @param id [String] the FileSet ID.
+    # @return [Faraday::Response] the raw delete response.
+    #
+    # @example
+    #   AtlasRb::FileSet.destroy("fs-001")
     def self.destroy(id)
       connection({}).delete(ROUTE + id)
     end
 
+    # Attach (or replace) the binary content backing this FileSet.
+    #
+    # The body is uploaded as `application/octet-stream` regardless of the
+    # file's true type — Atlas inspects the content server-side. To upload
+    # a binary blob *plus* an original filename, use {Blob.create} directly
+    # against the underlying `/files/` endpoint.
+    #
+    # @param id [String] the FileSet ID.
+    # @param blob_path [String] path to the binary file on disk.
+    # @return [Hash] the parsed JSON response from the patch.
+    #
+    # @example
+    #   AtlasRb::FileSet.update("fs-001", "/tmp/article.pdf")
     def self.update(id, blob_path)
       # Need to figure out blob vs XML
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(blob_path),

data/lib/atlas_rb/resource.rb

@@ -1,15 +1,54 @@
 # frozen_string_literal: true
 
 module AtlasRb
+  # Abstract base for every Atlas resource type.
+  #
+  # Subclasses define a `ROUTE` constant (e.g. `"/communities/"`) and override
+  # whichever of `find / create / destroy / update / metadata / mods` apply.
+  # The {Resource} class itself ships three endpoints that are not
+  # type-specific: a generic resolver, an XML preview helper, and a
+  # permissions lookup.
+  #
+  # The Atlas resource hierarchy is:
+  #
+  #     {Community}  →  {Collection}  →  {Work}  →  {FileSet}  →  {Blob}
+  #
+  # Subclasses extend {FaradayHelper} so that `connection(...)` and
+  # `multipart(...)` are available as class methods.
   class Resource
     extend AtlasRb::FaradayHelper
 
+    # 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
+    # resource type (`"community"`, `"collection"`, `"work"`, etc.); this
+    # method splits that into a normalized `{ "klass" => ..., "resource" => ... }`
+    # pair so callers can dispatch on type.
+    #
+    # @param id [String] an Atlas resource ID of any type.
+    # @return [Hash{String => String, Hash}] hash with two keys:
+    #   - `"klass"` — the resource type, capitalized (e.g. `"Work"`).
+    #   - `"resource"` — the resource payload as a Hash.
+    #
+    # @example Polymorphic lookup
+    #   AtlasRb::Resource.find("abc123")
+    #   # => { "klass" => "Work", "resource" => { "id" => "abc123", "title" => "..." } }
     def self.find(id)
       result = JSON.parse(connection({}).get('/resources/' + id)&.body)
       { "klass" => result.first[0].capitalize,
         "resource" => result.first[1] }
     end
 
+    # Validate a MODS XML document against Atlas's schema *without* persisting it.
+    #
+    # Useful for surfacing validation errors in UIs before the user commits.
+    #
+    # @param xml_path [String] path to a MODS XML file on disk.
+    # @return [String] the raw response body from `POST /resources/preview`
+    #   — typically a JSON or XML error report.
+    #
+    # @example
+    #   AtlasRb::Resource.preview("/tmp/draft-mods.xml")
     def self.preview(xml_path)
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
@@ -17,6 +56,15 @@ module AtlasRb
       multipart({}).post('/resources/preview', payload)&.body
     end
 
+    # Fetch the access-control entries for a resource.
+    #
+    # @param id [String] an Atlas resource ID.
+    # @return [Hash] the `"resource"` payload from `GET /resources/<id>/permissions`,
+    #   typically containing read/write/admin grant lists.
+    #
+    # @example
+    #   AtlasRb::Resource.permissions("abc123")
+    #   # => { "id" => "abc123", "read" => [...], "write" => [...] }
     def self.permissions(id)
       result = JSON.parse(connection({}).get('/resources/' + id + '/permissions')&.body)["resource"]
     end

data/lib/atlas_rb/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module AtlasRb
+  # Current gem version, read from the `.version` file at the repo root at load time.
   VERSION = File.read(".version").strip
 end

data/lib/atlas_rb/work.rb

@@ -1,13 +1,49 @@
 # frozen_string_literal: true
 
 module AtlasRb
+  # The bibliographic unit in Atlas — an article, thesis, dataset, image, etc.
+  #
+  # A Work belongs to exactly one {Collection} and aggregates one or more
+  # {FileSet}s, each of which holds binary content via a {Blob}. MODS metadata
+  # is attached at the Work level.
+  #
+  # See also: {Collection}, {FileSet}, {Blob}.
   class Work < Resource
+    # Atlas REST endpoint prefix for this resource.
+    # @api private
     ROUTE = "/works/"
 
+    # Fetch a single Work by ID.
+    #
+    # @param id [String] the Work ID.
+    # @return [Hash] the `"work"` object, already unwrapped from the JSON
+    #   response.
+    #
+    # @example
+    #   AtlasRb::Work.find("w-789")
+    #   # => { "id" => "w-789", "title" => "An Article", ... }
     def self.find(id)
       JSON.parse(connection({}).get(ROUTE + id)&.body)["work"]
     end
 
+    # Create a new Work in an existing Collection.
+    #
+    # **Note**: unlike {Community.create} and {Collection.create}, the `id`
+    # parameter here is the parent **Collection** ID. The underlying request
+    # uses the `collection_id` query param rather than `parent_id`.
+    #
+    # @param id [String] the parent Collection ID.
+    # @param xml_path [String, nil] optional path to a MODS XML file. When
+    #   given, the Work is created and immediately patched with the metadata
+    #   in the file.
+    # @return [Hash] the created Work payload (post-update if `xml_path` was
+    #   supplied).
+    #
+    # @example Empty work, metadata to be added later
+    #   AtlasRb::Work.create("col-456")
+    #
+    # @example Work seeded from MODS
+    #   AtlasRb::Work.create("col-456", "/tmp/work-mods.xml")
     def self.create(id, xml_path = nil)
       result = JSON.parse(connection({ collection_id: id }).post(ROUTE)&.body)["work"]
       return result unless xml_path.present?
@@ -16,10 +52,25 @@ module AtlasRb
       find(result["id"])
     end
 
+    # Delete a Work.
+    #
+    # @param id [String] the Work ID.
+    # @return [Faraday::Response] the raw delete response.
+    #
+    # @example
+    #   AtlasRb::Work.destroy("w-789")
     def self.destroy(id)
       connection({}).delete(ROUTE + id)
     end
 
+    # Replace a Work's metadata by uploading a MODS XML document.
+    #
+    # @param id [String] the Work ID.
+    # @param xml_path [String] path to a MODS XML file on disk.
+    # @return [Hash] the parsed JSON response from the patch.
+    #
+    # @example
+    #   AtlasRb::Work.update("w-789", "/tmp/work-mods.xml")
     def self.update(id, xml_path)
       payload = { binary: Faraday::Multipart::FilePart.new(File.open(xml_path),
                                                            "application/xml",
@@ -27,14 +78,41 @@ module AtlasRb
       JSON.parse(multipart({}).patch(ROUTE + id, payload)&.body)
     end
 
+    # Patch individual metadata fields without uploading a full MODS document.
+    #
+    # @param id [String] the Work ID.
+    # @param values [Hash] field-level metadata updates.
+    # @return [Hash] the parsed JSON response.
+    #
+    # @example
+    #   AtlasRb::Work.metadata("w-789", title: "Revised Title")
     def self.metadata(id, values)
       JSON.parse(connection({ metadata: values }).patch(ROUTE + id)&.body)
     end
 
+    # List the {FileSet}s and {Blob}s attached to a Work.
+    #
+    # Useful for building download UIs — the response includes enough to
+    # render each file's display name, size, and download URL.
+    #
+    # @param id [String] the Work ID.
+    # @return [Hash] the listing from `GET /works/<id>/files`.
+    #
+    # @example
+    #   AtlasRb::Work.files("w-789")
     def self.files(id)
       JSON.parse(connection({}).get(ROUTE + id + '/files')&.body)
     end
 
+    # Fetch the Work's MODS representation in the requested format.
+    #
+    # @param id [String] the Work ID.
+    # @param kind [String, nil] one of `"json"` (default), `"html"`, or
+    #   `"xml"`.
+    # @return [String] the raw response body in the requested format.
+    #
+    # @example
+    #   AtlasRb::Work.mods("w-789", "html")
     def self.mods(id, kind = nil)
       # json default, html, xml
       connection({}).get(

data/lib/atlas_rb.rb

@@ -13,13 +13,73 @@ require_relative "atlas_rb/work"
 require_relative "atlas_rb/file_set"
 require_relative "atlas_rb/blob"
 
+# Ruby client for the Atlas API — Northeastern University's institutional
+# digital repository (the successor to Cerberus).
+#
+# ## Configuration
+#
+# Two environment variables drive every request:
+#
+# - `ATLAS_URL`   — base URL of the Atlas API (e.g. `https://atlas.example.edu`).
+# - `ATLAS_TOKEN` — bearer token sent in the `Authorization` header.
+#
+# {AtlasRb::Authentication} additionally accepts an NUID (Northeastern
+# University ID) which is forwarded in a `User: NUID <nuid>` header so the
+# server can resolve the acting user.
+#
+# ## Resource hierarchy
+#
+#     {AtlasRb::Community}  →  {AtlasRb::Collection}  →  {AtlasRb::Work}
+#                                                          ↓
+#                                                       {AtlasRb::FileSet}
+#                                                          ↓
+#                                                       {AtlasRb::Blob}
+#
+# - **Community** — top-level org unit; may nest sub-Communities.
+# - **Collection** — holds Works; lives directly under a Community.
+# - **Work** — the bibliographic unit (article, thesis, dataset…); MODS
+#   metadata is attached here.
+# - **FileSet** — classified slot under a Work that owns one Blob.
+# - **Blob** — the binary bytes themselves; supports streaming downloads
+#   via {AtlasRb::Blob.content}.
+#
+# ## Quick start
+#
+# @example End-to-end: create a Work and attach a file
+#   ENV["ATLAS_URL"]   = "https://atlas.example.edu"
+#   ENV["ATLAS_TOKEN"] = "..."
+#
+#   community  = AtlasRb::Community.create(nil, "/tmp/community-mods.xml")
+#   collection = AtlasRb::Collection.create(community["id"], "/tmp/coll-mods.xml")
+#   work       = AtlasRb::Work.create(collection["id"], "/tmp/work-mods.xml")
+#   blob       = AtlasRb::Blob.create(work["id"],
+#                                     "/tmp/upload.tmp",
+#                                     "thesis.pdf")
+#
+# @example Streaming a download
+#   File.open("out.pdf", "wb") do |f|
+#     AtlasRb::Blob.content(blob["id"]) { |chunk| f.write(chunk) }
+#   end
 module AtlasRb
+  # Generic error raised by future code paths; not currently used by any
+  # resource class. Atlas errors today surface as raw `Faraday::Response`
+  # objects or `JSON::ParserError`s on malformed bodies.
   class Error < StandardError; end
-  # Your code goes here...
 
+  # Test-environment helper that wipes Atlas state via `GET /reset`.
+  #
+  # **Do not call against production.** This exists so RSpec suites running
+  # against a disposable Atlas instance can return to a clean baseline
+  # between examples.
   class Reset
     extend AtlasRb::FaradayHelper
 
+    # Reset the connected Atlas instance to a clean state.
+    #
+    # @return [String, nil] the raw response body from `GET /reset`.
+    #
+    # @example
+    #   AtlasRb::Reset.clean
     def self.clean
       connection({}).get("/reset")&.body
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atlas_rb
 version: !ruby/object:Gem::Version
-  version: 0.0.81
+  version: 0.0.83
 platform: ruby
 authors:
 - David Cliff
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-22 00:00:00.000000000 Z
+date: 2026-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description:
 email:
 - david.g.cliff@gmail.com
@@ -77,6 +91,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".version"
+- ".yardopts"
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt