@drmhse/sso-sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1352 @@
+// src/errors.ts
+var SsoApiError = class _SsoApiError extends Error {
+  constructor(message, statusCode, errorCode, timestamp) {
+    super(message);
+    this.name = "SsoApiError";
+    this.statusCode = statusCode;
+    this.errorCode = errorCode;
+    this.timestamp = timestamp;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _SsoApiError);
+    }
+  }
+  /**
+   * Check if the error is a specific error code.
+   */
+  is(errorCode) {
+    return this.errorCode === errorCode;
+  }
+  /**
+   * Check if the error is an authentication error.
+   */
+  isAuthError() {
+    return this.statusCode === 401 || this.errorCode === "UNAUTHORIZED" || this.errorCode === "TOKEN_EXPIRED";
+  }
+  /**
+   * Check if the error is a permission error.
+   */
+  isForbidden() {
+    return this.statusCode === 403 || this.errorCode === "FORBIDDEN";
+  }
+  /**
+   * Check if the error is a not found error.
+   */
+  isNotFound() {
+    return this.statusCode === 404 || this.errorCode === "NOT_FOUND";
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(baseURL) {
+    this.defaults = {
+      baseURL,
+      headers: {
+        common: {
+          "Content-Type": "application/json"
+        }
+      },
+      timeout: 3e4
+    };
+  }
+  /**
+   * Build query string from params object
+   */
+  buildQueryString(params) {
+    if (!params) return "";
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== void 0 && value !== null) {
+        searchParams.append(key, String(value));
+      }
+    });
+    const queryString = searchParams.toString();
+    return queryString ? `?${queryString}` : "";
+  }
+  /**
+   * Build full URL from path and params
+   */
+  buildUrl(path, params) {
+    const baseUrl = this.defaults.baseURL.replace(/\/$/, "");
+    const cleanPath = path.startsWith("/") ? path : `/${path}`;
+    const queryString = this.buildQueryString(params);
+    return `${baseUrl}${cleanPath}${queryString}`;
+  }
+  /**
+   * Make HTTP request with timeout support
+   */
+  async request(path, options) {
+    const url = this.buildUrl(path, options.params);
+    const timeout = options.timeout ?? this.defaults.timeout;
+    const headers = {
+      ...this.defaults.headers.common,
+      ...options.headers
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(url, {
+        method: options.method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : void 0,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      let data;
+      const contentType = response.headers.get("content-type");
+      if (contentType?.includes("application/json")) {
+        data = await response.json();
+      } else {
+        const text = await response.text();
+        data = text || void 0;
+      }
+      if (!response.ok) {
+        if (data && data.error_code && data.error && data.timestamp) {
+          throw new SsoApiError(data.error, response.status, data.error_code, data.timestamp);
+        }
+        throw new SsoApiError(
+          data?.message || `HTTP ${response.status}: ${response.statusText}`,
+          response.status,
+          "UNKNOWN_ERROR",
+          (/* @__PURE__ */ new Date()).toISOString()
+        );
+      }
+      return {
+        data,
+        status: response.status,
+        headers: response.headers
+      };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error.name === "AbortError") {
+        throw new SsoApiError("Request timeout", 408, "TIMEOUT", (/* @__PURE__ */ new Date()).toISOString());
+      }
+      if (error instanceof TypeError && error.message.includes("fetch")) {
+        throw new SsoApiError(
+          "Network error - unable to reach the server",
+          0,
+          "NETWORK_ERROR",
+          (/* @__PURE__ */ new Date()).toISOString()
+        );
+      }
+      if (error instanceof SsoApiError) {
+        throw error;
+      }
+      throw new SsoApiError(
+        error.message || "An unexpected error occurred",
+        500,
+        "UNKNOWN_ERROR",
+        (/* @__PURE__ */ new Date()).toISOString()
+      );
+    }
+  }
+  /**
+   * GET request
+   */
+  async get(path, config) {
+    return this.request(path, {
+      method: "GET",
+      params: config?.params,
+      headers: config?.headers
+    });
+  }
+  /**
+   * POST request
+   */
+  async post(path, data, config) {
+    return this.request(path, {
+      method: "POST",
+      body: data,
+      headers: config?.headers
+    });
+  }
+  /**
+   * PATCH request
+   */
+  async patch(path, data, config) {
+    return this.request(path, {
+      method: "PATCH",
+      body: data,
+      headers: config?.headers
+    });
+  }
+  /**
+   * DELETE request
+   */
+  async delete(path, config) {
+    return this.request(path, {
+      method: "DELETE",
+      headers: config?.headers
+    });
+  }
+};
+function createHttpAgent(baseURL) {
+  return new HttpClient(baseURL);
+}
+
+// src/modules/analytics.ts
+var AnalyticsModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async getLoginTrends(orgSlug, params) {
+    const response = await this.http.get(
+      `/api/organizations/${orgSlug}/analytics/login-trends`,
+      { params }
+    );
+    return response.data;
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async getLoginsByService(orgSlug, params) {
+    const response = await this.http.get(
+      `/api/organizations/${orgSlug}/analytics/logins-by-service`,
+      { params }
+    );
+    return response.data;
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async getLoginsByProvider(orgSlug, params) {
+    const response = await this.http.get(
+      `/api/organizations/${orgSlug}/analytics/logins-by-provider`,
+      { params }
+    );
+    return response.data;
+  }
+  /**
+   * 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);
+   * });
+   * ```
+   */
+  async getRecentLogins(orgSlug, params) {
+    const response = await this.http.get(
+      `/api/organizations/${orgSlug}/analytics/recent-logins`,
+      { params }
+    );
+    return response.data;
+  }
+};
+
+// src/modules/auth.ts
+var AuthModule = class {
+  constructor(http) {
+    this.http = http;
+    /**
+     * 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}`);
+     * ```
+     */
+    this.deviceCode = {
+      /**
+       * Request a device code
+       */
+      request: async (payload) => {
+        const response = await this.http.post("/auth/device/code", payload);
+        return response.data;
+      },
+      /**
+       * 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: async (payload) => {
+        const response = await this.http.post("/auth/token", payload);
+        return response.data;
+      }
+    };
+  }
+  /**
+   * 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, params) {
+    const baseURL = this.http.defaults.baseURL || "";
+    const searchParams = new URLSearchParams({
+      org: params.org,
+      service: params.service
+    });
+    if (params.redirect_uri) {
+      searchParams.append("redirect_uri", params.redirect_uri);
+    }
+    return `${baseURL}/auth/${provider}?${searchParams.toString()}`;
+  }
+  /**
+   * 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, params) {
+    const baseURL = this.http.defaults.baseURL || "";
+    const searchParams = new URLSearchParams();
+    if (params?.org_slug) {
+      searchParams.append("org_slug", params.org_slug);
+    }
+    const queryString = searchParams.toString();
+    return `${baseURL}/auth/admin/${provider}${queryString ? `?${queryString}` : ""}`;
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async logout() {
+    await this.http.post("/api/auth/logout");
+  }
+  /**
+   * 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
+   * ```
+   */
+  async getProviderToken(provider) {
+    const response = await this.http.get(`/api/provider-token/${provider}`);
+    return response.data;
+  }
+};
+
+// src/modules/user.ts
+var IdentitiesModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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' }]
+   * ```
+   */
+  async list() {
+    const response = await this.http.get("/api/user/identities");
+    return response.data;
+  }
+  /**
+   * 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
+   * ```
+   */
+  async startLink(provider) {
+    const response = await this.http.post(`/api/user/identities/${provider}/link`, {});
+    return response.data;
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async unlink(provider) {
+    await this.http.delete(`/api/user/identities/${provider}`);
+  }
+};
+var UserModule = class {
+  constructor(http) {
+    this.http = http;
+    this.identities = new IdentitiesModule(http);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getProfile() {
+    const response = await this.http.get("/api/user");
+    return response.data;
+  }
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async updateProfile(payload) {
+    const response = await this.http.patch("/api/user", payload);
+    return response.data;
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async getSubscription() {
+    const response = await this.http.get("/api/subscription");
+    return response.data;
+  }
+};
+
+// src/modules/organizations.ts
+var OrganizationsModule = class {
+  constructor(http) {
+    this.http = http;
+    /**
+     * Member management methods
+     */
+    this.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: async (orgSlug) => {
+        const response = await this.http.get(
+          `/api/organizations/${orgSlug}/members`
+        );
+        return response.data;
+      },
+      /**
+       * 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: async (orgSlug, userId, payload) => {
+        const response = await this.http.patch(
+          `/api/organizations/${orgSlug}/members/${userId}`,
+          payload
+        );
+        return response.data;
+      },
+      /**
+       * 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: async (orgSlug, userId) => {
+        await this.http.post(`/api/organizations/${orgSlug}/members/${userId}`);
+      },
+      /**
+       * 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: async (orgSlug, payload) => {
+        await this.http.post(`/api/organizations/${orgSlug}/members/transfer-ownership`, payload);
+      }
+    };
+    /**
+     * End-user management methods
+     * Manage organization's customers (end-users with subscriptions)
+     */
+    this.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: async (orgSlug, params) => {
+        const response = await this.http.get(
+          `/api/organizations/${orgSlug}/users`,
+          { params }
+        );
+        return response.data;
+      },
+      /**
+       * 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: async (orgSlug, userId) => {
+        const response = await this.http.get(
+          `/api/organizations/${orgSlug}/users/${userId}`
+        );
+        return response.data;
+      },
+      /**
+       * 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: async (orgSlug, userId) => {
+        const response = await this.http.delete(
+          `/api/organizations/${orgSlug}/users/${userId}/sessions`
+        );
+        return response.data;
+      }
+    };
+    /**
+     * BYOO (Bring Your Own OAuth) credential management
+     */
+    this.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: async (orgSlug, provider, payload) => {
+        const response = await this.http.post(
+          `/api/organizations/${orgSlug}/oauth-credentials/${provider}`,
+          payload
+        );
+        return response.data;
+      },
+      /**
+       * 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: async (orgSlug, provider) => {
+        const response = await this.http.get(
+          `/api/organizations/${orgSlug}/oauth-credentials/${provider}`
+        );
+        return response.data;
+      }
+    };
+  }
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async createPublic(payload) {
+    const response = await this.http.post("/api/organizations", payload);
+    return response.data;
+  }
+  /**
+   * 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
+   * });
+   * ```
+   */
+  async list(params) {
+    const response = await this.http.get("/api/organizations", { params });
+    return response.data;
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async get(orgSlug) {
+    const response = await this.http.get(`/api/organizations/${orgSlug}`);
+    return response.data;
+  }
+  /**
+   * 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
+   * });
+   * ```
+   */
+  async update(orgSlug, payload) {
+    const response = await this.http.patch(
+      `/api/organizations/${orgSlug}`,
+      payload
+    );
+    return response.data;
+  }
+};
+
+// src/modules/services.ts
+var ServicesModule = class {
+  constructor(http) {
+    this.http = http;
+    /**
+     * Plan management methods
+     */
+    this.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: async (orgSlug, serviceSlug, payload) => {
+        const response = await this.http.post(
+          `/api/organizations/${orgSlug}/services/${serviceSlug}/plans`,
+          payload
+        );
+        return response.data;
+      },
+      /**
+       * 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: async (orgSlug, serviceSlug) => {
+        const response = await this.http.get(
+          `/api/organizations/${orgSlug}/services/${serviceSlug}/plans`
+        );
+        return response.data;
+      }
+    };
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async create(orgSlug, payload) {
+    const response = await this.http.post(
+      `/api/organizations/${orgSlug}/services`,
+      payload
+    );
+    return response.data;
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async list(orgSlug) {
+    const response = await this.http.get(`/api/organizations/${orgSlug}/services`);
+    return response.data;
+  }
+  /**
+   * 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);
+   * ```
+   */
+  async get(orgSlug, serviceSlug) {
+    const response = await this.http.get(
+      `/api/organizations/${orgSlug}/services/${serviceSlug}`
+    );
+    return response.data;
+  }
+  /**
+   * 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']
+   * });
+   * ```
+   */
+  async update(orgSlug, serviceSlug, payload) {
+    const response = await this.http.patch(
+      `/api/organizations/${orgSlug}/services/${serviceSlug}`,
+      payload
+    );
+    return response.data;
+  }
+  /**
+   * Delete a service.
+   * Requires 'owner' role.
+   *
+   * @param orgSlug Organization slug
+   * @param serviceSlug Service slug
+   *
+   * @example
+   * ```typescript
+   * await sso.services.delete('acme-corp', 'old-app');
+   * ```
+   */
+  async delete(orgSlug, serviceSlug) {
+    await this.http.delete(`/api/organizations/${orgSlug}/services/${serviceSlug}`);
+  }
+};
+
+// src/modules/invitations.ts
+var InvitationsModule = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async create(orgSlug, payload) {
+    const response = await this.http.post(
+      `/api/organizations/${orgSlug}/invitations`,
+      payload
+    );
+    return response.data;
+  }
+  /**
+   * 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));
+   * ```
+   */
+  async listForOrg(orgSlug) {
+    const response = await this.http.get(
+      `/api/organizations/${orgSlug}/invitations`
+    );
+    return response.data;
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async cancel(orgSlug, invitationId) {
+    await this.http.post(`/api/organizations/${orgSlug}/invitations/${invitationId}`);
+  }
+  /**
+   * 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}`);
+   * });
+   * ```
+   */
+  async listForUser() {
+    const response = await this.http.get("/api/invitations");
+    return response.data;
+  }
+  /**
+   * Accept an invitation using its token.
+   *
+   * @param token Invitation token
+   *
+   * @example
+   * ```typescript
+   * await sso.invitations.accept('invitation-token-from-email');
+   * ```
+   */
+  async accept(token) {
+    const payload = { token };
+    await this.http.post("/api/invitations/accept", payload);
+  }
+  /**
+   * Decline an invitation using its token.
+   *
+   * @param token Invitation token
+   *
+   * @example
+   * ```typescript
+   * await sso.invitations.decline('invitation-token-from-email');
+   * ```
+   */
+  async decline(token) {
+    const payload = { token };
+    await this.http.post("/api/invitations/decline", payload);
+  }
+};
+
+// src/modules/platform.ts
+var PlatformModule = class {
+  constructor(http) {
+    this.http = http;
+    /**
+     * Organization management for platform owners
+     */
+    this.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: async (params) => {
+        const response = await this.http.get(
+          "/api/platform/organizations",
+          { params }
+        );
+        return response.data;
+      },
+      /**
+       * 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: async (orgId, payload) => {
+        const response = await this.http.post(
+          `/api/platform/organizations/${orgId}/approve`,
+          payload
+        );
+        return response.data;
+      },
+      /**
+       * 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: async (orgId, payload) => {
+        const response = await this.http.post(
+          `/api/platform/organizations/${orgId}/reject`,
+          payload
+        );
+        return response.data;
+      },
+      /**
+       * Suspend an active organization.
+       *
+       * @param orgId Organization ID
+       * @returns Suspended organization
+       *
+       * @example
+       * ```typescript
+       * await sso.platform.organizations.suspend('org-id');
+       * ```
+       */
+      suspend: async (orgId) => {
+        const response = await this.http.post(
+          `/api/platform/organizations/${orgId}/suspend`
+        );
+        return response.data;
+      },
+      /**
+       * Re-activate a suspended organization.
+       *
+       * @param orgId Organization ID
+       * @returns Activated organization
+       *
+       * @example
+       * ```typescript
+       * await sso.platform.organizations.activate('org-id');
+       * ```
+       */
+      activate: async (orgId) => {
+        const response = await this.http.post(
+          `/api/platform/organizations/${orgId}/activate`
+        );
+        return response.data;
+      },
+      /**
+       * 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: async (orgId, payload) => {
+        const response = await this.http.patch(
+          `/api/platform/organizations/${orgId}/tier`,
+          payload
+        );
+        return response.data;
+      }
+    };
+  }
+  /**
+   * 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', ... }]
+   * ```
+   */
+  async getTiers() {
+    const response = await this.http.get("/api/platform/tiers");
+    return response.data;
+  }
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  async promoteOwner(payload) {
+    await this.http.post("/api/platform/owners", payload);
+  }
+  /**
+   * 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');
+   * ```
+   */
+  async demoteOwner(userId) {
+    await this.http.delete(`/api/platform/owners/${userId}`);
+  }
+  /**
+   * 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
+   * });
+   * ```
+   */
+  async getAuditLog(params) {
+    const response = await this.http.get("/api/platform/audit-log", { params });
+    return response.data;
+  }
+};
+
+// src/client.ts
+var SsoClient = class {
+  constructor(options) {
+    this.http = createHttpAgent(options.baseURL);
+    if (options.token) {
+      this.setAuthToken(options.token);
+    }
+    this.analytics = new AnalyticsModule(this.http);
+    this.auth = new AuthModule(this.http);
+    this.user = new UserModule(this.http);
+    this.organizations = new OrganizationsModule(this.http);
+    this.services = new ServicesModule(this.http);
+    this.invitations = new InvitationsModule(this.http);
+    this.platform = new PlatformModule(this.http);
+  }
+  /**
+   * 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) {
+    if (token) {
+      this.http.defaults.headers.common["Authorization"] = `Bearer ${token}`;
+    } else {
+      delete this.http.defaults.headers.common["Authorization"];
+    }
+  }
+  /**
+   * Gets the current base URL
+   */
+  getBaseURL() {
+    return this.http.defaults.baseURL || "";
+  }
+};
+export {
+  AuthModule,
+  InvitationsModule,
+  OrganizationsModule,
+  PlatformModule,
+  ServicesModule,
+  SsoApiError,
+  SsoClient,
+  UserModule
+};