@apvee/spfx-react-toolkit 1.3.0 → 2.0.0

package/lib/hooks/useSPFxTenantProperty.d.ts

@@ -19,27 +19,12 @@ export interface SPFxTenantPropertyResult<T> {
     readonly isLoading: boolean;
     /**
      * Last error from read operations.
-     * Cleared on successful load or write.
+     * Cleared on successful load.
      */
     readonly error: Error | undefined;
-    /**
-     * Loading state for write operations.
-     * True during write() calls.
-     */
-    readonly isWriting: boolean;
-    /**
-     * Last error from write operations.
-     * Cleared on successful write or load.
-     */
-    readonly writeError: Error | undefined;
-    /**
-     * Whether the current user has permission to write tenant properties.
-     * False if user lacks Manage Web permissions on tenant app catalog.
-     */
-    readonly canWrite: boolean;
     /**
      * Manually load/reload the property from tenant app catalog.
-     * Updates data, description, comment, isLoading, and error states.
+     * Updates data, description, isLoading, and error states.
      *
      * @returns Promise that resolves when load completes
      *
@@ -52,48 +37,6 @@ export interface SPFxTenantPropertyResult<T> {
      * ```
      */
     readonly load: () => Promise<void>;
-    /**
-     * Write property to tenant app catalog.
-     * Creates property if it doesn't exist, updates if it does.
-     * Updates isWriting and writeError states.
-     *
-     * Smart serialization:
-     * - Primitives (string, number, boolean, null, bigint) → String(content)
-     * - Date objects → ISO string
-     * - Objects/arrays → JSON.stringify(content)
-     *
-     * @param content - Data to write
-     * @param description - Optional description metadata (SharePoint only supports description, not comment)
-     * @returns Promise that resolves when write completes
-     *
-     * @example
-     * ```tsx
-     * const { write, isWriting } = useSPFxTenantProperty<string>('apiEndpoint');
-     *
-     * const handleSave = async () => {
-     *   await write('https://api.example.com', 'Production API endpoint');
-     * };
-     * ```
-     */
-    readonly write: (content: T, description?: string) => Promise<void>;
-    /**
-     * Remove property from tenant app catalog.
-     * Requires Manage Web permissions.
-     *
-     * @returns Promise that resolves when removal completes
-     *
-     * @example
-     * ```tsx
-     * const { remove } = useSPFxTenantProperty<string>('oldSetting');
-     *
-     * const handleDelete = async () => {
-     *   if (confirm('Delete this property?')) {
-     *     await remove();
-     *   }
-     * };
-     * ```
-     */
-    readonly remove: () => Promise<void>;
     /**
      * Computed state: true if data is loaded successfully.
      * Equivalent to: !isLoading && !error && data !== undefined
@@ -107,111 +50,48 @@ export interface SPFxTenantPropertyResult<T> {
     readonly isReady: boolean;
 }
 /**
- * Hook to manage tenant-wide properties using SharePoint StorageEntity API
+ * Hook to read tenant-wide properties using SharePoint StorageEntity API (read-only)
  *
- * Provides read/write operations for tenant-scoped properties stored in the
- * SharePoint tenant app catalog. Properties are accessible across all sites
- * in the tenant and support metadata (description only).
+ * Provides read access to tenant-scoped properties stored in the SharePoint tenant
+ * app catalog. Properties are accessible across all sites in the tenant.
+ *
+ * **Note:** Write and remove operations have been removed because Microsoft has
+ * blocked the SetStorageEntity and RemoveStorageEntity REST API endpoints.
+ * Tenant properties can only be managed via PowerShell (Set-PnPStorageEntity,
+ * Remove-PnPStorageEntity) or the SharePoint Management Shell.
+ * For a read/write key-value store at tenant level, use `useSPFxTenantKeyValueStore`.
  *
  * Features:
  * - Tenant-wide centralized storage (not site-specific)
- * - Smart serialization for primitives, Date, and complex objects
- * - Permission checking (canWrite flag)
+ * - Smart deserialization for primitives and complex objects
  * - Optional metadata (description only - SharePoint limitation)
  * - Type-safe with TypeScript generics
  * - Memory leak safe with mounted state tracking
  * - Automatic app catalog URL discovery
- * - Remove operation for cleanup
  *
  * Requirements:
  * - Tenant app catalog must be provisioned
- * - Read: Any authenticated user
- * - Write/Remove: Site Collection Administrator role on tenant app catalog site
- *
- * Permission Notes:
- * - Being a Tenant Admin is NOT sufficient for write operations
- * - You must be explicitly added as Site Collection Administrator to the tenant app catalog
- * - Navigate to the app catalog site → Site Settings → Site Collection Administrators
- * - Add your user account if write operations fail with permission errors
- *
- * Storage Format:
- * - Primitives (string, number, boolean, null) → stored as string
- * - Date → stored as ISO 8601 string
- * - Objects/arrays → stored as JSON string
+ * - Any authenticated user can read tenant properties
  *
  * @param key - Unique property key (e.g., 'appVersion', 'apiEndpoint', 'featureFlags')
  * @param autoFetch - Whether to automatically load property on mount. Default: true
  *
- * @returns Object with data, metadata, loading states, error states, and CRUD functions
+ * @returns Object with data, metadata, loading state, error state, and load function
  *
  * @example Basic usage - string property
  * ```tsx
  * function VersionDisplay() {
- *   const { data, isLoading, error, write, canWrite } =
- *     useSPFxTenantProperty<string>('appVersion');
+ *   const { data, isLoading, error } = useSPFxTenantProperty<string>('appVersion');
  *
  *   if (isLoading) return <Spinner label="Loading version..." />;
  *   if (error) return <MessageBar messageBarType={MessageBarType.error}>
  *     Failed to load: {error.message}
  *   </MessageBar>;
  *
- *   const handleUpdate = async () => {
- *     if (!canWrite) {
- *       alert('Insufficient permissions');
- *       return;
- *     }
- *
- *     try {
- *       await write('2.0.1', 'Current application version');
- *       console.log('Version updated!');
- *     } catch (err) {
- *       console.error('Update failed:', err);
- *     }
- *   };
- *
- *   return (
- *     <div>
- *       <Text>Current Version: {data ?? 'Not Set'}</Text>
- *       {canWrite && <PrimaryButton onClick={handleUpdate}>Update Version</PrimaryButton>}
- *     </div>
- *   );
- * }
- * ```
- *
- * @example Number property
- * ```tsx
- * const { data, write } = useSPFxTenantProperty<number>('maxUploadSize');
- *
- * // Stored as "10485760" (10MB in bytes)
- * await write(10485760, 'Maximum file upload size in bytes');
- *
- * // Read returns: 10485760 (number)
- * console.log(typeof data); // "number"
- * ```
- *
- * @example Boolean flag
- * ```tsx
- * const { data: maintenanceMode, write } = useSPFxTenantProperty<boolean>('maintenanceMode');
- *
- * // Stored as "true" or "false"
- * await write(true, 'Maintenance mode enabled');
- *
- * if (maintenanceMode) {
- *   return <MessageBar>System is under maintenance</MessageBar>;
+ *   return <Text>Current Version: {data ?? 'Not Set'}</Text>;
  * }
  * ```
  *
- * @example Date property
- * ```tsx
- * const { data, write } = useSPFxTenantProperty<string>('lastDeployment');
- *
- * // Write date as ISO string
- * await write(new Date().toISOString(), 'Last deployment timestamp');
- *
- * // Read and convert back to Date
- * const lastDeploy = data ? new Date(data) : undefined;
- * ```
- *
  * @example Complex object with JSON
  * ```tsx
  * interface FeatureFlags {
@@ -220,74 +100,14 @@ export interface SPFxTenantPropertyResult<T> {
  *   maxUsers: number;
  * }
  *
- * const { data, write, isLoading } = useSPFxTenantProperty<FeatureFlags>('featureFlags');
- *
- * // Stored as JSON string
- * await write({
- *   enableChat: true,
- *   enableAnalytics: false,
- *   maxUsers: 1000
- * }, 'Global feature flags configuration');
+ * const { data, isLoading } = useSPFxTenantProperty<FeatureFlags>('featureFlags');
  *
- * // Read returns parsed object
+ * // Returns parsed object (stored as JSON string via PowerShell)
  * if (data?.enableChat) {
  *   return <ChatPanel />;
  * }
  * ```
  *
- * @example Permission-aware UI
- * ```tsx
- * function TenantConfigPanel() {
- *   const { data, canWrite, write, isWriting, error, writeError } =
- *     useSPFxTenantProperty<string>('apiEndpoint');
- *
- *   const [editValue, setEditValue] = React.useState(data ?? '');
- *
- *   React.useEffect(() => {
- *     setEditValue(data ?? '');
- *   }, [data]);
- *
- *   if (!canWrite) {
- *     return (
- *       <MessageBar messageBarType={MessageBarType.info}>
- *         You don't have permission to edit tenant properties.
- *         Contact your SharePoint administrator.
- *       </MessageBar>
- *     );
- *   }
- *
- *   const handleSave = async () => {
- *     try {
- *       await write(editValue, 'Production API endpoint URL');
- *     } catch (err) {
- *       console.error('Save failed:', err);
- *     }
- *   };
- *
- *   return (
- *     <Stack tokens={{ childrenGap: 10 }}>
- *       <TextField
- *         label="API Endpoint"
- *         value={editValue}
- *         onChange={(_, val) => setEditValue(val ?? '')}
- *         disabled={isWriting}
- *       />
- *       <PrimaryButton
- *         onClick={handleSave}
- *         disabled={isWriting || editValue === data}
- *       >
- *         {isWriting ? 'Saving...' : 'Save'}
- *       </PrimaryButton>
- *       {writeError && (
- *         <MessageBar messageBarType={MessageBarType.error}>
- *           {writeError.message}
- *         </MessageBar>
- *       )}
- *     </Stack>
- *   );
- * }
- * ```
- *
  * @example With metadata viewing
  * ```tsx
  * function PropertyViewer() {
@@ -307,7 +127,7 @@ export interface SPFxTenantPropertyResult<T> {
  *
  * @example Lazy loading with manual trigger
  * ```tsx
- * const { data, load, isLoading, write } = useSPFxTenantProperty<Config>(
+ * const { data, load, isLoading } = useSPFxTenantProperty<Config>(
  *   'appConfig',
  *   false  // Don't auto-fetch
  * );
@@ -322,64 +142,23 @@ export interface SPFxTenantPropertyResult<T> {
  * );
  * ```
  *
- * @example Property removal
- * ```tsx
- * function PropertyManager() {
- *   const { data, remove, canWrite } = useSPFxTenantProperty<string>('deprecatedSetting');
- *
- *   const handleDelete = async () => {
- *     if (!confirm('Delete this property? This cannot be undone.')) return;
- *
- *     try {
- *       await remove();
- *       console.log('Property deleted');
- *     } catch (err) {
- *       console.error('Delete failed:', err);
- *     }
- *   };
- *
- *   if (!data) return <Text>Property not found</Text>;
- *
- *   return (
- *     <Stack tokens={{ childrenGap: 10 }}>
- *       <Text>Value: {data}</Text>
- *       {canWrite && (
- *         <DefaultButton onClick={handleDelete} text="Delete Property" />
- *       )}
- *     </Stack>
- *   );
- * }
- * ```
- *
  * @example Multi-property dashboard
  * ```tsx
  * function TenantDashboard() {
  *   const version = useSPFxTenantProperty<string>('appVersion');
  *   const maintenance = useSPFxTenantProperty<boolean>('maintenanceMode');
- *   const lastUpdate = useSPFxTenantProperty<string>('lastUpdate');
  *   const config = useSPFxTenantProperty<AppConfig>('appConfig');
  *
- *   const isLoading = version.isLoading || maintenance.isLoading ||
- *                     lastUpdate.isLoading || config.isLoading;
+ *   const isLoading = version.isLoading || maintenance.isLoading || config.isLoading;
  *
  *   if (isLoading) return <Spinner label="Loading dashboard..." />;
  *
  *   return (
  *     <Stack tokens={{ childrenGap: 20 }}>
  *       <Text variant="xxLarge">Tenant Configuration</Text>
- *
- *       <Stack tokens={{ childrenGap: 10 }}>
- *         <Label>App Version: {version.data ?? 'Not Set'}</Label>
- *         <Label>Maintenance Mode: {maintenance.data ? 'ON' : 'OFF'}</Label>
- *         <Label>Last Update: {lastUpdate.data ? new Date(lastUpdate.data).toLocaleString() : 'Never'}</Label>
- *       </Stack>
- *
- *       {config.data && (
- *         <Stack tokens={{ childrenGap: 5 }}>
- *           <Text variant="large">Configuration</Text>
- *           <pre>{JSON.stringify(config.data, null, 2)}</pre>
- *         </Stack>
- *       )}
+ *       <Label>App Version: {version.data ?? 'Not Set'}</Label>
+ *       <Label>Maintenance Mode: {maintenance.data ? 'ON' : 'OFF'}</Label>
+ *       {config.data && <pre>{JSON.stringify(config.data, null, 2)}</pre>}
  *     </Stack>
  *   );
  * }

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

@@ -1 +1 @@
-{"version":3,"file":"useSPFxTenantProperty.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxTenantProperty.ts"],"names":[],"mappings":"AASA;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,SAAS,CAAC;IAEvC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpE;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAErC;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsRG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EAC/C,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,OAAc,GACxB,wBAAwB,CAAC,CAAC,CAAC,CA0V7B"}
+{"version":3,"file":"useSPFxTenantProperty.d.ts","sourceRoot":"","sources":["../../src/hooks/useSPFxTenantProperty.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAEzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC;IAElC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,GAAG,OAAO,EAC/C,GAAG,EAAE,MAAM,EACX,SAAS,GAAE,OAAc,GACxB,wBAAwB,CAAC,CAAC,CAAC,CAmG7B"}