denial

package
v0.57.17 Latest Latest
Warning

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

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package denial is the single client-error-envelope/v1 type for cost-bearing and entitlement denials. The schema lives in the workspace (public StackKits standards/client-error-envelope.v1.schema.json). Callers must not declare a parallel envelope; user_guidance is always an object.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalidEnvelope = errors.New("denial: envelope is not client-error-envelope/v1")
	ErrGuidanceObject  = errors.New("denial: user_guidance must be an object")
)

Functions

This section is empty.

Types

type Action

type Action struct {
	Kind       ActionKind `json:"kind"`
	ModelID    string     `json:"model_id,omitempty"`
	ProviderID string     `json:"provider_id,omitempty"`
	EndpointID string     `json:"endpoint_id,omitempty"`
}

Action is semantic: clients map it to their own trusted UI, never a served executable or arbitrary navigation URL. Validate checks the kind's parameters.

func (Action) Validate

func (a Action) Validate() error

type ActionKind

type ActionKind string
const (
	ActionRetry             ActionKind = "retry"
	ActionSignIn            ActionKind = "sign_in"
	ActionSelectModel       ActionKind = "select_model"
	ActionSelectFreeModel   ActionKind = "select_free_model"
	ActionConfigureProvider ActionKind = "configure_provider"
	ActionUseProviderKey    ActionKind = "use_provider_key"
	ActionUseModelEndpoint  ActionKind = "use_model_endpoint"
	ActionManagePlan        ActionKind = "manage_plan"
	ActionBuyAIBoost        ActionKind = "buy_ai_boost"
	ActionContactSupport    ActionKind = "contact_support"
)

type Cause

type Cause string
const (
	CauseAuthentication       Cause = "authentication"
	CauseAuthorization        Cause = "authorization"
	CauseModelPolicy          Cause = "model_policy"
	CauseFunding              Cause = "funding"
	CauseCapacity             Cause = "capacity"
	CauseConfiguration        Cause = "configuration"
	CauseInfrastructure       Cause = "infrastructure"
	CauseProvider             Cause = "provider"
	CapabilityModelExecutions       = "ai.model-executions"
	CapabilityAgentRuns             = "ai.agent-runs"
)

type Envelope

type Envelope struct {
	ErrorCode        string         `json:"error_code"`
	ReasonCode       string         `json:"reason_code"`
	RequestID        string         `json:"request_id,omitempty"`
	Capability       string         `json:"capability,omitempty"`
	ProviderID       string         `json:"provider_id,omitempty"`
	RequiredFeatures []string       `json:"required_features,omitempty"`
	MissingFeatures  []string       `json:"missing_features,omitempty"`
	Cause            Cause          `json:"cause,omitempty"`
	RetryAfterMS     *int64         `json:"retry_after_ms,omitempty"`
	ResetAt          string         `json:"reset_at,omitempty"`
	Actions          []Action       `json:"actions,omitempty"`
	Retryable        bool           `json:"retryable"`
	UserGuidance     UserGuidance   `json:"user_guidance"`
	Remediation      string         `json:"remediation,omitempty"`
	SupportContext   map[string]any `json:"support_context,omitempty"`
}

Envelope is the machine-readable denial. Required fields match the workspace schema: error_code, reason_code, retryable, user_guidance.

func Parse

func Parse(data []byte) (Envelope, error)

Parse accepts the canonical envelope and the three running representations declared in workspace client-error-transport.v1.schema.json. Aliases are validated as their named transport, never admitted as canonical extensions.

func (*Envelope) Error

func (e *Envelope) Error() string

func (Envelope) MarshalJSON

func (e Envelope) MarshalJSON() ([]byte, error)

MarshalJSON always writes user_guidance as an object.

func (*Envelope) Validate

func (e *Envelope) Validate() error

Validate reports whether the envelope satisfies the required schema fields.

type Localization

type Localization struct {
	TitleMessageID     string         `json:"title_message_id"`
	BodyMessageID      string         `json:"body_message_id"`
	NextStepMessageIDs []string       `json:"next_step_message_ids"`
	MessageParams      map[string]any `json:"message_params,omitempty"`
}

type UserGuidance

type UserGuidance struct {
	Title        string        `json:"title"`
	Body         string        `json:"body"`
	NextSteps    []string      `json:"next_steps"`
	Localization *Localization `json:"localization,omitempty"`
}

UserGuidance is the human-facing part of a denial. It is always a JSON object with title, body, and at least one next step.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL