errclass

Documentation

Index

• func APIHint(subtype errs.Subtype) string
• 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 PermissionHint(missing []string, identity string, subtype errs.Subtype, consoleURL string) string
• 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 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 CLI-side canonical 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 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, 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, user re-login for missing_scope / token_scope_insufficient / user_unauthorized, and tenant admin for app_unavailable / app_disabled. The subtype argument is the primary discriminator; identity is retained for the generic permission_denied fallback so callers that do not yet route on subtype still get a sensible hint.

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