postex-auth-sdk-stage 2.3.0 → 3.0.0

package/README.md

@@ -101,7 +101,7 @@ Accepts either a direct email string or an identifier object.
 
 ```typescript
 async getStatus(
-  identifier: string | { email?: string; mobileNumber?: string }
+  identifier: string | { email?: string; mobileNumber?: string; username?: string }
 ): Promise<AuthStatusResponse>
 ```
 
@@ -110,6 +110,7 @@ async getStatus(
 - `auth.getStatus('user@example.com')`
 - `auth.getStatus({ email: 'user@example.com' })`
 - `auth.getStatus({ mobileNumber: '03011266254' })`
+- `auth.getStatus({ username: 'user123' })`
 
 **Returns:**
 
@@ -126,13 +127,22 @@ Start the authentication process. Returns either a WebAuthn challenge or confirm
 
 ```typescript
 async initiateAuth(
-  identifier: string | { email?: string; mobileNumber?: string }
+  identifier: string | { email?: string; mobileNumber?: string; username?: string }
 ): Promise<InitiateAuthResponse>
 ```
 
+**Supported input forms:**
+
+- `auth.initiateAuth('user@example.com')`
+- `auth.initiateAuth({ email: 'user@example.com' })`
+- `auth.initiateAuth({ mobileNumber: '03011266254' })`
+- `auth.initiateAuth({ username: 'user123' })`
+
 **Returns:**
 
 - `status`: `'webauthn_challenge'` | `'otp_sent'`
+- `message`: Backend initiation message
+- `delivery`: OTP delivery metadata when status is `'otp_sent'`
 - `challenge`, `credentialIds`, `rp`: WebAuthn data if status is `'webauthn_challenge'`
 
 ---
@@ -140,24 +150,34 @@ async initiateAuth(
 #### initiateOTP()
 
 Start OTP authentication directly via `/otp/initiate`.
-Requires at least one identifier: `email` or `mobileNumber`.
+Requires at least one identifier: `email`, `mobileNumber`, or `username`.
 
 ```typescript
 async initiateOTP(
-  identifier: string | { email?: string; mobileNumber?: string }
+  identifier: string | { email?: string; mobileNumber?: string; username?: string }
 ): Promise<{
+  statusText?: string;
   message?: string;
+  statusCode?: number;
+  success?: boolean;
+  data?: {
+    delivery?: {
+      channel: 'email' | 'sms';
+      target: string;
+    };
+  };
 }>
 ```
 
 **Supported input forms:**
 - `auth.initiateOTP({ email: 'user@example.com' })`
 - `auth.initiateOTP({ mobileNumber: '03011266254' })`
-- `auth.initiateOTP({ email: 'user@example.com' })`
+- `auth.initiateOTP({ username: 'user123' })`
 
 **Validation:**
 
-- Throws an error when both `email` and `mobileNumber` are missing/empty.
+- Throws an error when `email`, `mobileNumber`, and `username` are all missing/empty.
+- `username` is trimmed, must be 64 characters or fewer, and must not contain control characters.
 
 ---
 
@@ -184,13 +204,23 @@ async verifyOTP(otp: string): Promise<OTPVerifyResponse>
 Resend OTP code for the standard login OTP flow.
 
 ```typescript
-async resendOTP(): Promise<{ success: boolean; message?: string }>
+async resendOTP(): Promise<{
+  message?: string;
+  success?: boolean;
+  data?: {
+    delivery?: {
+      channel: 'email' | 'sms';
+      target: string;
+    };
+  };
+}>
 ```
 
 **Returns:**
 
-- `success`: Whether resend request was accepted
-- `message`: Optional backend message
+- `message`: Backend resend message
+- `success`: Whether resend request was accepted, when provided by the backend
+- `data.delivery`: OTP delivery channel and masked target
 
 ---
 

package/dist/auth.d.ts

@@ -2,6 +2,7 @@ type AuthEntity = "xstak" | "postex" | "callcourier" | "postexglobal" | "postexs
 type AuthIdentifierInput = string | {
     email?: string;
     mobileNumber?: string;
+    username?: string;
     realm?: string;
 };
 interface RealmOptions {
@@ -25,8 +26,15 @@ interface AuthStatusResponse {
 }
 /** Response from POST /auth/initiate */
 type InitiateAuthStatusType = "webauthn_challenge" | "otp_sent";
+type OTPDeliveryChannel = "email" | "sms";
+interface OTPDeliveryMetadata {
+    channel: OTPDeliveryChannel;
+    target: string;
+}
 interface InitiateAuthResponse {
     status: InitiateAuthStatusType;
+    message?: string;
+    delivery?: OTPDeliveryMetadata;
     challenge?: string;
     credentialIds?: string[];
     rp?: {
@@ -49,7 +57,16 @@ interface OTPInitiateResponse {
     success?: boolean;
     message?: string;
     data?: {
-        message?: string;
+        delivery?: OTPDeliveryMetadata;
+        [key: string]: any;
+    };
+    [key: string]: any;
+}
+interface OTPResendResponse {
+    message?: string;
+    success?: boolean;
+    data?: {
+        delivery?: OTPDeliveryMetadata;
         [key: string]: any;
     };
     [key: string]: any;
@@ -126,6 +143,7 @@ export declare class AuthSDK {
     private assertNoControlChars;
     private validateEmail;
     private validateMobileNumber;
+    private validateUsername;
     private validateOTP;
     private validateMagicLinkToken;
     private validateRealm;
@@ -149,12 +167,12 @@ export declare class AuthSDK {
     getStatus(identifier: AuthIdentifierInput, options?: RealmOptions): Promise<AuthStatusResponse>;
     /**
      * POST /auth/initiate - Unified entry: returns webauthn_challenge or otp_sent.
-     * Sets auth_session cookie when otp_sent.
+     * Sets auth_session cookie and includes delivery metadata when otp_sent.
      */
     initiateAuth(identifier: AuthIdentifierInput, options?: RealmOptions): Promise<InitiateAuthResponse>;
     /**
-     * POST /otp/initiate - Direct OTP initiation using email or mobile number.
-     * Requires at least one identifier: email or mobileNumber.
+     * POST /otp/initiate - Direct OTP initiation using email, mobile number, or username.
+     * Requires at least one identifier: email, mobileNumber, or username.
      */
     initiateOTP(identifier: AuthIdentifierInput, options?: RealmOptions): Promise<OTPInitiateResponse>;
     /**
@@ -163,13 +181,10 @@ export declare class AuthSDK {
      */
     verifyOTP(otp: string): Promise<OTPVerifyResponse>;
     /**
-     * POST /resend - Resend OTP code to the user's email.
+     * POST /otp/resend - Resend OTP code to the user's email or mobile number.
      * No payload required, relies on auth_session cookie.
      */
-    resendOTP(): Promise<{
-        success: boolean;
-        message?: string;
-    }>;
+    resendOTP(): Promise<OTPResendResponse>;
     /**
      * POST /otp/signup/verify - Verify OTP for signup flow.
      * Stores tokens from the response when provided by backend.