@pam-ai/pam-ordo-contracts 3.12.0 → 3.14.0

package/README.md

@@ -9,7 +9,7 @@ Pin consumers to an exact npm version:
 ```json
 {
   "dependencies": {
-    "@pam-ai/pam-ordo-contracts": "3.12.0"
+    "@pam-ai/pam-ordo-contracts": "3.13.0"
   }
 }
 ```
@@ -40,6 +40,12 @@ Conversation AI consumers import `ConversationAiSnapshotV1`. It is a
 replace-in-place snapshot keyed by rooftop and canonical Customer identity; it
 is not a source-of-truth Interaction record or a version-history API.
 
+Reach out consumers use `CreateInboxCustomerCommand` for an explicit
+create-only Customer request and `SendInboxMessageCommand` for the
+Conversation-aware Telnyx SMS operation. Directory reads, Customer creation,
+calls, and messages remain separate capabilities; a consumer must never infer
+one grant from another.
+
 The public npm artifact contains compiled TypeScript declarations, bundled OpenAPI, and shared fixtures. Consumers do not need GitHub repository credentials.
 
 New DASH-273 verification runners must use the canonical v2 manifest exported at

package/dist/generated.d.ts

@@ -111,6 +111,46 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/inbox/commands/create-customer": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create a new rooftop Customer for Reach out
+         * @description Creates a Customer only when the submitted mobile number is not already owned or quarantined at the selected rooftop. This is not an upsert: a number already owned by another Customer returns a conflict and is never silently merged. Ordo authorizes the User and delegates canonical Customer creation to pam-customers-service. Requires CREATE_CUSTOMER.
+         */
+        post: operations["createInboxCustomer"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/inbox/commands/send-message": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Send a Telnyx SMS and find or create its canonical Conversation
+         * @description Sends an outbound Customer SMS through the Ordo boundary. The caller names the canonical Customer, not a telephone number or provider. Ordo resolves or creates the Conversation, applies the explicit ownership disposition, and records the operation before delegating delivery to the Telnyx-only Comms path. An outbound-only Conversation may remain Closed with no active WorkCycle. Requires MESSAGE_CUSTOMER. Unknown provider outcomes are returned explicitly and are never blindly resent.
+         */
+        post: operations["sendInboxMessage"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/inbox/commands/assign": {
         parameters: {
             query?: never;
@@ -162,6 +202,46 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/inbox/commands/hold-pam": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Stop Pam answering this Customer's texts
+         * @description Places a hold on Pam's automatic text replies for this Conversation. The hold is a lease rather than a switch: the messaging authority expires it on its own, and the resulting expiry is published as PamAutoReplyV1.pausedUntil. Governs texting only and never inbound telephone calls. Requires HOLD_PAM_AUTO_REPLY. A Conversation with no messaging record — one provisioned from an accepted repair order, for instance — has nothing to hold and is refused rather than silently accepted.
+         */
+        post: operations["holdConversationPamAutoReply"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/inbox/commands/resume-pam": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Let Pam answer this Customer's texts again
+         * @description Releases a hold before its lease expires. Accepted on a Conversation that is already ACTIVE so a reader who has lost track of the lease is never stuck; the operation is idempotent by operationId like every other command here. Requires HOLD_PAM_AUTO_REPLY.
+         */
+        post: operations["resumeConversationPamAutoReply"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/inbox/commands/set-reminder": {
         parameters: {
             query?: never;
@@ -420,7 +500,7 @@ export interface components {
          * @description A single Ordo product capability. Capabilities are the only authorization vocabulary for Ordo surfaces. They are not a second half of the dashboard's resource/action permission model and do not divide the work with it. Resource permissions govern legacy dashboard surfaces and nothing else; capabilities govern Ordo surfaces and nothing else; neither is a fallback or an outer gate for the other. A same-named resource is a coincidence of vocabulary rather than a related grant, so REPAIR_ORDERS:READ says nothing about VIEW_OPEN_REPAIR_ORDERS and a User may hold either without the other. Resolved per rooftop by pam-permissions-service from the User's role, and enforced by pam-ordo-service. The distribution across personas is the approved capability contract in section 3.3 of the Ordo Product and Engineering Specification.
          * @enum {string}
          */
-        OrdoCapability: "VIEW_OWN_INBOX" | "VIEW_TEAM_INBOX" | "VIEW_CUSTOMER_DIRECTORY" | "CALL_CUSTOMER" | "SWITCH_ROOFTOP" | "VIEW_ANY_ROOFTOP_CONVERSATION" | "VIEW_OPEN_REPAIR_ORDERS" | "VIEW_ALL_OPEN_REPAIR_ORDERS" | "ASSIGN_OWNED_WORK" | "ASSIGN_ANY_WORK" | "CLOSE_OWNED_WORK" | "CLOSE_ANY_WORK" | "RESOLVE_NEEDS_ATTENTION" | "MENTION_USERS" | "ADD_CUSTOMER_NOTE" | "DELETE_ANY_CUSTOMER_NOTE";
+        OrdoCapability: "VIEW_OWN_INBOX" | "VIEW_TEAM_INBOX" | "VIEW_CUSTOMER_DIRECTORY" | "CALL_CUSTOMER" | "CREATE_CUSTOMER" | "MESSAGE_CUSTOMER" | "SWITCH_ROOFTOP" | "VIEW_ANY_ROOFTOP_CONVERSATION" | "VIEW_OPEN_REPAIR_ORDERS" | "VIEW_ALL_OPEN_REPAIR_ORDERS" | "ASSIGN_OWNED_WORK" | "ASSIGN_ANY_WORK" | "CLOSE_OWNED_WORK" | "CLOSE_ANY_WORK" | "RESOLVE_NEEDS_ATTENTION" | "MENTION_USERS" | "ADD_CUSTOMER_NOTE" | "DELETE_ANY_CUSTOMER_NOTE" | "HOLD_PAM_AUTO_REPLY";
         /** @description A configured target for one stable rooftop User identity. */
         InboxPolicyUserTargetV1: {
             /**
@@ -671,7 +751,7 @@ export interface components {
             channels: string[];
         };
         /** @enum {string} */
-        AvailableAction: "ASSIGN" | "SNOOZE" | "UNSNOOZE" | "SET_REMINDER" | "CLEAR_REMINDER" | "CLOSE" | "RESOLVE_ATTENTION" | "ADD_INTERNAL_COMMENT";
+        AvailableAction: "ASSIGN" | "SNOOZE" | "UNSNOOZE" | "SET_REMINDER" | "CLEAR_REMINDER" | "CLOSE" | "RESOLVE_ATTENTION" | "ADD_INTERNAL_COMMENT" | "SEND_MESSAGE" | "HOLD_PAM" | "RESUME_PAM";
         InboxRow: {
             /** Format: uuid */
             conversationId: string;
@@ -736,6 +816,8 @@ export interface components {
             openRepairOrder?: components["schemas"]["RepairOrderRef"] | null;
             /** @description The Customer's most recent Conversation, or null when they have none. Null is a fact about the Customer rather than a hydration gap. */
             conversationId: string | null;
+            /** @description Stable current owner identity used to render the colleague-owned Reach out choice. Optional during the additive rollout; null means the current WorkCycle is unassigned or there is no current WorkCycle. */
+            ownerUserId?: string | null;
             relationship: components["schemas"]["ContactRelationship"];
             availability: components["schemas"]["Availability"];
         };
@@ -768,9 +850,15 @@ export interface components {
             mentions?: components["schemas"]["MentionRef"][];
             /**
              * Format: uuid
-             * @description WorkCycle that was active when this Interaction was ingested, mirroring conversation_interaction_refs.work_cycle_id. Null is authoritative and means the Interaction belongs to no cycle, which is expected for RO transitions and other non-work events. Optional only to keep this addition a minor version; every producer emits it unconditionally and pam-ordo-service asserts that in its contract tests, so consumers should treat an absent field as a producer defect rather than a supported state. Consumers must never infer cycle membership from interaction timestamps.
+             * @description WorkCycle that was active when this Interaction was ingested, mirroring conversation_interaction_refs.work_cycle_id. Null is authoritative and means the Interaction belongs to no cycle. That is UNCOMMON rather than expected: an RO transition is attributed to the active cycle like any other activity, and because a cycle cannot be closed while a repair order is still linked and open, an RO_OPENED and its RO_CLOSED necessarily fall in the same cycle. A null here means no cycle was open when the Interaction arrived — an RO raised on a resolved Conversation, or the tested race where a Close commits first. Earlier revisions of this description said null was expected for RO transitions, which contradicted the sentence above it and led at least one consumer to treat a cycle-scoped read as unusable for repair-order events. Optional only to keep this addition a minor version; every producer emits it unconditionally and pam-ordo-service asserts that in its contract tests, so consumers should treat an absent field as a producer defect rather than a supported state. Consumers must never infer cycle membership from interaction timestamps.
              */
             workCycleId?: string | null;
+            /** @description The system that mastered this Interaction, mirroring conversation_interaction_refs.source_system — `pam_messaging_dynamodb` for SMS, `pam_call_metadata` for calls and voicemails, and null for anything Ordo authored itself, such as an internal comment. Published so a consumer can tell WHICH external authority governs a Conversation's messaging without inferring it from a channel string. */
+            sourceSystem?: string | null;
+            /** @description The exact native locator of the mastering record, when the source system uses one. Published for the same reason the column that stores it carries the comment "exact native locator, never reconstructed from a current phone alias": a consumer that rebuilds this key from the Customer's current telephone number addresses the wrong thread whenever that number has been corrected, and cannot address one at all when the number is withheld or failed to hydrate. */
+            sourceLocator?: components["schemas"]["SourceLocatorV1"] | null;
+            /** @description Present only on an Interaction of kind `ro_event`, and never null on one. Before this field a repair-order Interaction arrived with kind `ro_event`, a null body and nothing else, so a reader could tell that SOMETHING had happened to a repair order but neither which one nor whether it had opened or closed. */
+            repairOrder?: components["schemas"]["InteractionRepairOrderRefV1"] | null;
             sequenceNumber: number;
             kind: string;
             channel?: string | null;
@@ -797,6 +885,40 @@ export interface components {
             vin: components["schemas"]["HydratedText"];
             availability: components["schemas"]["Availability"];
         };
+        /** @description Where a mastered record actually lives, in the shape its own system uses. Today only the DynamoDB-backed messaging source supplies one; a source that addresses records by a plain identifier has none, and its Interactions carry null. */
+        SourceLocatorV1: {
+            /** @description The item-collection key. For `pam_messaging_dynamodb` this is `DEALER#{clientOrgId}#FROM#{customerE164}`, which is the same key the conversation-level state record uses, so a consumer holding it can address the Conversation's messaging state without deriving anything. */
+            partitionKey: string;
+            /** @description The individual record within the collection, when the source has one. */
+            sortKey?: string | null;
+        };
+        /** @description Which repair order moved, and which way. The vocabulary is the producer's own `ProducerRepairOrderTransitionV1.transition`; this republishes it on the read model rather than inventing a second one. */
+        InteractionRepairOrderRefV1: {
+            /** @enum {string} */
+            transition: "RO_OPENED" | "RO_CLOSED";
+            sourceSystem: string;
+            externalId: string;
+            /** @description The number a reader recognises. Hydrated, and therefore able to be unavailable on its own: the transition is known from the Interaction itself and stays readable when the Customer-facing number does not resolve. */
+            displayNumber: components["schemas"]["HydratedText"];
+        };
+        /**
+         * @description Whether Pam is answering this Customer's texts, and until when.
+         *     A LEASE RATHER THAN A SWITCH, because that is what the systems underneath actually implement: a hold placed by a human expires on its own after a fixed window and Pam resumes. Publishing a bare boolean would let a consumer draw "paused" over a Conversation Pam had already started answering again, which is worse than drawing nothing — the reader believes they own the thread.
+         *     SCOPED TO TEXT. Nothing here governs whether Pam answers an inbound telephone call. A consumer must not label this control with a word that claims more than texting.
+         */
+        PamAutoReplyV1: {
+            /**
+             * @description `UNKNOWN` is a real answer and not an error: the messaging authority may be unreachable, or the Conversation may have no messaging record at all, which is the normal state of one provisioned from an accepted repair order or a reach-out. A consumer must not render `UNKNOWN` as either of the other two.
+             * @enum {string}
+             */
+            state: "ACTIVE" | "PAUSED" | "UNKNOWN";
+            /**
+             * Format: date-time
+             * @description When a `PAUSED` hold lapses. Null while `ACTIVE`, and null on a `PAUSED` state whose authority does not expire holds. A consumer comparing this to the current time is computing the same thing the authority computes when it decides whether to suppress a reply.
+             */
+            pausedUntil?: string | null;
+            availability: components["schemas"]["Availability"];
+        };
         RepairOrderRef: {
             sourceSystem: string;
             externalId: string;
@@ -818,6 +940,8 @@ export interface components {
                 reminder: components["schemas"]["Reminder"] | null;
                 attention: components["schemas"]["AttentionSummary"] | null;
                 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"];
                 customerDisplayName: components["schemas"]["HydratedText"];
                 /** @description The Customer's contact telephone number, for placing an outbound call. Optional because no producer can supply it yet: Ordo stores a Customer reference and no payload, so this arrives with external Customer hydration. Absent and `{ value: null }` mean different things - absent is a producer that does not publish the field, null with an availability is a source that could not supply it. */
                 customerPhone?: components["schemas"]["HydratedText"];
@@ -1347,6 +1471,8 @@ export interface components {
             /** Format: uuid */
             throughInteractionRefId: string;
         };
+        /** @description Conversation-scoped rather than WorkCycle-scoped, and deliberately carrying no expectedVersion. Whether Pam answers a Customer's texts is a property of the Conversation's messaging, not of the work in front of an advisor: a Conversation with no open cycle still receives texts, and a hold that could only be placed while a cycle happened to be open would be unavailable in exactly the state — a resolved thread the Customer is still writing to — where a human most wants it. There is no version to guard either, because the authority underneath is a lease that expires on its own; the operationId carries idempotency, as it does for Customer notes. */
+        PamAutoReplyCommand: components["schemas"]["ConversationOperationEnvelope"];
         AddCustomerNoteCommand: components["schemas"]["ConversationOperationEnvelope"] & {
             body: string;
         };
@@ -1355,6 +1481,74 @@ export interface components {
             noteId: string;
             expectedNoteVersion: number;
         };
+        InboxCustomerIdentity: {
+            /** @constant */
+            sourceSystem: "pam_customers_service";
+            /** Format: uuid */
+            customerId: string;
+        };
+        /** @description Optional structured vehicle information for a newly created Customer. At least one field is required when the object is present. It creates Customer context only and never implies an open repair order. */
+        NewCustomerVehicleInput: {
+            year?: number;
+            make?: string;
+            model?: string;
+            vin?: string;
+        };
+        CreateInboxCustomerCommand: {
+            operationId: string;
+            clientOrgId: string;
+            firstName: string;
+            lastName?: string;
+            /** @description Normalized E.164 mobile number. */
+            mobileNumber: string;
+            vehicle?: components["schemas"]["NewCustomerVehicleInput"];
+        };
+        CreateInboxCustomerResult: {
+            data: {
+                operationId: string;
+                applied: boolean;
+                replayed: boolean;
+                customer: components["schemas"]["InboxCustomerIdentity"];
+                /** Format: uuid */
+                vehicleId: string | null;
+            };
+        };
+        /**
+         * @description PRESERVE leaves an existing owner unchanged. TAKE explicitly requests assignment to the authenticated User when an active WorkCycle exists; it never creates a WorkCycle merely to assign it.
+         * @enum {string}
+         */
+        OutboundMessageOwnershipDisposition: "PRESERVE" | "TAKE";
+        SendInboxMessageCommand: {
+            operationId: string;
+            clientOrgId: string;
+            customer: components["schemas"]["InboxCustomerIdentity"];
+            /**
+             * Format: uuid
+             * @description The Conversation observed by the caller, or null when contact search reported NONE. Ordo revalidates it against the canonical Customer and safely finds or creates the Conversation under its tenant lock.
+             */
+            conversationId: string | null;
+            body: string;
+            ownershipDisposition: components["schemas"]["OutboundMessageOwnershipDisposition"];
+        };
+        /** @enum {string} */
+        OutboundMessageDeliveryState: "PENDING" | "ACCEPTED" | "FAILED" | "UNKNOWN";
+        SendInboxMessageResult: {
+            data: {
+                operationId: string;
+                applied: boolean;
+                replayed: boolean;
+                /** Format: uuid */
+                conversationId: string;
+                conversationCreated: boolean;
+                /** Format: uuid */
+                deliveryId: string;
+                deliveryState: components["schemas"]["OutboundMessageDeliveryState"];
+                /** Format: uuid */
+                workCycleId: string | null;
+                resultingVersion: number | null;
+                ownershipDisposition: components["schemas"]["OutboundMessageOwnershipDisposition"];
+            };
+        };
         CommandResult: {
             data: {
                 operationId: string;
@@ -1482,6 +1676,26 @@ export interface components {
                 "application/json": components["schemas"]["NotificationCommandResult"];
             };
         };
+        /** @description Created or idempotently replayed canonical Customer result. */
+        InboxCustomerCreated: {
+            headers: {
+                "x-correlation-id": components["headers"]["CorrelationId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["CreateInboxCustomerResult"];
+            };
+        };
+        /** @description Submitted or idempotently replayed outbound-message result. */
+        InboxMessageSubmitted: {
+            headers: {
+                "x-correlation-id": components["headers"]["CorrelationId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["SendInboxMessageResult"];
+            };
+        };
         /** @description Invalid input. */
         BadRequest: {
             headers: {
@@ -1606,6 +1820,11 @@ export interface components {
                 "application/json": components["schemas"]["AdvanceReadCursorCommand"];
             };
         };
+        PamAutoReplyCommand: {
+            content: {
+                "application/json": components["schemas"]["PamAutoReplyCommand"];
+            };
+        };
         AddCustomerNoteCommand: {
             content: {
                 "application/json": components["schemas"]["AddCustomerNoteCommand"];
@@ -1621,6 +1840,16 @@ export interface components {
                 "application/json": components["schemas"]["NotificationCommand"];
             };
         };
+        CreateInboxCustomerCommand: {
+            content: {
+                "application/json": components["schemas"]["CreateInboxCustomerCommand"];
+            };
+        };
+        SendInboxMessageCommand: {
+            content: {
+                "application/json": components["schemas"]["SendInboxMessageCommand"];
+            };
+        };
     };
     headers: {
         /** @description Stable request correlation identifier. */
@@ -1852,6 +2081,49 @@ export interface operations {
             503: components["responses"]["ServiceUnavailable"];
         };
     };
+    createInboxCustomer: {
+        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"]["CreateInboxCustomerCommand"];
+        responses: {
+            200: components["responses"]["InboxCustomerCreated"];
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            409: components["responses"]["Conflict"];
+            500: components["responses"]["InternalError"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
+    sendInboxMessage: {
+        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"]["SendInboxMessageCommand"];
+        responses: {
+            200: components["responses"]["InboxMessageSubmitted"];
+            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"];
+        };
+    };
     assignConversation: {
         parameters: {
             query?: never;
@@ -1921,6 +2193,52 @@ export interface operations {
             503: components["responses"]["ServiceUnavailable"];
         };
     };
+    holdConversationPamAutoReply: {
+        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"]["PamAutoReplyCommand"];
+        responses: {
+            200: components["responses"]["CommandApplied"];
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+            500: components["responses"]["InternalError"];
+            501: components["responses"]["NotImplemented"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
+    resumeConversationPamAutoReply: {
+        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"]["PamAutoReplyCommand"];
+        responses: {
+            200: components["responses"]["CommandApplied"];
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: components["responses"]["Conflict"];
+            500: components["responses"]["InternalError"];
+            501: components["responses"]["NotImplemented"];
+            503: components["responses"]["ServiceUnavailable"];
+        };
+    };
     setConversationReminder: {
         parameters: {
             query?: never;