@company-semantics/contracts 0.50.0 → 0.52.0

package/package.json

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

package/src/company-admin.ts

@@ -0,0 +1,29 @@
+/**
+ * Company admin types — shared vocabulary for cross-org admin control plane.
+ *
+ * These types support the company admin MVP (read-only).
+ * @see PRD-00113 for design rationale.
+ */
+
+/** Read-only capabilities for company admin MVP. */
+export type CompanyCapability =
+  | 'company.view_orgs'
+  | 'company.view_audit'
+  | 'company.view_system';
+
+/** Context attached to company-admin requests after auth middleware validation. */
+export interface CompanyAdminContext {
+  readonly kind: 'company';
+  readonly adminEmail: string;
+  readonly capabilities: readonly CompanyCapability[];
+}
+
+/**
+ * Discriminated union for request contexts.
+ *
+ * Org-scoped requests carry OrgScopedContext (kind: 'org').
+ * Company admin requests carry CompanyAdminContext (kind: 'company').
+ */
+export type RequestContext =
+  | (import('./org/types').OrgScopedContext & { readonly kind: 'org' })
+  | CompanyAdminContext;

package/src/identity/index.ts

@@ -6,7 +6,14 @@
  */
 
 // Types
-export type { ISODateString, NameSource, UserIdentity } from './types';
+export type {
+  ISODateString,
+  NameSource,
+  UserIdentity,
+  UserLifecycleStatus,
+  DeletionBlocker,
+  AccountDeletionEligibility,
+} from './types';
 
 // Functions - Display Name
 export {

package/src/identity/types.ts

@@ -94,3 +94,36 @@ export type UserIdentity = {
    */
   slackAvatarLastSyncedAt?: ISODateString;
 };
+
+// =============================================================================
+// User Lifecycle
+// =============================================================================
+
+/**
+ * User lifecycle status. Replaces the boolean `isActive` field.
+ *
+ * State transitions:
+ *   active → pending_deletion  (self-service deletion request)
+ *   pending_deletion → active  (cancel during grace period)
+ *   pending_deletion → deleted (async purge after grace period)
+ *   deleted → (terminal, no transitions)
+ *   active → deleted           (FORBIDDEN — must pass through pending_deletion)
+ */
+export type UserLifecycleStatus = 'active' | 'pending_deletion' | 'deleted';
+
+/**
+ * Conditions that block account deletion.
+ * Discriminated union — extend with new blocker types without breaking changes.
+ */
+export type DeletionBlocker =
+  | { type: 'sole_workspace_owner'; workspaceId: string; workspaceName: string }
+  | { type: 'active_legal_hold'; holdId: string };
+
+/**
+ * Result of an account deletion eligibility check.
+ * Invariant: eligible=true ↔ blockers.length === 0
+ */
+export type AccountDeletionEligibility = {
+  eligible: boolean;
+  blockers: DeletionBlocker[];
+};

package/src/index.ts

@@ -106,7 +106,14 @@ export type { Compatibility, Deprecation } from './compatibility'
 
 // User identity types and functions
 // @see ADR-CONT-032 for design rationale
-export type { ISODateString, NameSource, UserIdentity } from './identity/index'
+export type {
+  ISODateString,
+  NameSource,
+  UserIdentity,
+  UserLifecycleStatus,
+  DeletionBlocker,
+  AccountDeletionEligibility,
+} from './identity/index'
 export { extractFirstWord, resolveDisplayName, deriveFullName } from './identity/index'
 
 // Avatar types and functions
@@ -175,6 +182,12 @@ export type {
   // Authorization context types (Phase 5)
   // @see ADR-CTRL-010 for design rationale
   OrgScopedContext,
+  // Workspace Info/Settings surface types (PRD-00133)
+  WorkspaceSurface,
+  WorkspaceInfoOverview,
+  WorkspaceSettingsOverview,
+  IntegrationRequestStatus,
+  IntegrationRequest,
 } from './org/index'
 
 export { ROLE_DISPLAY_MAP, WORKSPACE_CAPABILITIES, ROLE_CAPABILITY_MAP, VIEW_SCOPE_MAP, getViewScope } from './org/index'
@@ -337,6 +350,14 @@ export type {
 // Ralph constants (cross-repo support)
 export { REPO_PRECEDENCE } from './ralph/index'
 
+// Company admin types (cross-org control plane)
+// @see PRD-00113 for design rationale
+export type {
+  CompanyCapability,
+  CompanyAdminContext,
+  RequestContext,
+} from './company-admin'
+
 // Rate limit domain types
 // @see PRD-00013 for contracts integration
 export type { RateLimitConfig, RateLimitResult } from './rate-limit/index'

package/src/org/index.ts

@@ -36,6 +36,12 @@ export type {
   UserOrgMembership,
   // Authorization context types (Phase 5 - ADR-CTRL-010)
   OrgScopedContext,
+  // Workspace Info/Settings surface types (PRD-00133)
+  WorkspaceSurface,
+  WorkspaceInfoOverview,
+  WorkspaceSettingsOverview,
+  IntegrationRequestStatus,
+  IntegrationRequest,
 } from './types';
 
 export { ROLE_DISPLAY_MAP } from './types';

package/src/org/types.ts

@@ -328,6 +328,8 @@ export interface UserOrgMembership {
   joinedAt: string;
   /** Whether this membership is currently active. */
   isActive: boolean;
+  /** Organization type (personal vs shared). */
+  orgType: OrgType;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -375,3 +377,78 @@ export interface OrgScopedContext {
    */
   readonly _orgValidated: true;
 }
+
+// =============================================================================
+// Workspace Info/Settings Surface Types (PRD-00133)
+// Capability naming invariant:
+//   Info surfaces use view-capabilities only (org.view_*)
+//   Settings surfaces use manage-capabilities only (org.manage_*)
+// Consumers MUST NOT cross-wire: Info routes must never require org.manage_*
+// capabilities, and Settings routes must never rely solely on org.view_*.
+// =============================================================================
+
+/**
+ * Discriminator for workspace surface routing.
+ * - 'info': Read-only surface, any member, org.view_* capabilities
+ * - 'settings': Admin surface, org.manage_* capabilities
+ */
+export type WorkspaceSurface = 'info' | 'settings';
+
+/**
+ * Read-only workspace overview for the Info surface.
+ * Visible to any workspace member with org.view_* capabilities.
+ *
+ * CAPABILITY INVARIANT: This type is served ONLY by Info routes
+ * which require org.view_* capabilities. Never use org.manage_*.
+ */
+export interface WorkspaceInfoOverview {
+  /** Organization name. */
+  name: string;
+  /** Workspace owners (display-only). */
+  owners: Array<{ id: string; name: string }>;
+  /** Total member count. */
+  memberCount: number;
+  /** Human-readable management line (e.g., "Managed by Alice"). */
+  managedByLine: string;
+}
+
+/**
+ * Full workspace overview for the Settings surface.
+ * Extends Info with mutation-relevant fields.
+ * Visible only to admins with org.manage_* capabilities.
+ *
+ * CAPABILITY INVARIANT: This type is served ONLY by Settings routes
+ * which require org.manage_* capabilities. Never use org.view_* alone.
+ */
+export interface WorkspaceSettingsOverview extends WorkspaceInfoOverview {
+  /** Organization slug (editable by admin). */
+  slug: string;
+  /** Metadata about who last edited settings and when. */
+  editMetadata: {
+    lastEditedBy: { id: string; name: string } | null;
+    lastEditedAt: string | null;
+  };
+}
+
+/**
+ * Status of an integration request from a member.
+ */
+export type IntegrationRequestStatus = 'pending' | 'approved' | 'denied';
+
+/**
+ * Advisory integration request created by a member.
+ * Members can request integration connections; admins see and action these.
+ * Creating a request does NOT guarantee approval.
+ */
+export interface IntegrationRequest {
+  /** Unique request identifier. */
+  id: string;
+  /** Integration provider name (e.g., 'slack', 'github'). */
+  provider: string;
+  /** User who made the request. */
+  requestedBy: { id: string; name: string };
+  /** Current status of the request. */
+  status: IntegrationRequestStatus;
+  /** ISO8601 timestamp when the request was created. */
+  createdAt: string;
+}