@bactv/socialite 1.0.0

package/README.md

@@ -0,0 +1,133 @@
+# socialite
+
+A Node.js / TypeScript SDK for "Login with ..." (OAuth2) flows, built with
+Domain-Driven Design layering. Supports:
+
+- Google
+- Microsoft (Azure AD / personal accounts)
+- Facebook
+- GitHub
+- Twitter / X (OAuth 2.0 + PKCE)
+- LinkedIn (OpenID Connect)
+
+## Why DDD here?
+
+Each provider is a slightly different dialect of OAuth2 (different token
+endpoints, some need PKCE, some need GET instead of POST for the token
+exchange, etc). Structuring the SDK in layers keeps that variance contained:
+
+```
+src/
+  domain/           <- Pure business rules & contracts (ports). Zero HTTP, zero I/O.
+    entities/        SocialUser
+    value-objects/    AccessTokenResult, ProviderName
+    contracts/        OAuthProviderContract, HttpClientContract, StateStoreContract
+    errors/           SocialiteError and subclasses
+
+  application/        <- Orchestrates domain contracts for the outside world.
+    services/          SocialiteManager (the public facade / use-case layer)
+    dto/                ProviderConfig, SocialiteConfig
+
+  infrastructure/     <- Concrete adapters implementing the domain contracts.
+    http/               FetchHttpClient, MemoryStateStore
+    providers/          AbstractProvider + one class per provider + ProviderFactory
+
+  index.ts           <- Public entry point (Socialite.create(...))
+```
+
+The **application layer only depends on domain contracts**, never on a
+concrete provider class. That means adding a 7th provider (say, Apple) is a
+matter of adding one infrastructure class + one registry entry -- nothing
+in `SocialiteManager` changes (Open/Closed Principle).
+
+## Install
+
+```bash
+npm install socialite
+```
+
+## Usage
+
+```ts
+import { Socialite } from "@bactv/socialite";
+
+const socialite = Socialite.create({
+  google: {
+    clientId: process.env.GOOGLE_CLIENT_ID!,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    redirectUri: "https://myapp.com/auth/google/callback",
+  },
+  github: {
+    clientId: process.env.GITHUB_CLIENT_ID!,
+    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    redirectUri: "https://myapp.com/auth/github/callback",
+  },
+  // ...microsoft, facebook, twitter, linkedin follow the same shape
+});
+
+// 1) Send the user to the provider's consent screen.
+app.get("/auth/:provider", (req, res) => {
+  const { url, state } = socialite.driver(req.params.provider).redirect();
+  res.cookie("oauth_state", state, { httpOnly: true });
+  res.redirect(url);
+});
+
+// 2) Handle the redirect back from the provider.
+app.get("/auth/:provider/callback", async (req, res) => {
+  const { code, state } = req.query;
+  if (state !== req.cookies.oauth_state) {
+    return res.status(400).send("Invalid state");
+  }
+  const user = await socialite.driver(req.params.provider).callback(code, state);
+  // user.id, user.name, user.email, user.avatar, user.accessToken, ...
+  res.json(user.toJSON());
+});
+```
+
+See `examples/express-example.ts` for a full working route setup across all
+six providers.
+
+## Custom scopes / extra params
+
+```ts
+Socialite.create({
+  google: {
+    clientId: "...",
+    clientSecret: "...",
+    redirectUri: "...",
+    scopes: ["openid", "email", "profile", "https://www.googleapis.com/auth/calendar.readonly"],
+    authorizationParams: { access_type: "offline", prompt: "consent" },
+  },
+});
+```
+
+## Swapping infrastructure
+
+Both the HTTP client and the CSRF/PKCE state store are injected via
+constructor and implement plain interfaces (`HttpClientContract`,
+`StateStoreContract`), so you can supply your own -- e.g. a Redis-backed
+state store for a multi-instance deployment:
+
+```ts
+import { Socialite, StateStoreContract } from "socialite";
+
+class RedisStateStore implements StateStoreContract {
+  async put(state: string, codeVerifier: string | null) { /* ... */ }
+  async pull(state: string) { /* ... */ return null; }
+}
+
+const socialite = Socialite.create(config, undefined, new RedisStateStore());
+```
+
+## Error handling
+
+All failure modes raise a subclass of `SocialiteError`:
+`ProviderNotConfiguredError`, `UnsupportedProviderError`,
+`TokenExchangeError`, `UserFetchError`, `InvalidStateError`.
+
+## Build
+
+```bash
+npm install
+npm run build
+```

package/dist/application/dto/ProviderConfig.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Application DTO: ProviderConfig
+ *
+ * Plain data shape supplied by the consumer of the SDK (credentials
+ * obtained from each provider's developer console).
+ */
+export interface ProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    /** Override default scopes if needed. */
+    scopes?: string[];
+    /** Extra query params to merge into the authorization URL. */
+    authorizationParams?: Record<string, string>;
+}
+export interface SocialiteConfig {
+    google?: ProviderConfig;
+    microsoft?: ProviderConfig;
+    facebook?: ProviderConfig;
+    github?: ProviderConfig;
+    twitter?: ProviderConfig;
+    linkedin?: ProviderConfig;
+}

package/dist/application/dto/ProviderConfig.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=ProviderConfig.js.map

package/dist/application/dto/ProviderConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderConfig.js","sourceRoot":"","sources":["../../../src/application/dto/ProviderConfig.ts"],"names":[],"mappings":""}

package/dist/application/services/SocialiteManager.d.ts

@@ -0,0 +1,50 @@
+import { SocialiteConfig } from "../dto/ProviderConfig";
+import { OAuthProviderContract } from "../../domain/contracts/OAuthProviderContract";
+import { HttpClientContract } from "../../domain/contracts/HttpClientContract";
+import { StateStoreContract } from "../../domain/contracts/StateStoreContract";
+import { ProviderName } from "../../domain/value-objects/ProviderName";
+import { SocialUser } from "../../domain/entities/SocialUser";
+export interface RedirectResult {
+    /** URL to send the end-user's browser to. */
+    url: string;
+    /** Opaque CSRF token; persist it (cookie/session) and pass back into `.callback()`. */
+    state: string;
+}
+/**
+ * Application Service: SocialiteManager
+ *
+ * The public facade of the SDK. It orchestrates domain contracts and
+ * infrastructure adapters but contains no provider-specific HTTP logic
+ * itself -- that all lives behind OAuthProviderContract implementations.
+ *
+ * Usage:
+ *   const socialite = Socialite.create({ google: {...}, github: {...} });
+ *   const { url, state } = socialite.driver("google").redirect();
+ *   // ...later, in your OAuth callback route:
+ *   const user = await socialite.driver("google").callback(code, state);
+ */
+export declare class SocialiteManager {
+    private readonly config;
+    private readonly http;
+    private readonly stateStore;
+    private readonly cache;
+    constructor(config: SocialiteConfig, http?: HttpClientContract, stateStore?: StateStoreContract);
+    /** Resolve (and memoize) the provider identified by `name`. */
+    driver(name: string): ProviderFacade;
+    /** List provider names currently configured with credentials. */
+    configuredProviders(): ProviderName[];
+}
+/**
+ * Thin per-request facade returned by `driver()`, giving callers a small,
+ * readable API surface (`redirect()` / `callback()`) instead of exposing
+ * the full OAuthProviderContract.
+ */
+declare class ProviderFacade {
+    private readonly provider;
+    constructor(provider: OAuthProviderContract);
+    /** Step 1: build the URL to redirect the user to, plus a state token to persist. */
+    redirect(): RedirectResult;
+    /** Step 2: exchange the callback's `code` (+ the `state` you persisted) for a SocialUser. */
+    callback(code: string, state?: string): Promise<SocialUser>;
+}
+export {};

package/dist/application/services/SocialiteManager.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialiteManager = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const ProviderName_1 = require("../../domain/value-objects/ProviderName");
+const ProviderFactory_1 = require("../../infrastructure/providers/ProviderFactory");
+const FetchHttpClient_1 = require("../../infrastructure/http/FetchHttpClient");
+const MemoryStateStore_1 = require("../../infrastructure/http/MemoryStateStore");
+const SocialiteError_1 = require("../../domain/errors/SocialiteError");
+/**
+ * Application Service: SocialiteManager
+ *
+ * The public facade of the SDK. It orchestrates domain contracts and
+ * infrastructure adapters but contains no provider-specific HTTP logic
+ * itself -- that all lives behind OAuthProviderContract implementations.
+ *
+ * Usage:
+ *   const socialite = Socialite.create({ google: {...}, github: {...} });
+ *   const { url, state } = socialite.driver("google").redirect();
+ *   // ...later, in your OAuth callback route:
+ *   const user = await socialite.driver("google").callback(code, state);
+ */
+class SocialiteManager {
+    constructor(config, http = new FetchHttpClient_1.FetchHttpClient(), stateStore = new MemoryStateStore_1.MemoryStateStore()) {
+        this.config = config;
+        this.http = http;
+        this.stateStore = stateStore;
+        this.cache = new Map();
+    }
+    /** Resolve (and memoize) the provider identified by `name`. */
+    driver(name) {
+        if (!(0, ProviderName_1.isSupportedProvider)(name)) {
+            throw new SocialiteError_1.UnsupportedProviderError(name);
+        }
+        if (!this.cache.has(name)) {
+            const providerConfig = this.config[name];
+            if (!providerConfig) {
+                throw new SocialiteError_1.ProviderNotConfiguredError(name);
+            }
+            this.cache.set(name, ProviderFactory_1.ProviderFactory.make(name, providerConfig, this.http, this.stateStore));
+        }
+        return new ProviderFacade(this.cache.get(name));
+    }
+    /** List provider names currently configured with credentials. */
+    configuredProviders() {
+        return Object.keys(this.config).filter((key) => Boolean(this.config[key]));
+    }
+}
+exports.SocialiteManager = SocialiteManager;
+/**
+ * Thin per-request facade returned by `driver()`, giving callers a small,
+ * readable API surface (`redirect()` / `callback()`) instead of exposing
+ * the full OAuthProviderContract.
+ */
+class ProviderFacade {
+    constructor(provider) {
+        this.provider = provider;
+    }
+    /** Step 1: build the URL to redirect the user to, plus a state token to persist. */
+    redirect() {
+        const state = node_crypto_1.default.randomBytes(16).toString("hex");
+        const url = this.provider.getAuthorizationUrl(state);
+        return { url, state };
+    }
+    /** Step 2: exchange the callback's `code` (+ the `state` you persisted) for a SocialUser. */
+    callback(code, state) {
+        return this.provider.user(code, state);
+    }
+}
+//# sourceMappingURL=SocialiteManager.js.map

package/dist/application/services/SocialiteManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialiteManager.js","sourceRoot":"","sources":["../../../src/application/services/SocialiteManager.ts"],"names":[],"mappings":";;;;;;AAAA,8DAAiC;AAKjC,0EAA4F;AAE5F,oFAAiF;AACjF,+EAA4E;AAC5E,iFAA8E;AAC9E,uEAA0G;AAS1G;;;;;;;;;;;;GAYG;AACH,MAAa,gBAAgB;IAG3B,YACmB,MAAuB,EACvB,OAA2B,IAAI,iCAAe,EAAE,EAChD,aAAiC,IAAI,mCAAgB,EAAE;QAFvD,WAAM,GAAN,MAAM,CAAiB;QACvB,SAAI,GAAJ,IAAI,CAA4C;QAChD,eAAU,GAAV,UAAU,CAA6C;QALzD,UAAK,GAAG,IAAI,GAAG,EAAuC,CAAC;IAMrE,CAAC;IAEJ,+DAA+D;IAC/D,MAAM,CAAC,IAAY;QACjB,IAAI,CAAC,IAAA,kCAAmB,EAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,yCAAwB,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpB,MAAM,IAAI,2CAA0B,CAAC,IAAI,CAAC,CAAC;YAC7C,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,iCAAe,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAC/F,CAAC;QAED,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC,CAAC;IACnD,CAAC;IAED,iEAAiE;IACjE,mBAAmB;QACjB,OAAQ,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAoB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACjG,CAAC;CACF;AA9BD,4CA8BC;AAED;;;;GAIG;AACH,MAAM,cAAc;IAClB,YAA6B,QAA+B;QAA/B,aAAQ,GAAR,QAAQ,CAAuB;IAAG,CAAC;IAEhE,oFAAoF;IACpF,QAAQ;QACN,MAAM,KAAK,GAAG,qBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACrD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACrD,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;IACxB,CAAC;IAED,6FAA6F;IAC7F,QAAQ,CAAC,IAAY,EAAE,KAAc;QACnC,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;CACF"}

package/dist/domain/contracts/HttpClientContract.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Domain Contract (Port): HttpClientContract
+ *
+ * The domain/application layers should never call `fetch` directly.
+ * They depend on this abstraction so the actual HTTP implementation
+ * (native fetch, axios, a test double, ...) stays an infrastructure
+ * concern and is fully swappable/mockable.
+ */
+export interface HttpClientContract {
+    postForm<T = Record<string, unknown>>(url: string, form: Record<string, string>, headers?: Record<string, string>): Promise<T>;
+    getJson<T = Record<string, unknown>>(url: string, headers?: Record<string, string>): Promise<T>;
+}

package/dist/domain/contracts/HttpClientContract.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=HttpClientContract.js.map

package/dist/domain/contracts/HttpClientContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpClientContract.js","sourceRoot":"","sources":["../../../src/domain/contracts/HttpClientContract.ts"],"names":[],"mappings":""}

package/dist/domain/contracts/OAuthProviderContract.d.ts

@@ -0,0 +1,28 @@
+import { SocialUser } from "../entities/SocialUser";
+/**
+ * Domain Contract (Port): OAuthProviderContract
+ *
+ * Defines the behaviour every social login provider must expose.
+ * The application layer only ever depends on this interface, never on
+ * a concrete provider class -- that's what lets us swap/add providers
+ * (infrastructure) without touching application logic (Dependency
+ * Inversion Principle).
+ */
+export interface OAuthProviderContract {
+    /** Unique key such as "google", "github", etc. */
+    readonly name: string;
+    /**
+     * Build the URL the end-user should be redirected to in order to
+     * grant consent. `state` is used for CSRF protection and, for
+     * PKCE-based providers, a `codeVerifier` is generated/stored internally.
+     */
+    getAuthorizationUrl(state: string): string;
+    /** Exchange a temporary `code` (from the redirect callback) for tokens. */
+    getAccessToken(code: string, state?: string): Promise<import("../value-objects/AccessTokenResult").AccessTokenResult>;
+    /** Fetch the raw profile payload using a valid access token. */
+    getUserByToken(accessToken: string): Promise<Record<string, unknown>>;
+    /** Map a raw provider profile + token result into the domain SocialUser entity. */
+    mapToSocialUser(raw: Record<string, unknown>, token: import("../value-objects/AccessTokenResult").AccessTokenResult): SocialUser;
+    /** Convenience orchestration: code -> token -> profile -> SocialUser. */
+    user(code: string, state?: string): Promise<SocialUser>;
+}

package/dist/domain/contracts/OAuthProviderContract.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=OAuthProviderContract.js.map

package/dist/domain/contracts/OAuthProviderContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthProviderContract.js","sourceRoot":"","sources":["../../../src/domain/contracts/OAuthProviderContract.ts"],"names":[],"mappings":""}

package/dist/domain/contracts/StateStoreContract.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Domain Contract (Port): StateStoreContract
+ *
+ * OAuth "state" (CSRF token) and PKCE "code_verifier" values must be
+ * persisted between the redirect request and the callback request.
+ * In a real HTTP server this is usually backed by a session or cache;
+ * consumers of the SDK can provide their own implementation (e.g. Redis,
+ * express-session) instead of the in-memory default.
+ */
+export interface StateStoreContract {
+    put(state: string, codeVerifier: string | null): Promise<void> | void;
+    pull(state: string): Promise<string | null> | string | null;
+}

package/dist/domain/contracts/StateStoreContract.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=StateStoreContract.js.map

package/dist/domain/contracts/StateStoreContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StateStoreContract.js","sourceRoot":"","sources":["../../../src/domain/contracts/StateStoreContract.ts"],"names":[],"mappings":""}

package/dist/domain/entities/SocialUser.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Domain Entity: SocialUser
+ *
+ * A provider-agnostic representation of an authenticated user.
+ * Every concrete provider maps its own raw profile payload into this shape,
+ * so application code never has to deal with provider-specific fields.
+ */
+export interface SocialUserProps {
+    id: string;
+    nickname: string | null;
+    name: string | null;
+    email: string | null;
+    avatar: string | null;
+    provider: string;
+    accessToken: string;
+    refreshToken: string | null;
+    expiresIn: number | null;
+    /** The untouched payload returned by the provider, kept for edge cases. */
+    raw: Record<string, unknown>;
+}
+export declare class SocialUser {
+    readonly id: string;
+    readonly nickname: string | null;
+    readonly name: string | null;
+    readonly email: string | null;
+    readonly avatar: string | null;
+    readonly provider: string;
+    readonly accessToken: string;
+    readonly refreshToken: string | null;
+    readonly expiresIn: number | null;
+    readonly raw: Record<string, unknown>;
+    constructor(props: SocialUserProps);
+    toJSON(): Omit<SocialUserProps, "raw"> & {
+        raw: Record<string, unknown>;
+    };
+}

package/dist/domain/entities/SocialUser.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocialUser = void 0;
+class SocialUser {
+    constructor(props) {
+        this.id = props.id;
+        this.nickname = props.nickname;
+        this.name = props.name;
+        this.email = props.email;
+        this.avatar = props.avatar;
+        this.provider = props.provider;
+        this.accessToken = props.accessToken;
+        this.refreshToken = props.refreshToken;
+        this.expiresIn = props.expiresIn;
+        this.raw = props.raw;
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            nickname: this.nickname,
+            name: this.name,
+            email: this.email,
+            avatar: this.avatar,
+            provider: this.provider,
+            accessToken: this.accessToken,
+            refreshToken: this.refreshToken,
+            expiresIn: this.expiresIn,
+            raw: this.raw,
+        };
+    }
+}
+exports.SocialUser = SocialUser;
+//# sourceMappingURL=SocialUser.js.map

package/dist/domain/entities/SocialUser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialUser.js","sourceRoot":"","sources":["../../../src/domain/entities/SocialUser.ts"],"names":[],"mappings":";;;AAqBA,MAAa,UAAU;IAYrB,YAAY,KAAsB;QAChC,IAAI,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;QACnB,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACvB,CAAC;IAED,MAAM;QACJ,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,GAAG,EAAE,IAAI,CAAC,GAAG;SACd,CAAC;IACJ,CAAC;CACF;AAvCD,gCAuCC"}

package/dist/domain/errors/SocialiteError.d.ts

@@ -0,0 +1,18 @@
+export declare class SocialiteError extends Error {
+    constructor(message: string);
+}
+export declare class InvalidStateError extends SocialiteError {
+    constructor();
+}
+export declare class ProviderNotConfiguredError extends SocialiteError {
+    constructor(provider: string);
+}
+export declare class UnsupportedProviderError extends SocialiteError {
+    constructor(provider: string);
+}
+export declare class TokenExchangeError extends SocialiteError {
+    constructor(provider: string, details: string);
+}
+export declare class UserFetchError extends SocialiteError {
+    constructor(provider: string, details: string);
+}

package/dist/domain/errors/SocialiteError.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserFetchError = exports.TokenExchangeError = exports.UnsupportedProviderError = exports.ProviderNotConfiguredError = exports.InvalidStateError = exports.SocialiteError = void 0;
+class SocialiteError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SocialiteError";
+    }
+}
+exports.SocialiteError = SocialiteError;
+class InvalidStateError extends SocialiteError {
+    constructor() {
+        super("The OAuth 'state' parameter is invalid or has expired. Possible CSRF attempt.");
+        this.name = "InvalidStateError";
+    }
+}
+exports.InvalidStateError = InvalidStateError;
+class ProviderNotConfiguredError extends SocialiteError {
+    constructor(provider) {
+        super(`Provider "${provider}" is not configured. Pass its clientId/clientSecret/redirectUri to Socialite.create().`);
+        this.name = "ProviderNotConfiguredError";
+    }
+}
+exports.ProviderNotConfiguredError = ProviderNotConfiguredError;
+class UnsupportedProviderError extends SocialiteError {
+    constructor(provider) {
+        super(`Provider "${provider}" is not a supported Socialite driver.`);
+        this.name = "UnsupportedProviderError";
+    }
+}
+exports.UnsupportedProviderError = UnsupportedProviderError;
+class TokenExchangeError extends SocialiteError {
+    constructor(provider, details) {
+        super(`Failed to exchange authorization code for an access token with "${provider}": ${details}`);
+        this.name = "TokenExchangeError";
+    }
+}
+exports.TokenExchangeError = TokenExchangeError;
+class UserFetchError extends SocialiteError {
+    constructor(provider, details) {
+        super(`Failed to fetch user profile from "${provider}": ${details}`);
+        this.name = "UserFetchError";
+    }
+}
+exports.UserFetchError = UserFetchError;
+//# sourceMappingURL=SocialiteError.js.map

package/dist/domain/errors/SocialiteError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SocialiteError.js","sourceRoot":"","sources":["../../../src/domain/errors/SocialiteError.ts"],"names":[],"mappings":";;;AAAA,MAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC;AAED,MAAa,iBAAkB,SAAQ,cAAc;IACnD;QACE,KAAK,CAAC,+EAA+E,CAAC,CAAC;QACvF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AALD,8CAKC;AAED,MAAa,0BAA2B,SAAQ,cAAc;IAC5D,YAAY,QAAgB;QAC1B,KAAK,CAAC,aAAa,QAAQ,wFAAwF,CAAC,CAAC;QACrH,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AALD,gEAKC;AAED,MAAa,wBAAyB,SAAQ,cAAc;IAC1D,YAAY,QAAgB;QAC1B,KAAK,CAAC,aAAa,QAAQ,wCAAwC,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AALD,4DAKC;AAED,MAAa,kBAAmB,SAAQ,cAAc;IACpD,YAAY,QAAgB,EAAE,OAAe;QAC3C,KAAK,CAAC,mEAAmE,QAAQ,MAAM,OAAO,EAAE,CAAC,CAAC;QAClG,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AALD,gDAKC;AAED,MAAa,cAAe,SAAQ,cAAc;IAChD,YAAY,QAAgB,EAAE,OAAe;QAC3C,KAAK,CAAC,sCAAsC,QAAQ,MAAM,OAAO,EAAE,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC"}

package/dist/domain/value-objects/AccessTokenResult.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Value Object: AccessTokenResult
+ *
+ * Immutable representation of the token endpoint response. Value objects
+ * in DDD have no identity of their own -- two instances with the same
+ * data are considered equal/interchangeable.
+ */
+export declare class AccessTokenResult {
+    readonly accessToken: string;
+    readonly refreshToken: string | null;
+    readonly expiresIn: number | null;
+    readonly tokenType: string | null;
+    readonly raw: Record<string, unknown>;
+    constructor(accessToken: string, refreshToken: string | null, expiresIn: number | null, tokenType: string | null, raw: Record<string, unknown>);
+    static fromRaw(raw: Record<string, unknown>): AccessTokenResult;
+}

package/dist/domain/value-objects/AccessTokenResult.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessTokenResult = void 0;
+/**
+ * Value Object: AccessTokenResult
+ *
+ * Immutable representation of the token endpoint response. Value objects
+ * in DDD have no identity of their own -- two instances with the same
+ * data are considered equal/interchangeable.
+ */
+class AccessTokenResult {
+    constructor(accessToken, refreshToken, expiresIn, tokenType, raw) {
+        this.accessToken = accessToken;
+        this.refreshToken = refreshToken;
+        this.expiresIn = expiresIn;
+        this.tokenType = tokenType;
+        this.raw = raw;
+    }
+    static fromRaw(raw) {
+        const accessToken = raw.access_token ?? raw.accessToken;
+        if (!accessToken) {
+            throw new Error("Token response did not contain an access_token field");
+        }
+        return new AccessTokenResult(accessToken, raw.refresh_token ?? null, typeof raw.expires_in === "number" ? raw.expires_in : null, raw.token_type ?? null, raw);
+    }
+}
+exports.AccessTokenResult = AccessTokenResult;
+//# sourceMappingURL=AccessTokenResult.js.map

package/dist/domain/value-objects/AccessTokenResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccessTokenResult.js","sourceRoot":"","sources":["../../../src/domain/value-objects/AccessTokenResult.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,MAAa,iBAAiB;IAC5B,YACkB,WAAmB,EACnB,YAA2B,EAC3B,SAAwB,EACxB,SAAwB,EACxB,GAA4B;QAJ5B,gBAAW,GAAX,WAAW,CAAQ;QACnB,iBAAY,GAAZ,YAAY,CAAe;QAC3B,cAAS,GAAT,SAAS,CAAe;QACxB,cAAS,GAAT,SAAS,CAAe;QACxB,QAAG,GAAH,GAAG,CAAyB;IAC3C,CAAC;IAEJ,MAAM,CAAC,OAAO,CAAC,GAA4B;QACzC,MAAM,WAAW,GAAI,GAAG,CAAC,YAAuB,IAAK,GAAG,CAAC,WAAsB,CAAC;QAChF,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;QAC1E,CAAC;QACD,OAAO,IAAI,iBAAiB,CAC1B,WAAW,EACV,GAAG,CAAC,aAAwB,IAAI,IAAI,EACrC,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,EACzD,GAAG,CAAC,UAAqB,IAAI,IAAI,EAClC,GAAG,CACJ,CAAC;IACJ,CAAC;CACF;AAtBD,8CAsBC"}

package/dist/domain/value-objects/ProviderName.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Value Object: ProviderName
+ *
+ * Restricts provider identifiers to a known, closed set so that typos
+ * ("gogle") fail fast at the type level and at runtime.
+ */
+export declare const SUPPORTED_PROVIDERS: readonly ["google", "microsoft", "facebook", "github", "twitter", "linkedin"];
+export type ProviderName = (typeof SUPPORTED_PROVIDERS)[number];
+export declare function isSupportedProvider(value: string): value is ProviderName;

package/dist/domain/value-objects/ProviderName.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_PROVIDERS = void 0;
+exports.isSupportedProvider = isSupportedProvider;
+/**
+ * Value Object: ProviderName
+ *
+ * Restricts provider identifiers to a known, closed set so that typos
+ * ("gogle") fail fast at the type level and at runtime.
+ */
+exports.SUPPORTED_PROVIDERS = [
+    "google",
+    "microsoft",
+    "facebook",
+    "github",
+    "twitter",
+    "linkedin",
+];
+function isSupportedProvider(value) {
+    return exports.SUPPORTED_PROVIDERS.includes(value);
+}
+//# sourceMappingURL=ProviderName.js.map

package/dist/domain/value-objects/ProviderName.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProviderName.js","sourceRoot":"","sources":["../../../src/domain/value-objects/ProviderName.ts"],"names":[],"mappings":";;;AAiBA,kDAEC;AAnBD;;;;;GAKG;AACU,QAAA,mBAAmB,GAAG;IACjC,QAAQ;IACR,WAAW;IACX,UAAU;IACV,QAAQ;IACR,SAAS;IACT,UAAU;CACF,CAAC;AAIX,SAAgB,mBAAmB,CAAC,KAAa;IAC/C,OAAQ,2BAAyC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { SocialiteConfig } from "./application/dto/ProviderConfig";
+import { SocialiteManager } from "./application/services/SocialiteManager";
+import { HttpClientContract } from "./domain/contracts/HttpClientContract";
+import { StateStoreContract } from "./domain/contracts/StateStoreContract";
+/**
+ * Socialite -- public factory.
+ *
+ * const socialite = Socialite.create({
+ *   google: { clientId, clientSecret, redirectUri },
+ *   github: { clientId, clientSecret, redirectUri },
+ * });
+ */
+export declare class Socialite {
+    static create(config: SocialiteConfig, http?: HttpClientContract, stateStore?: StateStoreContract): SocialiteManager;
+}
+export { SocialUser } from "./domain/entities/SocialUser";
+export type { SocialUserProps } from "./domain/entities/SocialUser";
+export { AccessTokenResult } from "./domain/value-objects/AccessTokenResult";
+export { SUPPORTED_PROVIDERS, isSupportedProvider } from "./domain/value-objects/ProviderName";
+export type { ProviderName } from "./domain/value-objects/ProviderName";
+export type { OAuthProviderContract } from "./domain/contracts/OAuthProviderContract";
+export type { HttpClientContract } from "./domain/contracts/HttpClientContract";
+export type { StateStoreContract } from "./domain/contracts/StateStoreContract";
+export { SocialiteError, InvalidStateError, ProviderNotConfiguredError, UnsupportedProviderError, TokenExchangeError, UserFetchError, } from "./domain/errors/SocialiteError";
+export { SocialiteManager } from "./application/services/SocialiteManager";
+export type { RedirectResult } from "./application/services/SocialiteManager";
+export type { ProviderConfig, SocialiteConfig } from "./application/dto/ProviderConfig";
+export { FetchHttpClient } from "./infrastructure/http/FetchHttpClient";
+export { MemoryStateStore } from "./infrastructure/http/MemoryStateStore";
+export { ProviderFactory } from "./infrastructure/providers/ProviderFactory";
+export { GoogleProvider } from "./infrastructure/providers/GoogleProvider";
+export { MicrosoftProvider } from "./infrastructure/providers/MicrosoftProvider";
+export { FacebookProvider } from "./infrastructure/providers/FacebookProvider";
+export { GithubProvider } from "./infrastructure/providers/GithubProvider";
+export { TwitterProvider } from "./infrastructure/providers/TwitterProvider";
+export { LinkedinProvider } from "./infrastructure/providers/LinkedinProvider";