platform-types 1.10.764 → 1.10.765

package/dist/auth.d.ts

@@ -1,3 +1,4 @@
+import type { EmailSuppressionReason } from './emailSuppression.ts';
 declare global {
     interface Login {
         email: string;
@@ -1079,6 +1080,56 @@ declare global {
         /** Unix ms after which the code no longer redeems (mint + 60 s). */
         expiresAt: number;
     }
+    /**
+     * `POST /auth` (Web API) body for `send-otp`: mail a 6-digit code to the
+     * address STORED on the caller's customer row. Needs a Bearer customer ACCESS
+     * token (`Authorization: Bearer …`); the method has no API Gateway authorizer,
+     * so the handler verifies it. The body carries no address — one supplied is
+     * ignored.
+     *
+     * `200 { message }` with no `data` when a code was queued. Refusals: see
+     * {@link CUSTOMER_OTP_ERROR_CODES}. Timing: see {@link CUSTOMER_OTP_LIMITS}.
+     * Nothing is mailed automatically after the customer changes their address —
+     * call this.
+     */
+    interface CustomerSendOtpRequest {
+        mode: 'send-otp';
+    }
+    /**
+     * `POST /auth` (Web API) body for `verify-otp`, with the same Bearer customer
+     * ACCESS token as `send-otp`.
+     */
+    interface CustomerVerifyOtpRequest {
+        mode: 'verify-otp';
+        /** Exactly six ASCII digits; anything else is `400 VALIDATION_FAILED`. */
+        code: string;
+    }
+    /**
+     * `verify-otp` 200 `data`. Merge it into the cached `AuthCustomer`; the same
+     * pair also arrives as a `customers` socket frame (`data: { customerId,
+     * emailVerified, emailVerifiedAt }`) on every socket of this customer, so other
+     * open tabs update without a refresh.
+     */
+    interface CustomerVerifyOtpResponse {
+        emailVerified: true;
+        /** ms-epoch of the verification. */
+        emailVerifiedAt: number;
+    }
+    /**
+     * `verify-otp` `400 OTP_WRONG_CODE` body.
+     *
+     * ⚠️ `attemptsLeft` is TOP-LEVEL, beside `error`, not under `data`. `0` means
+     * the next guess answers `429 OTP_LOCKED`.
+     */
+    interface CustomerOtpWrongCodeBody {
+        error: 'OTP_WRONG_CODE';
+        message: string;
+        attemptsLeft: number;
+    }
+    /** `send-otp` `409 EMAIL_ADDRESS_SUPPRESSED` `data`: why the stored address cannot receive mail. */
+    interface CustomerOtpSuppressedData {
+        reason: EmailSuppressionReason;
+    }
     /**
      * `POST /auth` body for `social-bridge-redeem`. Public, captcha-exempt.
      *
@@ -1854,4 +1905,52 @@ export type PasskeyErrorCode = (typeof PASSKEY_ERROR_CODES)[number];
  */
 export declare const SESSION_ACTION_ERROR_CODES: readonly ["SESSION_LOOKUP_INCOMPLETE", "SESSION_UNKNOWN", "REVOKE_INCOMPLETE"];
 export type SessionActionErrorCode = (typeof SESSION_ACTION_ERROR_CODES)[number];
+/**
+ * `body.error` codes the two customer email-OTP modes (Web API `POST /auth`
+ * `send-otp` / `verify-otp`) refuse with. Match on `body.error`.
+ *
+ * NOT members, and answered by both modes before any of these: the shared
+ * customer-identity refusals — `MISSING_TOKEN`, `INVALID_TOKEN`,
+ * `REFRESH_TOKEN_NOT_ALLOWED` (401), `ROLE_NOT_ALLOWED`,
+ * `CUSTOMER_ACCESS_PENDING`, `CUSTOMER_ACCESS_REJECTED` (403),
+ * `CUSTOMER_NOT_FOUND` (404), `ACCOUNT_DISABLED` (400) — and, on `verify-otp`,
+ * `VALIDATION_FAILED` (400) for a `code` that is not six digits.
+ *
+ * - `OTP_COOLDOWN` · 429 — `send-otp` inside 60 s of the last live code.
+ * - `EMAIL_ADDRESS_SUPPRESSED` · 409 — `send-otp`; the address bounced.
+ *   `data` is {@link CustomerOtpSuppressedData}.
+ * - `EMAIL_ALREADY_VERIFIED` · 409 — `send-otp`; the stored address is already
+ *   verified, so nothing was mailed. Hide the resend action.
+ * - `OTP_INVALID` · 400 — `verify-otp`; no code outstanding for the CURRENT
+ *   address: none was sent, or the one sent went to an address the account no
+ *   longer holds. Ask for a new code.
+ * - `OTP_ALREADY_USED` · 400 — `verify-otp`; the code was consumed, or lost a
+ *   race (including a concurrent address change). Ask for a new code.
+ * - `OTP_EXPIRED` · 400 — `verify-otp`; past its 10-minute TTL.
+ * - `OTP_LOCKED` · 429 — `verify-otp`; 5 wrong guesses. Only a new `send-otp`
+ *   unlocks.
+ * - `OTP_WRONG_CODE` · 400 — `verify-otp`; {@link CustomerOtpWrongCodeBody},
+ *   `attemptsLeft` at the TOP level.
+ *
+ * ⚠️ Deliberately not the operator tree's vocabulary (`OTP_INVALID_OR_EXPIRED`,
+ * `OTP_TOO_MANY_ATTEMPTS`, `OTP_RESEND_TOO_SOON`); the two are not unified.
+ */
+export declare const CUSTOMER_OTP_ERROR_CODES: readonly ["OTP_COOLDOWN", "EMAIL_ADDRESS_SUPPRESSED", "EMAIL_ALREADY_VERIFIED", "OTP_INVALID", "OTP_ALREADY_USED", "OTP_EXPIRED", "OTP_LOCKED", "OTP_WRONG_CODE"];
+export type CustomerOtpErrorCode = (typeof CUSTOMER_OTP_ERROR_CODES)[number];
+/**
+ * The numbers the customer email OTP enforces, so a client countdown matches
+ * the server. The api's own OTP service reads them from here, for operators and
+ * customers alike.
+ *
+ * - `ttlSeconds` — a code expires this long after it was sent.
+ * - `resendCooldownSeconds` — `send-otp` answers `429 OTP_COOLDOWN` until this
+ *   long after the last live code.
+ * - `maxAttempts` — wrong guesses per code before `429 OTP_LOCKED`; a new code
+ *   starts the count again.
+ */
+export declare const CUSTOMER_OTP_LIMITS: {
+    readonly ttlSeconds: 600;
+    readonly resendCooldownSeconds: 60;
+    readonly maxAttempts: 5;
+};
 export {};

package/dist/auth.js

@@ -502,3 +502,55 @@ export const SESSION_ACTION_ERROR_CODES = [
     'SESSION_UNKNOWN',
     'REVOKE_INCOMPLETE',
 ];
+/**
+ * `body.error` codes the two customer email-OTP modes (Web API `POST /auth`
+ * `send-otp` / `verify-otp`) refuse with. Match on `body.error`.
+ *
+ * NOT members, and answered by both modes before any of these: the shared
+ * customer-identity refusals — `MISSING_TOKEN`, `INVALID_TOKEN`,
+ * `REFRESH_TOKEN_NOT_ALLOWED` (401), `ROLE_NOT_ALLOWED`,
+ * `CUSTOMER_ACCESS_PENDING`, `CUSTOMER_ACCESS_REJECTED` (403),
+ * `CUSTOMER_NOT_FOUND` (404), `ACCOUNT_DISABLED` (400) — and, on `verify-otp`,
+ * `VALIDATION_FAILED` (400) for a `code` that is not six digits.
+ *
+ * - `OTP_COOLDOWN` · 429 — `send-otp` inside 60 s of the last live code.
+ * - `EMAIL_ADDRESS_SUPPRESSED` · 409 — `send-otp`; the address bounced.
+ *   `data` is {@link CustomerOtpSuppressedData}.
+ * - `EMAIL_ALREADY_VERIFIED` · 409 — `send-otp`; the stored address is already
+ *   verified, so nothing was mailed. Hide the resend action.
+ * - `OTP_INVALID` · 400 — `verify-otp`; no code outstanding for the CURRENT
+ *   address: none was sent, or the one sent went to an address the account no
+ *   longer holds. Ask for a new code.
+ * - `OTP_ALREADY_USED` · 400 — `verify-otp`; the code was consumed, or lost a
+ *   race (including a concurrent address change). Ask for a new code.
+ * - `OTP_EXPIRED` · 400 — `verify-otp`; past its 10-minute TTL.
+ * - `OTP_LOCKED` · 429 — `verify-otp`; 5 wrong guesses. Only a new `send-otp`
+ *   unlocks.
+ * - `OTP_WRONG_CODE` · 400 — `verify-otp`; {@link CustomerOtpWrongCodeBody},
+ *   `attemptsLeft` at the TOP level.
+ *
+ * ⚠️ Deliberately not the operator tree's vocabulary (`OTP_INVALID_OR_EXPIRED`,
+ * `OTP_TOO_MANY_ATTEMPTS`, `OTP_RESEND_TOO_SOON`); the two are not unified.
+ */
+export const CUSTOMER_OTP_ERROR_CODES = [
+    'OTP_COOLDOWN',
+    'EMAIL_ADDRESS_SUPPRESSED',
+    'EMAIL_ALREADY_VERIFIED',
+    'OTP_INVALID',
+    'OTP_ALREADY_USED',
+    'OTP_EXPIRED',
+    'OTP_LOCKED',
+    'OTP_WRONG_CODE',
+];
+/**
+ * The numbers the customer email OTP enforces, so a client countdown matches
+ * the server. The api's own OTP service reads them from here, for operators and
+ * customers alike.
+ *
+ * - `ttlSeconds` — a code expires this long after it was sent.
+ * - `resendCooldownSeconds` — `send-otp` answers `429 OTP_COOLDOWN` until this
+ *   long after the last live code.
+ * - `maxAttempts` — wrong guesses per code before `429 OTP_LOCKED`; a new code
+ *   starts the count again.
+ */
+export const CUSTOMER_OTP_LIMITS = { ttlSeconds: 600, resendCooldownSeconds: 60, maxAttempts: 5 };

package/dist/cjs/auth.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_ACTION_ERROR_CODES = exports.PASSKEY_ERROR_CODES = exports.TWO_FACTOR_MANAGEMENT_ERROR_CODES = exports.LOGIN_2FA_ERROR_CODES = exports.LOGIN_ERROR_CODES = exports.STEP_UP_ERROR_CODES = exports.REFRESH_ERROR_CODES = exports.CUSTOMER_SOCIAL_REGISTER_ERROR_CODES = exports.SOCIAL_BRIDGE_ERROR_CODES = exports.SIGN_IN_METHOD_ERROR_CODES = void 0;
+exports.CUSTOMER_OTP_LIMITS = exports.CUSTOMER_OTP_ERROR_CODES = exports.SESSION_ACTION_ERROR_CODES = exports.PASSKEY_ERROR_CODES = exports.TWO_FACTOR_MANAGEMENT_ERROR_CODES = exports.LOGIN_2FA_ERROR_CODES = exports.LOGIN_ERROR_CODES = exports.STEP_UP_ERROR_CODES = exports.REFRESH_ERROR_CODES = exports.CUSTOMER_SOCIAL_REGISTER_ERROR_CODES = exports.SOCIAL_BRIDGE_ERROR_CODES = exports.SIGN_IN_METHOD_ERROR_CODES = void 0;
 /**
  * `body.error` codes the sign-in-method paths can refuse with.
  *
@@ -505,3 +505,55 @@ exports.SESSION_ACTION_ERROR_CODES = [
     'SESSION_UNKNOWN',
     'REVOKE_INCOMPLETE',
 ];
+/**
+ * `body.error` codes the two customer email-OTP modes (Web API `POST /auth`
+ * `send-otp` / `verify-otp`) refuse with. Match on `body.error`.
+ *
+ * NOT members, and answered by both modes before any of these: the shared
+ * customer-identity refusals — `MISSING_TOKEN`, `INVALID_TOKEN`,
+ * `REFRESH_TOKEN_NOT_ALLOWED` (401), `ROLE_NOT_ALLOWED`,
+ * `CUSTOMER_ACCESS_PENDING`, `CUSTOMER_ACCESS_REJECTED` (403),
+ * `CUSTOMER_NOT_FOUND` (404), `ACCOUNT_DISABLED` (400) — and, on `verify-otp`,
+ * `VALIDATION_FAILED` (400) for a `code` that is not six digits.
+ *
+ * - `OTP_COOLDOWN` · 429 — `send-otp` inside 60 s of the last live code.
+ * - `EMAIL_ADDRESS_SUPPRESSED` · 409 — `send-otp`; the address bounced.
+ *   `data` is {@link CustomerOtpSuppressedData}.
+ * - `EMAIL_ALREADY_VERIFIED` · 409 — `send-otp`; the stored address is already
+ *   verified, so nothing was mailed. Hide the resend action.
+ * - `OTP_INVALID` · 400 — `verify-otp`; no code outstanding for the CURRENT
+ *   address: none was sent, or the one sent went to an address the account no
+ *   longer holds. Ask for a new code.
+ * - `OTP_ALREADY_USED` · 400 — `verify-otp`; the code was consumed, or lost a
+ *   race (including a concurrent address change). Ask for a new code.
+ * - `OTP_EXPIRED` · 400 — `verify-otp`; past its 10-minute TTL.
+ * - `OTP_LOCKED` · 429 — `verify-otp`; 5 wrong guesses. Only a new `send-otp`
+ *   unlocks.
+ * - `OTP_WRONG_CODE` · 400 — `verify-otp`; {@link CustomerOtpWrongCodeBody},
+ *   `attemptsLeft` at the TOP level.
+ *
+ * ⚠️ Deliberately not the operator tree's vocabulary (`OTP_INVALID_OR_EXPIRED`,
+ * `OTP_TOO_MANY_ATTEMPTS`, `OTP_RESEND_TOO_SOON`); the two are not unified.
+ */
+exports.CUSTOMER_OTP_ERROR_CODES = [
+    'OTP_COOLDOWN',
+    'EMAIL_ADDRESS_SUPPRESSED',
+    'EMAIL_ALREADY_VERIFIED',
+    'OTP_INVALID',
+    'OTP_ALREADY_USED',
+    'OTP_EXPIRED',
+    'OTP_LOCKED',
+    'OTP_WRONG_CODE',
+];
+/**
+ * The numbers the customer email OTP enforces, so a client countdown matches
+ * the server. The api's own OTP service reads them from here, for operators and
+ * customers alike.
+ *
+ * - `ttlSeconds` — a code expires this long after it was sent.
+ * - `resendCooldownSeconds` — `send-otp` answers `429 OTP_COOLDOWN` until this
+ *   long after the last live code.
+ * - `maxAttempts` — wrong guesses per code before `429 OTP_LOCKED`; a new code
+ *   starts the count again.
+ */
+exports.CUSTOMER_OTP_LIMITS = { ttlSeconds: 600, resendCooldownSeconds: 60, maxAttempts: 5 };

package/dist/customer.d.ts

@@ -302,8 +302,16 @@ declare global {
         email?: string;
         /**
          * Set `true` ONLY where the address is proven: by the customer OTP verify
-         * transaction, or at creation by a storefront `register-social`, whose
-         * provider verified the email (an unverified identity creates nothing).
+         * transaction; at creation by a storefront `register-social`, whose
+         * provider verified the email (an unverified identity creates nothing); or
+         * by a storefront social sign-in (`social`, `social-bridge-redeem`) or
+         * `link-sign-in-method` whose provider asserts a verified email equal,
+         * case-insensitively, to the stored one — never through an Apple Hide My
+         * Email relay, which is not the stored address. A sign-in then answers
+         * `true` in its body and the customer's own sockets get a `customers` frame.
+         * When that sign-in is the provider's FIRST on a row that held an unproven
+         * password, the password is removed and every earlier session revoked.
+         * Any move or clear of the address resets it to `false`.
          *
          * ⚠️ UNDEFINED MEANS **NOT** VERIFIED — deliberately the INVERSE of
          * `User.emailVerified`, which carries a grandfather clause telling apps to
@@ -314,8 +322,10 @@ declare global {
          */
         emailVerified?: boolean;
         /**
-         * ms-epoch of the proof: the OTP verification, or — for a `register-social`
-         * account — the row's `createdAt`. Absent whenever `emailVerified` is not `true`.
+         * ms-epoch of the proof: the OTP verification, the social sign-in or link
+         * that proved it, or — for a `register-social` account — the row's
+         * `createdAt`. Kept from the FIRST proof; a later social sign-in does not
+         * move it. Absent or `null` whenever `emailVerified` is not `true`.
          */
         emailVerifiedAt?: number;
         /**

package/dist/store.d.ts

@@ -1222,6 +1222,14 @@ declare global {
          * until they verify. That is the tenant's decision to make, but a
          * settings UI should say so rather than presenting it as a neutral
          * switch.
+         *
+         * Web `GET /store` (and the storefront preview's store frame) ALWAYS
+         * carries it as a boolean, `true` only when the stored value is exactly
+         * `true` — absent, `false` or any other stored value reads `false`, the
+         * same test checkout applies. A storefront reads it to prompt for
+         * verification before checkout rather than after the
+         * `403 EMAIL_VERIFICATION_REQUIRED`. It is not on the customer `stores`
+         * socket frame; the next `GET /store` picks up a change.
          */
         requireEmailVerification?: boolean;
     }

package/package.json

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