@blezgo/api-sdk 0.1.0

package/dist/authentication/generated.d.ts

@@ -0,0 +1,746 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export interface paths {
+    "/v1/auth/sessions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Login User
+         * @description Authenticate user and create session.
+         *
+         *     **Authentication**: None (public endpoint)
+         *     **Rate Limit**: 10 requests per minute
+         *
+         *     ## Request Body Examples:
+         *
+         *     ### Login with Email + Password:
+         *     ```json
+         *     {
+         *         "email": "john.doe@example.com",
+         *         "password": "SecurePass123!",
+         *         "space_id": "spc_abc123xyz",
+         *         "device_id": "device_uuid_12345",
+         *         "g_recaptcha_response": "03AGdBq27..."
+         *     }
+         *     ```
+         *
+         *     ### Login with Username + Password:
+         *     ```json
+         *     {
+         *         "username": "johndoe",
+         *         "password": "SecurePass123!",
+         *         "space_id": "spc_abc123xyz",
+         *         "device_id": "device_uuid_12345"
+         *     }
+         *     ```
+         *
+         *     ### Login with Mobile + Password:
+         *     ```json
+         *     {
+         *         "mobile_isd_code": "+1",
+         *         "mobile_no": "5551234567",
+         *         "password": "SecurePass123!",
+         *         "space_id": "spc_abc123xyz"
+         *     }
+         *     ```
+         *
+         *     ### Login with Mobile + OTP:
+         *     ```json
+         *     {
+         *         "mobile_isd_code": "+1",
+         *         "mobile_no": "5551234567",
+         *         "otp": "1234",
+         *         "space_id": "spc_abc123xyz"
+         *     }
+         *     ```
+         *
+         *     ## Required Fields:
+         *     - **Identifier**: One of: `email`, `username`, or (`mobile_isd_code` + `mobile_no`)
+         *     - **Credentials**: Either `password` or `otp`
+         *     - **Space**: `space_id` (external ID format: `spc_xxx`)
+         *
+         *     ## Optional Fields:
+         *     - **device_id**: UUID for device trust (enables "remember this device" for MFA)
+         *     - **g_recaptcha_response**: reCAPTCHA token (required if triggered by failed attempts)
+         *     - **tracking_id**: UTM/campaign tracking identifier
+         *     - **return_data**: Additional data to return in response
+         *
+         *     ## Response Scenarios:
+         *
+         *     ### Standard Success:
+         *     Returns `access_token`, `user` data, and session info.
+         *     `refresh_token` is set as an HttpOnly cookie — not returned in the response body.
+         *
+         *     ### MFA Required (if enabled):
+         *     ```json
+         *     {
+         *         "status": "mfa_required",
+         *         "challenge_id": "chg_abc123",
+         *         "mfa_token": "short_lived_jwt_token",
+         *         "challenge_type": "primary",
+         *         "available_methods": ["totp", "sms", "email"],
+         *         "primary_method": "totp",
+         *         "masked_phone": "+1***7890",
+         *         "masked_email": "j***@example.com",
+         *         "message": "MFA verification required"
+         *     }
+         *     ```
+         *     Client must then call `POST /v1/auth/mfa/challenges` to complete login.
+         *
+         *     ## Security Features:
+         *     - Account lockout after max failed attempts (default: 5)
+         *     - reCAPTCHA trigger after failed attempts (default: 2)
+         *     - Rate limiting (10 requests/minute)
+         *     - MFA support (TOTP, SMS, Email)
+         *     - Device trust (30-day remember device)
+         *
+         *     **Reference**: See `docs/AUTH_CONFIG_EXAMPLES.md` and `docs/MFA_IMPLEMENTATION_GUIDE.md` for complete details.
+         */
+        post: operations["createSession"];
+        /**
+         * Logout User
+         * @description Logout user and invalidate the refresh token.
+         *
+         *     **Authentication**: Bearer access token (or refresh_token cookie as fallback)
+         *     **Rate Limit**: 5 requests per minute
+         *
+         *     Clears the `refresh_token` HttpOnly cookie regardless of outcome.
+         */
+        delete: operations["deleteSession"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/auth/tokens/refresh": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Refresh User Token
+         * @description Refresh access token using the HttpOnly refresh_token cookie.
+         *
+         *     **Authentication**: None (uses HttpOnly cookie set at login)
+         *     **Rate Limit**: 60 requests per minute
+         *
+         *     The refresh_token is read from the `refresh_token` HttpOnly cookie.
+         *     Non-browser clients may send it as `Authorization: Bearer <refresh_token>` instead
+         *     (deprecated — migrate to cookie before the announced removal deadline).
+         *
+         *     ## Frontend retry contract:
+         *     - `401` → authentication failure — send user to login, do NOT retry
+         *     - `5xx` / network timeout → infrastructure failure — retry with exponential backoff
+         *       (3 attempts: 1 s, 2 s, 4 s)
+         */
+        post: operations["refreshToken"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/auth/social/sessions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Initiate Social Login
+         * @description Initiate social login by generating OAuth authorization URL.
+         *
+         *     **For**: All users (public endpoint)
+         *     **Purpose**: Start social login flow
+         *
+         *     **Example Request Body**:
+         *     ```json
+         *     {
+         *         "provider": "google",
+         *         "space_id": "spc_aBc123",
+         *         "state": "optional-custom-state"
+         *     }
+         *     ```
+         *
+         *     **Supported Providers**: google, facebook, linkedin, x, apple
+         *     **Required Fields**: provider, space_id
+         *     **Rate Limit**: 10 requests per minute
+         *     **Authentication**: None (public endpoint — org_id resolved from Bearer app_token)
+         *
+         *     **Flow**:
+         *     1. Client calls this endpoint with provider and space_id
+         *     2. Server returns authorization_url
+         *     3. Client redirects user to authorization_url
+         *     4. User authenticates with provider
+         *     5. Provider redirects back to callback endpoint
+         */
+        post: operations["initiateSocialLogin"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/auth/social/callback/{provider}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Handle Social Callback
+         * @description Handle OAuth callback from social provider.
+         *
+         *     **For**: All users (callback endpoint)
+         *     **Purpose**: Complete social login flow, issue JWT tokens
+         *
+         *     **Query Parameters**:
+         *     - code: Authorization code from provider (required)
+         *     - state: State parameter containing space_id (required)
+         *     - error: Optional error from provider
+         *
+         *     **Rate Limit**: 10 requests per minute
+         *     **Authentication**: None (callback endpoint — org_id resolved from state JWT)
+         *
+         *     **Success Response**:
+         *     - New User: Creates account, returns tokens
+         *     - Existing Social User: Returns tokens
+         *     - Linked User: Links social account, returns tokens
+         *
+         *     **Error Response**:
+         *     - Invalid code/state
+         *     - Provider error
+         *     - Email conflict
+         */
+        get: operations["handleSocialCallback"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/auth/mfa/challenges": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Verify Mfa Challenge
+         * @description **Verify MFA code** during login.
+         *
+         *     Called after receiving `mfa_required` response from login endpoint.
+         *
+         *     **Authentication**: MFA Token (short-lived, from login response)
+         *
+         *     **Request Body**:
+         *     ```json
+         *     {
+         *       "challenge_id": "chg_abc123",
+         *       "mfa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+         *       "code": "123456",
+         *       "method": "totp",
+         *       "remember_device": true
+         *     }
+         *     ```
+         *
+         *     **Response**: Full authentication (access_token, refresh_token, user)
+         *
+         *     **Methods**:
+         *     - `totp`: 6-digit code from authenticator app
+         *     - `sms`: 6-digit code sent via SMS
+         *     - `email`: 6-digit code sent via email
+         *     - `backup_code`: 8-character backup code (XXXX-YYYY)
+         */
+        post: operations["verifyMFAChallenge"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/auth/mfa/challenges/{challenge_id}/resend": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Resend Mfa Otp
+         * @description **Resend OTP** (SMS/Email only).
+         *
+         *     **Authentication**: MFA Token
+         *
+         *     **Request Body**:
+         *     ```json
+         *     {
+         *       "mfa_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+         *       "method": "sms"
+         *     }
+         *     ```
+         *
+         *     **Rate Limit**: 30-second cooldown between resends, max 3 resends per challenge
+         */
+        post: operations["resendMFAOTP"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        /**
+         * SocialLoginRequest
+         * @description Request model for initiating social login.
+         */
+        SocialLoginRequest: {
+            /**
+             * Provider
+             * @enum {string}
+             */
+            provider: "google" | "facebook" | "linkedin" | "x" | "apple";
+            /** Space Id */
+            space_id: string;
+            /**
+             * State
+             * @description Custom state to preserve
+             */
+            state?: string | null;
+        };
+        Extensions: {
+            /** @example GENERIC_ERROR */
+            message_code?: string;
+            /** @example [] */
+            invalid_params?: components["schemas"]["InvalidParam"][];
+            extra_data?: Record<string, never> | null;
+            /** @example Detailed debug information */
+            debug?: string | null;
+        };
+        /** ValidationError */
+        ValidationError: {
+            /** Location */
+            loc: (string | number)[];
+            /** Message */
+            msg: string;
+            /** Error Type */
+            type: string;
+        };
+        /** LoginRequest */
+        LoginRequest: {
+            /** Email */
+            email?: string | null;
+            /** Username */
+            username?: string | null;
+            /** Mobile Isd Code */
+            mobile_isd_code?: string | null;
+            /** Mobile No */
+            mobile_no?: string | null;
+            /** Password */
+            password?: string | null;
+            /** Otp */
+            otp?: string | null;
+            /**
+             * Otp Challenge Id
+             * @description OTP challenge ID (otp_xxx) from step 1
+             */
+            otp_challenge_id?: string | null;
+            /** Space Id */
+            space_id: string;
+            /** G Recaptcha Response */
+            g_recaptcha_response?: string | null;
+            /** Return Data */
+            return_data?: {
+                [key: string]: unknown;
+            } | null;
+            /** Tracking Id */
+            tracking_id?: string | null;
+            /**
+             * Device Id
+             * @description Device UUID for MFA device trust
+             */
+            device_id?: string | null;
+        };
+        /**
+         * @example {
+         *       "status": "success",
+         *       "message": "Operation successful",
+         *       "message_code": "api_suc_20001",
+         *       "data": {},
+         *       "metadata": {
+         *         "timestamp": "2026-03-26T10:00:00.000Z",
+         *         "requestId": "07e22004-cb60-4dfc-bc9c-b6f99664dca1",
+         *         "traceId": "a9f1204c-bb82-41de-b234-7c3a9e120000",
+         *         "version": "v1",
+         *         "executionTime": 42,
+         *         "language": "en-US"
+         *       }
+         *     }
+         */
+        StandardResponse: {
+            /** @example success */
+            status?: string;
+            data?: Record<string, never> | null;
+            /** @example Operation successful */
+            message?: string | null;
+            /** @example api_suc_20001 */
+            message_code?: string | null;
+            metadata?: Record<string, never> | null;
+            error?: components["schemas"]["ErrorResponse"];
+        };
+        InvalidParam: {
+            /** @example items[0].quantity */
+            field?: string;
+            /** @example Input should be greater than or equal to 1 */
+            error?: string;
+        };
+        ErrorResponse: {
+            /** @example about:blank */
+            type?: string;
+            /** @example GENERIC_ERROR */
+            code?: string;
+            /** @example Client Error */
+            title?: string;
+            /** @example 400 */
+            status?: number;
+            /** @example An error occurred */
+            detail?: string;
+            /** @example /v1/cart/items */
+            instance?: string;
+            extensions?: components["schemas"]["Extensions"];
+        };
+        StandardResponse_Dict_str__Any__: {
+            [key: string]: unknown;
+        };
+        /** HTTPValidationError */
+        HTTPValidationError: {
+            /** Detail */
+            detail?: components["schemas"]["ValidationError"][];
+        };
+        /**
+         * MFAResendRequest
+         * @description Request to resend OTP
+         */
+        MFAResendRequest: {
+            /**
+             * Challenge Id
+             * @description Challenge session ID
+             */
+            challenge_id: string;
+            /**
+             * Mfa Token
+             * @description Short-lived JWT from login response
+             */
+            mfa_token: string;
+            /**
+             * Method
+             * @description Method to resend (not TOTP)
+             * @enum {string}
+             */
+            method: "sms" | "email";
+        };
+        /** LogoutRequest */
+        LogoutRequest: {
+            /**
+             * Logout All
+             * @default false
+             */
+            logout_all: boolean | null;
+        };
+        /**
+         * MFAVerifyRequest
+         * @description Request to verify MFA code
+         */
+        MFAVerifyRequest: {
+            /**
+             * Challenge Id
+             * @description Challenge session ID
+             */
+            challenge_id: string;
+            /**
+             * Mfa Token
+             * @description Short-lived JWT from login response
+             */
+            mfa_token: string;
+            /**
+             * Code
+             * @description OTP/TOTP code or backup code
+             */
+            code: string;
+            /**
+             * Method
+             * @enum {string}
+             */
+            method: "totp" | "sms" | "email" | "backup_code";
+            /**
+             * Remember Device
+             * @description Trust this device for 30 days
+             * @default false
+             */
+            remember_device: boolean;
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export interface operations {
+    createSession: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["LoginRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StandardResponse"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    deleteSession: {
+        parameters: {
+            query?: never;
+            header?: {
+                authorization?: string | null;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["LogoutRequest"] | null;
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StandardResponse_Dict_str__Any__"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    refreshToken: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StandardResponse_Dict_str__Any__"];
+                };
+            };
+        };
+    };
+    initiateSocialLogin: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["SocialLoginRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StandardResponse"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    handleSocialCallback: {
+        parameters: {
+            query: {
+                /** @description Authorization code from OAuth provider */
+                code: string;
+                /** @description State parameter containing space_id and org_id */
+                state: string;
+                /** @description Error from OAuth provider */
+                error?: string | null;
+            };
+            header?: never;
+            path: {
+                provider: "google" | "facebook" | "linkedin" | "x" | "apple";
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StandardResponse"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    verifyMFAChallenge: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["MFAVerifyRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StandardResponse"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+    resendMFAOTP: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description MFA challenge ID from the login response */
+                challenge_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["MFAResendRequest"];
+            };
+        };
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["StandardResponse"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
+}
+//# sourceMappingURL=generated.d.ts.map