@pam-ai/pam-ordo-contracts 3.23.0 → 3.25.0

package/dist/generated.d.ts

@@ -3,6 +3,62 @@
  * Do not make direct changes to the file.
  */
 export interface paths {
+    "/v1/inbox/staff-work-status/self": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read the authenticated staff member's effective work status */
+        get: operations["getInboxStaffWorkStatus"];
+        /** Set the authenticated staff member's bounded work-status override */
+        put: operations["setInboxStaffWorkStatus"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/inbox/staff-schedules/{userId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read one rooftop staff schedule */
+        get: operations["getInboxStaffSchedule"];
+        /** Replace one staff member's weekly rota and dated exceptions */
+        put: operations["setInboxStaffSchedule"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/inbox/assignment-candidates": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List rooftop staff with authoritative work status for assignment
+         * @description Returns the active rooftop roster from Permissions with effective work status. A scheduled shift is display context only and never implies AVAILABLE. Only a current explicit AVAILABLE self status may set assignmentCandidate true. Cursors are opaque and UNKNOWN or stale authority is always excluded.
+         */
+        get: operations["listInboxAssignmentCandidates"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/inbox/realtime-session": {
         parameters: {
             query?: never;
@@ -150,7 +206,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** List the authenticated User's visible active notifications */
+        /**
+         * List the authenticated User's visible active notifications
+         * @description Visible means undismissed and not currently snoozed. A notification with a future `snoozedUntil` is withheld from this page and from `unreadCount`, and returns on its own once that time passes; it is not dismissed and its unread state is unchanged while hidden.
+         */
         get: operations["listInboxNotifications"];
         put?: never;
         post?: never;
@@ -501,6 +560,28 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/inbox/commands/snooze-notification": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Hide one recipient-owned notification until a chosen time
+         * @description Recipient-scoped and deliberately NOT a WorkCycle command. Snoozing an alert means "not now, tell me again later"; it must not pause the work the alert points at, because the recipient is frequently not the person who owns that work and a Conversation the Customer is still writing to would go quiet for everyone.
+         *     That scoping is also why there is no `expectedVersion` here, in contrast to `/v1/inbox/commands/snooze`. Optimistic concurrency guards a mutation of the WorkCycle aggregate; this command mutates only the caller's own notification row, which nobody else can write. A notification carries no aggregate version for the same reason, and one stamped at send time would be stale before it arrived. `operationId` carries idempotency, as it does for the other recipient-owned notification commands.
+         *     `until` must be in the future. A notification already snoozed may be re-snoozed to a later or earlier time; the newest accepted value wins. Snoozing never marks the notification read, and dismissal supersedes a snooze permanently.
+         */
+        post: operations["snoozeInboxNotification"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/inbox/commands/dismiss-notifications": {
         parameters: {
             query?: never;
@@ -530,6 +611,158 @@ export interface components {
         InboxScope: "MY_INBOX" | "TEAM_INBOX" | "MENTIONS" | "CUSTOMERS" | "RO";
         /** @enum {string} */
         WorkCycleStatus: "OPEN" | "SNOOZED" | "RESOLVED";
+        /**
+         * @description Effective staff state owned by Permissions. AVAILABLE is reserved for a current explicit self override; being scheduled is not availability.
+         * @enum {string}
+         */
+        StaffWorkStatus: "AVAILABLE" | "ON_BREAK" | "OFF_FOR_DAY" | "OFF_SHIFT" | "UNKNOWN";
+        /** @enum {string} */
+        StaffWorkStatusSource: "SELF_OVERRIDE" | "DATE_EXCEPTION" | "WEEKLY_ROTA" | "NO_SCHEDULE" | "STALE_SCHEDULE";
+        StaffShiftWindow: {
+            /** Format: date */
+            date: string;
+            /** Format: date-time */
+            startAt: string;
+            /** Format: date-time */
+            endAt: string;
+        };
+        StaffWorkStatusSnapshot: {
+            clientOrgId: string;
+            userId: string;
+            status: components["schemas"]["StaffWorkStatus"];
+            source: components["schemas"]["StaffWorkStatusSource"];
+            /** Format: date-time */
+            observedAt: string;
+            /** @description The instant after which this answer must be recomputed. Null is allowed only for UNKNOWN. */
+            expiresAt: string | null;
+            scheduleVersion: number | null;
+            reason: string | null;
+            todayShift: components["schemas"]["StaffShiftWindow"] | null;
+        };
+        StaffAssignmentCandidate: {
+            clientOrgId: string;
+            userId: string;
+            status: components["schemas"]["StaffWorkStatus"];
+            source: components["schemas"]["StaffWorkStatusSource"];
+            /** Format: date-time */
+            observedAt: string;
+            expiresAt: string | null;
+            scheduleVersion: number | null;
+            reason: string | null;
+            todayShift: components["schemas"]["StaffShiftWindow"] | null;
+            displayName: components["schemas"]["HydratedText"];
+            persona: string | null;
+            department: ("SERVICE" | "BDC") | null;
+            teamIds: string[];
+            /** @description Active rooftop/capability eligibility for a deliberate User assignment. */
+            manualAssignmentEligible: boolean;
+            /** @description True only when manual eligibility and a current explicit AVAILABLE status both hold. */
+            automaticAssignmentEligible: boolean;
+            exclusionReason: string | null;
+        };
+        StaffAssignmentCandidatesResponse: {
+            data: {
+                /** Format: date-time */
+                observedAt: string;
+                candidates: components["schemas"]["StaffAssignmentCandidate"][];
+                nextCursor: string | null;
+            };
+        };
+        StaffWorkStatusSelfCommand: {
+            clientOrgId: string;
+            /** @enum {string} */
+            status: "AVAILABLE" | "ON_BREAK" | "OFF_FOR_DAY";
+            /** @enum {integer} */
+            breakDurationMinutes?: 15 | 30 | 60;
+            expectedVersion: number;
+            reason?: string;
+        } & unknown;
+        StaffWorkStatusSelfResult: {
+            data: {
+                overrideVersion: number;
+                workStatus: components["schemas"]["StaffWorkStatusSnapshot"];
+            };
+        };
+        StaffLocalTimeInterval: {
+            start: string;
+            end: string;
+        };
+        StaffWeeklyRota: {
+            MONDAY: components["schemas"]["StaffDayIntervals"];
+            TUESDAY: components["schemas"]["StaffDayIntervals"];
+            WEDNESDAY: components["schemas"]["StaffDayIntervals"];
+            THURSDAY: components["schemas"]["StaffDayIntervals"];
+            FRIDAY: components["schemas"]["StaffDayIntervals"];
+            SATURDAY: components["schemas"]["StaffDayIntervals"];
+            SUNDAY: components["schemas"]["StaffDayIntervals"];
+        };
+        StaffDayIntervals: components["schemas"]["StaffLocalTimeInterval"][];
+        StaffScheduleException: {
+            /** Format: date */
+            date: string;
+            /** @enum {string} */
+            kind: "WORKING" | "OFF";
+            intervals: components["schemas"]["StaffDayIntervals"];
+            reason: string | null;
+        };
+        StaffSchedule: {
+            clientOrgId: string;
+            userId: string;
+            version: number;
+            timezone: string;
+            /** Format: date */
+            effectiveFrom: string;
+            /** Format: date-time */
+            expiresAt: string;
+            weeklyRota: components["schemas"]["StaffWeeklyRota"];
+            dateExceptions: components["schemas"]["StaffScheduleException"][];
+            /** Format: date-time */
+            updatedAt: string;
+        };
+        StaffScheduleCommand: {
+            clientOrgId: string;
+            expectedVersion: number;
+            timezone: string;
+            /** Format: date */
+            effectiveFrom: string;
+            /** Format: date-time */
+            expiresAt: string;
+            weeklyRota: components["schemas"]["StaffWeeklyRota"];
+            dateExceptions: components["schemas"]["StaffScheduleException"][];
+        };
+        StaffScheduleResult: {
+            data: components["schemas"]["StaffSchedule"];
+        };
+        StaffRosterCandidateRequestV1: {
+            /** @constant */
+            schemaVersion: 1;
+            /** @constant */
+            mode: "ROSTER";
+            clientOrgId: string;
+            cursor?: string;
+            limit: number;
+        };
+        StaffExactCandidateRequestV1: {
+            /** @constant */
+            schemaVersion: 1;
+            /** @constant */
+            mode: "EXACT";
+            clientOrgId: string;
+            userIds: string[];
+        };
+        StaffAssignmentCandidateRequestV1: components["schemas"]["StaffRosterCandidateRequestV1"] | components["schemas"]["StaffExactCandidateRequestV1"];
+        /** @description For ROSTER requests, results retain the authority's stable roster page order and nextCursor is the opaque continuation cursor or null at completion. For EXACT requests, results are a unique subset of the requested User IDs in request order; an unresolved or ineligible User may be omitted, and nextCursor must be null. */
+        StaffAssignmentCandidateResponseV1: {
+            /** @constant */
+            schemaVersion: 1;
+            clientOrgId: string;
+            /** Format: date-time */
+            observedAt: string;
+            /** @description Candidate rows in stable roster order for ROSTER mode, or a unique request-ordered subset for EXACT mode. */
+            results: components["schemas"]["StaffAssignmentCandidate"][];
+            /** @description Opaque ROSTER continuation cursor; always null for EXACT mode. */
+            nextCursor: string | null;
+        };
         /** @enum {string} */
         AvailabilityState: "available" | "missing" | "stale" | "timeout" | "unauthorized" | "unsupported";
         Availability: {
@@ -741,6 +974,14 @@ export interface components {
             notifications: components["schemas"]["InboxPolicyNotificationRuleV1"][];
             customerMessageNotifications?: components["schemas"]["InboxPolicyCustomerMessageNotificationsV1"];
             emailDelivery?: components["schemas"]["InboxEmailDeliveryPolicyV1"];
+            staffWorkStatus?: components["schemas"]["InboxPolicyStaffWorkStatusV1"];
+        };
+        /** @description Rooftop activation for authoritative Permissions work status. Missing is normalized as DISPLAY_ONLY. SHADOW records the decision without changing routing; ENFORCED may exclude non-AVAILABLE Users from automatic routing. Manual assignment continues to use manualAssignmentEligible. */
+        InboxPolicyStaffWorkStatusV1: {
+            /** @enum {string} */
+            mode: "DISPLAY_ONLY" | "SHADOW" | "ENFORCED";
+            /** Format: date-time */
+            activatedAt: string;
         };
         /** @description Optional email-only delivery policy, separate from notification creation and recipient selection. Missing policy or enabled=false sends no email. Only notifications created at or after activatedAt are eligible. An empty kinds array opts into nothing. Reading, dismissal, and source resolution do not suppress an otherwise authorized send. Current disablement is a kill switch for unsent work; unknown send outcomes require reconciliation. */
         InboxEmailDeliveryPolicyV1: {
@@ -870,6 +1111,14 @@ export interface components {
             /** @description Whether the viewer has active Mentions-view membership for the current WorkCycle. */
             isMentionWatcher: boolean;
             unreadMentionCount: number;
+            /**
+             * @description Whether the viewer still owes an answer to a Mention on the current WorkCycle.
+             *     Cleared by resolution, which happens two ways and this field does not distinguish them. The explicit one is resolve-mention, the Done button. The implicit one is ANSWERING: commenting on the thread or sending the Customer a message resolves the viewer's outstanding Mentions on that cycle, because that is the thing they were asked to do and making them press Done as well would be asking them to report work the system just watched them finish. A comment never resolves the Mentions it itself raised.
+             *     None of the three fields above can stand in for it, which is why it exists. `isMentionWatcher` reports Mentions-view membership, and membership survives resolution on purpose so a later Mention on the same cycle still reaches the viewer. `unreadMentionCount` is cleared by reading, which is a different act from answering. And `latestMentionPreview` describes the newest Mention whether or not it is outstanding.
+             *     Until now the answer existed only inside the Mentions list's own server-side predicate, so a badge could be drawn on that list and nowhere else. Optional until every producer publishes it; absent means unknown, not false.
+             * @example true
+             */
+            hasUnresolvedMention?: boolean;
             latestMentionPreview?: components["schemas"]["LatestMentionPreview"] | null;
             /**
              * Format: uuid
@@ -981,6 +1230,16 @@ export interface components {
             /** Format: date-time */
             resolvedAt?: string | null;
             version: number;
+            /**
+             * @description Inbound Customer Interactions on THIS WorkCycle with no outbound Interaction after them. Optional until every producer publishes it; absent means the count is unknown, not zero.
+             *     It answers a different question from `InteractionSummary`, which sits beside this object rather than inside it: that one is Conversation-wide and totals every Interaction ever exchanged, so it keeps climbing across cycles and never falls when someone replies. A row that says how much is waiting on the reader needs this one. `oldestUnrespondedAt` already names the same set's earliest member.
+             */
+            unrespondedInboundCount?: number;
+            /**
+             * @description The text of the most recent Interaction counted by `unrespondedInboundCount`, truncated by the server. Present so a row holding exactly one waiting message can show the message instead of the number, which is the only case where a count is strictly less informative than the thing it counts.
+             *     Optional and independently nullable: absent means the producer does not publish it, null means there is nothing waiting or the body is not available. Never reconstruct it from the count, and never treat its absence as an empty message.
+             */
+            latestUnrespondedInboundPreview?: string | null;
         };
         InboxCounts: {
             total: number;
@@ -1241,6 +1500,11 @@ export interface components {
             createdAt: string;
             /** Format: date-time */
             readAt: string | null;
+            /**
+             * Format: date-time
+             * @description Optional until every reader publishes it; absent means this deployment does not support notification snooze, which is not the same as null. Null means never snoozed or already returned. A future value means the notification is withheld from the list until then. It is recipient state and never pauses the underlying WorkCycle.
+             */
+            snoozedUntil?: string | null;
             /** @description Optional authorized context for panel and banner presentation. Its absence is compatible with older producers; it must not be rebuilt from untrusted notification copy or realtime payloads. */
             displayContext?: components["schemas"]["NotificationDisplayContext"];
             /** @description Optional recipient-specific needs_attention metadata. Purpose is presentation context only; it never grants authorization or claims provider delivery. */
@@ -1675,6 +1939,19 @@ export interface components {
             /** Format: uuid */
             notificationId: string;
         };
+        /** @description Recipient-only. The notification envelope plus the time to surface the alert again, and no `expectedVersion`, because it writes no WorkCycle state. The three shared fields are repeated rather than composed: `NotificationCommand` is a published closed object that mark-read and dismiss already validate against, and refactoring it into a base reads as a breaking change to consumers for no gain here. */
+        SnoozeNotificationCommand: {
+            operationId: string;
+            clientOrgId: string;
+            /** Format: uuid */
+            notificationId: string;
+            /**
+             * Format: date-time
+             * @description When the notification returns to the panel. Must be in the future.
+             */
+            until: string;
+            reason?: string;
+        };
         /** @description Recipient-only bulk dismissal. Omit `cursor` on the first page so the server can establish the fixed action boundary. For later pages, pass the exact opaque cursor returned by the preceding response and a fresh operation ID. `clientOrgId` must match the selected rooftop header after normal authorization; neither value grants access. */
         DismissNotificationsCommand: {
             operationId: string;
@@ -1979,6 +2256,23 @@ export interface components {
                 dismissedAt: string | null;
             };
         };
+        /** @description Applied or idempotently replayed recipient-only notification snooze. `snoozedUntil` is the value now in force, which for a replay is the one the original request established rather than the one just submitted. */
+        NotificationSnoozeResult: {
+            data: {
+                operationId: string;
+                applied: boolean;
+                replayed: boolean;
+                /** Format: uuid */
+                notificationId: string;
+                /** Format: date-time */
+                snoozedUntil: string;
+                /**
+                 * Format: date-time
+                 * @description Unchanged by this command. Snoozing an alert is not reading it.
+                 */
+                readAt: string | null;
+            };
+        };
         /** @description Applied or idempotently replayed page of a recipient-only bulk dismissal. Counts cover this page, while `cutoff` and the cursor chain cover the fixed root snapshot. */
         DismissNotificationsResult: {
             data: {
@@ -2070,6 +2364,16 @@ export interface components {
                 "application/json": components["schemas"]["NotificationCommandResult"];
             };
         };
+        /** @description Applied or idempotently replayed recipient-only notification snooze. */
+        NotificationSnoozeApplied: {
+            headers: {
+                "x-correlation-id": components["headers"]["CorrelationId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["NotificationSnoozeResult"];
+            };
+        };
         /** @description Applied or idempotently replayed page of a fixed-snapshot notification dismissal. */
         DismissNotificationsApplied: {
             headers: {
@@ -2177,6 +2481,7 @@ export interface components {
         /** @description Authorized rooftop context. For commands this value must match body.clientOrgId; neither value is trusted without DASH-233 resolution. */
         ClientOrgId: string;
         ConversationId: string;
+        StaffUserId: string;
     };
     requestBodies: {
         BaseCommand: {
@@ -2249,6 +2554,11 @@ export interface components {
                 "application/json": components["schemas"]["NotificationCommand"];
             };
         };
+        SnoozeNotificationCommand: {
+            content: {
+                "application/json": components["schemas"]["SnoozeNotificationCommand"];
+            };
+        };
         DismissNotificationsCommand: {
             content: {
                 "application/json": components["schemas"]["DismissNotificationsCommand"];
@@ -2273,6 +2583,163 @@ export interface components {
 }
 export type $defs = Record<string, never>;
 export interface operations {
+    getInboxStaffWorkStatus: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Authorized rooftop context. For commands this value must match body.clientOrgId; neither value is trusted without DASH-233 resolution. */
+                "x-client-org-id": components["parameters"]["ClientOrgId"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Current self status and today's authoritative schedule window. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StaffWorkStatusSelfResult"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            500: components["responses"]["InternalError"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
+    setInboxStaffWorkStatus: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Authorized rooftop context. For commands this value must match body.clientOrgId; neither value is trusted without DASH-233 resolution. */
+                "x-client-org-id": components["parameters"]["ClientOrgId"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["StaffWorkStatusSelfCommand"];
+            };
+        };
+        responses: {
+            /** @description Applied self status with server-derived expiry. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StaffWorkStatusSelfResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            409: components["responses"]["Conflict"];
+            500: components["responses"]["InternalError"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
+    getInboxStaffSchedule: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Authorized rooftop context. For commands this value must match body.clientOrgId; neither value is trusted without DASH-233 resolution. */
+                "x-client-org-id": components["parameters"]["ClientOrgId"];
+            };
+            path: {
+                userId: components["parameters"]["StaffUserId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Manager-authorized staff schedule. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StaffScheduleResult"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            500: components["responses"]["InternalError"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
+    setInboxStaffSchedule: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Authorized rooftop context. For commands this value must match body.clientOrgId; neither value is trusted without DASH-233 resolution. */
+                "x-client-org-id": components["parameters"]["ClientOrgId"];
+            };
+            path: {
+                userId: components["parameters"]["StaffUserId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["StaffScheduleCommand"];
+            };
+        };
+        responses: {
+            /** @description Applied schedule snapshot. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StaffScheduleResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+            500: components["responses"]["InternalError"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
+    listInboxAssignmentCandidates: {
+        parameters: {
+            query?: {
+                cursor?: string;
+                limit?: number;
+            };
+            header: {
+                /** @description Authorized rooftop context. For commands this value must match body.clientOrgId; neither value is trusted without DASH-233 resolution. */
+                "x-client-org-id": components["parameters"]["ClientOrgId"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Bounded active rooftop staff page and effective work status. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StaffAssignmentCandidatesResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            500: components["responses"]["InternalError"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
     createInboxRealtimeSession: {
         parameters: {
             query?: never;
@@ -3021,6 +3488,28 @@ export interface operations {
             503: components["responses"]["ServiceUnavailable"];
         };
     };
+    snoozeInboxNotification: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Authorized rooftop context. For commands this value must match body.clientOrgId; neither value is trusted without DASH-233 resolution. */
+                "x-client-org-id": components["parameters"]["ClientOrgId"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: components["requestBodies"]["SnoozeNotificationCommand"];
+        responses: {
+            200: components["responses"]["NotificationSnoozeApplied"];
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+            500: components["responses"]["InternalError"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
     dismissInboxNotifications: {
         parameters: {
             query?: never;