codeapp-js 1.0.2 → 1.1.0

package/codeApp/dist/connectors/sharepoint.js

@@ -1,186 +1,202 @@
-
-// ────────────────────────────────────────────────────────────────────────────
-// ─────────────────────────────── SharePoint ─────────────────────────────────
-// ────────────────────────────────────────────────────────────────────────────
-import { getClient} from "../power-apps-data.js";
-import {_dbgWrap  } from "../codeapp.js";
-// ── Data source name (must match connectionReferences in power.config.json) ──
-const DATA_SOURCE_SP = "sharepointonline";
-
-// ── Initialize SDK client for the SharePoint connector ─────────
-function initSpClient() {
-  const dataSourcesInfo = {
-    [DATA_SOURCE_SP]: {
-      tableId: "",
-      version: "",
-      primaryKey: "",
-      dataSourceType: "Connector",
-      apis: {
-        GetItems: {
-          path: "/{connectionId}/datasets/{siteUrl}/tables/{table}/items",
-          method: "GET",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "table", in: "path", required: true },
-            { name: "$filter", in: "query", required: false },
-            { name: "$orderby", in: "query", required: false },
-            { name: "$top", in: "query", required: false },
-            { name: "$skip", in: "query", required: false },
-          ],
-        },
-        GetItem: {
-          path: "/{connectionId}/datasets/{siteUrl}/tables/{table}/items/{id}",
-          method: "GET",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "table", in: "path", required: true },
-            { name: "id", in: "path", required: true },
-          ],
-        },
-        PostItem: {
-          path: "/{connectionId}/datasets/{siteUrl}/tables/{table}/items",
-          method: "POST",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "table", in: "path", required: true },
-            { name: "item", in: "body", required: true },
-          ],
-        },
-        PatchItem: {
-          path: "/{connectionId}/datasets/{siteUrl}/tables/{table}/items/{id}",
-          method: "PATCH",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "table", in: "path", required: true },
-            { name: "id", in: "path", required: true },
-            { name: "item", in: "body", required: true },
-          ],
-        },
-        DeleteItem: {
-          path: "/{connectionId}/datasets/{siteUrl}/tables/{table}/items/{id}",
-          method: "DELETE",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "table", in: "path", required: true },
-            { name: "id", in: "path", required: true },
-          ],
-        },
-        GetTables: {
-          path: "/{connectionId}/datasets/{siteUrl}/tables",
-          method: "GET",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-          ],
-        },
-        GetDataSetsMetadata: {
-          path: "/{connectionId}/datasets/{siteUrl}",
-          method: "GET",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-          ],
-        },
-        CreateFile: {
-          path: "/{connectionId}/datasets/{siteUrl}/files",
-          method: "POST",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "folderPath", in: "query", required: true },
-            { name: "name", in: "query", required: true },
-            { name: "body", in: "body", required: true },
-          ],
-        },
-        UpdateFile: {
-          path: "/{connectionId}/datasets/{siteUrl}/files/{id}",
-          method: "PUT",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "id", in: "path", required: true },
-            { name: "body", in: "body", required: true },
-          ],
-        },
-        DeleteFile: {
-          path: "/{connectionId}/datasets/{siteUrl}/files/{id}",
-          method: "DELETE",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "id", in: "path", required: true },
-          ],
-        },
-        MoveFile: {
-          path: "/{connectionId}/datasets/{siteUrl}/files/{id}/moveto",
-          method: "POST",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "id", in: "path", required: true },
-            { name: "destinationFolderPath", in: "query", required: true },
-            { name: "newFileName", in: "query", required: false },
-          ],
-        },
-        GetFileMetadata: {
-          path: "/{connectionId}/datasets/{siteUrl}/files/{id}",
-          method: "GET",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-            { name: "siteUrl", in: "path", required: true },
-            { name: "id", in: "path", required: true },
-          ],
-        },
-        HttpRequest: {
-          path: "/{connectionId}/httprequest",
-          method: "POST",
-          parameters: [
-            { name: "connectionId", in: "path", required: true },
-          ],
-        },
+import { getClient } from '../power-apps-data.js';
+import { _dbgWrap } from '../codeapp.js';
+
+const DATA_SOURCE_NAME = 'sharepointonline';
+
+const dataSourcesInfo = {
+  [DATA_SOURCE_NAME]: {
+    tableId: '',
+    version: '',
+    primaryKey: '',
+    dataSourceType: 'Connector',
+    apis: {
+      GetItems: {
+        path: '/{connectionId}/datasets/{siteUrl}/tables/{table}/items',
+        method: 'GET',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'table', in: 'path', required: true, type: 'string' },
+          { name: '$filter', in: 'query', required: false, type: 'string' },
+          { name: '$orderby', in: 'query', required: false, type: 'string' },
+          { name: '$top', in: 'query', required: false, type: 'integer' },
+          { name: '$skip', in: 'query', required: false, type: 'integer' },
+        ],
+      },
+      GetItem: {
+        path: '/{connectionId}/datasets/{siteUrl}/tables/{table}/items/{id}',
+        method: 'GET',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'table', in: 'path', required: true, type: 'string' },
+          { name: 'id', in: 'path', required: true, type: 'string' },
+        ],
+      },
+      PostItem: {
+        path: '/{connectionId}/datasets/{siteUrl}/tables/{table}/items',
+        method: 'POST',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'table', in: 'path', required: true, type: 'string' },
+          { name: 'item', in: 'body', required: true, type: 'object' },
+        ],
+      },
+      PatchItem: {
+        path: '/{connectionId}/datasets/{siteUrl}/tables/{table}/items/{id}',
+        method: 'PATCH',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'table', in: 'path', required: true, type: 'string' },
+          { name: 'id', in: 'path', required: true, type: 'string' },
+          { name: 'item', in: 'body', required: true, type: 'object' },
+        ],
+      },
+      DeleteItem: {
+        path: '/{connectionId}/datasets/{siteUrl}/tables/{table}/items/{id}',
+        method: 'DELETE',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'table', in: 'path', required: true, type: 'string' },
+          { name: 'id', in: 'path', required: true, type: 'string' },
+        ],
+      },
+      GetTables: {
+        path: '/{connectionId}/datasets/{siteUrl}/tables',
+        method: 'GET',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+        ],
+      },
+      GetDataSetsMetadata: {
+        path: '/{connectionId}/datasets/{siteUrl}',
+        method: 'GET',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+        ],
+      },
+      CreateFile: {
+        path: '/{connectionId}/datasets/{siteUrl}/files',
+        method: 'POST',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'folderPath', in: 'query', required: true, type: 'string' },
+          { name: 'name', in: 'query', required: true, type: 'string' },
+          { name: 'body', in: 'body', required: true, type: 'object' },
+        ],
+      },
+      UpdateFile: {
+        path: '/{connectionId}/datasets/{siteUrl}/files/{id}',
+        method: 'PUT',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'id', in: 'path', required: true, type: 'string' },
+          { name: 'body', in: 'body', required: true, type: 'object' },
+        ],
+      },
+      DeleteFile: {
+        path: '/{connectionId}/datasets/{siteUrl}/files/{id}',
+        method: 'DELETE',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'id', in: 'path', required: true, type: 'string' },
+        ],
+      },
+      MoveFile: {
+        path: '/{connectionId}/datasets/{siteUrl}/files/{id}/moveto',
+        method: 'POST',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'id', in: 'path', required: true, type: 'string' },
+          { name: 'destinationFolderPath', in: 'query', required: true, type: 'string' },
+          { name: 'newFileName', in: 'query', required: false, type: 'string' },
+        ],
+      },
+      GetFileMetadata: {
+        path: '/{connectionId}/datasets/{siteUrl}/files/{id}',
+        method: 'GET',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'siteUrl', in: 'path', required: true, type: 'string' },
+          { name: 'id', in: 'path', required: true, type: 'string' },
+        ],
+      },
+      HttpRequest: {
+        path: '/{connectionId}/httprequest',
+        method: 'POST',
+        parameters: [
+          { name: 'connectionId', in: 'path', required: true, type: 'string' },
+          { name: 'method', in: 'body', required: true, type: 'string' },
+          { name: 'uri', in: 'body', required: true, type: 'string' },
+          { name: 'headers', in: 'body', required: false, type: 'object' },
+          { name: 'body', in: 'body', required: false, type: 'string' },
+        ],
       },
     },
-  };
+  },
+};
+
+const sharePointListCache = new Map();
+
+function initSharePointClient() {
   return getClient(dataSourcesInfo);
 }
 
-// ── Internal: execute a connector operation ────────────────────
-async function execSpOp(operationName, parameters) {
+async function executeConnectorOperation(operationName, parameters = {}) {
   try {
-    const client = await initSpClient();
-    const result = await client.executeAsync({
+    const oClient = await initSharePointClient();
+    const oResult = await oClient.executeAsync({
       connectorOperation: {
-        tableName: DATA_SOURCE_SP,
+        tableName: DATA_SOURCE_NAME,
         operationName,
-        parameters: parameters || {},
+        parameters,
       },
     });
 
-    if (!result) {
-      throw new Error("No result returned");
+    if (!oResult) {
+      throw new Error('No result returned');
     }
 
-    if (result.success === false) {
-      throw new Error(getSpErrorMessage(result.error));
+    if (oResult.success === false) {
+      throw new Error(getSpErrorMessage(oResult.error));
     }
 
-    return Object.prototype.hasOwnProperty.call(result, "data") ? result.data : result;
+    return Object.prototype.hasOwnProperty.call(oResult, 'data') ? oResult.data : oResult;
   } catch (oError) {
-    throw new Error("SharePoint " + operationName + " failed: " + getSpErrorMessage(oError));
+    throw new Error('SharePoint ' + operationName + ' failed: ' + getSpErrorMessage(oError));
   }
 }
 
+function pickSharePointValue() {
+  for (let iIndex = 0; iIndex < arguments.length; iIndex += 1) {
+    const oValue = arguments[iIndex];
+    if (oValue !== undefined && oValue !== null) {
+      return oValue;
+    }
+  }
+
+  return undefined;
+}
+
+function isSharePointRecord(oValue) {
+  return !!oValue && typeof oValue === 'object' && !Array.isArray(oValue);
+}
+
 function getSpErrorMessage(oError) {
   if (!oError) {
-    return "Unknown error";
+    return 'Unknown error';
   }
 
-  if (typeof oError === "string") {
+  if (typeof oError === 'string') {
     return oError;
   }
 
@@ -197,10 +213,7 @@ function getSpErrorMessage(oError) {
     oError.detail,
   ];
 
-  const sCandidate = aCandidates.find(function(sValue) {
-    return typeof sValue === "string" && sValue.trim() !== "";
-  });
-
+  const sCandidate = aCandidates.find((sValue) => typeof sValue === 'string' && sValue.trim() !== '');
   if (sCandidate) {
     return sCandidate;
   }
@@ -213,16 +226,16 @@ function getSpErrorMessage(oError) {
 }
 
 function requireNonEmptyString(sValue, sLabel) {
-  if (typeof sValue !== "string" || sValue.trim() === "") {
-    throw new Error("SharePoint " + sLabel + " is required.");
+  if (typeof sValue !== 'string' || sValue.trim() === '') {
+    throw new Error('SharePoint ' + sLabel + ' is required.');
   }
 
   return sValue.trim();
 }
 
 function requireRecord(oValue, sLabel) {
-  if (!oValue || typeof oValue !== "object" || Array.isArray(oValue)) {
-    throw new Error("SharePoint " + sLabel + " must be an object.");
+  if (!oValue || typeof oValue !== 'object' || Array.isArray(oValue)) {
+    throw new Error('SharePoint ' + sLabel + ' must be an object.');
   }
 
   return oValue;
@@ -233,60 +246,64 @@ function normalizeHeaders(oHeaders) {
     return {};
   }
 
-  if (typeof oHeaders !== "object" || Array.isArray(oHeaders)) {
-    throw new Error("SharePoint request headers must be an object.");
+  if (typeof oHeaders !== 'object' || Array.isArray(oHeaders)) {
+    throw new Error('SharePoint request headers must be an object.');
   }
 
   return oHeaders;
 }
 
 function normalizeNumericQueryValue(value, sLabel) {
-  if (value == null || value === "") {
+  if (value == null || value === '') {
     return null;
   }
 
   const iValue = Number(value);
   if (!Number.isFinite(iValue)) {
-    throw new Error("SharePoint " + sLabel + " must be numeric.");
+    throw new Error('SharePoint ' + sLabel + ' must be numeric.');
   }
 
   return iValue;
 }
 
 function requireItemId(iItemId) {
-  if ((typeof iItemId !== "string" && typeof iItemId !== "number") || String(iItemId).trim() === "") {
-    throw new Error("SharePoint item ID is required.");
+  if ((typeof iItemId !== 'string' && typeof iItemId !== 'number') || String(iItemId).trim() === '') {
+    throw new Error('SharePoint item ID is required.');
   }
 
   return iItemId;
 }
 
-function buildListContext(sSiteUrl, sListId) {
+function buildSiteUrlParam(siteUrl) {
+  return encodeURIComponent(requireNonEmptyString(siteUrl, 'site URL'));
+}
+
+function buildListContext(siteUrl, listId) {
   return {
-    siteUrl: encodeURIComponent(requireNonEmptyString(sSiteUrl, "site URL")),
-    table: requireNonEmptyString(sListId, "list ID"),
+    siteUrl: buildSiteUrlParam(siteUrl),
+    table: requireNonEmptyString(String(listId || ''), 'list ID'),
   };
 }
 
-function buildItemQueryParameters(sSiteUrl, sListId, { filter, orderBy, top, skip } = {}) {
-  const oParams = buildListContext(sSiteUrl, sListId);
+function buildItemQueryParameters(siteUrl, listId, { filter, orderBy, top, skip } = {}) {
+  const oParameters = buildListContext(siteUrl, listId);
   if (filter) {
-    oParams.$filter = String(filter);
+    oParameters.$filter = String(filter);
   }
   if (orderBy) {
-    oParams.$orderby = String(orderBy);
+    oParameters.$orderby = String(orderBy);
   }
 
-  const iTop = normalizeNumericQueryValue(top, "top");
-  const iSkip = normalizeNumericQueryValue(skip, "skip");
+  const iTop = normalizeNumericQueryValue(top, 'top');
+  const iSkip = normalizeNumericQueryValue(skip, 'skip');
   if (iTop != null) {
-    oParams.$top = iTop;
+    oParameters.$top = iTop;
   }
   if (iSkip != null) {
-    oParams.$skip = iSkip;
+    oParameters.$skip = iSkip;
   }
 
-  return oParams;
+  return oParameters;
 }
 
 function normalizeCollection(oPayload) {
@@ -306,161 +323,365 @@ function normalizeCollection(oPayload) {
     oPayload && oPayload.d && oPayload.d.results,
   ];
 
-  const aMatch = aCandidates.find(function(oCandidate) {
-    return Array.isArray(oCandidate);
-  });
-
+  const aMatch = aCandidates.find((oCandidate) => Array.isArray(oCandidate));
   return aMatch || [];
 }
 
-// ═══════════════════════════════════════════════════════════════
-//  GENERIC
-// ═══════════════════════════════════════════════════════════════
+function normalizeSharePointLookupValue(value) {
+  if (value === undefined || value === null) {
+    return '';
+  }
 
-// ── Call any SharePoint connector operation by name ─────────────
-export async function callSharePointOperation(operationName, parameters = {}) {
-  return _dbgWrap('callSharePointOperation', [operationName, parameters], async function() {
-  return execSpOp(operationName, parameters);
-  });
+  return String(value).trim().toLowerCase();
 }
 
-// ── Send HTTP Request (raw escape hatch) ───────────────────────
-export async function sendHttpRequest({ method = "GET", uri, headers, body } = {}) {
-  return _dbgWrap('sendHttpRequest', [{ method, uri, headers, body }], async function() {
-  return execSpOp("HttpRequest", {
-    method: String(method || "GET").toUpperCase(),
-    uri: requireNonEmptyString(uri, "request URI"),
-    headers: normalizeHeaders(headers),
-    body: body == null ? "" : body,
-  });
-  });
+function normalizeSharePointListReference(listReference) {
+  if (typeof listReference === 'string' || typeof listReference === 'number') {
+    const sValue = String(listReference).trim();
+    if (!sValue) {
+      throw new Error('SharePoint list reference is required.');
+    }
+
+    return { listName: sValue };
+  }
+
+  if (!isSharePointRecord(listReference)) {
+    throw new Error('SharePoint list reference must be a string or object.');
+  }
+
+  return listReference;
 }
 
-// ═══════════════════════════════════════════════════════════════
-//  ITEMS (standard API — uses list ID)
-// ═══════════════════════════════════════════════════════════════
+function getSharePointTableToken(oTable) {
+  const sCandidate = pickSharePointValue(
+    oTable && oTable.Name,
+    oTable && oTable.name,
+    oTable && oTable.table,
+    oTable && oTable.TableName,
+    oTable && oTable.tableName,
+    oTable && oTable.LogicalName,
+    oTable && oTable.logicalName
+  );
+
+  return typeof sCandidate === 'string' ? sCandidate.trim() : '';
+}
 
-// ── Get Items ──────────────────────────────────────────────────
-export async function getItems(sSiteUrl, sListId, { filter, orderBy, top, skip } = {}) {
-  return _dbgWrap('getItems', [sSiteUrl, sListId, { filter, orderBy, top, skip }], async function() {
-  return execSpOp("GetItems", buildItemQueryParameters(sSiteUrl, sListId, { filter, orderBy, top, skip }));
-  });
+function getSharePointExternalListId(oTable) {
+  const sCandidate = pickSharePointValue(
+    oTable && oTable.Id,
+    oTable && oTable.id,
+    oTable && oTable.TableId,
+    oTable && oTable.tableId,
+    oTable && oTable.ListId,
+    oTable && oTable.listId,
+    oTable && oTable.UniqueId,
+    oTable && oTable.uniqueId,
+    getSharePointTableToken(oTable)
+  );
+
+  return typeof sCandidate === 'string' ? sCandidate.trim() : '';
 }
 
-// ── Get Item ───────────────────────────────────────────────────
-export async function getSpItem(sSiteUrl, sListId, iItemId) {
-  return _dbgWrap('getSpItem', [sSiteUrl, sListId, iItemId], async function() {
-  return execSpOp("GetItem", Object.assign(buildListContext(sSiteUrl, sListId), {
-    id: requireItemId(iItemId),
-  }));
-  });
+function getSharePointTableNames(oTable) {
+  const aCandidates = [
+    oTable && oTable.DisplayName,
+    oTable && oTable.displayName,
+    oTable && oTable.Title,
+    oTable && oTable.title,
+    oTable && oTable.ListName,
+    oTable && oTable.listName,
+    oTable && oTable.Name,
+    oTable && oTable.name,
+  ];
+
+  return aCandidates
+    .filter((sValue, iIndex, aValues) => typeof sValue === 'string' && sValue.trim() !== '' && aValues.indexOf(sValue) === iIndex)
+    .map((sValue) => sValue.trim());
 }
 
-// ── Create Item ────────────────────────────────────────────────
-export async function createSpItem(sSiteUrl, sListId, oFields) {
-  return _dbgWrap('createSpItem', [sSiteUrl, sListId, oFields], async function() {
-  return execSpOp("PostItem", Object.assign(buildListContext(sSiteUrl, sListId), {
-    item: requireRecord(oFields, "item payload"),
-  }));
-  });
+function getSharePointPreferredListName(oTable, sFallback) {
+  return pickSharePointValue(...getSharePointTableNames(oTable), sFallback, '');
 }
 
-// ── Update Item ────────────────────────────────────────────────
-export async function updateSpItem(sSiteUrl, sListId, iItemId, oChangedFields) {
-  return _dbgWrap('updateSpItem', [sSiteUrl, sListId, iItemId, oChangedFields], async function() {
-  return execSpOp("PatchItem", Object.assign(buildListContext(sSiteUrl, sListId), {
-    id: requireItemId(iItemId),
-    item: requireRecord(oChangedFields, "item payload"),
-  }));
-  });
+function getSharePointListCacheKey(siteUrl, { listId, listName } = {}) {
+  return [
+    buildSiteUrlParam(siteUrl),
+    normalizeSharePointLookupValue(listId),
+    normalizeSharePointLookupValue(listName),
+  ].join('::');
 }
 
-// ── Delete Item ────────────────────────────────────────────────
-export async function deleteSpItem(sSiteUrl, sListId, iItemId) {
-  return _dbgWrap('deleteSpItem', [sSiteUrl, sListId, iItemId], async function() {
-  return execSpOp("DeleteItem", Object.assign(buildListContext(sSiteUrl, sListId), {
-    id: requireItemId(iItemId),
-  }));
-  });
+function createResolvedSharePointList(siteUrl, oTable, { listId, listName, accessLabel, matchedBy } = {}) {
+  const sSiteUrl = requireNonEmptyString(siteUrl, 'site URL');
+  const sTableToken = requireNonEmptyString(getSharePointTableToken(oTable) || getSharePointExternalListId(oTable), 'table token');
+  const sResolvedListId = requireNonEmptyString(getSharePointExternalListId(oTable) || listId || sTableToken, 'list ID');
+  const sResolvedListName = getSharePointPreferredListName(oTable, listName || sResolvedListId);
+  const sAccessLabel = pickSharePointValue(accessLabel, 'Connector table API');
+  const sMatchedBy = pickSharePointValue(matchedBy, 'connector table lookup');
+
+  return {
+    siteUrl: sSiteUrl,
+    listId: sResolvedListId,
+    listName: sResolvedListName,
+    table: sTableToken,
+    accessLabel: sAccessLabel,
+    matchedBy: sMatchedBy,
+    rawTable: oTable || null,
+    sSiteUrl: sSiteUrl,
+    sListId: sResolvedListId,
+    sListName: sResolvedListName,
+    sAccessLabel: sAccessLabel,
+    sMatchedBy: sMatchedBy,
+    oTable: oTable || null,
+  };
 }
 
-// ═══════════════════════════════════════════════════════════════
-//  TABLES / LISTS
-// ═══════════════════════════════════════════════════════════════
+function createConfiguredSharePointList(siteUrl, { listId, listName, accessLabel, matchedBy } = {}) {
+  const sSiteUrl = requireNonEmptyString(siteUrl, 'site URL');
+  const sResolvedListId = requireNonEmptyString(String(listId || ''), 'list ID');
+  const sResolvedListName = requireNonEmptyString(String(listName || sResolvedListId), 'list name');
+  const sAccessLabel = pickSharePointValue(accessLabel, 'Configured list ID');
+  const sMatchedBy = pickSharePointValue(matchedBy, 'configured list ID');
 
-// ── List Tables (Lists) ────────────────────────────────────────
-export async function listTables(sSiteUrl) {
-  return _dbgWrap('listTables', [sSiteUrl], async function() {
-  return normalizeCollection(await execSpOp("GetTables", {
-    siteUrl: encodeURIComponent(requireNonEmptyString(sSiteUrl, "site URL")),
-  }));
-  });
+  return {
+    siteUrl: sSiteUrl,
+    listId: sResolvedListId,
+    listName: sResolvedListName,
+    table: sResolvedListId,
+    accessLabel: sAccessLabel,
+    matchedBy: sMatchedBy,
+    rawTable: null,
+    sSiteUrl: sSiteUrl,
+    sListId: sResolvedListId,
+    sListName: sResolvedListName,
+    sAccessLabel: sAccessLabel,
+    sMatchedBy: sMatchedBy,
+    oTable: null,
+  };
 }
 
-// ── List Library (Document Libraries) ──────────────────────────
-export async function listLibrary(sSiteUrl) {
-  return _dbgWrap('listLibrary', [sSiteUrl], async function() {
-  return execSpOp("GetDataSetsMetadata", {
-    siteUrl: encodeURIComponent(requireNonEmptyString(sSiteUrl, "site URL")),
-  });
-  });
+function findSharePointTable(aTables, { listId, listName } = {}) {
+  const sNormalizedListId = normalizeSharePointLookupValue(listId);
+  const sNormalizedListName = normalizeSharePointLookupValue(listName);
+
+  return normalizeCollection(aTables).find((oTable) => {
+    const aIdCandidates = [
+      getSharePointTableToken(oTable),
+      getSharePointExternalListId(oTable),
+    ].map((sValue) => normalizeSharePointLookupValue(sValue)).filter(Boolean);
+
+    if (sNormalizedListId && aIdCandidates.indexOf(sNormalizedListId) !== -1) {
+      return true;
+    }
+
+    if (!sNormalizedListName) {
+      return false;
+    }
+
+    return getSharePointTableNames(oTable).some((sCandidate) => normalizeSharePointLookupValue(sCandidate) === sNormalizedListName);
+  }) || null;
 }
 
-// ═══════════════════════════════════════════════════════════════
-//  FILES
-// ═══════════════════════════════════════════════════════════════
-
-// ── Create File ────────────────────────────────────────────────
-export async function createFile(sSiteUrl, sLibraryName, sFileName, fileContent) {
-  return _dbgWrap('createFile', [sSiteUrl, sLibraryName, sFileName, fileContent], async function() {
-  return execSpOp("CreateFile", {
-    siteUrl: encodeURIComponent(requireNonEmptyString(sSiteUrl, "site URL")),
-    folderPath: requireNonEmptyString(sLibraryName, "folder path"),
-    name: requireNonEmptyString(sFileName, "file name"),
-    body: fileContent,
+export const callSharePointOperation = async (operationName, parameters = {}) => _dbgWrap('callSharePointOperation', [operationName, parameters], async function() {
+  return executeConnectorOperation(operationName, parameters);
+});
+
+export const sendHttpRequest = async ({ method = 'GET', uri, headers, body } = {}) => _dbgWrap('sendHttpRequest', [{ method, uri, headers, body }], async function() {
+  return executeConnectorOperation('HttpRequest', {
+    method: String(method || 'GET').toUpperCase(),
+    uri: requireNonEmptyString(uri, 'request URI'),
+    headers: normalizeHeaders(headers),
+    body: body == null ? '' : body,
   });
+});
+
+export const getItems = async (siteUrl, listId, { filter, orderBy, top, skip } = {}) => _dbgWrap('getItems', [siteUrl, listId, { filter, orderBy, top, skip }], async function() {
+  return executeConnectorOperation('GetItems', buildItemQueryParameters(siteUrl, listId, { filter, orderBy, top, skip }));
+});
+
+export const getSpItem = async (siteUrl, listId, itemId) => _dbgWrap('getSpItem', [siteUrl, listId, itemId], async function() {
+  return executeConnectorOperation('GetItem', Object.assign(buildListContext(siteUrl, listId), {
+    id: requireItemId(itemId),
+  }));
+});
+
+export const createSpItem = async (siteUrl, listId, fields) => _dbgWrap('createSpItem', [siteUrl, listId, fields], async function() {
+  return executeConnectorOperation('PostItem', Object.assign(buildListContext(siteUrl, listId), {
+    item: requireRecord(fields, 'item payload'),
+  }));
+});
+
+export const updateSpItem = async (siteUrl, listId, itemId, changedFields) => _dbgWrap('updateSpItem', [siteUrl, listId, itemId, changedFields], async function() {
+  return executeConnectorOperation('PatchItem', Object.assign(buildListContext(siteUrl, listId), {
+    id: requireItemId(itemId),
+    item: requireRecord(changedFields, 'item payload'),
+  }));
+});
+
+export const deleteSpItem = async (siteUrl, listId, itemId) => _dbgWrap('deleteSpItem', [siteUrl, listId, itemId], async function() {
+  return executeConnectorOperation('DeleteItem', Object.assign(buildListContext(siteUrl, listId), {
+    id: requireItemId(itemId),
+  }));
+});
+
+export const listTables = async (siteUrl) => _dbgWrap('listTables', [siteUrl], async function() {
+  return normalizeCollection(await executeConnectorOperation('GetTables', {
+    siteUrl: buildSiteUrlParam(siteUrl),
+  }));
+});
+
+export const listLibrary = async (siteUrl) => _dbgWrap('listLibrary', [siteUrl], async function() {
+  return executeConnectorOperation('GetDataSetsMetadata', {
+    siteUrl: buildSiteUrlParam(siteUrl),
   });
-}
+});
+
+export const resolveSharePointList = async (siteUrl, listReference = {}) => _dbgWrap('resolveSharePointList', [siteUrl, listReference], async function() {
+  const sSiteUrl = requireNonEmptyString(siteUrl, 'site URL');
+  const oReference = normalizeSharePointListReference(listReference);
+  const sListId = typeof pickSharePointValue(oReference.listId, oReference.sListId, oReference.table) === 'string' ? pickSharePointValue(oReference.listId, oReference.sListId, oReference.table).trim() : '';
+  const sListName = typeof pickSharePointValue(oReference.listName, oReference.sListName, oReference.name, oReference.title) === 'string' ? pickSharePointValue(oReference.listName, oReference.sListName, oReference.name, oReference.title).trim() : '';
+  const bRefresh = oReference.refresh === true;
+  const bSkipTableLookup = oReference.skipTableLookup === true;
+
+  if (!sListId && !sListName) {
+    throw new Error('Provide a SharePoint listId or listName.');
+  }
+
+  const sCacheKey = getSharePointListCacheKey(sSiteUrl, { listId: sListId, listName: sListName });
+  if (!bRefresh && sharePointListCache.has(sCacheKey)) {
+    return sharePointListCache.get(sCacheKey);
+  }
+
+  let oResolvedList = null;
+  let oLookupError = null;
+
+  if (!bSkipTableLookup) {
+    try {
+      const aTables = await listTables(sSiteUrl);
+      const oMatchedTable = findSharePointTable(aTables, {
+        listId: sListId,
+        listName: sListName,
+      });
+
+      if (oMatchedTable) {
+        oResolvedList = createResolvedSharePointList(sSiteUrl, oMatchedTable, {
+          listId: sListId,
+          listName: sListName,
+          matchedBy: sListId ? 'connector table ID' : 'connector table name',
+        });
+      }
+    } catch (oError) {
+      oLookupError = oError;
+    }
+  }
+
+  if (!oResolvedList && sListId) {
+    oResolvedList = createConfiguredSharePointList(sSiteUrl, {
+      listId: sListId,
+      listName: sListName,
+    });
+  }
+
+  if (!oResolvedList && oLookupError) {
+    throw oLookupError;
+  }
 
-// ── Update File ────────────────────────────────────────────────
-export async function updateFile(sSiteUrl, sFileId, fileContent) {
-  return _dbgWrap('updateFile', [sSiteUrl, sFileId, fileContent], async function() {
-  return execSpOp("UpdateFile", {
-    siteUrl: encodeURIComponent(requireNonEmptyString(sSiteUrl, "site URL")),
-    id: requireNonEmptyString(String(sFileId || ""), "file ID"),
+  if (!oResolvedList) {
+    throw new Error('SharePoint list "' + sListName + '" was not found for site ' + sSiteUrl + '.');
+  }
+
+  sharePointListCache.set(sCacheKey, oResolvedList);
+  return oResolvedList;
+});
+
+export const getItemsByList = async (siteUrl, listReference, queryOptions = {}) => _dbgWrap('getItemsByList', [siteUrl, listReference, queryOptions], async function() {
+  const oResolvedList = await resolveSharePointList(siteUrl, listReference);
+  return getItems(oResolvedList.siteUrl, pickSharePointValue(oResolvedList.table, oResolvedList.listId), queryOptions);
+});
+
+export const getSpItemByList = async (siteUrl, listReference, itemId) => _dbgWrap('getSpItemByList', [siteUrl, listReference, itemId], async function() {
+  const oResolvedList = await resolveSharePointList(siteUrl, listReference);
+  return getSpItem(oResolvedList.siteUrl, pickSharePointValue(oResolvedList.table, oResolvedList.listId), itemId);
+});
+
+export const createSpItemByList = async (siteUrl, listReference, fields) => _dbgWrap('createSpItemByList', [siteUrl, listReference, fields], async function() {
+  const oResolvedList = await resolveSharePointList(siteUrl, listReference);
+  return createSpItem(oResolvedList.siteUrl, pickSharePointValue(oResolvedList.table, oResolvedList.listId), fields);
+});
+
+export const updateSpItemByList = async (siteUrl, listReference, itemId, changedFields) => _dbgWrap('updateSpItemByList', [siteUrl, listReference, itemId, changedFields], async function() {
+  const oResolvedList = await resolveSharePointList(siteUrl, listReference);
+  return updateSpItem(oResolvedList.siteUrl, pickSharePointValue(oResolvedList.table, oResolvedList.listId), itemId, changedFields);
+});
+
+export const deleteSpItemByList = async (siteUrl, listReference, itemId) => _dbgWrap('deleteSpItemByList', [siteUrl, listReference, itemId], async function() {
+  const oResolvedList = await resolveSharePointList(siteUrl, listReference);
+  return deleteSpItem(oResolvedList.siteUrl, pickSharePointValue(oResolvedList.table, oResolvedList.listId), itemId);
+});
+
+export const createFile = async (siteUrl, folderPath, fileName, fileContent) => _dbgWrap('createFile', [siteUrl, folderPath, fileName, fileContent], async function() {
+  return executeConnectorOperation('CreateFile', {
+    siteUrl: buildSiteUrlParam(siteUrl),
+    folderPath: requireNonEmptyString(folderPath, 'folder path'),
+    name: requireNonEmptyString(fileName, 'file name'),
     body: fileContent,
   });
-  });
-}
+});
 
-// ── Delete File ────────────────────────────────────────────────
-export async function deleteFile(sSiteUrl, sFileId) {
-  return _dbgWrap('deleteFile', [sSiteUrl, sFileId], async function() {
-  return execSpOp("DeleteFile", {
-    siteUrl: encodeURIComponent(requireNonEmptyString(sSiteUrl, "site URL")),
-    id: requireNonEmptyString(String(sFileId || ""), "file ID"),
-  });
+export const updateFile = async (siteUrl, fileId, fileContent) => _dbgWrap('updateFile', [siteUrl, fileId, fileContent], async function() {
+  return executeConnectorOperation('UpdateFile', {
+    siteUrl: buildSiteUrlParam(siteUrl),
+    id: requireNonEmptyString(String(fileId || ''), 'file ID'),
+    body: fileContent,
   });
-}
+});
 
-// ── Move File ──────────────────────────────────────────────────
-export async function moveFile(sSiteUrl, sSourceFileId, sDestinationFolderPath, sNewFileName) {
-  return _dbgWrap('moveFile', [sSiteUrl, sSourceFileId, sDestinationFolderPath, sNewFileName], async function() {
-  return execSpOp("MoveFile", {
-    siteUrl: encodeURIComponent(requireNonEmptyString(sSiteUrl, "site URL")),
-    id: requireNonEmptyString(String(sSourceFileId || ""), "source file ID"),
-    destinationFolderPath: requireNonEmptyString(sDestinationFolderPath, "destination folder path"),
-    newFileName: sNewFileName || "",
+export const deleteFile = async (siteUrl, fileId) => _dbgWrap('deleteFile', [siteUrl, fileId], async function() {
+  return executeConnectorOperation('DeleteFile', {
+    siteUrl: buildSiteUrlParam(siteUrl),
+    id: requireNonEmptyString(String(fileId || ''), 'file ID'),
   });
+});
+
+export const moveFile = async (siteUrl, sourceFileId, destinationFolderPath, newFileName) => _dbgWrap('moveFile', [siteUrl, sourceFileId, destinationFolderPath, newFileName], async function() {
+  return executeConnectorOperation('MoveFile', {
+    siteUrl: buildSiteUrlParam(siteUrl),
+    id: requireNonEmptyString(String(sourceFileId || ''), 'source file ID'),
+    destinationFolderPath: requireNonEmptyString(destinationFolderPath, 'destination folder path'),
+    newFileName: newFileName || '',
   });
-}
+});
 
-// ── Get File Metadata ──────────────────────────────────────────
-export async function getFileMetadata(sSiteUrl, sFileId) {
-  return _dbgWrap('getFileMetadata', [sSiteUrl, sFileId], async function() {
-  return execSpOp("GetFileMetadata", {
-    siteUrl: encodeURIComponent(requireNonEmptyString(sSiteUrl, "site URL")),
-    id: requireNonEmptyString(String(sFileId || ""), "file ID"),
-  });
+export const getFileMetadata = async (siteUrl, fileId) => _dbgWrap('getFileMetadata', [siteUrl, fileId], async function() {
+  return executeConnectorOperation('GetFileMetadata', {
+    siteUrl: buildSiteUrlParam(siteUrl),
+    id: requireNonEmptyString(String(fileId || ''), 'file ID'),
   });
-}
+});
+
+const SharePointService = {
+  callSharePointOperation,
+  sendHttpRequest,
+  resolveSharePointList,
+  getItems,
+  getSpItem,
+  createSpItem,
+  updateSpItem,
+  deleteSpItem,
+  getItemsByList,
+  getSpItemByList,
+  createSpItemByList,
+  updateSpItemByList,
+  deleteSpItemByList,
+  listTables,
+  listLibrary,
+  createFile,
+  updateFile,
+  deleteFile,
+  moveFile,
+  getFileMetadata,
+};
+
+export { SharePointService };
+export default SharePointService;