platform-types 1.10.738 → 1.10.739

package/dist/auth.d.ts

@@ -153,18 +153,23 @@ declare global {
          * (`storeContactFooter`), and `phone` also on the emisor block of every
          * invoice PDF.
          *
-         * ⚠️ A STORE `email` is also a live DESTINATION from the first day, so the
-         * client must confirm it is a MONITORED business address, not just a
-         * public one:
-         * - it is the `Reply-To` of every store-branded mail to the store's
-         *   customers sent under the platform envelope, so a customer's answer goes
-         *   there;
-         * - it receives the storefront's survey responses (suppressed for a demo
-         *   store);
-         * - it is the one recipient of the scheduled sales digest, once the store
-         *   opts in and is entitled to it;
-         * - it is the last-resort recipient of an integration re-authorisation mail,
-         *   used when the request names no address and the founding admin has none.
+         * ⚠️ A STORE `email` becomes a DESTINATION once its inbox confirms it, so
+         * the client must confirm it is a MONITORED business address, not just a
+         * public one. Registering with it mails a single-use confirmation link
+         * there (platform-branded, valid 48 h), and until that link is followed:
+         * - customer-facing store-branded mail sent under the platform envelope
+         *   carries NO `Reply-To`; once confirmed, the address is that `Reply-To`,
+         *   so a customer's answer goes there. Customer mail never falls back to
+         *   the founder's address;
+         * - the storefront's survey responses (suppressed for a demo store) and
+         *   the scheduled sales digest (once the store opts in and is entitled
+         *   to it) go to the founding admin's verified login email instead, and
+         *   to no one when that account is disabled or its email unverified;
+         *   once confirmed, they go to this address. Without a store `email`
+         *   neither is sent at all;
+         * - an integration re-authorisation mail that names no address goes to
+         *   the founding admin's verified login email, and to this address only
+         *   when that one is unusable AND this one is confirmed.
          *
          * STRICT, like `acquisition`: an unknown key refuses the WHOLE
          * registration, and so does an empty object — send at least one key or

package/dist/store.d.ts

@@ -409,6 +409,34 @@ declare global {
         /** Unix ms — the registration's own `createdAt`, the instant the STORE item is stamped with. */
         capturedAt: number;
     }
+    /**
+     * The ownership check on the STORE row's `email`: whether whoever reads that
+     * inbox has confirmed it, by following a single-use link the api mailed to it.
+     *
+     * ⚠️ Server-owned: no request body may set it. Every write that puts a NEW
+     * `email` on the row stamps it `pending` for that exact address; the
+     * confirmation link flips it to `verified` only while the row still holds
+     * that address. Clearing `email` KEEPS the record: it names the address it
+     * is about, so it can only vouch for a later `email` that really is that
+     * verified address.
+     *
+     * ABSENT means verified (rows that predate it are grandfathered); a PRESENT
+     * record that is `null` or malformed counts as unverified. The one reader of
+     * "verified" is `isStoreEmailVerified` (`stacks/helpers/storeEmailVerified.ts`).
+     */
+    interface StoreEmailVerification {
+        /** `pending` until the link mailed to `address` is followed, then `verified`. */
+        status: 'pending' | 'verified';
+        /**
+         * The normalised address the record is about. A record whose `address` is
+         * not the row's current `email` says nothing about that email.
+         */
+        address: string;
+        /** Unix ms — when the api stamped it `pending`. */
+        requestedAt: number;
+        /** Unix ms — when the link was followed. Present only once `verified`. */
+        verifiedAt?: number;
+    }
     /**
      * The shop's public address, as every link minter and every client reads it.
      * Computed by the api from server-owned row fields that never reach a client
@@ -529,6 +557,16 @@ declare global {
          * and every operator-created tenant.
          */
         registrationPrefill?: StoreRegistrationPrefill;
+        /**
+         * Whether `email` has been confirmed by its inbox. Admin-only; written only
+         * by the server.
+         *
+         * ⚠️ **Absent means verified.** A row whose `email` predates verification
+         * carries no record, and that address is grandfathered as verified — it is
+         * never backfilled. Only a record that is `pending`, or `verified` for an
+         * address other than the current `email`, makes the email unverified.
+         */
+        emailVerification?: StoreEmailVerification;
         /**
          * Response-time join, not a persisted Store attribute — and TWO different
          * shapes depending on the endpoint: `GET /tenants` (SUPERVISOR) attaches the

package/package.json

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