errclass

Documentation

Index

• func BuildAPIError(resp map[string]any, cc ClassifyContext) error
• func ConsoleURL(brand, appID string, scopes []string) string
• func PermissionHint(missing []string, identity string, subtype errs.Subtype) string
• type ClassifyContext
• type CodeMeta
  • func LookupCodeMeta(code int) (CodeMeta, bool)

Functions

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 (Detail preserves raw response)

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

func ConsoleURL

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

ConsoleURL composes the Feishu/Lark open-platform scope-grant console URL, suitable for PermissionError.ConsoleURL. Empty appID → empty string. Empty scopes list returns the bare /auth landing page; scopes are joined with commas in the `q` query parameter so the console can pre-select them.

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

func PermissionHint

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

PermissionHint returns an actionable next-step string for a permission error. User identity with a missing user-scope is recovered by re-running `auth login --scope ...`; bot identity or app-level scope errors are recovered by enabling scopes in the open-platform console. The subtype argument distinguishes app-level failures (e.g. SubtypeAppScopeNotApplied) where re-authentication will not help regardless of the caller identity.

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.

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
}

ClassifyContext is the contextual data BuildAPIError uses to populate identity-aware fields on typed errors (PermissionError.Identity / ConsoleURL). Identity is a plain string ("user" / "bot" / "") so this package does not depend on internal/core (which would create an import cycle).

type CodeMeta

type CodeMeta struct {
	Category  errs.Category
	Subtype   errs.Subtype
	Retryable bool
}

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).

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.