@kohost/api-client 7.7.1 → 7.8.0

package/dist/schemas/ticket.d.ts

@@ -49,7 +49,7 @@ export declare const ticketSchema: {
                     };
                     readonly discriminator: {
                         readonly type: "string";
-                        readonly enum: readonly ["message", "opened", "assigned", "rated", "scheduled", "collaboratorAdded", "collaboratorRemoved", "statusChanged", "priorityChanged", "scheduleDateChanged", "locationChanged", "nudged"];
+                        readonly enum: readonly ["message", "opened", "assigned", "rated", "scheduled", "collaboratorAdded", "collaboratorRemoved", "statusChanged", "priorityChanged", "scheduleDateChanged", "locationChanged", "nudged", "approvalRequested", "approvalApproved", "approvalDenied", "workScheduled", "workRescheduled", "workCanceled", "costRecorded", "costPriceChanged"];
                         readonly default: "message";
                         readonly description: "The discriminator of the message.";
                     };
@@ -579,7 +579,373 @@ export declare const ticketSchema: {
             readonly type: "integer";
             readonly minimum: 0;
             readonly default: 0;
-            readonly description: "Server-derived count of transitions back to \"open\" that followed a solve/close. reopenCount > 0 answers \"was this ticket ever reopened?\" in O(1); maintained at the repository layer across every status-write path. Never set by clients.";
+            readonly description: 'Server-derived count of transitions back to "open" that followed a solve/close. reopenCount > 0 answers "was this ticket ever reopened?" in O(1); maintained at the repository layer across every status-write path. Never set by clients.';
+        };
+        readonly work: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly description: "Work items scheduled on the ticket: who is coming, when, and what for. Many per ticket, including repeat visits by the same performer. Carries no lifecycle status — the conversation log is the history and a past-dated entry is implicitly done. Never redacted; vendor identity is already public in assignment.";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "performer", "date"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly description: "The ID of the work item.";
+                    };
+                    readonly performer: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["id", "discriminator", "name"];
+                        readonly description: string;
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                                readonly description: "The ID of the performer.";
+                            };
+                            readonly discriminator: {
+                                readonly type: "string";
+                                readonly enum: readonly ["vendor", "user"];
+                                readonly description: "The discriminator of the performer.";
+                            };
+                            readonly name: {
+                                readonly type: "string";
+                                readonly description: "The performer's name, denormalized at schedule time for rendering.";
+                            };
+                        };
+                    };
+                    readonly date: {
+                        readonly type: "string";
+                        readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+                        readonly description: "The calendar date of the visit as YYYY-MM-DD, read in the property's timezone.";
+                    };
+                    readonly time: {
+                        readonly type: readonly ["string", "null"];
+                        readonly pattern: "^([01]\\d|2[0-3]):[0-5]\\d$";
+                        readonly default: null;
+                        readonly description: string;
+                    };
+                    readonly description: {
+                        readonly type: readonly ["string", "null"];
+                        readonly default: null;
+                        readonly description: string;
+                    };
+                    readonly scheduledBy: {
+                        readonly type: readonly ["string", "null"];
+                        readonly default: null;
+                        readonly description: "The ID of the user whose write created this work item. Null when the write was not user-attributable.";
+                    };
+                    readonly scheduledAt: {
+                        readonly $ref: "definitions.json#/definitions/date";
+                        readonly description: "When the work item was created.";
+                    };
+                    readonly noCharge: {
+                        readonly type: readonly ["object", "null"];
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["setBy", "setAt"];
+                        readonly default: null;
+                        readonly description: string;
+                        readonly properties: {
+                            readonly setBy: {
+                                readonly type: readonly ["string", "null"];
+                                readonly default: null;
+                                readonly description: string;
+                            };
+                            readonly setAt: {
+                                readonly $ref: "definitions.json#/definitions/date";
+                                readonly description: "When the disposition was set.";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly costs: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly description: "Cost line items recorded on the ticket. Each entry stores the customer price and the vendor cost side by side and keeps them independent: the price is seeded from the estimate and markup at recording, and nothing about the vendor side moves it afterwards. Every entry arrives as either the full vendor shape or the redacted price-only shape depending on whether the viewer may see the cost split.";
+            readonly items: {
+                readonly oneOf: readonly [{
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["id", "description", "currency", "price", "estimate", "markup"];
+                    readonly properties: {
+                        readonly id: {
+                            readonly type: "string";
+                            readonly description: "The ID of the cost entry.";
+                        };
+                        readonly description: {
+                            readonly type: "string";
+                            readonly description: "What the cost covers.";
+                        };
+                        readonly currency: {
+                            readonly type: "string";
+                            readonly default: "USD";
+                            readonly description: "ISO 4217 currency code of the entry's amounts.";
+                        };
+                        readonly price: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["amount", "recordedBy", "recordedAt"];
+                            readonly description: string;
+                            readonly properties: {
+                                readonly amount: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                    readonly description: "Customer price in integer cents.";
+                                };
+                                readonly recordedBy: {
+                                    readonly type: "string";
+                                    readonly description: "The ID of the user who recorded the amount.";
+                                };
+                                readonly recordedAt: {
+                                    readonly $ref: "definitions.json#/definitions/date";
+                                    readonly description: "When the amount was recorded.";
+                                };
+                            };
+                        };
+                        readonly estimate: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["amount", "recordedBy", "recordedAt"];
+                            readonly description: "The vendor cost estimate phase of the entry.";
+                            readonly properties: {
+                                readonly amount: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                    readonly description: "Vendor cost estimate in integer cents.";
+                                };
+                                readonly recordedBy: {
+                                    readonly type: "string";
+                                    readonly description: "The ID of the user who recorded the amount.";
+                                };
+                                readonly recordedAt: {
+                                    readonly $ref: "definitions.json#/definitions/date";
+                                    readonly description: "When the amount was recorded.";
+                                };
+                            };
+                        };
+                        readonly actual: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["amount", "recordedBy", "recordedAt"];
+                            readonly description: "The actual vendor cost phase of the entry, recorded after the work.";
+                            readonly properties: {
+                                readonly amount: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                    readonly description: "Actual vendor cost in integer cents.";
+                                };
+                                readonly recordedBy: {
+                                    readonly type: "string";
+                                    readonly description: "The ID of the user who recorded the amount.";
+                                };
+                                readonly recordedAt: {
+                                    readonly $ref: "definitions.json#/definitions/date";
+                                    readonly description: "When the amount was recorded.";
+                                };
+                            };
+                        };
+                        readonly markup: {
+                            readonly type: "object";
+                            readonly additionalProperties: false;
+                            readonly required: readonly ["percent"];
+                            readonly properties: {
+                                readonly percent: {
+                                    readonly type: "number";
+                                    readonly minimum: 0;
+                                    readonly description: string;
+                                };
+                                readonly custom: {
+                                    readonly type: "boolean";
+                                    readonly default: false;
+                                    readonly description: "Whether the percent was manually overridden rather than keyed from the configured markup tiers. Custom percents are never re-keyed on estimate edits.";
+                                };
+                            };
+                        };
+                        readonly vendorInvoices: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly $ref: "mediaFile.json";
+                            };
+                            readonly default: readonly [];
+                            readonly description: string;
+                        };
+                        readonly vendorInvoiceNumber: {
+                            readonly type: readonly ["string", "null"];
+                            readonly default: null;
+                            readonly description: string;
+                        };
+                        readonly vendorId: {
+                            readonly type: readonly ["string", "null"];
+                            readonly default: null;
+                            readonly description: string;
+                        };
+                        readonly workItemId: {
+                            readonly type: readonly ["string", "null"];
+                            readonly default: null;
+                            readonly description: string;
+                        };
+                        readonly categoryId: {
+                            readonly type: readonly ["string", "null"];
+                            readonly default: null;
+                            readonly description: string;
+                        };
+                        readonly billId: {
+                            readonly type: readonly ["string", "null"];
+                            readonly default: null;
+                            readonly description: string;
+                        };
+                        readonly writtenOff: {
+                            readonly type: "boolean";
+                            readonly default: false;
+                            readonly description: string;
+                        };
+                        readonly billingReview: {
+                            readonly type: "array";
+                            readonly default: readonly [];
+                            readonly description: string;
+                            readonly items: {
+                                readonly type: "object";
+                                readonly additionalProperties: false;
+                                readonly required: readonly ["id", "action", "performedAt"];
+                                readonly properties: {
+                                    readonly id: {
+                                        readonly type: "string";
+                                        readonly description: "The ID of the billing review entry.";
+                                    };
+                                    readonly action: {
+                                        readonly type: "string";
+                                        readonly enum: readonly ["writtenOff", "reinstated", "divergenceAcknowledged"];
+                                    };
+                                    readonly performedBy: {
+                                        readonly type: readonly ["string", "null"];
+                                        readonly default: null;
+                                        readonly description: string;
+                                    };
+                                    readonly performedAt: {
+                                        readonly $ref: "definitions.json#/definitions/date";
+                                        readonly description: "When the entry was appended.";
+                                    };
+                                    readonly note: {
+                                        readonly type: readonly ["string", "null"];
+                                        readonly default: null;
+                                        readonly description: "Free-text rationale for the action.";
+                                    };
+                                    readonly billedAmount: {
+                                        readonly type: "integer";
+                                        readonly minimum: 0;
+                                        readonly description: string;
+                                    };
+                                    readonly priceAmount: {
+                                        readonly type: "integer";
+                                        readonly minimum: 0;
+                                        readonly description: string;
+                                    };
+                                };
+                            };
+                        };
+                    };
+                }, {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["id", "description", "currency", "price"];
+                    readonly properties: {
+                        readonly id: {
+                            readonly type: "string";
+                            readonly description: "The ID of the cost entry.";
+                        };
+                        readonly description: {
+                            readonly type: "string";
+                            readonly description: "What the cost covers.";
+                        };
+                        readonly currency: {
+                            readonly type: "string";
+                            readonly default: "USD";
+                            readonly description: "ISO 4217 currency code of the entry's amounts.";
+                        };
+                        readonly price: {
+                            readonly type: "integer";
+                            readonly minimum: 0;
+                            readonly description: string;
+                        };
+                    };
+                }];
+            };
+        };
+        readonly approvals: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly description: "Approval request history for the ticket. At most one pending record at a time; records are immutable once decided (enforced by use cases).";
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["id", "amount", "approverUserIds", "status", "requestedAt"];
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly description: "The ID of the approval record.";
+                    };
+                    readonly amount: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                        readonly description: "The ticket's customer price total in integer cents, frozen at request time.";
+                    };
+                    readonly approverUserIds: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "The effective approver set for this request, frozen at request time.";
+                    };
+                    readonly status: {
+                        readonly type: "string";
+                        readonly enum: readonly ["pending", "approved", "denied"];
+                        readonly default: "pending";
+                    };
+                    readonly requestedAt: {
+                        readonly $ref: "definitions.json#/definitions/date";
+                        readonly description: "When the approval was requested.";
+                    };
+                    readonly requestedBy: {
+                        readonly type: readonly ["string", "null"];
+                        readonly default: null;
+                        readonly description: "The ID of the user whose write created this request, frozen at request time. Null when the write was not user-attributable.";
+                    };
+                    readonly decidedBy: {
+                        readonly type: readonly ["string", "null"];
+                        readonly default: null;
+                        readonly description: "The ID of the approver who decided the request.";
+                    };
+                    readonly decidedAt: {
+                        readonly anyOf: readonly [{
+                            readonly $ref: "definitions.json#/definitions/date";
+                        }, {
+                            readonly type: "null";
+                        }];
+                        readonly default: null;
+                        readonly description: "When the request was decided.";
+                    };
+                    readonly comment: {
+                        readonly type: readonly ["string", "null"];
+                        readonly default: null;
+                        readonly description: "The decider's comment. Required on deny, optional on approve (enforced by use cases).";
+                    };
+                };
+            };
+        };
+        readonly dneAmount: {
+            readonly type: readonly ["integer", "null"];
+            readonly minimum: 0;
+            readonly description: "The effective do-not-exceed amount in integer cents the approval gate compares against, resolved per read from the organization and property Concierge settings. Never stored on the document and never set by clients; absent on payloads where it could not be resolved. Viewer-independent: the DNE is the customer's own contract term, so org-side viewers see it.";
+        };
+        readonly approvalState: {
+            readonly type: "string";
+            readonly enum: readonly ["clear", "awaitingApproval", "denied"];
+            readonly default: "clear";
+            readonly description: "Server-maintained denormalization of the approval gate, updated on every cost or approval write (reopenCount pattern) so queue filters get O(1) access. Never set by clients.";
         };
         readonly tags: {
             readonly type: "array";
@@ -620,7 +986,7 @@ export declare const ticketSchema: {
         };
     };
 };
-export type TicketSchema = FromSchema<typeof ticketSchema, {
+type TicketSchemaBase = FromSchema<typeof ticketSchema, {
     references: [typeof defs, typeof mediaFileSchema];
     deserialize: [
         {
@@ -631,3 +997,15 @@ export type TicketSchema = FromSchema<typeof ticketSchema, {
         }
     ];
 }>;
+/** A stored cost entry: the full shape, with `price`, `estimate` and `markup`. */
+export type TicketCostEntry = Extract<NonNullable<TicketSchemaBase["costs"]>[number], {
+    estimate: unknown;
+}>;
+/** One scheduled performance of work on a ticket. */
+export type TicketWorkItem = NonNullable<TicketSchemaBase["work"]>[number];
+/** One append-only billing review entry on a stored cost entry. */
+export type TicketCostBillingReviewEntry = NonNullable<TicketCostEntry["billingReview"]>[number];
+export type TicketSchema = Omit<TicketSchemaBase, "costs"> & {
+    costs?: TicketCostEntry[];
+};
+export {};