@forge/react 11.2.9-next.0 → 11.3.0-experimental-6de6b19

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @forge/react
 
+## 11.3.0-experimental-6de6b19
+
+### Minor Changes
+
+- 01521ac: add usePermissions hook
+
+### Patch Changes
+
+- Updated dependencies [01521ac]
+  - @forge/bridge@5.5.0-experimental-6de6b19
+
+## 11.3.0
+
+### Minor Changes
+
+- 1fe70bc: Add package.json exports configuration for improved TypeScript module resolution in forge-react package.
+
+### Patch Changes
+
+- 0371b03: Update type import from @forge/bridge
+- Updated dependencies [8e77d28]
+- Updated dependencies [185f844]
+  - @forge/bridge@5.5.0
+
+## 11.3.0-next.1
+
+### Patch Changes
+
+- 0371b03: Update type import from @forge/bridge
+- Updated dependencies [8e77d28]
+  - @forge/bridge@5.5.0-next.0
+
+## 11.3.0-next.0
+
+### Minor Changes
+
+- 1fe70bc: Add package.json exports configuration for improved TypeScript module resolution in forge-react package.
+
+## 11.2.9
+
+### Patch Changes
+
+- Updated dependencies [c51a29d]
+  - @forge/bridge@5.4.1
+
 ## 11.2.9-next.0
 
 ### Patch Changes

package/out/hooks/__test__/usePermissions.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=usePermissions.test.d.ts.map

package/out/hooks/__test__/usePermissions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePermissions.test.d.ts","sourceRoot":"","sources":["../../../src/hooks/__test__/usePermissions.test.tsx"],"names":[],"mappings":""}

package/out/hooks/__test__/usePermissions.test.js

@@ -0,0 +1,384 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_hooks_1 = require("@testing-library/react-hooks");
+const usePermissions_1 = require("../usePermissions");
+const testUtils_1 = require("../../__test__/testUtils");
+// Mock @forge/bridge
+jest.mock('@forge/bridge', () => ({
+    view: {
+        getContext: jest.fn()
+    }
+}));
+const mockGetContext = jest.fn();
+describe('usePermissions', () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        (0, testUtils_1.setupBridge)();
+        // Set up the mock to use our mockGetContext function
+        const { view } = require('@forge/bridge');
+        view.getContext.mockImplementation(mockGetContext);
+    });
+    describe('Loading state', () => {
+        it('should start with loading true', () => {
+            const requiredPermissions = {
+                scopes: ['read:confluence-content']
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            expect(result.current.isLoading).toBe(true);
+            expect(result.current.hasPermission).toBe(false);
+            expect(result.current.missingPermissions).toBe(null);
+            expect(result.current.error).toBe(null);
+        });
+        it('should set loading to false after context loads', async () => {
+            const mockContext = {
+                permissions: {
+                    scopes: ['read:confluence-content']
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                scopes: ['read:confluence-content']
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+            expect(result.current.missingPermissions).toBe(null);
+        });
+    });
+    describe('Error handling', () => {
+        it('should handle context loading errors', async () => {
+            const error = new Error('Failed to load context');
+            mockGetContext.mockRejectedValue(error);
+            const requiredPermissions = {
+                scopes: ['read:confluence-content']
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.error).toEqual(error);
+            expect(result.current.hasPermission).toBe(false);
+            expect(result.current.missingPermissions).toBe(null);
+        });
+        it('should handle non-Error objects in catch block', async () => {
+            mockGetContext.mockRejectedValue('String error');
+            const requiredPermissions = {
+                scopes: ['read:confluence-content']
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.error).toEqual(new Error('Failed to load context'));
+        });
+    });
+    describe('Scope permissions', () => {
+        it('should grant permission when all required scopes are present', async () => {
+            const mockContext = {
+                permissions: {
+                    scopes: ['read:confluence-content', 'write:confluence-content']
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                scopes: ['read:confluence-content']
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+            expect(result.current.missingPermissions).toBe(null);
+        });
+        it('should deny permission when required scopes are missing', async () => {
+            const mockContext = {
+                permissions: {
+                    scopes: ['read:confluence-content']
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                scopes: ['read:confluence-content', 'write:jira-work']
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(false);
+            expect(result.current.missingPermissions).toEqual({
+                scopes: ['write:jira-work']
+            });
+        });
+        it('should handle scopes as object format', async () => {
+            const mockContext = {
+                permissions: {
+                    scopes: {
+                        'read:confluence-content': { allowImpersonation: false },
+                        'write:confluence-content': { allowImpersonation: true }
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                scopes: ['read:confluence-content']
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+        });
+        it('should handle empty scopes array', async () => {
+            const mockContext = {
+                permissions: {
+                    scopes: []
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                scopes: []
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+        });
+    });
+    describe('External permissions', () => {
+        it('should grant permission for allowed fetch URLs', async () => {
+            const mockContext = {
+                permissions: {
+                    external: {
+                        fetch: {
+                            backend: ['https://api.example.com', 'https://api.test.com'],
+                            client: ['https://cdn.example.com']
+                        }
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                external: {
+                    fetch: {
+                        backend: ['https://api.example.com'],
+                        client: ['https://cdn.example.com']
+                    }
+                }
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+        });
+        it('should deny permission for disallowed fetch URLs', async () => {
+            const mockContext = {
+                permissions: {
+                    external: {
+                        fetch: {
+                            backend: ['https://api.example.com']
+                        }
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                external: {
+                    fetch: {
+                        backend: ['https://api.example.com', 'https://api.unauthorized.com']
+                    }
+                }
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(false);
+            expect(result.current.missingPermissions).toEqual({
+                external: {
+                    fetch: {
+                        backend: ['https://api.unauthorized.com']
+                    }
+                }
+            });
+        });
+        it('should handle wildcard URL patterns', async () => {
+            const mockContext = {
+                permissions: {
+                    external: {
+                        fetch: {
+                            backend: ['https://api.example.com/*', 'https://*.test.com']
+                        }
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                external: {
+                    fetch: {
+                        backend: ['https://api.example.com/users', 'https://subdomain.test.com/api']
+                    }
+                }
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+        });
+        it('should handle resource permissions (fonts, images, etc.)', async () => {
+            const mockContext = {
+                permissions: {
+                    external: {
+                        fonts: ['https://fonts.googleapis.com'],
+                        images: ['https://images.example.com'],
+                        scripts: ['https://scripts.example.com']
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                external: {
+                    fonts: ['https://fonts.googleapis.com'],
+                    images: ['https://images.example.com']
+                }
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+        });
+    });
+    // Note: Content permissions are not supported in the current RuntimePermissions type
+    describe('Complex permission scenarios', () => {
+        it('should handle mixed permission types', async () => {
+            const mockContext = {
+                permissions: {
+                    scopes: ['read:confluence-content'],
+                    external: {
+                        fetch: {
+                            backend: ['https://api.example.com']
+                        },
+                        images: ['https://images.example.com']
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                scopes: ['read:confluence-content'],
+                external: {
+                    fetch: {
+                        backend: ['https://api.example.com']
+                    },
+                    images: ['https://images.example.com']
+                }
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+        });
+        it('should identify missing permissions across different types', async () => {
+            const mockContext = {
+                permissions: {
+                    scopes: ['read:confluence-content'],
+                    external: {
+                        fetch: {
+                            backend: ['https://api.example.com']
+                        }
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                scopes: ['read:confluence-content', 'write:jira-work'],
+                external: {
+                    fetch: {
+                        backend: ['https://api.example.com', 'https://api.unauthorized.com'],
+                        client: ['https://cdn.example.com']
+                    },
+                    images: ['https://images.example.com']
+                }
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(false);
+            expect(result.current.missingPermissions).toEqual({
+                scopes: ['write:jira-work'],
+                external: {
+                    fetch: {
+                        backend: ['https://api.unauthorized.com'],
+                        client: ['https://cdn.example.com']
+                    },
+                    images: ['https://images.example.com']
+                }
+            });
+        });
+    });
+    describe('Edge cases', () => {
+        it('should handle empty required permissions', async () => {
+            const mockContext = {
+                permissions: {
+                    scopes: ['read:confluence-content']
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {};
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+            expect(result.current.missingPermissions).toBe(null);
+        });
+        it('should handle complex external permission objects', async () => {
+            const mockContext = {
+                permissions: {
+                    external: {
+                        fetch: {
+                            backend: [
+                                'https://api.example.com',
+                                { address: 'https://api.address.com' },
+                                { remote: 'https://api.remote.com' }
+                            ]
+                        }
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                external: {
+                    fetch: {
+                        backend: ['https://api.example.com', 'https://api.address.com']
+                    }
+                }
+            };
+            const { result } = (0, react_hooks_1.renderHook)(() => (0, usePermissions_1.usePermissions)(requiredPermissions));
+            await (0, react_hooks_1.act)(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+        });
+    });
+});

package/out/hooks/usePermissions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * TODO: reuse logic in permissions.ts from @forge/api
+ */
+export interface PermissionRequirements {
+    scopes?: string[];
+    external?: {
+        fetch?: {
+            backend?: string[];
+            client?: string[];
+        };
+        fonts?: string[];
+        styles?: string[];
+        frames?: string[];
+        images?: string[];
+        media?: string[];
+        scripts?: string[];
+    };
+    content?: Record<string, unknown>;
+}
+/**
+ * Missing permissions information
+ */
+export interface MissingPermissions {
+    scopes?: string[];
+    external?: {
+        fetch?: {
+            backend?: string[];
+            client?: string[];
+        };
+        fonts?: string[];
+        styles?: string[];
+        frames?: string[];
+        images?: string[];
+        media?: string[];
+        scripts?: string[];
+    };
+    content?: Record<string, unknown>;
+}
+/**
+ * Permission check result
+ */
+export interface PermissionCheckResult {
+    granted: boolean;
+    missing: MissingPermissions | null;
+}
+/**
+ * Hook for checking permissions in Forge apps
+ *
+ * @param requiredPermissions - The permissions required for the component
+ * @returns Object containing permission state and loading status
+ *
+ * @example
+ * ```tsx
+ * const MyComponent: React.FC = () => {
+ *   const { hasPermission, isLoading, missingPermissions } = usePermissions({
+ *     scopes: ['write:confluence-content'],
+ *     external: {
+ *       fetch: {
+ *         backend: ['https://api.example.com']
+ *       }
+ *     }
+ *   });
+ *
+ *   if (isLoading) return <LoadingSpinner />;
+ *
+ *   if (!hasPermission) {
+ *     return <PermissionDenied missingPermissions={missingPermissions} />;
+ *   }
+ *
+ *   return <ProtectedFeature />;
+ * };
+ * ```
+ */
+export declare const usePermissions: (requiredPermissions: PermissionRequirements) => {
+    hasPermission: boolean;
+    isLoading: boolean;
+    missingPermissions: MissingPermissions | null;
+    error: Error | null;
+};
+//# sourceMappingURL=usePermissions.d.ts.map

package/out/hooks/usePermissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePermissions.d.ts","sourceRoot":"","sources":["../../src/hooks/usePermissions.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE;YACN,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;YACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;SACnB,CAAC;QACF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE;YACN,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;YACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;SACnB,CAAC;QACF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACpC;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,cAAc,wBAAyB,sBAAsB;;;;;CAqJzE,CAAC"}