@kohost/api-client 7.22.0 → 7.23.0

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.\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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"}
+{"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)`, a ticket-less line (`adhoc`, or `contract` for an\n// entry a Service contract minted) 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\", \"contract\"],\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. `contract` is a \" +\n        \"costs-collection entry a Service contract minted; it bills by the \" +\n        \"same rules as `adhoc`.\",\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 a \" +\n        \"ticket-less line. Internal, redacted org-side.\",\n    },\n    serviceContractId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The Service contract that minted the claimed entry. Null on every \" +\n        \"other line. Customer-facing: the org bill links the line to the \" +\n        \"contract it recurs under.\",\n    },\n    serviceContractName: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The contract's name, snapshotted at mark-sent so a sent bill reads \" +\n        \"the same after the contract is renamed. Null while drafting, when \" +\n        \"it live-reads from the contract.\",\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/cost.d.ts

@@ -186,10 +186,45 @@ export declare const costSchema: {
         };
         readonly source: {
             readonly type: "string";
-            readonly enum: readonly ["adhoc"];
+            readonly enum: readonly ["adhoc", "contract"];
             readonly default: "adhoc";
             readonly description: string;
         };
+        readonly serviceContractId: {
+            readonly type: readonly ["string", "null"];
+            readonly default: null;
+            readonly description: string;
+        };
+        readonly splitId: {
+            readonly type: readonly ["string", "null"];
+            readonly default: null;
+            readonly description: "The customer split the entry was minted for. Set once at mint.";
+        };
+        readonly periodStart: {
+            readonly anyOf: readonly [{
+                readonly $ref: "definitions.json#/definitions/date";
+            }, {
+                readonly type: "null";
+            }];
+            readonly default: null;
+            readonly description: string;
+        };
+        readonly customerPeriodStarts: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly items: {
+                readonly $ref: "definitions.json#/definitions/date";
+            };
+            readonly description: string;
+        };
+        readonly vendorPeriodStarts: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly items: {
+                readonly $ref: "definitions.json#/definitions/date";
+            };
+            readonly description: string;
+        };
         readonly organizationId: {
             readonly type: "string";
             readonly description: string;

package/dist/schemas/cost.js

@@ -17,9 +17,36 @@ const costSchema = {
 		},
 		source: {
 			type: "string",
-			enum: ["adhoc"],
+			enum: ["adhoc", "contract"],
 			default: "adhoc",
-			description: "How the entry came to be recorded. Only `adhoc` today, a biller typing in a charge; the enum is what lets a later importer or integration land in the same collection without a second one. A ticket cost entry carries no source: living on the ticket is what says where it came from."
+			description: "How the entry came to be recorded: `adhoc` when a biller typed in a charge, `contract` when a Service contract minted it for a line period. A contract entry's price is fixed by the contract: it skips the below-cost checks, and one priced at zero is never billed. A ticket cost entry carries no source: living on the ticket is what says where it came from."
+		},
+		serviceContractId: {
+			type: ["string", "null"],
+			default: null,
+			description: "The Service contract that minted the entry. Set once at mint and never edited; null on an ad hoc cost."
+		},
+		splitId: {
+			type: ["string", "null"],
+			default: null,
+			description: "The customer split the entry was minted for. Set once at mint."
+		},
+		periodStart: {
+			anyOf: [{ $ref: "definitions.json#/definitions/date" }, { type: "null" }],
+			default: null,
+			description: "The first day (UTC) of the line period the entry was minted for. With the contract and split it is the slot a line occupies, so a line is never minted twice."
+		},
+		customerPeriodStarts: {
+			type: "array",
+			default: [],
+			items: { $ref: "definitions.json#/definitions/date" },
+			description: "The first day (UTC) of each customer period whose price landed on this line: none or one. Empty on an ad hoc cost."
+		},
+		vendorPeriodStarts: {
+			type: "array",
+			default: [],
+			items: { $ref: "definitions.json#/definitions/date" },
+			description: "The first day (UTC) of each vendor period whose invoice day falls in this line, so its vendor amount landed here. Empty on an ad hoc cost and on a line whose vendor side is a settled zero."
 		},
 		organizationId: {
 			type: "string",

package/dist/schemas/cost.js.map

@@ -1 +1 @@
-{"version":3,"file":"cost.js","names":[],"sources":["../../.generated/schemas/cost.ts"],"sourcesContent":["import defs, { ISODateString } from \"./definitions\";\nimport type { FromSchema } from \"json-schema-to-ts\";\nimport { costEntryProperties, costEntryRequired } from \"./costEntry\";\nimport { mediaFileSchema } from \"./mediaFile\";\n\nexport const costSchema = {\n  $schema: \"http://json-schema.org/draft-07/schema\",\n  $id: \"cost.json\",\n  title: \"Cost\",\n  description:\n    \"A OneBill cost entry that no ticket carries: a recurring vendor charge, \" +\n    \"an expense found while reconciling an invoice, a pass-through cost. It \" +\n    \"shares the money shape and reconciliation lifecycle of a ticket cost \" +\n    \"entry and moves through the uninvoiced pool the same way, but because no \" +\n    \"ticket carries it the DNE approval gate never applies. Stored \" +\n    \"platform-wide beside bills and stamped with its organization.\",\n  type: \"object\",\n  required: [...costEntryRequired, \"organizationId\"],\n  additionalProperties: false,\n  properties: {\n    ...costEntryProperties,\n    type: {\n      type: \"string\",\n      enum: [\"cost\"],\n      default: \"cost\",\n    },\n    source: {\n      type: \"string\",\n      enum: [\"adhoc\"],\n      default: \"adhoc\",\n      description:\n        \"How the entry came to be recorded. Only `adhoc` today, a biller \" +\n        \"typing in a charge; the enum is what lets a later importer or \" +\n        \"integration land in the same collection without a second one. A \" +\n        \"ticket cost entry carries no source: living on the ticket is what \" +\n        \"says where it came from.\",\n    },\n    organizationId: {\n      type: \"string\",\n      description:\n        \"The organization the cost is billed to. These entries live in one \" +\n        \"admin-database collection across every organization, so each \" +\n        \"carries its owner explicitly — stamped from the request context at \" +\n        \"creation, never client-supplied.\",\n    },\n    propertyId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The property the cost is attributed to, when it concerns one.\",\n    },\n    createdBy: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The ID of the billing staff member who recorded the entry. Null \" +\n        \"when the write was not user-attributable.\",\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 CostSchema = FromSchema<\n  typeof costSchema,\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 entry of a cost's append-only billing review history. */\nexport type CostBillingReviewEntry = NonNullable<\n  CostSchema[\"billingReview\"]\n>[number];\n"],"mappings":";;AAKA,MAAa,aAAa;CACxB,SAAS;CACT,KAAK;CACL,OAAO;CACP,aACE;CAMF,MAAM;CACN,UAAU,CAAC,GAAG,mBAAmB,gBAAgB;CACjD,sBAAsB;CACtB,YAAY;EACV,GAAG;EACH,MAAM;GACJ,MAAM;GACN,MAAM,CAAC,MAAM;GACb,SAAS;EACX;EACA,QAAQ;GACN,MAAM;GACN,MAAM,CAAC,OAAO;GACd,SAAS;GACT,aACE;EAKJ;EACA,gBAAgB;GACd,MAAM;GACN,aACE;EAIJ;EACA,YAAY;GACV,MAAM,CAAC,UAAU,MAAM;GACvB,SAAS;GACT,aACE;EACJ;EACA,WAAW;GACT,MAAM,CAAC,UAAU,MAAM;GACvB,SAAS;GACT,aACE;EAEJ;EACA,WAAW,EACT,MAAM,qCACR;EACA,WAAW,EACT,MAAM,qCACR;CACF;AACF"}
+{"version":3,"file":"cost.js","names":[],"sources":["../../.generated/schemas/cost.ts"],"sourcesContent":["import defs, { ISODateString } from \"./definitions\";\nimport type { FromSchema } from \"json-schema-to-ts\";\nimport { costEntryProperties, costEntryRequired } from \"./costEntry\";\nimport { mediaFileSchema } from \"./mediaFile\";\n\nexport const costSchema = {\n  $schema: \"http://json-schema.org/draft-07/schema\",\n  $id: \"cost.json\",\n  title: \"Cost\",\n  description:\n    \"A OneBill cost entry that no ticket carries: a recurring vendor charge, \" +\n    \"an expense found while reconciling an invoice, a pass-through cost. It \" +\n    \"shares the money shape and reconciliation lifecycle of a ticket cost \" +\n    \"entry and moves through the uninvoiced pool the same way, but because no \" +\n    \"ticket carries it the DNE approval gate never applies. Stored \" +\n    \"platform-wide beside bills and stamped with its organization.\",\n  type: \"object\",\n  required: [...costEntryRequired, \"organizationId\"],\n  additionalProperties: false,\n  properties: {\n    ...costEntryProperties,\n    type: {\n      type: \"string\",\n      enum: [\"cost\"],\n      default: \"cost\",\n    },\n    source: {\n      type: \"string\",\n      enum: [\"adhoc\", \"contract\"],\n      default: \"adhoc\",\n      description:\n        \"How the entry came to be recorded: `adhoc` when a biller typed in a \" +\n        \"charge, `contract` when a Service contract minted it for a line \" +\n        \"period. A contract entry's price is fixed by the contract: it skips \" +\n        \"the below-cost checks, and one priced at zero is never billed. A \" +\n        \"ticket cost entry carries no source: living on the ticket is what \" +\n        \"says where it came from.\",\n    },\n    serviceContractId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The Service contract that minted the entry. Set once at mint and \" +\n        \"never edited; null on an ad hoc cost.\",\n    },\n    splitId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The customer split the entry was minted for. Set once at mint.\",\n    },\n    periodStart: {\n      anyOf: [{ $ref: \"definitions.json#/definitions/date\" }, { type: \"null\" }],\n      default: null,\n      description:\n        \"The first day (UTC) of the line period the entry was minted for. \" +\n        \"With the contract and split it is the slot a line occupies, so a \" +\n        \"line is never minted twice.\",\n    },\n    customerPeriodStarts: {\n      type: \"array\",\n      default: [],\n      items: { $ref: \"definitions.json#/definitions/date\" },\n      description:\n        \"The first day (UTC) of each customer period whose price landed on \" +\n        \"this line: none or one. Empty on an ad hoc cost.\",\n    },\n    vendorPeriodStarts: {\n      type: \"array\",\n      default: [],\n      items: { $ref: \"definitions.json#/definitions/date\" },\n      description:\n        \"The first day (UTC) of each vendor period whose invoice day falls \" +\n        \"in this line, so its vendor amount landed here. Empty on an ad hoc \" +\n        \"cost and on a line whose vendor side is a settled zero.\",\n    },\n    organizationId: {\n      type: \"string\",\n      description:\n        \"The organization the cost is billed to. These entries live in one \" +\n        \"admin-database collection across every organization, so each \" +\n        \"carries its owner explicitly — stamped from the request context at \" +\n        \"creation, never client-supplied.\",\n    },\n    propertyId: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The property the cost is attributed to, when it concerns one.\",\n    },\n    createdBy: {\n      type: [\"string\", \"null\"],\n      default: null,\n      description:\n        \"The ID of the billing staff member who recorded the entry. Null \" +\n        \"when the write was not user-attributable.\",\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 CostSchema = FromSchema<\n  typeof costSchema,\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 entry of a cost's append-only billing review history. */\nexport type CostBillingReviewEntry = NonNullable<\n  CostSchema[\"billingReview\"]\n>[number];\n"],"mappings":";;AAKA,MAAa,aAAa;CACxB,SAAS;CACT,KAAK;CACL,OAAO;CACP,aACE;CAMF,MAAM;CACN,UAAU,CAAC,GAAG,mBAAmB,gBAAgB;CACjD,sBAAsB;CACtB,YAAY;EACV,GAAG;EACH,MAAM;GACJ,MAAM;GACN,MAAM,CAAC,MAAM;GACb,SAAS;EACX;EACA,QAAQ;GACN,MAAM;GACN,MAAM,CAAC,SAAS,UAAU;GAC1B,SAAS;GACT,aACE;EAMJ;EACA,mBAAmB;GACjB,MAAM,CAAC,UAAU,MAAM;GACvB,SAAS;GACT,aACE;EAEJ;EACA,SAAS;GACP,MAAM,CAAC,UAAU,MAAM;GACvB,SAAS;GACT,aACE;EACJ;EACA,aAAa;GACX,OAAO,CAAC,EAAE,MAAM,qCAAqC,GAAG,EAAE,MAAM,OAAO,CAAC;GACxE,SAAS;GACT,aACE;EAGJ;EACA,sBAAsB;GACpB,MAAM;GACN,SAAS,CAAC;GACV,OAAO,EAAE,MAAM,qCAAqC;GACpD,aACE;EAEJ;EACA,oBAAoB;GAClB,MAAM;GACN,SAAS,CAAC;GACV,OAAO,EAAE,MAAM,qCAAqC;GACpD,aACE;EAGJ;EACA,gBAAgB;GACd,MAAM;GACN,aACE;EAIJ;EACA,YAAY;GACV,MAAM,CAAC,UAAU,MAAM;GACvB,SAAS;GACT,aACE;EACJ;EACA,WAAW;GACT,MAAM,CAAC,UAAU,MAAM;GACvB,SAAS;GACT,aACE;EAEJ;EACA,WAAW,EACT,MAAM,qCACR;EACA,WAAW,EACT,MAAM,qCACR;CACF;AACF"}

package/dist/schemas/index.d.ts

@@ -33,6 +33,7 @@ export { propertySchema, type PropertySchema } from "./property.js";
 export { reservationSchema, type ReservationSchema } from "./reservation.js";
 export { resourceSchema, type ResourceSchema } from "./resource.js";
 export { serverSchema, type ServerSchema } from "./server.js";
+export { serviceContractSchema, type ServiceContractSchema, type ServiceContractCustomerStream, type ServiceContractSplit, type ServiceContractVendorStream, } from "./serviceContract.js";
 export { sessionSchema, type SessionSchema } from "./session.js";
 export { shortLinkSchema, type ShortLinkSchema } from "./shortLink.js";
 export { smsMessageSchema, type SmsMessageSchema } from "./smsMessage.js";

package/dist/schemas/index.js

@@ -33,6 +33,7 @@ import { propertySchema } from "./property.js";
 import { reservationSchema } from "./reservation.js";
 import { resourceSchema } from "./resource.js";
 import { serverSchema } from "./server.js";
+import { serviceContractSchema } from "./serviceContract.js";
 import { sessionSchema } from "./session.js";
 import { shortLinkSchema } from "./shortLink.js";
 import { smsMessageSchema } from "./smsMessage.js";
@@ -48,4 +49,4 @@ import { timeSheetSchema } from "./timeSheet.js";
 import { getters, userSchema } from "./user.js";
 import { vendorSchema } from "./vendor.js";
 import { windowCoveringSchema } from "./windowCovering.js";
-export { alarmSchema, announcementSchema, automationSchema, billSchema, billingCategorySchema, cameraSchema, categorySchema, costSchema, courtesySchema, credentialSchema, departmentSchema, dimmerSchema, discoveredDeviceSchema, emailMessageSchema, energyReportSchema, energyReportShardSchema, gatewaySchema, groupSchema, identificationSchema, integrationSchema, issueSchema, lockSchema, logSchema, methods as mediaFileMethods, mediaFileSchema, mediaSourceSchema, motionSensorSchema, notificationSchema, organizationSchema, paymentSchema, policySchema, productSchema, propertySchema, reservationSchema, resourceSchema, serverSchema, sessionSchema, shortLinkSchema, smsMessageSchema, sosEventSchema, sosTypeSchema, spaceSchema, switchSchema, systemSchema, systemUserSchema, thermostatSchema, ticketSchema, timeSheetSchema, getters as userGetters, userSchema, vendorSchema, windowCoveringSchema };
+export { alarmSchema, announcementSchema, automationSchema, billSchema, billingCategorySchema, cameraSchema, categorySchema, costSchema, courtesySchema, credentialSchema, departmentSchema, dimmerSchema, discoveredDeviceSchema, emailMessageSchema, energyReportSchema, energyReportShardSchema, gatewaySchema, groupSchema, identificationSchema, integrationSchema, issueSchema, lockSchema, logSchema, methods as mediaFileMethods, mediaFileSchema, mediaSourceSchema, motionSensorSchema, notificationSchema, organizationSchema, paymentSchema, policySchema, productSchema, propertySchema, reservationSchema, resourceSchema, serverSchema, serviceContractSchema, sessionSchema, shortLinkSchema, smsMessageSchema, sosEventSchema, sosTypeSchema, spaceSchema, switchSchema, systemSchema, systemUserSchema, thermostatSchema, ticketSchema, timeSheetSchema, getters as userGetters, userSchema, vendorSchema, windowCoveringSchema };

package/dist/schemas/serviceContract.d.ts

@@ -0,0 +1,272 @@
+import defs, { ISODateString } from "./definitions.js";
+import type { FromSchema } from "json-schema-to-ts";
+import { mediaFileSchema } from "./mediaFile.js";
+export declare const serviceContractSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema";
+    readonly $id: "serviceContract.json";
+    readonly title: "Service Contract";
+    readonly description: string;
+    readonly type: "object";
+    readonly required: readonly ["id", "type", "organizationId", "name", "startsAt", "customer", "status"];
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly id: {
+            readonly $ref: "definitions.json#/definitions/id";
+        };
+        readonly type: {
+            readonly type: "string";
+            readonly enum: readonly ["serviceContract"];
+            readonly default: "serviceContract";
+        };
+        readonly organizationId: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly reference: {
+            readonly type: readonly ["string", "null"];
+            readonly default: null;
+            readonly description: "The vendor's own contract number.";
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly default: "";
+            readonly description: string;
+        };
+        readonly startsAt: {
+            readonly $ref: "definitions.json#/definitions/date";
+        };
+        readonly endsAt: {
+            readonly anyOf: readonly [{
+                readonly $ref: "definitions.json#/definitions/date";
+            }, {
+                readonly type: "null";
+            }];
+            readonly default: null;
+            readonly description: "Null on an open-ended contract.";
+        };
+        readonly customer: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly description: string;
+            readonly required: readonly ["amount", "cadence", "startsAt", "splits"];
+            readonly properties: {
+                readonly amount: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: "The per-period total, in integer cents.";
+                };
+                readonly cadence: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["months"];
+                    readonly properties: {
+                        readonly months: {
+                            readonly type: "integer";
+                            readonly enum: readonly [1, 3, 6, 12];
+                            readonly description: "Length of one period in whole months.";
+                        };
+                    };
+                };
+                readonly startsAt: {
+                    readonly $ref: "definitions.json#/definitions/date";
+                    readonly description: string;
+                };
+                readonly nextPeriodStartsAt: {
+                    readonly anyOf: readonly [{
+                        readonly $ref: "definitions.json#/definitions/date";
+                    }, {
+                        readonly type: "null";
+                    }];
+                    readonly default: null;
+                    readonly description: string;
+                };
+                readonly splits: {
+                    readonly type: "array";
+                    readonly default: readonly [];
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["id", "propertyId", "amount"];
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly propertyId: {
+                                readonly type: readonly ["string", "null"];
+                                readonly description: "Null on an org-wide split.";
+                            };
+                            readonly label: {
+                                readonly type: readonly ["string", "null"];
+                                readonly default: null;
+                            };
+                            readonly amount: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                                readonly description: string;
+                            };
+                            readonly categoryId: {
+                                readonly type: readonly ["string", "null"];
+                                readonly default: null;
+                                readonly description: "The billing category the split's Contract costs arrive under.";
+                            };
+                            readonly vendorAmount: {
+                                readonly type: readonly ["integer", "null"];
+                                readonly minimum: 0;
+                                readonly default: null;
+                                readonly description: string;
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly vendor: {
+            readonly anyOf: readonly [{
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly description: string;
+                readonly required: readonly ["amount", "cadence", "startsAt", "vendorId"];
+                readonly properties: {
+                    readonly amount: {
+                        readonly type: "integer";
+                        readonly minimum: 0;
+                        readonly description: "The per-period total, in integer cents.";
+                    };
+                    readonly cadence: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["months"];
+                        readonly properties: {
+                            readonly months: {
+                                readonly type: "integer";
+                                readonly enum: readonly [1, 3, 6, 12];
+                                readonly description: "Length of one period in whole months.";
+                            };
+                        };
+                    };
+                    readonly startsAt: {
+                        readonly $ref: "definitions.json#/definitions/date";
+                        readonly description: string;
+                    };
+                    readonly nextPeriodStartsAt: {
+                        readonly anyOf: readonly [{
+                            readonly $ref: "definitions.json#/definitions/date";
+                        }, {
+                            readonly type: "null";
+                        }];
+                        readonly default: null;
+                        readonly description: string;
+                    };
+                    readonly vendorId: {
+                        readonly type: readonly ["string", "null"];
+                        readonly default: null;
+                        readonly description: "Required to activate.";
+                    };
+                    readonly invoicing: {
+                        readonly type: "string";
+                        readonly enum: readonly ["advance", "arrears"];
+                        readonly default: "arrears";
+                        readonly description: string;
+                    };
+                };
+            }, {
+                readonly type: "null";
+            }];
+            readonly default: null;
+            readonly description: "Null on a contract with no vendor stream.";
+        };
+        readonly approval: {
+            readonly type: readonly ["object", "null"];
+            readonly default: null;
+            readonly additionalProperties: false;
+            readonly description: "The organization's written approval of the recurring charge.";
+            readonly properties: {
+                readonly file: {
+                    readonly anyOf: readonly [{
+                        readonly $ref: "mediaFile.json";
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+                readonly approvedBy: {
+                    readonly type: readonly ["object", "null"];
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["name"];
+                    readonly properties: {
+                        readonly name: {
+                            readonly type: "string";
+                        };
+                        readonly title: {
+                            readonly type: readonly ["string", "null"];
+                        };
+                    };
+                };
+                readonly approvedAt: {
+                    readonly anyOf: readonly [{
+                        readonly $ref: "definitions.json#/definitions/date";
+                    }, {
+                        readonly type: "null";
+                    }];
+                };
+            };
+        };
+        readonly documents: {
+            readonly type: "array";
+            readonly items: {
+                readonly $ref: "mediaFile.json";
+            };
+            readonly default: readonly [];
+        };
+        readonly ticketSchedules: {
+            readonly type: "array";
+            readonly default: readonly [];
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["automationId"];
+                readonly properties: {
+                    readonly automationId: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly ["draft", "active", "ended", "cancelled"];
+            readonly default: "draft";
+        };
+        readonly cancelledReason: {
+            readonly type: readonly ["string", "null"];
+            readonly default: null;
+        };
+        readonly createdBy: {
+            readonly type: readonly ["string", "null"];
+            readonly default: null;
+        };
+        readonly createdAt: {
+            readonly $ref: "definitions.json#/definitions/date";
+        };
+        readonly updatedAt: {
+            readonly $ref: "definitions.json#/definitions/date";
+        };
+    };
+};
+export type ServiceContractSchema = FromSchema<typeof serviceContractSchema, {
+    references: [typeof defs, typeof mediaFileSchema];
+    deserialize: [
+        {
+            pattern: {
+                format: "date-time";
+            };
+            output: Date | ISODateString;
+        }
+    ];
+}>;
+export type ServiceContractCustomerStream = ServiceContractSchema["customer"];
+export type ServiceContractVendorStream = NonNullable<ServiceContractSchema["vendor"]>;
+export type ServiceContractSplit = ServiceContractCustomerStream["splits"][number];