@company-semantics/contracts 56.0.0 → 56.1.0

package/package.json

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

package/src/api/generated-spec-hash.ts

@@ -1,3 +1,3 @@
 // AUTO-GENERATED — do not edit. Run pnpm generate:spec-hash to regenerate.
-export const SPEC_HASH = '6eb28e0d82f9' as const;
-export const SPEC_HASH_FULL = '6eb28e0d82f9d1d88e4fc954ece5377c85ddd6da30b6171c4d2aa75f347c09ed' as const;
+export const SPEC_HASH = '373ff35b2847' as const;
+export const SPEC_HASH_FULL = '373ff35b284714e9030fd0c611b3d4c1be255cd12df7f6adec2b6f7e6ba9179f' as const;

package/src/api/generated.ts

@@ -926,6 +926,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/workspace/invites/batch": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Invite many directory people at once */
+        post: operations["batchInvite"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/workspace/invites/accept": {
         parameters: {
             query?: never;
@@ -977,6 +994,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/workspace/directory": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List the org people directory */
+        get: operations["listOrgDirectory"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/workspace/domains": {
         parameters: {
             query?: never;
@@ -4577,6 +4611,26 @@ export interface components {
                 contributesTo: string[];
             };
         };
+        BatchInviteResponse: {
+            invited: string[];
+            skipped: {
+                /** Format: uuid */
+                personId: string;
+                /** @enum {string} */
+                reason: "already-member" | "invite-pending" | "no-email" | "send-failed";
+            }[];
+            failed: {
+                /** Format: uuid */
+                personId: string;
+                /** @enum {string} */
+                reason: "already-member" | "invite-pending" | "no-email" | "send-failed";
+            }[];
+        };
+        BatchInviteRequest: {
+            personIds: string[];
+            /** @enum {string} */
+            role: "admin" | "member";
+        };
         InviteListResponse: {
             id: string;
             orgId: string;
@@ -4625,6 +4679,15 @@ export interface components {
             status: string;
             orgName?: string;
         };
+        OrgDirectoryResponse: {
+            people: {
+                /** Format: uuid */
+                personId: string;
+                displayName: string;
+                primaryEmail: string | null;
+                userId: string | null;
+            }[];
+        };
         DomainListResponse: {
             id: string;
             orgId: string;
@@ -8230,6 +8293,30 @@ export interface operations {
             };
         };
     };
+    batchInvite: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["BatchInviteRequest"];
+            };
+        };
+        responses: {
+            /** @description Per-person outcome; partial success is a normal result */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BatchInviteResponse"];
+                };
+            };
+        };
+    };
     acceptInvite: {
         parameters: {
             query?: never;
@@ -8296,6 +8383,26 @@ export interface operations {
             };
         };
     };
+    listOrgDirectory: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Every person in the org directory */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["OrgDirectoryResponse"];
+                };
+            };
+        };
+    };
     listDomains: {
         parameters: {
             query?: never;

package/src/generated/openapi-routes.ts

@@ -185,12 +185,14 @@ export const openApiRoutes = {
   '/api/workspace/auth-policy/test-sso': ['POST'],
   '/api/workspace/auth-policy/test-sso/{attemptId}': ['GET'],
   '/api/workspace/auth-policy/validate-oidc': ['POST'],
+  '/api/workspace/directory': ['GET'],
   '/api/workspace/domains': ['GET', 'POST'],
   '/api/workspace/domains/{id}': ['DELETE'],
   '/api/workspace/domains/{id}/verify': ['POST'],
   '/api/workspace/handle': ['PATCH'],
   '/api/workspace/invites': ['GET', 'POST'],
   '/api/workspace/invites/accept': ['POST'],
+  '/api/workspace/invites/batch': ['POST'],
   '/api/workspace/invites/validate': ['GET'],
   '/api/workspace/invites/{id}': ['DELETE'],
   '/api/workspace/members': ['GET'],

package/src/index.ts

@@ -620,6 +620,31 @@ export type {
   PositionReporting,
 } from "./org/index";
 
+// People directory: every `persons` row in the org, account-bearing or not.
+// Neither the member list (RBAC principals) nor the org chart (topology) — the
+// set an HRIS sync populates, and the only surface carrying a directory email.
+// Capability-gated, deliberately: the org-chart read is authenticated-only.
+export {
+  OrgDirectoryPersonSchema,
+  OrgDirectoryResponseSchema,
+} from "./org/index";
+export type { OrgDirectoryPerson, OrgDirectoryResponse } from "./org/index";
+
+// Bulk invite, keyed by personId so recipients are resolved server-side from the
+// caller's own directory rather than supplied by the caller.
+export {
+  BATCH_INVITE_PERSONS_MAX,
+  BATCH_INVITE_SKIP_REASONS,
+  BatchInviteSkipReasonSchema,
+  BatchInviteRequestSchema,
+  BatchInviteResponseSchema,
+} from "./org/index";
+export type {
+  BatchInviteSkipReason,
+  BatchInviteRequest,
+  BatchInviteResponse,
+} from "./org/index";
+
 // Source authority: per-field ownership — who may WRITE a given entity field.
 // Orthogonal to provenance (who reported). (ADR-CONT-083 / ADR-CTRL-182)
 export { SourceAuthoritySchema } from "./org/index";

package/src/org/README.md

@@ -37,6 +37,14 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `AuthoritySource` _(type)_
 - `AuthoritySourceSchema` — Engine-internal authority source.
 - `AuthorizableView` _(type)_ — Type for views that can be checked against VIEWSCOPEMAP.
+- `BATCH_INVITE_PERSONS_MAX` — Cap on one batch.
+- `BATCH_INVITE_SKIP_REASONS` — Why one person in a batch did not receive an invite. - `already-member` — holds an account in this org…
+- `BatchInviteRequest` _(type)_
+- `BatchInviteRequestSchema`
+- `BatchInviteResponse` _(type)_
+- `BatchInviteResponseSchema`
+- `BatchInviteSkipReason` _(type)_
+- `BatchInviteSkipReasonSchema`
 - `COMPANY_MD_COLLAB_MAX_DOC_TEXT_BYTES` — Cap on the MATERIALIZED document text, in UTF-8 bytes of the expanded result.
 - `COMPANY_MD_COLLAB_MAX_PRESENCE_POSITION_CHARS` — Cap on ONE presence position blob (`anchor` or `head`), in base64 chars.
 - `COMPANY_MD_COLLAB_MAX_UPDATE_B64_CHARS` — Cap on ONE encoded update, measured on the base64 payload as it is sent.
@@ -178,6 +186,10 @@ Shared type vocabulary for organization ownership, type classification, and tran
 - `OrgBudgetConfigSchema`
 - `OrgDeletionStatus` _(type)_
 - `OrgDeletionStatusSchema`
+- `OrgDirectoryPerson` _(type)_
+- `OrgDirectoryPersonSchema`
+- `OrgDirectoryResponse` _(type)_
+- `OrgDirectoryResponseSchema`
 - `OrgDivergence` _(type)_
 - `OrgDivergenceResolution` _(type)_
 - `OrgDivergenceResolutionSchema` — What resolving a divergence means today.

package/src/org/index.ts

@@ -354,6 +354,14 @@ export {
   CreateInviteRequestSchema,
   InviteResponseSchema,
   InviteListResponseSchema,
+  // People directory + bulk invite (personId-keyed, capability-gated)
+  OrgDirectoryPersonSchema,
+  OrgDirectoryResponseSchema,
+  BATCH_INVITE_PERSONS_MAX,
+  BATCH_INVITE_SKIP_REASONS,
+  BatchInviteSkipReasonSchema,
+  BatchInviteRequestSchema,
+  BatchInviteResponseSchema,
   DomainResponseSchema,
   DomainListResponseSchema,
   OrgBillingResponseSchema,
@@ -366,6 +374,11 @@ export type {
   CreateInviteRequestPayload,
   InviteResponse,
   InviteListResponse,
+  OrgDirectoryPerson,
+  OrgDirectoryResponse,
+  BatchInviteSkipReason,
+  BatchInviteRequest,
+  BatchInviteResponse,
   DomainResponse,
   DomainListResponse,
   OrgBillingResponse,

package/src/org/schemas.ts

@@ -781,6 +781,116 @@ export type CreateInviteRequestPayload = z.infer<
   typeof CreateInviteRequestSchema
 >;
 
+// ---------------------------------------------------------------------------
+// GET /api/workspace/directory
+//
+// The org's PEOPLE DIRECTORY — every `persons` row, account-bearing or not.
+// Distinct from the member list (`user_org_memberships`, RBAC principals) and
+// from the org chart (`positions` + occupancy, topology): this is the answer to
+// "who does this org know about", which after an HRIS sync is a much larger set
+// than either.
+//
+// It exists because inviting a synced person needs their address, and the org
+// chart cannot carry one: `GET /api/users/org-chart` is authenticated-only, so a
+// `primaryEmail` there would let any member enumerate the whole company's email
+// addresses. This surface is capability-gated instead.
+// ---------------------------------------------------------------------------
+
+export const OrgDirectoryPersonSchema = z.object({
+  personId: z.string().uuid(),
+  displayName: z.string(),
+  /**
+   * Nullable and NOT optional. A directory person with no address is a real,
+   * common state — an HRIS export with the email column unmapped produces a
+   * whole org of them — and it is the difference between "cannot be invited" and
+   * "not yet loaded". Callers must render the distinction rather than treat a
+   * missing address as absence of the person.
+   */
+  primaryEmail: z.string().nullable(),
+  /** The linked account, or null when this person has never signed up. */
+  userId: z.string().uuid().nullable(),
+});
+
+export type OrgDirectoryPerson = z.infer<typeof OrgDirectoryPersonSchema>;
+
+export const OrgDirectoryResponseSchema = z.object({
+  people: z.array(OrgDirectoryPersonSchema),
+});
+
+export type OrgDirectoryResponse = z.infer<typeof OrgDirectoryResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api/workspace/invites/batch
+//
+// Bulk invite, keyed by `personId` rather than by email. That is a security
+// property, not a convenience: the single-invite route takes a caller-supplied
+// address and can therefore reach any mailbox on the internet, which is why it
+// carries a strict per-minute limit. This route's recipients are resolved
+// server-side from the caller's own `persons` rows, so the reachable set is
+// bounded by the org's own directory and the arbitrary-recipient risk is gone.
+//
+// Consequence for callers: the client never needs to hold an email address to
+// send an invite, and an unknown or cross-org `personId` is silently omitted
+// from the response rather than reported — reporting it would make this a
+// membership oracle.
+// ---------------------------------------------------------------------------
+
+/**
+ * Cap on one batch. Bounds worst-case request latency, since the invite emails
+ * are sent before the response returns (the raw token exists only in memory and
+ * must not be parked in a queue).
+ */
+export const BATCH_INVITE_PERSONS_MAX = 100;
+
+export const BatchInviteRequestSchema = z.object({
+  personIds: z.array(z.string().uuid()).min(1).max(BATCH_INVITE_PERSONS_MAX),
+  // Same restricted {admin, member} domain as a single invite.
+  role: z.enum(["admin", "member"]),
+});
+
+export type BatchInviteRequest = z.infer<typeof BatchInviteRequestSchema>;
+
+/**
+ * Why one person in a batch did not receive an invite.
+ *
+ * - `already-member`  — holds an account in this org already.
+ * - `invite-pending`  — an unexpired invite is already outstanding.
+ * - `no-email`        — the directory row carries no address to send to.
+ * - `send-failed`     — the invite row COMMITTED but the email did not leave.
+ *                       Recoverable by resending; never a reason to roll the
+ *                       invite back.
+ */
+export const BATCH_INVITE_SKIP_REASONS = [
+  "already-member",
+  "invite-pending",
+  "no-email",
+  "send-failed",
+] as const;
+
+export const BatchInviteSkipReasonSchema = z.enum(BATCH_INVITE_SKIP_REASONS);
+
+export type BatchInviteSkipReason = z.infer<typeof BatchInviteSkipReasonSchema>;
+
+const BatchInviteOutcomeSchema = z.object({
+  personId: z.string().uuid(),
+  reason: BatchInviteSkipReasonSchema,
+});
+
+export const BatchInviteResponseSchema = z.object({
+  /** Person ids that now hold a pending invite AND were emailed. */
+  invited: z.array(z.string().uuid()),
+  /** Never attempted — see {@link BatchInviteSkipReason}. */
+  skipped: z.array(BatchInviteOutcomeSchema),
+  /**
+   * Invite row exists, delivery did not. Separate from `skipped` because the
+   * remedy differs: a skip needs the underlying state to change, a failure needs
+   * a resend.
+   */
+  failed: z.array(BatchInviteOutcomeSchema),
+});
+
+export type BatchInviteResponse = z.infer<typeof BatchInviteResponseSchema>;
+
 // ---------------------------------------------------------------------------
 // OrgDomain sub-schema
 // ---------------------------------------------------------------------------

package/src/resource-key-types.ts

@@ -20,6 +20,9 @@ export type ResourceKey =
   | { type: "teams"; orgId: string }
   | { type: "integrations"; orgId: string }
   | { type: "invites"; orgId: string }
+  // The people directory (`persons`) — every person the org knows about,
+  // account-bearing or not. Distinct from `members`, which is accounts only.
+  | { type: "orgDirectory"; orgId: string }
   | { type: "auditEvents"; orgId: string }
   | { type: "timeline"; orgId: string }
   // Identities (singular) — single entities

package/src/resource-keys.ts

@@ -129,6 +129,7 @@ const ORG_SCOPED_TYPES = [
   "teams",
   "integrations",
   "invites",
+  "orgDirectory",
   "auditEvents",
   "timeline",
   "workspace",
@@ -266,6 +267,7 @@ export function toQueryKey(key: ResourceKey): readonly string[] {
     case "teams":
     case "integrations":
     case "invites":
+    case "orgDirectory":
     case "auditEvents":
     case "timeline":
     case "workspace":