Documentation
¶
Overview ¶
Package graph is the thin, hand-written Microsoft Graph client PLAN.md chooses over msgraph-sdk-go. It owns the transport concerns every endpoint shares: base URL per cloud, bearer injection, the documented request headers, the error envelope, throttling retry and @odata.nextLink paging.
Endpoint wrappers (teams.go, chats.go, messages.go, ...) are added per phase; this file is the foundation they all sit on.
Index ¶
- Constants
- func AllowsTeamsMeetings(providers []string) bool
- func ChannelMessagePath(teamID, channelID, messageID string) string
- func ChatFilterTopic(topic string) string
- func ChatFilterType(chatType string) string
- func ChatMessagePath(chatID, messageID string) string
- func EachPage[T any](ctx context.Context, c *Client, path string, q url.Values, ...) error
- func EventIDFromHitID(hitID string) (string, bool)
- func IsBadRequest(err error) bool
- func IsConflict(err error) bool
- func IsForbidden(err error) bool
- func IsNotFound(err error) bool
- func IsThrottled(err error) bool
- func IsUnauthorized(err error) bool
- func Items[T any](ctx context.Context, c *Client, path string, q url.Values, ...) iter.Seq2[T, error]
- func ListAll[T any](ctx context.Context, c *Client, path string, q url.Values, limit int, ...) ([]T, error)
- func ODataQuote(s string) string
- func RequestIDOf(err error) string
- func StripDashes(s string) string
- func Top(n int) url.Values
- func TopWith(n int, extra url.Values) url.Values
- func UserFilterDisplayName(prefix string) string
- func UserFilterMail(prefix string) string
- func UserFilterUserPrincipalName(prefix string) string
- type APIError
- type Attachment
- type Attendee
- type BatchItemResponse
- type BatchRequest
- type Channel
- type ChannelIdentity
- type Chat
- type ChatCreate
- type ChatMemberSpec
- type ChatQuery
- type ChatViewpoint
- type ClaimsTokenSource
- type Client
- func (c *Client) AddChatMember(ctx context.Context, chatID, userID string, roles []string) (ConversationMember, error)
- func (c *Client) AllowedOnlineMeetingProviders(ctx context.Context) ([]string, error)
- func (c *Client) BaseURL() string
- func (c *Client) Batch(ctx context.Context, reqs []BatchRequest) (map[string]BatchItemResponse, error)
- func (c *Client) BatchOrdered(ctx context.Context, reqs []BatchRequest) ([]BatchItemResponse, error)
- func (c *Client) CancelEvent(ctx context.Context, eventID, comment string) error
- func (c *Client) CreateChat(ctx context.Context, in ChatCreate) (Chat, error)
- func (c *Client) CreateEvent(ctx context.Context, in EventCreate) (Event, error)
- func (c *Client) CreateShareLink(ctx context.Context, driveID, itemID, scope string) (string, error)
- func (c *Client) Delete(ctx context.Context, path string, opts ...RequestOption) error
- func (c *Client) DeleteChat(ctx context.Context, chatID string) error
- func (c *Client) DeleteEvent(ctx context.Context, eventID string) error
- func (c *Client) Do(ctx context.Context, req Request) (*Response, error)
- func (c *Client) DownloadDriveItemContent(ctx context.Context, driveID, itemID string) (Download, error)
- func (c *Client) FindMeetingChatID(ctx context.Context, joinURL string) (string, error)
- func (c *Client) Get(ctx context.Context, path string, out any, opts ...RequestOption) error
- func (c *Client) GetChannel(ctx context.Context, teamID, channelID string) (Channel, error)
- func (c *Client) GetChannelMessage(ctx context.Context, teamID, channelID, messageID string) (Message, error)
- func (c *Client) GetChannelReply(ctx context.Context, teamID, channelID, messageID, replyID string) (Message, error)
- func (c *Client) GetChat(ctx context.Context, chatID string, members bool) (Chat, error)
- func (c *Client) GetChatMessage(ctx context.Context, chatID, messageID string) (Message, error)
- func (c *Client) GetDefaultDrive(ctx context.Context) (Drive, error)
- func (c *Client) GetDriveItem(ctx context.Context, driveID, itemID string, withWebDavURL bool) (DriveItem, error)
- func (c *Client) GetEvent(ctx context.Context, eventID, selectFields string) (Event, error)
- func (c *Client) GetFilesFolder(ctx context.Context, teamID, channelID string) (DriveItem, error)
- func (c *Client) GetHostedContentValue(ctx context.Context, messagePath, contentID string) (Download, error)
- func (c *Client) GetMe(ctx context.Context) (Me, error)
- func (c *Client) GetSchedule(ctx context.Context, mails []string, start, end time.Time, zone string, ...) ([]ScheduleInformation, error)
- func (c *Client) GetTeam(ctx context.Context, teamID string) (Team, error)
- func (c *Client) GetUser(ctx context.Context, idOrUPN string) (User, error)
- func (c *Client) ListCalendarView(ctx context.Context, userID string, start, end time.Time, fn func(Event) bool) error
- func (c *Client) ListChannelFiles(ctx context.Context, teamID, channelID string) (folder DriveItem, items []DriveItem, err error)
- func (c *Client) ListChannelMessages(ctx context.Context, teamID, channelID string, q MessageQuery) ([]Message, error)
- func (c *Client) ListChannelReplies(ctx context.Context, teamID, channelID, messageID string, q MessageQuery) ([]Message, error)
- func (c *Client) ListChannels(ctx context.Context, teamID string) ([]Channel, error)
- func (c *Client) ListChatMembers(ctx context.Context, chatID string) ([]ConversationMember, error)
- func (c *Client) ListChatMessages(ctx context.Context, chatID string, q MessageQuery) ([]Message, error)
- func (c *Client) ListChats(ctx context.Context, q ChatQuery) ([]Chat, error)
- func (c *Client) ListDriveItemChildren(ctx context.Context, driveID, itemID string, limit int) ([]DriveItem, error)
- func (c *Client) ListJoinedTeams(ctx context.Context) ([]Team, error)
- func (c *Client) ListMessageHostedContents(ctx context.Context, messagePath string) ([]HostedContent, error)
- func (c *Client) ListPeople(ctx context.Context, search string, limit int) ([]Person, error)
- func (c *Client) ListTeamMembers(ctx context.Context, teamID string) ([]ConversationMember, error)
- func (c *Client) ListUsers(ctx context.Context, filter string, limit int) ([]User, error)
- func (c *Client) MarkChatRead(ctx context.Context, chatID, userID string) error
- func (c *Client) MarkChatUnread(ctx context.Context, chatID, userID string) error
- func (c *Client) Patch(ctx context.Context, path string, body, out any, opts ...RequestOption) error
- func (c *Client) Post(ctx context.Context, path string, body, out any, opts ...RequestOption) error
- func (c *Client) PostMessage(ctx context.Context, target MessageTarget, post MessagePost) (Message, error)
- func (c *Client) PostReply(ctx context.Context, target MessageTarget, post MessagePost) (Message, error)
- func (c *Client) PreCheckEvent(ctx context.Context, eventID string) (EventPreCheck, error)
- func (c *Client) React(ctx context.Context, target MessageTarget, reaction string, remove bool) error
- func (c *Client) RespondEvent(ctx context.Context, eventID string, kind EventResponse, comment string, ...) error
- func (c *Client) SearchEvents(ctx context.Context, query string, from, size int) (SearchResult, error)
- func (c *Client) SearchMessages(ctx context.Context, q SearchQuery) (SearchResult, error)
- func (c *Client) SearchPage(ctx context.Context, query string, from, size int) (SearchResult, error)
- func (c *Client) SearchUsers(ctx context.Context, query string, limit int) ([]User, error)
- func (c *Client) SoftDeleteMessage(ctx context.Context, target MessageTarget) error
- func (c *Client) UpdateEvent(ctx context.Context, eventID string, in EventUpdate) (Event, error)
- func (c *Client) UpdateMessage(ctx context.Context, target MessageTarget, patch MessagePatch) error
- func (c *Client) UploadFile(ctx context.Context, target UploadTarget, name, contentType string, ...) (UploadResult, error)
- type ConversationMember
- type DateTimeTimeZone
- type Download
- type Drive
- type DriveItem
- type EmailAddress
- type ErrorDetail
- type Event
- type EventCreate
- type EventPreCheck
- type EventResponse
- type EventUpdate
- type FileFacet
- type FolderFacet
- type FreeBusyError
- type HostedContent
- type HostedContentUpload
- type Identity
- type IdentitySet
- type ItemBody
- type ItemReference
- type Location
- type Me
- type Mention
- type MentionedIdentitySet
- type Message
- type MessagePatch
- type MessagePost
- type MessageQuery
- type MessageTarget
- type OnlineMeetingInfo
- type Options
- type Page
- type Person
- type Reaction
- type Recipient
- type Recorder
- type Request
- type RequestOption
- type Response
- type ResponseStatus
- type ScheduleInformation
- type ScheduleItem
- type ScoredEmailAddress
- type SearchFilters
- type SearchHit
- type SearchQuery
- type SearchResource
- type SearchResult
- type SearchSender
- type Sleeper
- type Team
- type TeamworkUserIdentity
- type TimeSlot
- type TimeoutError
- type TokenSource
- type TokenSourceFunc
- type UploadResult
- type UploadTarget
- type UsageError
- type User
- type WorkingHours
Constants ¶
const ( DefaultScheduleInterval = 30 MinScheduleInterval = 5 MaxScheduleInterval = 1440 )
DefaultScheduleInterval is the documented default availabilityView interval in minutes; the documented range is 5 to 1440 (refs/graph/api-reference/v1.0/api/calendar-getschedule.md:44).
const ( RoleOwner = "owner" RoleGuest = "guest" )
Chat member roles. The docs allow exactly two and require one on every member of a new chat: "Each member must be assigned a role of owner or guest" (refs/graph/api-reference/v1.0/api/chat-post.md:47). The CLI always sends owner: `member` is not an accepted value in the delegated flow, and a guest role is a tenant decision the CLI cannot make on the user's behalf.
const ( ChatTypeOneOnOne = "oneOnOne" ChatTypeGroup = "group" )
ChatTypes the create endpoint accepts. The chat *resource* also knows meeting and unknownFutureValue, but a create only takes these two (refs/graph/api-reference/v1.0/api/chat-post.md:50 against refs/graph/api-reference/v1.0/resources/chat.md:67).
const ( // DefaultTimeout bounds ONE request attempt: connect, TLS, request, response // body. Without it a stalled connection - a VPN handoff, a proxy that accepts // and never answers, a dropped SYN - blocks the CLI forever, because neither // http.DefaultClient nor context.Background() has a deadline. Graph documents // no per-request timeout; 60s is generous for a single page of messages and // still short enough that a user sees an error instead of a mystery hang. DefaultTimeout = 60 * time.Second DefaultMaxRetries = 3 DefaultBaseDelay = 500 * time.Millisecond DefaultMaxDelay = 8 * time.Second DefaultMaxRetryFor = 60 * time.Second )
Default retry policy. Graph documents 429 with Retry-After as the throttle signal and exponential backoff when the header is missing (refs/graph/concepts/throttling.md:82-95). Jitter is our choice: the mirror documents none.
const ( DefaultTopMessages = 20 MaxTopMessages = 50 MaxTopChats = 50 MaxTopMembers = 999 DefaultTopMembers = 100 MaxTopSearch = 50 DefaultTopSearch = 25 MaxTopPeople = 999 DefaultTopPeople = 25 )
Documented pagination limits. Channel messages and replies cap $top at 50, chat listings at 50, member listings at 999, and a chatMessage search page at 50 for the live service (the docs cap mail and events at 25).
Refs: refs/graph/api-reference/v1.0/api/channel-list-messages.md:33, chatmessage-list-replies.md:41, chat-list-messages.md:47, chat-list.md:63, team-list-members.md:45, docs/spike/phase1.md:75.
const AttendeeTypeRequired = "required"
AttendeeTypeRequired is the attendee type `calendar create` sends. The CLI has no "--optional" flag, so every attendee is required.
const CalendarEventPath = "/me/calendar/events"
CalendarEventPath is the documented create path. The api-reference documents POST /me/calendar/events, not POST /me/events (refs/graph/api-reference/v1.0/api/calendar-post-events.md:12).
const CalendarViewTop = 100
CalendarViewTop is the page size every calendarView call sends. The documented default is 10, which is far too small for a day, and the live service accepted 1000 (handoff §3, F2). The list.go comment block records the other ceilings.
const EventPreCheckSelect = "isOrganizer,allowNewTimeProposals,isOnlineMeeting,onlineMeeting,subject"
EventPreCheckSelect is the $select the pre-check uses.
const MaxBatchRequests = 20
MaxBatchRequests is the documented limit for /$batch (refs/graph/concepts/json-batching.md:17).
const MaxCalendarViewDays = 1825
MaxCalendarViewDays is the largest calendarView range the live service accepts: 1826 days is a 400 ErrorInvalidRequest (handoff §3, F2). The CLI caps its own window lower so the one-day widening on each side still fits.
const MaxPages = 1000
MaxPages is a safety valve: a server that keeps returning a next link must not hang the CLI forever.
const MaxQuotedMessages = 10
MaxQuotedMessages is the documented cap on replyWithQuote's messageIds (refs/graph/api-reference/v1.0/api/chatmessage-replywithquote.md:18).
const MaxScheduleAddresses = 20
MaxScheduleAddresses is the documented maximum number of schedules one getSchedule call takes (refs/graph/api-reference/v1.0/api/calendar-getschedule.md:40). GetSchedule chunks larger sets into calls of this size.
const MaxScheduleDays = 62
MaxScheduleDays is the largest getSchedule range: 63 days is a 400 ErrorTimeIntervalTooBig (handoff §3, F7). It is not in the docs.
const NoMailboxResponseCode = "5016"
NoMailboxResponseCode is the responseCode a schedule carries when the mailbox could not be resolved at all: no mailbox, inactive, on-premises, or no such user (verified live 2026-10-05, handoff §3, F7).
const OnlineMeetingProviderTeams = "teamsForBusiness"
OnlineMeetingProviderTeams is the documented provider value for a Teams meeting (refs/graph/api-reference/v1.0/resources/event.md).
const PreferUnknownEnumMembers = "include-unknown-enum-members"
PreferUnknownEnumMembers is the Prefer header value that makes evolvable enums work: without it Graph collapses new members to `unknownFutureValue`, so `systemEventMessage` never appears in a parsed messageType (refs/graph/api-reference/v1.0/resources/chatmessage.md:81; confirmed in docs/spike/phase1.md:54).
const SimpleUploadMaxSize = 4 << 20
SimpleUploadMaxSize is the size at or below which a file is uploaded in one PUT. Exactly this size is still simple, which is the MCP's comparison (size <= SIMPLE_UPLOAD_MAX_SIZE, refs/teams-mcp/src/utils/file-upload.ts:228).
const UploadChunkSize = 10 * 320 * 1024
UploadChunkSize is the chunk size of a large upload: ten 320 KiB blocks, the documented granularity of an upload session.
Variables ¶
This section is empty.
Functions ¶
func AllowsTeamsMeetings ¶ added in v1.1.0
AllowsTeamsMeetings reports whether a provider list contains teamsForBusiness.
func ChannelMessagePath ¶
ChannelMessagePath is the Graph path of one channel message. It is exported because the file-download and inline-image reads address a message by path.
func ChatFilterTopic ¶
ChatFilterTopic builds the documented $filter for a chat topic.
func ChatFilterType ¶
ChatFilterType builds the documented $filter for a chat type.
func ChatMessagePath ¶
ChatMessagePath is the Graph path of one chat message. The /chats form is the one the api-reference documents for every chat message operation, and it is equivalent to /me/chats for a delegated caller.
func EachPage ¶
func EachPage[T any](ctx context.Context, c *Client, path string, q url.Values, fn func(Page[T]) (bool, error), opts ...RequestOption) error
EachPage walks every page, following @odata.nextLink verbatim as documented (refs/graph/concepts/paging.md:91). fn returns false to stop early. The next link carries its own query parameters, so it is requested without ours.
func EventIDFromHitID ¶ added in v1.1.0
EventIDFromHitID converts a search hitId into the event id the REST endpoints accept.
The two differ only in the base64 alphabet: the search service reports the id in the standard alphabet, where "/" and "+" are illegal in a URL path, and the REST endpoints are addressed with the URL-safe alphabet. So the conversion is exactly two character substitutions — the value is NOT base64-decoded, because the id *is* the encoded string.
This is observed behaviour, not documented: it was verified live on 2026-10-05 (handoff §3, F8). Getting it wrong is quiet rather than loud — a decoded id becomes a URL with NUL bytes in it, Graph answers 400, and every hit is dropped — which is why the live run of a real tenant found it and the fake, which encoded the id the same wrong way, did not.
The bool reports whether the value is usable as an event id at all: an empty hitId is not.
func IsBadRequest ¶
IsBadRequest reports whether err is a Graph 400.
func IsUnauthorized ¶
IsUnauthorized reports whether err is a Graph 401.
func Items ¶
func Items[T any](ctx context.Context, c *Client, path string, q url.Values, opts ...RequestOption) iter.Seq2[T, error]
Items returns a lazy iterator over every element of a collection, paging underneath. It exists so commands can `for item, err := range graph.Items[Chat](...)` and stop early without fetching the rest (PLAN.md "paging.go").
func ListAll ¶
func ListAll[T any](ctx context.Context, c *Client, path string, q url.Values, limit int, opts ...RequestOption) ([]T, error)
ListAll pages a collection and returns at most limit items, following @odata.nextLink as the docs require ("Follow pagination everywhere", refs/graph/concepts/paging.md:91). A limit of 0 means every item.
The result keeps whatever order Graph returned; callers that render a listing sort it themselves, because PLAN.md records that the default order of message listings is neither created- nor modified-sorted.
func ODataQuote ¶
ODataQuote quotes a string literal for an OData $filter. The docs require a single quote inside a literal to be doubled, which the MCP never does (refs/graph/concepts/query-parameters.md, "Filter parameter"; PLAN.md "Escape ' in OData $filter user search by doubling it").
func RequestIDOf ¶
RequestIDOf returns the Graph request id carried by err, for support tickets.
func StripDashes ¶
StripDashes removes the hyphens from a GUID, which the mentions: term requires (refs/graph/concepts/search-concept-chat-messages.md:267).
func UserFilterDisplayName ¶
UserFilterDisplayName builds the documented startswith filter on displayName. The literal is escaped by doubling single quotes (refs/graph/concepts/query-parameters.md, "Filter parameter").
func UserFilterMail ¶
UserFilterMail builds the startswith filter on mail.
func UserFilterUserPrincipalName ¶
UserFilterUserPrincipalName builds the startswith filter on userPrincipalName.
Types ¶
type APIError ¶
type APIError struct {
Method string
URL string
Status int
// Code is error.code, for example Authorization_RequestDenied or
// TooManyRequests. It is empty for the batch sample where Graph sends "".
Code string
Message string
Target string
Details []ErrorDetail
// InnerError fields, when present.
InnerCode string
InnerMessage string
InnerStatusCode string
RequestID string
ClientRequestID string
// RetryAfter is the parsed Retry-After header (or the innerError value).
RetryAfter time.Duration
// Claims is the claims challenge of a 401 from continuous access evaluation (CAE): the token was revoked (a
// policy changed, the user's session was revoked…) and a new one must be requested with these claims
// (refs/entra/docs/identity-platform/claims-challenge.md). Decoded JSON; empty when there is none.
Claims string
Header http.Header
// Body is the raw response body for `-v` diagnostics and tests. It may
// contain message content, so it is never printed by default.
Body []byte
}
APIError is a non-2xx Graph response, decoded from the documented envelope
{"error":{"code":…,"message":…,"target":…,"details":[…],
"innerError":{"code":…,"message":…,"date":…,
"request-id":…,"client-request-id":…}}}
(refs/graph/concepts/json-batching.md:165-175, refs/graph/concepts/throttling.md:59-71, refs/openapi/openapi/v1.0/openapi.yaml:941229-941276). innerError is optional and the body may not be JSON at all, so every field is best-effort.
type Attachment ¶
type Attachment struct {
ID string `json:"id,omitempty"`
ContentType string `json:"contentType,omitempty"`
ContentURL string `json:"contentUrl,omitempty"`
Content string `json:"content,omitempty"`
Name string `json:"name,omitempty"`
ThumbnailURL string `json:"thumbnailUrl,omitempty"`
TeamsAppID string `json:"teamsAppId,omitempty"`
}
Attachment is chatMessageAttachment (refs/graph/api-reference/v1.0/resources/chatmessageattachment.md).
type Attendee ¶ added in v1.1.0
type Attendee struct {
EmailAddress *EmailAddress `json:"emailAddress,omitempty"`
Status *ResponseStatus `json:"status,omitempty"`
Type string `json:"type,omitempty"`
}
Attendee is microsoft.graph.attendee (refs/graph/api-reference/v1.0/resources/attendee.md).
func (Attendee) DisplayName ¶ added in v1.1.0
DisplayName is the attendee's name, falling back to the address.
type BatchItemResponse ¶
type BatchItemResponse struct {
ID string `json:"id"`
Status int `json:"status"`
Headers map[string]string `json:"headers"`
// Body is the raw sub-response body; it is JSON for our endpoints.
Body json.RawMessage `json:"body"`
}
BatchItemResponse is one sub-response.
func (BatchItemResponse) Decode ¶
func (r BatchItemResponse) Decode(v any) error
Decode unmarshals the sub-response body into v.
func (BatchItemResponse) Err ¶
func (r BatchItemResponse) Err(req BatchRequest) error
Err returns an *APIError when the sub-response is not a success, and nil otherwise. The message and code come from the same error envelope a normal response would carry.
type BatchRequest ¶
type BatchRequest struct {
// ID correlates the response; it must be unique within the batch.
ID string
// Method is an HTTP method.
Method string
// Path is a Graph path relative to the service root ("/me/chats"), or an
// absolute URL for a next link.
Path string
// Query adds query parameters to Path.
Query map[string]string
// Headers are copied into the sub-request. Content-Type is added
// automatically when Body is set, as the docs require (:52).
Headers map[string]string
// Body is marshalled as JSON.
Body any
}
BatchRequest is one sub-request.
type Channel ¶
type Channel struct {
ID string `json:"id"`
DisplayName string `json:"displayName"`
Description string `json:"description,omitempty"`
MembershipType string `json:"membershipType,omitempty"`
WebURL string `json:"webUrl,omitempty"`
Email string `json:"email,omitempty"`
CreatedDateTime time.Time `json:"createdDateTime,omitzero"`
}
Channel is microsoft.graph.channel (refs/graph/api-reference/v1.0/resources/channel.md).
type ChannelIdentity ¶
type ChannelIdentity struct {
ChannelID string `json:"channelId,omitempty"`
TeamID string `json:"teamId,omitempty"`
}
ChannelIdentity is channelIdentity, present on a channel message (refs/graph/api-reference/v1.0/resources/channelidentity.md).
type Chat ¶
type Chat struct {
ID string `json:"id"`
ChatType string `json:"chatType,omitempty"`
Topic *string `json:"topic,omitempty"`
CreatedDateTime time.Time `json:"createdDateTime,omitzero"`
LastUpdatedDateTime time.Time `json:"lastUpdatedDateTime,omitzero"`
TenantID string `json:"tenantId,omitempty"`
WebURL string `json:"webUrl,omitempty"`
Viewpoint *ChatViewpoint `json:"viewpoint,omitempty"`
Members []ConversationMember `json:"members,omitempty"`
LastMessagePreview *Message `json:"lastMessagePreview,omitempty"`
}
Chat is microsoft.graph.chat (refs/graph/api-reference/v1.0/resources/chat.md). Members and LastMessagePreview are present only when the caller asked for the matching $expand; Viewpoint comes with every delegated listing.
func (Chat) LastActivity ¶
LastActivity is when the chat last moved: its newest message when the preview was expanded, otherwise the chat's own lastUpdatedDateTime. A chat with neither (no messages at all) reports the zero time, which any window treats as "older than everything".
func (Chat) Title ¶
func (c Chat) Title(other ...ConversationMember) string
Title is what a chat is called: its topic for a group chat, otherwise the other members' names.
type ChatCreate ¶
type ChatCreate struct {
// ChatType is "oneOnOne" or "group". One-on-one is unique: creating one for
// a pair that already has one returns the existing chat
// (refs/graph/api-reference/v1.0/api/chat-post.md:16).
ChatType string
// Topic is only valid on a group chat (:47).
Topic string
// Members must list everyone, including the caller (:47).
Members []ChatMemberSpec
}
ChatCreate is the body of a chat create.
type ChatMemberSpec ¶
type ChatMemberSpec struct {
// UserID is the participant's directory object id.
UserID string
// DisplayName is the participant's name, used by the CLI to report who was
// added. Graph takes the name from the directory, so it is never sent.
DisplayName string
// Roles are the conversation roles; empty means owner.
Roles []string
}
ChatMemberSpec is one participant of a chat to create.
type ChatQuery ¶
type ChatQuery struct {
// Top is the requested $top per page; it is clamped to the documented 50.
Top int
// Limit caps the total number of chats (0 means every page).
Limit int
// Members asks for $expand=members, which the docs cap at 25 member items
// per chat regardless of $top (refs/graph/api-reference/v1.0/api/chat-list.md:20).
Members bool
// LastMessagePreview asks for $expand=lastMessagePreview, which carries the
// newest message and is what makes the unread rule computable.
LastMessagePreview bool
// OrderByLastMessage asks for $orderby=lastMessagePreview/createdDateTime
// desc, the only ordering the API supports (refs/graph/api-reference/v1.0/api/chat-list.md:63).
OrderByLastMessage bool
// Filter is a raw OData $filter (topic eq '...' / chatType eq '...'), which
// the API documents but does not enumerate.
Filter string
// Since keeps only chats whose last activity is at or after it, and stops
// paging as soon as one is older: the listing is ordered by
// lastMessagePreview/createdDateTime desc, so everything after it is older
// too. It is what keeps `teams unread` to one round trip instead of walking
// every chat in the tenant.
Since time.Time
}
ChatQuery describes a chat listing.
type ChatViewpoint ¶
type ChatViewpoint struct {
IsHidden *bool `json:"isHidden,omitempty"`
LastMessageReadDateTime *time.Time `json:"lastMessageReadDateTime,omitempty"`
}
ChatViewpoint is chatViewpoint, the per-user read state of a chat. Only List chats returns it, and only for delegated callers (refs/graph/api-reference/v1.0/resources/chatviewpoint.md).
type ClaimsTokenSource ¶ added in v1.1.1
type ClaimsTokenSource interface {
TokenSource
TokenWithClaims(ctx context.Context, claims string) (string, error)
}
ClaimsTokenSource is a TokenSource that can answer a claims challenge: a new token requested with the claims a 401 from continuous access evaluation carried (internal/auth implements it). The cached token is then not used.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a Graph HTTP client.
func (*Client) AddChatMember ¶
func (c *Client) AddChatMember(ctx context.Context, chatID, userID string, roles []string) (ConversationMember, error)
AddChatMember adds one member to an existing chat and returns the created member (the documented 201). The role defaults to owner for the same reason CreateChat's does.
func (*Client) AllowedOnlineMeetingProviders ¶ added in v1.1.0
AllowedOnlineMeetingProviders returns the mailbox's GET /me/calendar -> allowedOnlineMeetingProviders values (refs/graph/api-reference/v1.0/api/calendar-get.md).
Phase 6b checks it before `create --teams`: a mailbox without teamsForBusiness accepts isOnlineMeeting: true with a 201 and silently drops the meeting, so the CLI refuses up front instead (verified live 2026-10-05, handoff §3, F10).
func (*Client) Batch ¶
func (c *Client) Batch(ctx context.Context, reqs []BatchRequest) (map[string]BatchItemResponse, error)
Batch sends the sub-requests in one call and returns the responses keyed by id: the documented order is not guaranteed, so callers must not rely on it.
A sub-request failure is not an error here — it is reported per item, because that is how Graph reports it. Callers check BatchItemResponse.Err and can retry a throttled item themselves, using the retry-after value from its own response.
func (*Client) BatchOrdered ¶
func (c *Client) BatchOrdered(ctx context.Context, reqs []BatchRequest) ([]BatchItemResponse, error)
BatchOrdered is Batch plus a slice in the request order, for callers that want stable output.
func (*Client) CancelEvent ¶ added in v1.1.0
CancelEvent cancels an event the caller organizes (POST /me/events/{event-id}/cancel). The organizer's attendees get a cancellation notice.
func (*Client) CreateChat ¶
CreateChat creates a chat and returns it. The response is the documented 201 with the chat resource, including its members.
func (*Client) CreateEvent ¶ added in v1.1.0
CreateEvent posts a new event (POST /me/calendar/events).
A transactionId makes the call safe to retry: re-posting the same body with the same transactionId returns the same event instead of creating a second one (verified live 2026-10-05, handoff §3, F10).
func (*Client) CreateShareLink ¶
func (c *Client) CreateShareLink(ctx context.Context, driveID, itemID, scope string) (string, error)
CreateShareLink asks for a view link to a drive item and returns its URL. The request is the documented one (refs/graph/api-reference/v1.0/api/driveitem-createlink.md:37).
func (*Client) DeleteChat ¶
DeleteChat deletes a chat (DELETE /chats/{chat-id}, 204 No Content).
The scope it needs, Chat.ManageDeletion.All, is admin-consented and is not in any preset: the CLI asks for it incrementally when this command runs (internal/config/scopes.go, IncrementalScopes).
func (*Client) DeleteEvent ¶ added in v1.1.0
DeleteEvent deletes an event. Deleting an event you organize sends cancellations to its attendees (refs/graph/api-reference/v1.0/api/event-delete.md).
func (*Client) Do ¶
Do performs the request, retrying per the documented throttling rules, and returns the raw response. A non-2xx response comes back as *APIError.
func (*Client) DownloadDriveItemContent ¶
func (c *Client) DownloadDriveItemContent(ctx context.Context, driveID, itemID string) (Download, error)
DownloadDriveItemContent fetches a file's bytes (refs/graph/api-reference/v1.0/api/driveitem-get-content.md). Graph answers with a 302 to a pre-authenticated URL; Go's HTTP client follows it, and it drops the Authorization header when the redirect leaves the Graph host, which is exactly the documented behaviour of that URL.
func (*Client) FindMeetingChatID ¶ added in v1.1.0
FindMeetingChatID resolves a Teams meeting's chat thread id from the join URL of an event (GET /me/onlineMeetings with a JoinWebUrl filter, refs/graph/api-reference/v1.0/api/onlinemeeting-get.md).
The filter value must be the joinUrl exactly as Graph returned it, percent escapes included: it is quoted with ODataQuote and url.Values does the encoding (handoff §3, F9).
A join URL that matches nothing is NOT an empty list: Graph answers 400 with code BadRequest and a message starting "1026" (verified live 2026-10-05, handoff §3, F9). That is "no chat found", not a failure, so this returns ("", nil) for any 400 and logs the reason under -v.
func (*Client) GetChannel ¶
GetChannel returns one channel (GET /teams/{team-id}/channels/{channel-id}, refs/graph/api-reference/v1.0/api/channel-get.md).
func (*Client) GetChannelMessage ¶
func (c *Client) GetChannelMessage(ctx context.Context, teamID, channelID, messageID string) (Message, error)
GetChannelMessage returns one root message (refs/graph/api-reference/v1.0/api/chatmessage-get.md).
func (*Client) GetChannelReply ¶
func (c *Client) GetChannelReply(ctx context.Context, teamID, channelID, messageID, replyID string) (Message, error)
GetChannelReply returns one reply of a channel message (refs/graph/api-reference/v1.0/api/chatmessage-get.md).
func (*Client) GetChat ¶
GetChat returns one chat (GET /me/chats/{chat-id}, refs/graph/api-reference/v1.0/api/chat-get.md). Members asks for $expand=members so the caller can name the other participants.
func (*Client) GetChatMessage ¶
GetChatMessage returns one chat message (refs/graph/api-reference/v1.0/api/chatmessage-get.md).
func (*Client) GetDefaultDrive ¶
GetDefaultDrive returns the signed-in user's drive (GET /me/drive, refs/graph/api-reference/v1.0/api/drive-get.md:38), which is where a chat attachment goes.
func (*Client) GetDriveItem ¶
func (c *Client) GetDriveItem(ctx context.Context, driveID, itemID string, withWebDavURL bool) (DriveItem, error)
GetDriveItem returns one item's metadata (refs/graph/api-reference/v1.0/api/driveitem-get.md). withWebDavURL asks for $select=webDavUrl, which PLAN.md:246 prefers for channel file attachments.
func (*Client) GetEvent ¶ added in v1.1.0
GetEvent returns one event by id (GET /me/events/{event-id}, refs/graph/api-reference/v1.0/api/event-get.md). selectFields "" means the full event; the Phase 6b pre-check passes eventPreCheckSelect to keep the read cheap.
Unlike calendarView, this endpoint returns onlineMeeting without isOnlineMeeting being selected (verified live 2026-10-05, handoff §3, F3).
func (*Client) GetFilesFolder ¶
GetFilesFolder returns a channel's files folder (refs/graph/api-reference/v1.0/api/channel-get-filesfolder.md).
func (*Client) GetHostedContentValue ¶
func (c *Client) GetHostedContentValue(ctx context.Context, messagePath, contentID string) (Download, error)
GetHostedContentValue returns one inline image's bytes and content type (refs/graph/api-reference/v1.0/api/chatmessagehostedcontent-get.md).
func (*Client) GetMe ¶
GetMe returns the signed-in user (GET /me, User.Read).
A chat message's soft delete and chat creation both need the caller's own id: the documented delete route is user-relative, and a chat must list every participant including the caller (refs/graph/api-reference/v1.0/api/chatmessage-softdelete.md:58, refs/graph/api-reference/v1.0/api/chat-post.md:47).
func (*Client) GetSchedule ¶ added in v1.1.0
func (c *Client) GetSchedule(ctx context.Context, mails []string, start, end time.Time, zone string, interval int) ([]ScheduleInformation, error)
GetSchedule calls POST /me/calendar/getSchedule for up to MaxScheduleAddresses addresses at a time and returns the schedules in the order they were asked for.
start and end are rendered as a wall clock in zone plus the zone's own name, which is the form the live service accepted ("Asia/Tokyo" worked); the response comes back in UTC regardless (verified live 2026-10-05, handoff §3, F7). An interval outside the documented 5..1440 is clamped.
func (*Client) GetTeam ¶
GetTeam returns one team (GET /teams/{team-id}, refs/graph/api-reference/v1.0/api/team-get.md).
func (*Client) GetUser ¶
GetUser returns one user by id, user principal name or mail (GET /users/{user-id}, refs/graph/api-reference/v1.0/api/user-get.md).
func (*Client) ListCalendarView ¶ added in v1.1.0
func (c *Client) ListCalendarView(ctx context.Context, userID string, start, end time.Time, fn func(Event) bool) error
ListCalendarView calls GET /me/calendarView (userID "") or GET /users/{userID}/calendarView and calls fn for every event, following @odata.nextLink. fn returns false to stop early.
The window is sent as RFC3339 with an offset, which the live service honours (verified live 2026-10-05, handoff §3, F2). Callers must widen it by a day on each side and filter the result themselves: all-day events are floating and the server matches them to the window as UTC midnight to midnight (handoff §3, F5). No Prefer: outlook.timezone is sent (decision D4).
func (*Client) ListChannelFiles ¶
func (c *Client) ListChannelFiles(ctx context.Context, teamID, channelID string) (folder DriveItem, items []DriveItem, err error)
ListChannelFiles returns the children of a channel's files folder, which is the "channel files" listing PLAN.md specifies. It resolves the filesFolder (GET /teams/{team-id}/channels/{channel-id}/filesFolder, refs/graph/api-reference/v1.0/api/channel-get-filesfolder.md) and then lists its children (refs/graph/api-reference/v1.0/api/driveitem-list-children.md).
func (*Client) ListChannelMessages ¶
func (c *Client) ListChannelMessages(ctx context.Context, teamID, channelID string, q MessageQuery) ([]Message, error)
ListChannelMessages returns a channel's root messages (GET /teams/{team-id}/channels/{channel-id}/messages, refs/graph/api-reference/v1.0/api/channel-list-messages.md:65).
The endpoint supports only $top (default 20, max 50) and $expand; $filter is a 400, not a silent ignore (docs/spike/phase1.md:53), so a --since window is applied here. Roots are ordered by "the last modified date of the entire reply chain", so the scan stops at the first chain older than --since and the result is sorted by the same key with the message id as a tie-break.
func (*Client) ListChannelReplies ¶
func (c *Client) ListChannelReplies(ctx context.Context, teamID, channelID, messageID string, q MessageQuery) ([]Message, error)
ListChannelReplies returns the replies of a channel message. $top caps at 50 here (refs/graph/api-reference/v1.0/api/chatmessage-list-replies.md:41).
func (*Client) ListChannels ¶
ListChannels returns a team's channels (GET /teams/{team-id}/channels, refs/graph/api-reference/v1.0/api/channel-list.md).
func (*Client) ListChatMembers ¶
ListChatMembers returns a chat's members (GET /chats/{chat-id}/members, refs/graph/api-reference/v1.0/api/chat-list-members.md).
func (*Client) ListChatMessages ¶
func (c *Client) ListChatMessages(ctx context.Context, chatID string, q MessageQuery) ([]Message, error)
ListChatMessages returns a chat's messages (GET /chats/{chat-id}/messages, refs/graph/api-reference/v1.0/api/chat-list-messages.md:47).
This endpoint, unlike the channel one, filters on the server: $orderby on lastModifiedDateTime (the default) or createdDateTime descending, and a $filter that is silently ignored unless $orderby names the same property. A --since window therefore uses lastModifiedDateTime gt, which returns a superset when a message was edited, and the result is re-checked on createdDateTime (PLAN.md:183).
func (*Client) ListChats ¶
ListChats returns the signed-in user's chats (GET /me/chats, refs/graph/api-reference/v1.0/api/chat-list.md).
func (*Client) ListDriveItemChildren ¶
func (c *Client) ListDriveItemChildren(ctx context.Context, driveID, itemID string, limit int) ([]DriveItem, error)
ListDriveItemChildren returns a folder's children (refs/graph/api-reference/v1.0/api/driveitem-list-children.md).
func (*Client) ListJoinedTeams ¶
ListJoinedTeams returns the teams the signed-in user is a member of (GET /me/joinedTeams, refs/graph/api-reference/v1.0/api/user-list-joinedteams.md).
No query parameters. The page says "This method doesn't currently support the OData query parameters to customize the response" (user-list-joinedteams.md:39), and a live tenant answers 400 "Query option 'Top' is not allowed" for exactly that. Paging still follows @odata.nextLink, which is what PLAN.md:230 requires.
func (*Client) ListMessageHostedContents ¶
func (c *Client) ListMessageHostedContents(ctx context.Context, messagePath string) ([]HostedContent, error)
ListMessageHostedContents returns the inline images of a message, addressed by the message path built with ChannelMessagePath or ChatMessagePath (refs/graph/api-reference/v1.0/api/chatmessage-list-hostedcontents.md).
func (*Client) ListPeople ¶
ListPeople returns relevance-ranked people (GET /me/people, refs/graph/api-reference/v1.0/api/user-list-people.md). The $search value is quoted because that is the documented form, and it is a fuzzy match, which is what makes "@yuki" mean the Yuki you work with.
func (*Client) ListTeamMembers ¶
ListTeamMembers returns a team's members. The docs imply no paging here, but the spike saw @odata.nextLink at $top=5, so the shared pager is used and is harmless when no link comes back (PLAN.md:230, docs/spike/phase1.md:50). The documented default and maximum page sizes are 100 and 999 (refs/graph/api-reference/v1.0/api/team-list-members.md:45).
func (*Client) ListUsers ¶
ListUsers returns directory users matching a raw OData $filter (GET /users, refs/graph/api-reference/v1.0/api/user-list.md). limit of 0 pages everything.
func (*Client) MarkChatRead ¶
MarkChatRead marks a chat read for one user (POST /chats/{chat-id}/markChatReadForUser, 204).
func (*Client) MarkChatUnread ¶
MarkChatUnread marks a chat unread for one user (POST /chats/{chat-id}/markChatUnreadForUser, 204). Leaving lastMessageReadDateTime out is documented as "the last message would be marked as unread" (refs/graph/api-reference/v1.0/api/chat-markchatunreadforuser.md:47).
func (*Client) Patch ¶
func (c *Client) Patch(ctx context.Context, path string, body, out any, opts ...RequestOption) error
Patch issues a PATCH.
func (*Client) PostMessage ¶
func (c *Client) PostMessage(ctx context.Context, target MessageTarget, post MessagePost) (Message, error)
PostMessage creates a message in a channel or a chat.
func (*Client) PostReply ¶
func (c *Client) PostReply(ctx context.Context, target MessageTarget, post MessagePost) (Message, error)
PostReply replies in a channel thread, or quote-replies in a chat (see the file comment). A chat reply quotes exactly the message being replied to.
func (*Client) PreCheckEvent ¶ added in v1.1.0
PreCheckEvent reads the three fields the write pre-checks need.
func (*Client) React ¶
func (c *Client) React(ctx context.Context, target MessageTarget, reaction string, remove bool) error
React sets or removes one reaction on a message. remove selects unsetReaction.
The reaction is a free-form string because the docs define reactionType as the reaction's unicode character, with "like" as the one named example (refs/graph/api-reference/v1.0/api/chatmessage-setreaction.md:68-71).
func (*Client) RespondEvent ¶ added in v1.1.0
func (c *Client) RespondEvent(ctx context.Context, eventID string, kind EventResponse, comment string, sendResponse bool, propose *TimeSlot, zone string) error
RespondEvent accepts, tentatively accepts or declines an event.
comment and sendResponse are always sent; propose is optional and only the tentative and decline responses document it. A proposed time with sendResponse: false is a 400 ErrorInvalidParameter, which the CLI refuses up front (plans/calendar.md §4.7, §4.5).
func (*Client) SearchEvents ¶ added in v1.1.0
func (c *Client) SearchEvents(ctx context.Context, query string, from, size int) (SearchResult, error)
SearchEvents runs one event search and returns hits whose ID is already the REST id (POST /search/query with entityTypes ["event"]).
Search covers the signed-in user's primary calendar only, takes at most 25 results per page, does not sort, and its total counts the page, not the matches (refs/graph/concepts/search-concept-events.md:97-98).
func (*Client) SearchMessages ¶
func (c *Client) SearchMessages(ctx context.Context, q SearchQuery) (SearchResult, error)
SearchMessages runs one chatMessage search. An empty query string is a usage error here rather than a round trip that Graph would reject with 400.
func (*Client) SearchPage ¶
func (c *Client) SearchPage(ctx context.Context, query string, from, size int) (SearchResult, error)
SearchPage fetches one page, which is how the CLI pages a search: the API has no next link, so the offset is explicit.
func (*Client) SearchUsers ¶
SearchUsers runs the two-step directory search the CLI exposes as "teams user search": a startswith filter on displayName first, then on userPrincipalName and mail when the first attempt found nothing. Graph supports one property per startswith filter and OR-combining them is not universally accepted, so the fallback is explicit rather than clever.
func (*Client) SoftDeleteMessage ¶
func (c *Client) SoftDeleteMessage(ctx context.Context, target MessageTarget) error
SoftDeleteMessage removes a message the way Teams does: the message keeps its id and gains a deletedDateTime, and drops out of listings and search (refs/graph/api-reference/v1.0/api/chatmessage-softdelete.md).
func (*Client) UpdateEvent ¶ added in v1.1.0
UpdateEvent patches an event with only the fields the caller set (PATCH /me/events/{event-id}).
As a non-organizer the call succeeds but changes only the caller's own copy, and the organizer's next update overwrites it, so the CLI refuses that case unless --local-copy was passed (verified live 2026-10-05, handoff §3, F10).
func (*Client) UpdateMessage ¶
func (c *Client) UpdateMessage(ctx context.Context, target MessageTarget, patch MessagePatch) error
UpdateMessage edits a message's body (and, when set, its subject). Delegated PATCH answers 204 No Content.
func (*Client) UploadFile ¶
func (c *Client) UploadFile(ctx context.Context, target UploadTarget, name, contentType string, data []byte) (UploadResult, error)
UploadFile uploads a file to a channel's files folder or to the caller's OneDrive (see UploadTarget), and returns what the attachment needs.
The contentType is the caller's decision (internal/format detects it from the bytes and the name) so that a --dry-run can report the same value without a network call.
type ConversationMember ¶
type ConversationMember struct {
ODataType string `json:"@odata.type,omitempty"`
ID string `json:"id"`
DisplayName string `json:"displayName,omitempty"`
Email string `json:"email,omitempty"`
Roles []string `json:"roles,omitempty"`
TenantID string `json:"tenantId,omitempty"`
UserID string `json:"userId,omitempty"`
VisibleHistoryStartDateTime *time.Time `json:"visibleHistoryStartDateTime,omitempty"`
}
ConversationMember is aadUserConversationMember: the member shape both chat and team member listings return (refs/graph/api-reference/v1.0/resources/aaduserconversationmember.md).
type DateTimeTimeZone ¶ added in v1.1.0
type DateTimeTimeZone struct {
DateTime string `json:"dateTime"`
TimeZone string `json:"timeZone,omitempty"`
}
DateTimeTimeZone is microsoft.graph.dateTimeTimeZone, the {dateTime, timeZone} pair every calendar request and response carries (refs/graph/api-reference/v1.0/resources/datetimetimezone.md).
Without a Prefer: outlook.timezone header Graph answers in UTC and the dateTime string carries no offset at all ("2026-10-06T01:00:00.0000000"), which is why UTC has its own layout (handoff §3, F6). The CLI never sends that header: an unknown zone is a hard 400 TimeZoneNotSupportedException rather than a fallback, so reading UTC and converting locally is both simpler and safer (decision D4).
func (DateTimeTimeZone) Date ¶ added in v1.1.0
func (d DateTimeTimeZone) Date() string
Date is the first ten characters of dateTime: the calendar date of a floating all-day event, which must never be time-converted (handoff §3, F5).
func (DateTimeTimeZone) UTC ¶ added in v1.1.0
func (d DateTimeTimeZone) UTC() (time.Time, error)
UTC converts the pair to an instant. The result is always UTC: callers convert to the display location themselves, because the CLI's own timezone rule (--tz, then $TZ, then /etc/localtime) is not Graph's.
type Drive ¶
type Drive struct {
ID string `json:"id"`
DriveType string `json:"driveType,omitempty"`
Name string `json:"name,omitempty"`
WebURL string `json:"webUrl,omitempty"`
}
Drive is the drive resource subset an upload needs (refs/graph/api-reference/v1.0/resources/drive.md).
type DriveItem ¶
type DriveItem struct {
ID string `json:"id"`
Name string `json:"name"`
Size int64 `json:"size,omitempty"`
CreatedDateTime time.Time `json:"createdDateTime,omitzero"`
LastModifiedDateTime time.Time `json:"lastModifiedDateTime,omitzero"`
WebURL string `json:"webUrl,omitempty"`
WebDavURL string `json:"webDavUrl,omitempty"`
ETag string `json:"eTag,omitempty"`
DownloadURL string `json:"@microsoft.graph.downloadUrl,omitempty"`
File *FileFacet `json:"file,omitempty"`
Folder *FolderFacet `json:"folder,omitempty"`
ParentReference *ItemReference `json:"parentReference,omitempty"`
}
DriveItem is the driveItem subset the CLI reads (refs/graph/api-reference/v1.0/resources/driveitem.md).
func (DriveItem) DriveID ¶
DriveID is the drive a driveItem lives in, taken from its parentReference. The filesFolder response documents parentReference.driveId as the way to address the item afterwards (refs/graph/api-reference/v1.0/resources/driveitem.md).
type EmailAddress ¶ added in v1.1.0
type EmailAddress struct {
Name string `json:"name,omitempty"`
Address string `json:"address,omitempty"`
}
EmailAddress is microsoft.graph.emailAddress, which an organizer, an attendee and a free/busy schedule address all use (refs/graph/api-reference/v1.0/resources/emailaddress.md).
type ErrorDetail ¶
type ErrorDetail struct {
Code string `json:"code"`
Message string `json:"message"`
Target string `json:"target"`
}
ErrorDetail mirrors error.details[].
type Event ¶ added in v1.1.0
type Event struct {
ID string `json:"id"`
Subject string `json:"subject,omitempty"`
Start DateTimeTimeZone `json:"start"`
End DateTimeTimeZone `json:"end"`
IsAllDay bool `json:"isAllDay,omitempty"`
IsCancelled bool `json:"isCancelled,omitempty"`
ShowAs string `json:"showAs,omitempty"`
Organizer *Recipient `json:"organizer,omitempty"`
IsOrganizer bool `json:"isOrganizer,omitempty"`
Location *Location `json:"location,omitempty"`
// IsOnlineMeeting must stay in $select or calendarView omits
// onlineMeeting entirely (verified live 2026-10-05, handoff §3, F3).
IsOnlineMeeting bool `json:"isOnlineMeeting,omitempty"`
OnlineMeeting *OnlineMeetingInfo `json:"onlineMeeting,omitempty"`
OnlineMeetingProvider string `json:"onlineMeetingProvider,omitempty"`
ResponseStatus *ResponseStatus `json:"responseStatus,omitempty"`
WebLink string `json:"webLink,omitempty"`
// Type is singleInstance, occurrence, exception or seriesMaster.
Type string `json:"type,omitempty"`
// SeriesMasterID is set when this instance belongs to a recurring series.
SeriesMasterID string `json:"seriesMasterId,omitempty"`
// Body and the write-only-ish pre-check fields are requested only by the
// commands that need them (show, and the Phase 6b pre-checks).
Body *ItemBody `json:"body,omitempty"`
Attendees []Attendee `json:"attendees,omitempty"`
AllowNewTimeProposals *bool `json:"allowNewTimeProposals,omitzero"`
ResponseRequested *bool `json:"responseRequested,omitzero"`
OnlineMeetingProviderKnown bool `json:"-"`
TransactionID string `json:"transactionId,omitempty"`
Occurrences []Event `json:"occurrences,omitempty"`
}
Event is the subset of microsoft.graph.event the calendar commands read (refs/graph/api-reference/v1.0/resources/event.md). The $select in calendarViewSelect names exactly these fields plus id.
func (Event) IsTeamsMeeting ¶ added in v1.1.0
IsTeamsMeeting reports whether the meeting is a Teams meeting. Graph can set isOnlineMeeting for a Skype meeting too, so the provider is checked as well (refs/graph/api-reference/v1.0/resources/event.md, "onlineMeetingProvider").
func (Event) SubjectLine ¶ added in v1.1.0
SubjectLine is the event's subject, with the placeholder the CLI prints for an event Graph returned without one.
type EventCreate ¶ added in v1.1.0
type EventCreate struct {
// Subject is the event title.
Subject string
// Start and End are instants; the wire body renders them as a wall clock in
// the event's own zone (plans/calendar.md §4.7).
Start time.Time
// End is the instant the event ends. A zero End means Start plus Duration.
End time.Time
// Duration fills in End when End is zero.
Duration time.Duration
// AllDay makes the event a floating all-day event: both ends are sent as
// midnight of their dates, and the zone is the one the caller names.
AllDay bool
// Zone is the IANA zone name both ends carry.
Zone string
// Attendees are the required attendees; each gets an invitation.
Attendees []Recipient
// Location is the free-text location.
Location string
// Body is the event body; empty means no body property is sent at all.
Body string
// Teams asks for a Teams online meeting. The caller checks the mailbox first
// (plans/calendar.md §3, F10).
Teams bool
// TransactionID deduplicates a retried create (plans/calendar.md §3, F10).
TransactionID string
}
EventCreate is the body of `calendar create`.
type EventPreCheck ¶ added in v1.1.0
type EventPreCheck struct {
IsOrganizer bool
AllowNewTimeProposals bool
IsOnlineMeeting bool
Subject string
}
EventPreCheck is the small read `calendar` writes take before they act, so the CLI can refuse a request Graph would answer with a 400 (plans/calendar.md §4.7).
type EventResponse ¶ added in v1.1.0
type EventResponse string
EventResponse is the kind of response `calendar accept|tentative|decline` sends.
const ( ResponseAccept EventResponse = "accept" ResponseTentative EventResponse = "tentativelyAccept" ResponseDecline EventResponse = "decline" )
The three documented responses (refs/graph/api-reference/v1.0/api/event-accept.md).
type EventUpdate ¶ added in v1.1.0
type EventUpdate struct {
Subject *string
Start *time.Time
End *time.Time
Duration time.Duration
Zone string
Location *string
Body *string
}
EventUpdate is the PATCH body of `calendar update`. Every field is a pointer so "not given" and "given as empty" stay distinguishable: the handoff requires that only the fields the user named are sent (plans/calendar.md §4.7).
type FileFacet ¶
type FileFacet struct {
MimeType string `json:"mimeType,omitempty"`
}
FileFacet is microsoft.graph.file.
type FolderFacet ¶
type FolderFacet struct {
ChildCount int `json:"childCount"`
}
FolderFacet is microsoft.graph.folder.
type FreeBusyError ¶ added in v1.1.0
type FreeBusyError struct {
Message string `json:"message,omitempty"`
ResponseCode string `json:"responseCode,omitempty"`
}
FreeBusyError is microsoft.graph.freeBusyError (refs/graph/api-reference/v1.0/resources/freebusyerror.md).
type HostedContent ¶
type HostedContent struct {
ID string `json:"id"`
ContentType string `json:"contentType,omitempty"`
}
HostedContent is chatMessageHostedContent: an inline image. contentBytes is write-only and never appears in a list response (refs/graph/api-reference/v1.0/resources/chatmessagehostedcontent.md).
type HostedContentUpload ¶
type HostedContentUpload struct {
TemporaryID string `json:"@microsoft.graph.temporaryId"`
ContentBytes string `json:"contentBytes,omitempty"`
ContentType string `json:"contentType,omitempty"`
}
HostedContentUpload is one hostedContents[] entry of a message POST. Graph takes the bytes inline, base64-encoded, and caps a hosted content at 4 MB (refs/graph/api-reference/v1.0/api/chatmessage-post.md:733,851).
func HostedContentUploadFor ¶
func HostedContentUploadFor(temporaryID, contentType string, data []byte) HostedContentUpload
HostedContentUploadFor builds the `hostedContents[]` entry for an inline image.
The temporaryId is what the body must reference as ../hostedContents/{temporaryId}/$value, so the two are built together by the caller, and Graph replaces the temporary id with the real one (refs/graph/api-reference/v1.0/api/chatmessage-post.md:731).
type Identity ¶
type Identity struct {
ID string `json:"id,omitempty"`
DisplayName string `json:"displayName,omitempty"`
}
Identity is microsoft.graph.identity: an id and a display name (refs/graph/api-reference/v1.0/resources/identityset.md).
type IdentitySet ¶
type IdentitySet struct {
User *Identity `json:"user,omitempty"`
Application *Identity `json:"application,omitempty"`
Device *Identity `json:"device,omitempty"`
Conversation *Identity `json:"conversation,omitempty"`
}
IdentitySet is identitySet, which channel messages carry in "from" (refs/graph/api-reference/v1.0/resources/identityset.md).
func (*IdentitySet) Sender ¶
func (s *IdentitySet) Sender() Identity
Sender returns the human behind a message, preferring the user identity and falling back to the application, which is what a bot message carries.
type ItemBody ¶
type ItemBody struct {
Content string `json:"content"`
ContentType string `json:"contentType,omitempty"`
}
ItemBody is itemBody: the message body plus how to read it (refs/graph/api-reference/v1.0/resources/itembody.md). contentType is "html" or "text"; Teams sends HTML whenever the message carries a mention.
type ItemReference ¶
type ItemReference struct {
DriveID string `json:"driveId,omitempty"`
DriveType string `json:"driveType,omitempty"`
ID string `json:"id,omitempty"`
Path string `json:"path,omitempty"`
}
ItemReference is microsoft.graph.itemReference, which tells us the drive a channel's file lives in.
type Location ¶ added in v1.1.0
type Location struct {
DisplayName string `json:"displayName,omitempty"`
}
Location is the part of microsoft.graph.location the CLI renders (refs/graph/api-reference/v1.0/resources/location.md).
type Me ¶
type Me struct {
ID string `json:"id"`
DisplayName string `json:"displayName,omitempty"`
UserPrincipalName string `json:"userPrincipalName,omitempty"`
Mail string `json:"mail,omitempty"`
}
Me is the signed-in user, with the properties a write needs.
type Mention ¶
type Mention struct {
ID int `json:"id"`
MentionText string `json:"mentionText,omitempty"`
Mentioned *MentionedIdentitySet `json:"mentioned,omitempty"`
}
Mention is chatMessageMention. Its id is the index the body's <at id="N"> tag refers to, so the two must always be read together (refs/graph/api-reference/v1.0/resources/chatmessagemention.md).
func (Mention) DisplayName ¶
DisplayName is the name to render for a mention: the mentioned user's display name when Graph sends one, otherwise the text Teams substituted into the body.
type MentionedIdentitySet ¶
type MentionedIdentitySet struct {
Application *Identity `json:"application,omitempty"`
Conversation *Identity `json:"conversation,omitempty"`
Tag *Identity `json:"tag,omitempty"`
User *TeamworkUserIdentity `json:"user,omitempty"`
}
MentionedIdentitySet is chatMessageMentionedIdentitySet (refs/graph/api-reference/v1.0/resources/chatmessagemention.md).
type Message ¶
type Message struct {
ID string `json:"id"`
ReplyToID string `json:"replyToId,omitempty"`
ETag string `json:"etag,omitempty"`
MessageType string `json:"messageType,omitempty"`
CreatedDateTime time.Time `json:"createdDateTime,omitzero"`
LastModifiedDateTime time.Time `json:"lastModifiedDateTime,omitzero"`
LastEditedDateTime *time.Time `json:"lastEditedDateTime,omitempty"`
DeletedDateTime *time.Time `json:"deletedDateTime,omitempty"`
Subject string `json:"subject,omitempty"`
Summary string `json:"summary,omitempty"`
Importance string `json:"importance,omitempty"`
Locale string `json:"locale,omitempty"`
WebURL string `json:"webUrl,omitempty"`
From *IdentitySet `json:"from,omitempty"`
Body ItemBody `json:"body"`
Attachments []Attachment `json:"attachments,omitempty"`
Mentions []Mention `json:"mentions,omitempty"`
Reactions []Reaction `json:"reactions,omitempty"`
HostedContents []HostedContent `json:"hostedContents,omitempty"`
ChannelIdentity *ChannelIdentity `json:"channelIdentity,omitempty"`
ChatID string `json:"chatId,omitempty"`
EventDetail json.RawMessage `json:"eventDetail,omitempty"`
// Replies arrives only through $expand=replies on the channel message list
// (refs/graph/api-reference/v1.0/api/channel-list-messages.md:37); it is not
// a chatMessage property.
Replies []Message `json:"replies,omitempty"`
// RepliesNextLink is replies@odata.nextLink, present when the expansion
// inlined only the first page of a long thread.
RepliesNextLink string `json:"replies@odata.nextLink,omitempty"`
}
Message is chatMessage, the resource every read command renders (refs/graph/api-reference/v1.0/resources/chatmessage.md). Nullable timestamps are pointers, exactly as Graph sends them (null when unset).
func (Message) IsDeleted ¶
IsDeleted reports whether the message was soft-deleted. Soft-deleted messages stay in a listing with a deletedDateTime, and Teams shows a tombstone.
func (Message) IsSystemEvent ¶
IsSystemEvent reports whether Teams generated the message rather than a person (a member added, a call ended, a tab created, ...). Reading it requires the Prefer: include-unknown-enum-members header (refs/graph/api-reference/v1.0/resources/chatmessage.md:81).
func (Message) LastActivity ¶
LastActivity is the timestamp a listing is ordered by: the later of the message's own modification and its newest reply. Channel root messages are documented as sorted by "the last modified date of the entire reply chain" (refs/graph/api-reference/v1.0/api/channel-list-messages.md:65), and the spike confirmed that a root's own lastModifiedDateTime misses reply activity (docs/spike/phase1.md:55). The order sentence is at refs/graph/api-reference/v1.0/api/channel-list-messages.md:65.
type MessagePatch ¶
type MessagePatch struct {
Body *ItemBody `json:"body,omitempty"`
Subject *string `json:"subject,omitempty"`
Importance *string `json:"importance,omitempty"`
}
MessagePatch is the PATCH body of an edit: the caller supplies a chatMessage with the properties it wants changed (refs/graph/api-reference/v1.0/api/chatmessage-update.md:44-45). The CLI sends the body, the subject and the importance; the response is the documented 204.
type MessagePost ¶
type MessagePost struct {
// Subject is stored by both containers, which the spike confirmed
// (docs/spike/phase1.md:90,94; PLAN.md:241).
Subject string `json:"subject,omitempty"`
// Body is the message text; contentType is "html" or "text"
// (refs/graph/api-reference/v1.0/resources/itembody.md).
Body ItemBody `json:"body"`
// Importance is "normal", "high" or "urgent"
// (refs/graph/api-reference/v1.0/resources/chatmessage.md:75).
Importance string `json:"importance,omitempty"`
// Mentions carries one entry per mentioned person, and each entry's id is
// the index of its <at id="N"> tag in Body.
Mentions []Mention `json:"mentions,omitempty"`
// Attachments are file references: {"contentType":"reference", ...}
// (refs/graph/api-reference/v1.0/resources/chatmessageattachment.md).
Attachments []Attachment `json:"attachments,omitempty"`
// HostedContents are the inline images, whose temporaryId must equal the id
// the body references as ../hostedContents/{temporaryId}/$value
// (refs/graph/api-reference/v1.0/api/chatmessage-post.md:731).
HostedContents []HostedContentUpload `json:"hostedContents,omitempty"`
}
MessagePost is the body of a message create. Only body is mandatory (refs/graph/api-reference/v1.0/api/chatmessage-post.md:68); everything else is sent only when the command asked for it.
Mentions, attachments and hostedContents are the three collections the same POST creates in one call, which is what makes an inline image possible at all: there is no v1.0 create endpoint for hosted content (refs/INDEX.md, "Inline images have no create endpoint in the v1.0 API reference").
type MessageQuery ¶
type MessageQuery struct {
// Top is the requested $top per page; it is clamped to the documented 50.
Top int
// Limit caps the total number of messages returned (0 means every page).
Limit int
// Since drops messages created before it.
Since time.Time
// Until drops messages created after it.
Until time.Time
// Replies asks for $expand=replies on a channel listing, which carries each
// root's replies so a thread view needs no second round trip.
Replies bool
}
MessageQuery describes a message listing.
The zero value lists the newest page of a container. Since and Until are inclusive windows; the client always re-checks timestamps and always sorts the result, because Graph's default order is neither created- nor modified-sorted (PLAN.md:185).
type MessageTarget ¶
type MessageTarget struct {
TeamID string
ChannelID string
ChatID string
// UserID is the signed-in user's id, needed only by SoftDelete on a chat
// message (see the file comment). It is never used for a channel message.
UserID string
// MessageID is the root message for a channel target and the message
// itself for a chat target.
MessageID string
// ReplyID is set when the target is a reply inside a channel thread.
ReplyID string
}
MessageTarget identifies the message a write acts on.
A channel message needs its team and channel; a chat message needs the chat. A *reply* is addressed by its root: ReplyID is the reply itself and MessageID is the root message it hangs under, because every reply route takes the root in the path (refs/graph/api-reference/v1.0/api/chatmessage-update.md:33-34).
func (MessageTarget) IsChat ¶
func (t MessageTarget) IsChat() bool
IsChat reports whether the target is a chat message.
type OnlineMeetingInfo ¶ added in v1.1.0
type OnlineMeetingInfo struct {
ConferenceID string `json:"conferenceId,omitempty"`
JoinURL string `json:"joinUrl,omitempty"`
QuickDial string `json:"quickDial,omitempty"`
TollFreeNumber []string `json:"tollFreeNumbers,omitempty"`
TollNumber string `json:"tollNumber,omitempty"`
}
OnlineMeetingInfo is microsoft.graph.onlineMeetingInfo. Only joinUrl is rendered, but the rest of the documented shape stays so the --json object is the Graph object (refs/graph/api-reference/v1.0/resources/onlinemeetinginfo.md).
type Options ¶
type Options struct {
// BaseURL is the Graph service root including the version segment, for
// example https://graph.microsoft.com/v1.0.
BaseURL string
// Token supplies bearer tokens.
Token TokenSource
// HTTPClient defaults to http.DefaultClient.
HTTPClient *http.Client
// UserAgent is sent as User-Agent.
UserAgent string
// MaxRetries defaults to DefaultMaxRetries; a negative value disables
// retries.
MaxRetries int
// Timeout bounds one request attempt; it defaults to DefaultTimeout and a
// negative value disables the bound (tests that drive a fake do that).
Timeout time.Duration
// Logger receives one line per request attempt and per page when set. The
// CLI wires it to -v, so a slow call is visible instead of looking hung.
Logger func(format string, args ...any)
// Clock is used for bookkeeping; defaults to the system clock.
Clock clock.Clock
// Sleeper defaults to a real timer. Tests inject a no-op.
Sleeper Sleeper
// Recorder is optional.
Recorder Recorder
// MaxRetryAfter caps how long a single Retry-After wait may be; a longer
// value ends the retries instead of blocking the CLI for minutes.
MaxRetryAfter time.Duration
// RetryThrottledOnly disables the transport-level 503/504 retry.
RetryThrottledOnly bool
}
Options configures a Client. Only BaseURL and Token are required.
type Page ¶
type Page[T any] struct { Value []T `json:"value"` NextLink string `json:"@odata.nextLink"` // Count is only present on the first page (refs/graph/concepts/paging.md:100). Count *int `json:"@odata.count"` // ODataContext is the documented @odata.context, kept so callers can log it. ODataContext string `json:"@odata.context"` }
Page is one page of a Graph collection.
type Person ¶
type Person struct {
ID string `json:"id"`
DisplayName string `json:"displayName,omitempty"`
GivenName string `json:"givenName,omitempty"`
Surname string `json:"surname,omitempty"`
CompanyName string `json:"companyName,omitempty"`
JobTitle string `json:"jobTitle,omitempty"`
Department string `json:"department,omitempty"`
OfficeLocation string `json:"officeLocation,omitempty"`
UserPrincipalName string `json:"userPrincipalName,omitempty"`
ScoredEmailAddresses []ScoredEmailAddress `json:"scoredEmailAddresses,omitempty"`
}
Person is the subset of microsoft.graph.person that /me/people returns. The API orders people by relevance, "determined by the user's communication and collaboration patterns", which is why it beats a directory search when "@yuki" should mean the Yuki you work with (refs/graph/api-reference/v1.0/api/user-list-people.md:12).
type Reaction ¶
type Reaction struct {
ReactionType string `json:"reactionType,omitempty"`
CreatedDateTime time.Time `json:"createdDateTime,omitempty"`
DisplayName string `json:"displayName,omitempty"`
ReactionContentURL string `json:"reactionContentUrl,omitempty"`
User *Identity `json:"user,omitempty"`
}
Reaction is chatMessageReaction (refs/graph/api-reference/v1.0/resources/chatmessagereaction.md).
type Recipient ¶ added in v1.1.0
type Recipient struct {
EmailAddress *EmailAddress `json:"emailAddress,omitempty"`
}
Recipient is microsoft.graph.recipient (an organizer) (refs/graph/api-reference/v1.0/resources/recipient.md).
type Recorder ¶
type Recorder interface {
RecordRequest(req *http.Request, body []byte)
RecordResponse(req *http.Request, status int, body []byte)
}
Recorder observes every request and response. The contract tests use it to validate the wire traffic against the vendored OpenAPI subset (PLAN.md Layer 6); production passes nil and pays nothing.
type Request ¶
type Request struct {
// Method is an HTTP method.
Method string
// Path is a Graph path ("/me/chats") or an absolute URL (an
// @odata.nextLink, which must be followed verbatim).
Path string
// Query holds query parameters.
Query url.Values
// Body is marshalled as JSON when non-nil.
Body any
// Raw is sent verbatim and takes precedence over Body. It is how an upload
// PUT sends file bytes (which JSON encoding would base64) and how
// `teams api --input` sends a body the caller wrote.
Raw []byte
// ContentType overrides the Content-Type header, which otherwise defaults to
// application/json whenever a body is present. An upload sets the file's own
// media type.
ContentType string
// PreAuthorized marks a request to a URL the service handed out (an upload
// session URL). Such a URL can be on another host, and the docs warn that
// sending an Authorization header to it can answer 401
// (refs/graph/api-reference/v1.0/api/driveitem-createuploadsession.md:242),
// so the bearer token is not attached and the host check is skipped.
PreAuthorized bool
// Header carries per-request headers (Prefer, Content-Type overrides).
Header http.Header
}
Request describes one Graph call.
func (Request) DisplayPath ¶
DisplayPath renders the request target for a log line: the Graph path when the caller used one, otherwise the URL without its query string.
type RequestOption ¶
type RequestOption func(*Request)
RequestOption customizes a convenience call.
func WithBody ¶
func WithBody(body any) RequestOption
WithBody replaces the request body (used by raw `teams api` calls).
func WithHeader ¶
func WithHeader(key, value string) RequestOption
WithHeader sets one request header.
func WithPreferUnknownEnumMembers ¶
func WithPreferUnknownEnumMembers() RequestOption
WithPreferUnknownEnumMembers adds the documented Prefer header.
type ResponseStatus ¶ added in v1.1.0
type ResponseStatus struct {
Response string `json:"response,omitempty"`
Time *time.Time `json:"time,omitzero"`
}
ResponseStatus is microsoft.graph.responseStatus (refs/graph/api-reference/v1.0/resources/responsestatus.md). The values are none, organizer, tentativelyAccepted, accepted, declined and notResponded.
type ScheduleInformation ¶ added in v1.1.0
type ScheduleInformation struct {
ScheduleID string `json:"scheduleId,omitempty"`
AvailabilityView string `json:"availabilityView,omitempty"`
ScheduleItems *[]ScheduleItem `json:"scheduleItems"`
Error *FreeBusyError `json:"error,omitempty"`
WorkingHours *WorkingHours `json:"workingHours,omitempty"`
}
ScheduleInformation is microsoft.graph.scheduleInformation (refs/graph/api-reference/v1.0/resources/scheduleinformation.md).
ScheduleItems is a pointer because Graph sets it to null, not to an empty list, when the per-schedule lookup failed: a user with no mailbox and a user that does not exist both answer error.responseCode "5016" with a null scheduleItems, and the two cannot be told apart (verified live 2026-10-05, handoff §3, F7).
func (ScheduleInformation) Items ¶ added in v1.1.0
func (s ScheduleInformation) Items() []ScheduleItem
Items returns the schedule items, treating a null scheduleItems as none.
type ScheduleItem ¶ added in v1.1.0
type ScheduleItem struct {
Start DateTimeTimeZone `json:"start"`
End DateTimeTimeZone `json:"end"`
Status string `json:"status,omitempty"`
Subject string `json:"subject,omitempty"`
Location string `json:"location,omitempty"`
IsPrivate *bool `json:"isPrivate,omitzero"`
}
ScheduleItem is microsoft.graph.scheduleItem (refs/graph/api-reference/v1.0/resources/scheduleitem.md).
Another user's unshared calendar returns only start, end and status: subject, location and isPrivate are absent, so they are omitempty and the CLI never assumes them (verified live 2026-10-05, handoff §3, F7).
func (ScheduleItem) IsFree ¶ added in v1.1.0
func (s ScheduleItem) IsFree() bool
IsFree reports whether the item is a free slot. The live service returns status "free" items for your own calendar, which the CLI drops (plans/calendar.md §4.3).
type ScoredEmailAddress ¶
type ScoredEmailAddress struct {
Address string `json:"address,omitempty"`
Score float64 `json:"relevanceScore"`
}
ScoredEmailAddress is scoredEmailAddress, which a person carries (refs/graph/api-reference/v1.0/resources/scoredemailaddress.md).
type SearchFilters ¶
type SearchFilters struct {
// Text is free text, passed through as KQL so a user who types a scope term
// of their own keeps it.
Text string
// From scopes to messages sent by that person (from:term).
From string
// To scopes to messages sent to that person; the docs mark it "partially
// supported for the one-on-one message".
To string
// Since and Until become sent>= / sent<= comparisons with a full UTC
// timestamp. PLAN.md:235 records that sent honors a time of day, so a bare
// date is never sent.
Since time.Time
Until time.Time
// MentionsMe adds IsMentioned:true.
MentionsMe bool
// MentionsUser adds mentions:<userId without dashes>.
MentionsUser string
// HasAttachment adds hasAttachment:true or hasAttachment:false.
HasAttachment *bool
}
SearchFilters is the CLI's search surface, which maps onto documented KQL scope terms.
func (SearchFilters) Empty ¶
func (f SearchFilters) Empty() bool
Empty reports whether the filters carry no term at all, which is a usage error rather than an empty search.
func (SearchFilters) KQL ¶
func (f SearchFilters) KQL() string
KQL renders the filters as a KQL query string. Terms are joined with spaces, which KQL reads as AND.
type SearchHit ¶
type SearchHit struct {
HitID string `json:"hitId"`
Rank int `json:"rank"`
Summary string `json:"summary,omitempty"`
Resource SearchResource `json:"resource"`
}
SearchHit is one searchHit (refs/graph/api-reference/v1.0/resources/searchhit.md).
type SearchQuery ¶
type SearchQuery struct {
// Query is the KQL query string, built with SearchFilters.KQL or typed by
// the user.
Query string
// From is the 0-based offset; the first page must use 0.
From int
// Size is the page size, clamped to the observed 50 for chatMessage.
Size int
// Fields narrows the returned properties. chatMessage search ignores it.
Fields []string
}
SearchQuery is one search request.
type SearchResource ¶
type SearchResource struct {
ODataType string `json:"@odata.type,omitempty"`
ID string `json:"id,omitempty"`
ChatID string `json:"chatId,omitempty"`
ChannelIdentity *ChannelIdentity `json:"channelIdentity,omitempty"`
CreatedDateTime time.Time `json:"createdDateTime,omitzero"`
LastModifiedDateTime time.Time `json:"lastModifiedDateTime,omitzero"`
Subject string `json:"subject,omitempty"`
Importance string `json:"importance,omitempty"`
ETag string `json:"etag,omitempty"`
WebLink string `json:"webLink,omitempty"`
From *SearchSender `json:"from,omitempty"`
}
SearchResource is the bodyless chatMessage a hit carries. Graph sends webLink rather than webUrl here (refs/graph/concepts/search-concept-chat-messages.md:365-380).
func (SearchResource) InChannel ¶
func (r SearchResource) InChannel() (teamID, channelID string, ok bool)
InChannel reports whether the hit is a channel message and returns its channel and team ids.
type SearchResult ¶
type SearchResult struct {
SearchTerms []string `json:"searchTerms,omitempty"`
Hits []SearchHit `json:"hits"`
Total int `json:"total"`
MoreResultsAvailable bool `json:"moreResultsAvailable"`
}
SearchResult is the useful part of a search response: the hits of the single hitsContainer the API returns, plus the counts.
type SearchSender ¶
type SearchSender struct {
EmailAddress struct {
Name string `json:"name,omitempty"`
Address string `json:"address,omitempty"`
} `json:"emailAddress"`
}
SearchSender is the search hit's "from", which is an emailAddress pair rather than the chatMessage identitySet.
func (*SearchSender) DisplayName ¶
func (s *SearchSender) DisplayName() string
DisplayName is the sender's name, falling back to the address.
type Team ¶
type Team struct {
ID string `json:"id"`
DisplayName string `json:"displayName,omitempty"`
Description string `json:"description,omitempty"`
Visibility string `json:"visibility,omitempty"`
IsArchived bool `json:"isArchived,omitempty"`
WebURL string `json:"webUrl,omitempty"`
CreatedDateTime time.Time `json:"createdDateTime,omitzero"`
TenantID string `json:"tenantId,omitempty"`
}
Team is microsoft.graph.team (refs/graph/api-reference/v1.0/resources/team.md).
type TeamworkUserIdentity ¶
type TeamworkUserIdentity struct {
ID string `json:"id,omitempty"`
DisplayName string `json:"displayName,omitempty"`
TenantID string `json:"tenantId,omitempty"`
UserIdentityType string `json:"userIdentityType,omitempty"`
}
TeamworkUserIdentity is teamworkUserIdentity, which a mention's mentioned.user carries. userIdentityType is "aadUser" for a person (refs/graph/api-reference/v1.0/resources/teamworkuseridentity.md).
type TimeSlot ¶ added in v1.1.0
TimeSlot is microsoft.graph.timeSlot, the proposedNewTime shape (refs/graph/api-reference/v1.0/resources/timeslot.md).
type TimeoutError ¶
type TimeoutError struct {
// Err is the underlying transport error.
Err error
// After is the deadline that fired.
After time.Duration
}
TimeoutError reports a request that exceeded the per-attempt deadline. It exists so a stall reads as a network problem with a next step, not as a CLI bug: before this, a stalled connection simply never returned.
func (*TimeoutError) Hint ¶
func (e *TimeoutError) Hint() string
Hint is the suggested fix shown under the error.
func (*TimeoutError) Unwrap ¶
func (e *TimeoutError) Unwrap() error
Unwrap exposes the transport error, so errors.Is(err, context.DeadlineExceeded) and the exit-code mapping keep working.
type TokenSource ¶
TokenSource supplies the bearer token for each request. internal/auth implements it; tests can pass a static one.
type TokenSourceFunc ¶
TokenSourceFunc adapts a function to TokenSource.
type UploadResult ¶
type UploadResult struct {
// WebURL is the URL the attachment's contentUrl carries. For a channel that
// is the SharePoint URL of the item; for a chat it is a sharing link, which
// is what recipient access needs (refs/teams-mcp/src/utils/file-upload.ts:270-272).
WebURL string
// AttachmentID is the GUID inside the item's eTag, which is the id the body's
// <attachment id="..."> reference and the attachments[] entry share
// (refs/INDEX.md:88).
AttachmentID string
// Name, Size and ContentType describe the uploaded file.
Name string
Size int64
ContentType string
// ItemID is the drive item's id, needed for the sharing link of a chat
// upload and reported with --json.
ItemID string
// DriveID is the drive the file landed in.
DriveID string
}
UploadResult is an uploaded file, in the shape the attachment needs.
type UploadTarget ¶
type UploadTarget struct {
// TeamID and ChannelID identify a channel's files folder.
TeamID string
ChannelID string
// Chat marks a chat attachment: the file goes into the caller's OneDrive,
// under the Teams chat folder.
Chat bool
}
UploadTarget says where a file goes.
A channel attachment is stored in the team's SharePoint drive, in the channel's files folder; a chat attachment goes into the signed-in user's own OneDrive, which is what makes Files.ReadWrite enough for one and Files.ReadWrite.All necessary for the other (PLAN.md:57).
func (UploadTarget) IsChannel ¶
func (t UploadTarget) IsChannel() bool
IsChannel reports whether the target is a channel's drive.
type UsageError ¶
type UsageError struct {
Msg string
}
UsageError is an error caused by the arguments the caller passed rather than by Graph itself. It carries exit code 2, the CLI's usage code (AGENTS.md "Exit codes"), which makes the layer's own validation consistent with the command layer's.
func (*UsageError) ExitCode ¶
func (e *UsageError) ExitCode() int
ExitCode is the documented usage exit code.
type User ¶
type User struct {
ID string `json:"id"`
DisplayName string `json:"displayName,omitempty"`
GivenName string `json:"givenName,omitempty"`
Surname string `json:"surname,omitempty"`
UserPrincipalName string `json:"userPrincipalName,omitempty"`
Mail string `json:"mail,omitempty"`
JobTitle string `json:"jobTitle,omitempty"`
Department string `json:"department,omitempty"`
OfficeLocation string `json:"officeLocation,omitempty"`
PreferredLanguage string `json:"preferredLanguage,omitempty"`
MobilePhone string `json:"mobilePhone,omitempty"`
BusinessPhones []string `json:"businessPhones,omitempty"`
}
User is the directory user subset the CLI reads. The default property set is the one user-list.md documents (refs/graph/api-reference/v1.0/api/user-list.md:39).
type WorkingHours ¶ added in v1.1.0
type WorkingHours struct {
DaysOfWeek []string `json:"daysOfWeek,omitempty"`
TimeZone *struct {
Name string `json:"name,omitempty"`
} `json:"timeZone,omitempty"`
StartTime string `json:"startTime,omitempty"`
EndTime string `json:"endTime,omitempty"`
}
WorkingHours is microsoft.graph.workingHours; only the time zone is read, and only to render it (refs/graph/api-reference/v1.0/resources/workinghours.md).