@company-semantics/contracts 19.1.0 → 19.2.0

package/package.json

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

package/src/index.ts

@@ -23,7 +23,12 @@ export type InsightConfidence = "low" | "medium" | "high";
 export type InvariantPhase = "observe" | "stabilize" | "enforce";
 
 // Integration partner categories — surface grouping in settings UIs
-export const INTEGRATION_CATEGORIES = ["Meetings", "Comms", "Docs"] as const;
+export const INTEGRATION_CATEGORIES = [
+  "Meetings",
+  "Comms",
+  "Docs",
+  "HR",
+] as const;
 export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number];
 
 // System diagram types
@@ -838,3 +843,8 @@ export * from "./permissions";
 // Single source of truth for upload formats; the backend normalizer joins its
 // private dispatch fields locally, the app derives its accept-set + copy.
 export * from "./ingestion";
+
+// Third-party integration vocabulary (PRD-00793)
+// HrConnectionStatus / HrConnectInput — see ./integrations/schemas.ts.
+// Pairs with the `HR` member of INTEGRATION_CATEGORIES above.
+export * from "./integrations";

package/src/integrations/README.md

@@ -0,0 +1,46 @@
+# integrations/
+
+Shared vocabulary for third-party integration surfaces.
+
+## Purpose
+
+The cross-repo contract for HR-system integrations. The backend owns the
+provider sync and persistence; the app renders the connection state and submits
+the connect form. Both repos share the same `HrConnectionStatus` projection and
+`HrConnectInput` shape so the boundary stays stable across independent releases.
+
+The `HR` member of `INTEGRATION_CATEGORIES` (package root) names this category
+alongside `Meetings`, `Comms`, and `Docs`.
+
+## Invariants
+
+- `HrConnectionStatusSchema` is a read projection: count and sync fields are
+  `null` until the first successful sync (a connected, never-synced integration).
+- `HrConnectInputSchema` carries only the customer's provider `subdomain`; no
+  secrets or provider credentials live in contracts.
+- Pure vocabulary — `zod` is the only runtime import (vocabulary-guard).
+
+<!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
+
+## Public API
+
+- `HrConnectInput` _(type)_
+- `HrConnectInputSchema` — Input submitted by the app to initiate an HR provider connection.
+- `HrConnectionStatus` _(type)_
+- `HrConnectionStatusSchema` — Health of the most recent HR provider sync.
+
+<!-- END GENERATED: readme-public-api -->
+
+<!-- BEGIN GENERATED: readme-dependencies — derived from code by `pnpm readme-api`. Do not edit. -->
+
+## Dependencies
+
+**Internal domains:**
+
+_None._
+
+**External packages:**
+
+- `zod`
+
+<!-- END GENERATED: readme-dependencies -->

package/src/integrations/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Third-party integration vocabulary barrel (PRD-00793).
+ *
+ * @see ./schemas.ts for the full schema definitions and invariants.
+ */
+export { HrConnectionStatusSchema, HrConnectInputSchema } from "./schemas";
+
+export type { HrConnectionStatus, HrConnectInput } from "./schemas";

package/src/integrations/schemas.ts

@@ -0,0 +1,72 @@
+/**
+ * Third-party integration shared vocabulary (PRD-00793).
+ *
+ * Zod schemas describing the cross-repo contract for HR-system integrations.
+ * The `HR` integration category joins the existing `INTEGRATION_CATEGORIES`
+ * tuple in the package root; these schemas describe the connection-status
+ * projection the backend exposes and the connect input the app submits.
+ *
+ * Lives in contracts because the integration surface crosses backend (which
+ * owns the provider sync + persistence) and app (which renders the connection
+ * state and the connect form), and breaking it would require coordinated
+ * releases (see the promotion rule in CLAUDE.md).
+ *
+ * Per the durable user preference `feedback_structured_metadata_not_json_strings`,
+ * descriptions live in `.meta({ description })` — structured metadata, not
+ * stringified JSON blobs on the schema.
+ */
+import { z } from "zod";
+
+// =============================================================================
+// HR connection status
+// =============================================================================
+
+/**
+ * Health of the most recent HR provider sync. `null` when no sync has run yet
+ * (a freshly connected, never-synced integration).
+ */
+export const HrConnectionStatusSchema = z
+  .object({
+    connected: z.boolean().meta({
+      description: "Whether an HR provider is currently connected.",
+    }),
+    employeeCount: z.number().int().nonnegative().nullable().meta({
+      description:
+        "Employees mirrored from the HR provider; null when never synced.",
+    }),
+    departmentCount: z.number().int().nonnegative().nullable().meta({
+      description:
+        "Departments mirrored from the HR provider; null when never synced.",
+    }),
+    lastSyncAt: z.string().datetime().nullable().meta({
+      description: "ISO timestamp of the last successful sync; null if never.",
+    }),
+    syncHealth: z.enum(["healthy", "degraded", "error"]).nullable().meta({
+      description:
+        "Health of the most recent sync; null when no sync has run yet.",
+    }),
+  })
+  .meta({
+    description: "Connection-status projection for an HR integration.",
+  });
+export type HrConnectionStatus = z.infer<typeof HrConnectionStatusSchema>;
+
+// =============================================================================
+// HR connect input
+// =============================================================================
+
+/**
+ * Input submitted by the app to initiate an HR provider connection. The
+ * `subdomain` identifies the customer's tenant on the provider (e.g. the
+ * BambooHR company subdomain).
+ */
+export const HrConnectInputSchema = z
+  .object({
+    subdomain: z.string().meta({
+      description: "Customer tenant subdomain on the HR provider.",
+    }),
+  })
+  .meta({
+    description: "Input to initiate an HR provider connection.",
+  });
+export type HrConnectInput = z.infer<typeof HrConnectInputSchema>;