customer-registration 0.0.124 → 0.0.126

package/README.md

@@ -1,53 +1,77 @@
-# Medusa Plugin: Customer Registration & OTP Verification
+# customer-registration
+> Medusa v2 plugin that extends customer auth with OTP verification, phone login (`phonepass`), verified contact updates, referral linking, and account deletion workflows.
 
-A comprehensive Medusa v2 plugin that provides OTP-based verification for email and phone functionality, with support for flexible registration identifiers, phone-only authentication, contact change flows, and account deletion.
+## Plugin Overview
 
-## Features
+This plugin customizes Medusa customer authentication and profile flows with:
 
-- **Unified OTP API**: Single endpoints for sending and verifying OTPs
-- **Token-based Verification**: Secure JWT token system for OTP verification
-- **Multiple Verification Types**: Email verification and phone verification
-- **Workflow-based Processing**: Automatic handling of verification flags
-- **Password Reset Support**: Notification subscriber for Medusa's built-in password reset flow
-- **Flexible Configuration**: Per-purpose channel configuration (email/SMS)
-- **Throttling & Rate Limiting**: Built-in protection against OTP spam
-- **Database Migrations**: Automatic schema updates for verification columns
-- **Account Deletion Request Flow**: Two-step OTP flow to request and confirm account deletion with optional cancel flow
-- **Unified registration & login**: **`POST /auth/customer/emailpass/register`** creates an **emailpass** or **phonepass** identity (from JSON body + `registration.identifier`); **`POST /auth/customer/emailpass`** logs in with `{ email, password }` or `{ phone, password }` per `login.identifier`, or **`{ email_or_phone, password }`** (values containing `@` are treated as email; otherwise as phone)
-- **Per-channel OTP at login**: When `registration.identifier` is **`"both"`** and `require_verification` is on, **email login** only requires **email** verified; **phone login** only requires **phone** verified — you can use either method after completing that channel’s OTP
-- **Authenticated Contact Change**: Dedicated OTP-verified routes for updating phone or email — new value is embedded in the signed JWT, no metadata staging required
+- OTP verification for email/phone with configurable channels (email/SMS)
+- unified register/login routes for email and phone credentials
+- secure contact change flow (`/store/customers/me/contact`) with OTP verification
+- account deletion request/cancel flows with OTP and scheduled deletion job
+- referral linkage at signup plus a customer-facing `my-referrals` endpoint
+- password reset support for both email and phone channels
 
-## Quick Start
+### Problem it solves
+
+It adds production-oriented identity controls that are not available in default customer auth flows:
+
+- enforce verified contact channels before login
+- allow phone-based auth (`phonepass`) in Medusa v2
+- avoid direct email/phone mutation without OTP proof
+- formalize account deletion lifecycle with cancellation and delayed execution
+
+### Medusa version
+
+Built for **Medusa v2** (`@medusajs/framework`, `@medusajs/medusa`, `@medusajs/cli` pinned to `2.11.2`).
+
+## Installation & Setup
+
+### Install package
 
-1. **Install the plugin**:
 ```bash
 npm install customer-registration
 ```
 
-2. **Add to medusa-config.ts**:
-```typescript
-import { defineConfig } from "@medusajs/framework/utils"
+or
+
+```bash
+yarn add customer-registration
+```
+
+### Register plugin in `medusa-config.ts`
+
+```ts
+import { defineConfig, Modules } from "@medusajs/framework/utils"
 
 export default defineConfig({
+  modules: [
+    {
+      resolve: "@medusajs/medusa/auth",
+      options: {
+        providers: [
+          {
+            resolve: "customer-registration/providers/phonepass",
+            id: "phonepass",
+          },
+        ],
+      },
+    },
+  ],
   plugins: [
     {
       resolve: "customer-registration",
       options: {
         storefrontUrl: "http://localhost:8000",
-
-        registration: {
-          identifier: "phone", // "email" | "phone" | "both"
-          require_verification: true,
-        },
-        login: {
-          identifier: "phone", // defaults to registration.identifier
-        },
-
+        registration: { identifier: "both", require_verification: true },
+        login: { identifier: "both" },
+        email_verification: { channel: "email", subject: "Verify your email" },
+        phone_verification: { channel: "sms" },
         password_reset: {
-          // With `login.identifier: "phone"`, set `sms_body` (and `storefrontUrl`). With `"email"`, set `template`. With `"both"`, set both.
-          sms_body: "Reset your password: {{reset_url}}",
+          template: "src/templates/emails/reset-password.html",
+          subject: "Reset Your Password",
+          sms_body: "Reset password: {{reset_url}}",
         },
-
         account_deletion_request: {
           template: "src/templates/emails/account-deletion-request.html",
           subject: "Confirm your account deletion request",
@@ -57,539 +81,657 @@ export default defineConfig({
           template: "src/templates/emails/account-deletion-cancel.html",
           subject: "Confirm cancellation of account deletion",
         },
-
-        email_verification: {
-          channel: "email",
-          subject: "Verify your email",
-        },
-        phone_verification: {
-          channel: "sms",
-        },
       },
     },
   ],
 })
 ```
 
-3. **Run migrations**:
+### Run migrations
+
 ```bash
 npx medusa db:migrate
 ```
 
-4. **Use the API** — see [API Endpoints](#api-endpoints) below.
-
----
+## Configuration
 
-## Installation
+### Plugin options (`options`)
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `storefrontUrl` | `string` | No | `undefined` | Base storefront URL used for password reset link generation. Required when `password_reset` is configured. |
+| `registration.identifier` | `"email" \| "phone" \| "both"` | No | `"email"` | Which identifier is used at registration. |
+| `registration.require_verification` | `boolean` | No | `true` | Whether login requires verification flags. |
+| `login.identifier` | `"email" \| "phone" \| "both"` | No | `registration.identifier` | Which login method(s) are accepted at `/auth/customer/emailpass`. |
+| `password_reset.template` | `string` | Conditional | `undefined` | Email HTML template path for reset email. Required if login channel includes email. |
+| `password_reset.subject` | `string` | No | `"Reset Your Password"` | Password reset email subject. |
+| `password_reset.sms_body` | `string` | Conditional | `undefined` | SMS template body for reset flow; supports `{{token}}`, `{{reset_url}}`, `{{phone}}`. Required if login channel includes phone. |
+| `account_deletion_request.template` | `string` | Yes when section used | none | Template for account deletion request OTP notification. |
+| `account_deletion_request.subject` | `string` | No | `"Confirm your account deletion request"` | Subject for request OTP notification. |
+| `account_deletion_request.scheduled_days` | `number` | No | `7` | Days from confirmation until deletion is due. |
+| `account_deletion_cancel.template` | `string` | Yes when section used | none | Template for cancellation OTP notification. |
+| `account_deletion_cancel.subject` | `string` | No | `"Confirm cancellation of account deletion"` | Subject for cancellation OTP notification. |
+
+### OTP module options (supported by OTP service)
+
+> ⚠️ Note: these options are implemented in `OtpVerificationService`/`OtpConfig`, but are not fully declared in `CustomerRegistrationPluginOptions` type. Confirm your expected typing strategy before publishing.
+
+| Option | Type | Required | Default | Description |
+|---|---|---:|---|---|
+| `otpLength` | `number` | No | `6` | OTP length. |
+| `otpCharset` | `"numeric" \| "alphanumeric"` | No | `"numeric"` | OTP charset. |
+| `otpExpiryMinutes` | `number` | No | `15` | OTP expiry in minutes. |
+| `maxAttempts` | `number` | No | `5` | Max verify attempts before lockout. |
+| `email_verification.channel` | `string` | Yes for email OTP | none | Notification channel (usually `email`). |
+| `email_verification.template` | `string \| null` | No | `null` | Template path. |
+| `email_verification.subject` | `string` | No | provider default | Subject for email. |
+| `email_verification.resendThrottleSeconds` | `number` | No | `90` | Resend throttle. |
+| `email_verification.autoSendOnRegistration` | `boolean` | No | `undefined` | Auto-send toggle (if used by caller flow). |
+| `phone_verification.channel` | `string` | Yes for phone OTP | none | Notification channel (usually `sms`). |
+| `phone_verification.template` | `string \| null` | No | `null` | SMS template path. |
+| `phone_verification.resendThrottleSeconds` | `number` | No | `90` | Resend throttle. |
+| `account_deletion_request.channel` | `string` | Yes for strict validation | fallback `email` | Channel for request OTP notifications. |
+| `account_deletion_request.template` | `string \| null` | Yes | none | Template path. |
+| `account_deletion_request.subject` | `string` | No | provider default | Subject. |
+| `account_deletion_request.resendThrottleSeconds` | `number` | No | `90` | Resend throttle. |
+| `account_deletion_cancel.channel` | `string` | Yes for strict validation | fallback `email` | Channel for cancellation OTP notifications. |
+| `account_deletion_cancel.template` | `string \| null` | Yes | none | Template path. |
+| `account_deletion_cancel.subject` | `string` | No | provider default | Subject. |
+| `account_deletion_cancel.resendThrottleSeconds` | `number` | No | `90` | Resend throttle. |
+
+### Complete config example
+
+```ts
+{
+  resolve: "customer-registration",
+  options: {
+    storefrontUrl: "https://store.example.com",
+    registration: {
+      identifier: "both",
+      require_verification: true,
+    },
+    login: {
+      identifier: "both",
+    },
+    otpLength: 6,
+    otpCharset: "numeric",
+    otpExpiryMinutes: 15,
+    maxAttempts: 5,
+    email_verification: {
+      channel: "email",
+      template: "src/templates/emails/otp-verification.html",
+      subject: "Verify your email",
+      resendThrottleSeconds: 90,
+    },
+    phone_verification: {
+      channel: "sms",
+      template: "src/templates/sms/otp.txt",
+      resendThrottleSeconds: 90,
+    },
+    password_reset: {
+      template: "src/templates/emails/reset-password.html",
+      subject: "Reset Your Password",
+      sms_body: "Reset password: {{reset_url}}",
+    },
+    account_deletion_request: {
+      channel: "email",
+      template: "src/templates/emails/account-deletion-request.html",
+      subject: "Confirm your account deletion request",
+      scheduled_days: 7,
+    },
+    account_deletion_cancel: {
+      channel: "email",
+      template: "src/templates/emails/account-deletion-cancel.html",
+      subject: "Confirm cancellation",
+    },
+  },
+}
+```
 
-### Local Development
+## Environment Variables
 
-1. Publish the plugin to local registry:
-```bash
-cd plugins/customer-registration
-npx medusa plugin:publish
-```
+Only one direct environment variable usage exists in plugin source:
 
-2. Install in your Medusa application:
-```bash
-cd ../../test-medusa
-npx medusa plugin:add customer-registration
-```
+| Variable | Required | Example | Purpose |
+|---|---:|---|---|
+| `NODE_ENV` | No | `production` | Used for development-only OTP config debug logging in OTP service. |
 
-3. Register the plugin in `medusa-config.ts` (see Quick Start above).
+> ⚠️ Note: JWT secret/expiry are read from Medusa config module (`projectConfig.http.jwtSecret` / `jwtExpiresIn`), not directly from `process.env` in this plugin.
 
-4. Start development mode (in plugin directory):
-```bash
-cd plugins/customer-registration
-npx medusa plugin:develop
-```
+## REST APIs / Routes
 
-5. Start your Medusa application:
-```bash
-cd ../../test-medusa
-yarn dev
-```
+### Auth routes
 
----
+#### `POST /auth/customer/emailpass/register`
+- Auth: Public
+- Description: Registers customer identity through `emailpass` or `phonepass` based on `registration.identifier`.
 
-## Configuration
+Body:
 
-### `registration.identifier`
+| Field | Type | Required | Notes |
+|---|---|---:|---|
+| `password` | `string` | Yes | Required always. |
+| `email` | `string` | Conditional | Required when mode resolves to email. |
+| `phone` | `string` | Conditional | Required when mode resolves to phone. |
 
-Controls which field is required at sign-up:
+Response:
 
-| Value | Behaviour |
-|---|---|
-| `"email"` (default) | Email required; standard Medusa registration |
-| `"phone"` | Phone required; no email needed; uses `phonepass` provider |
-| `"both"` | Both email and phone required |
+```json
+{ "token": "..." }
+```
 
-### `login.identifier`
+```bash
+curl -X POST http://localhost:9000/auth/customer/emailpass/register \
+  -H "Content-Type: application/json" \
+  -d '{"email":"alice@example.com","password":"Secret123!"}'
+```
 
-Controls which auth providers are accepted at login. Defaults to `registration.identifier`.
+#### `POST /auth/customer/emailpass`
+- Auth: Public
+- Description: Unified login endpoint for email/phone credentials.
 
-| Value | Accepted login methods |
-|---|---|
-| `"email"` | `POST /auth/customer/emailpass` with `{ "email", "password" }` only |
-| `"phone"` | Same endpoint with `{ "phone", "password" }` only |
-| `"both"` | Same endpoint; **either** email **or** phone (not both) plus `password` in the JSON body |
+Body/query params:
 
-You may send **`email_or_phone`** instead of `email` or `phone` (same endpoint): if the value contains `@`, it is used as email; otherwise as phone. Do not send `email_or_phone` together with `email` or `phone`.
+| Field | Type | Required | Notes |
+|---|---|---:|---|
+| `password` | `string` | Yes | Required. |
+| `email` | `string` | XOR | Use with password. |
+| `phone` | `string` | XOR | Use with password. |
+| `email_or_phone` | `string` | Optional alternative | Must not be combined with `email`/`phone`; value with `@` becomes email. |
 
-Login always uses **`POST /auth/customer/emailpass`** (single URL). There is **no** `/auth/customer/phonepass` route; phone registration uses the same **`POST /auth/customer/emailpass/register`** as email registration.
+Response:
 
-Credentials are normally sent in the **JSON body**; the same keys (`email`, `phone`, `email_or_phone`, `password`) can be supplied on the **query string** for missing fields (see `buildUnifiedLoginAuthData`) — prefer **body** for passwords.
+```json
+{ "token": "..." }
+```
 
-### `require_verification` and login
+#### `POST /auth/customer/emailpass/reset-password`
+- Auth: Public
+- Description: Requests password reset for email or phone channel depending on config.
 
-When **`registration.require_verification`** is **`true`** (default), login checks OTP flags **for the credential you use** (see [`enforce-registration-verification.ts`](src/api/auth/customer/shared/enforce-registration-verification.ts)):
+Body:
 
-- **`registration.identifier: "email"`** — signing in with **email** requires **`email_verified`**.
-- **`registration.identifier: "phone"`** — signing in with **phone** requires **`phone_verified`**.
-- **`registration.identifier: "both"`** — signing in with **email** requires **`email_verified`** only (phone may still be unverified). Signing in with **phone** requires **`phone_verified`** only (email may still be unverified).
+| Field | Type | Required | Notes |
+|---|---|---:|---|
+| `identifier` | `string` | Conditional | Email alias field. |
+| `email` | `string` | Conditional | Email lookup. |
+| `phone` | `string` | Conditional | Phone lookup. |
+| `email_or_phone` | `string` | Conditional | Auto-resolves by `@`. |
 
-So with **`both`**, a customer can **log in with email** after email OTP even if **phone** OTP is still pending, and the reverse for phone login.
+Response:
 
-When **`require_verification`** is **`false`**, these checks are skipped.
+```json
+{}
+```
 
-### Full options reference
+#### `POST /auth/customer/emailpass/update`
+- Auth: Public with reset token
+- Description: Completes password reset via `Authorization: Bearer <token>`.
 
-```typescript
-{
-  resolve: "customer-registration",
-  options: {
-    storefrontUrl?: string,          // Base URL for password reset links
+Body:
 
-    registration?: {
-      identifier?: "email" | "phone" | "both",  // default: "email"
-      require_verification?: boolean,            // default: true
-    },
-    login?: {
-      identifier?: "email" | "phone" | "both",  // default: registration.identifier
-    },
+| Field | Type | Required |
+|---|---|---:|
+| `password` | `string` | Yes |
+| `identifier` or `email` or `phone` or `email_or_phone` | `string` | Yes (exactly one logical lookup) |
 
-    // OTP settings (apply to all types)
-    otpLength?: number,              // default: 6
-    otpCharset?: "numeric" | "alphanumeric",  // default: "numeric"
-    otpExpiryMinutes?: number,       // default: 15
-    maxAttempts?: number,            // default: 5
-
-    email_verification?: {
-      channel: string,               // e.g. "email"
-      template?: string,
-      subject?: string,
-      resendThrottleSeconds?: number,
-      autoSendOnRegistration?: boolean,
-    },
-    phone_verification?: {
-      channel: string,               // e.g. "sms"
-      template?: string,
-      resendThrottleSeconds?: number,
-    },
+Response:
 
-    password_reset?: {
-      template?: string,             // HTML email path; required if login.identifier is "email" or "both"
-      subject?: string,
-      sms_body?: string,             // SMS text; supports {{token}}, {{reset_url}}, {{phone}} — required if login is "phone" or "both"
-    },
-    account_deletion_request?: {
-      template: string,
-      subject?: string,
-      scheduled_days?: number,       // default: 7
-    },
-    account_deletion_cancel?: {
-      template: string,
-      subject?: string,
-    },
-  },
-}
+```json
+{ "message": "Password reset successfully", "success": true }
 ```
 
----
+### Store routes
 
-## API Endpoints
+#### `POST /store/customers`
+- Auth: Pre-customer auth token (registration flow)
+- Description: Overrides default customer creation; supports `phone` and referral linking.
 
-### Registration & Initial Verification
+Body:
 
-| Endpoint | Method | Auth | Description |
-|---|---|---|---|
-| `/store/customers` | POST | Bearer (pre-customer) | Create customer account |
-| `/store/customers/otp/send` | POST | — | Send OTP for initial email/phone verification |
-| `/store/customers/otp/verify` | POST | — | Verify OTP code; returns login token on success |
+| Field | Type | Required | Notes |
+|---|---|---:|---|
+| `email` | `string` | Conditional | Depends on `registration.identifier`. |
+| `phone` | `string` | Conditional | Depends on `registration.identifier`. |
+| `first_name` | `string` | No | |
+| `last_name` | `string` | No | |
+| `company_name` | `string` | No | |
+| `metadata` | `object` | No | `metadata.referral_code` is consumed then removed. |
+| `referral_code` | `string` | No | Referrer customer id. |
 
-#### Send OTP
+Response:
 
-```bash
-POST /store/customers/otp/send
-{
-  "customer_id": "cus_...",
-  "type": "phone_verification"  # or "email_verification"
-}
-# Response: { "token": "...", "expires_at": "..." }
+```json
+{ "customer": { "id": "cus_...", "...": "..." } }
 ```
 
-#### Verify OTP
+#### `GET /store/customers/me`
+- Auth: Customer JWT
+- Description: Returns customer with appended `email_verified` and `phone_verified`.
 
-```bash
-POST /store/customers/otp/verify
-{
-  "token": "<token from send>",
-  "code": "482917"
-}
-# Response: { "verified": true, "customer": {...}, "token": "<login jwt>", "needs_login": false }
-```
+#### `PATCH /store/customers/me`
+- Auth: Customer JWT
+- Description: Updates non-contact profile fields only.
+- Rejects: `email`, `phone` with `NOT_ALLOWED`.
 
----
+#### `POST /store/customers/me/contact`
+- Auth: Customer JWT
+- Description: Starts contact change OTP flow.
 
-### Login & registration (customer auth)
+Body:
 
-Implementation lives under [`src/api/auth/customer/`](src/api/auth/customer/): **`emailpass/`** (login, **register**, password reset), **`shared/`** (credential parsing, verification, JWT helpers).
+| Field | Type | Required | Notes |
+|---|---|---:|---|
+| `email` | `string` | XOR | Exactly one of `email`/`phone`. |
+| `phone` | `string` | XOR | Exactly one of `email`/`phone`. |
 
-| Endpoint | Method | Description |
-|---|---|---|
-| `/auth/customer/emailpass/register` | POST | **Register.** JSON: `password` plus identifier per `registration.identifier` — **`email`** only for `"email"` and `"both"` (for `"both"`, phone is added on `POST /store/customers`); **`phone`** only for `"phone"`. Dispatches to `register("emailpass")` or `register("phonepass")`. Response: `{ "token" }` (pre-customer JWT). See [`emailpass/register/route.ts`](src/api/auth/customer/emailpass/register/route.ts), [`parse-register-body.ts`](src/api/auth/customer/shared/parse-register-body.ts), [`complete-registration-token.ts`](src/api/auth/customer/shared/complete-registration-token.ts). |
-| `/auth/customer/emailpass` | POST | **Login.** JSON: `password` plus **exactly one** of `email` or `phone` (XOR), **or** `email_or_phone` alone (expanded to email vs phone by `@`). Optional query params can fill missing keys (body wins). [`emailpass/route.ts`](src/api/auth/customer/emailpass/route.ts) → [`handleCustomerLogin`](src/api/auth/customer/shared/customer-login-post.ts). |
+Response:
 
-Password reset supports email and/or SMS by `login.identifier`; see [Password Reset](#password-reset).
+```json
+{ "token": "...", "expires_at": "..." }
+```
 
----
+#### `POST /store/customers/me/contact/verify`
+- Auth: Customer JWT
+- Description: Verifies OTP and atomically updates contact + verification flags.
 
-### Contact Change (Phone or Email Update)
+Body:
 
-> These are the dedicated authenticated routes for changing a customer's phone or email.
-> `PATCH /store/customers/me` **rejects** `phone` and `email` fields — all contact changes must go through these endpoints.
+| Field | Type | Required |
+|---|---|---:|
+| `token` | `string` | Yes |
+| `code` | `string` | Yes |
 
-| Endpoint | Method | Auth | Description |
-|---|---|---|---|
-| `/store/customers/me/contact` | POST | Customer JWT | Request contact change — validates new value, sends OTP, returns token |
-| `/store/customers/me/contact/verify` | POST | Customer JWT | Verify OTP and apply the change |
+Response:
 
-#### How it works
+```json
+{ "customer": { "id": "cus_..." }, "token": "..." }
+```
 
-The new phone or email is embedded directly in the signed OTP JWT. No metadata is written to the customer record during the pending state. On successful verification:
+#### `POST /store/customers/otp/send`
+- Auth: Public
+- Description: Sends OTP for verification/account deletion purpose.
 
-1. `customer.phone` / `customer.email` is updated
-2. `phone_verified` / `email_verified` is set to `true`
-3. `provider_identity.entity_id` is updated for `phonepass` / `emailpass` **only when the changed field is the active `login.identifier`** — so login continues to work with the new value
+Body:
 
-#### Step 1 — Request the change
+| Field | Type | Required |
+|---|---|---:|
+| `customer_id` | `string` | Yes |
+| `type` | `"email_verification" \| "phone_verification"` | Yes |
 
-```bash
-curl -X POST http://localhost:9000/store/customers/me/contact \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $CUSTOMER_JWT" \
-  -d '{ "phone": "+15559998888" }'
+Response:
 
-# Response
-{ "token": "<otp_token>", "expires_at": "2026-03-12T10:15:00.000Z" }
+```json
+{ "token": "...", "expires_at": "..." }
 ```
 
-Only one field at a time is accepted. Sending both `phone` and `email` returns a `400`.
+#### `POST /store/customers/otp/verify`
+- Auth: Public
+- Description: Verifies OTP and triggers verification workflow.
 
-#### Step 2 — Verify the OTP
+Body:
 
-```bash
-curl -X POST http://localhost:9000/store/customers/me/contact/verify \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $CUSTOMER_JWT" \
-  -d '{
-    "token": "<otp_token from step 1>",
-    "code": "482917"
-  }'
+| Field | Type | Required |
+|---|---|---:|
+| `token` | `string` | Yes |
+| `code` | `string` | Yes |
 
-# Response
+Response:
+
+```json
 {
-  "customer": { "id": "cus_...", "phone": "+15559998888", ... },
-  "token": "<fresh_login_jwt>"
+  "verified": true,
+  "customer": {},
+  "email_verified": true,
+  "token": null,
+  "needs_login": true
 }
 ```
 
-The response includes a **fresh login JWT** so the caller is immediately re-authenticated after the change.
-
-#### Security notes
+#### `POST /store/customers/change-password`
+- Auth: Customer JWT
+- Description: Changes password using old/new/confirm values.
 
-- The OTP token is signed with the server's `jwtSecret` — the new value cannot be tampered with
-- The verify route checks that `token.customer_id === auth_context.actor_id`, preventing one customer from applying another's OTP
-- `provider_identity.entity_id` sync has a compensation function: if a later workflow step fails the `entity_id` is rolled back to the original value
-- If the current phone/email is `null` (first-time contact assignment), the flow works identically — the field is set from null to the new value and marked verified
+Body:
 
-#### What `PATCH /store/customers/me` does now
+| Field | Type | Required |
+|---|---|---:|
+| `old_password` | `string` | Yes |
+| `new_password` | `string` | Yes |
+| `confirm_password` | `string` | Yes |
 
-Non-contact fields (e.g. `first_name`, `last_name`) continue to work as before. Passing `phone` or `email` in the body returns:
+Response:
 
 ```json
-{
-  "type": "not_allowed",
-  "message": "Phone changes require OTP verification. Use POST /store/customers/me/contact to request a change."
-}
+{ "message": "Password changed successfully", "customer_id": "cus_..." }
 ```
 
----
+#### `POST /store/customers/account-deletion/request`
+- Auth: Customer JWT
+- Description: Sends OTP for deletion confirmation.
 
-### Profile Update
+Body:
 
-| Endpoint | Method | Auth | Description |
-|---|---|---|---|
-| `/store/customers/me` | PATCH | Customer JWT | Update non-contact profile fields (first_name, last_name, etc.) |
+| Field | Type | Required |
+|---|---|---:|
+| `reason` | `string \| null` | No |
 
----
+Response:
 
-### Password Reset
+```json
+{ "token": "...", "expires_at": "..." }
+```
 
-Allowed JSON fields follow **`login.identifier`** (same idea as login): **`email`**, **`phone`**, **`email_or_phone`**, or **`identifier`** (email alias). Exactly one lookup field; do not combine with `email_or_phone` and `email`/`phone` at once.
+#### `POST /store/customers/account-deletion/confirm`
+- Auth: Public
+- Description: Confirms deletion request via OTP; creates confirmed request row.
 
-| `login.identifier` | Request reset with |
-|---|---|
-| `email` | `email`, `identifier`, or `email_or_phone` containing `@` |
-| `phone` | `phone` or `email_or_phone` without `@` |
-| `both` | Any of the above |
+Body:
 
-- **Email** path: sends HTML email using `password_reset.template`.
-- **Phone** path: sends **SMS** using `password_reset.sms_body` (placeholders: `{{token}}`, `{{reset_url}}`, `{{phone}}`).
-- **Config**: `storefrontUrl` is required when `password_reset` is set. If login is `email`, `template` is required; if `phone`, `sms_body` is required; if `both`, **both** `template` and `sms_body` are required (validated at plugin load).
+| Field | Type | Required |
+|---|---|---:|
+| `token` | `string` | Yes |
+| `code` | `string` | Yes |
 
-| Endpoint | Method | Description |
-|---|---|---|
-| `/auth/customer/emailpass/reset-password` | POST | Request reset (email and/or SMS per channel) |
-| `/auth/customer/emailpass/update` | POST | Set new password; `Authorization: Bearer <token>` + same lookup field shape as request + `password` |
+Response:
 
-```bash
-# Request reset (email example)
-POST /auth/customer/emailpass/reset-password
-{ "identifier": "customer@example.com" }
-
-# Request reset (phone example)
-POST /auth/customer/emailpass/reset-password
-{ "phone": "+15551234567" }
-
-# Complete reset (use Bearer token from link; body must include matching email or phone)
-POST /auth/customer/emailpass/update
-Authorization: Bearer <reset_token>
-{ "email": "customer@example.com", "password": "NewPassword123!" }
+```json
+{
+  "request": {
+    "id": "adr_...",
+    "customer_id": "cus_...",
+    "reason": null,
+    "deletion_scheduled_at": "...",
+    "status": "confirmed"
+  }
+}
 ```
 
----
+#### `POST /store/customers/account-deletion/cancel-request`
+- Auth: Public (IP rate-limited)
+- Description: Sends OTP for canceling an active deletion request.
 
-### Account Deletion
+Body:
 
-| Endpoint | Method | Auth | Description |
-|---|---|---|---|
-| `/store/customers/account-deletion/request` | POST | Customer JWT | Request deletion — sends OTP, returns token |
-| `/store/customers/account-deletion/confirm` | POST | — | Confirm deletion with OTP code |
-| `/store/customers/account-deletion/cancel-request` | POST | — | Request cancellation (lookup by email/phone) |
-| `/store/customers/account-deletion/cancel-confirm` | POST | — | Confirm cancellation with OTP code |
-| `/admin/account-deletion-requests` | GET | Admin JWT | List deletion requests |
+| Field | Type | Required |
+|---|---|---:|
+| `email` | `string` | Conditional |
+| `phone` | `string` | Conditional |
 
-```bash
-# 1. Request deletion
-curl -X POST http://localhost:9000/store/customers/account-deletion/request \
-  -H "Authorization: Bearer $CUSTOMER_JWT" \
-  -d '{"reason": "No longer need account"}'
-# Response: { "token": "...", "expires_at": "..." }
-
-# 2. Confirm deletion
-curl -X POST http://localhost:9000/store/customers/account-deletion/confirm \
-  -d '{"token": "...", "code": "123456"}'
-
-# 3. Request cancel (no auth; email lookup)
-curl -X POST http://localhost:9000/store/customers/account-deletion/cancel-request \
-  -d '{"email": "customer@example.com"}'
-
-# 4. Confirm cancel
-curl -X POST http://localhost:9000/store/customers/account-deletion/cancel-confirm \
-  -d '{"token": "...", "code": "123456"}'
-```
+Response:
 
----
+```json
+{ "token": "...", "expires_at": "..." }
+```
 
-## Phone-only Registration & Login (`phonepass`)
+#### `POST /store/customers/account-deletion/cancel-confirm`
+- Auth: Public
+- Description: Confirms cancellation OTP and marks request canceled.
 
-When `registration.identifier = "phone"`, customers register and log in with phone + password only. No email address is required.
+Body:
 
-### 1. Register the provider in `medusa-config.ts`
+| Field | Type | Required |
+|---|---|---:|
+| `token` | `string` | Yes |
+| `code` | `string` | Yes |
 
-```typescript
-import { Modules } from "@medusajs/framework/utils"
+Response:
 
-export default defineConfig({
-  modules: [
-    {
-      resolve: "@medusajs/medusa/auth",
-      options: {
-        providers: [
-          {
-            resolve: "customer-registration/providers/phonepass",
-            id: "phonepass",
-          },
-        ],
-      },
-    },
-  ],
-  plugins: [
-    {
-      resolve: "customer-registration",
-      options: {
-        registration: {
-          identifier: "phone",
-          require_verification: true,
-        },
-        login: {
-          identifier: "phone",
-        },
-        phone_verification: {
-          channel: "sms",
-        },
-      },
-    },
-  ],
-})
+```json
+{
+  "cancelled": true,
+  "request": {
+    "id": "adr_...",
+    "customer_id": "cus_...",
+    "status": "cancelled",
+    "cancelled_at": "..."
+  }
+}
 ```
 
-### 2. Registration flow
-
-```bash
-# Step 1 — create phonepass auth identity (unified register URL)
-POST /auth/customer/emailpass/register
-{ "phone": "+15551234567", "password": "SecretPass1!" }
-# Response: { "token": "<pre-customer jwt>" }
-
-# Step 2 — create customer record
-POST /store/customers
-Authorization: Bearer <token>
-{ "phone": "+15551234567", "first_name": "Jane" }
-
-# Step 3 — send phone OTP
-POST /store/customers/otp/send
-{ "customer_id": "cus_...", "type": "phone_verification" }
-# Response: { "token": "<otp_token>", "expires_at": "..." }
-
-# Step 4 — verify phone OTP (returns login token)
-POST /store/customers/otp/verify
-{ "token": "<otp_token>", "code": "482917" }
-# Response: { "verified": true, "phone_verified": true, "token": "<login jwt>" }
-```
+#### `GET /store/my-referrals`
+- Auth: Customer JWT
+- Description: Returns customers referred by the authenticated customer.
 
-### 3. Login flow
+Response:
 
-```bash
-POST /auth/customer/emailpass
-{ "phone": "+15551234567", "password": "SecretPass1!" }
-# Response: { "token": "<jwt>" }
+```json
+{
+  "children": [
+    {
+      "referral_link_id": "refl_...",
+      "referred_at": "...",
+      "parent_customers_by_level": { "1": "cus_referrer" },
+      "customer": {
+        "id": "cus_child",
+        "email": "child@example.com",
+        "first_name": null,
+        "last_name": null,
+        "phone": null,
+        "created_at": "..."
+      }
+    }
+  ]
+}
 ```
 
-### 3b. Password reset (phone)
+### Admin routes
 
-Configure `password_reset.sms_body`, `storefrontUrl`, and the notification module for SMS. Then:
+#### `GET /admin/account-deletion-requests`
+- Auth: Admin JWT
+- Description: Lists account deletion requests with filtering/pagination.
 
-```bash
-POST /auth/customer/emailpass/reset-password
-{ "phone": "+15551234567" }
+Query params:
 
-POST /auth/customer/emailpass/update
-Authorization: Bearer <token from SMS link>
-{ "phone": "+15551234567", "password": "NewSecretPass1!" }
-```
+| Param | Type | Required | Default |
+|---|---|---:|---|
+| `status` | `pending \| confirmed \| cancelled \| completed` | No | none |
+| `limit` | `number` | No | `20` |
+| `offset` | `number` | No | `0` |
+| `order` | `created_at \| updated_at \| customer_id` | No | `created_at` |
+| `order_direction` | `ASC \| DESC` | No | `DESC` |
 
-### 4. Update phone (after registration)
+Response:
 
-```bash
-# Request change
-POST /store/customers/me/contact
-Authorization: Bearer <login jwt>
-{ "phone": "+15559998888" }
-# Response: { "token": "<otp_token>", "expires_at": "..." }
-
-# Verify and apply
-POST /store/customers/me/contact/verify
-Authorization: Bearer <login jwt>
-{ "token": "<otp_token>", "code": "739201" }
-# Response: { "customer": { "phone": "+15559998888", ... }, "token": "<fresh jwt>" }
+```json
+{
+  "requests": [],
+  "count": 0,
+  "offset": 0,
+  "limit": 20
+}
 ```
 
----
+## Services
 
-## Modules
+### `OtpVerificationService`
+Manages OTP generation, validation, verification state updates, and channel config lookup.
 
-The plugin includes three modules:
+Key methods:
+- `generateOtpWithCode(input, jwtSecret)`
+- `generateOtpForContactChange(input, jwtSecret, newValue, contactType)`
+- `verifyOtp(input, jwtSecret)`
+- `decodeContactChangeToken(token, jwtSecret)`
+- `getCustomerVerificationByCustomerId(context, customerId)`
+- `updateEmailVerified(context, customerId)`
+- `updatePhoneVerified(context, customerId)`
 
-1. **`otp-verification`** — OTP generation, verification, and management
-2. **`customer-registration`** — Customer registration logic and route overrides
-3. **`account-deletion-request`** — Account deletion request lifecycle (pending → confirmed → completed/cancelled)
+### `AccountDeletionRequestService`
+Manages deletion lifecycle records and admin/job access patterns.
 
-## Workflows
+Key methods:
+- `createConfirmed(customer_id, deletion_scheduled_at)`
+- `cancelRequest(customer_id)`
+- `getActiveByCustomerId(customer_id)`
+- `hasPendingRequest(customerId)`
+- `hasActiveRequest(customerId)`
+- `listForAdmin(selector, listConfig)`
+- `listDueForDeletion(limit)`
+- `markCompleted(id)`
 
-| Workflow | Description |
-|---|---|
-| `verify-email` | Sets `email_verified = true` on the customer record |
-| `verify-phone` | Sets `phone_verified = true` on the customer record |
-| `update-contact` | Updates `customer.phone` / `customer.email`, sets verified flag, syncs `provider_identity.entity_id` when applicable |
-| `send-otp` | Resolves channel config, generates OTP, sends notification |
-| `send-contact-change-otp` | Generates OTP with `new_value` embedded in JWT, sends to the new contact address |
-| `change-password` | Updates customer password via the auth module |
+### `ReferralLinkModuleService`
+CRUD service for referral links (inherits generated methods from `MedusaService`).
 
-## Database Migrations
+### `PasswordManagementService`
+Utility service for password hash lookup/verification/update against provider identities.
 
-| Migration | Description |
-|---|---|
-| `Migration20250120000000AddCustomerVerificationColumns` | Adds `email_verified` and `phone_verified` columns to the customer table |
-| `Migration20250118001000CreateOtpVerificationTable` | Creates `otp_verification` table |
-| `Migration20250221000000CreateAccountDeletionRequestTable` | Creates `account_deletion_request` table |
-| `Migration20250221000000AddAccountDeletionOtpPurposes` | Extends `otp_verification.purpose` enum for account deletion flows |
+### `CustomerRegistrationService`
+Placeholder module service for registration-related extension points.
 
-```bash
-npx medusa db:migrate
-```
-
-## Password Reset (Helper Functions)
-
-```typescript
-import {
-  requestPasswordReset,
-  completePasswordReset,
-} from "customer-registration/helpers"
-
-await requestPasswordReset(
-  { email: "customer@example.com" },
-  { baseUrl: "https://store.example.com", publishableApiKey: "pk_..." }
-)
-
-await requestPasswordReset(
-  { phone: "+15551234567" },
-  { baseUrl: "https://store.example.com", publishableApiKey: "pk_..." }
-)
-
-await completePasswordReset(
-  {
-    email: "customer@example.com",
-    password: "NewPassword123!",
-    token: "reset_token_from_email",
-  },
-  { baseUrl: "https://store.example.com", publishableApiKey: "pk_..." }
-)
-```
+## Workflows & Steps
 
-## Requirements
+### Workflows
 
-- Medusa v2.11.2 or higher
-- Node.js >= 20
-- Notification module configured with at least one provider (email/SMS)
-- Database migrations applied (`npx medusa db:migrate`)
-- **`phonepass`** auth provider registered in `medusa-config` (required when customers can **register** or **log in** with phone — i.e. `registration.identifier` and/or `login.identifier` is `"phone"` or `"both"`)
-
-## Documentation
-
-This **README** is the main overview: configuration, auth routes, OTP behaviour, and API tables.
-
-## Development
-
-```bash
-# Build
-npm run build
-
-# Watch mode
-npx medusa plugin:develop
-```
-
-## License
-
-MIT
+| Workflow | Input | Output | Purpose |
+|---|---|---|---|
+| `send-otp` | `{ customer_id, type }` | `{ token, expires_at }` | Generic OTP send pipeline (customer lookup, config, token, notification). |
+| `send-contact-change-otp` | `{ customer_id, new_value, contact_type, otp_type }` | `{ token, expires_at }` | Sends OTP to new email/phone; token embeds pending value. |
+| `update-contact` | `{ customer_id, new_value, contact_type, login_identifier }` | `{ customer_id, customer }` | Updates contact, sets verified flags, syncs provider identity with compensation. |
+| `verify-email` | `{ customer_id }` | `{ customer_id, email_verified, customer }` | Marks email verified and returns updated customer. |
+| `verify-phone` | `{ customer_id, login_identifier? }` | `{ customer_id, phone_verified, customer }` | Marks phone verified and syncs `phonepass` entity id when needed. |
+| `change-password` | `{ customer_id, old_password, new_password, confirm_password }` | `{ customer_id, success }` | Validates and updates password through auth provider. |
+
+### Steps
+
+- `retrieve-customer`
+- `resolve-channel-config`
+- `determine-contact-method`
+- `generate-otp`
+- `generate-contact-change-otp`
+- `prepare-template-data`
+- `load-template`
+- `send-notification`
+- `find-customer-by-email`
+- `update-password`
+- `sync-phonepass-entity-id`
+
+## Subscribers / Event Hooks
+
+### `auth.password_reset` subscriber
+- File: `src/subscribers/password-reset.ts`
+- Event: `auth.password_reset`
+- Behavior: renders configured password reset template and sends email notification using notification module.
+
+## Admin UI / Extensions
+
+### Account Deletion Requests page
+- File: `src/admin/routes/account-deletion-requests/page.tsx`
+- Placement: Admin route labeled **Account Deletion Requests** (trash icon)
+- Renders:
+  - filterable/paginated table
+  - status badges (`pending`, `confirmed`, `cancelled`, `completed`)
+  - refresh + load more interactions
+- Data source: `GET /admin/account-deletion-requests`
+
+## Models & Entities
+
+### `otp_verification`
+| Field | Type | Nullable |
+|---|---|---:|
+| `id` | `text` | No |
+| `customer_id` | `text` | No |
+| `purpose` | enum | No |
+| `hashed_code` | `text` | No |
+| `expires_at` | `datetime` | No |
+| `attempts` | `number` | No |
+| `verified_at` | `datetime` | Yes |
+
+### `account_deletion_request`
+| Field | Type | Nullable |
+|---|---|---:|
+| `id` | `text` | No |
+| `customer_id` | `text` | No |
+| `reason` | `text` | Yes |
+| `deletion_scheduled_at` | `datetime` | Yes |
+| `status` | enum | No |
+| `cancelled_at` | `datetime` | Yes |
+
+### `referral_link`
+| Field | Type | Nullable |
+|---|---|---:|
+| `id` | `text` | No |
+| `customer_id` | `text` | No |
+| `referrer_id` | `text` | No |
+| `parent_customers_by_level` | `json` | No |
+
+### Core Medusa relationships
+- `customer_id` fields link to Medusa `customer` table by convention.
+- auth linkage is handled through `auth_identity.app_metadata.customer_id` and `provider_identity`.
+
+## Jobs
+
+### `process-account-deletions`
+- Schedule: hourly (`0 * * * *`)
+- Flow:
+  1. load due confirmed requests
+  2. delete auth identities for customer
+  3. delete customer
+  4. mark request as `completed`
+
+## Use Cases & Examples
+
+1. **Phone-first storefront signup**  
+   Use `POST /auth/customer/emailpass/register` with phone+password, then `POST /store/customers`, then OTP send/verify routes.
+
+2. **Secure email/phone change in customer profile**  
+   Use `POST /store/customers/me/contact` + `POST /store/customers/me/contact/verify` instead of direct patch.
+
+3. **Regulatory account deletion process**  
+   Use request/confirm/cancel flows under `/store/customers/account-deletion/*` and rely on scheduled deletion job.
+
+4. **Referral tree tracking for customers**  
+   Pass `referral_code` on signup and fetch referrals via `GET /store/my-referrals`.
+
+5. **Channel-aware password reset**  
+   Use `/auth/customer/emailpass/reset-password` and `/auth/customer/emailpass/update` with email, phone, or `email_or_phone`.
+
+## Troubleshooting
+
+### `storefrontUrl is required when password_reset is configured`
+- Cause: `password_reset` enabled without `storefrontUrl`.
+- Fix: set `options.storefrontUrl`.
+
+### OTP channel configuration not found
+- Cause: missing `email_verification.channel`, `phone_verification.channel`, or account deletion channel/template.
+- Fix: add channel config in plugin options.
+
+### `Phone login is not enabled` / `Email login is not enabled`
+- Cause: credential channel does not match `login.identifier`.
+- Fix: align request payload with config, or change `login.identifier`.
+
+### Password reset succeeds with empty `{}` but user gets no message
+- Cause: security behavior intentionally hides account existence and may swallow notification delivery errors.
+- Fix: verify notification module config, template path, and channel provider setup.
+
+### Contact change verify returns unauthorized token mismatch
+- Cause: OTP token used by different authenticated customer.
+- Fix: ensure same customer JWT that initiated the contact-change request is used during verify.
+
+### Account deletion routes blocked / login blocked
+- Cause: customer has active (`pending`/`confirmed`) deletion request; guard middleware blocks most store routes.
+- Fix: complete cancel flow (`cancel-request` + `cancel-confirm`) or allow job to complete deletion.
+
+### `JWT secret is not configured`
+- Cause: Medusa HTTP JWT config missing.
+- Fix: configure `projectConfig.http.jwtSecret` in Medusa app config.
+
+## Helper Utilities
+
+The package exports helper functions from `customer-registration/helpers`:
+
+- `requestPasswordReset(input, options)`
+- `completePasswordReset(input, options)`
+- `createRequestPasswordReset(options)`
+- `createCompletePasswordReset(options)`
+
+These support Medusa SDK client mode or direct fetch mode with optional `x-publishable-api-key`.
+
+## Migrations Included
+
+- `Migration20250118001000CreateOtpVerificationTable`
+- `Migration20250120000000RemoveForgotPasswordFromOtpPurpose`
+- `Migration20250221000000AddAccountDeletionOtpPurposes`
+- `Migration20250120000000AddCustomerVerificationColumns`
+- `Migration20250221000000CreateAccountDeletionRequestTable`
+- `Migration20250221100000AddCompletedStatusToAccountDeletionRequest`
+- `Migration20260502100000CreateReferralLinkTable`