targetresolver

package

v1.0.59 Latest Latest Go to latest Published: Aug 20, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation ¶

Overview ¶

Package targetresolver provides deterministic natural-target resolution for shortcuts. It owns extraction, stable-ID de-duplication, exact-match preference, ambiguity handling, and the machine-readable resolution error envelope shared by send/read/search/create/event facades.

Index ¶

func ChatLabels(chats []Chat) []string
func IsUnverifiedUserIDResolution(resolution UserResolution) bool
func LooksLikeCurrentDOpenDingTalkID(value string) bool
func LooksLikeOpenConversationID(value string) bool
func UserLabels(users []User) []string
func ValidateExplicitOpenDingTalkID(flagName, value string) error
type Chat
- func ExtractChats(data map[string]any) []Chat
- func PreferExactChats(chats []Chat, query string) []Chat
type ChatResolution
type IdentityRequirement
type Reader
type Status
type User
- func ExtractUsers(data map[string]any) []User
- func UsersWithUserID(users []User) []User
type UserResolution

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func ChatLabels ¶

func ChatLabels(chats []Chat) []string

ChatLabels renders group disambiguation labels.

func IsUnverifiedUserIDResolution ¶ added in v1.0.59

func IsUnverifiedUserIDResolution(resolution UserResolution) bool

IsUnverifiedUserIDResolution reports a mixed sender value that could not be classified by the directory and is therefore being tried as an exact userId. Consumers may use positive senderId equality, but must not claim a negative result is complete because the original value may instead have been a name.

func LooksLikeCurrentDOpenDingTalkID ¶ added in v1.0.59

func LooksLikeCurrentDOpenDingTalkID(value string) bool

LooksLikeCurrentDOpenDingTalkID reports whether value has the canonical wire format emitted by the current D-version encoder. It does not decrypt the value and therefore does not prove that the identity exists or is accessible to the current profile.

func LooksLikeOpenConversationID ¶

func LooksLikeOpenConversationID(value string) bool

LooksLikeOpenConversationID identifies the opaque group-conversation IDs returned by DingTalk. It is deliberately conservative: only the stable "cid..." form is recognized, so ordinary short names are still resolved by search and ambiguity checks.

func UserLabels ¶

func UserLabels(users []User) []string

UserLabels renders credential-free disambiguation labels.

func ValidateExplicitOpenDingTalkID ¶ added in v1.0.59

func ValidateExplicitOpenDingTalkID(flagName, value string) error

ValidateExplicitOpenDingTalkID applies the current-version format contract to an explicitly typed ID flag. Unlike mixed targets, an invalid explicit ID must fail locally instead of falling back to a name or userId lookup.

Types ¶

type Chat ¶

type Chat struct {
	OpenConversationID string `json:"openConversationId"`
	Name               string `json:"name,omitempty"`
}

Chat is the public identity returned by group resolution.

func ExtractChats ¶

func ExtractChats(data map[string]any) []Chat

ExtractChats accepts both bare and wrapped group search result lists.

func PreferExactChats ¶

func PreferExactChats(chats []Chat, query string) []Chat

PreferExactChats exposes the deterministic selection helper to legacy smart shortcuts while they migrate to ResolveChat.

type ChatResolution ¶

type ChatResolution struct {
	Status     Status `json:"status"`
	EntityType string `json:"entityType"`
	Query      string `json:"query"`
	MatchType  string `json:"matchType"`
	Selected   Chat   `json:"selected"`
	Profile    string `json:"profile,omitempty"`
}

ChatResolution is the typed successful group-resolution result.

func ResolveChat ¶

func ResolveChat(rt Reader, query string) (ChatResolution, error)

ResolveChat searches groups and resolves query to exactly one stable openConversationId. Exact names win over substring matches, but multiple exact names remain ambiguous.

func ResolveChatTarget ¶

func ResolveChatTarget(rt Reader, directValue, queryValue string) (ChatResolution, error)

ResolveChatTarget accepts either a stable openConversationId or a natural group name and returns one normalized ChatResolution. Stable IDs never reach search_groups; natural names retain ResolveChat's complete-pagination and fail-closed ambiguity semantics.

func ResolveChats ¶

func ResolveChats(rt Reader, queries []string) ([]ChatResolution, error)

ResolveChats is the batch equivalent of ResolveChat and returns only after every query has been preflighted.

type IdentityRequirement ¶

type IdentityRequirement string

IdentityRequirement filters contacts to identities accepted by the downstream interface.

const (
	IdentityAny            IdentityRequirement = "any"
	IdentityUserID         IdentityRequirement = "user_id"
	IdentityOpenDingTalkID IdentityRequirement = "open_dingtalk_id"
)

type Reader ¶

type Reader interface {
	CallMCPData(product, tool string, params map[string]any) (map[string]any, error)
}

Reader is the minimal read-only transport needed by natural target resolution. Shortcut RuntimeContext implements it, and native facades (for example event +listen-im) can provide an adapter without duplicating extraction or ambiguity rules.

type Status ¶

type Status string

Status is the stable resolution outcome used in successful plans and errors.

const (
	StatusResolved   Status = "resolved"
	StatusAmbiguous  Status = "ambiguous"
	StatusNotFound   Status = "not_found"
	StatusIncomplete Status = "incomplete"
)

type User ¶

type User struct {
	UserID         string `json:"userId,omitempty"`
	OpenDingTalkID string `json:"openDingTalkId,omitempty"`
	Name           string `json:"name,omitempty"`
}

User is the public, credential-free identity returned by contact resolution.

func ExtractUsers ¶

func ExtractUsers(data map[string]any) []User

ExtractUsers accepts the contact search response shapes used by the current directory MCP and keeps external contacts that only expose openDingTalkId.

func UsersWithUserID ¶

func UsersWithUserID(users []User) []User

UsersWithUserID preserves the legacy smart-shortcut helper contract.

type UserResolution ¶

type UserResolution struct {
	Status     Status `json:"status"`
	EntityType string `json:"entityType"`
	Query      string `json:"query"`
	MatchType  string `json:"matchType"`
	Selected   User   `json:"selected"`
	Profile    string `json:"profile,omitempty"`
}

UserResolution is the typed successful user-resolution result.

func ResolveEnterpriseUser ¶

func ResolveEnterpriseUser(rt Reader, query string, requirement IdentityRequirement) (UserResolution, error)

ResolveEnterpriseUser resolves an organization member through the same name-calibrated enterprise search used by `dws aisearch person`. Unlike the contact search, this source understands organization nicknames and aliases.

func ResolveSenderTarget ¶ added in v1.0.59

func ResolveSenderTarget(rt Reader, value string, requirement IdentityRequirement) (UserResolution, error)

ResolveSenderTarget resolves the mixed identity accepted specifically by sender convenience flags. Unlike the shared name resolver, it may select a unique candidate whose stable userId/openDingTalkId exactly equals the supplied value. Natural-name resolution accepts only exact names and retains fail-closed ambiguity behavior; a lone unrelated directory candidate must never replace the supplied value. If the directory cannot classify a value and userId is accepted downstream, the original value is retained as an unverified userId candidate so a valid stable ID is not blocked by directory availability.

func ResolveStableUserTarget ¶ added in v1.0.59

func ResolveStableUserTarget(rt Reader, value string, requirement IdentityRequirement) (UserResolution, error)

ResolveStableUserTarget accepts only a userId or current-version openDingTalkId. Because callers use it only for ID-only flags, a non-D value is already explicitly typed as userId and can be passed through without a directory availability dependency.

func ResolveUser ¶

func ResolveUser(rt Reader, query string, requirement IdentityRequirement) (UserResolution, error)

ResolveUser searches the current profile's directory and resolves query to exactly one identity accepted by the downstream interface.

func ResolveUserTarget ¶ added in v1.0.59

func ResolveUserTarget(rt Reader, value string, requirement IdentityRequirement) (UserResolution, error)

ResolveUserTarget accepts the mixed user target used by public convenience flags: a natural name, userId, or current-version openDingTalkId. The local format check is deliberately a classifier rather than an existence check. Format-valid IDs go directly to the downstream business API; all other values use the directory resolver, which can match names and exact userIds.

func ResolveUsers ¶

func ResolveUsers(
	rt Reader,
	queries []string,
	requirement IdentityRequirement,
) ([]UserResolution, error)

ResolveUsers resolves every query before returning. Resolution failures are collected into one typed envelope; upstream/auth failures still stop immediately. Successful identities are de-duplicated by stable ID.

Source Files ¶

View all Source files

resolver.go

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