@company-semantics/contracts 5.0.0 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/__tests__/resource-keys.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import {
+  toQueryKey,
+  fromQueryKey,
+  matchesResourceKey,
+  type ResourceKey,
+} from '../resource-keys.js';
+
+const ORG_ID = '11111111-1111-4111-8111-111111111111';
+
+describe('resource-keys: orgUnitOwners (org-scoped)', () => {
+  const key: ResourceKey = { type: 'orgUnitOwners', orgId: ORG_ID };
+
+  it('toQueryKey produces [type, orgId] with no unitId', () => {
+    const qk = toQueryKey(key);
+    expect(qk).toEqual(['orgUnitOwners', ORG_ID]);
+    // org-scoped: exactly two segments, no per-unit identity
+    expect(qk).toHaveLength(2);
+  });
+
+  it('roundtrips through fromQueryKey', () => {
+    const parsed = fromQueryKey(toQueryKey(key));
+    expect(parsed).toEqual(key);
+    expect('unitId' in parsed).toBe(false);
+  });
+
+  it('matchesResourceKey is org-scoped: rejects a different orgId', () => {
+    const other = '22222222-2222-4222-8222-222222222222';
+    expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    expect(matchesResourceKey(['orgUnitOwners', other], key)).toBe(false);
+  });
+});
+
+describe('resource-keys: system-scoped internalAdmin* types', () => {
+  const systemTypes = [
+    'internalAdminAiProviders',
+    'internalAdminPrompts',
+    'internalAdminAiRuntimeDefaults',
+  ] as const;
+
+  for (const type of systemTypes) {
+    const key = { type, scope: 'system' } as ResourceKey;
+
+    it(`${type}: toQueryKey produces [type, 'system']`, () => {
+      expect(toQueryKey(key)).toEqual([type, 'system']);
+    });
+
+    it(`${type}: roundtrips through fromQueryKey with scope: 'system'`, () => {
+      const parsed = fromQueryKey(toQueryKey(key));
+      expect(parsed).toEqual(key);
+      expect('orgId' in parsed).toBe(false);
+      expect('userId' in parsed).toBe(false);
+    });
+
+    it(`${type}: matchesResourceKey accepts a matching system key`, () => {
+      expect(matchesResourceKey(toQueryKey(key), key)).toBe(true);
+    });
+  }
+
+  it('matchesResourceKey rejects a mismatched system type', () => {
+    const target: ResourceKey = { type: 'internalAdminPrompts', scope: 'system' };
+    expect(matchesResourceKey(['internalAdminAiProviders', 'system'], target)).toBe(false);
+  });
+});

package/src/resource-keys.ts

@@ -36,8 +36,16 @@ export type ResourceKey =
   | { type: 'orgUnitAncestors'; orgId: string; unitId: string }
   | { type: 'orgUnitMemberships'; orgId: string; unitId: string }
   | { type: 'orgUnitPermissions'; orgId: string; unitId: string }
+  // Org-unit owners list (ADR-CONTRACTS-052) — owners are an org-wide
+  // projection, not a per-unit collection, so unitId is intentionally excluded.
+  | { type: 'orgUnitOwners'; orgId: string }
   // People reporting (ADR-BE-166) — drives the settings Org chart drill-down
   | { type: 'peopleOrgChart'; orgId: string }
+  // System-scoped (ADR-CONTRACTS-052) — tenant-less super-admin resources.
+  // No orgId/userId: these live above any single org. scope is the literal 'system'.
+  | { type: 'internalAdminAiProviders'; scope: 'system' }
+  | { type: 'internalAdminPrompts'; scope: 'system' }
+  | { type: 'internalAdminAiRuntimeDefaults'; scope: 'system' }
   // User-scoped
   | { type: 'dismissedBanners'; userId: string }
   | { type: 'userOrgs'; userId: string }
@@ -64,11 +72,20 @@ const ORG_SCOPED_TYPES = [
   'members', 'departments', 'chats', 'teams', 'integrations', 'invites',
   'auditEvents', 'timeline', 'workspace', 'workspaceDomains', 'authSettings',
   'billing', 'aiUsage', 'deletionEligibility', 'transferOwnership', 'companyMdDocs',
-  'orgTree', 'orgLevelConfig', 'peopleOrgChart',
+  'orgTree', 'orgLevelConfig', 'peopleOrgChart', 'orgUnitOwners',
 ] as const;
 
 const USER_SCOPED_TYPES = ['dismissedBanners', 'userOrgs', 'sessions', 'viewer'] as const;
 
+/**
+ * System-scoped types (ADR-CONTRACTS-052) — tenant-less super-admin resources.
+ * Their query key is [type, 'system']; they carry no orgId or userId.
+ * Intentionally NOT exported — internal to the parser like the other scope arrays.
+ */
+const SYSTEM_SCOPED_TYPES = [
+  'internalAdminAiProviders', 'internalAdminPrompts', 'internalAdminAiRuntimeDefaults',
+] as const;
+
 /**
  * Canonical ResourceKey → query key conversion.
  * This is the ONLY function that constructs query keys — no ad-hoc key
@@ -128,8 +145,15 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case 'orgTree':
     case 'orgLevelConfig':
     case 'peopleOrgChart':
+    case 'orgUnitOwners':
       return [key.type, key.orgId] as const;
 
+    // System-scoped (ADR-CONTRACTS-052) — tenant-less super-admin resources
+    case 'internalAdminAiProviders':
+    case 'internalAdminPrompts':
+    case 'internalAdminAiRuntimeDefaults':
+      return [key.type, key.scope] as const;
+
     default: {
       const _exhaustive: never = key;
       throw new Error(`Unknown resource type: ${JSON.stringify(_exhaustive)}`);
@@ -170,6 +194,11 @@ export function fromQueryKey(queryKey: readonly string[]): ResourceKey {
     return { type, orgId: rest[0], [identityFields[type]]: rest[1] } as ResourceKey;
   }
 
+  // System-scoped types (ADR-CONTRACTS-052) — query key is [type, 'system']
+  if ((SYSTEM_SCOPED_TYPES as readonly string[]).includes(type)) {
+    return { type, scope: 'system' } as ResourceKey;
+  }
+
   // User-scoped types
   if ((USER_SCOPED_TYPES as readonly string[]).includes(type)) {
     return { type, userId: rest[0] } as ResourceKey;
@@ -238,6 +267,7 @@ export function matchesResourceKey(queryKey: readonly unknown[], targetKey: Reso
   if ('chatId' in parsed && 'chatId' in targetKey && parsed.chatId !== targetKey.chatId) return false;
   if ('slug' in parsed && 'slug' in targetKey && parsed.slug !== targetKey.slug) return false;
   if ('unitId' in parsed && 'unitId' in targetKey && parsed.unitId !== targetKey.unitId) return false;
+  if ('scope' in parsed && 'scope' in targetKey && parsed.scope !== targetKey.scope) return false;
 
   return true;
 }