core

Documentation

Index

• Variables
• func GetConfigDir() string
• func GetConfigPath() string
• func RemoveSecretStore(input SecretInput, kc keychain.KeychainAccess)
• func ResolveOpenBaseURL(brand LarkBrand) string
• func ResolveSecretInput(s SecretInput, kc keychain.KeychainAccess) (string, error)
• func SaveMultiAppConfig(config *MultiAppConfig) error
• type AppConfig
• type AppUser
• type CliConfig
  • func RequireAuth(kc keychain.KeychainAccess) (*CliConfig, error)
  • func RequireConfig(kc keychain.KeychainAccess) (*CliConfig, error)
• type ConfigError
  • func (e *ConfigError) Error() string
• type Endpoints
  • func ResolveEndpoints(brand LarkBrand) Endpoints
• type Identity
  • func (id Identity) IsBot() bool
• type LarkBrand
• type MultiAppConfig
  • func LoadMultiAppConfig() (*MultiAppConfig, error)
• type SecretInput
  • func ForStorage(appId string, input SecretInput, kc keychain.KeychainAccess) (SecretInput, error)
  • func PlainSecret(s string) SecretInput
  • func (s SecretInput) IsPlain() bool
  • func (s SecretInput) IsSecretRef() bool
  • func (s SecretInput) IsZero() bool
  • func (s SecretInput) MarshalJSON() ([]byte, error)
  • func (s *SecretInput) UnmarshalJSON(data []byte) error
• type SecretRef

Variables

var ValidSecretSources = map[string]bool{
	"file": true, "keychain": true,
}

ValidSecretSources is the set of recognized SecretRef sources.

Functions

func GetConfigDir

func GetConfigDir() string

GetConfigDir returns the config directory path. If the home directory cannot be determined, it falls back to a relative path and prints a warning to stderr.

func GetConfigPath

func GetConfigPath() string

GetConfigPath returns the config file path.

func RemoveSecretStore

func RemoveSecretStore(input SecretInput, kc keychain.KeychainAccess)

RemoveSecretStore cleans up keychain entries when an app is removed. Errors are intentionally ignored — cleanup is best-effort.

func ResolveOpenBaseURL

func ResolveOpenBaseURL(brand LarkBrand) string

ResolveOpenBaseURL returns the Open API base URL for the given brand.

func ResolveSecretInput

func ResolveSecretInput(s SecretInput, kc keychain.KeychainAccess) (string, error)

ResolveSecretInput resolves a SecretInput to a plain string. SecretRef objects are resolved by source (file / keychain).

func SaveMultiAppConfig

func SaveMultiAppConfig(config *MultiAppConfig) error

SaveMultiAppConfig saves config to disk.

Types

type AppConfig

type AppConfig struct {
	AppId     string      `json:"appId"`
	AppSecret SecretInput `json:"appSecret"`
	Brand     LarkBrand   `json:"brand"`
	Lang      string      `json:"lang,omitempty"`
	DefaultAs string      `json:"defaultAs,omitempty"` // "user" | "bot" | "auto"
	Users     []AppUser   `json:"users"`
}

AppConfig is a per-app configuration entry (stored format — secrets may be unresolved).

type AppUser

type AppUser struct {
	UserOpenId string `json:"userOpenId"`
	UserName   string `json:"userName"`
}

AppUser is a logged-in user record stored in config.

type CliConfig

type CliConfig struct {
	AppID      string
	AppSecret  string
	Brand      LarkBrand
	DefaultAs  string // "user" | "bot" | "auto" | "" (from config file)
	UserOpenId string
	UserName   string
}

CliConfig is the resolved single-app config used by downstream code.

func RequireAuth

func RequireAuth(kc keychain.KeychainAccess) (*CliConfig, error)

RequireAuth loads config and ensures a user is logged in.

func RequireConfig

func RequireConfig(kc keychain.KeychainAccess) (*CliConfig, error)

RequireConfig loads the single-app config. Takes Apps[0] directly.

type ConfigError

type ConfigError struct {
	Code    int    // exit code: 2=validation, 3=auth
	Type    string // "config" or "auth"
	Message string
	Hint    string
}

ConfigError is a structured error from config resolution. It carries enough information for main.go to convert it into an output.ExitError.

func (*ConfigError) Error

func (e *ConfigError) Error() string

type Endpoints

type Endpoints struct {
	Open     string // e.g. "https://open.feishu.cn"
	Accounts string // e.g. "https://accounts.feishu.cn"
	MCP      string // e.g. "https://mcp.feishu.cn"
}

Endpoints holds resolved endpoint URLs for different Lark services.

func ResolveEndpoints

func ResolveEndpoints(brand LarkBrand) Endpoints

ResolveEndpoints resolves endpoint URLs based on brand.

type Identity

type Identity string

Identity represents the caller identity for API requests.

const (
	AsUser Identity = "user"
	AsBot  Identity = "bot"
)

func (Identity) IsBot

func (id Identity) IsBot() bool

IsBot returns true if the identity is bot.

type LarkBrand

type LarkBrand string

LarkBrand represents the Lark platform brand. "feishu" targets China-mainland, "lark" targets international. Any other string is treated as a custom base URL.

const (
	BrandFeishu LarkBrand = "feishu"
	BrandLark   LarkBrand = "lark"
)

type MultiAppConfig

type MultiAppConfig struct {
	Apps []AppConfig `json:"apps"`
}

MultiAppConfig is the multi-app config file format.

func LoadMultiAppConfig

func LoadMultiAppConfig() (*MultiAppConfig, error)

LoadMultiAppConfig loads multi-app config from disk.

type SecretInput

type SecretInput struct {
	Plain string     // non-empty for plain string values
	Ref   *SecretRef // non-nil for SecretRef values
}

SecretInput represents a secret value: either a plain string or a SecretRef object.

func ForStorage

func ForStorage(appId string, input SecretInput, kc keychain.KeychainAccess) (SecretInput, error)

ForStorage determines how to store a secret in config.json. - SecretRef → preserved as-is - Plain text → stored in keychain, returns keychain SecretRef Returns error if keychain is unavailable (no silent plaintext fallback).

func PlainSecret

func PlainSecret(s string) SecretInput

PlainSecret creates a SecretInput from a plain string.

func (SecretInput) IsPlain

func (s SecretInput) IsPlain() bool

IsPlain returns true if this is a plain text string (not a SecretRef).

func (SecretInput) IsSecretRef

func (s SecretInput) IsSecretRef() bool

IsSecretRef returns true if this is a SecretRef object (env/file/keychain).

func (SecretInput) IsZero

func (s SecretInput) IsZero() bool

IsZero returns true if the SecretInput has no value.

func (SecretInput) MarshalJSON

func (s SecretInput) MarshalJSON() ([]byte, error)

MarshalJSON serializes SecretInput: plain string → JSON string, SecretRef → JSON object.

func (*SecretInput) UnmarshalJSON

func (s *SecretInput) UnmarshalJSON(data []byte) error

UnmarshalJSON deserializes SecretInput from either a JSON string or a SecretRef object.

type SecretRef

type SecretRef struct {
	Source   string `json:"source"`             // "file" | "keychain"
	Provider string `json:"provider,omitempty"` // optional, reserved
	ID       string `json:"id"`                 // env var name / file path / command / keychain key
}

SecretRef references a secret stored externally.