api

Documentation

Index

• Variables
• type AnonymousTokenResponse
• type BillingError
  • func (e *BillingError) Error() string
  • func (e *BillingError) Unwrap() error
• type CapsuleRequest
• type CapsuleResponse
• type Client
  • func New(baseURL string) *Client
  • func (c *Client) AnonymousToken(ctx context.Context) (*AnonymousTokenResponse, error)
  • func (c *Client) Capsule(ctx context.Context, req CapsuleRequest) (*CapsuleResponse, error)
  • func (c *Client) Compact(ctx context.Context, req CapsuleRequest) (*CompactResponse, error)
  • func (c *Client) FreeCompact(ctx context.Context, req CapsuleRequest) (*CompactResponse, error)
  • func (c *Client) Health(ctx context.Context) (map[string]interface{}, error)
  • func (c *Client) Parse(ctx context.Context, lines []string) (*ParseResponse, error)
  • func (c *Client) WarmCache(ctx context.Context, req WarmRequest) (*WarmResponse, error)
• type CompactResponse
• type HTTPError
  • func (e *HTTPError) Error() string
• type LineRecord
• type ParseResponse
• type ParsedLine
• type RateLimitError
  • func (e *RateLimitError) Error() string
  • func (e *RateLimitError) Unwrap() error
• type Stats
• type Template
• type WarmRequest
• type WarmResponse

Variables

var ErrBillingRequired = errors.New("billing action required")

ErrBillingRequired is returned when the server blocks a metered call because the org needs a billing action: out of included credits, subscription past due, etc. Callers should surface a clear upgrade path instead of leaking a raw 402.

var ErrOverloaded = errors.New("codag is busy; retry later")

ErrOverloaded is returned when Codag is temporarily unable to accept more synchronous work. This is retryable and distinct from billing/quota.

var ErrQuotaExceeded = errors.New("warm quota exceeded for today")

ErrQuotaExceeded is returned on a 429 from /v1/onboard/warm. The onboard runner converts this to a clear "daily warm quota exceeded" per-source row in the report rather than the generic "server returned 429" string. The wrapped server detail (containing the remaining quota count) is preserved for users who need the exact number.

var ErrUnauthenticated = errors.New("not signed in (or refresh failed); run `codag auth login`")

ErrUnauthenticated is returned when the server rejects auth and refresh either failed or wasn't possible. Callers (notably the MCP dispatcher) recognize this to emit a "run `codag auth login`" hint.

Types

type AnonymousTokenResponse

type AnonymousTokenResponse struct {
	Token     string `json:"token"`
	TokenType string `json:"token_type"`
}

type BillingError

type BillingError struct {
	Detail      string
	UpgradePath string
	Body        string
}

BillingError carries the machine-readable detail and server-suggested upgrade path from a 402 response.

func (*BillingError) Error

func (e *BillingError) Error() string

func (*BillingError) Unwrap

func (e *BillingError) Unwrap() error

type CapsuleRequest

type CapsuleRequest struct {
	Lines    []LineRecord           `json:"lines"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
	// Engine selects the /v1/compact path. Empty/"auto" picks by plan,
	// "deterministic" forces codag-drain even for Pro orgs, "inference"
	// fails loudly (402) instead of degrading when Pro is unavailable.
	Engine string `json:"engine,omitempty"`
}

type CapsuleResponse

type CapsuleResponse struct {
	Capsule map[string]interface{} `json:"capsule"`
	Stats   Stats                  `json:"stats"`
}

type Client

type Client struct {
	BaseURL string
	HTTP    *http.Client
}

Client wraps a base URL. Auth tokens are resolved per-request from the OAuth refresher in cli/internal/auth.

func New

func New(baseURL string) *Client

New returns a Client with sensible defaults.

func (*Client) AnonymousToken

func (c *Client) AnonymousToken(ctx context.Context) (*AnonymousTokenResponse, error)

func (*Client) Capsule

func (c *Client) Capsule(ctx context.Context, req CapsuleRequest) (*CapsuleResponse, error)

Capsule calls POST /v1/capsule.

func (*Client) Compact

func (c *Client) Compact(ctx context.Context, req CapsuleRequest) (*CompactResponse, error)

Compact calls POST /v1/compact.

func (*Client) FreeCompact

func (c *Client) FreeCompact(ctx context.Context, req CapsuleRequest) (*CompactResponse, error)

FreeCompact calls POST /v1/free/compact with a persisted anonymous token.

func (*Client) Health

func (c *Client) Health(ctx context.Context) (map[string]interface{}, error)

Health calls GET /health.

func (*Client) Parse

func (c *Client) Parse(ctx context.Context, lines []string) (*ParseResponse, error)

Parse calls POST /v1/parse.

func (*Client) WarmCache

func (c *Client) WarmCache(ctx context.Context, req WarmRequest) (*WarmResponse, error)

WarmCache calls POST /v1/onboard/warm. Used by `codag onboard` to bulk pre-populate the org's template_cache from historical user logs.

type CompactResponse

type CompactResponse struct {
	Text            string `json:"text"`
	Stats           Stats  `json:"stats"`
	CompactEngine   string `json:"compact_engine,omitempty"`
	CompactFallback string `json:"compact_fallback,omitempty"`
	CompactError    string `json:"compact_error,omitempty"`
}

type HTTPError

type HTTPError struct {
	Status int
	Body   string
}

HTTPError carries the server-returned status + body for callers that want to branch on specific codes. Returned for any non-2xx that isn't already mapped to a sentinel above.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type LineRecord

type LineRecord struct {
	LineID    int    `json:"line_id"`
	Message   string `json:"message"`
	Level     string `json:"level,omitempty"`
	Timestamp string `json:"timestamp,omitempty"`
	Service   string `json:"service,omitempty"`
}

type ParseResponse

type ParseResponse struct {
	Templates []Template   `json:"templates"`
	Parsed    []ParsedLine `json:"parsed"`
	Stats     Stats        `json:"stats"`
}

type ParsedLine

type ParsedLine struct {
	Line        string `json:"line"`
	TemplateID  string `json:"template_id,omitempty"`
	RawTemplate string `json:"raw_template,omitempty"`
	CacheHit    bool   `json:"cache_hit"`
}

type RateLimitError

type RateLimitError struct {
	Detail     string
	RetryAfter string
	Body       string
}

RateLimitError carries the machine-readable detail and Retry-After hint from a 429 that is not a warm quota exhaustion.

func (*RateLimitError) Error

func (e *RateLimitError) Error() string

func (*RateLimitError) Unwrap

func (e *RateLimitError) Unwrap() error

type Stats

type Stats struct {
	LLMCalls                 int `json:"llm_calls"`
	CacheHits                int `json:"cache_hits"`
	Unmatched                int `json:"unmatched"`
	ElapsedMS                int `json:"elapsed_ms"`
	IncidentFamilyHits       int `json:"incident_family_hits"`
	IncidentInducedTemplates int `json:"incident_induced_templates"`
}

type Template

type Template struct {
	TemplateID  string `json:"template_id"`
	RawTemplate string `json:"raw_template"`
}

type WarmRequest

type WarmRequest struct {
	Lines  []string `json:"lines"`
	Source string   `json:"source"`
}

type WarmResponse

type WarmResponse struct {
	Source         string `json:"source"`
	TemplatesAdded int    `json:"templates_added"`
	TemplatesTotal int    `json:"templates_total"`
	LinesProcessed int    `json:"lines_processed"`
	LLMCalls       int    `json:"llm_calls"`
	CacheHits      int    `json:"cache_hits"`
	ElapsedMS      int    `json:"elapsed_ms"`
	QuotaRemaining int    `json:"quota_remaining"` // bytes of daily warm quota left today
}