@pam-ai/pam-ordo-contracts 3.15.1 → 3.16.0

package/dist/contract-invariants.d.ts

@@ -0,0 +1,134 @@
+import type { MentionRef, ResolveMentionResult, SearchInboxContactsParams } from './index.js';
+type Assert<T extends true> = T;
+type Accepts<Value, Shape> = Value extends Shape ? true : false;
+type Rejects<Value, Shape> = Value extends Shape ? false : true;
+/**
+ * `GET /v1/inbox/contacts` takes a query, a roState, or both — never neither,
+ * and never a roState that names no state.
+ */
+export type SearchInboxContactsInvariants = [
+    Assert<Accepts<{
+        query: 'ellery';
+    }, SearchInboxContactsParams>>,
+    Assert<Accepts<{
+        roState: ['OPEN'];
+    }, SearchInboxContactsParams>>,
+    Assert<Accepts<{
+        query: 'ellery';
+        roState: ['OPEN'];
+    }, SearchInboxContactsParams>>,
+    Assert<Accepts<{
+        roState: ['OPEN'];
+        limit: 25;
+    }, SearchInboxContactsParams>>,
+    Assert<Rejects<Record<string, never>, SearchInboxContactsParams>>,
+    Assert<Rejects<{
+        limit: 25;
+    }, SearchInboxContactsParams>>,
+    Assert<Rejects<{
+        roState: [];
+    }, SearchInboxContactsParams>>,
+    Assert<Rejects<{
+        roState: [];
+        limit: 25;
+    }, SearchInboxContactsParams>>
+];
+/** A Mention's two resolution fields move together, or are both absent. */
+export type MentionRefInvariants = [
+    Assert<Accepts<{
+        id: '1';
+        userId: 'u';
+        createdAt: 't';
+    }, MentionRef>>,
+    Assert<Accepts<{
+        id: '1';
+        userId: 'u';
+        createdAt: 't';
+        resolvedAt: null;
+        resolvedByUserId: null;
+    }, MentionRef>>,
+    Assert<Accepts<{
+        id: '1';
+        userId: 'u';
+        createdAt: 't';
+        resolvedAt: 't';
+        resolvedByUserId: 'u';
+    }, MentionRef>>,
+    Assert<Rejects<{
+        id: '1';
+        userId: 'u';
+        createdAt: 't';
+        resolvedAt: 't';
+        resolvedByUserId: null;
+    }, MentionRef>>,
+    Assert<Rejects<{
+        id: '1';
+        userId: 'u';
+        createdAt: 't';
+        resolvedAt: null;
+        resolvedByUserId: 'u';
+    }, MentionRef>>,
+    Assert<Rejects<{
+        id: '1';
+        userId: 'u';
+        createdAt: 't';
+        resolvedAt: 't';
+    }, MentionRef>>,
+    Assert<Rejects<{
+        id: '1';
+        userId: 'u';
+        createdAt: 't';
+        resolvedByUserId: 'u';
+    }, MentionRef>>
+];
+type Outcome = {
+    operationId: 'op';
+    applied: true;
+    replayed: false;
+    conversationId: 'c';
+    workCycleId: 'w';
+};
+/** Resolving something means it happened at a time. Zero says nothing either way. */
+export type ResolveMentionResultInvariants = [
+    Assert<Accepts<{
+        data: Outcome & {
+            resolvedCount: 3;
+            resolvedAt: 't';
+        };
+    }, ResolveMentionResult>>,
+    Assert<Accepts<{
+        data: Outcome & {
+            resolvedCount: 0;
+            resolvedAt: null;
+        };
+    }, ResolveMentionResult>>,
+    Assert<Accepts<{
+        data: Outcome & {
+            resolvedCount: 0;
+            resolvedAt: 't';
+        };
+    }, ResolveMentionResult>>,
+    Assert<Accepts<{
+        data: Outcome & {
+            resolvedCount: 0;
+        };
+    }, ResolveMentionResult>>,
+    Assert<Rejects<{
+        data: Outcome & {
+            resolvedCount: 3;
+            resolvedAt: null;
+        };
+    }, ResolveMentionResult>>,
+    Assert<Rejects<{
+        data: Outcome & {
+            resolvedCount: 3;
+        };
+    }, ResolveMentionResult>>
+];
+/**
+ * `resolvedAt` narrows the pairing, which is the reason a reader wants it: the
+ * resolver comes back a `string`, not a `string | null`.
+ */
+export declare function mentionResolver(mention: MentionRef): string | null;
+export {};
+//# sourceMappingURL=contract-invariants.d.ts.map

package/dist/contract-invariants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-invariants.d.ts","sourceRoot":"","sources":["../src/contract-invariants.ts"],"names":[],"mappings":"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"}

package/dist/contract-invariants.js

@@ -0,0 +1,8 @@
+/**
+ * `resolvedAt` narrows the pairing, which is the reason a reader wants it: the
+ * resolver comes back a `string`, not a `string | null`.
+ */
+export function mentionResolver(mention) {
+    return mention.resolvedAt ? mention.resolvedByUserId : null;
+}
+//# sourceMappingURL=contract-invariants.js.map

package/dist/contract-invariants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-invariants.js","sourceRoot":"","sources":["../src/contract-invariants.ts"],"names":[],"mappings":"AA2FA;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAmB;IACjD,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC"}

package/dist/generated.d.ts

@@ -84,6 +84,7 @@ export interface paths {
         /**
          * Search the rooftop's Customers to start an outbound Conversation
          * @description The outbound half of the Inbox. The Inbox itself is incoming-only, so a Conversation an advisor needs to START cannot be found in it: the Customer may have no thread at all, only an open repair order, or a thread another advisor owns. This searches the whole rooftop's Customers rather than the reader's own Conversations, and reports how each one already relates to them so the picker can say what opening it will do. Requires VIEW_CUSTOMER_DIRECTORY, which is a stronger grant than VIEW_OWN_INBOX: it exposes Customers the reader has never messaged. Contact detail is hydrated from the system that masters it, so a hydration gap degrades a field and never removes a Customer.
+         *     SEARCH OR BROWSE, AND ONE OF THEM IS REQUIRED. Supply a query, a roState, or both; supplying neither is a 400 rather than the rooftop's entire book of business, which is a page nobody asked for and the one request most likely to be slow.
          */
         get: operations["searchInboxContacts"];
         put?: never;
@@ -418,6 +419,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/inbox/commands/resolve-mention": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Mark the caller's outstanding Mentions on one WorkCycle dealt with */
+        post: operations["resolveInboxMentions"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/inbox/commands/dismiss-notification": {
         parameters: {
             query?: never;
@@ -827,6 +845,11 @@ export interface components {
             data: {
                 contacts: components["schemas"]["ContactRow"][];
             };
+            /** @description Present on a browse, which can exceed one page. A search is bounded by its own query and may omit this entirely, which is why the envelope is optional rather than required — an existing consumer that never reads it stays valid. */
+            meta?: {
+                /** @description Opaque keyset cursor, or null on the last page. */
+                nextCursor: string | null;
+            };
         };
         InboxListResponse: {
             data: {
@@ -883,7 +906,21 @@ export interface components {
             userId: string;
             /** Format: date-time */
             createdAt: string;
-        };
+            /**
+             * Format: date-time
+             * @description When the recipient marked this Mention dealt with, or null while it is still outstanding. A Mention was previously immutable and this is the one thing that may change about it: the words, the author and the recipient never do, and resolution records what the recipient did about it rather than editing what was said. Optional so a producer that predates DASH-322 is still valid; absent reads the same as null.
+             */
+            resolvedAt?: string | null;
+            /** @description Who resolved it, which is always the recipient — a Mention is recipient-scoped and nobody else can clear somebody's claim on their own attention. Published so a reader can tell a resolution apart from a Mention that was never raised, and so the two fields cannot disagree. Null exactly when resolvedAt is null. */
+            resolvedByUserId?: string | null;
+        } & (unknown | {
+            resolvedAt: null;
+            resolvedByUserId: null;
+        } | {
+            /** Format: date-time */
+            resolvedAt: string;
+            resolvedByUserId: string;
+        });
         VehicleRef: {
             sourceSystem: string;
             externalId: string;
@@ -934,6 +971,13 @@ export interface components {
             displayNumber: components["schemas"]["HydratedText"];
             status: components["schemas"]["HydratedText"];
             vehicle: components["schemas"]["VehicleRef"] | null;
+            /**
+             * Format: date-time
+             * @description When this repair order was opened.
+             *     ON THE REPAIR ORDER RATHER THAN ON THE ROW THAT CARRIES IT, because that is whose fact it is. Sorting Customers by "most recent open RO" was previously impossible at any cost: neither ContactRow nor this carried a single timestamp, so recency could not be derived by a client or asked for from the service.
+             *     Nullable, and null is not a defect: a source system that reports a repair order without an open date is publishing what it has, and a row must not disappear because an enrichment did not arrive. Rows with no openedAt sort last under RECENT_REPAIR_ORDER.
+             */
+            openedAt?: string | null;
             availability: components["schemas"]["Availability"];
         };
         ConversationDetailResponse: {
@@ -1420,6 +1464,42 @@ export interface components {
             /** Format: uuid */
             notificationId: 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.
+         *     It resolves only the CALLER's Mentions. A Mention is a claim on one person's attention, so nobody else can discharge it, and the command carries no recipient for that reason: the identity comes from the token.
+         *     Idempotent by operationId, and monotonic besides — resolving an already resolved Mention keeps the first resolvedAt rather than moving it, so a retry cannot rewrite when somebody dealt with something.
+         */
+        ResolveMentionCommand: {
+            operationId: string;
+            clientOrgId: string;
+            /** Format: uuid */
+            conversationId: string;
+            /** Format: uuid */
+            workCycleId: string;
+        };
+        ResolveMentionResult: {
+            /**
+             * @description RESOLVING SOMETHING MEANS IT HAPPENED AT A TIME. resolvedCount was required while resolvedAt stayed optional and nullable regardless of it, so `{ resolvedCount: 3, resolvedAt: null }` validated — three Mentions dealt with at no moment, which no reader can render and which the rows themselves cannot be in, since the pairing CHECK on conversation_mentions gives every resolved row a timestamp.
+             *     One-directional on purpose. A count of zero says nothing about resolvedAt: pressing Done twice, or replying and then pressing it, resolves nothing new and still has a real moment to report from the first time — and a caller who never had a Mention here has none. Both are honest answers, so zero admits a timestamp or null.
+             */
+            data: {
+                operationId: string;
+                applied: boolean;
+                replayed: boolean;
+                /** Format: uuid */
+                conversationId: string;
+                /** Format: uuid */
+                workCycleId: string;
+                /** @description How many of the caller's Mentions this resolved. Zero is a success, not a failure: it means they had none outstanding, which is the ordinary result of pressing Done twice or of replying first and then pressing it. */
+                resolvedCount: number;
+                /**
+                 * Format: date-time
+                 * @description When they were resolved. Set whenever anything is or was resolved; null only when the caller had nothing outstanding and nothing already resolved to report.
+                 */
+                resolvedAt?: string | null;
+            };
+        };
         BaseCommand: components["schemas"]["CommandEnvelope"];
         UserAssignmentTarget: {
             /**
@@ -1674,6 +1754,16 @@ export interface components {
                 "application/json": components["schemas"]["CustomerNoteCommandResult"];
             };
         };
+        /** @description Applied, replayed, or no-op Mention resolution result. */
+        MentionsResolved: {
+            headers: {
+                "x-correlation-id": components["headers"]["CorrelationId"];
+                [name: string]: unknown;
+            };
+            content: {
+                "application/json": components["schemas"]["ResolveMentionResult"];
+            };
+        };
         /** @description Applied, replayed, or monotonic no-op notification state result. */
         NotificationCommandApplied: {
             headers: {
@@ -1843,6 +1933,11 @@ export interface components {
                 "application/json": components["schemas"]["DeleteCustomerNoteCommand"];
             };
         };
+        ResolveMentionCommand: {
+            content: {
+                "application/json": components["schemas"]["ResolveMentionCommand"];
+            };
+        };
         NotificationCommand: {
             content: {
                 "application/json": components["schemas"]["NotificationCommand"];
@@ -2022,9 +2117,25 @@ export interface operations {
     };
     searchInboxContacts: {
         parameters: {
-            query: {
-                /** @description A name fragment, or a telephone number in any format. */
-                query: string;
+            query?: {
+                /**
+                 * @description A name fragment, or a telephone number in any format.
+                 *     OPTIONAL SINCE 3.16.0. It was required, which made the picker a search box and nothing else: an advisor who knew they wanted "whoever has a car in the shop" had to guess a name first. Omitting it now browses rather than searches, and roState is what makes that a useful list instead of the rooftop's entire book of business.
+                 */
+                query?: string;
+                /**
+                 * @description Narrow to Customers by the state of their car, using the same three values and the same meanings as the Conversation list: OPEN is a currently active repair order, CLOSED has had one and has none now, NONE never had one.
+                 *     This is what makes an omitted query answerable. "Everyone with a car in the shop right now" is a question an advisor actually has, and it is bounded by the service drive rather than by the size of the rooftop; "everyone" is not, which is why browsing without either a query or a roState is refused.
+                 *     An EMPTY ARRAY IS A 400, not an unfiltered browse. Presence is not a filter: `?roState=` names no state, so it would satisfy the at-least-one rule while asking for exactly the unbounded page that rule exists to refuse — and it is the shape a client reaches by serialising an empty selection rather than omitting the parameter, so it arrives by accident rather than by intent.
+                 */
+                roState?: ("OPEN" | "CLOSED" | "NONE")[];
+                /**
+                 * @description RECENT_REPAIR_ORDER puts the most recently opened repair order first, which is the order a service drive works in — the car that just arrived is the call that has not been made yet. NAME is the stable alphabetical order a search result wants.
+                 *     Defaults to NAME when a query is given and RECENT_REPAIR_ORDER when one is not, because a browse has no relevance to fall back on.
+                 */
+                sort?: "NAME" | "RECENT_REPAIR_ORDER";
+                /** @description Opaque keyset cursor. Present because a browse is not bounded the way a search is: a busy rooftop can carry several hundred open repair orders, and a limit alone would silently truncate the answer. */
+                cursor?: string;
                 /** @description Which side of the directory to read. MINE returns only Customers whose Conversation the reader owns; EVERYONE returns the rest. One set is always in the way of the other, so this is a switch rather than a filter. */
                 relationship?: "MINE" | "EVERYONE";
                 limit?: number;
@@ -2476,6 +2587,28 @@ export interface operations {
             503: components["responses"]["ServiceUnavailable"];
         };
     };
+    resolveInboxMentions: {
+        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"]["ResolveMentionCommand"];
+        responses: {
+            200: components["responses"]["MentionsResolved"];
+            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"];
+        };
+    };
     dismissInboxNotification: {
         parameters: {
             query?: never;