@drmhse/sso-sdk 0.1.0 → 0.2.0

package/README.md

@@ -122,6 +122,29 @@ localStorage.removeItem('jwt');
 
 ## API Reference
 
+### Analytics
+
+The analytics module provides login tracking and metrics for organizations.
+
+```typescript
+// Get login trends over time
+const trends = await sso.analytics.getLoginTrends('acme-corp', {
+  start_date: '2025-01-01',
+  end_date: '2025-01-31'
+});
+
+// Get logins grouped by service
+const byService = await sso.analytics.getLoginsByService('acme-corp');
+
+// Get logins grouped by OAuth provider
+const byProvider = await sso.analytics.getLoginsByProvider('acme-corp');
+
+// Get recent login events
+const recent = await sso.analytics.getRecentLogins('acme-corp', {
+  limit: 10
+});
+```
+
 ### Organizations
 
 ```typescript
@@ -155,28 +178,61 @@ await sso.organizations.oauthCredentials.set('acme-corp', 'github', {
   client_id: 'Iv1.abc123',
   client_secret: 'secret-value'
 });
+
+// Get configured OAuth credentials
+const creds = await sso.organizations.oauthCredentials.get('acme-corp', 'github');
+```
+
+### End-User Management
+
+Manage your organization's customers (end-users with subscriptions).
+
+```typescript
+// List all end-users for an organization
+const endUsers = await sso.organizations.endUsers.list('acme-corp', {
+  page: 1,
+  limit: 20
+});
+
+// Get detailed information about a specific end-user
+const endUser = await sso.organizations.endUsers.get('acme-corp', 'user-id');
+
+// Revoke all active sessions for an end-user
+const result = await sso.organizations.endUsers.revokeSessions('acme-corp', 'user-id');
 ```
 
 ### Services
 
 ```typescript
-// Create service
-const service = await sso.services.create('acme-corp', {
+// Create service (returns service with provider grants and default plan)
+const result = await sso.services.create('acme-corp', {
   slug: 'main-app',
   name: 'Main Application',
   service_type: 'web',
   github_scopes: ['user:email', 'read:org'],
+  microsoft_scopes: ['User.Read', 'email'],
+  google_scopes: ['openid', 'email', 'profile'],
   redirect_uris: ['https://app.acme.com/callback']
 });
+console.log(result.service.client_id);
+console.log(result.usage.current_services);
 
-// List services
-const services = await sso.services.list('acme-corp');
+// List services (returns services with usage metadata)
+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));
 
-// Get service details
-const details = await sso.services.get('acme-corp', 'main-app');
+// Get service details (includes provider grants and plans)
+const service = await sso.services.get('acme-corp', 'main-app');
+console.log(service.service.redirect_uris);
+console.log(service.plans);
 
 // Update service
-await sso.services.update('acme-corp', 'main-app', {
+const updated = await sso.services.update('acme-corp', 'main-app', {
+  name: 'Main Application v2',
+  github_scopes: ['user:email', 'read:org', 'repo'],
+  microsoft_scopes: ['User.Read', 'email', 'Mail.Read'],
+  google_scopes: ['openid', 'email', 'profile', 'drive.readonly'],
   redirect_uris: ['https://app.acme.com/callback', 'https://app.acme.com/oauth']
 });
 
@@ -186,9 +242,14 @@ await sso.services.delete('acme-corp', 'old-service');
 // Manage plans
 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']
+  features: ['api-access', 'advanced-analytics', 'priority-support']
 });
+
+// List all plans for a service
+const plans = await sso.services.plans.list('acme-corp', 'main-app');
+plans.forEach(plan => console.log(plan.name, plan.price_monthly));
 ```
 
 ### Invitations
@@ -229,6 +290,22 @@ await sso.user.updateProfile({ email: 'newemail@example.com' });
 const subscription = await sso.user.getSubscription();
 ```
 
+### Social Account Identities
+
+Manage linked social accounts for the authenticated user.
+
+```typescript
+// List all linked social accounts
+const identities = await sso.user.identities.list();
+
+// Start linking a new social account
+const { authorization_url } = await sso.user.identities.startLink('github');
+window.location.href = authorization_url;
+
+// Unlink a social account
+await sso.user.identities.unlink('google');
+```
+
 ### Provider Tokens
 
 ```typescript
@@ -274,6 +351,12 @@ await sso.platform.promoteOwner({
   user_id: 'user-uuid-here'
 });
 
+// Demote platform owner to regular user
+await sso.platform.demoteOwner('user-uuid-here');
+
+// List available organization tiers
+const tiers = await sso.platform.getTiers();
+
 // Get audit log
 const logs = await sso.platform.getAuditLog({
   action: 'organization.approved',
@@ -306,6 +389,12 @@ try {
     if (error.is('SERVICE_LIMIT_EXCEEDED')) {
       // Handle specific error
     }
+    if (error.isForbidden()) {
+      // Handle permission errors
+    }
+    if (error.isAuthError()) {
+      // Handle authentication errors
+    }
   }
 }
 ```
@@ -387,10 +476,26 @@ import type {
   Service,
   User,
   JwtClaims,
-  OAuthProvider
+  OAuthProvider,
+  SsoClientOptions,
+  SsoApiError,
+  AnalyticsQuery,
+  LoginTrendPoint,
+  LoginsByService,
+  LoginsByProvider,
+  RecentLogin,
+  Invitation,
+  Subscription,
+  ProviderToken,
+  UserProfile,
+  PlatformOrganizationResponse,
+  AuditLogEntry,
+  // ... and many more types
 } from '@drmhse/sso-sdk';
 ```
 
+All API responses, request payloads, and configuration options are fully typed for excellent IDE support and compile-time safety.
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -181,6 +181,14 @@ interface DeviceCodeResponse {
     expires_in: number;
     interval: number;
 }
+/**
+ * Device verify response - returns context for initiating OAuth flow
+ */
+interface DeviceVerifyResponse {
+    org_slug: string;
+    service_slug: string;
+    available_providers: string[];
+}
 /**
  * Token request payload for device flow
  */
@@ -213,6 +221,10 @@ interface LoginUrlParams {
      * Optional redirect URI (must be registered with the service)
      */
     redirect_uri?: string;
+    /**
+     * Optional user code for device flow authorization
+     */
+    user_code?: string;
 }
 /**
  * Parameters for constructing admin login URL
@@ -222,6 +234,10 @@ interface AdminLoginUrlParams {
      * Optional organization slug to manage
      */
     org_slug?: string;
+    /**
+     * Optional user code for device flow authorization
+     */
+    user_code?: string;
 }
 /**
  * Provider token response
@@ -233,6 +249,20 @@ interface ProviderToken {
     scopes: string[];
     provider: OAuthProvider;
 }
+/**
+ * Refresh token request payload
+ */
+interface RefreshTokenRequest {
+    refresh_token: string;
+}
+/**
+ * Refresh token response
+ */
+interface RefreshTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+}
 
 /**
  * User subscription details
@@ -416,6 +446,7 @@ interface Service {
     microsoft_scopes: string[];
     google_scopes: string[];
     redirect_uris: string[];
+    device_activation_uri?: string;
     created_at: string;
 }
 /**
@@ -452,6 +483,7 @@ interface CreateServicePayload {
     microsoft_scopes?: string[];
     google_scopes?: string[];
     redirect_uris: string[];
+    device_activation_uri?: string;
 }
 /**
  * Create service response
@@ -476,6 +508,7 @@ interface UpdateServicePayload {
     microsoft_scopes?: string[];
     google_scopes?: string[];
     redirect_uris?: string[];
+    device_activation_uri?: string;
 }
 /**
  * Service response with details
@@ -645,6 +678,69 @@ interface GetAuditLogParams extends PaginationParams {
     start_date?: string;
     end_date?: string;
 }
+/**
+ * Platform overview metrics
+ */
+interface PlatformOverviewMetrics {
+    total_organizations: number;
+    total_users: number;
+    total_end_users: number;
+    total_services: number;
+    total_logins_24h: number;
+    total_logins_30d: number;
+}
+/**
+ * Organization status breakdown
+ */
+interface OrganizationStatusBreakdown {
+    pending: number;
+    active: number;
+    suspended: number;
+    rejected: number;
+}
+/**
+ * Growth trend data point
+ */
+interface GrowthTrendPoint {
+    date: string;
+    new_organizations: number;
+    new_users: number;
+}
+/**
+ * Login activity data point
+ */
+interface LoginActivityPoint {
+    date: string;
+    count: number;
+}
+/**
+ * Top organization metrics
+ */
+interface TopOrganization {
+    id: string;
+    name: string;
+    slug: string;
+    user_count: number;
+    service_count: number;
+    login_count_30d: number;
+}
+/**
+ * Recent organization data
+ */
+interface RecentOrganization {
+    id: string;
+    name: string;
+    slug: string;
+    status: OrganizationStatus;
+    created_at: string;
+}
+/**
+ * Platform analytics date range query params
+ */
+interface PlatformAnalyticsDateRangeParams {
+    start_date?: string;
+    end_date?: string;
+}
 
 /**
  * End-user subscription details
@@ -886,6 +982,20 @@ declare class AuthModule {
          * Request a device code
          */
         request: (payload: DeviceCodeRequest) => Promise<DeviceCodeResponse>;
+        /**
+         * Verify a user code and get the context (org_slug, service_slug)
+         * needed for the UI to initiate the appropriate OAuth flow.
+         *
+         * @param userCode The user-friendly code displayed on the device
+         * @returns Context with organization and service information
+         *
+         * @example
+         * ```typescript
+         * const context = await sso.auth.deviceCode.verify('ABCD-1234');
+         * // Use context.org_slug and context.service_slug to determine which OAuth flow to initiate
+         * ```
+         */
+        verify: (userCode: string) => Promise<DeviceVerifyResponse>;
         /**
          * Exchange a device code for a JWT token.
          * This should be polled by the device/CLI after displaying the user code.
@@ -929,6 +1039,32 @@ declare class AuthModule {
      * ```
      */
     logout(): Promise<void>;
+    /**
+     * Refresh an expired JWT access token using a refresh token.
+     * This implements token rotation - both the access token and refresh token
+     * will be renewed with each call.
+     *
+     * The refresh token must be stored securely on the client side.
+     * After a successful refresh, update both tokens in storage and call
+     * `sso.setAuthToken(newAccessToken)`.
+     *
+     * @param refreshToken The refresh token obtained during login
+     * @returns New access token and refresh token pair
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const tokens = await sso.auth.refreshToken(storedRefreshToken);
+     *   sso.setAuthToken(tokens.access_token);
+     *   localStorage.setItem('access_token', tokens.access_token);
+     *   localStorage.setItem('refresh_token', tokens.refresh_token);
+     * } catch (error) {
+     *   // Refresh failed - redirect to login
+     *   window.location.href = '/login';
+     * }
+     * ```
+     */
+    refreshToken(refreshToken: string): Promise<RefreshTokenResponse>;
     /**
      * Get a fresh provider access token for the authenticated user.
      * This will automatically refresh the token if it's expired.
@@ -1636,6 +1772,91 @@ declare class PlatformModule {
      * ```
      */
     getAuditLog(params?: GetAuditLogParams): Promise<AuditLogEntry[]>;
+    /**
+     * Platform analytics methods
+     */
+    analytics: {
+        /**
+         * Get platform overview metrics.
+         *
+         * @returns Platform overview metrics
+         *
+         * @example
+         * ```typescript
+         * const metrics = await sso.platform.analytics.getOverview();
+         * console.log(metrics.total_organizations, metrics.total_users);
+         * ```
+         */
+        getOverview: () => Promise<PlatformOverviewMetrics>;
+        /**
+         * Get organization status breakdown.
+         *
+         * @returns Organization count by status
+         *
+         * @example
+         * ```typescript
+         * const breakdown = await sso.platform.analytics.getOrganizationStatus();
+         * console.log(breakdown.pending, breakdown.active);
+         * ```
+         */
+        getOrganizationStatus: () => Promise<OrganizationStatusBreakdown>;
+        /**
+         * Get platform growth trends over time.
+         *
+         * @param params Optional date range parameters
+         * @returns Array of growth trend data points
+         *
+         * @example
+         * ```typescript
+         * const trends = await sso.platform.analytics.getGrowthTrends({
+         *   start_date: '2024-01-01',
+         *   end_date: '2024-01-31'
+         * });
+         * ```
+         */
+        getGrowthTrends: (params?: PlatformAnalyticsDateRangeParams) => Promise<GrowthTrendPoint[]>;
+        /**
+         * Get platform-wide login activity trends.
+         *
+         * @param params Optional date range parameters
+         * @returns Array of login activity data points
+         *
+         * @example
+         * ```typescript
+         * const activity = await sso.platform.analytics.getLoginActivity({
+         *   start_date: '2024-01-01',
+         *   end_date: '2024-01-31'
+         * });
+         * ```
+         */
+        getLoginActivity: (params?: PlatformAnalyticsDateRangeParams) => Promise<LoginActivityPoint[]>;
+        /**
+         * Get top organizations by activity.
+         *
+         * @returns Array of top organizations
+         *
+         * @example
+         * ```typescript
+         * const topOrgs = await sso.platform.analytics.getTopOrganizations();
+         * console.log(topOrgs[0].login_count_30d);
+         * ```
+         */
+        getTopOrganizations: () => Promise<TopOrganization[]>;
+        /**
+         * Get recently created organizations.
+         *
+         * @param params Optional query parameters
+         * @returns Array of recent organizations
+         *
+         * @example
+         * ```typescript
+         * const recent = await sso.platform.analytics.getRecentOrganizations({
+         *   limit: 10
+         * });
+         * ```
+         */
+        getRecentOrganizations: (params?: GetAuditLogParams) => Promise<RecentOrganization[]>;
+    };
 }
 
 /**
@@ -1756,4 +1977,4 @@ declare class SsoApiError extends 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 };
+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 DeviceVerifyResponse, type EndUser, type EndUserDetailResponse, type EndUserIdentity, type EndUserListResponse, type EndUserSubscription, type GetAuditLogParams, type GrowthTrendPoint, type Identity, type Invitation, type InvitationStatus, type InvitationWithOrg, InvitationsModule, type JwtClaims, type ListEndUsersParams, type ListOrganizationsParams, type ListPlatformOrganizationsParams, type LoginActivityPoint, 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 OrganizationStatusBreakdown, type OrganizationTier, OrganizationsModule, type PaginatedResponse, type PaginationParams, type Plan, type PlatformAnalyticsDateRangeParams, PlatformModule, type PlatformOrganizationResponse, type PlatformOrganizationsListResponse, type PlatformOverviewMetrics, type PromotePlatformOwnerPayload, type ProviderToken, type ProviderTokenGrant, type RecentLogin, type RecentOrganization, type RefreshTokenRequest, type RefreshTokenResponse, 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 TopOrganization, type TransferOwnershipPayload, type UpdateMemberRolePayload, type UpdateOrganizationPayload, type UpdateOrganizationTierPayload, type UpdateServicePayload, type UpdateUserProfilePayload, type User, UserModule, type UserProfile };

package/dist/index.d.ts

@@ -181,6 +181,14 @@ interface DeviceCodeResponse {
     expires_in: number;
     interval: number;
 }
+/**
+ * Device verify response - returns context for initiating OAuth flow
+ */
+interface DeviceVerifyResponse {
+    org_slug: string;
+    service_slug: string;
+    available_providers: string[];
+}
 /**
  * Token request payload for device flow
  */
@@ -213,6 +221,10 @@ interface LoginUrlParams {
      * Optional redirect URI (must be registered with the service)
      */
     redirect_uri?: string;
+    /**
+     * Optional user code for device flow authorization
+     */
+    user_code?: string;
 }
 /**
  * Parameters for constructing admin login URL
@@ -222,6 +234,10 @@ interface AdminLoginUrlParams {
      * Optional organization slug to manage
      */
     org_slug?: string;
+    /**
+     * Optional user code for device flow authorization
+     */
+    user_code?: string;
 }
 /**
  * Provider token response
@@ -233,6 +249,20 @@ interface ProviderToken {
     scopes: string[];
     provider: OAuthProvider;
 }
+/**
+ * Refresh token request payload
+ */
+interface RefreshTokenRequest {
+    refresh_token: string;
+}
+/**
+ * Refresh token response
+ */
+interface RefreshTokenResponse {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+}
 
 /**
  * User subscription details
@@ -416,6 +446,7 @@ interface Service {
     microsoft_scopes: string[];
     google_scopes: string[];
     redirect_uris: string[];
+    device_activation_uri?: string;
     created_at: string;
 }
 /**
@@ -452,6 +483,7 @@ interface CreateServicePayload {
     microsoft_scopes?: string[];
     google_scopes?: string[];
     redirect_uris: string[];
+    device_activation_uri?: string;
 }
 /**
  * Create service response
@@ -476,6 +508,7 @@ interface UpdateServicePayload {
     microsoft_scopes?: string[];
     google_scopes?: string[];
     redirect_uris?: string[];
+    device_activation_uri?: string;
 }
 /**
  * Service response with details
@@ -645,6 +678,69 @@ interface GetAuditLogParams extends PaginationParams {
     start_date?: string;
     end_date?: string;
 }
+/**
+ * Platform overview metrics
+ */
+interface PlatformOverviewMetrics {
+    total_organizations: number;
+    total_users: number;
+    total_end_users: number;
+    total_services: number;
+    total_logins_24h: number;
+    total_logins_30d: number;
+}
+/**
+ * Organization status breakdown
+ */
+interface OrganizationStatusBreakdown {
+    pending: number;
+    active: number;
+    suspended: number;
+    rejected: number;
+}
+/**
+ * Growth trend data point
+ */
+interface GrowthTrendPoint {
+    date: string;
+    new_organizations: number;
+    new_users: number;
+}
+/**
+ * Login activity data point
+ */
+interface LoginActivityPoint {
+    date: string;
+    count: number;
+}
+/**
+ * Top organization metrics
+ */
+interface TopOrganization {
+    id: string;
+    name: string;
+    slug: string;
+    user_count: number;
+    service_count: number;
+    login_count_30d: number;
+}
+/**
+ * Recent organization data
+ */
+interface RecentOrganization {
+    id: string;
+    name: string;
+    slug: string;
+    status: OrganizationStatus;
+    created_at: string;
+}
+/**
+ * Platform analytics date range query params
+ */
+interface PlatformAnalyticsDateRangeParams {
+    start_date?: string;
+    end_date?: string;
+}
 
 /**
  * End-user subscription details
@@ -886,6 +982,20 @@ declare class AuthModule {
          * Request a device code
          */
         request: (payload: DeviceCodeRequest) => Promise<DeviceCodeResponse>;
+        /**
+         * Verify a user code and get the context (org_slug, service_slug)
+         * needed for the UI to initiate the appropriate OAuth flow.
+         *
+         * @param userCode The user-friendly code displayed on the device
+         * @returns Context with organization and service information
+         *
+         * @example
+         * ```typescript
+         * const context = await sso.auth.deviceCode.verify('ABCD-1234');
+         * // Use context.org_slug and context.service_slug to determine which OAuth flow to initiate
+         * ```
+         */
+        verify: (userCode: string) => Promise<DeviceVerifyResponse>;
         /**
          * Exchange a device code for a JWT token.
          * This should be polled by the device/CLI after displaying the user code.
@@ -929,6 +1039,32 @@ declare class AuthModule {
      * ```
      */
     logout(): Promise<void>;
+    /**
+     * Refresh an expired JWT access token using a refresh token.
+     * This implements token rotation - both the access token and refresh token
+     * will be renewed with each call.
+     *
+     * The refresh token must be stored securely on the client side.
+     * After a successful refresh, update both tokens in storage and call
+     * `sso.setAuthToken(newAccessToken)`.
+     *
+     * @param refreshToken The refresh token obtained during login
+     * @returns New access token and refresh token pair
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const tokens = await sso.auth.refreshToken(storedRefreshToken);
+     *   sso.setAuthToken(tokens.access_token);
+     *   localStorage.setItem('access_token', tokens.access_token);
+     *   localStorage.setItem('refresh_token', tokens.refresh_token);
+     * } catch (error) {
+     *   // Refresh failed - redirect to login
+     *   window.location.href = '/login';
+     * }
+     * ```
+     */
+    refreshToken(refreshToken: string): Promise<RefreshTokenResponse>;
     /**
      * Get a fresh provider access token for the authenticated user.
      * This will automatically refresh the token if it's expired.
@@ -1636,6 +1772,91 @@ declare class PlatformModule {
      * ```
      */
     getAuditLog(params?: GetAuditLogParams): Promise<AuditLogEntry[]>;
+    /**
+     * Platform analytics methods
+     */
+    analytics: {
+        /**
+         * Get platform overview metrics.
+         *
+         * @returns Platform overview metrics
+         *
+         * @example
+         * ```typescript
+         * const metrics = await sso.platform.analytics.getOverview();
+         * console.log(metrics.total_organizations, metrics.total_users);
+         * ```
+         */
+        getOverview: () => Promise<PlatformOverviewMetrics>;
+        /**
+         * Get organization status breakdown.
+         *
+         * @returns Organization count by status
+         *
+         * @example
+         * ```typescript
+         * const breakdown = await sso.platform.analytics.getOrganizationStatus();
+         * console.log(breakdown.pending, breakdown.active);
+         * ```
+         */
+        getOrganizationStatus: () => Promise<OrganizationStatusBreakdown>;
+        /**
+         * Get platform growth trends over time.
+         *
+         * @param params Optional date range parameters
+         * @returns Array of growth trend data points
+         *
+         * @example
+         * ```typescript
+         * const trends = await sso.platform.analytics.getGrowthTrends({
+         *   start_date: '2024-01-01',
+         *   end_date: '2024-01-31'
+         * });
+         * ```
+         */
+        getGrowthTrends: (params?: PlatformAnalyticsDateRangeParams) => Promise<GrowthTrendPoint[]>;
+        /**
+         * Get platform-wide login activity trends.
+         *
+         * @param params Optional date range parameters
+         * @returns Array of login activity data points
+         *
+         * @example
+         * ```typescript
+         * const activity = await sso.platform.analytics.getLoginActivity({
+         *   start_date: '2024-01-01',
+         *   end_date: '2024-01-31'
+         * });
+         * ```
+         */
+        getLoginActivity: (params?: PlatformAnalyticsDateRangeParams) => Promise<LoginActivityPoint[]>;
+        /**
+         * Get top organizations by activity.
+         *
+         * @returns Array of top organizations
+         *
+         * @example
+         * ```typescript
+         * const topOrgs = await sso.platform.analytics.getTopOrganizations();
+         * console.log(topOrgs[0].login_count_30d);
+         * ```
+         */
+        getTopOrganizations: () => Promise<TopOrganization[]>;
+        /**
+         * Get recently created organizations.
+         *
+         * @param params Optional query parameters
+         * @returns Array of recent organizations
+         *
+         * @example
+         * ```typescript
+         * const recent = await sso.platform.analytics.getRecentOrganizations({
+         *   limit: 10
+         * });
+         * ```
+         */
+        getRecentOrganizations: (params?: GetAuditLogParams) => Promise<RecentOrganization[]>;
+    };
 }
 
 /**
@@ -1756,4 +1977,4 @@ declare class SsoApiError extends 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 };
+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 DeviceVerifyResponse, type EndUser, type EndUserDetailResponse, type EndUserIdentity, type EndUserListResponse, type EndUserSubscription, type GetAuditLogParams, type GrowthTrendPoint, type Identity, type Invitation, type InvitationStatus, type InvitationWithOrg, InvitationsModule, type JwtClaims, type ListEndUsersParams, type ListOrganizationsParams, type ListPlatformOrganizationsParams, type LoginActivityPoint, 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 OrganizationStatusBreakdown, type OrganizationTier, OrganizationsModule, type PaginatedResponse, type PaginationParams, type Plan, type PlatformAnalyticsDateRangeParams, PlatformModule, type PlatformOrganizationResponse, type PlatformOrganizationsListResponse, type PlatformOverviewMetrics, type PromotePlatformOwnerPayload, type ProviderToken, type ProviderTokenGrant, type RecentLogin, type RecentOrganization, type RefreshTokenRequest, type RefreshTokenResponse, 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 TopOrganization, type TransferOwnershipPayload, type UpdateMemberRolePayload, type UpdateOrganizationPayload, type UpdateOrganizationTierPayload, type UpdateServicePayload, type UpdateUserProfilePayload, type User, UserModule, type UserProfile };

package/dist/index.js

@@ -348,6 +348,25 @@ var AuthModule = class {
         const response = await this.http.post("/auth/device/code", payload);
         return response.data;
       },
+      /**
+       * Verify a user code and get the context (org_slug, service_slug)
+       * needed for the UI to initiate the appropriate OAuth flow.
+       *
+       * @param userCode The user-friendly code displayed on the device
+       * @returns Context with organization and service information
+       *
+       * @example
+       * ```typescript
+       * const context = await sso.auth.deviceCode.verify('ABCD-1234');
+       * // Use context.org_slug and context.service_slug to determine which OAuth flow to initiate
+       * ```
+       */
+      verify: async (userCode) => {
+        const response = await this.http.post("/auth/device/verify", {
+          user_code: userCode
+        });
+        return response.data;
+      },
       /**
        * Exchange a device code for a JWT token.
        * This should be polled by the device/CLI after displaying the user code.
@@ -410,6 +429,9 @@ var AuthModule = class {
     if (params.redirect_uri) {
       searchParams.append("redirect_uri", params.redirect_uri);
     }
+    if (params.user_code) {
+      searchParams.append("user_code", params.user_code);
+    }
     return `${baseURL}/auth/${provider}?${searchParams.toString()}`;
   }
   /**
@@ -434,6 +456,9 @@ var AuthModule = class {
     if (params?.org_slug) {
       searchParams.append("org_slug", params.org_slug);
     }
+    if (params?.user_code) {
+      searchParams.append("user_code", params.user_code);
+    }
     const queryString = searchParams.toString();
     return `${baseURL}/auth/admin/${provider}${queryString ? `?${queryString}` : ""}`;
   }
@@ -452,6 +477,37 @@ var AuthModule = class {
   async logout() {
     await this.http.post("/api/auth/logout");
   }
+  /**
+   * Refresh an expired JWT access token using a refresh token.
+   * This implements token rotation - both the access token and refresh token
+   * will be renewed with each call.
+   *
+   * The refresh token must be stored securely on the client side.
+   * After a successful refresh, update both tokens in storage and call
+   * `sso.setAuthToken(newAccessToken)`.
+   *
+   * @param refreshToken The refresh token obtained during login
+   * @returns New access token and refresh token pair
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const tokens = await sso.auth.refreshToken(storedRefreshToken);
+   *   sso.setAuthToken(tokens.access_token);
+   *   localStorage.setItem('access_token', tokens.access_token);
+   *   localStorage.setItem('refresh_token', tokens.refresh_token);
+   * } catch (error) {
+   *   // Refresh failed - redirect to login
+   *   window.location.href = '/login';
+   * }
+   * ```
+   */
+  async refreshToken(refreshToken) {
+    const response = await this.http.post("/api/auth/refresh", {
+      refresh_token: refreshToken
+    });
+    return response.data;
+  }
   /**
    * Get a fresh provider access token for the authenticated user.
    * This will automatically refresh the token if it's expired.
@@ -1264,6 +1320,122 @@ var PlatformModule = class {
         return response.data;
       }
     };
+    /**
+     * Platform analytics methods
+     */
+    this.analytics = {
+      /**
+       * Get platform overview metrics.
+       *
+       * @returns Platform overview metrics
+       *
+       * @example
+       * ```typescript
+       * const metrics = await sso.platform.analytics.getOverview();
+       * console.log(metrics.total_organizations, metrics.total_users);
+       * ```
+       */
+      getOverview: async () => {
+        const response = await this.http.get("/api/platform/analytics/overview");
+        return response.data;
+      },
+      /**
+       * Get organization status breakdown.
+       *
+       * @returns Organization count by status
+       *
+       * @example
+       * ```typescript
+       * const breakdown = await sso.platform.analytics.getOrganizationStatus();
+       * console.log(breakdown.pending, breakdown.active);
+       * ```
+       */
+      getOrganizationStatus: async () => {
+        const response = await this.http.get(
+          "/api/platform/analytics/organization-status"
+        );
+        return response.data;
+      },
+      /**
+       * Get platform growth trends over time.
+       *
+       * @param params Optional date range parameters
+       * @returns Array of growth trend data points
+       *
+       * @example
+       * ```typescript
+       * const trends = await sso.platform.analytics.getGrowthTrends({
+       *   start_date: '2024-01-01',
+       *   end_date: '2024-01-31'
+       * });
+       * ```
+       */
+      getGrowthTrends: async (params) => {
+        const response = await this.http.get(
+          "/api/platform/analytics/growth-trends",
+          { params }
+        );
+        return response.data;
+      },
+      /**
+       * Get platform-wide login activity trends.
+       *
+       * @param params Optional date range parameters
+       * @returns Array of login activity data points
+       *
+       * @example
+       * ```typescript
+       * const activity = await sso.platform.analytics.getLoginActivity({
+       *   start_date: '2024-01-01',
+       *   end_date: '2024-01-31'
+       * });
+       * ```
+       */
+      getLoginActivity: async (params) => {
+        const response = await this.http.get(
+          "/api/platform/analytics/login-activity",
+          { params }
+        );
+        return response.data;
+      },
+      /**
+       * Get top organizations by activity.
+       *
+       * @returns Array of top organizations
+       *
+       * @example
+       * ```typescript
+       * const topOrgs = await sso.platform.analytics.getTopOrganizations();
+       * console.log(topOrgs[0].login_count_30d);
+       * ```
+       */
+      getTopOrganizations: async () => {
+        const response = await this.http.get(
+          "/api/platform/analytics/top-organizations"
+        );
+        return response.data;
+      },
+      /**
+       * Get recently created organizations.
+       *
+       * @param params Optional query parameters
+       * @returns Array of recent organizations
+       *
+       * @example
+       * ```typescript
+       * const recent = await sso.platform.analytics.getRecentOrganizations({
+       *   limit: 10
+       * });
+       * ```
+       */
+      getRecentOrganizations: async (params) => {
+        const response = await this.http.get(
+          "/api/platform/analytics/recent-organizations",
+          { params }
+        );
+        return response.data;
+      }
+    };
   }
   /**
    * List all available organization tiers.

package/dist/index.mjs

@@ -315,6 +315,25 @@ var AuthModule = class {
         const response = await this.http.post("/auth/device/code", payload);
         return response.data;
       },
+      /**
+       * Verify a user code and get the context (org_slug, service_slug)
+       * needed for the UI to initiate the appropriate OAuth flow.
+       *
+       * @param userCode The user-friendly code displayed on the device
+       * @returns Context with organization and service information
+       *
+       * @example
+       * ```typescript
+       * const context = await sso.auth.deviceCode.verify('ABCD-1234');
+       * // Use context.org_slug and context.service_slug to determine which OAuth flow to initiate
+       * ```
+       */
+      verify: async (userCode) => {
+        const response = await this.http.post("/auth/device/verify", {
+          user_code: userCode
+        });
+        return response.data;
+      },
       /**
        * Exchange a device code for a JWT token.
        * This should be polled by the device/CLI after displaying the user code.
@@ -377,6 +396,9 @@ var AuthModule = class {
     if (params.redirect_uri) {
       searchParams.append("redirect_uri", params.redirect_uri);
     }
+    if (params.user_code) {
+      searchParams.append("user_code", params.user_code);
+    }
     return `${baseURL}/auth/${provider}?${searchParams.toString()}`;
   }
   /**
@@ -401,6 +423,9 @@ var AuthModule = class {
     if (params?.org_slug) {
       searchParams.append("org_slug", params.org_slug);
     }
+    if (params?.user_code) {
+      searchParams.append("user_code", params.user_code);
+    }
     const queryString = searchParams.toString();
     return `${baseURL}/auth/admin/${provider}${queryString ? `?${queryString}` : ""}`;
   }
@@ -419,6 +444,37 @@ var AuthModule = class {
   async logout() {
     await this.http.post("/api/auth/logout");
   }
+  /**
+   * Refresh an expired JWT access token using a refresh token.
+   * This implements token rotation - both the access token and refresh token
+   * will be renewed with each call.
+   *
+   * The refresh token must be stored securely on the client side.
+   * After a successful refresh, update both tokens in storage and call
+   * `sso.setAuthToken(newAccessToken)`.
+   *
+   * @param refreshToken The refresh token obtained during login
+   * @returns New access token and refresh token pair
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const tokens = await sso.auth.refreshToken(storedRefreshToken);
+   *   sso.setAuthToken(tokens.access_token);
+   *   localStorage.setItem('access_token', tokens.access_token);
+   *   localStorage.setItem('refresh_token', tokens.refresh_token);
+   * } catch (error) {
+   *   // Refresh failed - redirect to login
+   *   window.location.href = '/login';
+   * }
+   * ```
+   */
+  async refreshToken(refreshToken) {
+    const response = await this.http.post("/api/auth/refresh", {
+      refresh_token: refreshToken
+    });
+    return response.data;
+  }
   /**
    * Get a fresh provider access token for the authenticated user.
    * This will automatically refresh the token if it's expired.
@@ -1231,6 +1287,122 @@ var PlatformModule = class {
         return response.data;
       }
     };
+    /**
+     * Platform analytics methods
+     */
+    this.analytics = {
+      /**
+       * Get platform overview metrics.
+       *
+       * @returns Platform overview metrics
+       *
+       * @example
+       * ```typescript
+       * const metrics = await sso.platform.analytics.getOverview();
+       * console.log(metrics.total_organizations, metrics.total_users);
+       * ```
+       */
+      getOverview: async () => {
+        const response = await this.http.get("/api/platform/analytics/overview");
+        return response.data;
+      },
+      /**
+       * Get organization status breakdown.
+       *
+       * @returns Organization count by status
+       *
+       * @example
+       * ```typescript
+       * const breakdown = await sso.platform.analytics.getOrganizationStatus();
+       * console.log(breakdown.pending, breakdown.active);
+       * ```
+       */
+      getOrganizationStatus: async () => {
+        const response = await this.http.get(
+          "/api/platform/analytics/organization-status"
+        );
+        return response.data;
+      },
+      /**
+       * Get platform growth trends over time.
+       *
+       * @param params Optional date range parameters
+       * @returns Array of growth trend data points
+       *
+       * @example
+       * ```typescript
+       * const trends = await sso.platform.analytics.getGrowthTrends({
+       *   start_date: '2024-01-01',
+       *   end_date: '2024-01-31'
+       * });
+       * ```
+       */
+      getGrowthTrends: async (params) => {
+        const response = await this.http.get(
+          "/api/platform/analytics/growth-trends",
+          { params }
+        );
+        return response.data;
+      },
+      /**
+       * Get platform-wide login activity trends.
+       *
+       * @param params Optional date range parameters
+       * @returns Array of login activity data points
+       *
+       * @example
+       * ```typescript
+       * const activity = await sso.platform.analytics.getLoginActivity({
+       *   start_date: '2024-01-01',
+       *   end_date: '2024-01-31'
+       * });
+       * ```
+       */
+      getLoginActivity: async (params) => {
+        const response = await this.http.get(
+          "/api/platform/analytics/login-activity",
+          { params }
+        );
+        return response.data;
+      },
+      /**
+       * Get top organizations by activity.
+       *
+       * @returns Array of top organizations
+       *
+       * @example
+       * ```typescript
+       * const topOrgs = await sso.platform.analytics.getTopOrganizations();
+       * console.log(topOrgs[0].login_count_30d);
+       * ```
+       */
+      getTopOrganizations: async () => {
+        const response = await this.http.get(
+          "/api/platform/analytics/top-organizations"
+        );
+        return response.data;
+      },
+      /**
+       * Get recently created organizations.
+       *
+       * @param params Optional query parameters
+       * @returns Array of recent organizations
+       *
+       * @example
+       * ```typescript
+       * const recent = await sso.platform.analytics.getRecentOrganizations({
+       *   limit: 10
+       * });
+       * ```
+       */
+      getRecentOrganizations: async (params) => {
+        const response = await this.http.get(
+          "/api/platform/analytics/recent-organizations",
+          { params }
+        );
+        return response.data;
+      }
+    };
   }
   /**
    * List all available organization tiers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drmhse/sso-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zero-dependency TypeScript SDK for the multi-tenant SSO Platform API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",