@company-semantics/contracts 19.1.0 → 20.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "19.1.0",
+  "version": "20.0.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 = '814c99a18543' as const;
-export const SPEC_HASH_FULL = '814c99a18543f448daaed5312db276f7704a9b63710c512b1a298be5fc652105' as const;
+export const SPEC_HASH = '79972d6725ff' as const;
+export const SPEC_HASH_FULL = '79972d6725ff3dfd29ee68945c8006039eddc196eadaeb0bcd77abeeebf2b066' as const;

package/src/api/generated.ts

@@ -1338,14 +1338,14 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}": {
+    "/api/company-md/docs/{id}": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        /** Get a company.md document by slug */
+        /** Get a company.md document by id */
         get: operations["getCompanyMdDoc"];
         put?: never;
         post?: never;
@@ -1355,7 +1355,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/content": {
+    "/api/company-md/docs/{id}/content": {
         parameters: {
             query?: never;
             header?: never;
@@ -1372,7 +1372,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/title": {
+    "/api/company-md/docs/{id}/title": {
         parameters: {
             query?: never;
             header?: never;
@@ -1406,7 +1406,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/context-bank": {
+    "/api/company-md/docs/{id}/context-bank": {
         parameters: {
             query?: never;
             header?: never;
@@ -1440,7 +1440,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/context-bank/associate": {
+    "/api/company-md/docs/{id}/context-bank/associate": {
         parameters: {
             query?: never;
             header?: never;
@@ -1457,7 +1457,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/context-bank/{contextDocSlug}": {
+    "/api/company-md/docs/{id}/context-bank/{contextDocId}": {
         parameters: {
             query?: never;
             header?: never;
@@ -1474,7 +1474,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/context-bank/{id}/order": {
+    "/api/company-md/docs/{id}/context-bank/{contextDocId}/order": {
         parameters: {
             query?: never;
             header?: never;
@@ -1491,7 +1491,7 @@ export interface paths {
         patch: operations["reorderCompanyMdContextBankItem"];
         trace?: never;
     };
-    "/api/company-md/docs/{parentSlug}/context-bank/upload": {
+    "/api/company-md/docs/{id}/context-bank/upload": {
         parameters: {
             query?: never;
             header?: never;
@@ -1508,7 +1508,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/context-bank/retry": {
+    "/api/company-md/docs/{id}/context-bank/retry": {
         parameters: {
             query?: never;
             header?: never;
@@ -1525,7 +1525,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/transfer-owner": {
+    "/api/company-md/docs/{id}/transfer-owner": {
         parameters: {
             query?: never;
             header?: never;
@@ -1593,7 +1593,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/sharing": {
+    "/api/company-md/docs/{id}/sharing": {
         parameters: {
             query?: never;
             header?: never;
@@ -1610,7 +1610,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/sharing/policy": {
+    "/api/company-md/docs/{id}/sharing/policy": {
         parameters: {
             query?: never;
             header?: never;
@@ -1627,7 +1627,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/sharing/acl": {
+    "/api/company-md/docs/{id}/sharing/acl": {
         parameters: {
             query?: never;
             header?: never;
@@ -1644,7 +1644,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/api/company-md/docs/{slug}/sharing/acl/{aclId}": {
+    "/api/company-md/docs/{id}/sharing/acl/{aclId}": {
         parameters: {
             query?: never;
             header?: never;
@@ -4187,10 +4187,10 @@ export interface components {
         };
         CreateContextDocRequest: {
             title: string;
-            parentDocSlug: string;
+            parentDocId: string;
         };
         AssociateContextDocRequest: {
-            contextDocSlug: string;
+            contextDocId: string;
         };
         TransferCompanyMdDocOwnerRequest: {
             /** Format: uuid */
@@ -7421,7 +7421,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7443,7 +7443,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7467,7 +7467,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7515,7 +7515,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7559,7 +7559,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7583,8 +7583,8 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
-                contextDocSlug: string;
+                id: string;
+                contextDocId: string;
             };
             cookie?: never;
         };
@@ -7604,8 +7604,8 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
                 id: string;
+                contextDocId: string;
             };
             cookie?: never;
         };
@@ -7639,7 +7639,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                parentSlug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7679,7 +7679,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7692,7 +7692,7 @@ export interface operations {
                 };
                 content?: never;
             };
-            /** @description Retry limit exceeded or invalid slug */
+            /** @description Retry limit exceeded or invalid doc */
             422: {
                 headers: {
                     [name: string]: unknown;
@@ -7706,7 +7706,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7824,7 +7824,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7846,7 +7846,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7870,7 +7870,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
             };
             cookie?: never;
         };
@@ -7894,7 +7894,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
                 aclId: string;
             };
             cookie?: never;
@@ -7919,7 +7919,7 @@ export interface operations {
             query?: never;
             header?: never;
             path: {
-                slug: string;
+                id: string;
                 aclId: string;
             };
             cookie?: never;

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>;