@kohost/api-client 7.15.0 → 7.17.0

package/dist/schemas/bill.d.ts

@@ -120,6 +120,16 @@ export declare const billSchema: {
                             readonly default: null;
                             readonly description: string;
                         };
+                        readonly propertyId: {
+                            readonly type: readonly ["string", "null"];
+                            readonly default: null;
+                            readonly description: string;
+                        };
+                        readonly ticketNumber: {
+                            readonly type: readonly ["string", "null"];
+                            readonly default: null;
+                            readonly description: string;
+                        };
                         readonly categoryId: {
                             readonly type: readonly ["string", "null"];
                             readonly default: null;
@@ -151,6 +161,21 @@ export declare const billSchema: {
                             readonly default: null;
                             readonly description: string;
                         };
+                        readonly vendorCost: {
+                            readonly type: readonly ["integer", "null"];
+                            readonly default: null;
+                            readonly description: string;
+                        };
+                        readonly vendorId: {
+                            readonly type: readonly ["string", "null"];
+                            readonly default: null;
+                            readonly description: string;
+                        };
+                        readonly hasActual: {
+                            readonly type: "boolean";
+                            readonly default: false;
+                            readonly description: string;
+                        };
                         readonly taxable: {
                             readonly type: "boolean";
                             readonly default: false;

package/dist/schemas/bill.js

@@ -121,6 +121,16 @@ const billSchema = {
 						default: null,
 						description: "The ID of the claimed cost entry: an entry within the ticket on a `ticket` line, a costs-collection document on an `adhoc` one."
 					},
+					propertyId: {
+						type: ["string", "null"],
+						default: null,
+						description: "The property the claimed entry belongs to, snapshotted at mark-sent: the source ticket's property on a `ticket` line, the ad hoc entry's attributed property on an `adhoc` one. Lets a cross-organization reader reach the ticket's property scope without a ticket read. Internal, redacted org-side."
+					},
+					ticketNumber: {
+						type: ["string", "null"],
+						default: null,
+						description: "The source ticket's number, snapshotted at mark-sent. Null on an `adhoc` line. Internal, redacted org-side."
+					},
 					categoryId: {
 						type: ["string", "null"],
 						default: null,
@@ -152,6 +162,21 @@ const billSchema = {
 						default: null,
 						description: "The line description, snapshotted at mark-sent. Null while drafting, when it live-reads from the cost entry."
 					},
+					vendorCost: {
+						type: ["integer", "null"],
+						default: null,
+						description: "What the claimed entry costs Kohost in integer cents, snapshotted at mark-sent: the vendor actual when recorded, else the estimate. Null while drafting or when the entry carries neither. Re-patched when a late actual lands. Internal, redacted org-side."
+					},
+					vendorId: {
+						type: ["string", "null"],
+						default: null,
+						description: "The org-scoped Vendor named on the claimed entry, snapshotted at mark-sent. Internal, redacted org-side."
+					},
+					hasActual: {
+						type: "boolean",
+						default: false,
+						description: "Whether `vendorCost` is the vendor's settled actual rather than the estimate, snapshotted at mark-sent and re-patched when the actual lands. Internal, redacted org-side."
+					},
 					taxable: {
 						type: "boolean",
 						default: false,

package/dist/schemas/bill.js.map

@@ -1 +1 @@
-{"version":3,"file":"bill.js","names":[],"sources":["../../.generated/schemas/bill.ts"],"sourcesContent":["import defs, { ISODateString } from \"./definitions\";\nimport type { FromSchema } from \"json-schema-to-ts\";\nimport { mediaFileSchema } from \"./mediaFile\";\n\n// One bill line is a discriminated union on `type`, so `lines.items` is their\n// `oneOf`. The two branches are disjoint via the `type` const plus\n// `additionalProperties: false`, so a line validates against exactly one.\n//\n// A cost line always names its entry by `costId`; `source` says which\n// collection to look it up in. A `ticket` line resolves through\n// `(ticketId, costId)`, an `adhoc` line reads `costId` straight off the costs\n// collection with `ticketId` null. The claim path is what pairs the two, since\n// JSON Schema cannot state the pairing without splitting the branch and\n// breaking the `type` discriminator every reader keys off.\n//\n// While the bill is a draft the line carries only the reference, the picked\n// `categoryId`, and any draft-time adjustment; the customer-facing `amount`,\n// `description`, and `categoryName` are live-read from the claimed entry and\n// snapshotted onto the line at mark-sent. The billed amount is the marked-up\n// actual (or the `adjustedAmount` override, floored at zero) — vendor truth on\n// the entry is never touched.\nconst costLineSchema = {\n  type: \"object\",\n  additionalProperties: false,\n  required: [\"id\", \"type\"],\n  properties: {\n    id: {\n      type: \"string\",\n      description: \"Server-minted ID of the bill line.\",\n    },\n    type: {\n      type: \"string\",\n      enum: [\"cost\"],\n      description: \"Discriminator: a line drawn from a recorded cost entry.\",\n    },\n    source: {\n      type: \"string\",\n      enum: [\"ticket\", \"adhoc\"],\n      default: \"ticket\",\n      description:\n        \"Where the claimed cost entry lives, and therefore how `costId` \" +\n        \"resolves: on a ticket, or in the costs collection.\",\n    },\n    ticketId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The ID of the ticket the claimed cost entry lives on. Null on an \" +\n        \"`adhoc` line, which no ticket carries.\",\n    },\n    costId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The ID of the claimed cost entry: an entry within the ticket on a \" +\n        \"`ticket` line, a costs-collection document on an `adhoc` one.\",\n    },\n    categoryId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The picked billing category, inherited from the claimed cost entry \" +\n        \"when the claim does not name one. Optional while drafting, required \" +\n        \"at mark-sent. Manual pick — never derived from the ticket's issue.\",\n    },\n    categoryName: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The category name snapshotted at mark-sent. Null while drafting, \" +\n        \"when it live-reads from the category library.\",\n    },\n    adjustedAmount: {\n      type: [\"integer\", \"null\"],\n      minimum: 0,\n      default: null,\n      description:\n        \"Optional draft-time override of the billed amount in integer cents, \" +\n        \"floored at zero, replacing the marked-up actual at display and \" +\n        \"snapshot. Requires `adjustmentReason`. A credit (below zero) is a \" +\n        \"manual line instead.\",\n    },\n    adjustmentReason: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"Short required reason accompanying `adjustedAmount`, kept for the \" +\n        \"internal record.\",\n    },\n    amount: {\n      type: [\"integer\", \"null\"],\n      default: null,\n      description:\n        \"The billed amount in integer cents, snapshotted at mark-sent. Null \" +\n        \"while drafting, when it live-reads (marked-up actual or the \" +\n        \"adjustment) from the cost entry.\",\n    },\n    description: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The line description, snapshotted at mark-sent. Null while drafting, \" +\n        \"when it live-reads from the cost entry.\",\n    },\n    taxable: {\n      type: \"boolean\",\n      default: false,\n      description:\n        \"Whether the line's amount joins the bill's taxable subtotal. \" +\n        \"Customer-facing: locks at mark-sent.\",\n    },\n  },\n} as const;\n\n// A manual line is a literal customer-facing row with no markup math: a\n// `description` and `amount` (which may be negative, serving as a credit) and\n// an optional `propertyId`. The independent internal fields — informational\n// `cost` (never derives the amount), `vendorId`, the vendor-invoice file, and\n// `vendorInvoiceNumber` — are redacted org-side via `canSeeCostSplit` and stay\n// editable in any bill state.\nconst manualLineSchema = {\n  type: \"object\",\n  additionalProperties: false,\n  required: [\"id\", \"type\", \"description\", \"amount\"],\n  properties: {\n    id: {\n      type: \"string\",\n      description: \"Server-minted ID of the bill line.\",\n    },\n    type: {\n      type: \"string\",\n      enum: [\"manual\"],\n      description: \"Discriminator: a literal, non-ticket line.\",\n    },\n    description: {\n      type: \"string\",\n      minLength: 1,\n      description: \"The literal customer-facing description.\",\n    },\n    amount: {\n      type: \"integer\",\n      description:\n        \"The billed amount in integer cents. May be negative, serving as a \" +\n        \"credit (reference the reason in the description).\",\n    },\n    propertyId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The property the manual line is attributed to, when it concerns one.\",\n    },\n    categoryId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The picked billing category. Optional while drafting, required at \" +\n        \"mark-sent.\",\n    },\n    categoryName: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description: \"The category name snapshotted at mark-sent.\",\n    },\n    cost: {\n      type: [\"integer\", \"null\"],\n      default: null,\n      description:\n        \"Informational internal vendor cost in integer cents. Never derives \" +\n        \"the amount. Redacted org-side.\",\n    },\n    vendorId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"Optional reference to the org-scoped Vendor. Internal, redacted \" +\n        \"org-side.\",\n    },\n    vendorInvoice: {\n      anyOf: [{ $ref: \"mediaFile.json\" }, { type: \"null\" }],\n      default: null,\n      description:\n        \"The vendor's invoice file backing the line, mirroring the cost-entry \" +\n        \"field. Internal, redacted org-side.\",\n    },\n    vendorInvoiceNumber: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The vendor's own invoice number. Internal, redacted org-side.\",\n    },\n    taxable: {\n      type: \"boolean\",\n      default: false,\n      description:\n        \"Whether the line's amount joins the bill's taxable subtotal. \" +\n        \"Customer-facing: locks at mark-sent.\",\n    },\n  },\n} as const;\n\nexport const billSchema = {\n  $schema: \"http://json-schema.org/draft-07/schema\",\n  $id: \"bill.json\",\n  title: \"Bill\",\n  description:\n    \"A OneBill bill, stored platform-wide and stamped with its organization: \" +\n    \"KFC staff assemble billed lines from the \" +\n    \"uninvoiced cost pool (plus manual lines) into a draft, then mark it sent \" +\n    \"to freeze and reveal it to the customer. Lifecycle draft → sent → paid, \" +\n    \"plus void. Customers see a bill in-app only once sent.\",\n  type: \"object\",\n  required: [\"id\", \"organizationId\", \"status\", \"currency\", \"lines\"],\n  additionalProperties: false,\n  properties: {\n    id: {\n      $ref: \"definitions.json#/definitions/id\",\n    },\n    type: {\n      type: \"string\",\n      enum: [\"bill\"],\n      default: \"bill\",\n    },\n    organizationId: {\n      type: \"string\",\n      description:\n        \"The organization the bill invoices. Bills live in one admin-database \" +\n        \"collection across every organization, so each carries its owner \" +\n        \"explicitly — stamped from the request context at creation, never \" +\n        \"client-supplied.\",\n    },\n    status: {\n      type: \"string\",\n      enum: [\"draft\", \"sent\", \"paid\", \"void\"],\n      default: \"draft\",\n      description:\n        \"Lifecycle state. `sent` freezes customer-facing fields and reveals \" +\n        \"the bill to the org; `paid` records manual payment; `void` releases \" +\n        \"cost-entry claims and hides the bill from the org view. Drafts \" +\n        \"hard-delete rather than voiding.\",\n    },\n    invoiceNumber: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"Kohost's own invoice number, `KB-<n>` from a single global sequence. \" +\n        \"System-assigned at mark-sent and never entered by hand: null while \" +\n        \"the bill is a draft, immutable once set. A wrong bill is corrected \" +\n        \"by void-and-reissue, so numbers gap and are never reused.\",\n    },\n    period: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        'Display-only month label (e.g. \"July 2026\"). A UI hint; the bill\\'s ' +\n        \"membership is defined by its lines, not a calendar bucket.\",\n    },\n    currency: {\n      type: \"string\",\n      enum: [\"USD\"],\n      default: \"USD\",\n      description: \"ISO 4217 currency code. USD only in v1.\",\n    },\n    fileId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The generated bill PDF's media-file ID, minted atomically at \" +\n        \"mark-sent.\",\n    },\n    fileUrl: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The generated bill PDF's file-store URL, snapshotted at mark-sent \" +\n        \"alongside fileId. Held so the sent-bill surface and the sent \" +\n        \"notification email can mint a signed, unauthenticated download link \" +\n        \"without a file lookup. Unsigned on its own (a bare link 401s).\",\n    },\n    memo: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"Internal KFC-only note. Never customer-facing; editable in any state.\",\n    },\n    billingAddress: {\n      anyOf: [\n        { $ref: \"definitions.json#/definitions/address\" },\n        { type: \"null\" },\n      ],\n      default: null,\n      description:\n        \"The org billing address snapshotted at mark-sent. Null while \" +\n        \"drafting, when it live-reads from the Organization. Mark-sent \" +\n        \"requires a complete address (line1, city, state, postalCode).\",\n    },\n    taxRate: {\n      type: [\"number\", \"null\"],\n      default: null,\n      minimum: 0,\n      description:\n        \"Tax rate as a plain float percent applied to the taxable line \" +\n        \"subtotal. While drafting, null means the platform default rate; the \" +\n        \"effective rate is snapshotted at mark-sent.\",\n    },\n    taxExempt: {\n      type: \"boolean\",\n      default: false,\n      description:\n        \"The organization's tax exemption snapshotted at mark-sent. While \" +\n        \"drafting it live-reads from the Organization.\",\n    },\n    shippingAmount: {\n      type: [\"integer\", \"null\"],\n      default: null,\n      minimum: 0,\n      description:\n        \"Shipping & handling in integer cents, added to the grand total on \" +\n        \"top of the line subtotal and tax. Null means none.\",\n    },\n    lines: {\n      type: \"array\",\n      default: [],\n      description:\n        \"The bill's lines: cost lines claimed from the uninvoiced pool and \" +\n        \"literal manual lines.\",\n      items: {\n        oneOf: [costLineSchema, manualLineSchema],\n      },\n    },\n    sentAt: {\n      $ref: \"definitions.json#/definitions/date\",\n      description: \"When the bill was marked sent. Absent until sent.\",\n    },\n    paidAt: {\n      $ref: \"definitions.json#/definitions/date\",\n      description: \"When the bill was marked paid. Absent until paid.\",\n    },\n    voidedAt: {\n      $ref: \"definitions.json#/definitions/date\",\n      description: \"When the bill was voided. Absent unless voided.\",\n    },\n    createdAt: {\n      $ref: \"definitions.json#/definitions/date\",\n    },\n    updatedAt: {\n      $ref: \"definitions.json#/definitions/date\",\n    },\n  },\n} as const;\n\nexport type BillSchema = FromSchema<\n  typeof billSchema,\n  {\n    references: [typeof defs, typeof mediaFileSchema];\n    deserialize: [\n      {\n        pattern: {\n          format: \"date-time\";\n        };\n        output: Date | ISODateString;\n      },\n    ];\n  }\n>;\n\n/** One line on a bill: a cost line or a manual line. */\nexport type BillLine = NonNullable<BillSchema[\"lines\"]>[number];\n"],"mappings":"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"}
+{"version":3,"file":"bill.js","names":[],"sources":["../../.generated/schemas/bill.ts"],"sourcesContent":["import defs, { ISODateString } from \"./definitions\";\nimport type { FromSchema } from \"json-schema-to-ts\";\nimport { mediaFileSchema } from \"./mediaFile\";\n\n// One bill line is a discriminated union on `type`, so `lines.items` is their\n// `oneOf`. The two branches are disjoint via the `type` const plus\n// `additionalProperties: false`, so a line validates against exactly one.\n//\n// A cost line always names its entry by `costId`; `source` says which\n// collection to look it up in. A `ticket` line resolves through\n// `(ticketId, costId)`, an `adhoc` line reads `costId` straight off the costs\n// collection with `ticketId` null. The claim path is what pairs the two, since\n// JSON Schema cannot state the pairing without splitting the branch and\n// breaking the `type` discriminator every reader keys off.\n//\n// While the bill is a draft the line carries only the reference, the picked\n// `categoryId`, and any draft-time adjustment; the customer-facing `amount`,\n// `description`, and `categoryName` are live-read from the claimed entry and\n// snapshotted onto the line at mark-sent. The billed amount is the marked-up\n// actual (or the `adjustedAmount` override, floored at zero) — vendor truth on\n// the entry is never touched.\n//\n// `vendorCost`, `vendorId` and `hasActual` are a derived snapshot of that\n// vendor truth, written at mark-sent beside `amount` and re-patched when a\n// late actual lands on the claimed entry, so the transactions view and period\n// margin read one collection. `propertyId` and `ticketNumber` are snapshotted\n// beside them so that reader can address the source ticket's property without\n// resolving the ticket. The entry stays the source of truth; the vendor\n// invoice number and files are read live from it, never snapshotted.\nconst costLineSchema = {\n  type: \"object\",\n  additionalProperties: false,\n  required: [\"id\", \"type\"],\n  properties: {\n    id: {\n      type: \"string\",\n      description: \"Server-minted ID of the bill line.\",\n    },\n    type: {\n      type: \"string\",\n      enum: [\"cost\"],\n      description: \"Discriminator: a line drawn from a recorded cost entry.\",\n    },\n    source: {\n      type: \"string\",\n      enum: [\"ticket\", \"adhoc\"],\n      default: \"ticket\",\n      description:\n        \"Where the claimed cost entry lives, and therefore how `costId` \" +\n        \"resolves: on a ticket, or in the costs collection.\",\n    },\n    ticketId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The ID of the ticket the claimed cost entry lives on. Null on an \" +\n        \"`adhoc` line, which no ticket carries.\",\n    },\n    costId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The ID of the claimed cost entry: an entry within the ticket on a \" +\n        \"`ticket` line, a costs-collection document on an `adhoc` one.\",\n    },\n    propertyId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The property the claimed entry belongs to, snapshotted at \" +\n        \"mark-sent: the source ticket's property on a `ticket` line, the \" +\n        \"ad hoc entry's attributed property on an `adhoc` one. Lets a \" +\n        \"cross-organization reader reach the ticket's property scope \" +\n        \"without a ticket read. Internal, redacted org-side.\",\n    },\n    ticketNumber: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The source ticket's number, snapshotted at mark-sent. Null on an \" +\n        \"`adhoc` line. Internal, redacted org-side.\",\n    },\n    categoryId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The picked billing category, inherited from the claimed cost entry \" +\n        \"when the claim does not name one. Optional while drafting, required \" +\n        \"at mark-sent. Manual pick — never derived from the ticket's issue.\",\n    },\n    categoryName: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The category name snapshotted at mark-sent. Null while drafting, \" +\n        \"when it live-reads from the category library.\",\n    },\n    adjustedAmount: {\n      type: [\"integer\", \"null\"],\n      minimum: 0,\n      default: null,\n      description:\n        \"Optional draft-time override of the billed amount in integer cents, \" +\n        \"floored at zero, replacing the marked-up actual at display and \" +\n        \"snapshot. Requires `adjustmentReason`. A credit (below zero) is a \" +\n        \"manual line instead.\",\n    },\n    adjustmentReason: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"Short required reason accompanying `adjustedAmount`, kept for the \" +\n        \"internal record.\",\n    },\n    amount: {\n      type: [\"integer\", \"null\"],\n      default: null,\n      description:\n        \"The billed amount in integer cents, snapshotted at mark-sent. Null \" +\n        \"while drafting, when it live-reads (marked-up actual or the \" +\n        \"adjustment) from the cost entry.\",\n    },\n    description: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The line description, snapshotted at mark-sent. Null while drafting, \" +\n        \"when it live-reads from the cost entry.\",\n    },\n    vendorCost: {\n      type: [\"integer\", \"null\"],\n      default: null,\n      description:\n        \"What the claimed entry costs Kohost in integer cents, snapshotted \" +\n        \"at mark-sent: the vendor actual when recorded, else the estimate. \" +\n        \"Null while drafting or when the entry carries neither. Re-patched \" +\n        \"when a late actual lands. Internal, redacted org-side.\",\n    },\n    vendorId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The org-scoped Vendor named on the claimed entry, snapshotted at \" +\n        \"mark-sent. Internal, redacted org-side.\",\n    },\n    hasActual: {\n      type: \"boolean\",\n      default: false,\n      description:\n        \"Whether `vendorCost` is the vendor's settled actual rather than the \" +\n        \"estimate, snapshotted at mark-sent and re-patched when the actual \" +\n        \"lands. Internal, redacted org-side.\",\n    },\n    taxable: {\n      type: \"boolean\",\n      default: false,\n      description:\n        \"Whether the line's amount joins the bill's taxable subtotal. \" +\n        \"Customer-facing: locks at mark-sent.\",\n    },\n  },\n} as const;\n\n// A manual line is a literal customer-facing row with no markup math: a\n// `description` and `amount` (which may be negative, serving as a credit) and\n// an optional `propertyId`. The independent internal fields — informational\n// `cost` (never derives the amount), `vendorId`, the vendor-invoice file, and\n// `vendorInvoiceNumber` — are redacted org-side via `canSeeCostSplit` and stay\n// editable in any bill state.\nconst manualLineSchema = {\n  type: \"object\",\n  additionalProperties: false,\n  required: [\"id\", \"type\", \"description\", \"amount\"],\n  properties: {\n    id: {\n      type: \"string\",\n      description: \"Server-minted ID of the bill line.\",\n    },\n    type: {\n      type: \"string\",\n      enum: [\"manual\"],\n      description: \"Discriminator: a literal, non-ticket line.\",\n    },\n    description: {\n      type: \"string\",\n      minLength: 1,\n      description: \"The literal customer-facing description.\",\n    },\n    amount: {\n      type: \"integer\",\n      description:\n        \"The billed amount in integer cents. May be negative, serving as a \" +\n        \"credit (reference the reason in the description).\",\n    },\n    propertyId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The property the manual line is attributed to, when it concerns one.\",\n    },\n    categoryId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The picked billing category. Optional while drafting, required at \" +\n        \"mark-sent.\",\n    },\n    categoryName: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description: \"The category name snapshotted at mark-sent.\",\n    },\n    cost: {\n      type: [\"integer\", \"null\"],\n      default: null,\n      description:\n        \"Informational internal vendor cost in integer cents. Never derives \" +\n        \"the amount. Redacted org-side.\",\n    },\n    vendorId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"Optional reference to the org-scoped Vendor. Internal, redacted \" +\n        \"org-side.\",\n    },\n    vendorInvoice: {\n      anyOf: [{ $ref: \"mediaFile.json\" }, { type: \"null\" }],\n      default: null,\n      description:\n        \"The vendor's invoice file backing the line, mirroring the cost-entry \" +\n        \"field. Internal, redacted org-side.\",\n    },\n    vendorInvoiceNumber: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The vendor's own invoice number. Internal, redacted org-side.\",\n    },\n    taxable: {\n      type: \"boolean\",\n      default: false,\n      description:\n        \"Whether the line's amount joins the bill's taxable subtotal. \" +\n        \"Customer-facing: locks at mark-sent.\",\n    },\n  },\n} as const;\n\nexport const billSchema = {\n  $schema: \"http://json-schema.org/draft-07/schema\",\n  $id: \"bill.json\",\n  title: \"Bill\",\n  description:\n    \"A OneBill bill, stored platform-wide and stamped with its organization: \" +\n    \"KFC staff assemble billed lines from the \" +\n    \"uninvoiced cost pool (plus manual lines) into a draft, then mark it sent \" +\n    \"to freeze and reveal it to the customer. Lifecycle draft → sent → paid, \" +\n    \"plus void. Customers see a bill in-app only once sent.\",\n  type: \"object\",\n  required: [\"id\", \"organizationId\", \"status\", \"currency\", \"lines\"],\n  additionalProperties: false,\n  properties: {\n    id: {\n      $ref: \"definitions.json#/definitions/id\",\n    },\n    type: {\n      type: \"string\",\n      enum: [\"bill\"],\n      default: \"bill\",\n    },\n    organizationId: {\n      type: \"string\",\n      description:\n        \"The organization the bill invoices. Bills live in one admin-database \" +\n        \"collection across every organization, so each carries its owner \" +\n        \"explicitly — stamped from the request context at creation, never \" +\n        \"client-supplied.\",\n    },\n    status: {\n      type: \"string\",\n      enum: [\"draft\", \"sent\", \"paid\", \"void\"],\n      default: \"draft\",\n      description:\n        \"Lifecycle state. `sent` freezes customer-facing fields and reveals \" +\n        \"the bill to the org; `paid` records manual payment; `void` releases \" +\n        \"cost-entry claims and hides the bill from the org view. Drafts \" +\n        \"hard-delete rather than voiding.\",\n    },\n    invoiceNumber: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"Kohost's own invoice number, `KB-<n>` from a single global sequence. \" +\n        \"System-assigned at mark-sent and never entered by hand: null while \" +\n        \"the bill is a draft, immutable once set. A wrong bill is corrected \" +\n        \"by void-and-reissue, so numbers gap and are never reused.\",\n    },\n    period: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        'Display-only month label (e.g. \"July 2026\"). A UI hint; the bill\\'s ' +\n        \"membership is defined by its lines, not a calendar bucket.\",\n    },\n    currency: {\n      type: \"string\",\n      enum: [\"USD\"],\n      default: \"USD\",\n      description: \"ISO 4217 currency code. USD only in v1.\",\n    },\n    fileId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The generated bill PDF's media-file ID, minted atomically at \" +\n        \"mark-sent.\",\n    },\n    fileUrl: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The generated bill PDF's file-store URL, snapshotted at mark-sent \" +\n        \"alongside fileId. Held so the sent-bill surface and the sent \" +\n        \"notification email can mint a signed, unauthenticated download link \" +\n        \"without a file lookup. Unsigned on its own (a bare link 401s).\",\n    },\n    memo: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"Internal KFC-only note. Never customer-facing; editable in any state.\",\n    },\n    billingAddress: {\n      anyOf: [\n        { $ref: \"definitions.json#/definitions/address\" },\n        { type: \"null\" },\n      ],\n      default: null,\n      description:\n        \"The org billing address snapshotted at mark-sent. Null while \" +\n        \"drafting, when it live-reads from the Organization. Mark-sent \" +\n        \"requires a complete address (line1, city, state, postalCode).\",\n    },\n    taxRate: {\n      type: [\"number\", \"null\"],\n      default: null,\n      minimum: 0,\n      description:\n        \"Tax rate as a plain float percent applied to the taxable line \" +\n        \"subtotal. While drafting, null means the platform default rate; the \" +\n        \"effective rate is snapshotted at mark-sent.\",\n    },\n    taxExempt: {\n      type: \"boolean\",\n      default: false,\n      description:\n        \"The organization's tax exemption snapshotted at mark-sent. While \" +\n        \"drafting it live-reads from the Organization.\",\n    },\n    shippingAmount: {\n      type: [\"integer\", \"null\"],\n      default: null,\n      minimum: 0,\n      description:\n        \"Shipping & handling in integer cents, added to the grand total on \" +\n        \"top of the line subtotal and tax. Null means none.\",\n    },\n    lines: {\n      type: \"array\",\n      default: [],\n      description:\n        \"The bill's lines: cost lines claimed from the uninvoiced pool and \" +\n        \"literal manual lines.\",\n      items: {\n        oneOf: [costLineSchema, manualLineSchema],\n      },\n    },\n    sentAt: {\n      $ref: \"definitions.json#/definitions/date\",\n      description: \"When the bill was marked sent. Absent until sent.\",\n    },\n    paidAt: {\n      $ref: \"definitions.json#/definitions/date\",\n      description: \"When the bill was marked paid. Absent until paid.\",\n    },\n    voidedAt: {\n      $ref: \"definitions.json#/definitions/date\",\n      description: \"When the bill was voided. Absent unless voided.\",\n    },\n    createdAt: {\n      $ref: \"definitions.json#/definitions/date\",\n    },\n    updatedAt: {\n      $ref: \"definitions.json#/definitions/date\",\n    },\n  },\n} as const;\n\nexport type BillSchema = FromSchema<\n  typeof billSchema,\n  {\n    references: [typeof defs, typeof mediaFileSchema];\n    deserialize: [\n      {\n        pattern: {\n          format: \"date-time\";\n        };\n        output: Date | ISODateString;\n      },\n    ];\n  }\n>;\n\n/** One line on a bill: a cost line or a manual line. */\nexport type BillLine = NonNullable<BillSchema[\"lines\"]>[number];\n"],"mappings":"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"}

package/dist/schemas/costEntry.d.ts

@@ -1,3 +1,30 @@
+/**
+ * The same phase on a host that admits a Pending cost, where `null` means the
+ * amount is not known yet. Only the ticket cost entry takes this shape: a
+ * ticket is what a vendor quote is awaited on.
+ */
+export declare const nullableMoney: (description: string) => {
+    readonly type: readonly ["object", "null"];
+    readonly additionalProperties: false;
+    readonly required: readonly ["amount", "recordedBy", "recordedAt"];
+    readonly default: null;
+    readonly description: string;
+    readonly properties: {
+        readonly amount: {
+            readonly type: "integer";
+            readonly minimum: 0;
+            readonly description: "The amount 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.";
+        };
+    };
+};
 /**
  * The append-only billing review history, over whichever actions the host
  * admits. A ticket cost can be voided (withdrawn from the customer); a

package/dist/schemas/costEntry.js

@@ -1,28 +1,43 @@
 //#region .generated/schemas/costEntry.ts
+const moneyProperties = {
+	amount: {
+		type: "integer",
+		minimum: 0,
+		description: "The amount in integer cents."
+	},
+	recordedBy: {
+		type: "string",
+		description: "The ID of the user who recorded the amount."
+	},
+	recordedAt: {
+		$ref: "definitions.json#/definitions/date",
+		description: "When the amount was recorded."
+	}
+};
+const moneyRequired = [
+	"amount",
+	"recordedBy",
+	"recordedAt"
+];
 const money = (description) => ({
 	type: "object",
 	additionalProperties: false,
-	required: [
-		"amount",
-		"recordedBy",
-		"recordedAt"
-	],
+	required: moneyRequired,
 	description,
-	properties: {
-		amount: {
-			type: "integer",
-			minimum: 0,
-			description: "The amount in integer cents."
-		},
-		recordedBy: {
-			type: "string",
-			description: "The ID of the user who recorded the amount."
-		},
-		recordedAt: {
-			$ref: "definitions.json#/definitions/date",
-			description: "When the amount was recorded."
-		}
-	}
+	properties: moneyProperties
+});
+/**
+* The same phase on a host that admits a Pending cost, where `null` means the
+* amount is not known yet. Only the ticket cost entry takes this shape: a
+* ticket is what a vendor quote is awaited on.
+*/
+const nullableMoney = (description) => ({
+	type: ["object", "null"],
+	additionalProperties: false,
+	required: moneyRequired,
+	default: null,
+	description,
+	properties: moneyProperties
 });
 /**
 * The append-only billing review history, over whichever actions the host
@@ -157,6 +172,6 @@ const costEntryProperties = {
 	])
 };
 //#endregion
-export { costBillingReview, costEntryProperties, costEntryRequired };
+export { costBillingReview, costEntryProperties, costEntryRequired, nullableMoney };
 
 //# sourceMappingURL=costEntry.js.map

package/dist/schemas/costEntry.js.map

@@ -1 +1 @@
-{"version":3,"file":"costEntry.js","names":[],"sources":["../../.generated/schemas/costEntry.ts"],"sourcesContent":["// The cost-entry core: the money shape and reconciliation lifecycle every\n// OneBill cost carries, whether a Ticket embeds it or it stands alone in the\n// costs collection. Both hosts spread these consts into their own `properties`\n// and `required` rather than `$ref`-ing this file: draft-07 resolves `allOf`\n// against `additionalProperties: false` per subschema, so a composed entry\n// would reject every field the other half declared, and `FromSchema` derives\n// nothing useful from a reference it cannot inline.\n//\n// Nothing here is exported with a name ending in \"Schema\" and the model\n// generator skips this file by name (`scripts/generate-source-models.js`):\n// these are fragments, not an entity.\n\nconst money = (description: string) =>\n  ({\n    type: \"object\",\n    additionalProperties: false,\n    required: [\"amount\", \"recordedBy\", \"recordedAt\"],\n    description,\n    properties: {\n      amount: {\n        type: \"integer\",\n        minimum: 0,\n        description: \"The amount in integer cents.\",\n      },\n      recordedBy: {\n        type: \"string\",\n        description: \"The ID of the user who recorded the amount.\",\n      },\n      recordedAt: {\n        $ref: \"definitions.json#/definitions/date\",\n        description: \"When the amount was recorded.\",\n      },\n    },\n  }) as const;\n\n/**\n * The append-only billing review history, over whichever actions the host\n * admits. A ticket cost can be voided (withdrawn from the customer); a\n * standalone cost has no ticket to withdraw it from, so its history stops at\n * write-offs and divergence acknowledgements.\n */\nexport const costBillingReview = <const Actions extends readonly string[]>(\n  actions: Actions,\n) =>\n  ({\n    type: \"array\",\n    default: [],\n    description:\n      \"Append-only billing review history for the entry (approval-history \" +\n      \"pattern): reversible write-offs, and billed-vs-price divergence \" +\n      \"acknowledgements. Internal, redacted org-side.\",\n    items: {\n      type: \"object\",\n      additionalProperties: false,\n      required: [\"id\", \"action\", \"performedAt\"],\n      properties: {\n        id: {\n          type: \"string\",\n          description: \"The ID of the billing review entry.\",\n        },\n        action: {\n          type: \"string\",\n          enum: actions,\n        },\n        performedBy: {\n          type: [\"string\", \"null\"],\n          default: null,\n          description:\n            \"The ID of the user whose write appended this entry. Null when \" +\n            \"the write was not user-attributable.\",\n        },\n        performedAt: {\n          $ref: \"definitions.json#/definitions/date\",\n          description: \"When the entry was appended.\",\n        },\n        note: {\n          type: [\"string\", \"null\"],\n          default: null,\n          description: \"Free-text rationale for the action.\",\n        },\n        billedAmount: {\n          type: \"integer\",\n          minimum: 0,\n          description:\n            \"divergenceAcknowledged only: the amount a bill line already \" +\n            \"charged for this entry, in integer cents, frozen at ack time.\",\n        },\n        priceAmount: {\n          type: \"integer\",\n          minimum: 0,\n          description:\n            \"divergenceAcknowledged only: the entry's stored customer price \" +\n            \"in integer cents at ack time. A divergence is a billed line \" +\n            \"that no longer matches the price behind it — a price corrected \" +\n            \"after the cost was claimed — so the ack silences this one pair \" +\n            \"and any later price move re-flags it. A vendor actual arriving \" +\n            \"after billing is not a divergence: it moves margin, not what \" +\n            \"the customer owes.\",\n        },\n      },\n    },\n  }) as const;\n\nexport const costEntryRequired = [\n  \"id\",\n  \"description\",\n  \"currency\",\n  \"price\",\n  \"estimate\",\n  \"markup\",\n] as const;\n\nexport const costEntryProperties = {\n  id: {\n    type: \"string\",\n    description: \"The ID of the cost entry.\",\n  },\n  description: {\n    type: \"string\",\n    description: \"What the cost covers.\",\n  },\n  currency: {\n    type: \"string\",\n    default: \"USD\",\n    description: \"ISO 4217 currency code of the entry's amounts.\",\n  },\n  price: money(\n    \"The authoritative customer price — what the org is charged, what the \" +\n      \"approval gate totals, and what a bill line bills. Seeded at recording \" +\n      \"from the estimate and the markup, and from then on independent of all \" +\n      \"three: editing `estimate`, `actual`, or `markup` never moves it. Only \" +\n      \"an explicit price write does.\",\n  ),\n  estimate: money(\"The vendor cost estimate phase of the entry.\"),\n  actual: money(\n    \"The settled vendor cost, recorded once the vendor's figure is known.\",\n  ),\n  markup: {\n    type: \"object\",\n    additionalProperties: false,\n    required: [\"percent\"],\n    properties: {\n      percent: {\n        type: \"number\",\n        description:\n          \"Markup percent the price was derived at, uncapped in either \" +\n          \"direction. Context for how the price was arrived at, not the \" +\n          \"source of truth for any amount: `price` is stored, so re-keying \" +\n          \"this percent prices nothing. A biller may charge under the vendor \" +\n          \"cost as a deliberate comp, and this records that as the negative \" +\n          \"percent it is rather than as a floor of zero the price never came \" +\n          \"from.\",\n      },\n      custom: {\n        type: \"boolean\",\n        default: false,\n        description:\n          \"Whether the percent was overridden by hand rather than keyed from \" +\n          \"the configured markup tiers. Custom percents are never re-keyed on \" +\n          \"estimate edits.\",\n      },\n    },\n  },\n  vendorId: {\n    type: [\"string\", \"null\"],\n    default: null,\n    description:\n      \"The Vendor the charge is owed to. A plain reference — no rollups — \" +\n      \"resolved inside the entry's own organization. Internal, redacted \" +\n      \"org-side with the rest of the cost split.\",\n  },\n  categoryId: {\n    type: [\"string\", \"null\"],\n    default: null,\n    description:\n      \"The billing category classifying this cost. `AddBillLine` snapshots \" +\n      \"it onto the claiming line, which owns its own category from then on. \" +\n      \"Internal, redacted org-side with the rest of the cost split.\",\n  },\n  vendorInvoices: {\n    type: \"array\",\n    items: { $ref: \"mediaFile.json\" },\n    default: [],\n    description:\n      \"The vendor's paperwork backing the entry's amounts — an invoice plus \" +\n      \"whatever came with it. Internal: the file-store cannot enforce \" +\n      \"roster-only reads, so the boundary is this field living on the full \" +\n      \"shape only, and the redacted projection never carries it.\",\n  },\n  vendorInvoiceNumber: {\n    type: [\"string\", \"null\"],\n    default: null,\n    description:\n      \"The vendor's own invoice number. Internal, redacted org-side like the \" +\n      \"rest of the cost split.\",\n  },\n  billId: {\n    type: [\"string\", \"null\"],\n    default: null,\n    description:\n      \"Backlink to the bill whose draft claimed this cost as a line. Written \" +\n      \"when a draft bill adds the line, cleared on line removal, draft \" +\n      \"delete, or bill void; a claimed cost leaves the uninvoiced pool, \" +\n      \"making double-invoicing structurally impossible. Server-maintained at \" +\n      \"the repository, never set by clients.\",\n  },\n  writtenOff: {\n    type: \"boolean\",\n    default: false,\n    description:\n      \"Server-maintained denormalization of billingReview (approvalState \" +\n      \"pattern): true after a writtenOff entry until a reinstated entry \" +\n      \"follows. A written-off cost leaves the uninvoiced pool. Never set by \" +\n      \"clients.\",\n  },\n  billingReview: costBillingReview([\n    \"writtenOff\",\n    \"reinstated\",\n    \"divergenceAcknowledged\",\n  ]),\n} as const;\n"],"mappings":";AAYA,MAAM,SAAS,iBACZ;CACC,MAAM;CACN,sBAAsB;CACtB,UAAU;EAAC;EAAU;EAAc;CAAY;CAC/C;CACA,YAAY;EACV,QAAQ;GACN,MAAM;GACN,SAAS;GACT,aAAa;EACf;EACA,YAAY;GACV,MAAM;GACN,aAAa;EACf;EACA,YAAY;GACV,MAAM;GACN,aAAa;EACf;CACF;AACF;;;;;;;AAQF,MAAa,qBACX,aAEC;CACC,MAAM;CACN,SAAS,CAAC;CACV,aACE;CAGF,OAAO;EACL,MAAM;EACN,sBAAsB;EACtB,UAAU;GAAC;GAAM;GAAU;EAAa;EACxC,YAAY;GACV,IAAI;IACF,MAAM;IACN,aAAa;GACf;GACA,QAAQ;IACN,MAAM;IACN,MAAM;GACR;GACA,aAAa;IACX,MAAM,CAAC,UAAU,MAAM;IACvB,SAAS;IACT,aACE;GAEJ;GACA,aAAa;IACX,MAAM;IACN,aAAa;GACf;GACA,MAAM;IACJ,MAAM,CAAC,UAAU,MAAM;IACvB,SAAS;IACT,aAAa;GACf;GACA,cAAc;IACZ,MAAM;IACN,SAAS;IACT,aACE;GAEJ;GACA,aAAa;IACX,MAAM;IACN,SAAS;IACT,aACE;GAOJ;EACF;CACF;AACF;AAEF,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;AACF;AAEA,MAAa,sBAAsB;CACjC,IAAI;EACF,MAAM;EACN,aAAa;CACf;CACA,aAAa;EACX,MAAM;EACN,aAAa;CACf;CACA,UAAU;EACR,MAAM;EACN,SAAS;EACT,aAAa;CACf;CACA,OAAO,MACL,sTAKF;CACA,UAAU,MAAM,8CAA8C;CAC9D,QAAQ,MACN,sEACF;CACA,QAAQ;EACN,MAAM;EACN,sBAAsB;EACtB,UAAU,CAAC,SAAS;EACpB,YAAY;GACV,SAAS;IACP,MAAM;IACN,aACE;GAOJ;GACA,QAAQ;IACN,MAAM;IACN,SAAS;IACT,aACE;GAGJ;EACF;CACF;CACA,UAAU;EACR,MAAM,CAAC,UAAU,MAAM;EACvB,SAAS;EACT,aACE;CAGJ;CACA,YAAY;EACV,MAAM,CAAC,UAAU,MAAM;EACvB,SAAS;EACT,aACE;CAGJ;CACA,gBAAgB;EACd,MAAM;EACN,OAAO,EAAE,MAAM,iBAAiB;EAChC,SAAS,CAAC;EACV,aACE;CAIJ;CACA,qBAAqB;EACnB,MAAM,CAAC,UAAU,MAAM;EACvB,SAAS;EACT,aACE;CAEJ;CACA,QAAQ;EACN,MAAM,CAAC,UAAU,MAAM;EACvB,SAAS;EACT,aACE;CAKJ;CACA,YAAY;EACV,MAAM;EACN,SAAS;EACT,aACE;CAIJ;CACA,eAAe,kBAAkB;EAC/B;EACA;EACA;CACF,CAAC;AACH"}
+{"version":3,"file":"costEntry.js","names":[],"sources":["../../.generated/schemas/costEntry.ts"],"sourcesContent":["// The cost-entry core: the money shape and reconciliation lifecycle every\n// OneBill cost carries, whether a Ticket embeds it or it stands alone in the\n// costs collection. Both hosts spread these consts into their own `properties`\n// and `required` rather than `$ref`-ing this file: draft-07 resolves `allOf`\n// against `additionalProperties: false` per subschema, so a composed entry\n// would reject every field the other half declared, and `FromSchema` derives\n// nothing useful from a reference it cannot inline.\n//\n// Nothing here is exported with a name ending in \"Schema\" and the model\n// generator skips this file by name (`scripts/generate-source-models.js`):\n// these are fragments, not an entity.\n\nconst moneyProperties = {\n  amount: {\n    type: \"integer\",\n    minimum: 0,\n    description: \"The amount in integer cents.\",\n  },\n  recordedBy: {\n    type: \"string\",\n    description: \"The ID of the user who recorded the amount.\",\n  },\n  recordedAt: {\n    $ref: \"definitions.json#/definitions/date\",\n    description: \"When the amount was recorded.\",\n  },\n} as const;\n\nconst moneyRequired = [\"amount\", \"recordedBy\", \"recordedAt\"] as const;\n\nconst money = (description: string) =>\n  ({\n    type: \"object\",\n    additionalProperties: false,\n    required: moneyRequired,\n    description,\n    properties: moneyProperties,\n  }) as const;\n\n/**\n * The same phase on a host that admits a Pending cost, where `null` means the\n * amount is not known yet. Only the ticket cost entry takes this shape: a\n * ticket is what a vendor quote is awaited on.\n */\nexport const nullableMoney = (description: string) =>\n  ({\n    type: [\"object\", \"null\"],\n    additionalProperties: false,\n    required: moneyRequired,\n    default: null,\n    description,\n    properties: moneyProperties,\n  }) as const;\n\n/**\n * The append-only billing review history, over whichever actions the host\n * admits. A ticket cost can be voided (withdrawn from the customer); a\n * standalone cost has no ticket to withdraw it from, so its history stops at\n * write-offs and divergence acknowledgements.\n */\nexport const costBillingReview = <const Actions extends readonly string[]>(\n  actions: Actions,\n) =>\n  ({\n    type: \"array\",\n    default: [],\n    description:\n      \"Append-only billing review history for the entry (approval-history \" +\n      \"pattern): reversible write-offs, and billed-vs-price divergence \" +\n      \"acknowledgements. Internal, redacted org-side.\",\n    items: {\n      type: \"object\",\n      additionalProperties: false,\n      required: [\"id\", \"action\", \"performedAt\"],\n      properties: {\n        id: {\n          type: \"string\",\n          description: \"The ID of the billing review entry.\",\n        },\n        action: {\n          type: \"string\",\n          enum: actions,\n        },\n        performedBy: {\n          type: [\"string\", \"null\"],\n          default: null,\n          description:\n            \"The ID of the user whose write appended this entry. Null when \" +\n            \"the write was not user-attributable.\",\n        },\n        performedAt: {\n          $ref: \"definitions.json#/definitions/date\",\n          description: \"When the entry was appended.\",\n        },\n        note: {\n          type: [\"string\", \"null\"],\n          default: null,\n          description: \"Free-text rationale for the action.\",\n        },\n        billedAmount: {\n          type: \"integer\",\n          minimum: 0,\n          description:\n            \"divergenceAcknowledged only: the amount a bill line already \" +\n            \"charged for this entry, in integer cents, frozen at ack time.\",\n        },\n        priceAmount: {\n          type: \"integer\",\n          minimum: 0,\n          description:\n            \"divergenceAcknowledged only: the entry's stored customer price \" +\n            \"in integer cents at ack time. A divergence is a billed line \" +\n            \"that no longer matches the price behind it — a price corrected \" +\n            \"after the cost was claimed — so the ack silences this one pair \" +\n            \"and any later price move re-flags it. A vendor actual arriving \" +\n            \"after billing is not a divergence: it moves margin, not what \" +\n            \"the customer owes.\",\n        },\n      },\n    },\n  }) as const;\n\nexport const costEntryRequired = [\n  \"id\",\n  \"description\",\n  \"currency\",\n  \"price\",\n  \"estimate\",\n  \"markup\",\n] as const;\n\nexport const costEntryProperties = {\n  id: {\n    type: \"string\",\n    description: \"The ID of the cost entry.\",\n  },\n  description: {\n    type: \"string\",\n    description: \"What the cost covers.\",\n  },\n  currency: {\n    type: \"string\",\n    default: \"USD\",\n    description: \"ISO 4217 currency code of the entry's amounts.\",\n  },\n  price: money(\n    \"The authoritative customer price — what the org is charged, what the \" +\n      \"approval gate totals, and what a bill line bills. Seeded at recording \" +\n      \"from the estimate and the markup, and from then on independent of all \" +\n      \"three: editing `estimate`, `actual`, or `markup` never moves it. Only \" +\n      \"an explicit price write does.\",\n  ),\n  estimate: money(\"The vendor cost estimate phase of the entry.\"),\n  actual: money(\n    \"The settled vendor cost, recorded once the vendor's figure is known.\",\n  ),\n  markup: {\n    type: \"object\",\n    additionalProperties: false,\n    required: [\"percent\"],\n    properties: {\n      percent: {\n        type: \"number\",\n        description:\n          \"Markup percent the price was derived at, uncapped in either \" +\n          \"direction. Context for how the price was arrived at, not the \" +\n          \"source of truth for any amount: `price` is stored, so re-keying \" +\n          \"this percent prices nothing. A biller may charge under the vendor \" +\n          \"cost as a deliberate comp, and this records that as the negative \" +\n          \"percent it is rather than as a floor of zero the price never came \" +\n          \"from.\",\n      },\n      custom: {\n        type: \"boolean\",\n        default: false,\n        description:\n          \"Whether the percent was overridden by hand rather than keyed from \" +\n          \"the configured markup tiers. Custom percents are never re-keyed on \" +\n          \"estimate edits.\",\n      },\n    },\n  },\n  vendorId: {\n    type: [\"string\", \"null\"],\n    default: null,\n    description:\n      \"The Vendor the charge is owed to. A plain reference — no rollups — \" +\n      \"resolved inside the entry's own organization. Internal, redacted \" +\n      \"org-side with the rest of the cost split.\",\n  },\n  categoryId: {\n    type: [\"string\", \"null\"],\n    default: null,\n    description:\n      \"The billing category classifying this cost. `AddBillLine` snapshots \" +\n      \"it onto the claiming line, which owns its own category from then on. \" +\n      \"Internal, redacted org-side with the rest of the cost split.\",\n  },\n  vendorInvoices: {\n    type: \"array\",\n    items: { $ref: \"mediaFile.json\" },\n    default: [],\n    description:\n      \"The vendor's paperwork backing the entry's amounts — an invoice plus \" +\n      \"whatever came with it. Internal: the file-store cannot enforce \" +\n      \"roster-only reads, so the boundary is this field living on the full \" +\n      \"shape only, and the redacted projection never carries it.\",\n  },\n  vendorInvoiceNumber: {\n    type: [\"string\", \"null\"],\n    default: null,\n    description:\n      \"The vendor's own invoice number. Internal, redacted org-side like the \" +\n      \"rest of the cost split.\",\n  },\n  billId: {\n    type: [\"string\", \"null\"],\n    default: null,\n    description:\n      \"Backlink to the bill whose draft claimed this cost as a line. Written \" +\n      \"when a draft bill adds the line, cleared on line removal, draft \" +\n      \"delete, or bill void; a claimed cost leaves the uninvoiced pool, \" +\n      \"making double-invoicing structurally impossible. Server-maintained at \" +\n      \"the repository, never set by clients.\",\n  },\n  writtenOff: {\n    type: \"boolean\",\n    default: false,\n    description:\n      \"Server-maintained denormalization of billingReview (approvalState \" +\n      \"pattern): true after a writtenOff entry until a reinstated entry \" +\n      \"follows. A written-off cost leaves the uninvoiced pool. Never set by \" +\n      \"clients.\",\n  },\n  billingReview: costBillingReview([\n    \"writtenOff\",\n    \"reinstated\",\n    \"divergenceAcknowledged\",\n  ]),\n} as const;\n"],"mappings":";AAYA,MAAM,kBAAkB;CACtB,QAAQ;EACN,MAAM;EACN,SAAS;EACT,aAAa;CACf;CACA,YAAY;EACV,MAAM;EACN,aAAa;CACf;CACA,YAAY;EACV,MAAM;EACN,aAAa;CACf;AACF;AAEA,MAAM,gBAAgB;CAAC;CAAU;CAAc;AAAY;AAE3D,MAAM,SAAS,iBACZ;CACC,MAAM;CACN,sBAAsB;CACtB,UAAU;CACV;CACA,YAAY;AACd;;;;;;AAOF,MAAa,iBAAiB,iBAC3B;CACC,MAAM,CAAC,UAAU,MAAM;CACvB,sBAAsB;CACtB,UAAU;CACV,SAAS;CACT;CACA,YAAY;AACd;;;;;;;AAQF,MAAa,qBACX,aAEC;CACC,MAAM;CACN,SAAS,CAAC;CACV,aACE;CAGF,OAAO;EACL,MAAM;EACN,sBAAsB;EACtB,UAAU;GAAC;GAAM;GAAU;EAAa;EACxC,YAAY;GACV,IAAI;IACF,MAAM;IACN,aAAa;GACf;GACA,QAAQ;IACN,MAAM;IACN,MAAM;GACR;GACA,aAAa;IACX,MAAM,CAAC,UAAU,MAAM;IACvB,SAAS;IACT,aACE;GAEJ;GACA,aAAa;IACX,MAAM;IACN,aAAa;GACf;GACA,MAAM;IACJ,MAAM,CAAC,UAAU,MAAM;IACvB,SAAS;IACT,aAAa;GACf;GACA,cAAc;IACZ,MAAM;IACN,SAAS;IACT,aACE;GAEJ;GACA,aAAa;IACX,MAAM;IACN,SAAS;IACT,aACE;GAOJ;EACF;CACF;AACF;AAEF,MAAa,oBAAoB;CAC/B;CACA;CACA;CACA;CACA;CACA;AACF;AAEA,MAAa,sBAAsB;CACjC,IAAI;EACF,MAAM;EACN,aAAa;CACf;CACA,aAAa;EACX,MAAM;EACN,aAAa;CACf;CACA,UAAU;EACR,MAAM;EACN,SAAS;EACT,aAAa;CACf;CACA,OAAO,MACL,sTAKF;CACA,UAAU,MAAM,8CAA8C;CAC9D,QAAQ,MACN,sEACF;CACA,QAAQ;EACN,MAAM;EACN,sBAAsB;EACtB,UAAU,CAAC,SAAS;EACpB,YAAY;GACV,SAAS;IACP,MAAM;IACN,aACE;GAOJ;GACA,QAAQ;IACN,MAAM;IACN,SAAS;IACT,aACE;GAGJ;EACF;CACF;CACA,UAAU;EACR,MAAM,CAAC,UAAU,MAAM;EACvB,SAAS;EACT,aACE;CAGJ;CACA,YAAY;EACV,MAAM,CAAC,UAAU,MAAM;EACvB,SAAS;EACT,aACE;CAGJ;CACA,gBAAgB;EACd,MAAM;EACN,OAAO,EAAE,MAAM,iBAAiB;EAChC,SAAS,CAAC;EACV,aACE;CAIJ;CACA,qBAAqB;EACnB,MAAM,CAAC,UAAU,MAAM;EACvB,SAAS;EACT,aACE;CAEJ;CACA,QAAQ;EACN,MAAM,CAAC,UAAU,MAAM;EACvB,SAAS;EACT,aACE;CAKJ;CACA,YAAY;EACV,MAAM;EACN,SAAS;EACT,aACE;CAIJ;CACA,eAAe,kBAAkB;EAC/B;EACA;EACA;CACF,CAAC;AACH"}

package/dist/schemas/definitions.d.ts

@@ -11,11 +11,14 @@ export type PlatformRoleName = (typeof PLATFORM_ROLE_NAMES)[number];
 /**
  * The people outside the platform a broadcast may name, sourced from the SIS
  * roster. `students` is every system user the SIS marks as a Student;
- * `parents` is everybody else on the roster — every emergency-contact
+ * `staff` is everybody synced with nothing but the Staff role (faculty and
+ * staff); `parents` is everybody else on the roster — every emergency-contact
  * relationship the source system carries, whatever it calls it.
  */
-export declare const EXTERNAL_AUDIENCE_GROUPS: readonly ["students", "parents"];
+export declare const EXTERNAL_AUDIENCE_GROUPS: readonly ["students", "parents", "staff"];
 export type ExternalAudienceGroup = (typeof EXTERNAL_AUDIENCE_GROUPS)[number];
+export declare const SMS_OPT_OUT_REASONS: readonly ["stop", "vendor"];
+export declare const EMAIL_OPT_OUT_REASONS: readonly ["unsubscribe", "spamReport", "bounce"];
 declare const defs: {
     readonly $schema: "http://json-schema.org/draft-07/schema";
     readonly $id: "definitions.json";
@@ -208,6 +211,61 @@ declare const defs: {
                     readonly type: "integer";
                     readonly minimum: 0;
                 };
+                readonly optedOut: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "Recipients skipped because they opted out of this channel. Counted apart from `failed`; absent on sends recorded before opt-out tracking.";
+                };
+            };
+        };
+        readonly consent: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly sms: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["optedOutAt"];
+                    readonly properties: {
+                        readonly optedOutAt: {
+                            readonly anyOf: readonly [{
+                                readonly type: readonly ["string", "object"];
+                                readonly format: "date-time";
+                            }, {
+                                readonly type: "null";
+                            }];
+                            readonly description: "When the person opted out of this channel; null while they are reachable.";
+                        };
+                        readonly reason: {
+                            readonly type: "string";
+                            readonly enum: readonly ["stop", "vendor"];
+                        };
+                        readonly lastOptOutNoticeAt: {
+                            readonly type: readonly ["string", "object"];
+                            readonly format: "date-time";
+                        };
+                    };
+                };
+                readonly email: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["optedOutAt"];
+                    readonly properties: {
+                        readonly optedOutAt: {
+                            readonly anyOf: readonly [{
+                                readonly type: readonly ["string", "object"];
+                                readonly format: "date-time";
+                            }, {
+                                readonly type: "null";
+                            }];
+                            readonly description: "When the person opted out of this channel; null while they are reachable.";
+                        };
+                        readonly reason: {
+                            readonly type: "string";
+                            readonly enum: readonly ["unsubscribe", "spamReport", "bounce"];
+                        };
+                    };
+                };
             };
         };
         readonly audience: {
@@ -248,7 +306,7 @@ declare const defs: {
                     readonly description: "Which groups of the external SIS roster were included. Human-triggered sends only; an Automation can never set it.";
                     readonly items: {
                         readonly type: "string";
-                        readonly enum: readonly ["students", "parents"];
+                        readonly enum: readonly ["students", "parents", "staff"];
                     };
                 };
                 readonly emergencyContacts: {
@@ -284,6 +342,11 @@ declare const defs: {
                                     readonly type: "integer";
                                     readonly minimum: 0;
                                 };
+                                readonly optedOut: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                    readonly description: "Recipients skipped because they opted out of this channel. Counted apart from `failed`; absent on sends recorded before opt-out tracking.";
+                                };
                             };
                         };
                         readonly external: {
@@ -303,6 +366,11 @@ declare const defs: {
                                     readonly type: "integer";
                                     readonly minimum: 0;
                                 };
+                                readonly optedOut: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                    readonly description: "Recipients skipped because they opted out of this channel. Counted apart from `failed`; absent on sends recorded before opt-out tracking.";
+                                };
                                 readonly byChannel: {
                                     readonly type: "object";
                                     readonly additionalProperties: false;
@@ -325,6 +393,11 @@ declare const defs: {
                                                     readonly type: "integer";
                                                     readonly minimum: 0;
                                                 };
+                                                readonly optedOut: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                    readonly description: "Recipients skipped because they opted out of this channel. Counted apart from `failed`; absent on sends recorded before opt-out tracking.";
+                                                };
                                             };
                                         };
                                         readonly email: {
@@ -344,6 +417,11 @@ declare const defs: {
                                                     readonly type: "integer";
                                                     readonly minimum: 0;
                                                 };
+                                                readonly optedOut: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                    readonly description: "Recipients skipped because they opted out of this channel. Counted apart from `failed`; absent on sends recorded before opt-out tracking.";
+                                                };
                                             };
                                         };
                                     };
@@ -368,6 +446,11 @@ declare const defs: {
                                     readonly type: "integer";
                                     readonly minimum: 0;
                                 };
+                                readonly optedOut: {
+                                    readonly type: "integer";
+                                    readonly minimum: 0;
+                                    readonly description: "Recipients skipped because they opted out of this channel. Counted apart from `failed`; absent on sends recorded before opt-out tracking.";
+                                };
                                 readonly byChannel: {
                                     readonly type: "object";
                                     readonly additionalProperties: false;
@@ -390,6 +473,11 @@ declare const defs: {
                                                     readonly type: "integer";
                                                     readonly minimum: 0;
                                                 };
+                                                readonly optedOut: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                    readonly description: "Recipients skipped because they opted out of this channel. Counted apart from `failed`; absent on sends recorded before opt-out tracking.";
+                                                };
                                             };
                                         };
                                         readonly email: {
@@ -409,6 +497,11 @@ declare const defs: {
                                                     readonly type: "integer";
                                                     readonly minimum: 0;
                                                 };
+                                                readonly optedOut: {
+                                                    readonly type: "integer";
+                                                    readonly minimum: 0;
+                                                    readonly description: "Recipients skipped because they opted out of this channel. Counted apart from `failed`; absent on sends recorded before opt-out tracking.";
+                                                };
                                             };
                                         };
                                     };

package/dist/schemas/definitions.js

@@ -31,10 +31,15 @@ const PLATFORM_ROLE_NAMES = [
 /**
 * The people outside the platform a broadcast may name, sourced from the SIS
 * roster. `students` is every system user the SIS marks as a Student;
-* `parents` is everybody else on the roster — every emergency-contact
+* `staff` is everybody synced with nothing but the Staff role (faculty and
+* staff); `parents` is everybody else on the roster — every emergency-contact
 * relationship the source system carries, whatever it calls it.
 */
-const EXTERNAL_AUDIENCE_GROUPS = ["students", "parents"];
+const EXTERNAL_AUDIENCE_GROUPS = [
+	"students",
+	"parents",
+	"staff"
+];
 const deliveryCountsNode = {
 	type: "object",
 	additionalProperties: false,
@@ -55,9 +60,28 @@ const deliveryCountsNode = {
 		failed: {
 			type: "integer",
 			minimum: 0
+		},
+		optedOut: {
+			type: "integer",
+			minimum: 0,
+			description: "Recipients skipped because they opted out of this channel. Counted apart from `failed`; absent on sends recorded before opt-out tracking."
 		}
 	}
 };
+const SMS_OPT_OUT_REASONS = ["stop", "vendor"];
+const EMAIL_OPT_OUT_REASONS = [
+	"unsubscribe",
+	"spamReport",
+	"bounce"
+];
+const dateNode = {
+	type: ["string", "object"],
+	format: "date-time"
+};
+const optedOutAtNode = {
+	anyOf: [dateNode, { type: "null" }],
+	description: "When the person opted out of this channel; null while they are reachable."
+};
 const defs = {
 	$schema: "http://json-schema.org/draft-07/schema",
 	$id: "definitions.json",
@@ -347,6 +371,37 @@ const defs = {
 			enum: NOTIFICATION_CHANNELS
 		},
 		deliveryCounts: deliveryCountsNode,
+		consent: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				sms: {
+					type: "object",
+					additionalProperties: false,
+					required: ["optedOutAt"],
+					properties: {
+						optedOutAt: optedOutAtNode,
+						reason: {
+							type: "string",
+							enum: SMS_OPT_OUT_REASONS
+						},
+						lastOptOutNoticeAt: dateNode
+					}
+				},
+				email: {
+					type: "object",
+					additionalProperties: false,
+					required: ["optedOutAt"],
+					properties: {
+						optedOutAt: optedOutAtNode,
+						reason: {
+							type: "string",
+							enum: EMAIL_OPT_OUT_REASONS
+						}
+					}
+				}
+			}
+		},
 		audience: {
 			type: "object",
 			additionalProperties: false,
@@ -449,6 +504,6 @@ const defs = {
 	}
 };
 //#endregion
-export { EXTERNAL_AUDIENCE_GROUPS, NOTIFICATION_CHANNELS, PLATFORM_ROLE_NAMES, TICKET_NOTIFICATION_EVENTS, defs as default, defs as definitionsSchema };
+export { EMAIL_OPT_OUT_REASONS, EXTERNAL_AUDIENCE_GROUPS, NOTIFICATION_CHANNELS, PLATFORM_ROLE_NAMES, SMS_OPT_OUT_REASONS, TICKET_NOTIFICATION_EVENTS, defs as default, defs as definitionsSchema };
 
 //# sourceMappingURL=definitions.js.map