@opencxh/domain 1.286.3 → 1.288.0

package/dist/entities/activity/types.d.ts

@@ -239,6 +239,10 @@ export type InteractionStatus = "open" | "closed" | "snoozed";
 export type InteractionStatusChangedPayload = {
     fromStatus: InteractionStatus;
     toStatus: InteractionStatus;
+    /** Set on a close with a reason: the key, and its label and outcome as they were at that moment. */
+    resolution?: string;
+    resolutionLabel?: string;
+    resolutionPositive?: boolean;
 };
 /**
  * A service target that ran out. Written by the app that owns the clocks, not by comms.

package/dist/entities/agreement/index.d.ts

@@ -0,0 +1,3 @@
+export * from './period';
+export * from './schedule';
+export * from './types';

package/dist/entities/agreement/period.d.ts

@@ -0,0 +1,37 @@
+import { Agreement, AgreementInterval, AgreementLine } from './types';
+/** `a` bills more often than `b`: a monthly line in a yearly agreement would bill 12 at once. */
+export declare function isShorter(a: AgreementInterval, b: AgreementInterval): boolean;
+export interface Period {
+    from: number;
+    /** Exclusive. */
+    to: number;
+}
+/**
+ * The period of `interval` that contains `at`, on calendar boundaries.
+ *
+ * ponytail: UTC boundaries — a call at 00:30 Amsterdam time on the 1st lands in the previous
+ * month. Pass the organisation's zone offset here when that difference starts to matter.
+ */
+export declare function periodAt(at: number, interval: AgreementInterval): Period;
+/** When a line runs: its own dates inside the agreement's term. `to` absent = open-ended. */
+export declare function lineTerm(agreement: Pick<Agreement, "startsAt" | "endsAt">, line: Pick<AgreementLine, "startsAt" | "endsAt">): {
+    from: number;
+    to?: number;
+};
+/** The part of `period` a term covers, or `null` when they do not meet. */
+export declare function overlap(term: {
+    from: number;
+    to?: number;
+}, period: Period): Period | null;
+/**
+ * How much of a period a fixed line bills: 1 for a whole period, 0 when it ran only part of it
+ * and `proration` is off, the share of days when it is on (12 of 31 days = 12/31).
+ */
+export declare function periodShare(term: {
+    from: number;
+    to?: number;
+}, period: Period, proration: boolean): number;
+export type LineStatus = "planned" | "active" | "ended";
+export declare function lineStatus(agreement: Pick<Agreement, "startsAt" | "endsAt">, line: Pick<AgreementLine, "startsAt" | "endsAt">, now: number): LineStatus;
+/** Lines that run at `at` or will later — the ones whose accounts are taken. */
+export declare function currentLines<T extends Pick<AgreementLine, "startsAt" | "endsAt">>(agreement: Pick<Agreement, "startsAt" | "endsAt">, lines: readonly T[], at: number): T[];

package/dist/entities/agreement/period.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/agreement/schedule.d.ts

@@ -0,0 +1,80 @@
+import { Cents } from '../money/money';
+import { Period } from './period';
+import { Agreement, AgreementLine, LineBilling, LineRhythm } from './types';
+/** A fixed line keeps its own rhythm; usage follows the agreement, it is read per period. */
+export declare function rhythmOf(agreement: Pick<Agreement, "interval">, line: AgreementLine): LineRhythm;
+/** Fixed lines bill in advance unless told otherwise; usage is only known afterwards. */
+export declare function timingOf(line: AgreementLine): LineBilling;
+/** An invoice line an agreement wrote earlier, as far as scheduling cares. */
+export interface BilledLine {
+    agreementLineId: string;
+    servicePeriod: Period;
+    quantity: number;
+    unitPriceCents: Cents;
+    correction?: boolean;
+}
+/** One window of one line that is due and not yet on an invoice. */
+export interface Charge {
+    lineId: string;
+    /** The line's whole window in its rhythm: what "billed" is matched on. */
+    window: Period;
+    /** The part of it the line ran, which the invoice line says it covers. */
+    part: Period;
+    /** Fixed lines: the share of the window billed, 1 unless prorated. Usage: 1. */
+    share: number;
+    timing: LineBilling;
+}
+/** A window billed before the line's term changed, settled at the price it was billed at. */
+export interface Correction {
+    lineId: string;
+    window: Period;
+    /** The days added (positive quantity) or taken off (negative). */
+    part: Period;
+    quantity: number;
+    unitPriceCents: Cents;
+}
+/**
+ * What an agreement owes on `now`, per line: every window that is due minus the windows an
+ * invoice already covers, plus corrections for billed windows whose days changed since.
+ *
+ * Due: a window in advance on its first day, in arrears after its last, plus grace either way,
+ * so "fixed October" and "usage September" land on the same run. A window a line only partly
+ * runs, and a correction, wait for the window's end — they ride along with the next regular
+ * invoice instead of producing one of their own.
+ */
+export declare function dueCharges(agreement: Pick<Agreement, "startsAt" | "endsAt" | "interval" | "graceDays" | "proration">, lines: readonly AgreementLine[], billed: readonly BilledLine[], now: number): {
+    charges: Charge[];
+    corrections: Correction[];
+};
+export interface RunSpan {
+    timing: LineBilling;
+    from: number;
+    /** Exclusive. */
+    to: number;
+}
+/**
+ * What a run or an invoice covers, for a list: per timing the first and last service day, and how
+ * many corrections — "Vooraf okt · Achteraf sep · 1 correctie".
+ */
+export declare function runSpans(lines: readonly {
+    timing: LineBilling;
+    servicePeriod: Period;
+    correction?: boolean;
+}[]): {
+    spans: RunSpan[];
+    corrections: number;
+};
+export type DueStatus = "ready" | "needs_quantity" | "unrated" | "error";
+/** One row of "to bill": what a run on this agreement would do right now. */
+export interface DueRun {
+    agreementId: string;
+    title: string;
+    companyId: string;
+    status: DueStatus;
+    netCents: number;
+    spans: RunSpan[];
+    corrections: number;
+    needsQuantity: number;
+    unrated: number;
+    error?: string;
+}

package/dist/entities/agreement/schedule.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/agreement/types.d.ts

@@ -0,0 +1,167 @@
+import { PriceBand } from '../catalog/rating';
+import { Cents } from '../money/money';
+/**
+ * A standing arrangement with a customer that bills every period: number rental, licences, and
+ * the usage of an account at a source (calls on a PBX tenant).
+ *
+ * It does not hold the invoices it produced. Each invoice line it wrote carries the agreement line
+ * and the service period it covers, and those lines are the whole "what was billed" state.
+ */
+export interface Agreement {
+    id: string;
+    organizationId: string;
+    title: string;
+    companyId: string;
+    businessEntityId?: string;
+    currency: string;
+    status: AgreementStatus;
+    /** Epoch ms. The first period starts on the interval boundary at or before this. */
+    startsAt: number;
+    /** Exclusive: the first moment it no longer runs. A screen shows the day before as "last day". */
+    endsAt?: number;
+    /**
+     * A fixed line that starts or stops inside a period: `false` bills whole periods only (from the
+     * first full one, up to the last full one); `true` bills the days it ran, pro rata, and settles
+     * a window billed in advance when the line's term changes afterwards.
+     */
+    proration?: boolean;
+    interval: AgreementInterval;
+    /**
+     * Days after a window opens (in advance) or closes (in arrears) before it is due: late call
+     * records still arrive, and both land on the same run.
+     */
+    graceDays: number;
+    paymentTermKey?: string;
+    /**
+     * The account usage is read from (a PBX tenant). Usage lines without an account of their own
+     * take this one; a line may still name another, say texts from a second source.
+     */
+    sourceAccount?: UsageAccountRef;
+    lines: AgreementLine[];
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export type AgreementStatus = "draft" | "active" | "ended";
+export type AgreementInterval = "month" | "quarter" | "year";
+export interface AgreementLine {
+    id: string;
+    productId: string;
+    /** Copied from the product, like a transaction line: the agreement must stay readable. */
+    name: string;
+    /**
+     * Where the quantity comes from. How it is priced is the product's business (`pricing`), and a
+     * price for this agreement is a price agreement with `contractId` = the agreement.
+     */
+    quantity: LineQuantity;
+    /** Taken off the quantity before the price: "the first 5 are included". */
+    included?: number;
+    /**
+     * When this line runs, inside the agreement's own term. Absent = with the agreement. A change
+     * "from 1 May" ends one line and starts another, so billed periods keep saying what they said.
+     */
+    startsAt?: number;
+    /** Exclusive, like `Agreement.endsAt`. */
+    endsAt?: number;
+    /** A fixed line only: usage is known after the period, so it always bills in arrears. */
+    billing?: LineBilling;
+    /** A fixed line's own rhythm; never shorter than the agreement's. Absent = the agreement's. */
+    every?: LineRhythm;
+}
+export type LineBilling = "advance" | "arrears";
+export type LineRhythm = AgreementInterval | "once";
+export type LineQuantity = {
+    from: "fixed";
+    value: number;
+}
+/** Entered per period, when billing. */
+ | {
+    from: "manual";
+}
+/** Read from a usage source. No `accountRef` = the agreement's `sourceAccount`. */
+ | {
+    from: "meter";
+    app: string;
+    meter: string;
+    accountRef?: string;
+};
+/** An account at a usage source: which app reports it, and its id there. */
+export interface UsageAccountRef {
+    app: string;
+    accountRef: string;
+}
+/** The account a meter line reads, own or inherited. `null` when neither names one. */
+export declare function usageAccountOf(agreement: Pick<Agreement, "sourceAccount">, line: AgreementLine): UsageAccountRef | null;
+/** Every account an agreement reads usage from, deduplicated. */
+export declare function usageAccountsOf(agreement: Pick<Agreement, "sourceAccount" | "lines">): UsageAccountRef[];
+export interface SaveAgreementRequest extends Partial<Omit<Agreement, "id" | "organizationId" | "createdBy" | "createdAt" | "updatedAt">> {
+    id?: string;
+}
+/** What a billing run would put on the invoice, before anything is written. */
+export interface AgreementRunPreview {
+    /** The moment it was computed for: everything due by then and not yet billed. */
+    at: number;
+    /** The earliest and latest service day on it. Absent when nothing is due. */
+    covers?: {
+        from: number;
+        to: number;
+    };
+    lines: RunLine[];
+    netCents: Cents;
+    /** Records without a rate, per dimension combination. Billing needs `skipUnrated` then. */
+    unrated: {
+        meter: string;
+        dimensions: Record<string, string>;
+        count: number;
+    }[];
+    /** Quantity keys of manual lines still waiting for a number. Billing refuses until given. */
+    needsQuantity: string[];
+    /** Records seen across all meter lines, rated or not. */
+    records: number;
+}
+export interface RunLine {
+    /** The agreement line it came from; a rated line yields one invoice line per rate. */
+    lineId: string;
+    name: string;
+    productId: string;
+    unitKey: string;
+    taxRateKey: string;
+    quantity: number;
+    unitPriceCents: Cents;
+    priceSourceKey: string;
+    /** What it covers: the part of the line's window it ran. */
+    servicePeriod: {
+        from: number;
+        to: number;
+    };
+    timing: LineBilling;
+    /** Settles a window that was billed before the line's term changed. */
+    correction?: boolean;
+    /** Manual lines: the key its entered quantity travels under — see `quantityKey`. */
+    quantityKey?: string;
+    /** A fixed line that ran part of its window: the share billed. */
+    share?: number;
+    /** Hours read from the time app: the invoice stamps them, so nothing bills them again. */
+    timeEntryIds?: string[];
+    usage?: LineUsage;
+}
+/** Manual quantities are entered per line and window: a catch-up run may ask for two months. */
+export declare function quantityKey(lineId: string, windowFrom: number): string;
+/**
+ * How a usage line was counted, kept on the invoice line. A rated group bills 1 × its total (it
+ * has no whole-cent unit price), so the real quantity and the tier bands live here.
+ */
+export interface LineUsage {
+    from: "manual" | "meter";
+    /** Rated lines: the rate this group is. */
+    rateId?: string;
+    records?: number;
+    /** Aggregated, before `included`. */
+    measured: number;
+    included?: number;
+    /** For display: the meter's display unit (`minute`) or the product's unit. */
+    unit: string;
+    /** Meter units per display unit (60 seconds per minute). */
+    per: number;
+    bands?: PriceBand[];
+}

package/dist/entities/catalog/index.d.ts

@@ -1,3 +1,6 @@
 export * from './codes';
 export * from './pricing';
+export * from './rate-csv';
+export * from './rating';
 export * from './types';
+export * from './usage-source';

package/dist/entities/catalog/pricing.d.ts

@@ -33,14 +33,17 @@ export interface ResolvedPrice {
     sourceKey: string;
     ruleId?: string;
 }
+export declare function resolvePrice(product: Product, ctx: PriceContext, rules: readonly PriceRule[]): ResolvedPrice;
+export interface ResolvedRateCard {
+    rateCardId: string;
+    sourceKey: string;
+    ruleId?: string;
+}
 /**
- * The price for this product, for this customer, at this quantity, on this date.
- *
- * Pure, so the screen can compute along while you type and land on the same cent the server
- * stores. A rule that names neither the product nor its category does not apply, however
- * specific its customer is: a discount on "everything" is a decision, not a price rule.
+ * The rate card a `rated` product is billed on for this customer: the same ladder as a price,
+ * over the rules whose outcome is a card, then the product's own card. `null` = it has none.
  */
-export declare function resolvePrice(product: Product, ctx: PriceContext, rules: readonly PriceRule[]): ResolvedPrice;
+export declare function resolveRateCard(product: Product, ctx: PriceContext, rules: readonly PriceRule[]): ResolvedRateCard | null;
 /** The `priceSourceKey` of a price somebody typed themselves. The ladder never overwrites it. */
 export declare const MANUAL_PRICE_SOURCE = "manual";
 /**

package/dist/entities/catalog/rate-csv.d.ts

@@ -0,0 +1,29 @@
+import { Micros, Rate, RatePrice } from './rating';
+import { UsageMeter } from './usage-source';
+/**
+ * A rate deck as CSV, one rate per line, with columns that follow the meter:
+ *
+ *     label;<one column per dimension>;setup;price[;increment;minimum]
+ *     Nederland mobiel;316;outbound;0,0450;0,0650;60/1;60      (calls: destination, direction)
+ *     Internet uit;eu-west-1;;+12%                              (traffic: region, direction)
+ *
+ * `;` or `,` separated (a Dutch Excel writes `;` because `,` is its decimal mark); a first line
+ * whose price column is not a price is a header. The price is per `meter.display` unit, written
+ * with either decimal mark, or `+12%` for a markup on cost. An empty dimension matches anything.
+ * Increment and minimum only exist when the meter bills per record (`display.per > 1`). Tiers
+ * are edited on screen, not in a file.
+ */
+export interface RateCsvResult {
+    rates: Omit<Rate, "id">[];
+    errors: {
+        line: number;
+        message: string;
+    }[];
+}
+/** `"0,0450"` → 45 000 micros, without a float in between. */
+export declare function parseMicros(value: string): Micros | undefined;
+/** 45 000 micros → `"0,0450"`: at least four decimals, more only when the rate has them. */
+export declare function formatMicros(micros: Micros): string;
+/** `"+12%"` → a markup; a plain amount → a flat price; anything else → `undefined`. */
+export declare function parseRatePrice(value: string): RatePrice | undefined;
+export declare function parseRateCsv(text: string, meter: UsageMeter): RateCsvResult;

package/dist/entities/catalog/rate-csv.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/catalog/rating.d.ts

@@ -0,0 +1,122 @@
+import { Cents } from '../money/money';
+/**
+ * Pricing records on a rate card: a call, a text, a gigabyte of traffic, an hour of compute.
+ *
+ * Each record is matched to one rate on its dimensions; the records of a rate are then summed
+ * (or averaged, per the meter) and priced as a group — flat, tiered, or as a markup on cost.
+ * Carriers and clouds quote in four or five decimals, so rates are in **micros** (millionths of
+ * the currency unit); only a group's total becomes cents.
+ */
+export type Micros = number;
+export declare const MICROS_PER_CENT = 10000;
+/**
+ * One usage record as a source reports it: a real event (a call) or a summary (GB transferred
+ * in a region on one day) — a source with millions of events sends summaries.
+ */
+export interface UsageRecord {
+    id: string;
+    meter: string;
+    /** In the meter's unit: seconds for a call, bytes or GB for traffic, seats for licences. */
+    quantity: number;
+    /** Whatever the meter declares: `direction`, `destination`, `region`, … */
+    dimensions: Record<string, string>;
+    occurredAt: number;
+    /** What the source paid for it. Needed by a markup rate; kept for a later margin view. */
+    costMicros?: Micros;
+}
+/** How a period's records become one number: calls add up, licences take their peak. */
+export type UsageAggregation = "sum" | "max" | "last" | "average";
+export declare function aggregateUsage(records: readonly {
+    quantity: number;
+    occurredAt?: number;
+}[], aggregation: UsageAggregation): number;
+/** `equals` pins a value; `prefix` takes the longest match (a number range, a region family). */
+export type RateMatcher = {
+    equals: string;
+} | {
+    prefix: string;
+};
+export type RatePrice = 
+/** The price of `unitSize` units. */
+{
+    kind: "flat";
+    micros: Micros;
+}
+/**
+ * Bands over the group's quantity. `graduated`: every band at its own price. `volume`: the whole
+ * quantity at the price of the band it lands in. The last band has no `upTo`.
+ */
+ | {
+    kind: "tiered";
+    mode: "graduated" | "volume";
+    tiers: {
+        upTo?: number;
+        micros: Micros;
+    }[];
+}
+/** The source's cost plus a percentage. A record without a cost has no price. */
+ | {
+    kind: "markup";
+    percent: number;
+};
+export interface Rate {
+    /** Unique within its card. */
+    id: string;
+    /** What the invoice line says: "Nederland mobiel", "Internet uit · eu-west-1". */
+    label: string;
+    /** Per dimension. A dimension not named matches anything. */
+    match: Record<string, RateMatcher>;
+    /** Once per record with a quantity above zero. */
+    setupMicros: Micros;
+    price: RatePrice;
+    /** How many meter units a price is for: 60 seconds, 3600 seconds, a million requests. */
+    unitSize: number;
+    /** Rounding per record: 60 / 1 bills the first 60 units whole, then each unit. 1/1 = none. */
+    firstIncrement: number;
+    nextIncrement: number;
+    /** At least this many units per record. */
+    minimum: number;
+    /** Free units per period, taken off the group before its price. */
+    included?: number;
+}
+/** `+31 6-1234`, `0031 61234` and `31612 34` are all `3161234`. */
+export declare function digitsOf(value: string): string;
+export declare function matchRate(record: UsageRecord, rates: readonly Rate[]): Rate | undefined;
+export declare function billedQuantity(quantity: number, rate: Rate): number;
+export interface PriceBand {
+    quantity: number;
+    micros: Micros;
+}
+/** A tiered price over `quantity` meter units, with the bands it used. */
+export declare function tieredMicros(quantity: number, price: Extract<RatePrice, {
+    kind: "tiered";
+}>, unitSize: number): {
+    micros: Micros;
+    bands: PriceBand[];
+};
+export interface RatedGroup {
+    rateId: string;
+    label: string;
+    records: number;
+    /** The records it holds, so an invoice can claim them (time entries). */
+    recordIds: string[];
+    /** After per-record rounding and the meter's aggregation, before `included`. */
+    measured: number;
+    included: number;
+    /** What is priced: `measured - included`, never below zero. */
+    billed: number;
+    micros: Micros;
+    cents: Cents;
+    /** The bands of a tiered price, for the invoice. */
+    bands?: PriceBand[];
+}
+export interface RatingResult {
+    groups: RatedGroup[];
+    /**
+     * Records no rate matched, or matched a markup without a cost. The caller decides, out loud,
+     * whether to bill without them — usage is never silently free.
+     */
+    unrated: UsageRecord[];
+}
+/** A period's records, rated and grouped per rate. Cents are rounded once per group. */
+export declare function rateRecords(records: readonly UsageRecord[], rates: readonly Rate[], aggregation?: UsageAggregation): RatingResult;

package/dist/entities/catalog/rating.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/catalog/types.d.ts

@@ -44,6 +44,13 @@ export interface Product {
      * type: time must not know sales, and several products may share one type (junior/senior).
      */
     workTypeKey?: string;
+    /**
+     * `unit`: a price per unit through the ladder (list price, tiers, customer agreements).
+     * `rated`: every record priced on a rate card by its dimensions (calls, traffic).
+     */
+    pricing?: ProductPricing;
+    /** The default card of a `rated` product. A price agreement may name another. */
+    rateCardId?: string;
     /** See {@link FIXED_UNITS}. Drives the form and the word after the quantity. */
     unitKey: string;
     /** Key into the organisation's VAT table, never the percentage itself. */
@@ -78,7 +85,8 @@ export interface Product {
  * Units follow work's `FIXED_TYPES` pattern: a fixed list plus a namespaced fallback, so an
  * unknown key reads as itself instead of breaking.
  */
-export declare const FIXED_UNITS: readonly ["piece", "hour", "day", "month", "km", "license"];
+export type ProductPricing = "unit" | "rated";
+export declare const FIXED_UNITS: readonly ["piece", "hour", "day", "month", "km", "license", "minute"];
 export type FixedUnit = (typeof FIXED_UNITS)[number];
 /**
  * A price for a customer, a segment or a contract.
@@ -98,9 +106,13 @@ export interface PriceRule {
     segmentKey?: string;
     /** From which quantity. Absent = from one. */
     minQuantity?: number;
-    /** Exactly one of the two. A fixed price beats a discount when both would apply. */
+    /**
+     * Exactly one outcome. A fixed price beats a discount; a rate card is the outcome for a `rated`
+     * product ("this customer calls on Enterprise") and is ignored by the unit ladder.
+     */
     unitPriceCents?: Cents;
     discountPercent?: number;
+    rateCardId?: string;
     currency: string;
     validFrom?: number;
     validTo?: number;
@@ -114,6 +126,29 @@ export interface PriceRule {
     createdBy: string;
     createdAt?: number;
 }
+/**
+ * A price list for usage: which meter it prices, in which currency, from when. The rates travel
+ * separately (`rate-card/:id/rates`) — a carrier's deck has thousands of rows and a list of cards
+ * must not carry them.
+ */
+export interface RateCard {
+    id: string;
+    organizationId: string;
+    name: string;
+    /** The app that reports the usage (`eylo-voip`) and its meter key (`eylo.call`). */
+    sourceApp: string;
+    meter: string;
+    /** Kept with the rates, so the list can show it without loading them. */
+    rateCount?: number;
+    currency: string;
+    validFrom?: number;
+    validTo?: number;
+    businessEntityId?: string;
+    archived?: boolean;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
 /**
  * What the product form sends. Everything optional but the name: the server fills defaults, and
  * a form that has to send a complete product cannot add a variant with two fields.
@@ -125,3 +160,7 @@ export interface SaveProductRequest extends Partial<Omit<Product, "id" | "organi
 export interface SavePriceRuleRequest extends Partial<Omit<PriceRule, "id" | "organizationId" | "createdBy" | "createdAt">> {
     id?: string;
 }
+export interface SaveRateCardRequest extends Partial<Omit<RateCard, "id" | "organizationId" | "createdBy" | "createdAt" | "updatedAt">> {
+    id?: string;
+    name: string;
+}

package/dist/entities/catalog/usage-source.d.ts

@@ -0,0 +1,83 @@
+import { LocaleBundle } from '../../platform/localization';
+import { UsageAggregation, UsageRecord } from './rating';
+/**
+ * Role group of an app whose usage can be billed: calls, texts, gigabytes.
+ *
+ * A constant for the same reason as `ONBOARDING_SOURCE_PROVIDER_GROUP`: an unknown group answers
+ * with an empty list, so a typo reads as "nothing to bill".
+ */
+export declare const USAGE_SOURCE_PROVIDER_GROUP = "usage-source";
+/** Route under the provider scope that returns a period's records. App-only. */
+export declare const USAGE_RECORDS_ROUTE = "/usage/records";
+export interface UsageMeter {
+    /** Namespaced by the owner, like analytics metrics: `eylo.call`, never `call`. */
+    key: string;
+    /** An i18n key from the source's `locales`. */
+    label: string;
+    /** What `UsageRecord.quantity` counts: `second`, `message`, `gigabyte`, `seat`. */
+    unit: string;
+    /**
+     * How a person reads it: `{ unit: "minute", per: 60 }` prices seconds per minute. `per > 1` is
+     * also what makes per-record rounding (60/1) and a minimum worth showing.
+     */
+    display: {
+        unit: string;
+        per: number;
+    };
+    /** How a period's records become one number: calls `sum`, licences `max`, storage `average`. */
+    aggregation: UsageAggregation;
+    /** What a rate may match on; `prefix` for number ranges and families, `exact` otherwise. */
+    dimensions: UsageDimension[];
+    /**
+     * Whose usage it is. `source`: one of the source's own accounts (a PBX tenant), picked on the
+     * agreement. `customer`: the agreement's customer itself — hours booked on a company — so there
+     * is nothing to pick, and the customer's id is the account. Absent = `source`.
+     */
+    account?: "source" | "customer";
+}
+export interface UsageDimension {
+    key: string;
+    label: string;
+    match: "exact" | "prefix";
+    /**
+     * The values it takes, when that is a known list: a rate then picks one instead of typing it,
+     * and a typo cannot silently match nothing. `label` is a key in the source's `locales`, or
+     * plain text for values the organisation named itself (a work type).
+     */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+}
+export interface UsageSourceDescription {
+    meters: UsageMeter[];
+    /**
+     * The accounts usage can be read for: a PBX tenant, a sms sender. The agreement binds one to a
+     * customer; the source never learns about customers.
+     */
+    accounts: {
+        ref: string;
+        name: string;
+    }[];
+    locales?: LocaleBundle;
+}
+export interface UsageRecordsRequest {
+    meter: string;
+    accountRef: string;
+    /** Epoch ms, `to` exclusive. */
+    from: number;
+    to: number;
+}
+export interface UsageRecordsResponse {
+    records: UsageRecord[];
+}
+/**
+ * A meter as another app described it, made whole. A describe crosses an app boundary and may be
+ * older than this contract (a source not redeployed yet, a cached describe): missing fields get
+ * the neutral answer — its own unit per 1, summed, matched exactly — instead of crashing a screen.
+ */
+export declare function normalizeMeter(raw: Partial<UsageMeter> & {
+    key: string;
+}): UsageMeter;
+/** Every meter of a describe made whole; see {@link normalizeMeter}. */
+export declare function normalizeUsageSource<T extends UsageSourceDescription>(source: T): T;

package/dist/entities/inbox/types.d.ts

@@ -1,3 +1,4 @@
+import { InteractionResolution } from '../interaction/resolution';
 export interface Inbox {
     id: string;
     organizationId: string;
@@ -23,4 +24,6 @@ export interface Inbox {
      * priority itself is rarely set.
      */
     slaHours?: number;
+    /** This inbox's own resolutions, next to `SYSTEM_RESOLUTIONS`. Read through `resolutionsFor`. */
+    resolutions?: InteractionResolution[];
 }