graph

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: 20 Imported by: 0

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

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

View Source
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.

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

View Source
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.

View Source
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.

View Source
const AttendeeTypeRequired = "required"

AttendeeTypeRequired is the attendee type `calendar create` sends. The CLI has no "--optional" flag, so every attendee is required.

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

View Source
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.

View Source
const EventPreCheckSelect = "isOrganizer,allowNewTimeProposals,isOnlineMeeting,onlineMeeting,subject"

EventPreCheckSelect is the $select the pre-check uses.

View Source
const MaxBatchRequests = 20

MaxBatchRequests is the documented limit for /$batch (refs/graph/concepts/json-batching.md:17).

View Source
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.

View Source
const MaxPages = 1000

MaxPages is a safety valve: a server that keeps returning a next link must not hang the CLI forever.

View Source
const MaxQuotedMessages = 10

MaxQuotedMessages is the documented cap on replyWithQuote's messageIds (refs/graph/api-reference/v1.0/api/chatmessage-replywithquote.md:18).

View Source
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.

View Source
const MaxScheduleDays = 62

MaxScheduleDays is the largest getSchedule range: 63 days is a 400 ErrorTimeIntervalTooBig (handoff §3, F7). It is not in the docs.

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

View Source
const OnlineMeetingProviderTeams = "teamsForBusiness"

OnlineMeetingProviderTeams is the documented provider value for a Teams meeting (refs/graph/api-reference/v1.0/resources/event.md).

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

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

View Source
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

func AllowsTeamsMeetings(providers []string) bool

AllowsTeamsMeetings reports whether a provider list contains teamsForBusiness.

func ChannelMessagePath

func ChannelMessagePath(teamID, channelID, messageID string) string

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

func ChatFilterTopic(topic string) string

ChatFilterTopic builds the documented $filter for a chat topic.

func ChatFilterType

func ChatFilterType(chatType string) string

ChatFilterType builds the documented $filter for a chat type.

func ChatMessagePath

func ChatMessagePath(chatID, messageID string) string

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

func EventIDFromHitID(hitID string) (string, bool)

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

func IsBadRequest(err error) bool

IsBadRequest reports whether err is a Graph 400.

func IsConflict

func IsConflict(err error) bool

IsConflict reports whether err is a Graph 409.

func IsForbidden

func IsForbidden(err error) bool

IsForbidden reports whether err is a Graph 403.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err is a Graph 404.

func IsThrottled

func IsThrottled(err error) bool

IsThrottled reports whether err is a Graph 429.

func IsUnauthorized

func IsUnauthorized(err error) bool

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

func ODataQuote(s string) string

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

func RequestIDOf(err error) string

RequestIDOf returns the Graph request id carried by err, for support tickets.

func StripDashes

func StripDashes(s string) string

StripDashes removes the hyphens from a GUID, which the mentions: term requires (refs/graph/concepts/search-concept-chat-messages.md:267).

func Top

func Top(n int) url.Values

Top returns a $top parameter value.

func TopWith

func TopWith(n int, extra url.Values) url.Values

TopWith merges extra parameters with $top.

func UserFilterDisplayName

func UserFilterDisplayName(prefix string) string

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

func UserFilterMail(prefix string) string

UserFilterMail builds the startswith filter on mail.

func UserFilterUserPrincipalName

func UserFilterUserPrincipalName(prefix string) string

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.

func (*APIError) Error

func (e *APIError) Error() string

Error implements error.

func (*APIError) ExitCode

func (e *APIError) ExitCode() int

ExitCode maps the status to the CLI contract (AGENTS.md: 0 ok, 1 error, 2 usage, 3 auth required, 4 not found, 5 throttled).

func (*APIError) Hint

func (e *APIError) Hint() string

Hint returns the one-line fix shown under the error, or "".

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

func (a Attendee) DisplayName() string

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

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

func (c Chat) LastActivity() time.Time

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.

func (Chat) Unread

func (c Chat) Unread() bool

Unread reports whether the chat's newest message is newer than the read watermark. A chat that has never been read counts as unread; a chat with no messages does not. PLAN.md:149 documents this rule: "A chat is unread when its last message is newer than that timestamp."

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 New

func New(opts Options) (*Client, error)

New builds a 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

func (c *Client) AllowedOnlineMeetingProviders(ctx context.Context) ([]string, error)

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

func (c *Client) BaseURL() string

BaseURL returns the service root.

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

func (c *Client) CancelEvent(ctx context.Context, eventID, comment string) error

CancelEvent cancels an event the caller organizes (POST /me/events/{event-id}/cancel). The organizer's attendees get a cancellation notice.

func (*Client) CreateChat

func (c *Client) CreateChat(ctx context.Context, in ChatCreate) (Chat, error)

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

func (c *Client) CreateEvent(ctx context.Context, in EventCreate) (Event, error)

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 (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) Delete

func (c *Client) Delete(ctx context.Context, path string, opts ...RequestOption) error

Delete issues a DELETE.

func (*Client) DeleteChat

func (c *Client) DeleteChat(ctx context.Context, chatID string) error

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

func (c *Client) DeleteEvent(ctx context.Context, eventID string) error

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

func (c *Client) Do(ctx context.Context, req Request) (*Response, error)

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

func (c *Client) FindMeetingChatID(ctx context.Context, joinURL string) (string, error)

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

func (c *Client) Get(ctx context.Context, path string, out any, opts ...RequestOption) error

Get issues a GET and decodes the JSON body into out (which may be nil).

func (*Client) GetChannel

func (c *Client) GetChannel(ctx context.Context, teamID, channelID string) (Channel, error)

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

func (c *Client) GetChat(ctx context.Context, chatID string, members bool) (Chat, error)

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

func (c *Client) GetChatMessage(ctx context.Context, chatID, messageID string) (Message, error)

GetChatMessage returns one chat message (refs/graph/api-reference/v1.0/api/chatmessage-get.md).

func (*Client) GetDefaultDrive

func (c *Client) GetDefaultDrive(ctx context.Context) (Drive, error)

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

func (c *Client) GetEvent(ctx context.Context, eventID, selectFields string) (Event, error)

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

func (c *Client) GetFilesFolder(ctx context.Context, teamID, channelID string) (DriveItem, error)

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

func (c *Client) GetMe(ctx context.Context) (Me, error)

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

func (c *Client) GetTeam(ctx context.Context, teamID string) (Team, error)

GetTeam returns one team (GET /teams/{team-id}, refs/graph/api-reference/v1.0/api/team-get.md).

func (*Client) GetUser

func (c *Client) GetUser(ctx context.Context, idOrUPN string) (User, error)

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

func (c *Client) ListChannels(ctx context.Context, teamID string) ([]Channel, error)

ListChannels returns a team's channels (GET /teams/{team-id}/channels, refs/graph/api-reference/v1.0/api/channel-list.md).

func (*Client) ListChatMembers

func (c *Client) ListChatMembers(ctx context.Context, chatID string) ([]ConversationMember, error)

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

func (c *Client) ListChats(ctx context.Context, q ChatQuery) ([]Chat, error)

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

func (c *Client) ListJoinedTeams(ctx context.Context) ([]Team, error)

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

func (c *Client) ListPeople(ctx context.Context, search string, limit int) ([]Person, error)

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

func (c *Client) ListTeamMembers(ctx context.Context, teamID string) ([]ConversationMember, error)

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

func (c *Client) ListUsers(ctx context.Context, filter string, limit int) ([]User, error)

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

func (c *Client) MarkChatRead(ctx context.Context, chatID, userID string) error

MarkChatRead marks a chat read for one user (POST /chats/{chat-id}/markChatReadForUser, 204).

func (*Client) MarkChatUnread

func (c *Client) MarkChatUnread(ctx context.Context, chatID, userID string) error

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

func (c *Client) Post(ctx context.Context, path string, body, out any, opts ...RequestOption) error

Post issues a POST.

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

func (c *Client) PreCheckEvent(ctx context.Context, eventID string) (EventPreCheck, error)

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

func (c *Client) SearchUsers(ctx context.Context, query string, limit int) ([]User, error)

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

func (c *Client) UpdateEvent(ctx context.Context, eventID string, in EventUpdate) (Event, error)

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 Download

type Download struct {
	Name        string
	ContentType string
	Bytes       []byte
}

Download is a fetched file's bytes and content type.

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

func (d DriveItem) DriveID() string

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

func (DriveItem) IsFolder

func (d DriveItem) IsFolder() bool

IsFolder reports whether the item is a folder rather than a file.

func (DriveItem) MimeType

func (d DriveItem) MimeType() string

MimeType is the item's content type, when Graph reports one.

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

func (e Event) IsTeamsMeeting() bool

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) JoinURL added in v1.1.0

func (e Event) JoinURL() string

JoinURL is the online meeting's join URL, or "".

func (Event) SubjectLine added in v1.1.0

func (e Event) SubjectLine() string

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

func (m Mention) DisplayName() string

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.

func (Mention) UserID

func (m Mention) UserID() string

UserID is the mentioned user's id, when the mention names a person.

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

func (m Message) IsDeleted() bool

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

func (m Message) IsReply() bool

IsReply reports whether this message is a reply inside a channel thread.

func (Message) IsSystemEvent

func (m Message) IsSystemEvent() bool

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

func (m Message) LastActivity() time.Time

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.

func GetPage

func GetPage[T any](ctx context.Context, c *Client, path string, q url.Values, opts ...RequestOption) (Page[T], error)

GetPage fetches a single page. path is a Graph path or an absolute next link.

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

func (Person) Address

func (p Person) Address() string

Address is the person's best e-mail: the highest-scored address.

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

func (*Recipient) Address added in v1.1.0

func (r *Recipient) Address() string

Address is the recipient's SMTP address, or "".

func (*Recipient) Name added in v1.1.0

func (r *Recipient) Name() string

Name is the recipient's display name, falling back to the address.

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

func (r Request) DisplayPath() string

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.

func WithQuery

func WithQuery(q url.Values) RequestOption

WithQuery sets query parameters.

type Response

type Response struct {
	StatusCode int
	Header     http.Header
	Body       []byte
}

Response is a decoded-but-unparsed Graph response.

func (*Response) Decode

func (r *Response) Decode(v any) error

Decode unmarshals the JSON body into v, tolerating an empty body.

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 Sleeper

type Sleeper func(ctx context.Context, d time.Duration) error

Sleeper makes retry delays testable.

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

type TimeSlot struct {
	Start time.Time
	End   time.Time
}

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

func (e *TimeoutError) Error() string

Error implements error.

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

type TokenSource interface {
	Token(ctx context.Context) (string, error)
}

TokenSource supplies the bearer token for each request. internal/auth implements it; tests can pass a static one.

type TokenSourceFunc

type TokenSourceFunc func(ctx context.Context) (string, error)

TokenSourceFunc adapts a function to TokenSource.

func (TokenSourceFunc) Token

func (f TokenSourceFunc) Token(ctx context.Context) (string, error)

Token calls f.

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

func (e *UsageError) Error() string

Error implements error.

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

func (User) Address

func (u User) Address() string

Address is the mail to show for a user: mail, then the UPN.

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

Jump to

Keyboard shortcuts

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