@nauth-toolkit/social-apple 0.1.14 → 0.1.17

package/dist/nestjs/apple-social-auth.module.d.ts

@@ -1,10 +1,47 @@
 import { OnModuleInit } from '@nestjs/common';
 import { AppleSocialAuthService } from '../src/apple-social-auth.service';
 import { SocialProviderRegistry } from '@nauth-toolkit/core/internal';
+/**
+ * Apple Social Authentication Module (NestJS Adapter)
+ *
+ * Provides Apple OAuth integration for nauth-toolkit in NestJS applications.
+ * Automatically registers itself with SocialAuthService when imported.
+ *
+ * **Usage:**
+ * ```typescript
+ * import { AuthModule } from '@nauth-toolkit/nestjs';
+ * import { AppleSocialAuthModule } from '@nauth-toolkit/social-apple/nestjs';
+ *
+ * @Module({
+ *   imports: [
+ *     AuthModule.forRoot(config),
+ *     AppleSocialAuthModule, // 👈 Auto-registers with SocialAuthService
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Use via registry (recommended for dynamic access)
+ * constructor(private socialAuthService: SocialAuthService) {}
+ *
+ * @Get('social/apple')
+ * async getAppleAuthUrl() {
+ *   const appleProvider = this.socialAuthService.getProvider('apple');
+ *   const authUrl = await appleProvider.getAuthUrl();
+ *   return { authUrl };
+ * }
+ *
+ * // Or inject directly
+ * constructor(private appleAuth: AppleSocialAuthService) {}
+ * ```
+ */
 export declare class AppleSocialAuthModule implements OnModuleInit {
     private readonly appleSocialAuthService;
     private readonly providerRegistry;
     constructor(appleSocialAuthService: AppleSocialAuthService, providerRegistry: SocialProviderRegistry);
+    /**
+     * Auto-register Apple provider with the SocialProviderRegistry
+     * when the module is initialized (only if enabled in config).
+     */
     onModuleInit(): void;
 }
 //# sourceMappingURL=apple-social-auth.module.d.ts.map

package/dist/nestjs/apple-social-auth.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apple-social-auth.module.d.ts","sourceRoot":"","sources":["../../nestjs/apple-social-auth.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAY1E,OAAO,EAIL,sBAAsB,EAGvB,MAAM,8BAA8B,CAAC;AAoCtC,qBAmEa,qBAAsB,YAAW,YAAY;IAEtD,OAAO,CAAC,QAAQ,CAAC,sBAAsB;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBADhB,sBAAsB,EAAE,sBAAsB,EAC9C,gBAAgB,EAAE,sBAAsB;IAO3D,YAAY,IAAI,IAAI;CAOrB"}
+{"version":3,"file":"apple-social-auth.module.d.ts","sourceRoot":"","sources":["../../nestjs/apple-social-auth.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAY1E,OAAO,EAIL,sBAAsB,EAGvB,MAAM,8BAA8B,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAmEa,qBAAsB,YAAW,YAAY;IAEtD,OAAO,CAAC,QAAQ,CAAC,sBAAsB;IACvC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBADhB,sBAAsB,EAAE,sBAAsB,EAC9C,gBAAgB,EAAE,sBAAsB;IAG3D;;;OAGG;IACH,YAAY,IAAI,IAAI;CAOrB"}

package/dist/nestjs/apple-social-auth.module.js

@@ -12,9 +12,44 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppleSocialAuthModule = void 0;
 const common_1 = require("@nestjs/common");
 const apple_social_auth_service_1 = require("../src/apple-social-auth.service");
+// Public API imports
 const core_1 = require("@nauth-toolkit/core");
+// Internal API imports (for provider implementations)
 const internal_1 = require("@nauth-toolkit/core/internal");
 const token_verifier_service_1 = require("../src/token-verifier.service");
+/**
+ * Apple Social Authentication Module (NestJS Adapter)
+ *
+ * Provides Apple OAuth integration for nauth-toolkit in NestJS applications.
+ * Automatically registers itself with SocialAuthService when imported.
+ *
+ * **Usage:**
+ * ```typescript
+ * import { AuthModule } from '@nauth-toolkit/nestjs';
+ * import { AppleSocialAuthModule } from '@nauth-toolkit/social-apple/nestjs';
+ *
+ * @Module({
+ *   imports: [
+ *     AuthModule.forRoot(config),
+ *     AppleSocialAuthModule, // 👈 Auto-registers with SocialAuthService
+ *   ],
+ * })
+ * export class AppModule {}
+ *
+ * // Use via registry (recommended for dynamic access)
+ * constructor(private socialAuthService: SocialAuthService) {}
+ *
+ * @Get('social/apple')
+ * async getAppleAuthUrl() {
+ *   const appleProvider = this.socialAuthService.getProvider('apple');
+ *   const authUrl = await appleProvider.getAuthUrl();
+ *   return { authUrl };
+ * }
+ *
+ * // Or inject directly
+ * constructor(private appleAuth: AppleSocialAuthService) {}
+ * ```
+ */
 let AppleSocialAuthModule = class AppleSocialAuthModule {
     appleSocialAuthService;
     providerRegistry;
@@ -22,8 +57,12 @@ let AppleSocialAuthModule = class AppleSocialAuthModule {
         this.appleSocialAuthService = appleSocialAuthService;
         this.providerRegistry = providerRegistry;
     }
+    /**
+     * Auto-register Apple provider with the SocialProviderRegistry
+     * when the module is initialized (only if enabled in config).
+     */
     onModuleInit() {
-        const config = this.appleSocialAuthService['config'];
+        const config = this.appleSocialAuthService['config']; // Access protected config
         const providerConfig = config.social?.apple;
         if (providerConfig?.enabled) {
             this.providerRegistry.registerProvider(this.appleSocialAuthService);
@@ -33,7 +72,9 @@ let AppleSocialAuthModule = class AppleSocialAuthModule {
 exports.AppleSocialAuthModule = AppleSocialAuthModule;
 exports.AppleSocialAuthModule = AppleSocialAuthModule = __decorate([
     (0, common_1.Module)({
+        // No imports needed - AuthModule is @Global() so its providers are available
         providers: [
+            // Token verifier for Apple ID tokens
             {
                 provide: 'APPLE_TOKEN_VERIFIER',
                 useFactory: (config) => {
@@ -41,9 +82,12 @@ exports.AppleSocialAuthModule = AppleSocialAuthModule = __decorate([
                 },
                 inject: ['NAUTH_CONFIG'],
             },
+            // Apple Social Auth Service (factory provider)
             {
                 provide: apple_social_auth_service_1.AppleSocialAuthService,
-                useFactory: (config, logger, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, stateStore, userRepository, phoneVerificationService, auditService, trustedDeviceService, tokenVerifier) => {
+                useFactory: (config, logger, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, stateStore, userRepository, phoneVerificationService, auditService, // Optional - only available when auditLogs.enabled is true
+                trustedDeviceService, // Optional - only available when rememberDevices is enabled
+                tokenVerifier) => {
                     return new apple_social_auth_service_1.AppleSocialAuthService(config, logger, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, stateStore, userRepository, phoneVerificationService, auditService, trustedDeviceService, tokenVerifier);
                 },
                 inject: [
@@ -58,8 +102,8 @@ exports.AppleSocialAuthModule = AppleSocialAuthModule = __decorate([
                     'SOCIAL_AUTH_STATE_STORE',
                     'UserRepository',
                     { token: core_1.PhoneVerificationService, optional: true },
-                    { token: internal_1.AuthAuditService, optional: true },
-                    { token: internal_1.TrustedDeviceService, optional: true },
+                    { token: internal_1.AuthAuditService, optional: true }, // Optional - only available when auditLogs.enabled is true
+                    { token: internal_1.TrustedDeviceService, optional: true }, // Optional - only available when rememberDevices is enabled
                     { token: 'APPLE_TOKEN_VERIFIER', optional: true },
                 ],
             },

package/dist/nestjs/apple-social-auth.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"apple-social-auth.module.js","sourceRoot":"","sources":["../../nestjs/apple-social-auth.module.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAsD;AACtD,gFAA0E;AAE1E,8CAQ6B;AAE7B,2DAOsC;AACtC,0EAAkG;AAsG3F,IAAM,qBAAqB,GAA3B,MAAM,qBAAqB;IAEb;IACA;IAFnB,YACmB,sBAA8C,EAC9C,gBAAwC;QADxC,2BAAsB,GAAtB,sBAAsB,CAAwB;QAC9C,qBAAgB,GAAhB,gBAAgB,CAAwB;IACxD,CAAC;IAMJ,YAAY;QACV,MAAM,MAAM,GAAG,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAgB,CAAC;QACpE,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAC5C,IAAI,cAAc,EAAE,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;CACF,CAAA;AAjBY,sDAAqB;gCAArB,qBAAqB;IAnEjC,IAAA,eAAM,EAAC;QAEN,SAAS,EAAE;YAET;gBACE,OAAO,EAAE,sBAAsB;gBAC/B,UAAU,EAAE,CAAC,MAAmB,EAAE,EAAE;oBAClC,OAAO,IAAI,6CAAyB,CAAC,MAAM,CAAC,CAAC;gBAC/C,CAAC;gBACD,MAAM,EAAE,CAAC,cAAc,CAAC;aACzB;YAED;gBACE,OAAO,EAAE,kDAAsB;gBAC/B,UAAU,EAAE,CACV,MAAmB,EACnB,MAAmB,EACnB,WAAwB,EACxB,iBAAoC,EACpC,UAAsB,EACtB,cAA8B,EAC9B,eAA2C,EAC3C,iBAAoC,EACpC,UAAgE,EAChE,cAAmB,EACnB,wBAAmD,EACnD,YAAuC,EACvC,oBAA2C,EAC3C,aAAqC,EACrC,EAAE;oBACF,OAAO,IAAI,kDAAsB,CAC/B,MAAM,EACN,MAAM,EACN,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,oBAAoB,EACpB,aAAa,CACd,CAAC;gBACJ,CAAC;gBACD,MAAM,EAAE;oBACN,cAAc;oBACd,cAAc;oBACd,kBAAW;oBACX,wBAAiB;oBACjB,qBAAU;oBACV,yBAAc;oBACd,qCAA0B;oBAC1B,wBAAiB;oBACjB,yBAAyB;oBACzB,gBAAgB;oBAChB,EAAE,KAAK,EAAE,+BAAwB,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACnD,EAAE,KAAK,EAAE,2BAAwB,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACnD,EAAE,KAAK,EAAE,+BAAoB,EAAE,QAAQ,EAAE,IAAI,EAAE;oBAC/C,EAAE,KAAK,EAAE,sBAAsB,EAAE,QAAQ,EAAE,IAAI,EAAE;iBAClD;aACF;SACF;QACD,OAAO,EAAE,CAAC,kDAAsB,CAAC;KAClC,CAAC;qCAG2C,kDAAsB;QAC5B,iCAAsB;GAHhD,qBAAqB,CAiBjC"}
+{"version":3,"file":"apple-social-auth.module.js","sourceRoot":"","sources":["../../nestjs/apple-social-auth.module.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAAsD;AACtD,gFAA0E;AAC1E,qBAAqB;AACrB,8CAQ6B;AAC7B,sDAAsD;AACtD,2DAOsC;AACtC,0EAAkG;AAElG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAoEI,IAAM,qBAAqB,GAA3B,MAAM,qBAAqB;IAEb;IACA;IAFnB,YACmB,sBAA8C,EAC9C,gBAAwC;QADxC,2BAAsB,GAAtB,sBAAsB,CAAwB;QAC9C,qBAAgB,GAAhB,gBAAgB,CAAwB;IACxD,CAAC;IAEJ;;;OAGG;IACH,YAAY;QACV,MAAM,MAAM,GAAG,IAAI,CAAC,sBAAsB,CAAC,QAAQ,CAAgB,CAAC,CAAC,0BAA0B;QAC/F,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;QAC5C,IAAI,cAAc,EAAE,OAAO,EAAE,CAAC;YAC5B,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;CACF,CAAA;AAjBY,sDAAqB;gCAArB,qBAAqB;IAnEjC,IAAA,eAAM,EAAC;QACN,6EAA6E;QAC7E,SAAS,EAAE;YACT,qCAAqC;YACrC;gBACE,OAAO,EAAE,sBAAsB;gBAC/B,UAAU,EAAE,CAAC,MAAmB,EAAE,EAAE;oBAClC,OAAO,IAAI,6CAAyB,CAAC,MAAM,CAAC,CAAC;gBAC/C,CAAC;gBACD,MAAM,EAAE,CAAC,cAAc,CAAC;aACzB;YACD,+CAA+C;YAC/C;gBACE,OAAO,EAAE,kDAAsB;gBAC/B,UAAU,EAAE,CACV,MAAmB,EACnB,MAAmB,EACnB,WAAwB,EACxB,iBAAoC,EACpC,UAAsB,EACtB,cAA8B,EAC9B,eAA2C,EAC3C,iBAAoC,EACpC,UAAgE,EAChE,cAAmB,EACnB,wBAAmD,EACnD,YAAuC,EAAE,2DAA2D;gBACpG,oBAA2C,EAAE,4DAA4D;gBACzG,aAAqC,EACrC,EAAE;oBACF,OAAO,IAAI,kDAAsB,CAC/B,MAAM,EACN,MAAM,EACN,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,oBAAoB,EACpB,aAAa,CACd,CAAC;gBACJ,CAAC;gBACD,MAAM,EAAE;oBACN,cAAc;oBACd,cAAc;oBACd,kBAAW;oBACX,wBAAiB;oBACjB,qBAAU;oBACV,yBAAc;oBACd,qCAA0B;oBAC1B,wBAAiB;oBACjB,yBAAyB;oBACzB,gBAAgB;oBAChB,EAAE,KAAK,EAAE,+BAAwB,EAAE,QAAQ,EAAE,IAAI,EAAE;oBACnD,EAAE,KAAK,EAAE,2BAAwB,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,2DAA2D;oBAChH,EAAE,KAAK,EAAE,+BAAoB,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,4DAA4D;oBAC7G,EAAE,KAAK,EAAE,sBAAsB,EAAE,QAAQ,EAAE,IAAI,EAAE;iBAClD;aACF;SACF;QACD,OAAO,EAAE,CAAC,kDAAsB,CAAC;KAClC,CAAC;qCAG2C,kDAAsB;QAC5B,iCAAsB;GAHhD,qBAAqB,CAiBjC"}

package/dist/nestjs/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @nauth-toolkit/social-apple/nestjs
+ *
+ * NestJS adapter for Apple Social Authentication
+ */
 export { AppleSocialAuthModule } from './apple-social-auth.module';
 export * from '../src/apple-social-auth.service';
 export * from '../src/apple-oauth.client';

package/dist/nestjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../nestjs/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGnE,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../nestjs/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGnE,cAAc,kCAAkC,CAAC;AACjD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,6BAA6B,CAAC"}

package/dist/nestjs/index.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * @nauth-toolkit/social-apple/nestjs
+ *
+ * NestJS adapter for Apple Social Authentication
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -17,6 +22,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppleSocialAuthModule = void 0;
 var apple_social_auth_module_1 = require("./apple-social-auth.module");
 Object.defineProperty(exports, "AppleSocialAuthModule", { enumerable: true, get: function () { return apple_social_auth_module_1.AppleSocialAuthModule; } });
+// Re-export core Apple social auth components
 __exportStar(require("../src/apple-social-auth.service"), exports);
 __exportStar(require("../src/apple-oauth.client"), exports);
 __exportStar(require("../src/token-verifier.service"), exports);

package/dist/nestjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../nestjs/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAMA,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA;AAG9B,mEAAiD;AACjD,4DAA0C;AAC1C,gEAA8C;AAC9C,0EAAwD;AACxD,8DAA4C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../nestjs/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;AAEH,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA;AAE9B,8CAA8C;AAC9C,mEAAiD;AACjD,4DAA0C;AAC1C,gEAA8C;AAC9C,0EAAwD;AACxD,8DAA4C"}

package/dist/src/apple-oauth.client.d.ts

@@ -1,15 +1,74 @@
 import { OAuthClient, OAuthConfig, OAuthUserProfile } from '@nauth-toolkit/core';
+/**
+ * Apple OAuth Client Implementation (Platform-Agnostic)
+ *
+ * Handles OAuth flow with Apple's Sign in with Apple API
+ * Uses Apple's userinfo endpoint for profile data
+ *
+ * This is a plain TypeScript class with no framework dependencies.
+ *
+ * @example
+ * ```typescript
+ * const client = new AppleOAuthClient({
+ *   clientId: 'apple_client_id',
+ *   clientSecret: 'apple_client_secret',
+ *   redirectUri: 'https://myapp.com/auth/apple/callback'
+ * });
+ *
+ * const profile = await client.getUserProfile(accessToken);
+ * ```
+ */
 export declare class AppleOAuthClient implements OAuthClient {
     private readonly config;
     private readonly tokenEndpoint;
     private readonly userInfoEndpoint;
     constructor(config: OAuthConfig);
+    /**
+     * Exchange authorization code for access token
+     *
+     * @param code - Authorization code from Apple OAuth callback
+     * @param redirectUri - Redirect URI used in OAuth flow
+     * @returns Access token and optional refresh token
+     * @throws {Error} When token exchange fails
+     *
+     * @example
+     * ```typescript
+     * const tokens = await client.exchangeCodeForToken(code, redirectUri);
+     * console.log(tokens.accessToken); // access_token_here
+     * ```
+     */
     exchangeCodeForToken(code: string, redirectUri: string): Promise<{
         accessToken: string;
         refreshToken?: string;
         expiresIn?: number;
     }>;
+    /**
+     * Get user profile from Apple using access token
+     *
+     * @param accessToken - OAuth access token
+     * @returns User profile data
+     * @throws {Error} When API call fails or token is invalid
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.getUserProfile(accessToken);
+     * console.log(profile.email); // user@icloud.com
+     * console.log(profile.firstName); // John
+     * ```
+     */
     getUserProfile(accessToken: string): Promise<OAuthUserProfile>;
+    /**
+     * Generate Apple OAuth authorization URL
+     *
+     * @param state - Optional state parameter for CSRF protection
+     * @returns Authorization URL for redirecting user to Apple
+     *
+     * @example
+     * ```typescript
+     * const authUrl = client.getAuthorizationUrl('random-state');
+     * // Redirect user to authUrl
+     * ```
+     */
     getAuthorizationUrl(state?: string): string;
 }
 //# sourceMappingURL=apple-oauth.client.d.ts.map

package/dist/src/apple-oauth.client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apple-oauth.client.d.ts","sourceRoot":"","sources":["../../src/apple-oauth.client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAiC,MAAM,qBAAqB,CAAC;AAqBhH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0C;IACxE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6C;gBAElE,MAAM,EAAE,WAAW;IAqBzB,oBAAoB,CACxB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QACT,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IAuDI,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAsDpE,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;CAe5C"}
+{"version":3,"file":"apple-oauth.client.d.ts","sourceRoot":"","sources":["../../src/apple-oauth.client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,gBAAgB,EAAiC,MAAM,qBAAqB,CAAC;AAEhH;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA0C;IACxE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA6C;gBAElE,MAAM,EAAE,WAAW;IAO/B;;;;;;;;;;;;;OAaG;IACG,oBAAoB,CACxB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;QACT,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IAyCF;;;;;;;;;;;;;OAaG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA0CpE;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM;CAe5C"}

package/dist/src/apple-oauth.client.js

@@ -2,6 +2,25 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppleOAuthClient = void 0;
 const core_1 = require("@nauth-toolkit/core");
+/**
+ * Apple OAuth Client Implementation (Platform-Agnostic)
+ *
+ * Handles OAuth flow with Apple's Sign in with Apple API
+ * Uses Apple's userinfo endpoint for profile data
+ *
+ * This is a plain TypeScript class with no framework dependencies.
+ *
+ * @example
+ * ```typescript
+ * const client = new AppleOAuthClient({
+ *   clientId: 'apple_client_id',
+ *   clientSecret: 'apple_client_secret',
+ *   redirectUri: 'https://myapp.com/auth/apple/callback'
+ * });
+ *
+ * const profile = await client.getUserProfile(accessToken);
+ * ```
+ */
 class AppleOAuthClient {
     config;
     tokenEndpoint = 'https://appleid.apple.com/auth/token';
@@ -12,6 +31,20 @@ class AppleOAuthClient {
             ...config,
         };
     }
+    /**
+     * Exchange authorization code for access token
+     *
+     * @param code - Authorization code from Apple OAuth callback
+     * @param redirectUri - Redirect URI used in OAuth flow
+     * @returns Access token and optional refresh token
+     * @throws {Error} When token exchange fails
+     *
+     * @example
+     * ```typescript
+     * const tokens = await client.exchangeCodeForToken(code, redirectUri);
+     * console.log(tokens.accessToken); // access_token_here
+     * ```
+     */
     async exchangeCodeForToken(code, redirectUri) {
         const params = new URLSearchParams({
             client_id: this.config.clientId,
@@ -46,6 +79,20 @@ class AppleOAuthClient {
             throw new core_1.NAuthException(core_1.AuthErrorCode.SOCIAL_TOKEN_INVALID, 'Apple token exchange failed: Unknown error');
         }
     }
+    /**
+     * Get user profile from Apple using access token
+     *
+     * @param accessToken - OAuth access token
+     * @returns User profile data
+     * @throws {Error} When API call fails or token is invalid
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.getUserProfile(accessToken);
+     * console.log(profile.email); // user@icloud.com
+     * console.log(profile.firstName); // John
+     * ```
+     */
     async getUserProfile(accessToken) {
         try {
             const response = await fetch(this.userInfoEndpoint, {
@@ -60,14 +107,16 @@ class AppleOAuthClient {
                 throw new core_1.NAuthException(core_1.AuthErrorCode.INTERNAL_ERROR, `Apple API call failed: ${response.status} ${response.statusText}`);
             }
             const data = (await response.json());
+            // Map Apple's response to our standardized format
+            // Apple provides name in a nested object format
             const firstName = data.name?.firstName || null;
             const lastName = data.name?.lastName || null;
             return {
-                id: data.sub,
+                id: data.sub, // Apple uses 'sub' as the user identifier
                 email: data.email || null,
                 firstName,
                 lastName,
-                picture: null,
+                picture: null, // Apple doesn't provide profile pictures
                 verified: data.email_verified || false,
                 raw: data,
             };
@@ -79,6 +128,18 @@ class AppleOAuthClient {
             throw new core_1.NAuthException(core_1.AuthErrorCode.INTERNAL_ERROR, 'Apple profile fetch failed: Unknown error');
         }
     }
+    /**
+     * Generate Apple OAuth authorization URL
+     *
+     * @param state - Optional state parameter for CSRF protection
+     * @returns Authorization URL for redirecting user to Apple
+     *
+     * @example
+     * ```typescript
+     * const authUrl = client.getAuthorizationUrl('random-state');
+     * // Redirect user to authUrl
+     * ```
+     */
     getAuthorizationUrl(state) {
         const params = new URLSearchParams({
             client_id: this.config.clientId,

package/dist/src/apple-oauth.client.js.map

@@ -1 +1 @@
-{"version":3,"file":"apple-oauth.client.js","sourceRoot":"","sources":["../../src/apple-oauth.client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apple-oauth.client.js","sourceRoot":"","sources":["../../src/apple-oauth.client.ts"],"names":[],"mappings":";;;AAAA,8CAAgH;AAEhH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,gBAAgB;IACV,MAAM,CAAc;IACpB,aAAa,GAAG,sCAAsC,CAAC;IACvD,gBAAgB,GAAG,yCAAyC,CAAC;IAE9E,YAAY,MAAmB;QAC7B,IAAI,CAAC,MAAM,GAAG;YACZ,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;YACzB,GAAG,MAAM;SACV,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,oBAAoB,CACxB,IAAY,EACZ,WAAmB;QAMnB,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;YACjC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;YAC/B,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;YACvC,IAAI;YACJ,UAAU,EAAE,oBAAoB;YAChC,YAAY,EAAE,WAAW;SAC1B,CAAC,CAAC;QAEH,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,aAAa,EAAE;gBAC/C,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,mCAAmC;iBACpD;gBACD,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE;aACxB,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,SAAS,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAQ,CAAC;gBACjD,MAAM,IAAI,qBAAc,CACtB,oBAAa,CAAC,oBAAoB,EAClC,0BAA0B,SAAS,CAAC,iBAAiB,IAAI,SAAS,CAAC,KAAK,EAAE,CAC3E,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAQ,CAAC;YAE5C,OAAO;gBACL,WAAW,EAAE,IAAI,CAAC,YAAY;gBAC9B,YAAY,EAAE,IAAI,CAAC,aAAa;gBAChC,SAAS,EAAE,IAAI,CAAC,UAAU;aAC3B,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,MAAM,IAAI,qBAAc,CAAC,oBAAa,CAAC,oBAAoB,EAAE,gCAAgC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAChH,CAAC;YACD,MAAM,IAAI,qBAAc,CAAC,oBAAa,CAAC,oBAAoB,EAAE,4CAA4C,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,cAAc,CAAC,WAAmB;QACtC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,gBAAgB,EAAE;gBAClD,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,WAAW,EAAE;iBACvC;aACF,CAAC,CAAC;YAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;oBAC5B,MAAM,IAAI,qBAAc,CAAC,oBAAa,CAAC,oBAAoB,EAAE,iCAAiC,CAAC,CAAC;gBAClG,CAAC;gBACD,MAAM,IAAI,qBAAc,CACtB,oBAAa,CAAC,cAAc,EAC5B,0BAA0B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CACnE,CAAC;YACJ,CAAC;YAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAQ,CAAC;YAE5C,kDAAkD;YAClD,gDAAgD;YAChD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,IAAI,IAAI,CAAC;YAC/C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,IAAI,IAAI,CAAC;YAE7C,OAAO;gBACL,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,0CAA0C;gBACxD,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI;gBACzB,SAAS;gBACT,QAAQ;gBACR,OAAO,EAAE,IAAI,EAAE,yCAAyC;gBACxD,QAAQ,EAAE,IAAI,CAAC,cAAc,IAAI,KAAK;gBACtC,GAAG,EAAE,IAAI;aACV,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,MAAM,IAAI,qBAAc,CAAC,oBAAa,CAAC,cAAc,EAAE,+BAA+B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACzG,CAAC;YACD,MAAM,IAAI,qBAAc,CAAC,oBAAa,CAAC,cAAc,EAAE,2CAA2C,CAAC,CAAC;QACtG,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,KAAc;QAChC,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;YACjC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;YAC/B,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;YACrC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,YAAY;YACpD,aAAa,EAAE,MAAM;YACrB,aAAa,EAAE,WAAW;SAC3B,CAAC,CAAC;QAEH,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,4CAA4C,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;IACzE,CAAC;CACF;AA7JD,4CA6JC"}

package/dist/src/apple-social-auth.service.d.ts

@@ -1,6 +1,37 @@
 import { AuthService, SocialAuthService, ClientInfoService, NAuthConfig, NAuthLogger, OAuthUserProfile, PhoneVerificationService, ISocialAuthProviderService, ITokenVerifierService, BaseUser } from '@nauth-toolkit/core';
-import { BaseSocialAuthProviderService, JwtService, SessionService, AuthChallengeHelperService, AuthAuditService, TrustedDeviceService } from '@nauth-toolkit/core/internal';
+import { BaseSocialAuthProviderService, JwtService, SessionService, AuthChallengeHelperService, AuthAuditService, // Internal version with recordEvent()
+TrustedDeviceService } from '@nauth-toolkit/core/internal';
 import { Repository } from 'typeorm';
+/**
+ * Apple Social Authentication Service (Platform-Agnostic)
+ *
+ * Handles Apple OAuth flow including:
+ * - OAuth web flow (redirect-based)
+ * - Native mobile token verification
+ * - Account linking
+ *
+ * This is a plain TypeScript class with no framework dependencies.
+ * Use `@nauth-toolkit/social-apple/nestjs` for NestJS integration.
+ *
+ * @example
+ * ```typescript
+ * // Direct instantiation (platform-agnostic)
+ * const appleAuth = new AppleSocialAuthService(
+ *   config,
+ *   logger,
+ *   authService,
+ *   socialAuthService,
+ *   jwtService,
+ *   sessionService,
+ *   challengeHelper,
+ *   clientInfoService,
+ *   auditService,
+ *   stateStore,
+ *   phoneVerificationService,
+ *   tokenVerifier
+ * );
+ * ```
+ */
 export declare class AppleSocialAuthService extends BaseSocialAuthProviderService implements ISocialAuthProviderService {
     readonly providerName = "apple";
     private readonly oauthClient;
@@ -9,8 +40,33 @@ export declare class AppleSocialAuthService extends BaseSocialAuthProviderServic
         timestamp: number;
         provider: string;
     }>, userRepository: Repository<BaseUser>, phoneVerificationService?: PhoneVerificationService, auditService?: AuthAuditService, trustedDeviceService?: TrustedDeviceService, tokenVerifier?: ITokenVerifierService);
+    /**
+     * Generate OAuth authorization URL for Apple
+     *
+     * @param state - Optional state parameter for CSRF protection
+     * @returns Authorization URL for redirecting user to Apple
+     */
     getAuthUrl(state?: string): Promise<string>;
+    /**
+     * Get OAuth user profile from callback
+     *
+     * Exchanges authorization code for access token and fetches user profile.
+     *
+     * @param code - Authorization code from Apple OAuth callback
+     * @param _state - State parameter (validated by base class)
+     * @returns User profile from Apple
+     * @protected
+     */
     protected getOAuthProfile(code: string, _state: string): Promise<OAuthUserProfile>;
+    /**
+     * Verify Apple ID token from native mobile apps
+     *
+     * @param idToken - Apple ID token from native Sign in with Apple
+     * @param _accessToken - Access token (not used for Apple)
+     * @param profileData - Optional profile data (name fields from first sign-in)
+     * @returns User profile from verified token
+     * @protected
+     */
     protected verifyNativeToken(idToken: string, _accessToken?: string, profileData?: unknown): Promise<OAuthUserProfile>;
 }
 //# sourceMappingURL=apple-social-auth.service.d.ts.map

package/dist/src/apple-social-auth.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apple-social-auth.service.d.ts","sourceRoot":"","sources":["../../src/apple-social-auth.service.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,gBAAgB,EAGhB,wBAAwB,EACxB,0BAA0B,EAC1B,qBAAqB,EACrB,QAAQ,EACT,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,6BAA6B,EAC7B,UAAU,EACV,cAAc,EACd,0BAA0B,EAC1B,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAmCrC,qBAAa,sBAAuB,SAAQ,6BAA8B,YAAW,0BAA0B;IAC7G,QAAQ,CAAC,YAAY,WAAW;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;gBAG3D,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,WAAW,EACxB,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,EAC9B,eAAe,EAAE,0BAA0B,EAC3C,iBAAiB,EAAE,iBAAiB,EAEpC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,EAChE,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EAEpC,wBAAwB,CAAC,EAAE,wBAAwB,EAEnD,YAAY,CAAC,EAAE,gBAAgB,EAE/B,oBAAoB,CAAC,EAAE,oBAAoB,EAE3C,aAAa,CAAC,EAAE,qBAAqB;IA2DjC,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;cAkBjC,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;cAyBxE,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CAAC,gBAAgB,CAAC;CAwC7B"}
+{"version":3,"file":"apple-social-auth.service.d.ts","sourceRoot":"","sources":["../../src/apple-social-auth.service.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,WAAW,EACX,gBAAgB,EAGhB,wBAAwB,EACxB,0BAA0B,EAC1B,qBAAqB,EACrB,QAAQ,EACT,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,6BAA6B,EAC7B,UAAU,EACV,cAAc,EACd,0BAA0B,EAC1B,gBAAgB,EAAE,sCAAsC;AACxD,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAKrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,sBAAuB,SAAQ,6BAA8B,YAAW,0BAA0B;IAC7G,QAAQ,CAAC,YAAY,WAAW;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0B;IACtD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA+B;gBAG3D,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,WAAW,EACxB,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,EAC9B,eAAe,EAAE,0BAA0B,EAC3C,iBAAiB,EAAE,iBAAiB,EAEpC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,EAChE,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EAEpC,wBAAwB,CAAC,EAAE,wBAAwB,EAEnD,YAAY,CAAC,EAAE,gBAAgB,EAE/B,oBAAoB,CAAC,EAAE,oBAAoB,EAE3C,aAAa,CAAC,EAAE,qBAAqB;IAqDvC;;;;;OAKG;IACG,UAAU,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQjD;;;;;;;;;OASG;cACa,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgBxF;;;;;;;;OAQG;cACa,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,MAAM,EACrB,WAAW,CAAC,EAAE,OAAO,GACpB,OAAO,CAAC,gBAAgB,CAAC;CAwC7B"}

package/dist/src/apple-social-auth.service.js

@@ -1,34 +1,81 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AppleSocialAuthService = void 0;
+// Public API imports
 const core_1 = require("@nauth-toolkit/core");
+// Internal API imports (for provider implementations)
 const internal_1 = require("@nauth-toolkit/core/internal");
 const apple_oauth_client_1 = require("./apple-oauth.client");
 const token_verifier_service_1 = require("./token-verifier.service");
+/**
+ * Apple Social Authentication Service (Platform-Agnostic)
+ *
+ * Handles Apple OAuth flow including:
+ * - OAuth web flow (redirect-based)
+ * - Native mobile token verification
+ * - Account linking
+ *
+ * This is a plain TypeScript class with no framework dependencies.
+ * Use `@nauth-toolkit/social-apple/nestjs` for NestJS integration.
+ *
+ * @example
+ * ```typescript
+ * // Direct instantiation (platform-agnostic)
+ * const appleAuth = new AppleSocialAuthService(
+ *   config,
+ *   logger,
+ *   authService,
+ *   socialAuthService,
+ *   jwtService,
+ *   sessionService,
+ *   challengeHelper,
+ *   clientInfoService,
+ *   auditService,
+ *   stateStore,
+ *   phoneVerificationService,
+ *   tokenVerifier
+ * );
+ * ```
+ */
 class AppleSocialAuthService extends internal_1.BaseSocialAuthProviderService {
     providerName = 'apple';
     oauthClient;
     tokenVerifier;
-    constructor(config, logger, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, stateStore, userRepository, phoneVerificationService, auditService, trustedDeviceService, tokenVerifier) {
+    constructor(config, logger, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, 
+    // State store shared across all providers
+    stateStore, userRepository, 
+    // Phone verification service (optional - only available when SMS provider is configured)
+    phoneVerificationService, 
+    // Audit service (optional - only available when auditLogs.enabled is true)
+    auditService, 
+    // Trusted device service (optional - only available when rememberDevices is enabled)
+    trustedDeviceService, 
+    // Apple-specific token verifier (optional, fallback to TOKEN_VERIFIER)
+    tokenVerifier) {
         super(config, logger, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, stateStore, userRepository, phoneVerificationService, auditService, trustedDeviceService);
+        // Initialize Apple OAuth client
         const providerConfig = this.getProviderConfig();
         if (!providerConfig || !providerConfig.enabled) {
             this.oauthClient = null;
             this.tokenVerifier = null;
-            return;
+            return; // Exit constructor early if disabled
         }
         const webClientId = Array.isArray(providerConfig.clientId) ? providerConfig.clientId[0] : providerConfig.clientId;
         if (!webClientId) {
+            // Schema validation should catch this, but handle gracefully
             this.oauthClient = null;
             this.tokenVerifier = null;
             return;
         }
+        // Note: Apple clientSecret is optional for native flow, but required for web OAuth
+        // It's a JWT that needs to be generated from Apple Developer credentials
         this.oauthClient = new apple_oauth_client_1.AppleOAuthClient({
             clientId: webClientId,
             clientSecret: providerConfig.clientSecret || '',
             redirectUri: providerConfig.callbackUrl || '',
             scopes: providerConfig.scopes || ['name', 'email'],
         });
+        // Use provided token verifier or create default one
         this.tokenVerifier =
             tokenVerifier ||
                 new token_verifier_service_1.TokenVerifierService(config) ||
@@ -36,6 +83,12 @@ class AppleSocialAuthService extends internal_1.BaseSocialAuthProviderService {
                 null;
         this.logger?.debug?.('AppleSocialAuthService initialized');
     }
+    /**
+     * Generate OAuth authorization URL for Apple
+     *
+     * @param state - Optional state parameter for CSRF protection
+     * @returns Authorization URL for redirecting user to Apple
+     */
     async getAuthUrl(state) {
         if (!this.oauthClient) {
             throw new core_1.NAuthException(core_1.AuthErrorCode.SOCIAL_CONFIG_MISSING, 'Apple OAuth is not enabled');
@@ -43,6 +96,16 @@ class AppleSocialAuthService extends internal_1.BaseSocialAuthProviderService {
         const finalState = state || this.generateState();
         return this.oauthClient.getAuthorizationUrl(finalState);
     }
+    /**
+     * Get OAuth user profile from callback
+     *
+     * Exchanges authorization code for access token and fetches user profile.
+     *
+     * @param code - Authorization code from Apple OAuth callback
+     * @param _state - State parameter (validated by base class)
+     * @returns User profile from Apple
+     * @protected
+     */
     async getOAuthProfile(code, _state) {
         if (!this.oauthClient) {
             throw new core_1.NAuthException(core_1.AuthErrorCode.SOCIAL_CONFIG_MISSING, 'Apple OAuth is not enabled');
@@ -51,9 +114,20 @@ class AppleSocialAuthService extends internal_1.BaseSocialAuthProviderService {
         if (!providerConfig || !providerConfig.callbackUrl) {
             throw new core_1.NAuthException(core_1.AuthErrorCode.SOCIAL_CONFIG_MISSING, 'Apple OAuth callback URL is not configured');
         }
+        // Exchange code for access token
         const tokens = await this.oauthClient.exchangeCodeForToken(code, providerConfig.callbackUrl);
+        // Get user profile from Apple
         return await this.oauthClient.getUserProfile(tokens.accessToken);
     }
+    /**
+     * Verify Apple ID token from native mobile apps
+     *
+     * @param idToken - Apple ID token from native Sign in with Apple
+     * @param _accessToken - Access token (not used for Apple)
+     * @param profileData - Optional profile data (name fields from first sign-in)
+     * @returns User profile from verified token
+     * @protected
+     */
     async verifyNativeToken(idToken, _accessToken, profileData) {
         if (!this.tokenVerifier) {
             throw new core_1.NAuthException(core_1.AuthErrorCode.SOCIAL_CONFIG_MISSING, 'Apple OAuth is not enabled');
@@ -66,18 +140,21 @@ class AppleSocialAuthService extends internal_1.BaseSocialAuthProviderService {
         if (!this.tokenVerifier.verifyAppleToken) {
             throw new core_1.NAuthException(core_1.AuthErrorCode.SOCIAL_CONFIG_MISSING, 'Apple token verifier is not available');
         }
+        // Verify ID token with Apple's JWKS public keys
         const verified = (await this.tokenVerifier.verifyAppleToken(idToken, clientId));
         this.logger?.debug?.(`Verified Apple token for: ${verified.email}`);
+        // CRITICAL: Require email from all social providers for signup
         if (!verified.email || !verified.email_verified) {
             throw new core_1.NAuthException(core_1.AuthErrorCode.SOCIAL_EMAIL_REQUIRED, 'Email is required and must be verified by Apple.');
         }
+        // Handle name from profileData (first-time sign-in only - Apple only sends name once)
         const profileDataTyped = profileData;
         return {
             id: verified.sub,
             email: verified.email,
             firstName: profileDataTyped?.firstName || null,
             lastName: profileDataTyped?.lastName || null,
-            picture: null,
+            picture: null, // Apple doesn't provide profile pictures
             verified: verified.email_verified,
             raw: {
                 sub: verified.sub,