@pam-ai/pam-ordo-contracts 3.19.0 → 3.21.0

package/README.md

@@ -9,7 +9,7 @@ Pin consumers to an exact npm version:
 ```json
 {
   "dependencies": {
-    "@pam-ai/pam-ordo-contracts": "3.13.0"
+    "@pam-ai/pam-ordo-contracts": "3.20.0"
   }
 }
 ```
@@ -18,13 +18,34 @@ Pin consumers to an exact npm version:
 import type {
   ConversationDetailResponse,
   InboxListResponse,
+  NotificationDisplayContext,
   NotificationListResponse,
+  DismissNotificationsCommand,
+  DismissNotificationsResult,
   CommandResult,
   ErrorEnvelope,
   paths,
 } from '@pam-ai/pam-ordo-contracts';
 ```
 
+Notification reads may include the optional `InboxNotification.displayContext`.
+When present, `NotificationDisplayContext` always contains `customerName`,
+`actorName`, `repairOrderNumber`, `commentExcerpt`, and `context`; the latter
+four values are either an authorized `HydratedText` or `null` when that context
+is not applicable. A relevant but unavailable or withheld source is represented
+by `HydratedText.availability`, not by `null`. Consumers should render
+availability and use the existing `title`/`body` fallback when the context
+object is absent.
+
+`POST /v1/inbox/commands/dismiss-notifications` implements Clear all for the
+authenticated recipient. The initial `DismissNotificationsCommand` omits
+`cursor`; the server fixes the action boundary and returns a stable informational
+`cutoff`. Each `nextCursor` continuation uses a new operation ID, and repeating
+the same request replays its `DismissNotificationsResult`. Cursors are opaque,
+recipient/rooftop-bound, and `nextCursor: null` means the fixed snapshot is
+complete. The response counts are for that page only; notifications created
+after the cutoff remain eligible for a later read.
+
 FIFO producers also import `ProducerCommandV1` plus the deterministic
 `producerMessageGroupId`, `producerMessageDeduplicationId`, and
 `producerMessageAttributes` helpers. The helpers keep every producer aligned

package/dist/generated.d.ts

@@ -501,6 +501,27 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/inbox/commands/dismiss-notifications": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Dismiss visible recipient-owned notifications through a fixed snapshot
+         * @description Dismisses the authenticated recipient's visible notifications for the selected rooftop and marks unread notifications read. The first request omits `cursor`; the server establishes the action boundary and returns its informational RFC3339 `cutoff`. A continuation submits the opaque `nextCursor` from the preceding response with a new `operationId`.
+         *     Continuation cursors are bound to the root operation, authenticated recipient, selected rooftop, and server cutoff. Clients must not decode, construct, or reuse a cursor outside the exact operation chain. Each page is independently idempotent: repeating the same request with the same operation ID replays that page's receipt, while reusing an operation ID with a different request is a conflict. `dismissedCount` and `readCount` describe state transitions in this page only. `nextCursor: null` means the fixed snapshot is complete; notifications created after the cutoff are not consumed by this operation.
+         */
+        post: operations["dismissInboxNotifications"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -522,6 +543,62 @@ export interface components {
             value?: string | null;
             availability: components["schemas"]["Availability"];
         };
+        /** @description A validated current-source Conversation AI assessment. This is separate from the cumulative Conversation snapshot: a null model result is omitted, meaning that this source did not provide qualifying evidence. The category remains the outer category-observed payload field so consumers cannot mistake provenance for a category. */
+        ConversationAiAssessmentV1: {
+            reason: string;
+            /** Format: date-time */
+            detectedAt: string;
+            model: string;
+            promptVersion: string;
+            confidence: number;
+        };
+        /** @description Current actionable Attention evidence exposed by a read. The source category pairs this assessment with its reason even when an AttentionCycle contains legacy evidence from another category. The reason is HydratedText so a source or enrichment outage is explicit; detectedAt is model provenance and is not the AttentionCycle lifecycle time or the source interaction occurredAt. This object never represents cumulative snapshot categories and never reopens an AttentionCycle by itself. */
+        AttentionAssessmentV1: {
+            category: string;
+            reason: components["schemas"]["HydratedText"];
+            /** Format: date-time */
+            detectedAt: string;
+            model: string;
+            promptVersion: string;
+            confidence: number;
+        };
+        /** @description A materially notified manager proven by a durable SQL notification row. notifiedAt is the SQL handoff/materialization time, not provider delivery, handset receipt, or a seen timestamp. User identity and display name are presentation data, not an authorization grant; authorization is evaluated by the service for the requesting user. */
+        AttentionNotifiedManagerV1: {
+            userId: string;
+            displayName: components["schemas"]["HydratedText"];
+            /** Format: date-time */
+            notifiedAt: string;
+        };
+        /** @description A hydrated User actor for an Attention history event. Null actor is used for source or system events without a User identity. Actor identity is provenance only and does not authorize the viewer. */
+        AttentionHistoryActorV1: {
+            userId: string;
+            displayName: components["schemas"]["HydratedText"];
+        };
+        /** @description One bounded, append-only AttentionCycle history event selected for a Conversation detail read. actorType deliberately distinguishes an explicit User resolution from the canonical WorkCycle-close resolution; work_cycle_close is not manager handling. occurredAt is the authoritative event business time. */
+        AttentionHistoryEventV1: {
+            /** Format: uuid */
+            id: string;
+            /** Format: uuid */
+            attentionCycleId: string;
+            /** Format: uuid */
+            workCycleId: string;
+            category: string;
+            /** @enum {string} */
+            eventType: "opened" | "evidence_added" | "recipients_resolved" | "acknowledged" | "resolution_prompted" | "resolved" | "corrected";
+            /** @enum {string} */
+            actorType: "user" | "system" | "source" | "work_cycle_close";
+            /** Format: date-time */
+            occurredAt: string;
+            actor: components["schemas"]["AttentionHistoryActorV1"] | null;
+        } & (unknown & unknown);
+        /** @description Recipient-specific metadata for a needs_attention notification. ACTIONABLE is the configured manager alert; INFORMATIONAL identifies a current owner notice and does not add that owner to attention_cycle_recipients. This context is presentation metadata only: purpose, category, reason, and manager rows never grant authorization or claim provider delivery. */
+        AttentionNotificationContextV1: {
+            /** @enum {string} */
+            purpose: "ACTIONABLE" | "INFORMATIONAL";
+            category?: string;
+            reason?: components["schemas"]["HydratedText"];
+            notifiedManagers?: components["schemas"]["AttentionNotifiedManagerV1"][];
+        } & unknown;
         HydratedStringList: {
             value: string[] | null;
             availability: components["schemas"]["Availability"];
@@ -550,6 +627,10 @@ export interface components {
             /** Format: date-time */
             openedAt: string;
             version: number;
+            /** @description Optional current-source evidence for this actionable cycle. This is deliberately separate from cumulative Conversation AI categories and does not reopen a cycle. */
+            assessment?: components["schemas"]["AttentionAssessmentV1"];
+            /** @description Manager identities with a durable SQL notification row for this cycle. This list is not provider-delivery or seen-state evidence and does not grant authorization. */
+            notifiedManagers?: components["schemas"]["AttentionNotifiedManagerV1"][];
         };
         /** @description Derived read-time Overdue presentation. It is never a mutable lifecycle flag. */
         OverdueSummary: {
@@ -1061,6 +1142,8 @@ export interface components {
                 owner: components["schemas"]["Owner"] | null;
                 reminder: components["schemas"]["Reminder"] | null;
                 attention: components["schemas"]["AttentionSummary"] | null;
+                /** @description Optional bounded, selected-cycle Attention history. Events preserve actorType so an explicit User resolution is not confused with canonical work-cycle closure. */
+                attentionEvents?: components["schemas"]["AttentionHistoryEventV1"][];
                 overdue: components["schemas"]["OverdueSummary"];
                 /** @description Optional so this addition stays a minor version. An absent field means this deployment does not resolve the messaging authority at all, which a consumer should treat the same way it treats `UNKNOWN` — draw no control rather than an inert one. */
                 pamAutoReply?: components["schemas"]["PamAutoReplyV1"];
@@ -1126,6 +1209,18 @@ export interface components {
             createdAt: string;
             /** Format: date-time */
             readAt: 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. */
+            attentionContext?: components["schemas"]["AttentionNotificationContextV1"];
+        } & unknown;
+        /** @description Authorized, bounded presentation context for one recipient notification. Every key is present when the object is returned. A `null` value means that context is not applicable to this notification. When a relevant source is unavailable or withholds a value, return a HydratedText with its availability state instead; neither form is an authorization grant. `customerName` remains a HydratedText object so its availability state is explicit. */
+        NotificationDisplayContext: {
+            customerName: components["schemas"]["HydratedText"];
+            actorName: components["schemas"]["HydratedText"] | null;
+            repairOrderNumber: components["schemas"]["HydratedText"] | null;
+            commentExcerpt: components["schemas"]["HydratedText"] | null;
+            context: components["schemas"]["HydratedText"] | null;
         };
         NotificationListResponse: {
             data: {
@@ -1352,6 +1447,8 @@ export interface components {
         ProducerAttentionCategoryObservedPayloadV1: {
             category: string;
             sourceInteraction: components["schemas"]["ProducerSourceInteractionIdentityV1"];
+            /** @description Optional same-call current-source assessment. It is omitted when the model abstains; consumers must not derive fresh Attention from cumulative snapshot categories. */
+            assessment?: components["schemas"]["ConversationAiAssessmentV1"];
         };
         ProducerReminderFirePayloadV1: {
             /** Format: uuid */
@@ -1534,6 +1631,13 @@ export interface components {
             /** Format: uuid */
             notificationId: 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;
+            clientOrgId: string;
+            /** @description Opaque continuation cursor from the immediately preceding page. */
+            cursor?: string;
+        };
         /**
          * @description Mark the caller's outstanding Mentions on one WorkCycle dealt with.
          *     CONVERSATION-WIDE, NOT PER-MENTION, and the shape is the point. A recipient does not think in Mentions; they think "I have handled this thread". Two colleagues naming the same person in one exchange raises two Mentions, and clearing one of them would leave the row on the Mentions list with nothing on screen to explain why.
@@ -1831,6 +1935,25 @@ export interface components {
                 dismissedAt: 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: {
+                operationId: string;
+                applied: boolean;
+                replayed: boolean;
+                /** @description Notifications transitioned to dismissed in this page. */
+                dismissedCount: number;
+                /** @description Previously unread notifications transitioned to read in this page. */
+                readCount: number;
+                /**
+                 * Format: date-time
+                 * @description Informational RFC3339 action boundary established by the initial request.
+                 */
+                cutoff: string;
+                /** @description Opaque continuation cursor, or null when the fixed snapshot is complete. */
+                nextCursor: string | null;
+            };
+        };
         ErrorEnvelope: {
             error: {
                 code: string;
@@ -1903,6 +2026,16 @@ export interface components {
                 "application/json": components["schemas"]["NotificationCommandResult"];
             };
         };
+        /** @description Applied or idempotently replayed page of a fixed-snapshot notification dismissal. */
+        DismissNotificationsApplied: {
+            headers: {
+                "x-correlation-id": components["headers"]["CorrelationId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["DismissNotificationsResult"];
+            };
+        };
         /** @description Created or idempotently replayed canonical Customer result. */
         InboxCustomerCreated: {
             headers: {
@@ -2072,6 +2205,11 @@ export interface components {
                 "application/json": components["schemas"]["NotificationCommand"];
             };
         };
+        DismissNotificationsCommand: {
+            content: {
+                "application/json": components["schemas"]["DismissNotificationsCommand"];
+            };
+        };
         CreateInboxCustomerCommand: {
             content: {
                 "application/json": components["schemas"]["CreateInboxCustomerCommand"];
@@ -2839,5 +2977,27 @@ export interface operations {
             503: components["responses"]["ServiceUnavailable"];
         };
     };
+    dismissInboxNotifications: {
+        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"]["DismissNotificationsCommand"];
+        responses: {
+            200: components["responses"]["DismissNotificationsApplied"];
+            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"];
+        };
+    };
 }
 //# sourceMappingURL=generated.d.ts.map