projectbranch.go

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

package stainless

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"net/url"
	"slices"

	"github.com/stainless-api/stainless-api-go/internal/apijson"
	"github.com/stainless-api/stainless-api-go/internal/apiquery"
	"github.com/stainless-api/stainless-api-go/internal/requestconfig"
	"github.com/stainless-api/stainless-api-go/option"
	"github.com/stainless-api/stainless-api-go/packages/pagination"
	"github.com/stainless-api/stainless-api-go/packages/param"
	"github.com/stainless-api/stainless-api-go/packages/respjson"
)

// ProjectBranchService contains methods and other services that help with
// interacting with the stainless API.
//
// Note, unlike clients, this service does not read variables from the environment
// automatically. You should not instantiate this service directly, and instead use
// the [NewProjectBranchService] method instead.
type ProjectBranchService struct {
	Options []option.RequestOption
}

// NewProjectBranchService generates a new service that applies the given options
// to each request. These options are applied after the parent client's options (if
// there is one), and before any request-specific options.
func NewProjectBranchService(opts ...option.RequestOption) (r ProjectBranchService) {
	r = ProjectBranchService{}
	r.Options = opts
	return
}

// Create a new branch for a project.
//
// The branch inherits the config files from the revision pointed to by the
// `branch_from` parameter. In addition, if the revision is a branch name, the
// branch will also inherit custom code changes from that branch.
func (r *ProjectBranchService) New(ctx context.Context, params ProjectBranchNewParams, opts ...option.RequestOption) (res *ProjectBranch, err error) {
	opts = slices.Concat(r.Options, opts)
	precfg, err := requestconfig.PreRequestOptions(opts...)
	if err != nil {
		return nil, err
	}
	requestconfig.UseDefaultParam(&params.Project, precfg.Project)
	if params.Project.Value == "" {
		err = errors.New("missing required project parameter")
		return nil, err
	}
	path := fmt.Sprintf("v0/projects/%s/branches", url.PathEscape(params.Project.Value))
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPost, path, params, &res, opts...)
	return res, err
}

// Retrieve a project branch by name.
func (r *ProjectBranchService) Get(ctx context.Context, branch string, query ProjectBranchGetParams, opts ...option.RequestOption) (res *ProjectBranch, err error) {
	opts = slices.Concat(r.Options, opts)
	precfg, err := requestconfig.PreRequestOptions(opts...)
	if err != nil {
		return nil, err
	}
	requestconfig.UseDefaultParam(&query.Project, precfg.Project)
	if query.Project.Value == "" {
		err = errors.New("missing required project parameter")
		return nil, err
	}
	if branch == "" {
		err = errors.New("missing required branch parameter")
		return nil, err
	}
	path := fmt.Sprintf("v0/projects/%s/branches/%s", url.PathEscape(query.Project.Value), url.PathEscape(branch))
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodGet, path, nil, &res, opts...)
	return res, err
}

// Retrieve a project branch by name.
func (r *ProjectBranchService) List(ctx context.Context, params ProjectBranchListParams, opts ...option.RequestOption) (res *pagination.Page[ProjectBranchListResponse], err error) {
	var raw *http.Response
	opts = slices.Concat(r.Options, opts)
	opts = append([]option.RequestOption{option.WithResponseInto(&raw)}, opts...)
	precfg, err := requestconfig.PreRequestOptions(opts...)
	if err != nil {
		return nil, err
	}
	requestconfig.UseDefaultParam(&params.Project, precfg.Project)
	if params.Project.Value == "" {
		err = errors.New("missing required project parameter")
		return nil, err
	}
	path := fmt.Sprintf("v0/projects/%s/branches", url.PathEscape(params.Project.Value))
	cfg, err := requestconfig.NewRequestConfig(ctx, http.MethodGet, path, params, &res, opts...)
	if err != nil {
		return nil, err
	}
	err = cfg.Execute()
	if err != nil {
		return nil, err
	}
	res.SetPageConfig(cfg, raw)
	return res, nil
}

// Retrieve a project branch by name.
func (r *ProjectBranchService) ListAutoPaging(ctx context.Context, params ProjectBranchListParams, opts ...option.RequestOption) *pagination.PageAutoPager[ProjectBranchListResponse] {
	return pagination.NewPageAutoPager(r.List(ctx, params, opts...))
}

// Delete a project branch by name.
func (r *ProjectBranchService) Delete(ctx context.Context, branch string, body ProjectBranchDeleteParams, opts ...option.RequestOption) (res *ProjectBranchDeleteResponse, err error) {
	opts = slices.Concat(r.Options, opts)
	precfg, err := requestconfig.PreRequestOptions(opts...)
	if err != nil {
		return nil, err
	}
	requestconfig.UseDefaultParam(&body.Project, precfg.Project)
	if body.Project.Value == "" {
		err = errors.New("missing required project parameter")
		return nil, err
	}
	if branch == "" {
		err = errors.New("missing required branch parameter")
		return nil, err
	}
	path := fmt.Sprintf("v0/projects/%s/branches/%s", url.PathEscape(body.Project.Value), url.PathEscape(branch))
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodDelete, path, nil, &res, opts...)
	return res, err
}

// Rebase a project branch.
//
// The branch is rebased onto the `base` branch or commit SHA, inheriting any
// config and custom code changes.
func (r *ProjectBranchService) Rebase(ctx context.Context, branch string, params ProjectBranchRebaseParams, opts ...option.RequestOption) (res *ProjectBranch, err error) {
	opts = slices.Concat(r.Options, opts)
	precfg, err := requestconfig.PreRequestOptions(opts...)
	if err != nil {
		return nil, err
	}
	requestconfig.UseDefaultParam(&params.Project, precfg.Project)
	if params.Project.Value == "" {
		err = errors.New("missing required project parameter")
		return nil, err
	}
	if branch == "" {
		err = errors.New("missing required branch parameter")
		return nil, err
	}
	path := fmt.Sprintf("v0/projects/%s/branches/%s/rebase", url.PathEscape(params.Project.Value), url.PathEscape(branch))
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPut, path, params, &res, opts...)
	return res, err
}

// Reset a project branch.
//
// If `branch` === `main`, the branch is reset to `target_config_sha`. Otherwise,
// the branch is reset to `main`.
func (r *ProjectBranchService) Reset(ctx context.Context, branch string, params ProjectBranchResetParams, opts ...option.RequestOption) (res *ProjectBranch, err error) {
	opts = slices.Concat(r.Options, opts)
	precfg, err := requestconfig.PreRequestOptions(opts...)
	if err != nil {
		return nil, err
	}
	requestconfig.UseDefaultParam(&params.Project, precfg.Project)
	if params.Project.Value == "" {
		err = errors.New("missing required project parameter")
		return nil, err
	}
	if branch == "" {
		err = errors.New("missing required branch parameter")
		return nil, err
	}
	path := fmt.Sprintf("v0/projects/%s/branches/%s/reset", url.PathEscape(params.Project.Value), url.PathEscape(branch))
	err = requestconfig.ExecuteNewRequest(ctx, http.MethodPut, path, params, &res, opts...)
	return res, err
}

// A project branch names a line of development for a project. Like a Git branch,
// it points to a Git commit with a set of config files. In addition, a project
// branch also points to a set of custom code changes, corresponding to Git
// branches in the staging repos.
type ProjectBranch struct {
	// Branch name
	Branch string `json:"branch" api:"required"`
	// A Git commit that points to the latest set of config files on a given branch.
	ConfigCommit ProjectBranchConfigCommit `json:"config_commit" api:"required"`
	LatestBuild  Build                     `json:"latest_build" api:"required"`
	// Any of "project_branch".
	Object ProjectBranchObject `json:"object" api:"required"`
	Org    string              `json:"org" api:"required"`
	// Project name
	Project string `json:"project" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Branch       respjson.Field
		ConfigCommit respjson.Field
		LatestBuild  respjson.Field
		Object       respjson.Field
		Org          respjson.Field
		Project      respjson.Field
		ExtraFields  map[string]respjson.Field
		raw          string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r ProjectBranch) RawJSON() string { return r.JSON.raw }
func (r *ProjectBranch) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// A Git commit that points to the latest set of config files on a given branch.
type ProjectBranchConfigCommit struct {
	Repo    ProjectBranchConfigCommitRepo  `json:"repo" api:"required"`
	Sha     string                         `json:"sha" api:"required"`
	Stats   ProjectBranchConfigCommitStats `json:"stats" api:"required"`
	TreeOid string                         `json:"tree_oid" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Repo        respjson.Field
		Sha         respjson.Field
		Stats       respjson.Field
		TreeOid     respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r ProjectBranchConfigCommit) RawJSON() string { return r.JSON.raw }
func (r *ProjectBranchConfigCommit) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type ProjectBranchConfigCommitRepo struct {
	Branch string `json:"branch" api:"required"`
	Host   string `json:"host" api:"required"`
	Name   string `json:"name" api:"required"`
	Owner  string `json:"owner" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Branch      respjson.Field
		Host        respjson.Field
		Name        respjson.Field
		Owner       respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r ProjectBranchConfigCommitRepo) RawJSON() string { return r.JSON.raw }
func (r *ProjectBranchConfigCommitRepo) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type ProjectBranchConfigCommitStats struct {
	Additions int64 `json:"additions" api:"required"`
	Deletions int64 `json:"deletions" api:"required"`
	Total     int64 `json:"total" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Additions   respjson.Field
		Deletions   respjson.Field
		Total       respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r ProjectBranchConfigCommitStats) RawJSON() string { return r.JSON.raw }
func (r *ProjectBranchConfigCommitStats) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type ProjectBranchObject string

const (
	ProjectBranchObjectProjectBranch ProjectBranchObject = "project_branch"
)

// A project branch names a line of development for a project. Like a Git branch,
// it points to a Git commit with a set of config files. In addition, a project
// branch also points to a set of custom code changes, corresponding to Git
// branches in the staging repos.
type ProjectBranchListResponse struct {
	// Branch name
	Branch string `json:"branch" api:"required"`
	// A Git commit that points to the latest set of config files on a given branch.
	ConfigCommit  ProjectBranchListResponseConfigCommit `json:"config_commit" api:"required"`
	LatestBuildID string                                `json:"latest_build_id" api:"required"`
	// Any of "project_branch".
	Object ProjectBranchListResponseObject `json:"object" api:"required"`
	Org    string                          `json:"org" api:"required"`
	// Project name
	Project string `json:"project" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Branch        respjson.Field
		ConfigCommit  respjson.Field
		LatestBuildID respjson.Field
		Object        respjson.Field
		Org           respjson.Field
		Project       respjson.Field
		ExtraFields   map[string]respjson.Field
		raw           string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r ProjectBranchListResponse) RawJSON() string { return r.JSON.raw }
func (r *ProjectBranchListResponse) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

// A Git commit that points to the latest set of config files on a given branch.
type ProjectBranchListResponseConfigCommit struct {
	Repo    ProjectBranchListResponseConfigCommitRepo  `json:"repo" api:"required"`
	Sha     string                                     `json:"sha" api:"required"`
	Stats   ProjectBranchListResponseConfigCommitStats `json:"stats" api:"required"`
	TreeOid string                                     `json:"tree_oid" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Repo        respjson.Field
		Sha         respjson.Field
		Stats       respjson.Field
		TreeOid     respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r ProjectBranchListResponseConfigCommit) RawJSON() string { return r.JSON.raw }
func (r *ProjectBranchListResponseConfigCommit) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type ProjectBranchListResponseConfigCommitRepo struct {
	Branch string `json:"branch" api:"required"`
	Host   string `json:"host" api:"required"`
	Name   string `json:"name" api:"required"`
	Owner  string `json:"owner" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Branch      respjson.Field
		Host        respjson.Field
		Name        respjson.Field
		Owner       respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r ProjectBranchListResponseConfigCommitRepo) RawJSON() string { return r.JSON.raw }
func (r *ProjectBranchListResponseConfigCommitRepo) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type ProjectBranchListResponseConfigCommitStats struct {
	Additions int64 `json:"additions" api:"required"`
	Deletions int64 `json:"deletions" api:"required"`
	Total     int64 `json:"total" api:"required"`
	// JSON contains metadata for fields, check presence with [respjson.Field.Valid].
	JSON struct {
		Additions   respjson.Field
		Deletions   respjson.Field
		Total       respjson.Field
		ExtraFields map[string]respjson.Field
		raw         string
	} `json:"-"`
}

// Returns the unmodified JSON received from the API
func (r ProjectBranchListResponseConfigCommitStats) RawJSON() string { return r.JSON.raw }
func (r *ProjectBranchListResponseConfigCommitStats) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type ProjectBranchListResponseObject string

const (
	ProjectBranchListResponseObjectProjectBranch ProjectBranchListResponseObject = "project_branch"
)

type ProjectBranchDeleteResponse = any

type ProjectBranchNewParams struct {
	// Use [option.WithProject] on the client to set a global default for this field.
	Project param.Opt[string] `path:"project,omitzero" api:"required" json:"-"`
	// Branch name
	Branch string `json:"branch" api:"required"`
	// Branch or commit SHA to branch from
	BranchFrom string `json:"branch_from" api:"required"`
	// Whether to throw an error if the branch already exists. Defaults to false.
	Force param.Opt[bool] `json:"force,omitzero"`
	paramObj
}

func (r ProjectBranchNewParams) MarshalJSON() (data []byte, err error) {
	type shadow ProjectBranchNewParams
	return param.MarshalObject(r, (*shadow)(&r))
}
func (r *ProjectBranchNewParams) UnmarshalJSON(data []byte) error {
	return apijson.UnmarshalRoot(data, r)
}

type ProjectBranchGetParams struct {
	// Use [option.WithProject] on the client to set a global default for this field.
	Project param.Opt[string] `path:"project,omitzero" api:"required" json:"-"`
	paramObj
}

type ProjectBranchListParams struct {
	// Use [option.WithProject] on the client to set a global default for this field.
	Project param.Opt[string] `path:"project,omitzero" api:"required" json:"-"`
	// Pagination cursor from a previous response
	Cursor param.Opt[string] `query:"cursor,omitzero" json:"-"`
	// Maximum number of items to return, defaults to 10 (maximum: 100).
	Limit param.Opt[float64] `query:"limit,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [ProjectBranchListParams]'s query parameters as
// `url.Values`.
func (r ProjectBranchListParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

type ProjectBranchDeleteParams struct {
	// Use [option.WithProject] on the client to set a global default for this field.
	Project param.Opt[string] `path:"project,omitzero" api:"required" json:"-"`
	paramObj
}

type ProjectBranchRebaseParams struct {
	// Use [option.WithProject] on the client to set a global default for this field.
	Project param.Opt[string] `path:"project,omitzero" api:"required" json:"-"`
	// The branch or commit SHA to rebase onto. Defaults to "main".
	Base param.Opt[string] `query:"base,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [ProjectBranchRebaseParams]'s query parameters as
// `url.Values`.
func (r ProjectBranchRebaseParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}

type ProjectBranchResetParams struct {
	// Use [option.WithProject] on the client to set a global default for this field.
	Project param.Opt[string] `path:"project,omitzero" api:"required" json:"-"`
	// The commit SHA to reset the main branch to. Required if resetting the main
	// branch; disallowed otherwise.
	TargetConfigSha param.Opt[string] `query:"target_config_sha,omitzero" json:"-"`
	paramObj
}

// URLQuery serializes [ProjectBranchResetParams]'s query parameters as
// `url.Values`.
func (r ProjectBranchResetParams) URLQuery() (v url.Values, err error) {
	return apiquery.MarshalWithSettings(r, apiquery.QuerySettings{
		ArrayFormat:  apiquery.ArrayQueryFormatComma,
		NestedFormat: apiquery.NestedQueryFormatBrackets,
	})
}