msteams-mcp 0.2.0

package/dist/utils/parsers.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Pure parsing functions for Teams API responses.
+ *
+ * These functions transform raw API responses into our internal types.
+ * They are extracted here for testability - no side effects or external dependencies.
+ */
+import type { TeamsSearchResult } from '../types/teams.js';
+/** Person search result from Substrate suggestions API. */
+export interface PersonSearchResult {
+    id: string;
+    mri: string;
+    displayName: string;
+    email?: string;
+    givenName?: string;
+    surname?: string;
+    jobTitle?: string;
+    department?: string;
+    companyName?: string;
+}
+/** User profile extracted from JWT tokens. */
+export interface UserProfile {
+    id: string;
+    mri: string;
+    email: string;
+    displayName: string;
+    givenName?: string;
+    surname?: string;
+    tenantId?: string;
+}
+/**
+ * Strips HTML tags from content for display.
+ */
+export declare function stripHtml(html: string): string;
+/**
+ * Builds a deep link to open a message in Teams.
+ *
+ * Format: https://teams.microsoft.com/l/message/{conversationId}/{messageTimestamp}
+ *
+ * @param conversationId - The conversation/thread ID (e.g., "19:xxx@thread.tacv2")
+ * @param messageTimestamp - The message timestamp in epoch milliseconds
+ */
+export declare function buildMessageLink(conversationId: string, messageTimestamp: string | number): string;
+/**
+ * Extracts a timestamp-based message ID from various sources.
+ * Teams uses epoch milliseconds as message IDs in URLs.
+ *
+ * IMPORTANT: For channel threaded replies, the ;messageid= in ClientConversationId
+ * is the PARENT thread's ID, not this message's ID. We must prefer the actual
+ * message timestamp (DateTimeReceived/DateTimeSent) for accurate deep links.
+ */
+export declare function extractMessageTimestamp(source: Record<string, unknown> | undefined, timestamp?: string): string | undefined;
+/**
+ * Parses a person suggestion from the Substrate API response.
+ *
+ * The API can return IDs in various formats:
+ * - GUID with tenant: "ab76f827-...@tenant.onmicrosoft.com"
+ * - Base64-encoded GUID: "93qkaTtFGWpUHjyRafgdhg=="
+ */
+export declare function parsePersonSuggestion(item: Record<string, unknown>): PersonSearchResult | null;
+/**
+ * Parses a v2 query result item into a search result.
+ */
+export declare function parseV2Result(item: Record<string, unknown>): TeamsSearchResult | null;
+/**
+ * Parses user profile from a JWT payload.
+ *
+ * @param payload - Decoded JWT payload object
+ * @returns User profile or null if required fields are missing
+ */
+export declare function parseJwtProfile(payload: Record<string, unknown>): UserProfile | null;
+/**
+ * Calculates token expiry status from an expiry timestamp.
+ *
+ * @param expiryMs - Token expiry time in milliseconds since epoch
+ * @param nowMs - Current time in milliseconds (for testing)
+ * @returns Token status including whether it's valid and time remaining
+ */
+export declare function calculateTokenStatus(expiryMs: number, nowMs?: number): {
+    isValid: boolean;
+    expiresAt: string;
+    minutesRemaining: number;
+};
+/**
+ * Parses the pagination result from a search API response.
+ *
+ * @param entitySets - Raw EntitySets array from API response
+ * @param from - Starting offset used in request
+ * @param size - Page size used in request
+ * @returns Parsed results and pagination metadata
+ */
+export declare function parseSearchResults(entitySets: unknown[] | undefined, from: number, size: number): {
+    results: TeamsSearchResult[];
+    total?: number;
+};
+/**
+ * Parses people search results from the Groups/Suggestions structure.
+ *
+ * @param groups - Raw Groups array from suggestions API response
+ * @returns Array of parsed person results
+ */
+export declare function parsePeopleResults(groups: unknown[] | undefined): PersonSearchResult[];
+/** Channel search result from Substrate suggestions API or Teams List API. */
+export interface ChannelSearchResult {
+    channelId: string;
+    channelName: string;
+    teamName: string;
+    teamId: string;
+    channelType: string;
+    description?: string;
+    isMember?: boolean;
+}
+/**
+ * Parses a single channel suggestion from the API response.
+ *
+ * @param suggestion - Raw suggestion object from API
+ * @returns Parsed channel result or null if required fields are missing
+ */
+export declare function parseChannelSuggestion(suggestion: Record<string, unknown>): ChannelSearchResult | null;
+/**
+ * Parses channel search results from the Groups/Suggestions structure.
+ *
+ * @param groups - Raw Groups array from suggestions API response
+ * @returns Array of parsed channel results
+ */
+export declare function parseChannelResults(groups: unknown[] | undefined): ChannelSearchResult[];
+/** Team with channels from the Teams List API response. */
+export interface TeamWithChannels {
+    teamId: string;
+    teamName: string;
+    threadId: string;
+    description?: string;
+    channels: ChannelSearchResult[];
+}
+/**
+ * Parses the Teams List API response to extract all teams and channels.
+ *
+ * @param data - Raw response data from /api/csa/{region}/api/v3/teams/users/me
+ * @returns Array of teams with their channels
+ */
+export declare function parseTeamsList(data: Record<string, unknown> | undefined): TeamWithChannels[];
+/**
+ * Filters channels from the Teams List by name.
+ *
+ * @param teams - Array of teams with channels from parseTeamsList
+ * @param query - Search query (case-insensitive partial match)
+ * @returns Matching channels flattened into a single array
+ */
+export declare function filterChannelsByName(teams: TeamWithChannels[], query: string): ChannelSearchResult[];
+/**
+ * Decodes a base64-encoded GUID to its standard string representation.
+ *
+ * Microsoft encodes GUIDs as 16 bytes with little-endian ordering for the
+ * first three groups (Data1, Data2, Data3).
+ *
+ * @param base64 - Base64-encoded GUID (typically 24 chars with == padding)
+ * @returns The GUID string in standard format, or null if invalid
+ */
+export declare function decodeBase64Guid(base64: string): string | null;
+/**
+ * Extracts the Azure AD object ID (GUID) from various formats.
+ *
+ * Handles:
+ * - MRI format: "8:orgid:ab76f827-27e2-4c67-a765-f1a53145fa24"
+ * - MRI with base64: "8:orgid:93qkaTtFGWpUHjyRafgdhg=="
+ * - Skype ID format: "orgid:ab76f827-27e2-4c67-a765-f1a53145fa24"
+ * - ID with tenant: "ab76f827-27e2-4c67-a765-f1a53145fa24@56b731a8-..."
+ * - Raw GUID: "ab76f827-27e2-4c67-a765-f1a53145fa24"
+ * - Base64-encoded GUID: "93qkaTtFGWpUHjyRafgdhg=="
+ *
+ * @param identifier - User identifier in any supported format
+ * @returns The extracted GUID or null if invalid format
+ */
+export declare function extractObjectId(identifier: string): string | null;
+/**
+ * Builds a 1:1 conversation ID from two user object IDs.
+ *
+ * The conversation ID format for 1:1 chats in Teams is:
+ * `19:{userId1}_{userId2}@unq.gbl.spaces`
+ *
+ * The user IDs are sorted lexicographically to ensure consistency -
+ * both participants will generate the same conversation ID.
+ *
+ * @param userId1 - First user's object ID (GUID, MRI, or ID with tenant)
+ * @param userId2 - Second user's object ID (GUID, MRI, or ID with tenant)
+ * @returns The constructed conversation ID, or null if either ID is invalid
+ */
+export declare function buildOneOnOneConversationId(userId1: string, userId2: string): string | null;