@forge/react 11.4.0 → 11.5.0-next.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @forge/react
 
+## 11.5.0-next.1
+
+### Minor Changes
+
+- 01521ac: add usePermissions hook
+
+### Patch Changes
+
+- Updated dependencies [01521ac]
+  - @forge/bridge@5.6.0-next.1
+
+## 11.4.1-next.0
+
+### Patch Changes
+
+- Updated dependencies [58a20e7]
+  - @forge/bridge@5.6.0-next.0
+
 ## 11.4.0
 
 ### Minor 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,413 @@
+"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('Interface inheritance', () => {
+        it('should allow PermissionRequirements to be used as Permissions', () => {
+            const requiredPermissions = {
+                scopes: ['read:confluence-content']
+            };
+            // This should compile without errors, demonstrating inheritance
+            const permissions = requiredPermissions;
+            expect(permissions.scopes).toEqual(['read:confluence-content']);
+        });
+        it('should allow MissingPermissions to be used as Permissions', () => {
+            const missingPermissions = {
+                scopes: ['write:jira-work']
+            };
+            // This should compile without errors, demonstrating inheritance
+            const permissions = missingPermissions;
+            expect(permissions.scopes).toEqual(['write:jira-work']);
+        });
+    });
+    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, 10));
+            });
+            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, 10));
+            });
+            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, 10));
+            });
+            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, 10));
+            });
+            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, 10));
+            });
+            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, 10));
+            });
+            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, 10));
+            });
+            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, 10));
+            });
+            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, 10));
+            });
+            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, 10));
+            });
+            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, 10));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+        });
+    });
+    describe('Complex permission scenarios', () => {
+        it('should handle mixed permission types', async () => {
+            const mockContext = {
+                permissions: {
+                    scopes: ['read:confluence-content', 'write:confluence-content', 'read:jira-work'],
+                    external: {
+                        fetch: {
+                            backend: ['https://api.example.com', 'https://api.test.com'],
+                            client: ['https://cdn.example.com', 'https://cdn.test.com']
+                        },
+                        images: ['https://images.example.com', 'https://images.test.com'],
+                        fonts: ['https://fonts.googleapis.com', 'https://fonts.gstatic.com'],
+                        scripts: ['https://scripts.example.com']
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                scopes: ['read:confluence-content', 'write:confluence-content'],
+                external: {
+                    fetch: {
+                        backend: ['https://api.example.com'],
+                        client: ['https://cdn.example.com']
+                    },
+                    images: ['https://images.example.com'],
+                    fonts: ['https://fonts.googleapis.com'],
+                    scripts: ['https://scripts.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, 10));
+            });
+            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', 'read:jira-work'],
+                    external: {
+                        fetch: {
+                            backend: ['https://api.example.com', 'https://api.authorized.com'],
+                            client: ['https://cdn.authorized.com']
+                        },
+                        images: ['https://images.authorized.com'],
+                        fonts: ['https://fonts.authorized.com']
+                    }
+                }
+            };
+            mockGetContext.mockResolvedValue(mockContext);
+            const requiredPermissions = {
+                scopes: ['read:confluence-content', 'write:jira-work', 'admin:confluence'],
+                external: {
+                    fetch: {
+                        backend: ['https://api.example.com', 'https://api.unauthorized.com', 'https://api.missing.com'],
+                        client: ['https://cdn.example.com', 'https://cdn.unauthorized.com']
+                    },
+                    images: ['https://images.example.com', 'https://images.unauthorized.com'],
+                    fonts: ['https://fonts.example.com'],
+                    scripts: ['https://scripts.example.com', 'https://scripts.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, 10));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(false);
+            expect(result.current.missingPermissions).toEqual({
+                scopes: ['write:jira-work', 'admin:confluence'],
+                external: {
+                    fetch: {
+                        backend: ['https://api.unauthorized.com', 'https://api.missing.com'],
+                        client: ['https://cdn.example.com', 'https://cdn.unauthorized.com']
+                    },
+                    images: ['https://images.example.com', 'https://images.unauthorized.com'],
+                    fonts: ['https://fonts.example.com'],
+                    scripts: ['https://scripts.example.com', 'https://scripts.unauthorized.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, 10));
+            });
+            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, 10));
+            });
+            expect(result.current.isLoading).toBe(false);
+            expect(result.current.hasPermission).toBe(true);
+        });
+    });
+});

package/out/hooks/usePermissions.d.ts

@@ -0,0 +1,89 @@
+/**
+ * https://ecosystem-platform.atlassian.net/browse/DEPLOY-1411
+ * reuse logic from @forge/api
+ */
+/**
+ * Resource types that can be loaded externally
+ */
+declare const RESOURCE_TYPES: readonly ["fonts", "styles", "frames", "images", "media", "scripts"];
+export declare type ResourceType = (typeof RESOURCE_TYPES)[number];
+/**
+ * Fetch types for external requests
+ */
+declare const FETCH_TYPES: readonly ["backend", "client"];
+export declare type FetchType = (typeof FETCH_TYPES)[number];
+export interface Permissions {
+    scopes?: string[];
+    external?: {
+        fetch?: {
+            backend?: string[];
+            client?: string[];
+        };
+        fonts?: string[];
+        styles?: string[];
+        frames?: string[];
+        images?: string[];
+        media?: string[];
+        scripts?: string[];
+    };
+    content?: Record<string, unknown>;
+}
+/**
+ * Required permissions for a component
+ */
+export declare type PermissionRequirements = Permissions;
+/**
+ * Missing permissions information
+ */
+export declare type MissingPermissions = Permissions;
+/**
+ * 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, loading status, and error information
+ * @returns hasPermission - Whether all required permissions are granted
+ * @returns isLoading - Whether the permission check is still in progress
+ * @returns missingPermissions - Details about which permissions are missing (null if all granted)
+ * @returns error - Any error that occurred during permission checking (null if no error)
+ *
+ * @example
+ * ```tsx
+ * const MyComponent: React.FC = () => {
+ *   const { hasPermission, isLoading, missingPermissions, error } = usePermissions({
+ *     scopes: ['write:confluence-content'],
+ *     external: {
+ *       fetch: {
+ *         backend: ['https://api.example.com']
+ *       }
+ *     }
+ *   });
+ *
+ *   if (isLoading) return <LoadingSpinner />;
+ *
+ *   if (error) {
+ *     return <ErrorMessage error={error} />;
+ *   }
+ *
+ *   if (!hasPermission) {
+ *     return <PermissionDenied missingPermissions={missingPermissions} />;
+ *   }
+ *
+ *   return <ProtectedFeature />;
+ * };
+ * ```
+ */
+export declare const usePermissions: (requiredPermissions: PermissionRequirements) => {
+    hasPermission: boolean;
+    isLoading: boolean;
+    missingPermissions: Permissions | null;
+    error: Error | null;
+};
+export {};
+//# 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":"AAIA;;;GAGG;AAEH;;GAEG;AACH,QAAA,MAAM,cAAc,sEAAuE,CAAC;AAC5F,oBAAY,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D;;GAEG;AACH,QAAA,MAAM,WAAW,gCAAiC,CAAC;AACnD,oBAAY,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,MAAM,WAAW,WAAW;IAC1B,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,oBAAY,sBAAsB,GAAG,WAAW,CAAC;AAEjD;;GAEG;AACH,oBAAY,kBAAkB,GAAG,WAAW,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACpC;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,cAAc,wBAAyB,sBAAsB;;;;;CA2JzE,CAAC"}