sinfactura-types 1.10.237 → 1.10.239

package/dist/marketing.d.ts

@@ -222,5 +222,70 @@ declare global {
         createdAt: number;
         updatedAt?: number;
     }
+    /** One datapoint of the campaign-engagement time series. `t` is epoch MILLISECONDS. */
+    interface CampaignEmailMetricPoint {
+        t: number;
+        v: number;
+    }
+    /**
+     * `GET /campaigns?mode=metrics` — the store's MARKETING email engagement,
+     * read from the CloudWatch event destination of the marketing SES
+     * Configuration Set.
+     *
+     * ⚠️ **Marketing mail only, and that is the point.** The figures come from
+     * the `sinfactura-email-marketing{-dev}` Configuration Set, which only a
+     * `kind: 'marketing'` send names. Password resets, OTP codes and order
+     * confirmations are on a different set with a different CloudWatch dimension
+     * set and cannot appear here — a transactional email is opened at a far
+     * higher rate than a campaign, so commingling them would produce an "open
+     * rate" that moves with transactional volume.
+     *
+     * ⚠️ **There is no `sent` figure, and its absence is deliberate.** The
+     * marketing Configuration Set does not publish the `SEND` event type, so no
+     * per-store send count exists in CloudWatch at all. `delivered` is the only
+     * available denominator. For attempted-send counts use `Campaign`'s own
+     * `queuedCount`/`sentCount` counters, which measure a different thing (what
+     * the worker handed to the transport, not what SES delivered).
+     */
+    interface CampaignEmailMetricsResponse {
+        storeId: string;
+        window: CampaignEmailMetricWindow;
+        /**
+         * Sums over the window.
+         *
+         * ⚠️ `opened` is TOTAL opens, not unique openers. SES emits one event per
+         * open, so one recipient opening five times counts five — and image
+         * caching plus privacy-protecting mail providers skew it in both
+         * directions. Read it as a floor with noise on top, never as a headcount.
+         * The per-message `EMAILEVENT` rows answer the unique-per-message question
+         * instead.
+         */
+        totals: {
+            delivered: number;
+            opened: number;
+            bounced: number;
+            complained: number;
+            rejected: number;
+        };
+        /**
+         * `opened / delivered`, ABSENT when nothing was delivered in the window.
+         *
+         * ⚠️ Absence is not zero. A store that sent no campaign and a store whose
+         * campaign nobody opened must not render identically — a synthesised `0`
+         * reads as "the campaign flopped" when the truth is "there was no
+         * campaign". ⚠️ It can exceed `1`, because the numerator counts repeat
+         * opens and the denominator counts messages.
+         */
+        openRate?: number;
+        /** Per-period series over the same window, ascending by `t`. */
+        series: {
+            delivered: CampaignEmailMetricPoint[];
+            opened: CampaignEmailMetricPoint[];
+        };
+        /** Unix MILLISECONDS the figures were read at. */
+        generatedAt: number;
+    }
+    /** Look-back window for {@link CampaignEmailMetricsResponse}. */
+    type CampaignEmailMetricWindow = '24h' | '7d' | '30d';
 }
 export {};

package/dist/order.d.ts

@@ -872,6 +872,28 @@ declare global {
         source: 'mp' | 'stripe' | 'mp_movement';
         total: number;
         linkedAt: number;
+        /**
+         * The denomination `total` is expressed in, as the provider stated it —
+         * an ISO code (`'USD'`) or a platform catalogId (`'usd-oficial'`), both
+         * accepted by the FX resolver.
+         *
+         * ⚠️ **ABSENT means "the order's own currency", and that is a
+         * back-catalogue reading, not a default.** Every entry written before
+         * this field existed carries no denomination at all and there is no
+         * backfill, so a reader summing the map has to assume parity for those —
+         * which is exactly the assumption this field exists to stop making
+         * going forward. A writer that knows the provider's currency MUST stamp
+         * it, even when it equals the order's: an entry that omits it is
+         * indistinguishable from a legacy row.
+         *
+         * ⚠️ Every entry in this map is SETTLED by construction — each writer
+         * only creates one once its provider says the money moved (Stripe
+         * `payment_intent.succeeded` / `charge.succeeded`, MercadoPago
+         * `status === 'approved'`, a manual link against an already-recorded
+         * PAYMENT row). There is deliberately no per-entry status: a pending
+         * provider notification never reaches this map at all.
+         */
+        currency?: string;
     }
     /**
      * The body of `POST /orders` on the CREATE / UPDATE path — the one carrying no

package/package.json

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