errclass

Documentation

Index

• func APIHint(subtype errs.Subtype) string
• func AnnotateConfigRecovery(err error, subtype errs.Subtype) error
• func BuildAPIError(resp map[string]any, cc ClassifyContext) error
• func CanonicalPermissionMessage(subtype errs.Subtype, appID string, missing []string, fallback string) string
• func ConfigHint(subtype errs.Subtype) string
• func ConsoleURL(brand, appID string, scopes []string) string
• func NewMissingScopeError(brand, appID, identity string, missing []string) error
• func PermissionHint(missing []string, identity string, subtype errs.Subtype, consoleURL string) string
• func PermissionRecovery(missing []string, identity string, subtype errs.Subtype, consoleURL string) recovery.Hint
• type ClassifyContext
• type CodeMeta
  • func LookupCodeMeta(code int) (CodeMeta, bool)

Functions

func APIHint

func APIHint(subtype errs.Subtype) string

APIHint returns the canonical per-subtype recovery hint for a typed APIError emitted via BuildAPIError, for API subtypes whose recovery is context-free. Context-specific guidance (e.g. a command's flags, an API's own quota) is layered on by the caller after BuildAPIError returns and overrides this.

func AnnotateConfigRecovery

func AnnotateConfigRecovery(err error, subtype errs.Subtype) error

AnnotateConfigRecovery attaches the same semantic recovery metadata used by BuildAPIError to a directly-constructed ConfigError.

func BuildAPIError

func BuildAPIError(resp map[string]any, cc ClassifyContext) error

BuildAPIError consumes a parsed Lark API response and returns a typed error. Returns nil when resp is nil or resp["code"] is 0.

Routing by Category:

Authorization → *errs.PermissionError (with MissingScopes / Identity / ConsoleURL)
Authentication → *errs.AuthenticationError
Config → *errs.ConfigError
Policy → *errs.SecurityPolicyError
Validation → *errs.ValidationError
Network → *errs.NetworkError
Internal → *errs.InternalError
Confirmation → *errs.ConfirmationRequiredError
default (CategoryAPI) → *errs.APIError (catch-all for classified Lark business errors)

Unknown Lark codes (LookupCodeMeta returns false) fall back to CategoryAPI + SubtypeUnknown.

func CanonicalPermissionMessage

func CanonicalPermissionMessage(subtype errs.Subtype, appID string, missing []string, fallback string) string

CanonicalPermissionMessage returns the default user-facing CLI wording for a typed PermissionError, preserving the Lark official-API phrasing ("access denied" / "unauthorized" / "token has no permission") and enhancing it with CLI context (app ID, missing scope list). Subtypes outside the known set fall through to fallback so the upstream message is preserved.

func ConfigHint

func ConfigHint(subtype errs.Subtype) string

ConfigHint returns the canonical per-subtype recovery hint for a typed ConfigError emitted via BuildAPIError.

func ConsoleURL

func ConsoleURL(brand, appID string, scopes []string) string

ConsoleURL composes the Feishu/Lark open-platform application-scope apply page URL (the official open-pages `/page/scope-apply` entry), suitable for PermissionError.ConsoleURL. Empty appID → empty string. Empty scopes list returns the page carrying only clientID; otherwise scopes are joined with commas in the `scopes` query parameter so the console can pre-select them.

brand is "feishu" or "lark"; unknown values default to feishu.

func NewMissingScopeError

func NewMissingScopeError(brand, appID, identity string, missing []string) error

NewMissingScopeError constructs the same typed missing-scope error as the API classifier from locally verified scope facts. Generated service preflight checks use this entrypoint so subtype-specific wire fields and recovery cannot drift from BuildAPIError.

func PermissionHint

func PermissionHint(missing []string, identity string, subtype errs.Subtype, consoleURL string) string

PermissionHint returns the canonical per-subtype recovery hint for a typed PermissionError. The hint distinguishes authorization subtypes routing to different recovery paths: developer console for app_scope_not_applied, identity-specific user or bot recovery for missing_scope / token_scope_insufficient / user_unauthorized, and tenant admin for app_unavailable / app_disabled. The subtype and identity together select the actor that can resolve the failure.

Exported so direct construction sites (cmd/service/service.go's checkServiceScopes) can produce hints that match the dispatcher path byte-for-byte instead of hand-rolling divergent strings.

func PermissionRecovery

func PermissionRecovery(missing []string, identity string, subtype errs.Subtype, consoleURL string) recovery.Hint

PermissionRecovery returns the semantic recovery represented by a PermissionError's machine fields. The root presenter uses it for direct business-produced PermissionErrors that did not need to know about command targets or distribution policy.

Types

type ClassifyContext

type ClassifyContext struct {
	Brand    string // "feishu" | "lark" — drives console_url host
	AppID    string // placed in console_url
	Identity string // "user" / "bot" / "" — caller converts core.Identity at the boundary
	LarkCmd  string // e.g. "drive +delete" — used as Action fallback on CategoryConfirmation arm
}

ClassifyContext is the contextual data BuildAPIError uses to populate identity-aware fields on typed errors (PermissionError.Identity / ConsoleURL). Brand and Identity are plain strings at this boundary; ConsoleURL normalizes Brand through core.ParseBrand, so callers can pass a raw brand string without coupling this contract to core's brand enum.

type CodeMeta

type CodeMeta struct {
	Category  errs.Category
	Subtype   errs.Subtype
	Retryable bool
	Risk      string // CategoryConfirmation arm only; empty otherwise
	Action    string // CategoryConfirmation arm only; empty otherwise
}

CodeMeta is the classification metadata attached to a Lark numeric code. It does NOT carry Message or Hint — those are derived at the dispatcher (see BuildAPIError).

Risk + Action are populated only for codes that route to CategoryConfirmation; the dispatcher falls back to RiskUnknown + ctx.LarkCmd when either is empty so the envelope is never wire-invalid.

func LookupCodeMeta

func LookupCodeMeta(code int) (CodeMeta, bool)

LookupCodeMeta is the single lookup entry. Returns ok=false for unknown codes — the caller (BuildAPIError) is responsible for falling back to CategoryAPI/SubtypeUnknown.