feat: Add strict metadata tags across mutable resources

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 45
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fhypeman-ef3a9825726e97be4c61ca3886bc1ddc04088aa179c1fbf25c73a515df604aa5.yml
-openapi_spec_hash: 349c7b6c17298c8dbdfd0750badf5608
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fhypeman-48572ed071402410249daca70dfcdd151ce9e0bf3674ccce98107ac4e0f9a800.yml
+openapi_spec_hash: 15415b3d8b119a94b7d7a71673af0237
 config_hash: 1fbc2955725b2b29a941f009ff2a2ce9

api.md

@@ -17,7 +17,7 @@ Response Types:
 Methods:
 
 - <code title="post /images">client.Images.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#ImageService.New">New</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#ImageNewParams">ImageNewParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Image">Image</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
-- <code title="get /images">client.Images.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#ImageService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Image">Image</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code title="get /images">client.Images.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#ImageService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, query <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#ImageListParams">ImageListParams</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Image">Image</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="delete /images/{name}">client.Images.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#ImageService.Delete">Delete</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, name <a href="https://pkg.go.dev/builtin#string">string</a>) <a href="https://pkg.go.dev/builtin#error">error</a></code>
 - <code title="get /images/{name}">client.Images.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#ImageService.Get">Get</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, name <a href="https://pkg.go.dev/builtin#string">string</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Image">Image</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 
@@ -91,7 +91,7 @@ Response Types:
 Methods:
 
 - <code title="post /volumes">client.Volumes.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#VolumeService.New">New</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#VolumeNewParams">VolumeNewParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Volume">Volume</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
-- <code title="get /volumes">client.Volumes.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#VolumeService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Volume">Volume</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code title="get /volumes">client.Volumes.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#VolumeService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, query <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#VolumeListParams">VolumeListParams</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Volume">Volume</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="delete /volumes/{id}">client.Volumes.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#VolumeService.Delete">Delete</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) <a href="https://pkg.go.dev/builtin#error">error</a></code>
 - <code title="post /volumes/from-archive">client.Volumes.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#VolumeService.NewFromArchive">NewFromArchive</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/builtin#io.Reader">io.Reader</a>, params <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#VolumeNewFromArchiveParams">VolumeNewFromArchiveParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Volume">Volume</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="get /volumes/{id}">client.Volumes.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#VolumeService.Get">Get</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Volume">Volume</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
@@ -108,7 +108,7 @@ Methods:
 
 - <code title="post /devices">client.Devices.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#DeviceService.New">New</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#DeviceNewParams">DeviceNewParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Device">Device</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="get /devices/{id}">client.Devices.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#DeviceService.Get">Get</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Device">Device</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
-- <code title="get /devices">client.Devices.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#DeviceService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Device">Device</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code title="get /devices">client.Devices.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#DeviceService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, query <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#DeviceListParams">DeviceListParams</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Device">Device</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="delete /devices/{id}">client.Devices.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#DeviceService.Delete">Delete</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) <a href="https://pkg.go.dev/builtin#error">error</a></code>
 - <code title="get /devices/available">client.Devices.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#DeviceService.ListAvailable">ListAvailable</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#AvailableDevice">AvailableDevice</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 
@@ -130,7 +130,7 @@ Response Types:
 Methods:
 
 - <code title="post /ingresses">client.Ingresses.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#IngressService.New">New</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#IngressNewParams">IngressNewParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Ingress">Ingress</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
-- <code title="get /ingresses">client.Ingresses.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#IngressService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Ingress">Ingress</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code title="get /ingresses">client.Ingresses.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#IngressService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, query <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#IngressListParams">IngressListParams</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Ingress">Ingress</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="delete /ingresses/{id}">client.Ingresses.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#IngressService.Delete">Delete</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) <a href="https://pkg.go.dev/builtin#error">error</a></code>
 - <code title="get /ingresses/{id}">client.Ingresses.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#IngressService.Get">Get</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Ingress">Ingress</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 
@@ -162,7 +162,7 @@ Response Types:
 Methods:
 
 - <code title="post /builds">client.Builds.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildService.New">New</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, body <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildNewParams">BuildNewParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Build">Build</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
-- <code title="get /builds">client.Builds.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Build">Build</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
+- <code title="get /builds">client.Builds.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildService.List">List</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, query <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildListParams">BuildListParams</a>) (\*[]<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Build">Build</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="delete /builds/{id}">client.Builds.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildService.Cancel">Cancel</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) <a href="https://pkg.go.dev/builtin#error">error</a></code>
 - <code title="get /builds/{id}/events">client.Builds.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildService.Events">Events</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>, query <a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildEventsParams">BuildEventsParams</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildEvent">BuildEvent</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>
 - <code title="get /builds/{id}">client.Builds.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#BuildService.Get">Get</a>(ctx <a href="https://pkg.go.dev/context">context</a>.<a href="https://pkg.go.dev/context#Context">Context</a>, id <a href="https://pkg.go.dev/builtin#string">string</a>) (\*<a href="https://pkg.go.dev/github.com/kernel/hypeman-go">hypeman</a>.<a href="https://pkg.go.dev/github.com/kernel/hypeman-go#Build">Build</a>, <a href="https://pkg.go.dev/builtin#error">error</a>)</code>

build.go

@@ -53,10 +53,10 @@ func (r *BuildService) New(ctx context.Context, body BuildNewParams, opts ...opt
 }
 
 // List builds
-func (r *BuildService) List(ctx context.Context, opts ...option.RequestOption) (res *[]Build, err error) {
+func (r *BuildService) List(ctx context.Context, query BuildListParams, opts ...option.RequestOption) (res *[]Build, err error) {
 	opts = slices.Concat(r.Options, opts)
 	path := "builds"
-	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...)
+	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, query, &res, opts...)
 	return
 }
 
@@ -128,8 +128,10 @@ type Build struct {
 	// Digest of built image (only when status is ready)
 	ImageDigest string `json:"image_digest" api:"nullable"`
 	// Full image reference (only when status is ready)
-	ImageRef   string          `json:"image_ref" api:"nullable"`
-	Provenance BuildProvenance `json:"provenance"`
+	ImageRef string `json:"image_ref" api:"nullable"`
+	// User-defined key-value metadata tags.
+	Metadata   map[string]string `json:"metadata"`
+	Provenance BuildProvenance   `json:"provenance"`
 	// Position in build queue (only when status is queued)
 	QueuePosition int64 `json:"queue_position" api:"nullable"`
 	// Build start timestamp
@@ -145,6 +147,7 @@ type Build struct {
 		Error             respjson.Field
 		ImageDigest       respjson.Field
 		ImageRef          respjson.Field
+		Metadata          respjson.Field
 		Provenance        respjson.Field
 		QueuePosition     respjson.Field
 		StartedAt         respjson.Field
@@ -262,6 +265,8 @@ type BuildNewParams struct {
 	IsAdminBuild param.Opt[string] `json:"is_admin_build,omitzero"`
 	// Memory limit for builder VM in MB (default 2048)
 	MemoryMB param.Opt[int64] `json:"memory_mb,omitzero"`
+	// JSON object of metadata tags. Example: {"team":"backend","env":"staging"}
+	Metadata param.Opt[string] `json:"metadata,omitzero"`
 	// JSON array of secret references to inject during build. Each object has "id"
 	// (required) for use with --mount=type=secret,id=... Example: [{"id":
 	// "npm_token"}, {"id": "github_token"}]
@@ -289,6 +294,20 @@ func (r BuildNewParams) MarshalMultipart() (data []byte, contentType string, err
 	return buf.Bytes(), writer.FormDataContentType(), nil
 }
 
+type BuildListParams struct {
+	// Filter builds by metadata key-value pairs.
+	Metadata map[string]string `query:"metadata,omitzero" json:"-"`
+	paramObj
+}
+
+// URLQuery serializes [BuildListParams]'s query parameters as `url.Values`.
+func (r BuildListParams) URLQuery() (v url.Values, err error) {
+	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
+		ArrayFormat:  apiquery.ArrayQueryFormatComma,
+		NestedFormat: apiquery.NestedQueryFormatBrackets,
+	})
+}
+
 type BuildEventsParams struct {
 	// Continue streaming new events after initial output
 	Follow param.Opt[bool] `query:"follow,omitzero" json:"-"`

build_test.go

@@ -38,6 +38,7 @@ func TestBuildNewWithOptionalParams(t *testing.T) {
 		ImageName:       hypeman.String("image_name"),
 		IsAdminBuild:    hypeman.String("is_admin_build"),
 		MemoryMB:        hypeman.Int(0),
+		Metadata:        hypeman.String("metadata"),
 		Secrets:         hypeman.String("secrets"),
 		TimeoutSeconds:  hypeman.Int(0),
 	})
@@ -50,7 +51,7 @@ func TestBuildNewWithOptionalParams(t *testing.T) {
 	}
 }
 
-func TestBuildList(t *testing.T) {
+func TestBuildListWithOptionalParams(t *testing.T) {
 	t.Skip("Mock server tests are disabled")
 	baseURL := "http://localhost:4010"
 	if envURL, ok := os.LookupEnv("TEST_API_BASE_URL"); ok {
@@ -63,7 +64,12 @@ func TestBuildList(t *testing.T) {
 		option.WithBaseURL(baseURL),
 		option.WithAPIKey("My API Key"),
 	)
-	_, err := client.Builds.List(context.TODO())
+	_, err := client.Builds.List(context.TODO(), hypeman.BuildListParams{
+		Metadata: map[string]string{
+			"team": "backend",
+			"env":  "staging",
+		},
+	})
 	if err != nil {
 		var apierr *hypeman.Error
 		if errors.As(err, &apierr) {