chore: import upstream snapshot with attribution

apps/sim/tools/sharepoint/get_list.ts

@@ -0,0 +1,270 @@
+import { createLogger } from '@sim/logger'
+import type {
+  SharepointGetListResponse,
+  SharepointList,
+  SharepointToolParams,
+} from '@/tools/sharepoint/types'
+import { assertGraphNextPageUrl, getGraphNextPageUrl, optionalTrim } from '@/tools/sharepoint/utils'
+import type { ToolConfig } from '@/tools/types'
+
+const logger = createLogger('SharePointGetList')
+
+export const getListTool: ToolConfig<SharepointToolParams, SharepointGetListResponse> = {
+  id: 'sharepoint_get_list',
+  name: 'Get SharePoint List',
+  description: 'Get metadata (and optionally columns/items) for a SharePoint list',
+  version: '1.0.0',
+
+  oauth: {
+    required: true,
+    provider: 'sharepoint',
+  },
+
+  params: {
+    accessToken: {
+      type: 'string',
+      required: true,
+      visibility: 'hidden',
+      description: 'The access token for the SharePoint API',
+    },
+    siteSelector: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Select the SharePoint site',
+    },
+    siteId: {
+      type: 'string',
+      required: false,
+      visibility: 'hidden',
+      description: 'The ID of the SharePoint site (internal use)',
+    },
+    listId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'The ID of the list to retrieve. Example: b!abc123def456 or a GUID like 12345678-1234-1234-1234-123456789012',
+    },
+    includeColumns: {
+      type: 'boolean',
+      required: false,
+      visibility: 'user-only',
+      description: 'Whether to include column definitions when retrieving a specific list',
+    },
+    includeItems: {
+      type: 'boolean',
+      required: false,
+      visibility: 'user-only',
+      description: 'Whether to include list items when retrieving a specific list',
+    },
+    nextPageUrl: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Full @odata.nextLink URL from a previous Microsoft Graph page response',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      if (params.nextPageUrl) {
+        return assertGraphNextPageUrl(params.nextPageUrl)
+      }
+
+      const siteId = optionalTrim(params.siteId) || optionalTrim(params.siteSelector) || 'root'
+      const encodedSiteId = encodeURIComponent(siteId)
+      const listId = optionalTrim(params.listId)
+
+      if (!listId) {
+        const baseUrl = `https://graph.microsoft.com/v1.0/sites/${encodedSiteId}/lists`
+        const url = new URL(baseUrl)
+        const finalUrl = url.toString()
+        logger.info('SharePoint List All Lists URL', {
+          finalUrl,
+          siteId,
+        })
+        return finalUrl
+      }
+
+      const listSegment = encodeURIComponent(listId)
+      const wantsItems = typeof params.includeItems === 'boolean' ? params.includeItems : true
+
+      if (wantsItems && !params.includeColumns) {
+        const itemsUrl = new URL(
+          `https://graph.microsoft.com/v1.0/sites/${encodedSiteId}/lists/${listSegment}/items`
+        )
+        itemsUrl.searchParams.set('$expand', 'fields')
+        const finalItemsUrl = itemsUrl.toString()
+        logger.info('SharePoint Get List Items URL', {
+          finalUrl: finalItemsUrl,
+          siteId,
+          listId,
+        })
+        return finalItemsUrl
+      }
+
+      const baseUrl = `https://graph.microsoft.com/v1.0/sites/${encodedSiteId}/lists/${listSegment}`
+      const url = new URL(baseUrl)
+      const expandParts: string[] = []
+      if (params.includeColumns) expandParts.push('columns')
+      if (wantsItems) expandParts.push('items(expand=fields)')
+      if (expandParts.length > 0) url.searchParams.append('$expand', expandParts.join(','))
+
+      const finalUrl = url.toString()
+      logger.info('SharePoint Get List URL', {
+        finalUrl,
+        siteId,
+        listId,
+        includeColumns: !!params.includeColumns,
+        includeItems: wantsItems,
+      })
+      return finalUrl
+    },
+    method: 'GET',
+    headers: (params) => ({
+      Authorization: `Bearer ${params.accessToken}`,
+      Accept: 'application/json',
+    }),
+  },
+
+  transformResponse: async (response: Response, params) => {
+    const data: Record<string, unknown> = await response.json()
+    const value = data.value
+
+    // If the response is a collection of items (from the items endpoint)
+    if (
+      Array.isArray(value) &&
+      value.length > 0 &&
+      value[0] &&
+      typeof value[0] === 'object' &&
+      'fields' in value[0]
+    ) {
+      const items = value.map((i: Record<string, unknown>) => ({
+        id: i.id as string,
+        fields: i.fields as Record<string, unknown>,
+      }))
+
+      const nextPageUrl = getGraphNextPageUrl(data)
+
+      return {
+        success: true,
+        output: {
+          list: { id: optionalTrim(params?.listId) || '', items } as SharepointList,
+          items,
+          nextPageUrl,
+        },
+      }
+    }
+
+    if (Array.isArray(value)) {
+      const lists: SharepointList[] = value.map((l: Record<string, unknown>) => ({
+        id: l.id as string,
+        displayName: (l.displayName ?? l.name) as string | undefined,
+        name: l.name as string | undefined,
+        webUrl: l.webUrl as string | undefined,
+        createdDateTime: l.createdDateTime as string | undefined,
+        lastModifiedDateTime: l.lastModifiedDateTime as string | undefined,
+        list: l.list as SharepointList['list'],
+      }))
+
+      const nextPageUrl = getGraphNextPageUrl(data)
+
+      return {
+        success: true,
+        output: { lists, nextPageUrl },
+      }
+    }
+
+    const list: SharepointList = {
+      id: data.id as string,
+      displayName: (data.displayName ?? data.name) as string | undefined,
+      name: data.name as string | undefined,
+      webUrl: data.webUrl as string | undefined,
+      createdDateTime: data.createdDateTime as string | undefined,
+      lastModifiedDateTime: data.lastModifiedDateTime as string | undefined,
+      list: data.list as SharepointList['list'],
+      columns: Array.isArray(data.columns)
+        ? data.columns.map((c: Record<string, unknown>) => ({
+            id: c.id as string | undefined,
+            name: c.name as string | undefined,
+            displayName: c.displayName as string | undefined,
+            description: c.description as string | undefined,
+            indexed: c.indexed as boolean | undefined,
+            enforcedUniqueValues: c.enforcedUniqueValues as boolean | undefined,
+            hidden: c.hidden as boolean | undefined,
+            readOnly: c.readOnly as boolean | undefined,
+            required: c.required as boolean | undefined,
+            columnGroup: c.columnGroup as string | undefined,
+          }))
+        : undefined,
+      items: Array.isArray(data.items)
+        ? data.items.map((i: Record<string, unknown>) => ({
+            id: i.id as string,
+            fields: i.fields as Record<string, unknown>,
+          }))
+        : undefined,
+    }
+
+    return {
+      success: true,
+      output: { list },
+    }
+  },
+
+  outputs: {
+    list: {
+      type: 'object',
+      description: 'Information about the SharePoint list',
+      properties: {
+        id: { type: 'string', description: 'The unique ID of the list' },
+        displayName: { type: 'string', description: 'The display name of the list' },
+        name: { type: 'string', description: 'The internal name of the list' },
+        webUrl: { type: 'string', description: 'The web URL of the list' },
+        createdDateTime: { type: 'string', description: 'When the list was created' },
+        lastModifiedDateTime: {
+          type: 'string',
+          description: 'When the list was last modified',
+        },
+        list: { type: 'object', description: 'List properties (e.g., template)' },
+        columns: {
+          type: 'array',
+          description: 'List column definitions',
+          items: { type: 'object' },
+        },
+        items: {
+          type: 'array',
+          description: 'List items (with fields when expanded)',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'Item ID' },
+              fields: { type: 'object', description: 'Field values for the item' },
+            },
+          },
+        },
+      },
+    },
+    lists: {
+      type: 'array',
+      description: 'All lists in the site when no listId/title provided',
+      items: { type: 'object' },
+    },
+    items: {
+      type: 'array',
+      description: 'List items with expanded fields when reading list items',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', description: 'Item ID' },
+          fields: { type: 'object', description: 'Field values for the item' },
+        },
+      },
+    },
+    nextPageUrl: {
+      type: 'string',
+      description: 'Full Microsoft Graph @odata.nextLink URL for the next page of results',
+      optional: true,
+    },
+  },
+}