@datalayer/core 1.0.20 → 1.0.22

package/lib/hooks/useCache.js

@@ -4,11 +4,9 @@
  */
 /**
  * TanStack Query-based cache hook for Datalayer API
+ * for automatic cache management, background refetching,
+ * and optimistic updates.
  *
- * This is a modernized replacement for useCache.tsx that leverages TanStack Query
- * for automatic cache management, background refetching, and optimistic updates.
- *
- * Key improvements over useCache:
  * - Automatic cache management (no manual Map objects)
  * - Built-in loading/error states
  * - Automatic refetching and deduplication
@@ -42,7 +40,6 @@ import { useQuery, useMutation, useQueryClient, } from '@tanstack/react-query';
 import { BOOTSTRAP_USER_ONBOARDING, asContact, asDatasource, asInvite, asOrganization, asPage, asSecret, asSpace, asTeam, asToken, asUser, } from '../models/index.js';
 import { useCoreStore, useIAMStore } from '../state/index.js';
 import { asDisplayName, namesAsInitials, asArray } from '../utils/index.js';
-import { newUserMock } from './../mocks/index.js';
 import { useDatalayer } from './useDatalayer.js';
 import { useAuthorization } from './useAuthorization.js';
 import { useUploadForm } from './useUpload.js';
@@ -81,7 +78,9 @@ export const queryKeys = {
         details: () => [...queryKeys.users.all(), 'detail'],
         detail: (id) => [...queryKeys.users.details(), id],
         byHandle: (handle) => [...queryKeys.users.all(), 'handle', handle],
+        publicProfileByHandle: (handle) => [...queryKeys.users.all(), 'public-profile', handle],
         search: (pattern) => [...queryKeys.users.all(), 'search', pattern],
+        bulk: (userIdsKey) => [...queryKeys.users.all(), 'bulk', userIdsKey],
         settings: (userId) => [...queryKeys.users.detail(userId), 'settings'],
         onboarding: (userId) => [...queryKeys.users.detail(userId), 'onboarding'],
         surveys: (userId) => [...queryKeys.users.detail(userId), 'surveys'],
@@ -94,6 +93,7 @@ export const queryKeys = {
         details: () => [...queryKeys.organizations.all(), 'detail'],
         detail: (id) => [...queryKeys.organizations.details(), id],
         byHandle: (handle) => [...queryKeys.organizations.all(), 'handle', handle],
+        publicProfileByHandle: (handle) => [...queryKeys.organizations.all(), 'public-profile', handle],
         userOrgs: () => [...queryKeys.organizations.all(), 'user'],
         members: (orgId) => [...queryKeys.organizations.detail(orgId), 'members'],
     },
@@ -284,6 +284,19 @@ export const queryKeys = {
         userById: (userId) => ['usages', 'user', userId],
         platform: () => ['usages', 'platform'],
     },
+    // Credits allocations
+    credits: {
+        organizationOverview: (organizationUid) => ['credits', 'allocations', 'organization', organizationUid],
+        organizationHistory: (organizationUid) => [
+            'credits',
+            'allocations',
+            'organization',
+            organizationUid,
+            'history',
+        ],
+        teamOverview: (teamUid) => ['credits', 'allocations', 'team', teamUid],
+        teamHistory: (teamUid) => ['credits', 'allocations', 'team', teamUid, 'history'],
+    },
     // Prices
     prices: {
         stripe: () => ['prices', 'stripe'],
@@ -368,10 +381,45 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     const toTeam = (org, organizationId) => {
         return asTeam(org, organizationId);
     };
+    /**
+     * Build a minimal {@link IUser} for an item's owner/creator from the
+     * raw fields returned by spacer (`creator_uid_s`/`creator_handle_s`
+     * and friends). Returns an empty-but-typed user when no creator info
+     * is available so the UI hydration hooks (e.g. `useUsersByUids`) can
+     * still fill in display data downstream.
+     */
+    const toItemOwner = (raw) => {
+        const uid = String(raw?.creator_uid_s ??
+            raw?.creator_uid ??
+            raw?.owner_uid_s ??
+            raw?.owner_uid ??
+            '').trim();
+        const handle = String(raw?.creator_handle_s ?? raw?.owner_handle_s ?? '').trim();
+        const firstName = String(raw?.creator_first_name_t ?? raw?.first_name_t ?? '').trim();
+        const lastName = String(raw?.creator_last_name_t ?? raw?.last_name_t ?? '').trim();
+        const email = String(raw?.creator_email_s ?? raw?.email_s ?? '').trim();
+        const displayName = firstName || lastName ? asDisplayName(firstName, lastName) : handle;
+        return {
+            id: uid,
+            handle,
+            email,
+            firstName,
+            lastName,
+            initials: namesAsInitials(firstName, lastName),
+            displayName,
+            roles: [],
+            iamProviders: [],
+            setRoles: () => { },
+            unsubscribedFromOutbounds: false,
+            onboarding: BOOTSTRAP_USER_ONBOARDING,
+            events: [],
+            settings: {},
+        };
+    };
     // Kept for potential future use
     // Kept for potential future use
     const toDataset = (raw_dataset) => {
-        const owner = newUserMock();
+        const owner = toItemOwner(raw_dataset);
         return {
             id: raw_dataset.uid,
             type: 'dataset',
@@ -394,12 +442,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 handle: raw_dataset.handle_s,
             },
             organization: {
-                handle: raw_dataset.handle_s,
+                id: raw_dataset.organization_uid_s,
+                handle: raw_dataset.organization_handle_s,
             },
         };
     };
     const toCell = (cl) => {
-        const owner = newUserMock();
+        const owner = toItemOwner(cl);
         return {
             id: cl.uid,
             type: 'cell',
@@ -418,12 +467,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 handle: cl.handle_s,
             },
             organization: {
-                handle: cl.handle_s,
+                id: cl.organization_uid_s,
+                handle: cl.organization_handle_s,
             },
         };
     };
     const toNotebook = (raw_notebook) => {
-        const owner = newUserMock();
+        const owner = toItemOwner(raw_notebook);
         return {
             id: raw_notebook.uid,
             type: 'notebook',
@@ -446,12 +496,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 handle: raw_notebook.handle_s,
             },
             organization: {
-                handle: raw_notebook.handle_s,
+                id: raw_notebook.organization_uid_s,
+                handle: raw_notebook.organization_handle_s,
             },
         };
     };
     const toDocument = (doc) => {
-        const owner = newUserMock();
+        const owner = toItemOwner(doc);
         return {
             id: doc.uid,
             type: 'document',
@@ -471,12 +522,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 handle: doc.handle_s,
             },
             organization: {
-                handle: doc.handle_s,
+                id: doc.organization_uid_s,
+                handle: doc.organization_handle_s,
             },
         };
     };
     const toLesson = (raw_lesson) => {
-        const owner = newUserMock();
+        const owner = toItemOwner(raw_lesson);
         return {
             id: raw_lesson.uid,
             type: 'lesson',
@@ -496,13 +548,14 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 handle: raw_lesson.handle_s,
             },
             organization: {
-                handle: raw_lesson.handle_s,
+                id: raw_lesson.organization_uid_s,
+                handle: raw_lesson.organization_handle_s,
             },
             datasets: [],
         };
     };
     const toExercise = (ex) => {
-        const owner = newUserMock();
+        const owner = toItemOwner(ex);
         return {
             id: ex.uid,
             type: 'exercise',
@@ -526,13 +579,14 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 handle: ex.handle_s,
             },
             organization: {
-                handle: ex.handle_s,
+                id: ex.organization_uid_s,
+                handle: ex.organization_handle_s,
             },
             datasets: [],
         };
     };
     const toAssignment = (raw_assignment) => {
-        const owner = newUserMock();
+        const owner = toItemOwner(raw_assignment);
         let studentItem = undefined;
         if (raw_assignment.student_items) {
             raw_assignment.student_items.forEach((student_item) => {
@@ -570,12 +624,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 handle: raw_assignment.handle_s,
             },
             organization: {
-                handle: raw_assignment.handle_s,
+                id: raw_assignment.organization_uid_s,
+                handle: raw_assignment.organization_handle_s,
             },
         };
     };
     const toEnvironment = (env) => {
-        const owner = newUserMock();
+        const owner = toItemOwner(env);
         return {
             id: env.uid,
             type: 'environment',
@@ -591,7 +646,8 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 handle: env.handle_s,
             },
             organization: {
-                handle: env.handle_s,
+                id: env.organization_uid_s,
+                handle: env.organization_handle_s,
             },
         };
     };
@@ -622,7 +678,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         }
     };
     const toCourse = (raw_course) => {
-        const owner = newUserMock();
+        const owner = toItemOwner(raw_course);
         let instructor = undefined;
         if (raw_course.members) {
             let raw_instructor = raw_course.members;
@@ -860,6 +916,46 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             enabled: !!handle,
         });
     };
+    /**
+     * Get enriched public user profile by handle.
+     */
+    const useUserPublicProfileByHandle = (handle) => {
+        return useQuery({
+            queryKey: queryKeys.users.publicProfileByHandle(handle),
+            queryFn: async () => {
+                const normalizedHandle = String(handle || '').trim();
+                if (!normalizedHandle) {
+                    return null;
+                }
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/users/public/${encodeURIComponent(normalizedHandle)}`,
+                    method: 'GET',
+                });
+                if (resp.success) {
+                    const profile = resp.profile || null;
+                    if (profile?.uid && profile?.handle) {
+                        const mappedUser = toUser({
+                            uid: profile.uid,
+                            id: profile.id,
+                            handle_s: profile.handle,
+                            first_name_t: profile.first_name,
+                            last_name_t: profile.last_name,
+                            avatar_url_s: profile.avatar_url,
+                            origin_s: profile.origin,
+                        });
+                        if (mappedUser) {
+                            queryClient.setQueryData(queryKeys.users.detail(mappedUser.id), mappedUser);
+                            queryClient.setQueryData(queryKeys.users.byHandle(mappedUser.handle), mappedUser);
+                        }
+                    }
+                    return profile;
+                }
+                return null;
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!handle,
+        });
+    };
     /**
      * Search users by naming pattern
      */
@@ -890,6 +986,44 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             enabled: namingPattern !== undefined && namingPattern !== null,
         });
     };
+    /**
+     * Get multiple users by UIDs in one request.
+     */
+    const useUsersByUids = (userIds) => {
+        const normalizedUserIds = Array.from(new Set((userIds || [])
+            .map(userId => String(userId || '').trim())
+            .filter(Boolean)));
+        const idsKey = normalizedUserIds.join(',');
+        return useQuery({
+            queryKey: queryKeys.users.bulk(idsKey),
+            queryFn: async () => {
+                if (normalizedUserIds.length === 0) {
+                    return [];
+                }
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/users/bulk`,
+                    method: 'POST',
+                    body: { userIds: normalizedUserIds },
+                });
+                if (resp.success && resp.users) {
+                    const users = resp.users
+                        .map((u) => {
+                        const user = toUser(u);
+                        if (user) {
+                            queryClient.setQueryData(queryKeys.users.detail(user.id), user);
+                            queryClient.setQueryData(queryKeys.users.byHandle(user.handle), user);
+                        }
+                        return user;
+                    })
+                        .filter(Boolean);
+                    return users;
+                }
+                return [];
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: normalizedUserIds.length > 0,
+        });
+    };
     /**
      * Update user onboarding
      */
@@ -979,6 +1113,30 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             enabled: !!handle,
         });
     };
+    /**
+     * Get enriched public organization profile by handle.
+     */
+    const useOrganizationPublicProfileByHandle = (handle) => {
+        return useQuery({
+            queryKey: queryKeys.organizations.publicProfileByHandle(handle),
+            queryFn: async () => {
+                const normalizedHandle = String(handle || '').trim();
+                if (!normalizedHandle) {
+                    return null;
+                }
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/organizations/public/${encodeURIComponent(normalizedHandle)}`,
+                    method: 'GET',
+                });
+                if (resp.success) {
+                    return resp.organization || null;
+                }
+                return null;
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!handle,
+        });
+    };
     /**
      * Get user's organizations
      */
@@ -1192,6 +1350,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                     queryClient.setQueryData(queryKeys.spaces.byHandle(space.handle), space);
                     return space;
                 }
+                if (resp?.code === 'FORBIDDEN') {
+                    throw new Error(resp.message || 'Not authorized to access this space');
+                }
                 throw new Error(resp.message || 'Failed to fetch space');
             },
             ...DEFAULT_QUERY_OPTIONS,
@@ -1212,6 +1373,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 if (resp.success && resp.space) {
                     return toSpace(resp.space);
                 }
+                if (resp?.code === 'FORBIDDEN') {
+                    throw new Error(resp.message || 'Not authorized to access this space');
+                }
                 throw new Error(resp.message || 'Failed to fetch space');
             },
             ...DEFAULT_QUERY_OPTIONS,
@@ -1246,12 +1410,24 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Get user spaces
      */
-    const useUserSpaces = () => {
+    const useUserSpaces = (scope) => {
         return useQuery({
-            queryKey: queryKeys.spaces.userSpaces(),
+            queryKey: [
+                ...queryKeys.spaces.userSpaces(),
+                scope?.selectedPrincipalUid || '',
+                scope?.selectedPrincipalKind || '',
+            ],
             queryFn: async () => {
+                const params = new URLSearchParams();
+                if (scope?.selectedPrincipalUid) {
+                    params.set('selected_principal_uid', scope.selectedPrincipalUid);
+                }
+                if (scope?.selectedPrincipalKind) {
+                    params.set('selected_principal_kind', scope.selectedPrincipalKind);
+                }
+                const query = params.toString();
                 const resp = await requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/spaces/users/me`,
+                    url: `${configuration.spacerRunUrl}/api/spacer/v1/spaces/users/me${query ? `?${query}` : ''}`,
                     method: 'GET',
                 });
                 if (resp.success && resp.spaces) {
@@ -1274,11 +1450,11 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
      */
     const useCreateSpace = () => {
         return useMutation({
-            mutationFn: async ({ space, organization, }) => {
+            mutationFn: async ({ space, organization, team, }) => {
                 const seedSpaceId = space.variant === 'course'
                     ? space.seedSpace?.id
                     : undefined;
-                return requestDatalayer({
+                const resp = await requestDatalayer({
                     url: `${configuration.spacerRunUrl}/api/spacer/v1/spaces`,
                     method: 'POST',
                     body: {
@@ -1288,9 +1464,20 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                         public: space.public,
                         spaceHandle: space.handle,
                         organizationId: organization?.id,
+                        organizationHandle: organization?.handle,
+                        teamId: team?.id,
+                        teamHandle: team?.handle,
                         seedSpaceId,
                     },
                 });
+                if (resp?.success === false ||
+                    resp?.sucess === false) {
+                    throw new Error(resp?.message || 'Failed to create space');
+                }
+                if (!resp?.space) {
+                    throw new Error(resp?.message || 'Failed to create space');
+                }
+                return resp;
             },
             onSuccess: (resp, _variables) => {
                 if (resp.space) {
@@ -1314,7 +1501,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             mutationFn: async (space) => {
                 const { id, name, description, ...extraFields } = space;
                 return requestDatalayer({
-                    url: `${configuration.spacerRunUrl}/api/spacer/v1/spaces/${id}/users/${user?.id}`,
+                    // Use the canonical space update route. This keeps project runtime
+                    // assignment cleanup resilient when stale runtime links must be cleared.
+                    url: `${configuration.spacerRunUrl}/api/spacer/v1/spaces/${id}`,
                     method: 'PUT',
                     body: {
                         name,
@@ -1372,6 +1561,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 if (resp.success && resp.notebook) {
                     return toNotebook(resp.notebook);
                 }
+                if (resp?.code === 'FORBIDDEN') {
+                    throw new Error(resp.message || 'Not authorized to access this notebook');
+                }
                 throw new Error(resp.message || 'Failed to fetch notebook');
             },
             ...DEFAULT_QUERY_OPTIONS,
@@ -1529,6 +1721,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 if (resp.success && resp.document) {
                     return toDocument(resp.document);
                 }
+                if (resp?.code === 'FORBIDDEN') {
+                    throw new Error(resp.message || 'Not authorized to access this document');
+                }
                 throw new Error(resp.message || 'Failed to fetch document');
             },
             ...DEFAULT_QUERY_OPTIONS,
@@ -1695,12 +1890,24 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Get all pages
      */
-    const usePages = () => {
+    const usePages = (scope) => {
         return useQuery({
-            queryKey: queryKeys.pages.all(),
+            queryKey: [
+                ...queryKeys.pages.all(),
+                scope?.selectedPrincipalUid || '',
+                scope?.selectedPrincipalKind || '',
+            ],
             queryFn: async () => {
+                const params = new URLSearchParams();
+                if (scope?.selectedPrincipalUid) {
+                    params.set('selected_principal_uid', scope.selectedPrincipalUid);
+                }
+                if (scope?.selectedPrincipalKind) {
+                    params.set('selected_principal_kind', scope.selectedPrincipalKind);
+                }
+                const query = params.toString();
                 const resp = await requestDatalayer({
-                    url: `${configuration.libraryRunUrl}/api/library/v1/pages`,
+                    url: `${configuration.libraryRunUrl}/api/library/v1/pages${query ? `?${query}` : ''}`,
                     method: 'GET',
                 });
                 if (resp.success && resp.pages) {
@@ -1797,18 +2004,17 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         });
     };
-    // ============================================================================
-    // Datasource, Secret, Token Hooks
-    // ============================================================================
     /**
      * Get all datasources
      */
-    const useDatasources = () => {
+    const useDatasources = (options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useQuery({
-            queryKey: queryKeys.datasources.all(),
+            queryKey: [...queryKeys.datasources.all(), principalUid || 'self', principalKind || ''],
             queryFn: async () => {
                 const resp = await requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/datasources`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/datasources`, principalUid, principalKind),
                     method: 'GET',
                 });
                 if (resp.success && resp.datasources) {
@@ -1831,11 +2037,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Create datasource
      */
-    const useCreateDatasource = () => {
+    const useCreateDatasource = (options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useMutation({
             mutationFn: async (datasource) => {
                 return requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/datasources`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/datasources`, principalUid, principalKind),
                     method: 'POST',
                     body: { ...datasource },
                 });
@@ -1860,12 +2068,14 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     // but this prevented useSecret from fetching fresh data (e.g., the value field).
     // Consider re-adding cache pre-population if the list endpoint returns full secret data,
     // or use a different query key pattern for partial vs full secret data.
-    const useSecrets = () => {
+    const useSecrets = (options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useQuery({
-            queryKey: queryKeys.secrets.all(),
+            queryKey: [...queryKeys.secrets.all(), principalUid || 'self', principalKind || ''],
             queryFn: async () => {
                 const resp = await requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/secrets`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/secrets`, principalUid, principalKind),
                     method: 'GET',
                 });
                 if (resp.success && resp.secrets) {
@@ -1883,11 +2093,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Create secret
      */
-    const useCreateSecret = () => {
+    const useCreateSecret = (options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useMutation({
             mutationFn: async (secret) => {
                 return requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/secrets`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/secrets`, principalUid, principalKind),
                     method: 'POST',
                     body: { ...secret },
                 });
@@ -1906,11 +2118,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Delete secret
      */
-    const useDeleteSecret = () => {
+    const useDeleteSecret = (options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useMutation({
             mutationFn: async (secretId) => {
                 return requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/secrets/${secretId}`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/secrets/${secretId}`, principalUid, principalKind),
                     method: 'DELETE',
                 });
             },
@@ -2167,12 +2381,14 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Get single datasource by ID
      */
-    const useDatasource = (datasourceId) => {
+    const useDatasource = (datasourceId, options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useQuery({
-            queryKey: queryKeys.datasources.detail(datasourceId),
+            queryKey: [...queryKeys.datasources.detail(datasourceId), principalUid || 'self', principalKind || ''],
             queryFn: async () => {
                 const resp = await requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/datasources/${datasourceId}`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/datasources/${datasourceId}`, principalUid, principalKind),
                     method: 'GET',
                 });
                 if (resp.success && resp.datasource) {
@@ -2187,11 +2403,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Update datasource
      */
-    const useUpdateDatasource = () => {
+    const useUpdateDatasource = (options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useMutation({
             mutationFn: async (datasource) => {
                 return requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/datasources/${datasource.id}`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/datasources/${datasource.id}`, principalUid, principalKind),
                     method: 'PUT',
                     body: { ...datasource },
                 });
@@ -2213,11 +2431,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
      * Get single secret by ID
      */
     const useSecret = (secretId, options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useQuery({
-            queryKey: queryKeys.secrets.detail(secretId),
+            queryKey: [...queryKeys.secrets.detail(secretId), principalUid || 'self', principalKind || ''],
             queryFn: async () => {
                 const resp = await requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/secrets/${secretId}`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/secrets/${secretId}`, principalUid, principalKind),
                     method: 'GET',
                 });
                 if (resp.success && resp.secret) {
@@ -2235,11 +2455,13 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Update secret
      */
-    const useUpdateSecret = () => {
+    const useUpdateSecret = (options) => {
+        const principalUid = options?.principalUid;
+        const principalKind = options?.principalKind;
         return useMutation({
             mutationFn: async (secret) => {
                 return requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/secrets/${secret.id}`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/secrets/${secret.id}`, principalUid, principalKind),
                     method: 'PUT',
                     body: { ...secret },
                 });
@@ -2383,6 +2605,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                     }
                     return space;
                 }
+                if (resp?.code === 'FORBIDDEN') {
+                    throw new Error(resp.message || 'Not authorized to access this space');
+                }
                 return null;
             },
             ...DEFAULT_QUERY_OPTIONS,
@@ -2441,6 +2666,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                     });
                     return targetSpace;
                 }
+                if (resp?.code === 'FORBIDDEN') {
+                    throw new Error(resp.message || 'Not authorized to access this space');
+                }
                 return null;
             },
             ...DEFAULT_QUERY_OPTIONS,
@@ -3384,6 +3612,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
                 if (resp.success && resp.item) {
                     return toCell(resp.item);
                 }
+                if (resp?.code === 'FORBIDDEN') {
+                    throw new Error(resp.message || 'Not authorized to access this cell');
+                }
                 return undefined;
             },
             enabled: !!cellId,
@@ -4307,43 +4538,265 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             },
         });
     };
-    // ============================================================================
-    // Checkout & Credits
-    // ============================================================================
+    const withAccountUidQuery = (url, accountUid, accountKind) => {
+        if (!accountUid) {
+            return url;
+        }
+        const separator = url.includes('?') ? '&' : '?';
+        const parts = [`billable_account_uid=${encodeURIComponent(accountUid)}`];
+        if (accountKind) {
+            parts.push(`billable_account_kind=${encodeURIComponent(accountKind)}`);
+        }
+        return `${url}${separator}${parts.join('&')}`;
+    };
+    const useTopUpPrices = (options) => {
+        return useQuery({
+            queryKey: ['stripe', 'plans', 'prices'],
+            queryFn: async () => {
+                const normalizeTopUpPrices = (raw) => {
+                    const prices = raw.map((item) => ({
+                        ...item,
+                        default: item?.default === true,
+                    }));
+                    const explicitDefaultIndex = prices.findIndex(item => item.default === true);
+                    if (explicitDefaultIndex >= 0) {
+                        return prices.map((item, index) => ({
+                            ...item,
+                            default: index === explicitDefaultIndex,
+                        }));
+                    }
+                    if (prices.length === 0) {
+                        return prices;
+                    }
+                    let fallbackDefaultIndex = 0;
+                    let fallbackDefaultAmount = Number(prices[0]?.amount || 0);
+                    for (let index = 1; index < prices.length; index += 1) {
+                        const amount = Number(prices[index]?.amount || 0);
+                        if (amount > fallbackDefaultAmount) {
+                            fallbackDefaultAmount = amount;
+                            fallbackDefaultIndex = index;
+                        }
+                    }
+                    return prices.map((item, index) => ({
+                        ...item,
+                        default: index === fallbackDefaultIndex,
+                    }));
+                };
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/stripe/v1/plans/prices`,
+                    method: 'GET',
+                });
+                if (resp?.success === false) {
+                    throw new Error(resp?.message || 'Unable to fetch available top-up products.');
+                }
+                if (Array.isArray(resp?.prices)) {
+                    return normalizeTopUpPrices(resp.prices);
+                }
+                if (Array.isArray(resp)) {
+                    return normalizeTopUpPrices(resp);
+                }
+                if (resp && Object.keys(resp).length === 0) {
+                    return [];
+                }
+                throw new Error('Unable to fetch available top-up products.');
+            },
+            ...options,
+        });
+    };
     /**
-     * Get Stripe pricing information
+     * Create Stripe top-up payment intent client secret
      */
-    const useStripePrices = (options) => {
+    const useCreateTopUpPaymentIntent = (scope) => {
+        return useMutation({
+            mutationFn: async ({ product, }) => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/stripe/v1/topup/payment-intent`,
+                    method: 'POST',
+                    body: {
+                        price_id: product?.id,
+                        ...(scope?.accountUid ? { account_uid: scope.accountUid } : {}),
+                    },
+                });
+                return resp.client_secret;
+            },
+        });
+    };
+    /**
+     * Get available monthly subscription plans.
+     */
+    const useSubscriptionPlans = (scope, options) => {
         return useQuery({
-            queryKey: ['stripe', 'prices'],
+            queryKey: ['subscription', 'plans', scope?.accountUid ?? 'self'],
             queryFn: async () => {
                 const resp = await requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/stripe/v1/prices`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/plans/catalog`, scope?.accountUid),
                     method: 'GET',
                 });
-                return resp.prices || [];
+                return resp.plans || [];
             },
             ...options,
         });
     };
     /**
-     * Create Stripe checkout session
+     * Create Stripe monthly subscription payment intent client secret.
      */
-    const useCreateCheckoutSession = () => {
+    const useCreateSubscriptionPaymentIntent = (scope) => {
         return useMutation({
-            mutationFn: async ({ product, location, }) => {
+            mutationFn: async ({ plan, }) => {
                 const resp = await requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/stripe/v1/checkout/session`,
+                    url: `${configuration.iamRunUrl}/api/iam/stripe/v1/subscription/payment-intent`,
                     method: 'POST',
                     body: {
-                        price_id: product?.id,
-                        return_url: `${location.protocol}//${location.host}${location.pathname.split('/').slice(0, -1).join('/')}`,
+                        price_id: plan?.id,
+                        ...(scope?.accountUid ? { account_uid: scope.accountUid } : {}),
                     },
                 });
                 return resp.client_secret;
             },
         });
     };
+    /**
+     * Create Stripe SetupIntent client secret to update card before resuming.
+     */
+    const useCreateResumeSetupIntent = (scope) => {
+        return useMutation({
+            mutationFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/stripe/v1/subscription/resume/setup-intent`,
+                    method: 'POST',
+                    body: scope?.accountUid ? { account_uid: scope.accountUid } : {},
+                });
+                return resp.client_secret;
+            },
+        });
+    };
+    /**
+     * Get authenticated user subscription details.
+     */
+    const useSubscriptionStatus = (scope, options) => {
+        return useQuery({
+            queryKey: ['subscription', 'status', scope?.accountUid ?? 'self'],
+            queryFn: async () => {
+                return requestDatalayer({
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/plans`, scope?.accountUid),
+                    method: 'GET',
+                });
+            },
+            ...options,
+        });
+    };
+    /**
+     * Get accounts (personal + organizations) eligible for subscription-backed workloads.
+     */
+    const useEligibleSubscriptionAccounts = (options) => {
+        return useQuery({
+            queryKey: ['subscription', 'eligible-accounts'],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/plans/eligible-accounts`,
+                    method: 'GET',
+                });
+                return resp.accounts || [];
+            },
+            ...options,
+        });
+    };
+    /**
+     * Get subscription details + eligibility for a batch of account UIDs.
+     */
+    const useSubscriptionAccountsDetails = (accountUids, options) => {
+        const normalizedAccountUids = Array.from(new Set((accountUids || [])
+            .map(uid => String(uid || '').trim())
+            .filter(Boolean)));
+        return useQuery({
+            queryKey: ['subscription', 'accounts-details', normalizedAccountUids],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/plans/accounts/details`,
+                    method: 'POST',
+                    body: {
+                        account_uids: normalizedAccountUids,
+                    },
+                });
+                return resp.accounts || [];
+            },
+            enabled: normalizedAccountUids.length > 0,
+            ...options,
+        });
+    };
+    /**
+     * Request cancellation portal for the current subscription.
+     */
+    const useCancelSubscription = (scope) => {
+        const queryClient = useQueryClient();
+        return useMutation({
+            mutationFn: async () => {
+                return requestDatalayer({
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/plans/cancel`, scope?.accountUid),
+                    method: 'POST',
+                });
+            },
+            onSuccess: () => {
+                queryClient.invalidateQueries({
+                    queryKey: ['subscription', 'status', scope?.accountUid ?? 'self'],
+                });
+            },
+        });
+    };
+    /**
+     * Resume a subscription already scheduled for cancellation.
+     */
+    const useResumeSubscription = (scope) => {
+        const queryClient = useQueryClient();
+        return useMutation({
+            mutationFn: async () => {
+                return requestDatalayer({
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/plans/resume`, scope?.accountUid),
+                    method: 'POST',
+                });
+            },
+            onSuccess: () => {
+                queryClient.invalidateQueries({
+                    queryKey: ['subscription', 'status', scope?.accountUid ?? 'self'],
+                });
+            },
+        });
+    };
+    /**
+     * Get subscription details for an arbitrary user (platform_admin only).
+     */
+    const useUserSubscription = (userId, options) => {
+        return useQuery({
+            queryKey: ['subscription', 'admin', userId],
+            queryFn: async () => {
+                return requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/plans/admin/${userId}`,
+                    method: 'GET',
+                });
+            },
+            enabled: Boolean(userId),
+            ...options,
+        });
+    };
+    /**
+     * Force-reset a user's subscription (platform_admin only).
+     */
+    const useResetUserSubscription = () => {
+        const queryClient = useQueryClient();
+        return useMutation({
+            mutationFn: async (userId) => {
+                return requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/plans/admin/${userId}/reset`,
+                    method: 'POST',
+                });
+            },
+            onSuccess: (_data, userId) => {
+                queryClient.invalidateQueries({
+                    queryKey: ['subscription', 'admin', userId],
+                });
+            },
+        });
+    };
     /**
      * Burn user credits (deduct from balance)
      */
@@ -4733,6 +5186,174 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     // ============================================================================
     // Credits Quota & Usage
     // ============================================================================
+    /**
+     * Get organization/team balances for allocation workflows
+     */
+    const useOrganizationAllocationOverview = (organizationUid) => {
+        return useQuery({
+            queryKey: queryKeys.credits.organizationOverview(organizationUid),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/usage/credits/allocations/organizations/${organizationUid}/overview`,
+                    method: 'GET',
+                });
+                return resp.overview ?? { organization: null, teams: [] };
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!organizationUid,
+        });
+    };
+    /**
+     * Get team/member balances for allocation workflows
+     */
+    const useTeamAllocationOverview = (teamUid) => {
+        return useQuery({
+            queryKey: queryKeys.credits.teamOverview(teamUid),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/usage/credits/allocations/teams/${teamUid}/overview`,
+                    method: 'GET',
+                });
+                return resp.overview ?? { team: null, members: [] };
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!teamUid,
+        });
+    };
+    /**
+     * Get organization allocation history
+     */
+    const useOrganizationAllocationHistory = (organizationUid) => {
+        return useQuery({
+            queryKey: queryKeys.credits.organizationHistory(organizationUid),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/usage/credits/allocations/organizations/${organizationUid}/history`,
+                    method: 'GET',
+                });
+                return (resp.history ?? { organization_uid: organizationUid, events: [] });
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!organizationUid,
+        });
+    };
+    /**
+     * Get team allocation history
+     */
+    const useTeamAllocationHistory = (teamUid) => {
+        return useQuery({
+            queryKey: queryKeys.credits.teamHistory(teamUid),
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/usage/credits/allocations/teams/${teamUid}/history`,
+                    method: 'GET',
+                });
+                return resp.history ?? { team_uid: teamUid, events: [] };
+            },
+            ...DEFAULT_QUERY_OPTIONS,
+            enabled: !!teamUid,
+        });
+    };
+    /**
+     * Allocate credits from organization to team
+     */
+    const useAllocateOrganizationCreditsToTeam = () => {
+        return useMutation({
+            mutationFn: async ({ organizationUid, teamUid, amount, }) => {
+                return requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/usage/credits/allocations/organizations/${organizationUid}/teams/${teamUid}`,
+                    method: 'POST',
+                    body: { amount },
+                });
+            },
+            onSuccess: (_, { organizationUid, teamUid }) => {
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.organizationOverview(organizationUid),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.organizationHistory(organizationUid),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.teamOverview(teamUid),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.teamHistory(teamUid),
+                });
+            },
+        });
+    };
+    /**
+     * Allocate credits from team to member
+     */
+    const useAllocateTeamCreditsToMember = () => {
+        return useMutation({
+            mutationFn: async ({ teamUid, memberUid, amount, }) => {
+                return requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/usage/credits/allocations/teams/${teamUid}/members/${memberUid}`,
+                    method: 'POST',
+                    body: { amount },
+                });
+            },
+            onSuccess: (_, { teamUid }) => {
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.teamOverview(teamUid),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.teamHistory(teamUid),
+                });
+            },
+        });
+    };
+    /**
+     * Revoke credits from team back to organization
+     */
+    const useRevokeOrganizationCreditsFromTeam = () => {
+        return useMutation({
+            mutationFn: async ({ organizationUid, teamUid, amount, }) => {
+                return requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/usage/credits/allocations/organizations/${organizationUid}/teams/${teamUid}/revoke`,
+                    method: 'POST',
+                    body: { amount },
+                });
+            },
+            onSuccess: (_, { organizationUid, teamUid }) => {
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.organizationOverview(organizationUid),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.organizationHistory(organizationUid),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.teamOverview(teamUid),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.teamHistory(teamUid),
+                });
+            },
+        });
+    };
+    /**
+     * Revoke credits from member back to team
+     */
+    const useRevokeTeamCreditsFromMember = () => {
+        return useMutation({
+            mutationFn: async ({ teamUid, memberUid, amount, }) => {
+                return requestDatalayer({
+                    url: `${configuration.iamRunUrl}/api/iam/v1/usage/credits/allocations/teams/${teamUid}/members/${memberUid}/revoke`,
+                    method: 'POST',
+                    body: { amount },
+                });
+            },
+            onSuccess: (_, { teamUid }) => {
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.teamOverview(teamUid),
+                });
+                queryClient.invalidateQueries({
+                    queryKey: queryKeys.credits.teamHistory(teamUid),
+                });
+            },
+        });
+    };
     /**
      * Update user credits quota
      */
@@ -4760,33 +5381,77 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
     /**
      * Get current user's usage data
      */
-    const useUsages = (options) => {
+    const useUsages = (scopeOrOptions, options) => {
+        const hasScope = !!scopeOrOptions &&
+            typeof scopeOrOptions === 'object' &&
+            'accountUid' in scopeOrOptions;
+        const scope = (hasScope ? scopeOrOptions : undefined);
+        const queryOptions = (hasScope ? options : scopeOrOptions);
         return useQuery({
-            queryKey: ['usage', 'me'],
+            queryKey: ['usage', 'me', scope?.accountUid ?? 'self'],
             queryFn: async () => {
+                const parseUsageDate = (value) => {
+                    if (!value) {
+                        return undefined;
+                    }
+                    const date = value instanceof Date ? value : new Date(value);
+                    return Number.isNaN(date.getTime()) ? undefined : date;
+                };
+                const asUsage = (u) => {
+                    const metadata = new Map(Object.entries(u.metadata || {}));
+                    const usagePeriodKey = u.usage_period_key;
+                    const usagePeriodLabel = u.usage_period_label;
+                    const usagePeriodStart = u.usage_period_start;
+                    const usagePeriodEnd = u.usage_period_end;
+                    if (usagePeriodKey) {
+                        metadata.set('usage_period_key', String(usagePeriodKey));
+                    }
+                    if (usagePeriodLabel) {
+                        metadata.set('usage_period_label', String(usagePeriodLabel));
+                    }
+                    if (usagePeriodStart) {
+                        metadata.set('usage_period_start', String(usagePeriodStart));
+                    }
+                    if (usagePeriodEnd) {
+                        metadata.set('usage_period_end', String(usagePeriodEnd));
+                    }
+                    const endDate = parseUsageDate(u.end_date);
+                    const updatedAt = parseUsageDate(u.updated_at) || endDate || new Date();
+                    const rawStartDate = parseUsageDate(u.start_date);
+                    let startDate = rawStartDate || endDate || updatedAt;
+                    if (endDate && startDate && startDate.getTime() > endDate.getTime()) {
+                        startDate =
+                            updatedAt.getTime() <= endDate.getTime() ? updatedAt : endDate;
+                    }
+                    return {
+                        id: u.resource_uid,
+                        accountId: u.account_uid,
+                        type: u.resource_type,
+                        burningRate: u.burning_rate,
+                        credits: u.credits,
+                        creditsLimit: u.credits_limit,
+                        startDate,
+                        updatedAt,
+                        endDate,
+                        givenName: u.given_name || u.resource_given_name || '',
+                        resourceState: u.resource_state,
+                        resources: u.pod_resources,
+                        usagePeriodKey,
+                        usagePeriodLabel,
+                        usagePeriodStart: parseUsageDate(usagePeriodStart),
+                        usagePeriodEnd: parseUsageDate(usagePeriodEnd),
+                        metadata,
+                    };
+                };
                 const resp = await requestDatalayer({
-                    url: `${configuration.iamRunUrl}/api/iam/v1/usage/user`,
+                    url: withAccountUidQuery(`${configuration.iamRunUrl}/api/iam/v1/usage/user`, scope?.accountUid),
                     method: 'GET',
                 });
                 // Transform snake_case API response to camelCase IUsage interface
-                const usages = (resp.usages || []).map((u) => ({
-                    id: u.resource_uid,
-                    accountId: u.account_uid,
-                    type: u.resource_type,
-                    burningRate: u.burning_rate,
-                    credits: u.credits,
-                    creditsLimit: u.credits_limit,
-                    startDate: u.start_date ? new Date(u.start_date) : new Date(),
-                    updatedAt: u.updated_at ? new Date(u.updated_at) : new Date(),
-                    endDate: u.end_date ? new Date(u.end_date) : undefined,
-                    givenName: u.given_name || u.resource_given_name || '',
-                    resourceState: u.resource_state,
-                    resources: u.pod_resources,
-                    metadata: new Map(Object.entries(u.metadata || {})),
-                }));
+                const usages = (resp.usages || []).map(asUsage);
                 return usages;
             },
-            ...options,
+            ...queryOptions,
         });
     };
     /**
@@ -4796,26 +5461,61 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         return useQuery({
             queryKey: ['usage', 'user', userId],
             queryFn: async () => {
+                const parseUsageDate = (value) => {
+                    if (!value) {
+                        return undefined;
+                    }
+                    const date = value instanceof Date ? value : new Date(value);
+                    return Number.isNaN(date.getTime()) ? undefined : date;
+                };
+                const asUsage = (u) => {
+                    const metadata = new Map(Object.entries(u.metadata || {}));
+                    if (u.usage_period_key) {
+                        metadata.set('usage_period_key', String(u.usage_period_key));
+                    }
+                    if (u.usage_period_label) {
+                        metadata.set('usage_period_label', String(u.usage_period_label));
+                    }
+                    if (u.usage_period_start) {
+                        metadata.set('usage_period_start', String(u.usage_period_start));
+                    }
+                    if (u.usage_period_end) {
+                        metadata.set('usage_period_end', String(u.usage_period_end));
+                    }
+                    const endDate = parseUsageDate(u.end_date);
+                    const updatedAt = parseUsageDate(u.updated_at) || endDate || new Date();
+                    const rawStartDate = parseUsageDate(u.start_date);
+                    let startDate = rawStartDate || endDate || updatedAt;
+                    if (endDate && startDate && startDate.getTime() > endDate.getTime()) {
+                        startDate =
+                            updatedAt.getTime() <= endDate.getTime() ? updatedAt : endDate;
+                    }
+                    return {
+                        id: u.resource_uid,
+                        accountId: u.account_uid,
+                        type: u.resource_type,
+                        burningRate: u.burning_rate,
+                        credits: u.credits,
+                        creditsLimit: u.credits_limit,
+                        startDate,
+                        updatedAt,
+                        endDate,
+                        givenName: u.given_name || u.resource_given_name || '',
+                        resourceState: u.resource_state,
+                        resources: u.pod_resources,
+                        usagePeriodKey: u.usage_period_key,
+                        usagePeriodLabel: u.usage_period_label,
+                        usagePeriodStart: parseUsageDate(u.usage_period_start),
+                        usagePeriodEnd: parseUsageDate(u.usage_period_end),
+                        metadata,
+                    };
+                };
                 const resp = await requestDatalayer({
                     url: `${configuration.iamRunUrl}/api/iam/v1/usage/users/${userId}`,
                     method: 'GET',
                 });
                 // Transform snake_case API response to camelCase IUsage interface
-                const usages = (resp.usages || []).map((u) => ({
-                    id: u.resource_uid,
-                    accountId: u.account_uid,
-                    type: u.resource_type,
-                    burningRate: u.burning_rate,
-                    credits: u.credits,
-                    creditsLimit: u.credits_limit,
-                    startDate: u.start_date ? new Date(u.start_date) : new Date(),
-                    updatedAt: u.updated_at ? new Date(u.updated_at) : new Date(),
-                    endDate: u.end_date ? new Date(u.end_date) : undefined,
-                    givenName: u.given_name || u.resource_given_name || '',
-                    resourceState: u.resource_state,
-                    resources: u.pod_resources,
-                    metadata: new Map(Object.entries(u.metadata || {})),
-                }));
+                const usages = (resp.usages || []).map(asUsage);
                 return usages;
             },
             enabled: !!userId,
@@ -4829,26 +5529,61 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         return useQuery({
             queryKey: ['usage', 'platform'],
             queryFn: async () => {
+                const parseUsageDate = (value) => {
+                    if (!value) {
+                        return undefined;
+                    }
+                    const date = value instanceof Date ? value : new Date(value);
+                    return Number.isNaN(date.getTime()) ? undefined : date;
+                };
+                const asUsage = (u) => {
+                    const metadata = new Map(Object.entries(u.metadata || {}));
+                    if (u.usage_period_key) {
+                        metadata.set('usage_period_key', String(u.usage_period_key));
+                    }
+                    if (u.usage_period_label) {
+                        metadata.set('usage_period_label', String(u.usage_period_label));
+                    }
+                    if (u.usage_period_start) {
+                        metadata.set('usage_period_start', String(u.usage_period_start));
+                    }
+                    if (u.usage_period_end) {
+                        metadata.set('usage_period_end', String(u.usage_period_end));
+                    }
+                    const endDate = parseUsageDate(u.end_date);
+                    const updatedAt = parseUsageDate(u.updated_at) || endDate || new Date();
+                    const rawStartDate = parseUsageDate(u.start_date);
+                    let startDate = rawStartDate || endDate || updatedAt;
+                    if (endDate && startDate && startDate.getTime() > endDate.getTime()) {
+                        startDate =
+                            updatedAt.getTime() <= endDate.getTime() ? updatedAt : endDate;
+                    }
+                    return {
+                        id: u.resource_uid,
+                        accountId: u.account_uid,
+                        type: u.resource_type,
+                        burningRate: u.burning_rate,
+                        credits: u.credits,
+                        creditsLimit: u.credits_limit,
+                        startDate,
+                        updatedAt,
+                        endDate,
+                        givenName: u.given_name || u.resource_given_name || '',
+                        resourceState: u.resource_state,
+                        resources: u.pod_resources,
+                        usagePeriodKey: u.usage_period_key,
+                        usagePeriodLabel: u.usage_period_label,
+                        usagePeriodStart: parseUsageDate(u.usage_period_start),
+                        usagePeriodEnd: parseUsageDate(u.usage_period_end),
+                        metadata,
+                    };
+                };
                 const resp = await requestDatalayer({
                     url: `${configuration.iamRunUrl}/api/iam/v1/usage/platform`,
                     method: 'GET',
                 });
                 // Transform snake_case API response to camelCase IUsage interface
-                const usages = (resp.usages || []).map((u) => ({
-                    id: u.resource_uid,
-                    accountId: u.account_uid,
-                    type: u.resource_type,
-                    burningRate: u.burning_rate,
-                    credits: u.credits,
-                    creditsLimit: u.credits_limit,
-                    startDate: u.start_date ? new Date(u.start_date) : new Date(),
-                    updatedAt: u.updated_at ? new Date(u.updated_at) : new Date(),
-                    endDate: u.end_date ? new Date(u.end_date) : undefined,
-                    givenName: u.given_name || u.resource_given_name || '',
-                    resourceState: u.resource_state,
-                    resources: u.pod_resources,
-                    metadata: new Map(Object.entries(u.metadata || {})),
-                }));
+                const usages = (resp.usages || []).map(asUsage);
                 return usages;
             },
             ...options,
@@ -5169,6 +5904,22 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
             ...options,
         });
     };
+    /**
+     * Get growth contacts KPIs.
+     */
+    const useGrowthContactsKPI = (options) => {
+        return useQuery({
+            queryKey: ['growth', 'contacts-kpi'],
+            queryFn: async () => {
+                const resp = await requestDatalayer({
+                    url: `${configuration.growthRunUrl}/api/growth/v1/kpis/contacts`,
+                    method: 'GET',
+                });
+                return resp;
+            },
+            ...options,
+        });
+    };
     // ============================================================================
     // Refresh Operations & Additional Methods
     // ============================================================================
@@ -6088,7 +6839,9 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         // Users
         useUser,
         useUserByHandle,
+        useUserPublicProfileByHandle,
         useSearchUsers,
+        useUsersByUids,
         useUpdateUserOnboarding,
         useUpdateUserSettings,
         useRefreshUser,
@@ -6096,6 +6849,14 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useUpdateUserCredits,
         useAssignRoleToUser,
         useUnassignRoleFromUser,
+        useOrganizationAllocationOverview,
+        useOrganizationAllocationHistory,
+        useTeamAllocationOverview,
+        useTeamAllocationHistory,
+        useAllocateOrganizationCreditsToTeam,
+        useAllocateTeamCreditsToMember,
+        useRevokeOrganizationCreditsFromTeam,
+        useRevokeTeamCreditsFromMember,
         useUpdateUserCreditsQuota,
         useUsages,
         useUsagesForUser,
@@ -6103,6 +6864,7 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         // Organizations
         useOrganization,
         useOrganizationByHandle,
+        useOrganizationPublicProfileByHandle,
         useUserOrganizations,
         useCreateOrganization,
         useUpdateOrganization,
@@ -6312,14 +7074,25 @@ export const useCache = ({ loginRoute = '/login' } = {}) => {
         useDisableUserMFA,
         useValidateUserMFACode,
         // Checkout & Credits
-        useCreateCheckoutSession,
+        useCreateTopUpPaymentIntent,
+        useCreateSubscriptionPaymentIntent,
+        useCreateResumeSetupIntent,
+        useSubscriptionStatus,
+        useSubscriptionPlans,
+        useEligibleSubscriptionAccounts,
+        useSubscriptionAccountsDetails,
+        useCancelSubscription,
+        useResumeSubscription,
+        useUserSubscription,
+        useResetUserSubscription,
         useBurnCredit,
-        useStripePrices,
+        useTopUpPrices,
         // Support & Growth
         useRequestPlatformSupport,
         useRequestPlatformSupport2,
         useUserSurveys,
         useGrowthKPI,
+        useGrowthContactsKPI,
         // Query keys for manual operations
         queryKeys,
         // Upload