@apvee/spfx-react-toolkit 1.0.0

package/lib/hooks/useSPFxMSGraphClient.d.ts

@@ -0,0 +1,200 @@
+import type { MSGraphClientV3 } from '@microsoft/sp-http';
+/**
+ * Return type for useSPFxMSGraphClient hook
+ */
+export interface SPFxMSGraphClientInfo {
+    /**
+     * Native MSGraphClientV3 from SPFx.
+     * Provides access to Microsoft Graph API with built-in authentication.
+     */
+    readonly client: MSGraphClientV3 | undefined;
+    /**
+     * Invoke Graph API call with automatic state management.
+     * Tracks loading state and captures errors automatically.
+     *
+     * @param fn - Function that receives Graph client and returns a promise
+     * @returns Promise with the result
+     *
+     * @example
+     * ```tsx
+     * const { invoke } = useSPFxMSGraphClient();
+     *
+     * const user = await invoke(client =>
+     *   client.api('/me').select('displayName,mail').get()
+     * );
+     * ```
+     */
+    readonly invoke: <T>(fn: (client: MSGraphClientV3) => Promise<T>) => Promise<T>;
+    /**
+     * Loading state - true during invoke() calls.
+     * Does not track direct client usage.
+     */
+    readonly isLoading: boolean;
+    /**
+     * Last error from invoke() calls.
+     * Does not capture errors from direct client usage.
+     */
+    readonly error: Error | undefined;
+    /** Clear the current error */
+    readonly clearError: () => void;
+}
+/**
+ * Hook to access Microsoft Graph client with built-in state management
+ *
+ * Provides native MSGraphClientV3 for authenticated Microsoft Graph API access.
+ * Offers two usage patterns:
+ *
+ * 1. **invoke()** - Automatic state management (loading + error tracking)
+ * 2. **client** - Direct access for full control
+ *
+ * For type safety, install @microsoft/microsoft-graph-types:
+ * ```bash
+ * npm install @microsoft/microsoft-graph-types --save-dev
+ * ```
+ *
+ * And import SPFx types:
+ * ```typescript
+ * import type { MSGraphClientV3 } from '@microsoft/sp-http';
+ * import type * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
+ * ```
+ *
+ * Requirements:
+ * - MSGraphClientFactory available in SPFx context (v1.15.0+)
+ * - Appropriate Microsoft Graph permissions granted by admin
+ *
+ * @example Using invoke with state management
+ * ```tsx
+ * import type * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
+ *
+ * function UserProfile() {
+ *   const { invoke, isLoading, error, clearError } = useSPFxMSGraphClient();
+ *   const [user, setUser] = useState<MicrosoftGraph.User>();
+ *
+ *   const loadUser = () => {
+ *     invoke(client =>
+ *       client.api('/me')
+ *         .select('displayName,mail,jobTitle')
+ *         .get()
+ *     ).then(setUser);
+ *   };
+ *
+ *   useEffect(() => { loadUser(); }, []);
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return (
+ *     <MessageBar messageBarType={MessageBarType.error}>
+ *       {error.message}
+ *       <Link onClick={() => { clearError(); loadUser(); }}>Retry</Link>
+ *     </MessageBar>
+ *   );
+ *
+ *   return <div>{user?.displayName}</div>;
+ * }
+ * ```
+ *
+ * @example Using client directly for advanced control
+ * ```tsx
+ * import type { MSGraphClientV3 } from '@microsoft/sp-http';
+ * import type * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
+ *
+ * function MessagesList() {
+ *   const { client } = useSPFxMSGraphClient();
+ *   const [messages, setMessages] = useState<MicrosoftGraph.Message[]>([]);
+ *   const [loading, setLoading] = useState(false);
+ *
+ *   if (!client) return <Spinner label="Initializing Graph client..." />;
+ *
+ *   const loadMessages = async () => {
+ *     setLoading(true);
+ *     try {
+ *       const result = await client.api('/me/messages')
+ *         .version('v1.0')
+ *         .select('subject,from,receivedDateTime')
+ *         .filter("importance eq 'high'")
+ *         .orderBy('receivedDateTime DESC')
+ *         .top(20)
+ *         .get();
+ *       setMessages(result.value);
+ *     } catch (err) {
+ *       console.error(err);
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={loadMessages} disabled={loading}>Load</button>
+ *       {loading && <Spinner />}
+ *       <MessageList items={messages} />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example CRUD operations with invoke
+ * ```tsx
+ * function ContactsManager() {
+ *   const { invoke, isLoading, error } = useSPFxMSGraphClient();
+ *   const [contacts, setContacts] = useState([]);
+ *
+ *   const loadContacts = () => {
+ *     invoke(client =>
+ *       client.api('/me/contacts').get()
+ *     ).then(result => setContacts(result.value));
+ *   };
+ *
+ *   const createContact = (contact: any) => {
+ *     invoke(client =>
+ *       client.api('/me/contacts').post(contact)
+ *     ).then(newContact => setContacts([...contacts, newContact]));
+ *   };
+ *
+ *   const updateContact = (id: string, changes: any) => {
+ *     invoke(client =>
+ *       client.api(`/me/contacts/${id}`).patch(changes)
+ *     ).then(loadContacts);
+ *   };
+ *
+ *   const deleteContact = (id: string) => {
+ *     invoke(client =>
+ *       client.api(`/me/contacts/${id}`).delete()
+ *     ).then(() => setContacts(contacts.filter(c => c.id !== id)));
+ *   };
+ *
+ *   return (
+ *     <ContactsUI
+ *       contacts={contacts}
+ *       loading={isLoading}
+ *       error={error}
+ *       onCreate={createContact}
+ *       onUpdate={updateContact}
+ *       onDelete={deleteContact}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example Batch operations with client
+ * ```tsx
+ * function BatchOperations() {
+ *   const { client } = useSPFxMSGraphClient();
+ *
+ *   if (!client) return <Spinner />;
+ *
+ *   const batchRequest = async () => {
+ *     const batch = {
+ *       requests: [
+ *         { id: '1', method: 'GET', url: '/me' },
+ *         { id: '2', method: 'GET', url: '/me/messages?$top=5' }
+ *       ]
+ *     };
+ *
+ *     const result = await client.api('/$batch').post(batch);
+ *     console.log(result);
+ *   };
+ * }
+ * ```
+ */
+export declare function useSPFxMSGraphClient(): SPFxMSGraphClientInfo;
+//# sourceMappingURL=useSPFxMSGraphClient.d.ts.map

package/lib/hooks/useSPFxMSGraphClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxMSGraphClient.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxMSGraphClient.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IAE7C;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAEhF;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IAElC,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6JG;AACH,wBAAgB,oBAAoB,IAAI,qBAAqB,CAkE5D"}

package/lib/hooks/useSPFxMSGraphClient.js

@@ -0,0 +1,264 @@
+// useSPFxMSGraphClient.ts
+// Hook to access Microsoft Graph client with state management
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import { useState, useCallback, useEffect } from 'react';
+import { useSPFxContext } from './useSPFxContext';
+/**
+ * Hook to access Microsoft Graph client with built-in state management
+ *
+ * Provides native MSGraphClientV3 for authenticated Microsoft Graph API access.
+ * Offers two usage patterns:
+ *
+ * 1. **invoke()** - Automatic state management (loading + error tracking)
+ * 2. **client** - Direct access for full control
+ *
+ * For type safety, install @microsoft/microsoft-graph-types:
+ * ```bash
+ * npm install @microsoft/microsoft-graph-types --save-dev
+ * ```
+ *
+ * And import SPFx types:
+ * ```typescript
+ * import type { MSGraphClientV3 } from '@microsoft/sp-http';
+ * import type * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
+ * ```
+ *
+ * Requirements:
+ * - MSGraphClientFactory available in SPFx context (v1.15.0+)
+ * - Appropriate Microsoft Graph permissions granted by admin
+ *
+ * @example Using invoke with state management
+ * ```tsx
+ * import type * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
+ *
+ * function UserProfile() {
+ *   const { invoke, isLoading, error, clearError } = useSPFxMSGraphClient();
+ *   const [user, setUser] = useState<MicrosoftGraph.User>();
+ *
+ *   const loadUser = () => {
+ *     invoke(client =>
+ *       client.api('/me')
+ *         .select('displayName,mail,jobTitle')
+ *         .get()
+ *     ).then(setUser);
+ *   };
+ *
+ *   useEffect(() => { loadUser(); }, []);
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return (
+ *     <MessageBar messageBarType={MessageBarType.error}>
+ *       {error.message}
+ *       <Link onClick={() => { clearError(); loadUser(); }}>Retry</Link>
+ *     </MessageBar>
+ *   );
+ *
+ *   return <div>{user?.displayName}</div>;
+ * }
+ * ```
+ *
+ * @example Using client directly for advanced control
+ * ```tsx
+ * import type { MSGraphClientV3 } from '@microsoft/sp-http';
+ * import type * as MicrosoftGraph from '@microsoft/microsoft-graph-types';
+ *
+ * function MessagesList() {
+ *   const { client } = useSPFxMSGraphClient();
+ *   const [messages, setMessages] = useState<MicrosoftGraph.Message[]>([]);
+ *   const [loading, setLoading] = useState(false);
+ *
+ *   if (!client) return <Spinner label="Initializing Graph client..." />;
+ *
+ *   const loadMessages = async () => {
+ *     setLoading(true);
+ *     try {
+ *       const result = await client.api('/me/messages')
+ *         .version('v1.0')
+ *         .select('subject,from,receivedDateTime')
+ *         .filter("importance eq 'high'")
+ *         .orderBy('receivedDateTime DESC')
+ *         .top(20)
+ *         .get();
+ *       setMessages(result.value);
+ *     } catch (err) {
+ *       console.error(err);
+ *     } finally {
+ *       setLoading(false);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={loadMessages} disabled={loading}>Load</button>
+ *       {loading && <Spinner />}
+ *       <MessageList items={messages} />
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example CRUD operations with invoke
+ * ```tsx
+ * function ContactsManager() {
+ *   const { invoke, isLoading, error } = useSPFxMSGraphClient();
+ *   const [contacts, setContacts] = useState([]);
+ *
+ *   const loadContacts = () => {
+ *     invoke(client =>
+ *       client.api('/me/contacts').get()
+ *     ).then(result => setContacts(result.value));
+ *   };
+ *
+ *   const createContact = (contact: any) => {
+ *     invoke(client =>
+ *       client.api('/me/contacts').post(contact)
+ *     ).then(newContact => setContacts([...contacts, newContact]));
+ *   };
+ *
+ *   const updateContact = (id: string, changes: any) => {
+ *     invoke(client =>
+ *       client.api(`/me/contacts/${id}`).patch(changes)
+ *     ).then(loadContacts);
+ *   };
+ *
+ *   const deleteContact = (id: string) => {
+ *     invoke(client =>
+ *       client.api(`/me/contacts/${id}`).delete()
+ *     ).then(() => setContacts(contacts.filter(c => c.id !== id)));
+ *   };
+ *
+ *   return (
+ *     <ContactsUI
+ *       contacts={contacts}
+ *       loading={isLoading}
+ *       error={error}
+ *       onCreate={createContact}
+ *       onUpdate={updateContact}
+ *       onDelete={deleteContact}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example Batch operations with client
+ * ```tsx
+ * function BatchOperations() {
+ *   const { client } = useSPFxMSGraphClient();
+ *
+ *   if (!client) return <Spinner />;
+ *
+ *   const batchRequest = async () => {
+ *     const batch = {
+ *       requests: [
+ *         { id: '1', method: 'GET', url: '/me' },
+ *         { id: '2', method: 'GET', url: '/me/messages?$top=5' }
+ *       ]
+ *     };
+ *
+ *     const result = await client.api('/$batch').post(batch);
+ *     console.log(result);
+ *   };
+ * }
+ * ```
+ */
+export function useSPFxMSGraphClient() {
+    var _this = this;
+    var spfxContext = useSPFxContext().spfxContext;
+    var _a = useState(undefined), client = _a[0], setClient = _a[1];
+    var _b = useState(false), isLoading = _b[0], setIsLoading = _b[1];
+    var _c = useState(undefined), error = _c[0], setError = _c[1];
+    // Initialize Graph client
+    useEffect(function () {
+        var ctx = spfxContext;
+        if (!ctx.msGraphClientFactory) {
+            console.warn('MSGraphClientFactory not available in SPFx context');
+            return;
+        }
+        // Get MSGraphClientV3 (version 3 of Microsoft Graph JavaScript Client Library)
+        ctx.msGraphClientFactory
+            .getClient('3')
+            .then(function (graphClient) {
+            setClient(graphClient);
+        })
+            .catch(function (err) {
+            console.error('Failed to initialize MSGraphClient:', err);
+        });
+    }, [spfxContext]);
+    // Invoke with automatic state management
+    var invoke = useCallback(function (fn) { return __awaiter(_this, void 0, void 0, function () {
+        var result, err_1, error_1;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!client) {
+                        throw new Error('Graph client not initialized. Wait for client to be available.');
+                    }
+                    setIsLoading(true);
+                    setError(undefined);
+                    _a.label = 1;
+                case 1:
+                    _a.trys.push([1, 3, 4, 5]);
+                    return [4 /*yield*/, fn(client)];
+                case 2:
+                    result = _a.sent();
+                    return [2 /*return*/, result];
+                case 3:
+                    err_1 = _a.sent();
+                    error_1 = err_1 instanceof Error ? err_1 : new Error(String(err_1));
+                    setError(error_1);
+                    throw error_1;
+                case 4:
+                    setIsLoading(false);
+                    return [7 /*endfinally*/];
+                case 5: return [2 /*return*/];
+            }
+        });
+    }); }, [client]);
+    // Clear error helper
+    var clearError = useCallback(function () {
+        setError(undefined);
+    }, []);
+    return {
+        client: client,
+        invoke: invoke,
+        isLoading: isLoading,
+        error: error,
+        clearError: clearError,
+    };
+}
+//# sourceMappingURL=useSPFxMSGraphClient.js.map

package/lib/hooks/useSPFxMSGraphClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSPFxMSGraphClient.js","sourceRoot":"","sources":["../../src/hooks/useSPFxMSGraphClient.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,8DAA8D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAE9D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA+ClD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6JG;AACH,MAAM,UAAU,oBAAoB;IAApC,iBAkEC;IAjES,IAAA,WAAW,GAAK,cAAc,EAAE,YAArB,CAAsB;IACnC,IAAA,KAAsB,QAAQ,CAA8B,SAAS,CAAC,EAArE,MAAM,QAAA,EAAE,SAAS,QAAoD,CAAC;IACvE,IAAA,KAA4B,QAAQ,CAAC,KAAK,CAAC,EAA1C,SAAS,QAAA,EAAE,YAAY,QAAmB,CAAC;IAC5C,IAAA,KAAoB,QAAQ,CAAoB,SAAS,CAAC,EAAzD,KAAK,QAAA,EAAE,QAAQ,QAA0C,CAAC;IAEjE,0BAA0B;IAC1B,SAAS,CAAC;QACR,IAAM,GAAG,GAAG,WAIX,CAAC;QAEF,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;YACnE,OAAO;QACT,CAAC;QAED,+EAA+E;QAC/E,GAAG,CAAC,oBAAoB;aACrB,SAAS,CAAC,GAAG,CAAC;aACd,IAAI,CAAC,UAAC,WAA4B;YACjC,SAAS,CAAC,WAAW,CAAC,CAAC;QACzB,CAAC,CAAC;aACD,KAAK,CAAC,UAAC,GAAU;YAChB,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,GAAG,CAAC,CAAC;QAC5D,CAAC,CAAC,CAAC;IACP,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAElB,yCAAyC;IACzC,IAAM,MAAM,GAAG,WAAW,CACxB,UAAU,EAA2C;;;;;oBACnD,IAAI,CAAC,MAAM,EAAE,CAAC;wBACZ,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;oBACpF,CAAC;oBAED,YAAY,CAAC,IAAI,CAAC,CAAC;oBACnB,QAAQ,CAAC,SAAS,CAAC,CAAC;;;;oBAGH,qBAAM,EAAE,CAAC,MAAM,CAAC,EAAA;;oBAAzB,MAAM,GAAG,SAAgB;oBAC/B,sBAAO,MAAM,EAAC;;;oBAER,UAAQ,KAAG,YAAY,KAAK,CAAC,CAAC,CAAC,KAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAG,CAAC,CAAC,CAAC;oBAClE,QAAQ,CAAC,OAAK,CAAC,CAAC;oBAChB,MAAM,OAAK,CAAC;;oBAEZ,YAAY,CAAC,KAAK,CAAC,CAAC;;;;;SAEvB,EACD,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,qBAAqB;IACrB,IAAM,UAAU,GAAG,WAAW,CAAC;QAC7B,QAAQ,CAAC,SAAS,CAAC,CAAC;IACtB,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO;QACL,MAAM,QAAA;QACN,MAAM,QAAA;QACN,SAAS,WAAA;QACT,KAAK,OAAA;QACL,UAAU,YAAA;KACX,CAAC;AACJ,CAAC"}