api

package
v0.11.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 23, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultBaseURL is the production Entire API origin.
	DefaultBaseURL = "https://entire.io"

	// DefaultAuthBaseURL is the production Entire login server — the
	// default for `entire login --server`.
	//
	// This apex host is a dispatcher, not a token issuer: it redirects
	// /authorize and /device_authorization to the caller's regional login
	// server (e.g. https://us.auth.entire.io) and serves no token endpoint,
	// no discovery document, and no JWKS. Tokens are always minted by a
	// region, with iss and aud set to that region's host — which is what
	// gets persisted as a context's CoreURL and is the target of every
	// later refresh and RFC 8693 exchange.
	DefaultAuthBaseURL = "https://auth.entire.io"

	// BaseURLEnvVar overrides the Entire API origin for local development.
	BaseURLEnvVar = "ENTIRE_API_BASE_URL"

	// AuthBaseURLEnvVar is the retired auth-origin override. Nothing reads
	// its value — RejectRemovedAuthEnv fails every command when it is set,
	// pointing at `entire login --server`.
	AuthBaseURLEnvVar = "ENTIRE_AUTH_BASE_URL"
)

Variables

View Source 
var ErrInsecureHTTP = errors.New("refusing to use insecure http:// base URL for authentication (use --insecure-http-auth to override)")

ErrInsecureHTTP is returned when the base URL uses HTTP without an explicit opt-in.

Functions

func BaseURL 

func BaseURL() string

BaseURL returns the effective Entire API base URL. ENTIRE_API_BASE_URL takes precedence over the production default.

func BaseURLOverride added in v0.11.0 

func BaseURLOverride() (string, bool)

BaseURLOverride returns the normalized ENTIRE_API_BASE_URL and true when the user pointed the CLI at an explicit data host, or ("", false) when BaseURL() would fall back to the production default. See auth.resolveCellClientSubject for a caller that must tell the two apart.

func CheckResponse added in v0.5.2 

func CheckResponse(resp *http.Response) error

CheckResponse returns an error if the response status code indicates failure. For non-2xx responses, it reads and parses the error message from the body and returns it as an *HTTPError. The caller is responsible for closing resp.Body.

func DecodeJSON added in v0.5.2 

func DecodeJSON(resp *http.Response, dest any) error

DecodeJSON reads the response body and decodes it into dest. It limits the body size to protect against unbounded reads. The caller is responsible for closing resp.Body.

func IsHTTPErrorStatus added in v0.6.0 

func IsHTTPErrorStatus(err error, status int) bool

IsHTTPErrorStatus reports whether err wraps an *HTTPError with the given HTTP status.

func NormalizeOriginURL added in v0.6.3 

func NormalizeOriginURL(raw string) string

NormalizeOriginURL canonicalises an origin URL the same way auth-go's tokenmanager does internally: lowercase scheme/host, default port stripped (80 for http, 443 for https), path/query/fragment dropped, trailing slash collapsed. On parse failure, raw is returned unchanged so non-URL audience values still compare byte-for-byte.

Mirrors auth-go's internal/oauthhttp.NormalizeOriginURL so the value the CLI hands to the manager as Issuer survives the manager's own normalisation pass byte-for-byte; a cosmetically-different origin (uppercase host, explicit :443, trailing slash) would otherwise be keyed under a different keyring slot than the manager later reads.

func OriginOnly added in v0.6.3 

func OriginOnly(raw string) string

OriginOnly is a backwards-compatible alias for NormalizeOriginURL. Callers reading raw URLs (e.g. ENTIRE_API_BASE_URL) and feeding them into tokenmanager.TokenRequest.Resource use this to strip path/query/fragment before the lib's stricter origin-only validator runs.

func RejectRemovedAuthEnv added in v0.7.6 

func RejectRemovedAuthEnv() error

RejectRemovedAuthEnv returns an error when ENTIRE_AUTH_BASE_URL is set at all (even empty). The variable is retired in favour of `entire login --server`; failing loudly beats silently ignoring an override the operator believes is in effect.

func RequireSecureURL 

func RequireSecureURL(baseURL string) error

RequireSecureURL returns ErrInsecureHTTP if the base URL uses the http scheme. Call this before making authenticated requests unless --insecure-http-auth is set.

func ResolveURLFromBase 

func ResolveURLFromBase(baseURL, path string) (string, error)

ResolveURLFromBase joins an API-relative path against an explicit base URL. Only http and https schemes are accepted.

Types

type AuthSession added in v0.7.4 

type AuthSession struct {
	ID     string `json:"id"`
	UserID string `json:"user_id"`
	Name   string `json:"name"`
	// Scope is "cli", "web" or "system"; ClientID is the raw OAuth client.
	Scope      string  `json:"scope"`
	ClientID   string  `json:"client_id"`
	ExpiresAt  string  `json:"expires_at"`
	LastUsedAt *string `json:"last_used_at"`
	CreatedAt  string  `json:"created_at"`
}

AuthSession is a single active login session — an OAuth refresh-token family — returned by entire-core's session endpoint. One is created per `entire login`, across all of a user's devices. Plaintext token values are never returned by the server, only metadata. (The list envelope's wire key is "tokens"; the rows are sessions.)

type AuthSessionsResponse added in v0.7.4 

type AuthSessionsResponse struct {
	Sessions []AuthSession `json:"tokens"`
}

AuthSessionsResponse is the envelope returned by the list endpoint.

type Client added in v0.5.2 

type Client struct {
	// contains filtered or unexported fields
}

Client is an authenticated HTTP client for the Entire API. It attaches the bearer token to all outgoing requests via the Authorization header.

func NewClientWithBaseURL added in v0.6.3 

func NewClientWithBaseURL(token, baseURL string) *Client

NewClientWithBaseURL creates a new authenticated API client targeting an explicit base URL.

This is the only constructor on purpose. Its predecessor, NewClient(token), defaulted the host to BaseURL() — ENTIRE_API_BASE_URL or the production apex — which is exactly the ambient default the data plane no longer has: the host belongs to the acting login and comes from auth.ResolveDataAPI / auth.DataBaseURL. Keeping a one-argument constructor around would let the next caller reintroduce that silently, sending a staging login's bearer to entire.io, so the base URL is a required argument and every caller has to say where it got it.

func (*Client) Delete added in v0.5.2 

func (c *Client) Delete(ctx context.Context, path string) (*http.Response, error)

Delete sends an authenticated DELETE request to the given API-relative path.

func (*Client) Get added in v0.5.2 

func (c *Client) Get(ctx context.Context, path string) (*http.Response, error)

Get sends an authenticated GET request to the given API-relative path.

func (*Client) GetStream added in v0.6.2 

func (c *Client) GetStream(ctx context.Context, path string, headers http.Header) (*http.Response, error)

GetStream sends an authenticated GET request with optional extra request headers (e.g. Accept: text/event-stream, Last-Event-ID) and returns the response with the body still open. Callers are responsible for reading and closing resp.Body. Intended for streaming endpoints such as Server-Sent Events; for normal JSON requests use Get.

func (*Client) ListAuthSessions added in v0.7.4 

func (c *Client) ListAuthSessions(ctx context.Context) ([]AuthSession, error)

ListAuthSessions returns the authenticated user's active login sessions.

func (*Client) ListRepositories added in v0.5.6 

func (c *Client) ListRepositories(ctx context.Context, sort RepositorySort) ([]Repository, error)

ListRepositories lists the authenticated user's repositories. An empty sort uses the server default.

func (*Client) Patch added in v0.5.2 

func (c *Client) Patch(ctx context.Context, path string, body any) (*http.Response, error)

Patch sends an authenticated PATCH request with a JSON body to the given API-relative path.

func (*Client) Post added in v0.5.2 

func (c *Client) Post(ctx context.Context, path string, body any) (*http.Response, error)

Post sends an authenticated POST request with a JSON body to the given API-relative path.

func (*Client) Put added in v0.5.2 

func (c *Client) Put(ctx context.Context, path string, body any) (*http.Response, error)

Put sends an authenticated PUT request with a JSON body to the given API-relative path.

func (*Client) ReportEnable added in v0.7.6 

func (c *Client) ReportEnable(ctx context.Context, remoteURL string) (*EnableRepoResponse, error)

ReportEnable records that the authenticated user ran `entire enable` for the repo identified by remoteURL, and returns whether the App can reach it.

func (*Client) Request added in v0.8.0 

func (c *Client) Request(ctx context.Context, method, path string, headers http.Header, body io.Reader) (*http.Response, error)

Request sends an authenticated request with an explicit method, optional extra headers, and an optional raw body. It's the general-purpose escape hatch behind `entire api`; prefer the typed verbs (Get/Post/…) for normal use. The bearer, User-Agent, and default Accept are still attached by the transport; a body defaults to Content-Type: application/json unless the caller supplies its own via headers.

func (*Client) RevokeAllAuthSessions added in v0.11.0 

func (c *Client) RevokeAllAuthSessions(ctx context.Context) error

RevokeAllAuthSessions revokes every session of the authenticated user, browser and web included (DELETE on the collection with scope=all). A login server that predates the endpoint answers 404 or 405; callers fall back to list + revoke by id.

func (*Client) RevokeAuthSession added in v0.7.4 

func (c *Client) RevokeAuthSession(ctx context.Context, id string) error

RevokeAuthSession revokes the login session with the given id.

func (*Client) RevokeCLIAuthSessions added in v0.11.0 

func (c *Client) RevokeCLIAuthSessions(ctx context.Context) error

RevokeCLIAuthSessions revokes every CLI login session of the authenticated user, on every machine, in one call (DELETE on the collection). Browser and web sessions stay. A login server that predates the endpoint answers 404 or 405.

func (*Client) RevokeCurrentAuthSession added in v0.7.4 

func (c *Client) RevokeCurrentAuthSession(ctx context.Context) error

RevokeCurrentAuthSession revokes the login session this client is authenticating with (the family the current bearer belongs to).

func (*Client) SetTrailRoute added in v0.10.1 

func (c *Client) SetTrailRoute(trailID, path string)

SetTrailRoute registers the entire-api base path for a resolved trail, so later requests spelled with the trail's ID are rewritten onto its forge/owner/repo/number route (see rewriteTrailRoute).

func (*Client) TrailsEnabled added in v0.7.7 

func (c *Client) TrailsEnabled(ctx context.Context, forge, owner, repo string) (bool, error)

TrailsEnabled probes trail availability: 2xx=true, 403/404/410=false, everything else ambiguous.

func (*Client) WithAuthSessionsPath added in v0.7.4 

func (c *Client) WithAuthSessionsPath(path string) *Client

WithAuthSessionsPath sets the base path used by ListAuthSessions, RevokeCurrentAuthSession, and RevokeAuthSession. Returns the receiver for chaining at construction: 

c := api.NewClientWithBaseURL(token, base).WithAuthSessionsPath(p)

type EnableRepoRequest added in v0.7.6 

type EnableRepoRequest struct {
	RemoteURL string `json:"remote_url"`
}

EnableRepoRequest is the body of POST /api/v1/cli/enable. RemoteURL is a clean, credential-free remote URL (the CLI strips any embedded credentials and query params before sending — see reportRepoEnabled); the server resolves it to a repo on its end.

type EnableRepoResponse added in v0.7.6 

type EnableRepoResponse struct {
	Connected  bool   `json:"connected"`
	InstallURL string `json:"install_url,omitempty"`
	Repo       *struct {
		FullName string `json:"full_name"`
		GitHubID int64  `json:"github_id"`
		Private  bool   `json:"private"`
	} `json:"repo,omitempty"`
}

EnableRepoResponse is the result of recording an `entire enable`. Connected reports whether the GitHub App can currently reach the repo; when it can't, InstallURL points at the App installation page.

The CLI deliberately ignores these fields today: reporting is best-effort and the "install the GitHub App" nudge is surfaced by the web onboarding, not the CLI. They are decoded for the API contract and potential future use.

type ErrorResponse added in v0.5.2 

type ErrorResponse struct {
	Error     any    `json:"error"`
	Detail    string `json:"detail"`
	Title     string `json:"title"`
	Code      string `json:"code"`
	RequestID string `json:"request_id"`
}

ErrorResponse represents a standard API error response. Older endpoints return {"error":"message"}; newer endpoints return {"error":{"code":"...","message":"...",...}}; entire-api cells return RFC 9457 problem details (application/problem+json), whose human-readable text is detail with title as the coarser fallback. RequestID is a problem-details extension entire-api sets on every error; it is what support needs to find the server-side trace, so it is carried through to HTTPError.

func (ErrorResponse) ErrorCode added in v0.11.1 

func (e ErrorResponse) ErrorCode() string

ErrorCode extracts the stable machine-readable code, if the server sent one. entire-api's contract (docs/api-errors.md there) is to branch on code, never on message text: problem details and compact cell errors carry it top-level; the legacy nested envelope carries it as error.code.

func (ErrorResponse) Message added in v0.6.3 

func (e ErrorResponse) Message() string

Message extracts the human-readable error message from any envelope shape.

type HTTPError added in v0.6.0 

type HTTPError struct {
	StatusCode int
	Message    string
	// Code is the server's stable error code (e.g. rate_limited, conflict,
	// wrong_cell) when it sent one. Branch on it, not on Message, which is
	// human-readable prose the server may reword.
	Code string
	// RequestID is the RFC 9457 request_id extension when the server sent one.
	RequestID string
}

HTTPError is returned by CheckResponse for non-2xx responses. Callers can use errors.As to inspect the HTTP status, or IsHTTPErrorStatus for a quick check.

func (*HTTPError) Error added in v0.6.0 

func (e *HTTPError) Error() string

type RepositoriesResponse added in v0.5.6 

type RepositoriesResponse struct {
	Repositories []Repository `json:"repositories"`
}

RepositoriesResponse is the envelope returned by GET /api/v1/repositories.

type Repository added in v0.5.6 

type Repository struct {
	FullName        string `json:"full_name"`
	CheckpointCount int    `json:"checkpoint_count"`
}

Repository is a single entry returned by GET /api/v1/repositories. Only fields currently consumed by callers are decoded; extras are ignored.

type RepositorySort added in v0.5.6 

type RepositorySort string
const (
	RepositorySortRecent RepositorySort = "recent"
	RepositorySortName   RepositorySort = "name"
)

type TrailApproval added in v0.9.0 

type TrailApproval struct {
	ID        string    `json:"id"`
	Author    string    `json:"author"`
	Event     string    `json:"event"`
	Body      string    `json:"body,omitempty"`
	CommitSHA string    `json:"commit_sha,omitempty"`
	CreatedAt time.Time `json:"created_at"`
}

TrailApproval is a single approval decision on a trail. Author is exposed as a login string while UnmarshalJSON accepts both shapes entire-api itself uses: the approvals collection sends a bare login string, the trail resource sends an {id,login} object. Both are live — this is not legacy tolerance.

func (*TrailApproval) UnmarshalJSON added in v0.10.1 

func (a *TrailApproval) UnmarshalJSON(data []byte) error

type TrailApprovalRequest added in v0.9.0 

type TrailApprovalRequest struct {
	Event string `json:"event"`
	Body  string `json:"body,omitempty"`
}

type TrailApprovalResponse added in v0.9.0 

type TrailApprovalResponse struct {
	OK       bool          `json:"ok"`
	Approval TrailApproval `json:"approval"`
}

type TrailApprovalsResponse added in v0.9.0 

type TrailApprovalsResponse struct {
	Approvals []TrailApproval `json:"approvals"`
}

type TrailBodyDocument added in v0.7.8 

type TrailBodyDocument struct {
	TextSnapshot string `json:"text_snapshot"`
	ETag         string `json:"etag,omitempty"`
}

TrailBodyDocument is the trail's description editor document. TextSnapshot is the rendered plain text displayed by the CLI. The document is also what a body write returns (see TrailBodyRequest), so both directions decode into this type; the fields the CLI does not use (id, document_key, schema_version, content_json, updated_at) are simply left out of it. ETag is populated on a read as well as on a write response, and is what makes If-Match viable on the next write (see sendTrailBody).

type TrailBodyRequest added in v0.10.2 

type TrailBodyRequest struct {
	Markdown  string `json:"markdown"`
	Overwrite bool   `json:"overwrite,omitempty"`
}

TrailBodyRequest is the body for PUT /api/v1/trails/:host/:owner/:repo/:number/body, the only route that writes a trail's description (see TrailUpdateRequest for why it is not PATCH). The route answers with the resulting document, which decodes into TrailBodyDocument.

Markdown carries no omitempty: an empty string is how a description is cleared, and the server distinguishes present-and-empty from absent — with omitempty the field would vanish from the JSON and the request would be rejected as "exactly one of markdown/content_json is required".

The route also accepts content_json (ProseMirror JSON, written as-is) in place of markdown; the CLI only ever writes Markdown, so content_json is not modeled here. The route also accepts an If-Match header for optimistic concurrency, populated from a prior read of TrailBodyDocument.ETag — see sendTrailBody for the dispatch between If-Match and Overwrite.

type TrailCreateRequest added in v0.5.2 

type TrailCreateRequest struct {
	Title        string   `json:"title"`
	Body         string   `json:"body,omitempty"`
	BranchName   string   `json:"branch_name,omitempty"`
	BranchAction string   `json:"branch_action,omitempty"`
	Base         string   `json:"base,omitempty"`
	Status       string   `json:"status,omitempty"`
	Assignees    []string `json:"assignees,omitempty"`
	Priority     string   `json:"priority,omitempty"`
	Type         string   `json:"type,omitempty"`
}

TrailCreateRequest is the body for POST /api/v1/trails/:host/:owner/:repo.

type TrailCreateResponse added in v0.5.2 

type TrailCreateResponse struct {
	Trail TrailResource `json:"trail"`
}

type TrailDiscussionCreateRequest added in v0.11.1 

type TrailDiscussionCreateRequest struct {
	Title string `json:"title,omitempty"`
	Body  string `json:"body"`
}

TrailDiscussionCreateRequest is the body for POST .../:number/discussions. Body is required; Title is optional (server defaults it to "Conversation").

type TrailDiscussionCreateResponse added in v0.11.1 

type TrailDiscussionCreateResponse struct {
	Discussion TrailDiscussionSummary  `json:"discussion"`
	Message    *TrailDiscussionMessage `json:"message"`
}

TrailDiscussionCreateResponse is the response from POST .../:number/discussions.

type TrailDiscussionDetailResponse added in v0.11.1 

type TrailDiscussionDetailResponse struct {
	Discussion  TrailDiscussionSummary   `json:"discussion"`
	Messages    []TrailDiscussionMessage `json:"messages"`
	EventCursor string                   `json:"event_cursor"`
}

TrailDiscussionDetailResponse is the response from GET .../:number/discussions/:id.

type TrailDiscussionMessage added in v0.11.1 

type TrailDiscussionMessage struct {
	ID        string                 `json:"id"`
	Author    string                 `json:"author"` // GitHub login
	CreatedAt time.Time              `json:"created_at"`
	Body      string                 `json:"body"`
	Replies   []TrailDiscussionReply `json:"replies"`
}

TrailDiscussionMessage is a top-level message in a discussion.

type TrailDiscussionMessageRequest added in v0.11.1 

type TrailDiscussionMessageRequest struct {
	Body string `json:"body"`
}

TrailDiscussionMessageRequest is the body for POST/PATCH message endpoints.

type TrailDiscussionMessageResponse added in v0.11.1 

type TrailDiscussionMessageResponse struct {
	Message TrailDiscussionMessage `json:"message"`
}

TrailDiscussionMessageResponse is the response from the message endpoints.

type TrailDiscussionParticipant added in v0.11.1 

type TrailDiscussionParticipant struct {
	Login string `json:"login"`
}

TrailDiscussionParticipant identifies a discussion participant by login.

type TrailDiscussionReply added in v0.11.1 

type TrailDiscussionReply struct {
	ID        string    `json:"id"`
	Author    string    `json:"author"` // GitHub login
	CreatedAt time.Time `json:"created_at"`
	Body      string    `json:"body"`
}

TrailDiscussionReply is a reply on a discussion message. Replies do not nest further.

type TrailDiscussionSummary added in v0.11.1 

type TrailDiscussionSummary struct {
	ID                string                       `json:"id"`
	TrailID           string                       `json:"trail_id"`
	Kind              string                       `json:"kind"` // "discussion" | "code_review"
	Title             string                       `json:"title"`
	ReviewCommentID   *string                      `json:"review_comment_id"`
	Resolved          bool                         `json:"resolved"`
	ResolvedBy        *string                      `json:"resolved_by"` // actor UUID
	ResolvedAt        *time.Time                   `json:"resolved_at"`
	CreatedBy         *string                      `json:"created_by"` // actor UUID
	CreatedAt         time.Time                    `json:"created_at"`
	UpdatedAt         time.Time                    `json:"updated_at"`
	LastMessageAt     *time.Time                   `json:"last_message_at"`
	LastMessageAuthor *string                      `json:"last_message_author"` // GitHub login
	MessageCount      int                          `json:"message_count"`
	Participants      []TrailDiscussionParticipant `json:"participants"`
}

TrailDiscussionSummary is a discussion's metadata. The server's review_comment blob (present only for kind=="code_review") is intentionally not decoded here: code-review discussions are surfaced through `trail finding`.

type TrailDiscussionUpdateRequest added in v0.11.1 

type TrailDiscussionUpdateRequest struct {
	Title    *string `json:"title,omitempty"`
	Resolved *bool   `json:"resolved,omitempty"`
}

TrailDiscussionUpdateRequest is the body for PATCH .../:number/discussions/:id. Pointer fields distinguish "not provided" from an explicit value.

type TrailDiscussionUpdateResponse added in v0.11.1 

type TrailDiscussionUpdateResponse struct {
	Discussion TrailDiscussionSummary `json:"discussion"`
}

TrailDiscussionUpdateResponse is the response from PATCH .../:number/discussions/:id.

type TrailDiscussionsResponse added in v0.11.1 

type TrailDiscussionsResponse struct {
	Items       []TrailDiscussionSummary `json:"items"`
	NextCursor  *string                  `json:"next_cursor,omitempty"`
	EventCursor string                   `json:"event_cursor"`
}

TrailDiscussionsResponse is the response from GET .../:number/discussions.

type TrailListResponse added in v0.5.2 

type TrailListResponse struct {
	Trails     []TrailResource `json:"items"`
	Total      int             `json:"total_count"`
	NextCursor *string         `json:"next_cursor"`
}

TrailListResponse is the response from entire-api's trail list endpoint.

type TrailResource added in v0.5.2 

type TrailResource struct {
	ID                 string             `json:"id,omitempty"`
	Number             int                `json:"number,omitempty"`
	URL                string             `json:"url,omitempty"`
	Branch             string             `json:"branch"`
	OriginalBranch     string             `json:"original_branch,omitempty"`
	Base               string             `json:"base"`
	Title              string             `json:"title"`
	Body               string             `json:"body,omitempty"`
	Status             string             `json:"status"`
	Phase              string             `json:"phase,omitempty"`
	Author             *trail.Author      `json:"author"`
	Assignees          []string           `json:"assignees"`
	Labels             []string           `json:"labels,omitempty"`
	Priority           string             `json:"priority,omitempty"`
	Type               string             `json:"type,omitempty"`
	Reviewers          []trail.Reviewer   `json:"reviewers,omitempty"`
	RequestedReviewers []string           `json:"requested_reviewers,omitempty"`
	CreatedAt          time.Time          `json:"created_at"`
	UpdatedAt          time.Time          `json:"updated_at"`
	MergedAt           *time.Time         `json:"merged_at,omitempty"`
	CommentCount       int                `json:"comment_count,omitempty"`
	UnresolvedCount    int                `json:"unresolved_count,omitempty"`
	CheckpointCount    int                `json:"checkpoint_count,omitempty"`
	CommitsAhead       int                `json:"commits_ahead,omitempty"`
	BodyDocument       *TrailBodyDocument `json:"body_document,omitempty"`
}

TrailResource represents a trail returned by entire-api. The backend uses snake_case and nullable branch fields. Branch is empty when the trail is currently unlinked; OriginalBranch separately preserves its last link.

func (*TrailResource) ToMetadata added in v0.5.2 

func (r *TrailResource) ToMetadata() *trail.Metadata

ToMetadata converts a TrailResource to display metadata.

type TrailReview added in v0.7.6 

type TrailReview struct {
	ID            string    `json:"id"`
	TrailID       string    `json:"trail_id"`
	CodeVersionID string    `json:"code_version_id"`
	ActorID       string    `json:"actor_id"`
	Summary       *string   `json:"summary"`
	StartedAt     time.Time `json:"started_at"`
}

TrailReview represents a review session.

type TrailReviewCodeVersion added in v0.7.6 

type TrailReviewCodeVersion struct {
	ID           string    `json:"id"`
	TrailID      string    `json:"trail_id"`
	RepositoryID string    `json:"repo_id"`
	BaseRef      *string   `json:"base_ref"`
	HeadRef      *string   `json:"head_ref"`
	BaseSHA      *string   `json:"base_sha"`
	HeadSHA      *string   `json:"head_sha"`
	CapturedAt   time.Time `json:"captured_at"`
}

TrailReviewCodeVersion pins the base/head that a review covers.

type TrailReviewComment added in v0.7.6 

type TrailReviewComment struct {
	ID                        string                       `json:"id"`
	TrailID                   string                       `json:"trail_id"`
	RepositoryID              string                       `json:"repo_id"`
	ReviewID                  string                       `json:"review_id"`
	CodeVersionID             string                       `json:"code_version_id"`
	ActorID                   string                       `json:"actor_id"`
	Title                     *string                      `json:"title"`
	Body                      *string                      `json:"body"`
	Severity                  *string                      `json:"severity"`
	Confidence                *float64                     `json:"confidence"`
	Status                    string                       `json:"status"`
	StatusReason              *string                      `json:"status_reason"`
	StaleOutcome              string                       `json:"stale_outcome"`
	StaleCheckedAt            *time.Time                   `json:"stale_checked_at"`
	StaleCheckedCodeVersionID *string                      `json:"stale_checked_code_version_id"`
	ClientID                  *string                      `json:"client_id"`
	ClientIDHash              *string                      `json:"client_id_hash"`
	CreatedAt                 time.Time                    `json:"created_at"`
	UpdatedAt                 time.Time                    `json:"updated_at"`
	Location                  TrailReviewLocation          `json:"location"`
	SuggestedChanges          []TrailReviewSuggestedChange `json:"suggested_changes,omitempty"`
	DiscussionID              *string                      `json:"discussion_id,omitempty"`
	DiscussionMessageCount    int                          `json:"discussion_message_count,omitempty"`
	OutgoingLinks             []TrailReviewOutgoingLink    `json:"outgoing_links,omitempty"`
}

TrailReviewComment is a single agent-native review finding.

type TrailReviewCommentBatchError added in v0.7.6 

type TrailReviewCommentBatchError struct {
	Code      string  `json:"code"`
	Message   string  `json:"message"`
	Field     *string `json:"field"`
	Retryable bool    `json:"retryable"`
}

TrailReviewCommentBatchError describes why a single finding in a batch failed.

type TrailReviewCommentBatchRequest added in v0.7.6 

type TrailReviewCommentBatchRequest struct {
	Comments []TrailReviewCommentInput `json:"comments"`
}

TrailReviewCommentBatchRequest posts a batch of findings to a review via POST /api/v1/trails/{trail_id}/reviews/{id}/comments. The API requires at least one comment and rejects batches larger than the review's max_comments_per_batch limit.

type TrailReviewCommentBatchResponse added in v0.7.6 

type TrailReviewCommentBatchResponse struct {
	Results []TrailReviewCommentBatchResult `json:"results"`
}

TrailReviewCommentBatchResponse is returned by the batch comment endpoint.

type TrailReviewCommentBatchResult added in v0.7.6 

type TrailReviewCommentBatchResult struct {
	ClientID        string                        `json:"client_id"`
	Status          string                        `json:"status"`
	Comment         *TrailReviewComment           `json:"comment,omitempty"`
	SuggestedChange *TrailReviewSuggestedChange   `json:"suggested_change,omitempty"`
	Error           *TrailReviewCommentBatchError `json:"error,omitempty"`
}

TrailReviewCommentBatchResult reports the per-finding outcome of a batch. Status is one of "created", "existing", or "error"; Comment is populated for the first two, Error for the last.

type TrailReviewCommentInput added in v0.7.6 

type TrailReviewCommentInput struct {
	ClientID        string                                   `json:"client_id"`
	Body            *string                                  `json:"body,omitempty"`
	Severity        *string                                  `json:"severity,omitempty"`
	Confidence      *float64                                 `json:"confidence,omitempty"`
	Status          *string                                  `json:"status,omitempty"`
	StatusReason    *string                                  `json:"status_reason,omitempty"`
	Location        TrailReviewLocationCreateRequest         `json:"location"`
	SuggestedChange *TrailReviewSuggestedChangeCreateRequest `json:"suggested_change,omitempty"`
}

TrailReviewCommentInput is a single finding within a batch create request. client_id (an idempotency key) and location are required by the API.

type TrailReviewCommentPatchRequest added in v0.7.6 

type TrailReviewCommentPatchRequest struct {
	Title        *string  `json:"title,omitempty"`
	Body         *string  `json:"body,omitempty"`
	Severity     *string  `json:"severity,omitempty"`
	Confidence   *float64 `json:"confidence,omitempty"`
	Status       string   `json:"status,omitempty"`
	StatusReason *string  `json:"status_reason,omitempty"`
}

TrailReviewCommentPatchRequest updates a review finding.

type TrailReviewCommentsResponse added in v0.7.6 

type TrailReviewCommentsResponse struct {
	Comments    []TrailReviewComment `json:"comments"`
	NextCursor  *string              `json:"next_cursor,omitempty"`
	EventCursor string               `json:"event_cursor,omitempty"`
}

TrailReviewCommentsResponse is returned by trail/review comment list endpoints.

type TrailReviewCounts added in v0.7.6 

type TrailReviewCounts struct {
	Open      int `json:"open"`
	Resolved  int `json:"resolved"`
	Dismissed int `json:"dismissed"`
	Stale     int `json:"stale"`
	Total     int `json:"total"`
}

TrailReviewCounts are review-scoped comment counts.

type TrailReviewLimits added in v0.7.6 

type TrailReviewLimits struct {
	MaxCommentsPerBatch int `json:"max_comments_per_batch"`
}

TrailReviewLimits carries the server-enforced batch limits for a review.

type TrailReviewLocation added in v0.7.6 

type TrailReviewLocation struct {
	ID              string  `json:"id"`
	ReviewCommentID string  `json:"review_comment_id"`
	CodeVersionID   string  `json:"code_version_id"`
	Granularity     string  `json:"granularity"`
	FilePath        *string `json:"file_path"`
	StartLine       *int    `json:"start_line"`
	StartColumn     *int    `json:"start_column"`
	EndLine         *int    `json:"end_line"`
	EndColumn       *int    `json:"end_column"`
	SelectedText    *string `json:"selected_text"`
	NearbyText      *string `json:"nearby_text"`
	Language        *string `json:"language"`
}

TrailReviewLocation identifies where a finding applies.

type TrailReviewLocationCreateRequest added in v0.7.6 

type TrailReviewLocationCreateRequest struct {
	Granularity  string  `json:"granularity"`
	FilePath     *string `json:"file_path,omitempty"`
	StartLine    *int    `json:"start_line,omitempty"`
	StartColumn  *int    `json:"start_column,omitempty"`
	EndLine      *int    `json:"end_line,omitempty"`
	EndColumn    *int    `json:"end_column,omitempty"`
	SelectedText *string `json:"selected_text,omitempty"`
	NearbyText   *string `json:"nearby_text,omitempty"`
	Language     *string `json:"language,omitempty"`
}

TrailReviewLocationCreateRequest identifies where a new finding applies. 

type TrailReviewOutgoingLink struct {
	SourceCommentID string `json:"source_comment_id"`
	TargetCommentID string `json:"target_comment_id"`
	LinkType        string `json:"link_type"`
}

TrailReviewOutgoingLink relates two review comments.

type TrailReviewStartRequest added in v0.7.6 

type TrailReviewStartRequest struct {
	HeadSHA *string `json:"head_sha,omitempty"`
	BaseSHA *string `json:"base_sha,omitempty"`
	BaseRef *string `json:"base_ref,omitempty"`
	HeadRef *string `json:"head_ref,omitempty"`
}

TrailReviewStartRequest starts a review session for a trail via POST /api/v1/trails/{trail_id}/reviews. All fields are optional; the server resolves the code version (base/head) when they are omitted.

type TrailReviewStartResponse added in v0.7.6 

type TrailReviewStartResponse struct {
	ReviewID       string            `json:"review_id"`
	TrailID        string            `json:"trail_id"`
	RepositoryID   string            `json:"repo_id"`
	CodeVersionID  string            `json:"code_version_id"`
	BaseSHA        *string           `json:"base_sha"`
	HeadSHA        *string           `json:"head_sha"`
	EventStreamURL string            `json:"event_stream_url"`
	DiffURL        string            `json:"diff_url"`
	FilesURL       string            `json:"files_url"`
	Limits         TrailReviewLimits `json:"limits"`
}

TrailReviewStartResponse is returned by POST /api/v1/trails/{trail_id}/reviews.

type TrailReviewStateResponse added in v0.7.6 

type TrailReviewStateResponse struct {
	Review      TrailReview            `json:"review"`
	CodeVersion TrailReviewCodeVersion `json:"code_version"`
	Counts      TrailReviewCounts      `json:"counts"`
	Comments    []TrailReviewComment   `json:"comments"`
	NextCursor  *string                `json:"next_cursor"`
	EventCursor string                 `json:"event_cursor"`
}

TrailReviewStateResponse is returned by GET /api/v1/trails/{trail_id}/reviews/{id}.

type TrailReviewSuggestedChange added in v0.7.6 

type TrailReviewSuggestedChange struct {
	ID                string    `json:"id"`
	ReviewCommentID   string    `json:"review_comment_id"`
	CodeVersionID     string    `json:"code_version_id"`
	ChangeType        string    `json:"change_type"`
	Patch             *string   `json:"patch"`
	Instruction       *string   `json:"instruction"`
	ExpectedFilePath  *string   `json:"expected_file_path"`
	ExpectedFileHash  *string   `json:"expected_file_hash"`
	ExpectedStartLine *int      `json:"expected_start_line"`
	ExpectedEndLine   *int      `json:"expected_end_line"`
	ExpectedLines     *string   `json:"expected_lines"`
	CreatedBy         string    `json:"created_by"`
	CreatedAt         time.Time `json:"created_at"`
	UpdatedAt         time.Time `json:"updated_at"`
}

TrailReviewSuggestedChange describes a machine-applicable or manual fix.

type TrailReviewSuggestedChangeCreateRequest added in v0.7.6 

type TrailReviewSuggestedChangeCreateRequest struct {
	ChangeType        string  `json:"change_type"`
	Patch             *string `json:"patch,omitempty"`
	Instruction       *string `json:"instruction,omitempty"`
	ExpectedFilePath  *string `json:"expected_file_path,omitempty"`
	ExpectedFileHash  *string `json:"expected_file_hash,omitempty"`
	ExpectedStartLine *int    `json:"expected_start_line,omitempty"`
	ExpectedEndLine   *int    `json:"expected_end_line,omitempty"`
	ExpectedLines     *string `json:"expected_lines,omitempty"`
}

TrailReviewSuggestedChangeCreateRequest attaches a suggested fix to a new finding.

Every change_type other than manual_instruction requires the full expected_* anchor — the API rejects a patch that arrives without it. The anchor describes the pre-image the patch was written against, so a later apply can tell whether the file has moved on:

  • ExpectedFileHash is the git blob OID of the whole file as it stood in the author's worktree, i.e. what `git hash-object <file>` prints in that repo. The server stores it opaquely, so this is the CLI's convention; keep producers in agreement before relying on it for staleness checks.
  • ExpectedLines is the byte-exact content of ExpectedStartLine..ExpectedEndLine with line endings intact — not CRLF-normalized display text.

type TrailUpdateRequest added in v0.5.2 

type TrailUpdateRequest struct {
	Status             *string   `json:"status,omitempty"`
	Title              *string   `json:"title,omitempty"`
	Assignees          *[]string `json:"assignees,omitempty"`
	RequestedReviewers *[]string `json:"requested_reviewers,omitempty"`
	Type               *string   `json:"type,omitempty"`
	Priority           *string   `json:"priority,omitempty"`
}

TrailUpdateRequest uses pointers to distinguish absent fields from clears. There is deliberately no Labels field: the trails API does not accept label writes, so `trail update` exposes no label flags (labels are read-only, see TrailResource.Labels).

There is deliberately no Body field either. The trails API does not serve body writes on this route — it rejects a body field outright and names the dedicated route to use instead — so the description has its own route and its own request shape; see TrailBodyRequest. Do not reintroduce the field to save a request: the rejection has been served as a redacted 5xx, which reads to the caller as a flaky server rather than as the wrong route, and that is what made this bug survive as long as it did.

type TrailUpdateResponse added in v0.5.2 

type TrailUpdateResponse struct {
	Trail TrailResource `json:"trail"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.