platform-types 1.10.841 → 1.10.842

package/dist/cjs/index.js

@@ -75,6 +75,7 @@ __exportStar(require("./maintenance.js"), exports);
 __exportStar(require("./marketing.js"), exports);
 __exportStar(require("./mercadolibre.js"), exports);
 __exportStar(require("./mercadopago.js"), exports);
+__exportStar(require("./messaging.js"), exports);
 __exportStar(require("./notification.js"), exports);
 __exportStar(require("./order.js"), exports);
 __exportStar(require("./orderCollectionAttempt.js"), exports);

package/dist/cjs/messaging.js

@@ -0,0 +1,49 @@
+"use strict";
+/*
+ * Copyright © 2026 BACKSPACE S.A. All rights reserved.
+ *
+ * SPDX-License-Identifier: PROPRIETARY
+ *
+ * This file is proprietary and confidential. Unauthorized copying,
+ * modification, or distribution is strictly prohibited.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MESSAGE_DELIVERY_STAMPS = exports.MESSAGE_LEDGER_KINDS = exports.MESSAGE_CREDITS_PER_CHANNEL = exports.MESSAGE_ALLOWANCE_UNLIMITED = exports.SMS_FALLBACK_CREDITS = exports.WHATSAPP_MESSAGE_CREDITS = exports.MESSAGE_LEDGER_OPERATOR_ONLY_FIELDS = void 0;
+/**
+ * Fields a store's own ledger read drops from an `adjustment` entry: it is a
+ * platform operator act, and its `actor`, `reason` and `refId` (the
+ * operator's own `adjustmentId`) stay on operator surfaces — the store sees
+ * the entry, its credits and its balance. Other kinds cross whole.
+ */
+exports.MESSAGE_LEDGER_OPERATOR_ONLY_FIELDS = [
+    'actor',
+    'reason',
+    'refId',
+];
+/** Credits one WhatsApp message costs. */
+exports.WHATSAPP_MESSAGE_CREDITS = 1;
+/** Credits one SMS fallback costs. */
+exports.SMS_FALLBACK_CREDITS = 3;
+/**
+ * `MessageBalanceView.allowanceLimit` for a plan or override whose `monthlyMessageAllowance` grant is
+ * `limit: -1` (the repo-wide spelling of unlimited). `allowanceLeft` and `available` then read `-1` too, and
+ * every message is taken from the allowance — never from the bought balance.
+ */
+exports.MESSAGE_ALLOWANCE_UNLIMITED = -1;
+/** Credits per message, by channel. */
+exports.MESSAGE_CREDITS_PER_CHANNEL = {
+    whatsapp: exports.WHATSAPP_MESSAGE_CREDITS,
+    sms: exports.SMS_FALLBACK_CREDITS,
+};
+exports.MESSAGE_LEDGER_KINDS = [
+    'debit',
+    'refund',
+    'allowance-grant',
+    'purchase',
+    'adjustment',
+];
+exports.MESSAGE_DELIVERY_STAMPS = [
+    'delivered',
+    'read',
+    'failed',
+];

package/dist/cjs/notification.js

@@ -7,7 +7,7 @@ exports.WEB_NOTIFICATIONS_MAX_LIMIT = exports.CUSTOMER_NOTIFICATION_TYPES = expo
 // Addressed ERROR / ML_FACTURADOR_COLLISION / ML_SELLER_SWITCHED /
 // ML_CONNECTION_BROKEN / MENTION / CUSTOMER_PENDING_APPROVAL /
 // PAYMENT_ATTEMPT_RESOLUTION / CUSTOMER_WHOLESALE_REQUEST / STOREFRONT_QUOTE_REQUEST /
-// REFUND_OBLIGATION_OVERDUE do not select a
+// REFUND_OBLIGATION_OVERDUE / MESSAGE_CREDITS_LOW / MESSAGE_SKIPPED_NO_CREDITS do not select a
 // producer subscriber audience;
 // the consumer still reads the live USER row for each delivery channel.
 // AFIP_CERT_EXPIRY is seeded on the founding user and uses the subscriber index.
@@ -257,6 +257,33 @@ var NotificationTypeEnum;
      * `REFUND_OVERDUE` ERROR row and rings nothing. Never a `customerId`.
      */
     NotificationTypeEnum["REFUND_OBLIGATION_OVERDUE"] = "REFUND_OBLIGATION_OVERDUE";
+    /**
+     * The store's message credits (allowance left + bought balance) fell below
+     * the `messagingLowBalanceThreshold` platform global: a reserved message
+     * took them from at or above it to below it. Names the credits left in the
+     * description; the app opens the message-credits screen from the type.
+     *
+     * ⚠️ ADMIN-ONLY, and its own preference key. The producer fans out to every
+     * non-disabled ADMIN of the store (`listActiveAdmins`), with no legacy
+     * opt-in scan; the consumer enforces explicit type/channel preferences
+     * (`notificationPreferences.MESSAGE_CREDITS_LOW`), default-on when absent.
+     * Additive — no backfill or consumer migration owed.
+     *
+     * Once per crossing: a claim keyed on the reservation that crossed makes a
+     * redelivered or replayed reservation ring nothing more. Carries no
+     * customer, phone or message content.
+     */
+    NotificationTypeEnum["MESSAGE_CREDITS_LOW"] = "MESSAGE_CREDITS_LOW";
+    /**
+     * A customer message was NOT sent because the store had no credits left
+     * for it (allowance and bought balance both short). At most one per store
+     * per Buenos Aires day, whatever the number of skipped messages.
+     *
+     * ⚠️ ADMIN-ONLY, and its own preference key — the same audience and
+     * preference rules as `MESSAGE_CREDITS_LOW`. Carries no customer, phone,
+     * order or message content: NOTIF# rows outlive an erasure.
+     */
+    NotificationTypeEnum["MESSAGE_SKIPPED_NO_CREDITS"] = "MESSAGE_SKIPPED_NO_CREDITS";
 })(NotificationTypeEnum || (exports.NotificationTypeEnum = NotificationTypeEnum = {}));
 /**
  * The notification types a CUSTOMER bell can carry today; each links through

package/dist/index.d.ts

@@ -51,6 +51,7 @@ export * from './maintenance.ts';
 export * from './marketing.ts';
 export * from './mercadolibre.ts';
 export * from './mercadopago.ts';
+export * from './messaging.ts';
 export * from './notification.ts';
 export * from './order.ts';
 export * from './orderCollectionAttempt.ts';

package/dist/index.js

@@ -59,6 +59,7 @@ export * from "./maintenance.js";
 export * from "./marketing.js";
 export * from "./mercadolibre.js";
 export * from "./mercadopago.js";
+export * from "./messaging.js";
 export * from "./notification.js";
 export * from "./order.js";
 export * from "./orderCollectionAttempt.js";

package/dist/messaging.d.ts

@@ -0,0 +1,180 @@
+declare global {
+    /** How a store-paid customer message went out. */
+    type MessageCreditChannel = 'whatsapp' | 'sms';
+    /**
+     * What a ledger entry records:
+     * - `debit` — a reserved message (`credits` < 0).
+     * - `refund` — that reservation given back (`credits` ≥ 0). An allowance part
+     *   reserved in an earlier period is NOT given back (the allowance never rolls
+     *   over), so a refund can be smaller than its debit, down to `0`.
+     * - `allowance-grant` — a period's allowance starting (`credits` = the limit,
+     *   into the allowance bucket). Written with the period's first debit, so a
+     *   period with no message has none.
+     * - `purchase` — bought credits (`credits` > 0).
+     * - `adjustment` — a MANAGER/SUPERVISOR correction of the bought balance,
+     *   either sign, with `actor` and `reason` — operator-only, with its `refId`:
+     *   the store's own ledger read drops them (`MESSAGE_LEDGER_OPERATOR_ONLY_FIELDS`).
+     */
+    type MessageLedgerKind = 'debit' | 'refund' | 'allowance-grant' | 'purchase' | 'adjustment';
+    /**
+     * How a debited message ended, stamped on its `debit` entry by the sending
+     * pipeline — the ONE field written after the entry lands. Absent means
+     * unknown (not yet reported, or never), never "not delivered".
+     */
+    type MessageDeliveryStamp = 'delivered' | 'read' | 'failed';
+    /** Who made an `adjustment` (or a staff `purchase`). */
+    interface MessageLedgerActor {
+        userId: string;
+        /** Empty, never absent, when the user row carried none. */
+        fullName: string;
+    }
+    /**
+     * One ledger entry as it crosses the wire. Entries are never edited, except
+     * a `debit`'s `delivery`/`deliveryAt`.
+     *
+     * `entryId` is opaque (newest entries sort first by it); address an entry by
+     * it, never read a date out of it — `createdAt` is the time.
+     */
+    interface MessageLedgerEntry {
+        entryId: string;
+        kind: MessageLedgerKind;
+        /** Signed total: the sum of `fromAllowance` and `fromBalance`. */
+        credits: number;
+        /** Signed move of the allowance bucket: negative on a debit, positive on a grant or refund. */
+        fromAllowance: number;
+        /** Signed move of the bought balance. */
+        fromBalance: number;
+        /** The bought balance after this entry. */
+        balanceAfter: number;
+        /** Allowance credits used in `period` after this entry. */
+        allowanceUsedAfter: number;
+        /** The allowance period (`YYYY-MM`, Buenos Aires) the entry was written in. */
+        period: string;
+        createdAt: number;
+        /** The reservation a `debit`/`refund` belongs to, the purchase id, or the adjustment id. */
+        refId?: string;
+        /** `debit` and `refund` only. */
+        noticeType?: StoreMessageNotice;
+        /** `debit` and `refund` only. */
+        channel?: MessageCreditChannel;
+        /** `refund` only: the period its reservation was debited in. */
+        reservationPeriod?: string;
+        /** `allowance-grant` only: the plan's monthly limit that period started with. */
+        allowanceLimit?: number;
+        /** `adjustment` (and a staff `purchase`). */
+        actor?: MessageLedgerActor;
+        /** `adjustment`: why, as the operator wrote it. */
+        reason?: string;
+        /** `debit` only — see `MessageDeliveryStamp`. */
+        delivery?: MessageDeliveryStamp;
+        deliveryAt?: number;
+    }
+    /** The store's credits right now, the period already rolled forward when it has ended. */
+    interface MessageBalanceView {
+        /** Bought credits, never below zero. */
+        balance: number;
+        /** The current allowance period (`YYYY-MM`, Buenos Aires). */
+        period: string;
+        /** The plan's monthly allowance; `0` when the plan includes none, `-1` (`MESSAGE_ALLOWANCE_UNLIMITED`) when unlimited. */
+        allowanceLimit: number;
+        allowanceUsed: number;
+        /** `max(0, allowanceLimit - allowanceUsed)`; `-1` when unlimited. */
+        allowanceLeft: number;
+        /** `allowanceLeft + balance` — what the next messages can spend; `-1` when unlimited. */
+        available: number;
+    }
+    /** One page of the ledger, newest first. `cursor` present only when more may follow. */
+    interface MessageLedgerPage {
+        items: MessageLedgerEntry[];
+        cursor?: string;
+    }
+    /** Per-notice slice of `MessageUsageReport`, refunded messages excluded. */
+    interface MessageUsageNoticeTotals {
+        messages: number;
+        sms: number;
+        credits: number;
+    }
+    /**
+     * One period's usage, computed from the ledger alone. A message counts once
+     * per `debit` not refunded; a refund written up to the end of the FOLLOWING
+     * period still nets its debit out.
+     *
+     * Rates are over the messages carrying a `delivery` stamp (`stamped`), never
+     * over all of them, and `null` when none is stamped: an unstamped message is
+     * unknown, not failed. `read` counts as delivered too.
+     *
+     * `truncated: true` — the ledger read stopped at its row cap, so every figure
+     * is a lower bound.
+     */
+    interface MessageUsageReport {
+        period: string;
+        truncated: boolean;
+        messages: number;
+        whatsapp: number;
+        sms: number;
+        /** `sms / messages`; `null` with no message. */
+        smsFallbackShare: number | null;
+        creditsSpent: number;
+        creditsFromAllowance: number;
+        creditsFromBalance: number;
+        delivery: {
+            stamped: number;
+            delivered: number;
+            read: number;
+            failed: number;
+            deliveredRate: number | null;
+            readRate: number | null;
+        };
+        byNotice: Partial<Record<StoreMessageNotice, MessageUsageNoticeTotals>>;
+    }
+    /**
+     * `POST /platform/stores/{storeId}/message-credits` — a MANAGER/SUPERVISOR
+     * correction of the store's BOUGHT balance (never the allowance).
+     */
+    interface MessageCreditAdjustmentRequest {
+        /** Signed, whole, non-zero. A negative one that would take the balance below zero is refused. */
+        credits: number;
+        /** 10–500 characters, no personal data. Internal: the store's own reads never show it. */
+        reason: string;
+        /** The target `storeId`, echoed (type-to-confirm). */
+        confirm: string;
+        /**
+         * The caller's idempotency id (`[A-Za-z0-9][\w.:~-]{0,127}`): a repeat with
+         * it answers the first outcome and moves nothing.
+         */
+        adjustmentId: string;
+    }
+    interface MessageCreditAdjustmentResult {
+        storeId: string;
+        /** The `adjustment` ledger entry. */
+        entryId: string;
+        /** The bought balance after the adjustment. */
+        balanceAfter: number;
+        /** `true` when `adjustmentId` had already been applied — nothing moved this time. */
+        replayed: boolean;
+    }
+}
+/**
+ * Fields a store's own ledger read drops from an `adjustment` entry: it is a
+ * platform operator act, and its `actor`, `reason` and `refId` (the
+ * operator's own `adjustmentId`) stay on operator surfaces — the store sees
+ * the entry, its credits and its balance. Other kinds cross whole.
+ */
+export declare const MESSAGE_LEDGER_OPERATOR_ONLY_FIELDS: readonly ["actor", "reason", "refId"];
+/** Credits one WhatsApp message costs. */
+export declare const WHATSAPP_MESSAGE_CREDITS = 1;
+/** Credits one SMS fallback costs. */
+export declare const SMS_FALLBACK_CREDITS = 3;
+/**
+ * `MessageBalanceView.allowanceLimit` for a plan or override whose `monthlyMessageAllowance` grant is
+ * `limit: -1` (the repo-wide spelling of unlimited). `allowanceLeft` and `available` then read `-1` too, and
+ * every message is taken from the allowance — never from the bought balance.
+ */
+export declare const MESSAGE_ALLOWANCE_UNLIMITED = -1;
+/** Credits per message, by channel. */
+export declare const MESSAGE_CREDITS_PER_CHANNEL: {
+    readonly whatsapp: 1;
+    readonly sms: 3;
+};
+export declare const MESSAGE_LEDGER_KINDS: readonly ["debit", "refund", "allowance-grant", "purchase", "adjustment"];
+export declare const MESSAGE_DELIVERY_STAMPS: readonly ["delivered", "read", "failed"];

package/dist/messaging.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright © 2026 BACKSPACE S.A. All rights reserved.
+ *
+ * SPDX-License-Identifier: PROPRIETARY
+ *
+ * This file is proprietary and confidential. Unauthorized copying,
+ * modification, or distribution is strictly prohibited.
+ */
+/**
+ * Fields a store's own ledger read drops from an `adjustment` entry: it is a
+ * platform operator act, and its `actor`, `reason` and `refId` (the
+ * operator's own `adjustmentId`) stay on operator surfaces — the store sees
+ * the entry, its credits and its balance. Other kinds cross whole.
+ */
+export const MESSAGE_LEDGER_OPERATOR_ONLY_FIELDS = [
+    'actor',
+    'reason',
+    'refId',
+];
+/** Credits one WhatsApp message costs. */
+export const WHATSAPP_MESSAGE_CREDITS = 1;
+/** Credits one SMS fallback costs. */
+export const SMS_FALLBACK_CREDITS = 3;
+/**
+ * `MessageBalanceView.allowanceLimit` for a plan or override whose `monthlyMessageAllowance` grant is
+ * `limit: -1` (the repo-wide spelling of unlimited). `allowanceLeft` and `available` then read `-1` too, and
+ * every message is taken from the allowance — never from the bought balance.
+ */
+export const MESSAGE_ALLOWANCE_UNLIMITED = -1;
+/** Credits per message, by channel. */
+export const MESSAGE_CREDITS_PER_CHANNEL = {
+    whatsapp: WHATSAPP_MESSAGE_CREDITS,
+    sms: SMS_FALLBACK_CREDITS,
+};
+export const MESSAGE_LEDGER_KINDS = [
+    'debit',
+    'refund',
+    'allowance-grant',
+    'purchase',
+    'adjustment',
+];
+export const MESSAGE_DELIVERY_STAMPS = [
+    'delivered',
+    'read',
+    'failed',
+];

package/dist/notification.d.ts

@@ -233,7 +233,34 @@ export declare enum NotificationTypeEnum {
      * daily repeat of an obligation already `overdue` writes the
      * `REFUND_OVERDUE` ERROR row and rings nothing. Never a `customerId`.
      */
-    REFUND_OBLIGATION_OVERDUE = "REFUND_OBLIGATION_OVERDUE"
+    REFUND_OBLIGATION_OVERDUE = "REFUND_OBLIGATION_OVERDUE",
+    /**
+     * The store's message credits (allowance left + bought balance) fell below
+     * the `messagingLowBalanceThreshold` platform global: a reserved message
+     * took them from at or above it to below it. Names the credits left in the
+     * description; the app opens the message-credits screen from the type.
+     *
+     * ⚠️ ADMIN-ONLY, and its own preference key. The producer fans out to every
+     * non-disabled ADMIN of the store (`listActiveAdmins`), with no legacy
+     * opt-in scan; the consumer enforces explicit type/channel preferences
+     * (`notificationPreferences.MESSAGE_CREDITS_LOW`), default-on when absent.
+     * Additive — no backfill or consumer migration owed.
+     *
+     * Once per crossing: a claim keyed on the reservation that crossed makes a
+     * redelivered or replayed reservation ring nothing more. Carries no
+     * customer, phone or message content.
+     */
+    MESSAGE_CREDITS_LOW = "MESSAGE_CREDITS_LOW",
+    /**
+     * A customer message was NOT sent because the store had no credits left
+     * for it (allowance and bought balance both short). At most one per store
+     * per Buenos Aires day, whatever the number of skipped messages.
+     *
+     * ⚠️ ADMIN-ONLY, and its own preference key — the same audience and
+     * preference rules as `MESSAGE_CREDITS_LOW`. Carries no customer, phone,
+     * order or message content: NOTIF# rows outlive an erasure.
+     */
+    MESSAGE_SKIPPED_NO_CREDITS = "MESSAGE_SKIPPED_NO_CREDITS"
 }
 /**
  * The notification types a CUSTOMER bell can carry today; each links through

package/dist/notification.js

@@ -4,7 +4,7 @@
 // Addressed ERROR / ML_FACTURADOR_COLLISION / ML_SELLER_SWITCHED /
 // ML_CONNECTION_BROKEN / MENTION / CUSTOMER_PENDING_APPROVAL /
 // PAYMENT_ATTEMPT_RESOLUTION / CUSTOMER_WHOLESALE_REQUEST / STOREFRONT_QUOTE_REQUEST /
-// REFUND_OBLIGATION_OVERDUE do not select a
+// REFUND_OBLIGATION_OVERDUE / MESSAGE_CREDITS_LOW / MESSAGE_SKIPPED_NO_CREDITS do not select a
 // producer subscriber audience;
 // the consumer still reads the live USER row for each delivery channel.
 // AFIP_CERT_EXPIRY is seeded on the founding user and uses the subscriber index.
@@ -254,6 +254,33 @@ export var NotificationTypeEnum;
      * `REFUND_OVERDUE` ERROR row and rings nothing. Never a `customerId`.
      */
     NotificationTypeEnum["REFUND_OBLIGATION_OVERDUE"] = "REFUND_OBLIGATION_OVERDUE";
+    /**
+     * The store's message credits (allowance left + bought balance) fell below
+     * the `messagingLowBalanceThreshold` platform global: a reserved message
+     * took them from at or above it to below it. Names the credits left in the
+     * description; the app opens the message-credits screen from the type.
+     *
+     * ⚠️ ADMIN-ONLY, and its own preference key. The producer fans out to every
+     * non-disabled ADMIN of the store (`listActiveAdmins`), with no legacy
+     * opt-in scan; the consumer enforces explicit type/channel preferences
+     * (`notificationPreferences.MESSAGE_CREDITS_LOW`), default-on when absent.
+     * Additive — no backfill or consumer migration owed.
+     *
+     * Once per crossing: a claim keyed on the reservation that crossed makes a
+     * redelivered or replayed reservation ring nothing more. Carries no
+     * customer, phone or message content.
+     */
+    NotificationTypeEnum["MESSAGE_CREDITS_LOW"] = "MESSAGE_CREDITS_LOW";
+    /**
+     * A customer message was NOT sent because the store had no credits left
+     * for it (allowance and bought balance both short). At most one per store
+     * per Buenos Aires day, whatever the number of skipped messages.
+     *
+     * ⚠️ ADMIN-ONLY, and its own preference key — the same audience and
+     * preference rules as `MESSAGE_CREDITS_LOW`. Carries no customer, phone,
+     * order or message content: NOTIF# rows outlive an erasure.
+     */
+    NotificationTypeEnum["MESSAGE_SKIPPED_NO_CREDITS"] = "MESSAGE_SKIPPED_NO_CREDITS";
 })(NotificationTypeEnum || (NotificationTypeEnum = {}));
 /**
  * The notification types a CUSTOMER bell can carry today; each links through

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "platform-types",
-	"version": "1.10.841",
+	"version": "1.10.842",
 	"description": "Shared wire and entity contracts for the platform.",
 	"type": "module",
 	"main": "dist/index.js",