feat: list versions of a single cookbook and cookbook artifact (#31)

Add the two read endpoints from the Chef Server API that were unexposed:

  GET /organizations/ORG/cookbooks/NAME           -> Cookbooks.GetVersions
  GET /organizations/ORG/cookbook_artifacts/NAME  -> CookbookArtifacts.GetVersions

Both return the versions/identifiers of one named item, unwrapped from the
server's single-key {name: {url, versions}} envelope into the existing
CookbookListEntry / CookbookArtifactListEntry types. Cookbooks.GetVersions
accepts the documented num_versions filter ("" / "n" / "all").

Previously callers could only List() every cookbook or Get() one specific
version/identifier; there was no way to ask for one cookbook's version set.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tas50

README.md

@@ -28,8 +28,8 @@ following endpoint families are implemented:
 | `c.Associations`     | `/organizations/O/users`, `/association_requests`, `/users/U/...` | Members (ListMembers/GetMember/AddMember/RemoveMember), org invites (ListInvites/Invite/RescindInvite), user invites (ListUserInvites/UserInviteCount/RespondInvite) and ListUserOrgs |
 | `c.Clients`          | `/clients`                            | List / Get / Create / Update / Delete / Reregister                   |
 | `c.Containers`       | `/containers`                         | List / Get / Create / Delete                                         |
-| `c.Cookbooks`        | `/cookbooks`                          | List / Get (with metadata) / Delete / Upload (sandbox flow) / Download / ListLatest / ListRecipes |
-| `c.CookbookArtifacts`| `/cookbook_artifacts`                 | List / Get (with metadata) / Delete / Upload                         |
+| `c.Cookbooks`        | `/cookbooks`                          | List / GetVersions (one cookbook, `num_versions`) / Get (with metadata) / Delete / Upload (sandbox flow) / Download / ListLatest / ListRecipes |
+| `c.CookbookArtifacts`| `/cookbook_artifacts`                 | List / GetVersions (one artifact) / Get (with metadata) / Delete / Upload |
 | `c.DataBags`         | `/data`                               | List / Create / Delete; per-bag Items handle for CRUD                |
 | `c.Environments`     | `/environments`                       | List / Get / Create / Update / Delete / ListCookbooks / GetCookbook / CookbookVersions / ListNodes / ListRecipes / RoleRunList |
 | `c.Groups`           | `/groups`                             | List / Get / Create / Update / Delete                                |

cookbook_artifacts.go

@@ -27,6 +27,22 @@ func (s *CookbookArtifactsService) List(ctx context.Context) (map[string]Cookboo
 		s.client.orgPath("/cookbook_artifacts"), nil)
 }
 
+// GetVersions returns the available identifiers of a single cookbook artifact
+// (GET /cookbook_artifacts/NAME), unwrapped from the server's single-key
+// {name: {url, versions}} envelope.
+func (s *CookbookArtifactsService) GetVersions(ctx context.Context, name string) (*CookbookArtifactListEntry, *Response, error) {
+	m, resp, err := do[map[string]CookbookArtifactListEntry](ctx, s.client, "GET",
+		s.client.orgPath("/cookbook_artifacts/"+name), nil)
+	if err != nil {
+		return nil, resp, err
+	}
+	entry, ok := m[name]
+	if !ok {
+		return nil, resp, fmt.Errorf("cinc: cookbook artifact %q missing from response", name)
+	}
+	return &entry, resp, nil
+}
+
 // Get retrieves a single cookbook artifact by name and identifier.
 func (s *CookbookArtifactsService) Get(ctx context.Context, name, identifier string) (*Cookbook, *Response, error) {
 	cb, resp, err := do[Cookbook](ctx, s.client, "GET",

cookbook_artifacts_test.go

@@ -2,6 +2,7 @@ package cinc
 
 import (
 	"context"
+	"errors"
 	"io"
 	"net/http"
 	"os"
@@ -11,6 +12,45 @@ import (
 	"github.com/tas50/cinc-api/internal/cinctest"
 )
 
+func TestCookbookArtifacts_GetVersions(t *testing.T) {
+	t.Run("unwraps single-key envelope", func(t *testing.T) {
+		srv := cinctest.New(t)
+		srv.Handle("GET /organizations/o/cookbook_artifacts/rabbitmq", cinctest.Route{
+			Body: `{"rabbitmq":{"url":"http://x/rabbitmq","versions":[` +
+				`{"url":"http://x/rabbitmq/0bd7","identifier":"0bd7"},` +
+				`{"url":"http://x/rabbitmq/0e10","identifier":"0e10"}]}}`,
+		})
+		c := newTestClient(t, srv.Server)
+
+		entry, resp, err := c.CookbookArtifacts.GetVersions(context.Background(), "rabbitmq")
+		if err != nil {
+			t.Fatalf("GetVersions: %v", err)
+		}
+		if resp.StatusCode != 200 {
+			t.Fatalf("status = %d", resp.StatusCode)
+		}
+		if entry == nil || len(entry.Versions) != 2 || entry.Versions[0].Identifier != "0bd7" {
+			t.Fatalf("entry = %+v, want 2 identifiers", entry)
+		}
+	})
+
+	t.Run("propagates 404", func(t *testing.T) {
+		srv := cinctest.New(t)
+		srv.Handle("GET /organizations/o/cookbook_artifacts/missing", cinctest.Route{
+			Status: 404, Body: `{"error":["not found"]}`,
+		})
+		c := newTestClient(t, srv.Server)
+
+		entry, _, err := c.CookbookArtifacts.GetVersions(context.Background(), "missing")
+		if !errors.Is(err, ErrNotFound) {
+			t.Fatalf("err = %v, want ErrNotFound", err)
+		}
+		if entry != nil {
+			t.Errorf("entry = %+v, want nil on error", entry)
+		}
+	})
+}
+
 func TestCookbookArtifacts_Upload_ErrorWrapped(t *testing.T) {
 	// Build a minimal cookbook so LocalCookbookFromDir succeeds, then have the
 	// fake server fail the sandbox POST so Upload wraps the error.

cookbooks.go

@@ -6,6 +6,7 @@ import (
 	"io"
 	"io/fs"
 	"net/http"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
@@ -158,6 +159,27 @@ func (s *CookbooksService) ListRecipes(ctx context.Context) ([]string, *Response
 		s.client.orgPath("/cookbooks/_recipes"), nil)
 }
 
+// GetVersions returns the available versions of a single cookbook
+// (GET /cookbooks/NAME), unwrapped from the server's single-key
+// {name: {url, versions}} envelope. numVersions limits the versions returned
+// ("" for the server default of one, "all" for every version, or "n");
+// versions come back newest-first.
+func (s *CookbooksService) GetVersions(ctx context.Context, name, numVersions string) (*CookbookListEntry, *Response, error) {
+	path := s.client.orgPath("/cookbooks/" + name)
+	if numVersions != "" {
+		path += "?num_versions=" + url.QueryEscape(numVersions)
+	}
+	m, resp, err := do[map[string]CookbookListEntry](ctx, s.client, "GET", path, nil)
+	if err != nil {
+		return nil, resp, err
+	}
+	entry, ok := m[name]
+	if !ok {
+		return nil, resp, fmt.Errorf("cinc: cookbook %q missing from response", name)
+	}
+	return &entry, resp, nil
+}
+
 // Get retrieves a single cookbook version manifest.
 func (s *CookbooksService) Get(ctx context.Context, name, version string) (*Cookbook, *Response, error) {
 	cb, resp, err := do[Cookbook](ctx, s.client, "GET",

cookbooks_test.go

@@ -3,6 +3,7 @@ package cinc
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
@@ -15,6 +16,71 @@ import (
 	"github.com/tas50/cinc-api/internal/cinctest"
 )
 
+func TestCookbooks_GetVersions(t *testing.T) {
+	t.Run("unwraps single-key envelope and sends num_versions", func(t *testing.T) {
+		srv := cinctest.New(t)
+		var gotNumVersions string
+		srv.Handle("GET /organizations/o/cookbooks/apache2", cinctest.Route{
+			Body: `{"apache2":{"url":"http://x/apache2","versions":[` +
+				`{"url":"http://x/apache2/5.1.0","version":"5.1.0"},` +
+				`{"url":"http://x/apache2/4.2.0","version":"4.2.0"}]}}`,
+			Assert: func(t *testing.T, r *http.Request, _ []byte) {
+				gotNumVersions = r.URL.Query().Get("num_versions")
+			},
+		})
+		c := newTestClient(t, srv.Server)
+
+		entry, resp, err := c.Cookbooks.GetVersions(context.Background(), "apache2", "all")
+		if err != nil {
+			t.Fatalf("GetVersions: %v", err)
+		}
+		if resp.StatusCode != 200 {
+			t.Fatalf("status = %d", resp.StatusCode)
+		}
+		if gotNumVersions != "all" {
+			t.Errorf("num_versions = %q, want all", gotNumVersions)
+		}
+		if entry == nil || len(entry.Versions) != 2 || entry.Versions[0].Version != "5.1.0" {
+			t.Fatalf("entry = %+v, want 2 versions newest-first", entry)
+		}
+	})
+
+	t.Run("omits num_versions when empty", func(t *testing.T) {
+		srv := cinctest.New(t)
+		var hadParam bool
+		srv.Handle("GET /organizations/o/cookbooks/nginx", cinctest.Route{
+			Body: `{"nginx":{"url":"http://x/nginx","versions":[{"url":"http://x/nginx/1.0.0","version":"1.0.0"}]}}`,
+			Assert: func(t *testing.T, r *http.Request, _ []byte) {
+				_, hadParam = r.URL.Query()["num_versions"]
+			},
+		})
+		c := newTestClient(t, srv.Server)
+
+		if _, _, err := c.Cookbooks.GetVersions(context.Background(), "nginx", ""); err != nil {
+			t.Fatalf("GetVersions: %v", err)
+		}
+		if hadParam {
+			t.Error("num_versions should be absent when numVersions is empty")
+		}
+	})
+
+	t.Run("propagates 404", func(t *testing.T) {
+		srv := cinctest.New(t)
+		srv.Handle("GET /organizations/o/cookbooks/missing", cinctest.Route{
+			Status: 404, Body: `{"error":["not found"]}`,
+		})
+		c := newTestClient(t, srv.Server)
+
+		entry, _, err := c.Cookbooks.GetVersions(context.Background(), "missing", "")
+		if !errors.Is(err, ErrNotFound) {
+			t.Fatalf("err = %v, want ErrNotFound", err)
+		}
+		if entry != nil {
+			t.Errorf("entry = %+v, want nil on error", entry)
+		}
+	})
+}
+
 func TestCookbooks_GetAndList(t *testing.T) {
 	srv := cinctest.New(t)
 	srv.Handle("GET /organizations/o/cookbooks",