@nimee/shared-types 1.0.333 → 1.0.336

package/dist/crm/diningCommit.d.ts

@@ -38,6 +38,13 @@ export interface IDiningCommitItem {
     addedAt?: Date | string;
     [key: string]: unknown;
 }
+export interface IDiningCommitAdjustment {
+    amount: number;
+    reason: string;
+    createdBy?: string | mongoose.Types.ObjectId;
+    createdByName?: string;
+    createdAt?: Date;
+}
 export interface IDiningCommitModel {
     _id?: string | mongoose.Types.ObjectId;
     endUser: string | mongoose.Types.ObjectId;
@@ -68,6 +75,43 @@ export interface IDiningCommitModel {
     customer?: Record<string, unknown>;
     settled: boolean;
     chargeId?: string | mongoose.Types.ObjectId | null;
+    /** Who triggered settlement, and when. `null`/`undefined` reserved for a future automated sweep. */
+    settledBy?: string | mongoose.Types.ObjectId | null;
+    settledByName?: string | null;
+    settledAt?: Date | null;
+    /**
+     * Whether the charge that collected this meal was later refunded. Stamped at refund time, not
+     * derived on read — the guest's page must stay one query.
+     *
+     * `full` means the whole charge came back, so this meal's money did too. `partial` is charge-level
+     * and carries no per-meal figure: a charge covers several meals and a partial refund does not say
+     * which of them it was for.
+     */
+    refundState?: "partial" | "full";
+    refundedAt?: Date;
+    /**
+     * This meal's share of the money returned, in SHEKELS. Stamped alongside `refundState`.
+     *
+     * On a `full` refund it is exactly this meal's own effectiveAmount. On a `partial` it is the
+     * meal's PRO-RATA share of the charge's refunded total, weighted by effective amount — an
+     * apportionment, not a fact about this meal, since a partial refund never says which of the
+     * charge's meals it was for. The apportionment is exact in aggregate: the shares always sum back
+     * to the amount actually returned, which is what makes it safe to total in reporting.
+     *
+     * That is also why the guest-facing page shows this figure only for a `full` refund: reporting can
+     * honestly sum an apportionment, but telling one diner "we gave you back 41.30 for this dish"
+     * would state something we do not know.
+     */
+    refundedAmount?: number;
+    /** Pre-charge-only price reductions. `amount` above is never mutated — see `effectiveAmount`. */
+    adjustments?: IDiningCommitAdjustment[];
+    /**
+     * `amount + sum(adjustments[].amount)`. NEVER stored — always computed at read time (aggregation
+     * `$addFields` in the DB manager, or in-memory when a single already-fetched doc is reshaped). This
+     * field exists on the interface only so callers that receive an already-computed value (API
+     * responses, aggregation output) have a name for it.
+     */
+    effectiveAmount?: number;
     createdAt?: Date;
     updatedAt?: Date;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimee/shared-types",
-  "version": "1.0.333",
+  "version": "1.0.336",
   "description": "Types and interfaces that any service can access if needed",
   "main": "dist/index.js",
   "author": "dan goldberg",

package/src/crm/diningCommit.ts

@@ -15,6 +15,14 @@ export interface IDiningCommitItem {
   [key: string]: unknown;
 }
 
+export interface IDiningCommitAdjustment {
+  amount: number; // always < 0 — a compensation only ever reduces the price
+  reason: string;
+  createdBy?: string | mongoose.Types.ObjectId;
+  createdByName?: string;
+  createdAt?: Date;
+}
+
 export interface IDiningCommitModel {
   _id?: string | mongoose.Types.ObjectId;
   endUser: string | mongoose.Types.ObjectId;
@@ -45,6 +53,43 @@ export interface IDiningCommitModel {
   customer?: Record<string, unknown>;
   settled: boolean;
   chargeId?: string | mongoose.Types.ObjectId | null;
+  /** Who triggered settlement, and when. `null`/`undefined` reserved for a future automated sweep. */
+  settledBy?: string | mongoose.Types.ObjectId | null;
+  settledByName?: string | null;
+  settledAt?: Date | null;
+  /**
+   * Whether the charge that collected this meal was later refunded. Stamped at refund time, not
+   * derived on read — the guest's page must stay one query.
+   *
+   * `full` means the whole charge came back, so this meal's money did too. `partial` is charge-level
+   * and carries no per-meal figure: a charge covers several meals and a partial refund does not say
+   * which of them it was for.
+   */
+  refundState?: "partial" | "full";
+  refundedAt?: Date;
+  /**
+   * This meal's share of the money returned, in SHEKELS. Stamped alongside `refundState`.
+   *
+   * On a `full` refund it is exactly this meal's own effectiveAmount. On a `partial` it is the
+   * meal's PRO-RATA share of the charge's refunded total, weighted by effective amount — an
+   * apportionment, not a fact about this meal, since a partial refund never says which of the
+   * charge's meals it was for. The apportionment is exact in aggregate: the shares always sum back
+   * to the amount actually returned, which is what makes it safe to total in reporting.
+   *
+   * That is also why the guest-facing page shows this figure only for a `full` refund: reporting can
+   * honestly sum an apportionment, but telling one diner "we gave you back 41.30 for this dish"
+   * would state something we do not know.
+   */
+  refundedAmount?: number;
+  /** Pre-charge-only price reductions. `amount` above is never mutated — see `effectiveAmount`. */
+  adjustments?: IDiningCommitAdjustment[];
+  /**
+   * `amount + sum(adjustments[].amount)`. NEVER stored — always computed at read time (aggregation
+   * `$addFields` in the DB manager, or in-memory when a single already-fetched doc is reshaped). This
+   * field exists on the interface only so callers that receive an already-computed value (API
+   * responses, aggregation output) have a name for it.
+   */
+  effectiveAmount?: number;
   createdAt?: Date;
   updatedAt?: Date;
 }