@drmhse/sso-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1759 @@
+/**
+ * HTTP response wrapper
+ */
+interface HttpResponse<T = any> {
+    data: T;
+    status: number;
+    headers: Headers;
+}
+/**
+ * HTTP client defaults
+ */
+interface HttpDefaults {
+    baseURL: string;
+    headers: {
+        common: Record<string, string>;
+    };
+    timeout: number;
+}
+/**
+ * Custom HTTP client using native fetch API.
+ * Provides an interface similar to Axios for easy migration.
+ */
+declare class HttpClient {
+    defaults: HttpDefaults;
+    constructor(baseURL: string);
+    /**
+     * Build query string from params object
+     */
+    private buildQueryString;
+    /**
+     * Build full URL from path and params
+     */
+    private buildUrl;
+    /**
+     * Make HTTP request with timeout support
+     */
+    private request;
+    /**
+     * GET request
+     */
+    get<T = any>(path: string, config?: {
+        params?: Record<string, any>;
+        headers?: Record<string, string>;
+    }): Promise<HttpResponse<T>>;
+    /**
+     * POST request
+     */
+    post<T = any>(path: string, data?: any, config?: {
+        headers?: Record<string, string>;
+    }): Promise<HttpResponse<T>>;
+    /**
+     * PATCH request
+     */
+    patch<T = any>(path: string, data?: any, config?: {
+        headers?: Record<string, string>;
+    }): Promise<HttpResponse<T>>;
+    /**
+     * DELETE request
+     */
+    delete<T = any>(path: string, config?: {
+        headers?: Record<string, string>;
+    }): Promise<HttpResponse<T>>;
+}
+
+/**
+ * Common types used across the SDK
+ */
+/**
+ * Represents a user in the system.
+ */
+interface User {
+    id: string;
+    email: string;
+    is_platform_owner: boolean;
+    created_at: string;
+}
+/**
+ * User profile response (includes context from JWT)
+ */
+interface UserProfile {
+    id: string;
+    email: string;
+    org?: string;
+    service?: string;
+}
+/**
+ * Paginated response wrapper
+ */
+interface PaginatedResponse<T> {
+    data: T[];
+    total: number;
+    page: number;
+    limit: number;
+    has_more: boolean;
+}
+/**
+ * Standard pagination parameters
+ */
+interface PaginationParams {
+    page?: number;
+    limit?: number;
+}
+/**
+ * OAuth provider types
+ */
+type OAuthProvider = 'github' | 'google' | 'microsoft';
+/**
+ * Organization status types
+ */
+type OrganizationStatus = 'pending' | 'active' | 'suspended' | 'rejected';
+/**
+ * Service types
+ */
+type ServiceType = 'web' | 'mobile' | 'desktop' | 'api';
+/**
+ * Organization member roles
+ */
+type MemberRole = 'owner' | 'admin' | 'member';
+/**
+ * Invitation status
+ */
+type InvitationStatus = 'pending' | 'accepted' | 'declined' | 'cancelled';
+
+/**
+ * JWT Claims payload structure
+ */
+interface JwtClaims {
+    /**
+     * Subject - the user ID
+     */
+    sub: string;
+    /**
+     * User's email address
+     */
+    email: string;
+    /**
+     * Whether the user is a platform owner
+     */
+    is_platform_owner: boolean;
+    /**
+     * Organization slug (present in Org and Service JWTs)
+     */
+    org?: string;
+    /**
+     * Service slug (present only in Service JWTs)
+     */
+    service?: string;
+    /**
+     * Subscription plan name
+     */
+    plan?: string;
+    /**
+     * List of enabled features
+     */
+    features?: string[];
+    /**
+     * Expiration timestamp (Unix epoch)
+     */
+    exp: number;
+    /**
+     * Issued at timestamp (Unix epoch)
+     */
+    iat: number;
+}
+
+/**
+ * Device code request payload
+ */
+interface DeviceCodeRequest {
+    client_id: string;
+    org: string;
+    service: string;
+}
+/**
+ * Device code response
+ */
+interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    expires_in: number;
+    interval: number;
+}
+/**
+ * Token request payload for device flow
+ */
+interface TokenRequest {
+    grant_type: 'urn:ietf:params:oauth:grant-type:device_code';
+    device_code: string;
+    client_id: string;
+}
+/**
+ * Token response
+ */
+interface TokenResponse {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+}
+/**
+ * Parameters for constructing login URL
+ */
+interface LoginUrlParams {
+    /**
+     * Organization slug
+     */
+    org: string;
+    /**
+     * Service slug
+     */
+    service: string;
+    /**
+     * Optional redirect URI (must be registered with the service)
+     */
+    redirect_uri?: string;
+}
+/**
+ * Parameters for constructing admin login URL
+ */
+interface AdminLoginUrlParams {
+    /**
+     * Optional organization slug to manage
+     */
+    org_slug?: string;
+}
+/**
+ * Provider token response
+ */
+interface ProviderToken {
+    access_token: string;
+    refresh_token?: string;
+    expires_at: string;
+    scopes: string[];
+    provider: OAuthProvider;
+}
+
+/**
+ * User subscription details
+ */
+interface Subscription {
+    service: string;
+    plan: string;
+    features: string[];
+    status: string;
+    current_period_end?: string;
+}
+/**
+ * Update user profile payload
+ */
+interface UpdateUserProfilePayload {
+    email?: string;
+}
+/**
+ * Social identity linked to the user
+ */
+interface Identity {
+    provider: string;
+}
+/**
+ * Response when starting a social account link
+ */
+interface StartLinkResponse {
+    authorization_url: string;
+}
+
+/**
+ * Organization entity
+ */
+interface Organization {
+    id: string;
+    slug: string;
+    name: string;
+    owner_user_id: string;
+    status: OrganizationStatus;
+    tier_id: string;
+    max_services?: number | null;
+    max_users?: number | null;
+    approved_by?: string | null;
+    approved_at?: string | null;
+    rejected_by?: string | null;
+    rejected_at?: string | null;
+    rejection_reason?: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Organization tier details
+ */
+interface OrganizationTier {
+    id: string;
+    name: string;
+    display_name?: string;
+    default_max_services: number;
+    default_max_users: number;
+    features: string;
+    price_cents?: number;
+    currency?: string;
+    created_at: string;
+}
+/**
+ * Organization membership
+ */
+interface Membership {
+    id: string;
+    org_id: string;
+    user_id: string;
+    role: MemberRole;
+    created_at: string;
+}
+/**
+ * Organization response with metadata
+ */
+interface OrganizationResponse {
+    organization: Organization;
+    membership_count: number;
+    service_count: number;
+    tier: OrganizationTier;
+}
+/**
+ * Organization member details
+ */
+interface OrganizationMember {
+    user_id: string;
+    email: string;
+    role: MemberRole;
+    joined_at: string;
+}
+/**
+ * Create organization payload (public endpoint)
+ */
+interface CreateOrganizationPayload {
+    slug: string;
+    name: string;
+    owner_email: string;
+}
+/**
+ * Create organization response
+ */
+interface CreateOrganizationResponse {
+    organization: Organization;
+    owner: {
+        id: string;
+        email: string;
+        is_platform_owner: boolean;
+        created_at: string;
+    };
+    membership: Membership;
+}
+/**
+ * Update organization payload
+ */
+interface UpdateOrganizationPayload {
+    name?: string;
+    max_services?: number;
+    max_users?: number;
+}
+/**
+ * Update member role payload
+ */
+interface UpdateMemberRolePayload {
+    role: MemberRole;
+}
+/**
+ * Transfer ownership payload
+ */
+interface TransferOwnershipPayload {
+    new_owner_user_id: string;
+}
+/**
+ * OAuth credentials payload
+ */
+interface SetOAuthCredentialsPayload {
+    client_id: string;
+    client_secret: string;
+}
+/**
+ * OAuth credentials response (secret never returned)
+ */
+interface OAuthCredentials {
+    id: string;
+    org_id: string;
+    provider: OAuthProvider;
+    client_id: string;
+    created_at: string;
+}
+/**
+ * List organizations query params
+ */
+interface ListOrganizationsParams extends PaginationParams {
+    status?: OrganizationStatus;
+}
+/**
+ * Member list response with pagination metadata
+ */
+interface MemberListResponse {
+    members: OrganizationMember[];
+    total: number;
+    limit: {
+        current: number;
+        max: number;
+        source: string;
+    };
+}
+
+/**
+ * Service entity
+ */
+interface Service {
+    id: string;
+    org_id: string;
+    slug: string;
+    name: string;
+    service_type: ServiceType;
+    client_id: string;
+    github_scopes: string[];
+    microsoft_scopes: string[];
+    google_scopes: string[];
+    redirect_uris: string[];
+    created_at: string;
+}
+/**
+ * Provider token grant configuration
+ */
+interface ProviderTokenGrant {
+    id: string;
+    service_id: string;
+    provider: string;
+    scopes: string[];
+    created_at: string;
+}
+/**
+ * Subscription plan
+ */
+interface Plan {
+    id: string;
+    service_id: string;
+    name: string;
+    description?: string;
+    price_monthly?: number;
+    features: string[];
+    is_default: boolean;
+    created_at: string;
+}
+/**
+ * Create service payload
+ */
+interface CreateServicePayload {
+    slug: string;
+    name: string;
+    service_type: ServiceType;
+    github_scopes?: string[];
+    microsoft_scopes?: string[];
+    google_scopes?: string[];
+    redirect_uris: string[];
+}
+/**
+ * Create service response
+ */
+interface CreateServiceResponse {
+    service: Service;
+    provider_grants: ProviderTokenGrant[];
+    default_plan: Plan;
+    usage: {
+        current_services: number;
+        max_services: number;
+        tier: string;
+    };
+}
+/**
+ * Update service payload
+ */
+interface UpdateServicePayload {
+    name?: string;
+    service_type?: ServiceType;
+    github_scopes?: string[];
+    microsoft_scopes?: string[];
+    google_scopes?: string[];
+    redirect_uris?: string[];
+}
+/**
+ * Service response with details
+ */
+interface ServiceResponse {
+    service: Service;
+    provider_grants: ProviderTokenGrant[];
+    plans: Plan[];
+}
+/**
+ * Create plan payload
+ */
+interface CreatePlanPayload {
+    name: string;
+    description?: string;
+    price_monthly?: number;
+    features: string[];
+    is_default?: boolean;
+}
+/**
+ * Service with aggregated details
+ */
+interface ServiceWithDetails extends Service {
+    plan_count: number;
+    subscription_count: number;
+}
+/**
+ * Service list response with usage metadata
+ */
+interface ServiceListResponse {
+    services: ServiceWithDetails[];
+    usage: {
+        current_services: number;
+        max_services: number;
+        tier: string;
+    };
+}
+
+/**
+ * Invitation entity
+ */
+interface Invitation {
+    id: string;
+    org_id: string;
+    inviter_user_id: string;
+    invitee_email: string;
+    role: MemberRole;
+    token: string;
+    status: InvitationStatus;
+    expires_at: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Create invitation payload
+ */
+interface CreateInvitationPayload {
+    invitee_email: string;
+    role: MemberRole;
+}
+/**
+ * Accept invitation payload
+ */
+interface AcceptInvitationPayload {
+    token: string;
+}
+/**
+ * Decline invitation payload
+ */
+interface DeclineInvitationPayload {
+    token: string;
+}
+/**
+ * Invitation with organization details
+ */
+interface InvitationWithOrg extends Invitation {
+    organization_name: string;
+    organization_slug: string;
+    inviter_email: string;
+}
+
+/**
+ * Platform organization response with additional metadata
+ */
+interface PlatformOrganizationResponse {
+    id: string;
+    slug: string;
+    name: string;
+    owner_user_id: string;
+    status: OrganizationStatus;
+    tier_id: string;
+    max_services?: number | null;
+    max_users?: number | null;
+    approved_by?: string | null;
+    approved_at?: string | null;
+    rejected_by?: string | null;
+    rejected_at?: string | null;
+    rejection_reason?: string | null;
+    created_at: string;
+    updated_at: string;
+    tier: OrganizationTier;
+    owner: User;
+}
+/**
+ * Platform organizations list response
+ */
+interface PlatformOrganizationsListResponse {
+    organizations: PlatformOrganizationResponse[];
+    total: number;
+}
+/**
+ * Approve organization payload
+ */
+interface ApproveOrganizationPayload {
+    tier_id: string;
+}
+/**
+ * Reject organization payload
+ */
+interface RejectOrganizationPayload {
+    reason: string;
+}
+/**
+ * Update organization tier payload
+ */
+interface UpdateOrganizationTierPayload {
+    tier_id: string;
+    max_services?: number;
+    max_users?: number;
+}
+/**
+ * Promote user to platform owner payload
+ */
+interface PromotePlatformOwnerPayload {
+    user_id: string;
+}
+/**
+ * Audit log entry
+ */
+interface AuditLogEntry {
+    id: string;
+    user_id: string;
+    user_email: string;
+    action: string;
+    resource_type: string;
+    resource_id: string;
+    details?: Record<string, any>;
+    ip_address?: string;
+    user_agent?: string;
+    created_at: string;
+}
+/**
+ * List platform organizations params
+ */
+interface ListPlatformOrganizationsParams extends PaginationParams {
+    status?: OrganizationStatus;
+    search?: string;
+    tier_id?: string;
+}
+/**
+ * Get audit log params
+ */
+interface GetAuditLogParams extends PaginationParams {
+    user_id?: string;
+    action?: string;
+    resource_type?: string;
+    start_date?: string;
+    end_date?: string;
+}
+
+/**
+ * End-user subscription details
+ */
+interface EndUserSubscription {
+    service_id: string;
+    service_slug: string;
+    service_name: string;
+    plan_id: string;
+    plan_name: string;
+    status: string;
+    current_period_end: string;
+    created_at: string;
+}
+/**
+ * End-user identity (OAuth provider link)
+ */
+interface EndUserIdentity {
+    provider: string;
+    provider_user_id: string;
+    created_at: string;
+}
+/**
+ * End-user with subscriptions and identities
+ */
+interface EndUser {
+    user: {
+        id: string;
+        email: string;
+        is_platform_owner: boolean;
+        created_at: string;
+    };
+    subscriptions: EndUserSubscription[];
+    identities: EndUserIdentity[];
+}
+/**
+ * End-user list response
+ */
+interface EndUserListResponse {
+    users: EndUser[];
+    total: number;
+    page: number;
+    limit: number;
+}
+/**
+ * End-user detail response with session info
+ */
+interface EndUserDetailResponse {
+    user: {
+        id: string;
+        email: string;
+        is_platform_owner: boolean;
+        created_at: string;
+    };
+    subscriptions: EndUserSubscription[];
+    identities: EndUserIdentity[];
+    session_count: number;
+}
+/**
+ * List end-users query params
+ */
+interface ListEndUsersParams extends PaginationParams {
+}
+/**
+ * Revoke sessions response
+ */
+interface RevokeSessionsResponse {
+    message: string;
+    revoked_count: number;
+}
+
+interface LoginTrendPoint {
+    date: string;
+    count: number;
+}
+interface LoginsByService {
+    service_id: string;
+    service_name: string;
+    count: number;
+}
+interface LoginsByProvider {
+    provider: 'github' | 'google' | 'microsoft';
+    count: number;
+}
+interface RecentLogin {
+    id: string;
+    user_id: string;
+    service_id: string;
+    provider: string;
+    created_at: string;
+}
+interface AnalyticsQuery {
+    start_date?: string;
+    end_date?: string;
+    limit?: number;
+}
+
+/**
+ * Analytics and login tracking methods
+ */
+declare class AnalyticsModule {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Get login trends over time.
+     * Returns daily login counts grouped by date.
+     *
+     * @param orgSlug Organization slug
+     * @param params Optional query parameters (date range)
+     * @returns Array of login trend data points
+     *
+     * @example
+     * ```typescript
+     * const trends = await sso.analytics.getLoginTrends('acme-corp', {
+     *   start_date: '2025-01-01',
+     *   end_date: '2025-01-31'
+     * });
+     * trends.forEach(point => console.log(point.date, point.count));
+     * ```
+     */
+    getLoginTrends(orgSlug: string, params?: AnalyticsQuery): Promise<LoginTrendPoint[]>;
+    /**
+     * Get login counts grouped by service.
+     * Shows which services have the most authentication activity.
+     *
+     * @param orgSlug Organization slug
+     * @param params Optional query parameters (date range)
+     * @returns Array of login counts per service
+     *
+     * @example
+     * ```typescript
+     * const byService = await sso.analytics.getLoginsByService('acme-corp', {
+     *   start_date: '2025-01-01',
+     *   end_date: '2025-01-31'
+     * });
+     * byService.forEach(s => console.log(s.service_name, s.count));
+     * ```
+     */
+    getLoginsByService(orgSlug: string, params?: AnalyticsQuery): Promise<LoginsByService[]>;
+    /**
+     * Get login counts grouped by OAuth provider.
+     * Shows which authentication providers are being used (GitHub, Google, Microsoft).
+     *
+     * @param orgSlug Organization slug
+     * @param params Optional query parameters (date range)
+     * @returns Array of login counts per provider
+     *
+     * @example
+     * ```typescript
+     * const byProvider = await sso.analytics.getLoginsByProvider('acme-corp', {
+     *   start_date: '2025-01-01',
+     *   end_date: '2025-01-31'
+     * });
+     * byProvider.forEach(p => console.log(p.provider, p.count));
+     * ```
+     */
+    getLoginsByProvider(orgSlug: string, params?: AnalyticsQuery): Promise<LoginsByProvider[]>;
+    /**
+     * Get the most recent login events.
+     *
+     * @param orgSlug Organization slug
+     * @param params Optional query parameters (limit)
+     * @returns Array of recent login events
+     *
+     * @example
+     * ```typescript
+     * const recentLogins = await sso.analytics.getRecentLogins('acme-corp', {
+     *   limit: 10
+     * });
+     * recentLogins.forEach(login => {
+     *   console.log(login.user_id, login.provider, login.created_at);
+     * });
+     * ```
+     */
+    getRecentLogins(orgSlug: string, params?: AnalyticsQuery): Promise<RecentLogin[]>;
+}
+
+/**
+ * Authentication and OAuth flow methods
+ */
+declare class AuthModule {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Constructs the OAuth login URL for end-users.
+     * This does not perform the redirect; the consuming application
+     * should redirect the user's browser to this URL.
+     *
+     * @param provider The OAuth provider to use
+     * @param params Login parameters (org, service, redirect_uri)
+     * @returns The full URL to redirect the user to
+     *
+     * @example
+     * ```typescript
+     * const url = sso.auth.getLoginUrl('github', {
+     *   org: 'acme-corp',
+     *   service: 'main-app',
+     *   redirect_uri: 'https://app.acme.com/callback'
+     * });
+     * window.location.href = url;
+     * ```
+     */
+    getLoginUrl(provider: OAuthProvider, params: LoginUrlParams): string;
+    /**
+     * Constructs the OAuth login URL for platform/organization admins.
+     * This uses the platform's dedicated OAuth credentials.
+     *
+     * @param provider The OAuth provider to use
+     * @param params Optional admin login parameters
+     * @returns The full URL to redirect the admin to
+     *
+     * @example
+     * ```typescript
+     * const url = sso.auth.getAdminLoginUrl('github', {
+     *   org_slug: 'acme-corp'
+     * });
+     * window.location.href = url;
+     * ```
+     */
+    getAdminLoginUrl(provider: OAuthProvider, params?: AdminLoginUrlParams): string;
+    /**
+     * Device Flow: Request a device code for CLI/device authentication.
+     *
+     * @param payload Device code request payload
+     * @returns Device code response with user code and verification URI
+     *
+     * @example
+     * ```typescript
+     * const response = await sso.auth.deviceCode.request({
+     *   client_id: 'service-client-id',
+     *   org: 'acme-corp',
+     *   service: 'acme-cli'
+     * });
+     * console.log(`Visit ${response.verification_uri} and enter code: ${response.user_code}`);
+     * ```
+     */
+    deviceCode: {
+        /**
+         * Request a device code
+         */
+        request: (payload: DeviceCodeRequest) => Promise<DeviceCodeResponse>;
+        /**
+         * Exchange a device code for a JWT token.
+         * This should be polled by the device/CLI after displaying the user code.
+         *
+         * @param payload Token request payload
+         * @returns Token response with JWT
+         *
+         * @example
+         * ```typescript
+         * // Poll every 5 seconds
+         * const interval = setInterval(async () => {
+         *   try {
+         *     const token = await sso.auth.deviceCode.exchangeToken({
+         *       grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+         *       device_code: deviceCode,
+         *       client_id: 'service-client-id'
+         *     });
+         *     clearInterval(interval);
+         *     sso.setAuthToken(token.access_token);
+         *   } catch (error) {
+         *     if (error.errorCode !== 'authorization_pending') {
+         *       clearInterval(interval);
+         *       throw error;
+         *     }
+         *   }
+         * }, 5000);
+         * ```
+         */
+        exchangeToken: (payload: TokenRequest) => Promise<TokenResponse>;
+    };
+    /**
+     * Logout the current user by revoking their JWT.
+     * After calling this, you should clear the token from storage
+     * and call `sso.setAuthToken(null)`.
+     *
+     * @example
+     * ```typescript
+     * await sso.auth.logout();
+     * sso.setAuthToken(null);
+     * localStorage.removeItem('jwt');
+     * ```
+     */
+    logout(): Promise<void>;
+    /**
+     * Get a fresh provider access token for the authenticated user.
+     * This will automatically refresh the token if it's expired.
+     *
+     * @param provider The OAuth provider
+     * @returns Fresh provider token
+     *
+     * @example
+     * ```typescript
+     * const token = await sso.auth.getProviderToken('github');
+     * // Use token.access_token to make GitHub API calls
+     * ```
+     */
+    getProviderToken(provider: OAuthProvider): Promise<ProviderToken>;
+}
+
+/**
+ * Identity (social account linking) methods
+ */
+declare class IdentitiesModule {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List all social accounts linked to the authenticated user.
+     *
+     * @returns Array of linked identities
+     *
+     * @example
+     * ```typescript
+     * const identities = await sso.user.identities.list();
+     * console.log(identities); // [{ provider: 'github' }, { provider: 'google' }]
+     * ```
+     */
+    list(): Promise<Identity[]>;
+    /**
+     * Start linking a new social account to the authenticated user.
+     * Returns an authorization URL that the user should be redirected to.
+     *
+     * @param provider The OAuth provider to link (e.g., 'github', 'google', 'microsoft')
+     * @returns Object containing the authorization URL
+     *
+     * @example
+     * ```typescript
+     * const { authorization_url } = await sso.user.identities.startLink('github');
+     * window.location.href = authorization_url; // Redirect user to complete OAuth
+     * ```
+     */
+    startLink(provider: string): Promise<StartLinkResponse>;
+    /**
+     * Unlink a social account from the authenticated user.
+     * Note: Cannot unlink the last remaining identity to prevent account lockout.
+     *
+     * @param provider The OAuth provider to unlink (e.g., 'github', 'google', 'microsoft')
+     *
+     * @example
+     * ```typescript
+     * await sso.user.identities.unlink('google');
+     * ```
+     */
+    unlink(provider: string): Promise<void>;
+}
+/**
+ * User profile and subscription methods
+ */
+declare class UserModule {
+    private http;
+    readonly identities: IdentitiesModule;
+    constructor(http: HttpClient);
+    /**
+     * Get the profile of the currently authenticated user.
+     * The response includes context from the JWT (org, service).
+     *
+     * @returns User profile
+     *
+     * @example
+     * ```typescript
+     * const profile = await sso.user.getProfile();
+     * console.log(profile.email, profile.org, profile.service);
+     * ```
+     */
+    getProfile(): Promise<UserProfile>;
+    /**
+     * Update the authenticated user's profile.
+     *
+     * @param payload Update payload
+     * @returns Updated user profile
+     *
+     * @example
+     * ```typescript
+     * const updated = await sso.user.updateProfile({
+     *   email: 'newemail@example.com'
+     * });
+     * ```
+     */
+    updateProfile(payload: UpdateUserProfilePayload): Promise<UserProfile>;
+    /**
+     * Get the current user's subscription details for the service in their JWT.
+     *
+     * @returns Subscription details
+     *
+     * @example
+     * ```typescript
+     * const subscription = await sso.user.getSubscription();
+     * console.log(subscription.plan, subscription.features);
+     * ```
+     */
+    getSubscription(): Promise<Subscription>;
+}
+
+/**
+ * Organization management methods
+ */
+declare class OrganizationsModule {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new organization (public endpoint).
+     * The organization will be created with 'pending' status and requires
+     * platform owner approval before becoming active.
+     *
+     * @param payload Organization creation payload
+     * @returns Created organization with owner and membership details
+     *
+     * @example
+     * ```typescript
+     * const result = await sso.organizations.createPublic({
+     *   slug: 'acme-corp',
+     *   name: 'Acme Corporation',
+     *   owner_email: 'founder@acme.com'
+     * });
+     * ```
+     */
+    createPublic(payload: CreateOrganizationPayload): Promise<CreateOrganizationResponse>;
+    /**
+     * List all organizations the authenticated user is a member of.
+     *
+     * @param params Optional query parameters for filtering and pagination
+     * @returns Array of organization responses
+     *
+     * @example
+     * ```typescript
+     * const orgs = await sso.organizations.list({
+     *   status: 'active',
+     *   page: 1,
+     *   limit: 20
+     * });
+     * ```
+     */
+    list(params?: ListOrganizationsParams): Promise<OrganizationResponse[]>;
+    /**
+     * Get detailed information for a specific organization.
+     *
+     * @param orgSlug Organization slug
+     * @returns Organization details
+     *
+     * @example
+     * ```typescript
+     * const org = await sso.organizations.get('acme-corp');
+     * console.log(org.organization.name, org.membership_count);
+     * ```
+     */
+    get(orgSlug: string): Promise<OrganizationResponse>;
+    /**
+     * Update organization details.
+     * Requires 'owner' or 'admin' role.
+     *
+     * @param orgSlug Organization slug
+     * @param payload Update payload
+     * @returns Updated organization details
+     *
+     * @example
+     * ```typescript
+     * const updated = await sso.organizations.update('acme-corp', {
+     *   name: 'Acme Corporation Inc.',
+     *   max_services: 20
+     * });
+     * ```
+     */
+    update(orgSlug: string, payload: UpdateOrganizationPayload): Promise<OrganizationResponse>;
+    /**
+     * Member management methods
+     */
+    members: {
+        /**
+         * List all members of an organization.
+         *
+         * @param orgSlug Organization slug
+         * @returns Member list response with pagination metadata
+         *
+         * @example
+         * ```typescript
+         * const result = await sso.organizations.members.list('acme-corp');
+         * console.log(`Total members: ${result.total}`);
+         * result.members.forEach(m => console.log(m.email, m.role));
+         * ```
+         */
+        list: (orgSlug: string) => Promise<MemberListResponse>;
+        /**
+         * Update a member's role.
+         * Requires 'owner' role.
+         *
+         * @param orgSlug Organization slug
+         * @param userId User ID to update
+         * @param payload Role update payload
+         * @returns Updated member details
+         *
+         * @example
+         * ```typescript
+         * await sso.organizations.members.updateRole('acme-corp', 'user-id', {
+         *   role: 'admin'
+         * });
+         * ```
+         */
+        updateRole: (orgSlug: string, userId: string, payload: UpdateMemberRolePayload) => Promise<OrganizationMember>;
+        /**
+         * Remove a member from the organization.
+         * Requires 'owner' or 'admin' role.
+         *
+         * @param orgSlug Organization slug
+         * @param userId User ID to remove
+         *
+         * @example
+         * ```typescript
+         * await sso.organizations.members.remove('acme-corp', 'user-id');
+         * ```
+         */
+        remove: (orgSlug: string, userId: string) => Promise<void>;
+        /**
+         * Transfer organization ownership to another member.
+         * Requires 'owner' role.
+         *
+         * @param orgSlug Organization slug
+         * @param payload Transfer payload with new owner ID
+         *
+         * @example
+         * ```typescript
+         * await sso.organizations.members.transferOwnership('acme-corp', {
+         *   new_owner_user_id: 'new-owner-id'
+         * });
+         * ```
+         */
+        transferOwnership: (orgSlug: string, payload: TransferOwnershipPayload) => Promise<void>;
+    };
+    /**
+     * End-user management methods
+     * Manage organization's customers (end-users with subscriptions)
+     */
+    endUsers: {
+        /**
+         * List all end-users for an organization.
+         * End-users are customers who have subscriptions to the organization's services.
+         *
+         * @param orgSlug Organization slug
+         * @param params Optional query parameters for pagination
+         * @returns Paginated list of end-users with their subscriptions
+         *
+         * @example
+         * ```typescript
+         * const endUsers = await sso.organizations.endUsers.list('acme-corp', {
+         *   page: 1,
+         *   limit: 20
+         * });
+         * console.log(`Total end-users: ${endUsers.total}`);
+         * ```
+         */
+        list: (orgSlug: string, params?: ListEndUsersParams) => Promise<EndUserListResponse>;
+        /**
+         * Get detailed information about a specific end-user.
+         *
+         * @param orgSlug Organization slug
+         * @param userId User ID
+         * @returns End-user details with subscriptions, identities, and session count
+         *
+         * @example
+         * ```typescript
+         * const endUser = await sso.organizations.endUsers.get('acme-corp', 'user-id');
+         * console.log(`Active sessions: ${endUser.session_count}`);
+         * ```
+         */
+        get: (orgSlug: string, userId: string) => Promise<EndUserDetailResponse>;
+        /**
+         * Revoke all active sessions for an end-user.
+         * Requires admin or owner role.
+         * This will force the user to re-authenticate.
+         *
+         * @param orgSlug Organization slug
+         * @param userId User ID
+         * @returns Response with number of revoked sessions
+         *
+         * @example
+         * ```typescript
+         * const result = await sso.organizations.endUsers.revokeSessions('acme-corp', 'user-id');
+         * console.log(`Revoked ${result.revoked_count} sessions`);
+         * ```
+         */
+        revokeSessions: (orgSlug: string, userId: string) => Promise<RevokeSessionsResponse>;
+    };
+    /**
+     * BYOO (Bring Your Own OAuth) credential management
+     */
+    oauthCredentials: {
+        /**
+         * Set or update custom OAuth credentials for a provider.
+         * This enables white-labeled authentication using the organization's
+         * own OAuth application.
+         * Requires 'owner' or 'admin' role.
+         *
+         * @param orgSlug Organization slug
+         * @param provider OAuth provider
+         * @param payload OAuth credentials
+         * @returns Created/updated credentials (without secret)
+         *
+         * @example
+         * ```typescript
+         * await sso.organizations.oauthCredentials.set('acme-corp', 'github', {
+         *   client_id: 'Iv1.abc123',
+         *   client_secret: 'secret-value'
+         * });
+         * ```
+         */
+        set: (orgSlug: string, provider: OAuthProvider, payload: SetOAuthCredentialsPayload) => Promise<OAuthCredentials>;
+        /**
+         * Get the configured OAuth credentials for a provider.
+         * The secret is never returned.
+         *
+         * @param orgSlug Organization slug
+         * @param provider OAuth provider
+         * @returns OAuth credentials (without secret)
+         *
+         * @example
+         * ```typescript
+         * const creds = await sso.organizations.oauthCredentials.get('acme-corp', 'github');
+         * console.log(creds.client_id);
+         * ```
+         */
+        get: (orgSlug: string, provider: OAuthProvider) => Promise<OAuthCredentials>;
+    };
+}
+
+/**
+ * Service management methods
+ */
+declare class ServicesModule {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new service for an organization.
+     * Requires 'owner' or 'admin' role.
+     *
+     * @param orgSlug Organization slug
+     * @param payload Service creation payload
+     * @returns Created service with details
+     *
+     * @example
+     * ```typescript
+     * const result = await sso.services.create('acme-corp', {
+     *   slug: 'main-app',
+     *   name: 'Main Application',
+     *   service_type: 'web',
+     *   github_scopes: ['user:email', 'read:org'],
+     *   redirect_uris: ['https://app.acme.com/callback']
+     * });
+     * console.log(result.service.client_id);
+     * ```
+     */
+    create(orgSlug: string, payload: CreateServicePayload): Promise<CreateServiceResponse>;
+    /**
+     * List all services for an organization.
+     *
+     * @param orgSlug Organization slug
+     * @returns Service list response with usage metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await sso.services.list('acme-corp');
+     * console.log(`Using ${result.usage.current_services} of ${result.usage.max_services} services`);
+     * result.services.forEach(svc => console.log(svc.name, svc.client_id));
+     * ```
+     */
+    list(orgSlug: string): Promise<ServiceListResponse>;
+    /**
+     * Get detailed information for a specific service.
+     *
+     * @param orgSlug Organization slug
+     * @param serviceSlug Service slug
+     * @returns Service with provider grants and plans
+     *
+     * @example
+     * ```typescript
+     * const service = await sso.services.get('acme-corp', 'main-app');
+     * console.log(service.service.redirect_uris);
+     * console.log(service.plans);
+     * ```
+     */
+    get(orgSlug: string, serviceSlug: string): Promise<ServiceResponse>;
+    /**
+     * Update service configuration.
+     * Requires 'owner' or 'admin' role.
+     *
+     * @param orgSlug Organization slug
+     * @param serviceSlug Service slug
+     * @param payload Update payload
+     * @returns Updated service
+     *
+     * @example
+     * ```typescript
+     * const updated = await sso.services.update('acme-corp', 'main-app', {
+     *   name: 'Main Application v2',
+     *   redirect_uris: ['https://app.acme.com/callback', 'https://app.acme.com/oauth']
+     * });
+     * ```
+     */
+    update(orgSlug: string, serviceSlug: string, payload: UpdateServicePayload): Promise<Service>;
+    /**
+     * Delete a service.
+     * Requires 'owner' role.
+     *
+     * @param orgSlug Organization slug
+     * @param serviceSlug Service slug
+     *
+     * @example
+     * ```typescript
+     * await sso.services.delete('acme-corp', 'old-app');
+     * ```
+     */
+    delete(orgSlug: string, serviceSlug: string): Promise<void>;
+    /**
+     * Plan management methods
+     */
+    plans: {
+        /**
+         * Create a new subscription plan for a service.
+         * Requires 'owner' or 'admin' role.
+         *
+         * @param orgSlug Organization slug
+         * @param serviceSlug Service slug
+         * @param payload Plan creation payload
+         * @returns Created plan
+         *
+         * @example
+         * ```typescript
+         * const plan = await sso.services.plans.create('acme-corp', 'main-app', {
+         *   name: 'pro',
+         *   description: 'Pro tier with advanced features',
+         *   price_monthly: 29.99,
+         *   features: ['api-access', 'advanced-analytics', 'priority-support']
+         * });
+         * ```
+         */
+        create: (orgSlug: string, serviceSlug: string, payload: CreatePlanPayload) => Promise<Plan>;
+        /**
+         * List all plans for a service.
+         *
+         * @param orgSlug Organization slug
+         * @param serviceSlug Service slug
+         * @returns Array of plans
+         *
+         * @example
+         * ```typescript
+         * const plans = await sso.services.plans.list('acme-corp', 'main-app');
+         * plans.forEach(plan => console.log(plan.name, plan.price_monthly));
+         * ```
+         */
+        list: (orgSlug: string, serviceSlug: string) => Promise<Plan[]>;
+    };
+}
+
+/**
+ * Invitation management methods
+ */
+declare class InvitationsModule {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create and send an invitation to join an organization.
+     * Requires 'owner' or 'admin' role.
+     *
+     * @param orgSlug Organization slug
+     * @param payload Invitation payload with email and role
+     * @returns Created invitation
+     *
+     * @example
+     * ```typescript
+     * const invitation = await sso.invitations.create('acme-corp', {
+     *   invitee_email: 'newuser@example.com',
+     *   role: 'member'
+     * });
+     * ```
+     */
+    create(orgSlug: string, payload: CreateInvitationPayload): Promise<Invitation>;
+    /**
+     * List all invitations for an organization.
+     * Requires 'owner' or 'admin' role.
+     *
+     * @param orgSlug Organization slug
+     * @returns Array of invitations
+     *
+     * @example
+     * ```typescript
+     * const invitations = await sso.invitations.listForOrg('acme-corp');
+     * invitations.forEach(inv => console.log(inv.invitee_email, inv.status));
+     * ```
+     */
+    listForOrg(orgSlug: string): Promise<Invitation[]>;
+    /**
+     * Cancel a pending invitation.
+     * Requires 'owner' or 'admin' role.
+     *
+     * @param orgSlug Organization slug
+     * @param invitationId Invitation ID to cancel
+     *
+     * @example
+     * ```typescript
+     * await sso.invitations.cancel('acme-corp', 'invitation-id');
+     * ```
+     */
+    cancel(orgSlug: string, invitationId: string): Promise<void>;
+    /**
+     * List invitations received by the current authenticated user.
+     *
+     * @returns Array of invitations with organization details
+     *
+     * @example
+     * ```typescript
+     * const myInvitations = await sso.invitations.listForUser();
+     * myInvitations.forEach(inv => {
+     *   console.log(`Invited to ${inv.organization_name} as ${inv.role}`);
+     * });
+     * ```
+     */
+    listForUser(): Promise<InvitationWithOrg[]>;
+    /**
+     * Accept an invitation using its token.
+     *
+     * @param token Invitation token
+     *
+     * @example
+     * ```typescript
+     * await sso.invitations.accept('invitation-token-from-email');
+     * ```
+     */
+    accept(token: string): Promise<void>;
+    /**
+     * Decline an invitation using its token.
+     *
+     * @param token Invitation token
+     *
+     * @example
+     * ```typescript
+     * await sso.invitations.decline('invitation-token-from-email');
+     * ```
+     */
+    decline(token: string): Promise<void>;
+}
+
+/**
+ * Platform owner administration methods.
+ * All methods require a Platform Owner JWT.
+ */
+declare class PlatformModule {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * List all available organization tiers.
+     *
+     * @returns Array of organization tiers
+     *
+     * @example
+     * ```typescript
+     * const tiers = await sso.platform.getTiers();
+     * console.log(tiers); // [{ id: 'tier_free', display_name: 'Free Tier', ... }]
+     * ```
+     */
+    getTiers(): Promise<OrganizationTier[]>;
+    /**
+     * Organization management for platform owners
+     */
+    organizations: {
+        /**
+         * List all organizations on the platform with optional filters.
+         *
+         * @param params Optional query parameters for filtering
+         * @returns Platform organizations list with pagination info
+         *
+         * @example
+         * ```typescript
+         * const result = await sso.platform.organizations.list({
+         *   status: 'pending',
+         *   page: 1,
+         *   limit: 50
+         * });
+         * console.log(result.total, result.organizations);
+         * ```
+         */
+        list: (params?: ListPlatformOrganizationsParams) => Promise<PlatformOrganizationsListResponse>;
+        /**
+         * Approve a pending organization and assign it a tier.
+         *
+         * @param orgId Organization ID
+         * @param payload Approval payload with tier assignment
+         * @returns Approved organization
+         *
+         * @example
+         * ```typescript
+         * const approved = await sso.platform.organizations.approve('org-id', {
+         *   tier_id: 'tier-starter'
+         * });
+         * ```
+         */
+        approve: (orgId: string, payload: ApproveOrganizationPayload) => Promise<Organization>;
+        /**
+         * Reject a pending organization with a reason.
+         *
+         * @param orgId Organization ID
+         * @param payload Rejection payload with reason
+         * @returns Rejected organization
+         *
+         * @example
+         * ```typescript
+         * await sso.platform.organizations.reject('org-id', {
+         *   reason: 'Does not meet platform requirements'
+         * });
+         * ```
+         */
+        reject: (orgId: string, payload: RejectOrganizationPayload) => Promise<Organization>;
+        /**
+         * Suspend an active organization.
+         *
+         * @param orgId Organization ID
+         * @returns Suspended organization
+         *
+         * @example
+         * ```typescript
+         * await sso.platform.organizations.suspend('org-id');
+         * ```
+         */
+        suspend: (orgId: string) => Promise<Organization>;
+        /**
+         * Re-activate a suspended organization.
+         *
+         * @param orgId Organization ID
+         * @returns Activated organization
+         *
+         * @example
+         * ```typescript
+         * await sso.platform.organizations.activate('org-id');
+         * ```
+         */
+        activate: (orgId: string) => Promise<Organization>;
+        /**
+         * Update an organization's tier and resource limits.
+         *
+         * @param orgId Organization ID
+         * @param payload Tier update payload
+         * @returns Updated organization
+         *
+         * @example
+         * ```typescript
+         * await sso.platform.organizations.updateTier('org-id', {
+         *   tier_id: 'tier-pro',
+         *   max_services: 20,
+         *   max_users: 100
+         * });
+         * ```
+         */
+        updateTier: (orgId: string, payload: UpdateOrganizationTierPayload) => Promise<Organization>;
+    };
+    /**
+     * Promote an existing user to platform owner.
+     *
+     * @param payload Promotion payload with user ID
+     *
+     * @example
+     * ```typescript
+     * await sso.platform.promoteOwner({
+     *   user_id: 'user-uuid-here'
+     * });
+     * ```
+     */
+    promoteOwner(payload: PromotePlatformOwnerPayload): Promise<void>;
+    /**
+     * Demote a platform owner to regular user.
+     *
+     * @param userId The ID of the user to demote
+     *
+     * @example
+     * ```typescript
+     * await sso.platform.demoteOwner('user-uuid-here');
+     * ```
+     */
+    demoteOwner(userId: string): Promise<void>;
+    /**
+     * Retrieve the platform-wide audit log with optional filters.
+     *
+     * @param params Optional query parameters for filtering
+     * @returns Array of audit log entries
+     *
+     * @example
+     * ```typescript
+     * const logs = await sso.platform.getAuditLog({
+     *   action: 'organization.approved',
+     *   start_date: '2024-01-01',
+     *   limit: 100
+     * });
+     * ```
+     */
+    getAuditLog(params?: GetAuditLogParams): Promise<AuditLogEntry[]>;
+}
+
+/**
+ * Configuration options for the SSO client
+ */
+interface SsoClientOptions {
+    /**
+     * Base URL of the SSO API service
+     */
+    baseURL: string;
+    /**
+     * Optional JWT token to initialize with
+     */
+    token?: string;
+}
+/**
+ * Main SSO client class.
+ * This is the entry point for all SDK operations.
+ *
+ * @example
+ * ```typescript
+ * const sso = new SsoClient({
+ *   baseURL: 'https://sso.example.com',
+ *   token: localStorage.getItem('jwt')
+ * });
+ *
+ * // Use the modules
+ * const user = await sso.user.getProfile();
+ * const orgs = await sso.organizations.list();
+ * ```
+ */
+declare class SsoClient {
+    private http;
+    /**
+     * Analytics and login tracking methods
+     */
+    readonly analytics: AnalyticsModule;
+    /**
+     * Authentication and OAuth flow methods
+     */
+    readonly auth: AuthModule;
+    /**
+     * User profile and subscription methods
+     */
+    readonly user: UserModule;
+    /**
+     * Organization management methods
+     */
+    readonly organizations: OrganizationsModule;
+    /**
+     * Service management methods
+     */
+    readonly services: ServicesModule;
+    /**
+     * Invitation management methods
+     */
+    readonly invitations: InvitationsModule;
+    /**
+     * Platform owner administration methods
+     */
+    readonly platform: PlatformModule;
+    constructor(options: SsoClientOptions);
+    /**
+     * Sets the JWT for all subsequent authenticated requests.
+     * Pass null to clear the token.
+     *
+     * @param token The JWT string, or null to clear
+     *
+     * @example
+     * ```typescript
+     * // Set token
+     * sso.setAuthToken(jwt);
+     *
+     * // Clear token
+     * sso.setAuthToken(null);
+     * ```
+     */
+    setAuthToken(token: string | null): void;
+    /**
+     * Gets the current base URL
+     */
+    getBaseURL(): string;
+}
+
+/**
+ * Custom error class for SSO API errors.
+ * Provides structured error information from the API.
+ */
+declare class SsoApiError extends Error {
+    /**
+     * The HTTP status code of the error response.
+     */
+    readonly statusCode: number;
+    /**
+     * The specific error code returned by the API.
+     */
+    readonly errorCode: string;
+    /**
+     * ISO 8601 timestamp when the error occurred.
+     */
+    readonly timestamp: string;
+    constructor(message: string, statusCode: number, errorCode: string, timestamp: string);
+    /**
+     * Check if the error is a specific error code.
+     */
+    is(errorCode: string): boolean;
+    /**
+     * Check if the error is an authentication error.
+     */
+    isAuthError(): boolean;
+    /**
+     * Check if the error is a permission error.
+     */
+    isForbidden(): boolean;
+    /**
+     * Check if the error is a not found error.
+     */
+    isNotFound(): boolean;
+}
+
+export { type AcceptInvitationPayload, type AdminLoginUrlParams, type AnalyticsQuery, type ApproveOrganizationPayload, type AuditLogEntry, AuthModule, type CreateInvitationPayload, type CreateOrganizationPayload, type CreateOrganizationResponse, type CreatePlanPayload, type CreateServicePayload, type CreateServiceResponse, type DeclineInvitationPayload, type DeviceCodeRequest, type DeviceCodeResponse, type EndUser, type EndUserDetailResponse, type EndUserIdentity, type EndUserListResponse, type EndUserSubscription, type GetAuditLogParams, type Identity, type Invitation, type InvitationStatus, type InvitationWithOrg, InvitationsModule, type JwtClaims, type ListEndUsersParams, type ListOrganizationsParams, type ListPlatformOrganizationsParams, type LoginTrendPoint, type LoginUrlParams, type LoginsByProvider, type LoginsByService, type MemberListResponse, type MemberRole, type Membership, type OAuthCredentials, type OAuthProvider, type Organization, type OrganizationMember, type OrganizationResponse, type OrganizationStatus, type OrganizationTier, OrganizationsModule, type PaginatedResponse, type PaginationParams, type Plan, PlatformModule, type PlatformOrganizationResponse, type PlatformOrganizationsListResponse, type PromotePlatformOwnerPayload, type ProviderToken, type ProviderTokenGrant, type RecentLogin, type RejectOrganizationPayload, type RevokeSessionsResponse, type Service, type ServiceListResponse, type ServiceResponse, type ServiceType, type ServiceWithDetails, ServicesModule, type SetOAuthCredentialsPayload, SsoApiError, SsoClient, type SsoClientOptions, type StartLinkResponse, type Subscription, type TokenRequest, type TokenResponse, type TransferOwnershipPayload, type UpdateMemberRolePayload, type UpdateOrganizationPayload, type UpdateOrganizationTierPayload, type UpdateServicePayload, type UpdateUserProfilePayload, type User, UserModule, type UserProfile };