ref

package
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package ref turns the flexible references the CLI accepts into concrete Microsoft Graph ids: Teams deep links, "Team/Channel/Message" name paths, "@person", e-mail addresses, aliases and raw ids.

PLAN.md "Smart references" is the specification for this package. Its two halves are the parser (ParseURL, Parse) and the resolver (Resolver), which is the only part that talks to Graph or the entity cache.

Everything here is tolerant by design. A pasted "Copy link" URL may carry the channel id raw (19:...@thread.tacv2) or percent-encoded, its query parameters in any order, and parameters we do not know; the parser accepts all of it and the resolver rejects only what cannot be resolved at all.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func LooksLikeChannelID

func LooksLikeChannelID(s string) bool

LooksLikeChannelID reports whether s has the shape of a channel id.

func LooksLikeChatID

func LooksLikeChatID(s string) bool

LooksLikeChatID reports whether s has the shape of a chat id. Graph chat ids start with "19:" and end in a thread marker; a channel id shares the prefix but uses @thread.tacv2, so the suffix is what separates the two families (refs/msteams/msteams-platform/concepts/build-and-test/deep-link-teams.md).

func PersonKey

func PersonKey(raw string) string

PersonKey is the cache key for a person reference: the typed text, lowercased and without the leading @, so @Yuki, yuki and yuki@x.com stay distinct while casing does not. Distinct forms are intentional: the entity cache records which form resolved to whom.

Types

type Chooser

type Chooser interface {
	Interactive() bool
	Choose(question string, options []string) (int, error)
}

Chooser picks one of several candidates on a terminal. The CLI implements it; when it is nil, or says the session is not interactive, the resolver fails with the candidate list instead of guessing - which is what PLAN.md requires of non-interactive mode.

type Error

type Error struct {
	Msg  string
	Code int
	Fix  string
}

Error is a reference error: a message, the exit code it maps to, and the one-line fix to print under it.

func (*Error) Error

func (e *Error) Error() string

Error implements error.

func (*Error) ExitCode

func (e *Error) ExitCode() int

ExitCode is the process exit code for this error.

func (*Error) Hint

func (e *Error) Hint() string

Hint is the suggested fix, printed by the CLI under the error.

type Kind

type Kind string

Kind is what a reference points at.

const (
	KindUnknown Kind = ""
	KindTeam    Kind = "team"
	KindChannel Kind = "channel"
	KindChat    Kind = "chat"
	KindMessage Kind = "message"
	KindUser    Kind = "user"
	KindFile    Kind = "file"
)

Reference kinds. KindUnknown is what a parse produces when the string is a bare Graph id whose meaning depends on the command that accepted it ("19:..." is a channel id in one command and a chat id in another), so the resolver, not the parser, decides.

type Ref

type Ref struct {
	Kind Kind
	// Raw is the input, kept for error messages and for the entity cache key.
	Raw string

	// TeamID and TeamName come from a deep link (groupId, teamName or the name
	// path's first element).
	TeamID   string
	TeamName string

	// ChannelID and ChannelName come from a deep link or a name path.
	ChannelID   string
	ChannelName string

	// ChatID is a chat's 19:... id, from a deep link or a raw id; ChatTopic is
	// the display name when the chat was matched by one.
	ChatID    string
	ChatTopic string

	// MessageID and ParentMessageID are the message a link or a name path points
	// at. InChat records that the message lives in a chat: /l/message/ carries
	// both families and the query string is the only discriminator
	// (refs/msteams/msteams-platform/concepts/build-and-test/deep-link-teams.md,
	// "Deep link to navigate to chat messages").
	MessageID       string
	ParentMessageID string
	InChat          bool

	// User is the person form as typed: a display name, an e-mail, a UPN or a
	// user id. UserID, UserName and UserMail are filled in by the resolver.
	User     string
	UserID   string
	UserName string
	UserMail string
	// IsEmail records that User looks like an address, which resolves faster
	// (an exact GET /users/{id} instead of a directory search).
	IsEmail bool

	// FileID is a /l/file/ link's file id.
	FileID string

	// Path is a name path split on "/": ["Engineering", "General"] or
	// ["Engineering", "General", "1758..."].
	Path []string

	// Target is what an alias points at, when the reference came from one; it is
	// empty for a direct reference. Raw stays the text the user typed, so an error
	// message quotes what they wrote, while a name lookup searches Target: an alias
	// for a chat topic has to match the topic, not the alias name (PLAN.md:168).
	Target string

	// Host is the deep link's host, so the parser can accept the newer
	// teams.cloud.microsoft host defensively (PLAN.md:164).
	Host string
	// TenantID is the deep link's tenantId parameter, when present.
	TenantID string
}

Ref is a parsed, unresolved reference. Only the fields that the input carried are set; everything else is filled in by the Resolver.

func Parse

func Parse(raw string) (Ref, error)

Parse classifies a reference string without touching the network. It is the first half of PLAN.md's "Smart references": the resolver then turns the classification into ids. The classification is deliberately loose, because the same string means different things to different commands: a bare 19:...@thread.v2 is a chat id to `chat read` and nothing useful to `team show`.

func ParseURL

func ParseURL(raw string) (ref Ref, ok bool, err error)

ParseURL parses a Teams deep link. ok is false when raw is not a Teams URL at all (the caller then tries the other reference shapes).

ok is true for every URL that is shaped like a Teams deep link, even when the parser refuses it: err is then set for the families the CLI cannot open (/l/app, /l/entity, /l/task, /l/call, /l/meeting*, PLAN.md:164), so the caller maps one error class to exit code 2 instead of silently treating a pasted URL as a raw id. A message link without groupId parses with an empty TeamID: the resolver decides whether to fail with exit 4 or ask for --team (PLAN.md:164 and refs/INDEX.md section 5).

func (Ref) IsZero

func (r Ref) IsZero() bool

IsZero reports whether nothing was parsed out of the input.

func (Ref) NamePath

func (r Ref) NamePath() string

NamePath returns the "/"-joined name path, or "" when the input was not one.

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver turns references into Graph ids. It is the only part of this package that talks to Graph or to local state.

func NewResolver

func NewResolver(opts ResolverOptions) *Resolver

NewResolver builds a Resolver.

func (*Resolver) Cache

func (r *Resolver) Cache() *store.EntityCache

Cache exposes the entity cache, so the CLI can persist it after a run.

func (*Resolver) Channel

func (r *Resolver) Channel(ctx context.Context, raw, teamHint string) (Ref, error)

Channel resolves a channel reference. teamHint is the --team flag, which a channel-message link without groupId needs: every channel route takes the team id, and there is no channel-to-team lookup (PLAN.md:164).

func (*Resolver) Chat

func (r *Resolver) Chat(ctx context.Context, raw string) (Ref, error)

Chat resolves a chat reference: a chat id, a Teams chat link, a person (which means the 1:1 chat with them) or a chat topic.

func (*Resolver) Client

func (r *Resolver) Client() *graph.Client

Client exposes the Graph client the resolver was built with, so a command can keep using the same one.

func (*Resolver) Message

func (r *Resolver) Message(ctx context.Context, raw, teamHint string) (Ref, error)

Message resolves a message reference. A channel message needs its team and channel; a chat message needs its chat. A bare message id is rejected, because no Graph route can find the container from the id alone.

func (*Resolver) Person

func (r *Resolver) Person(ctx context.Context, raw string) (Ref, error)

Person returns the user a person reference points at.

func (*Resolver) PersonChat

func (r *Resolver) PersonChat(ctx context.Context, raw string) (Ref, error)

PersonChat returns the 1:1 chat id with a person. PLAN.md:166 documents why this is a scan and not a lookup: there is no person-to-chat API. The result is cached for a week, so the scan runs once per person.

func (*Resolver) PersonID

func (r *Resolver) PersonID(ctx context.Context, raw string) (string, error)

PersonID is a convenience for callers that only need the id.

func (*Resolver) Team

func (r *Resolver) Team(ctx context.Context, raw string) (Ref, error)

Team resolves a team reference to a team id. A URL, a name path's first element, a bare name, an alias and a raw id are all accepted (PLAN.md:158).

type ResolverOptions

type ResolverOptions struct {
	// Client is the Graph client every lookup uses.
	Client *graph.Client
	// Cache is the per-profile entity cache (may be nil in tests).
	Cache *store.EntityCache
	// Aliases is the per-profile alias table, name to target.
	Aliases map[string]string
	// Refresh bypasses the cache, for --refresh.
	Refresh bool
	// Chooser is the interactive picker; nil never prompts.
	Chooser Chooser
	// Now supplies the clock for cache metadata.
	Now func() time.Time
	// Debugf logs cache hits and lookups under --verbose.
	Debugf func(format string, args ...any)
}

ResolverOptions configures a Resolver.

Jump to

Keyboard shortcuts

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