[V8] create client API for methods that don't require an API key (#1354)

This pull request introduces a new set of client-only methods for
building OAuth and SSO URLs that do not require a WorkOS API key, making
them suitable for browser-based PKCE flows and similar use cases. The
changes include the addition of new client modules for user management
and SSO, comprehensive tests for these modules, a shared query string
utility, and updates to the main SDK exports. Additionally, the
server-side SDK now delegates URL generation to the new client modules
for consistency and maintainability.

**Client Module Additions and Exports:**

* Added new `src/client/user-management.ts` and `src/client/sso.ts`
modules, providing functions to build authorization, logout, and JWKS
URLs for OAuth and SSO flows without requiring an API key. These modules
include robust argument validation and support for custom query
parameters and PKCE.
[[1]](diffhunk://#diff-b5a04503adce4aaadee02b4511ee9bd11ec26a46927bde7c07d85ad31786e4bbR1-R147)
[[2]](diffhunk://#diff-aba556dc64a77e993f9ce2de8ffd20b276128d1f6f4ba69bf2967e05dc1f7676R1-R62)
* Updated `src/index.client.ts` and `src/client/index.ts` to export the
new client modules and their types, making them easily accessible for
browser environments.
[[1]](diffhunk://#diff-0311bcbdf2e78d79d36c4417c3c6d6409834421d79d111e294dbacf47e487984R1-R19)
[[2]](diffhunk://#diff-24f1ac19d22913269d99a8a5afa4c13aa7fd2c8b9858529046424841ca6421daR1-R18)
* Updated the package export map in `package.json` to include the new
client entry points for both ESM and CJS consumers.

**Testing and Utilities:**

* Added comprehensive test suites for the new client modules in
`src/client/user-management.spec.ts`, `src/client/sso.spec.ts`, and
integration tests in `src/index.client.spec.ts`, ensuring correct URL
generation and error handling for all supported options.
[[1]](diffhunk://#diff-01061808fc40490ae09053b5553be015aa94e42cb7efcf8dbeba57a23c699e80R1-R219)
[[2]](diffhunk://#diff-28da04c6058919471ee96a352c58c206146b8ac07454e7ab25613a59a20fc7bdR1-R114)
[[3]](diffhunk://#diff-da4fa2fd6101519fd777b8803892a919b567b988b1bb48fc941671e20beb23ecR1-R47)
* Introduced a shared `toQueryString` utility in `src/client/utils.ts`
for consistent and backwards-compatible query string generation across
client modules.

**Server SDK Refactoring:**

* Updated server-side SDK modules (`src/sso/sso.ts` and
`src/user-management/user-management.ts`) to delegate authorization URL
generation to the new client modules, ensuring consistency and reducing
code duplication.
[[1]](diffhunk://#diff-40f88259248b65c47b88e6460bbb0e52cd4f70fc298c96319889051c19bcd3a6L1-R1)
[[2]](diffhunk://#diff-40f88259248b65c47b88e6460bbb0e52cd4f70fc298c96319889051c19bcd3a6L26-L40)
[[3]](diffhunk://#diff-40f88259248b65c47b88e6460bbb0e52cd4f70fc298c96319889051c19bcd3a6L68-L100)
[[4]](diffhunk://#diff-5df813524b03843b7a76359f2c080a36e82f2c065c578794071eb6ffcc0efa7cL3-R3)

These changes collectively improve the SDK's usability for client-side
OAuth flows, enhance maintainability, and ensure robust, well-tested URL
generation logic.

Author: nicknisi

package.json

@@ -103,6 +103,15 @@
       "require": "./lib/cjs/index.cjs",
       "default": "./lib/esm/index.js"
     },
+    "./client": {
+      "types": {
+        "require": "./lib/cjs/index.client.d.cts",
+        "import": "./lib/esm/index.client.d.ts"
+      },
+      "import": "./lib/esm/index.client.js",
+      "require": "./lib/cjs/index.client.cjs",
+      "default": "./lib/esm/index.client.js"
+    },
     "./worker": {
       "types": {
         "require": "./lib/cjs/index.worker.d.cts",

src/client/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Client methods that can be used without a WorkOS API key.
+ * These are OAuth client operations suitable for PKCE flows.
+ */
+
+// User Management client methods and types
+export * as userManagement from './user-management';
+
+// SSO client methods and types
+export * as sso from './sso';
+
+// Re-export specific types for convenience
+export type {
+  AuthorizationURLOptions as UserManagementAuthorizationURLOptions,
+  LogoutURLOptions,
+} from './user-management';
+
+export type { SSOAuthorizationURLOptions } from './sso';

src/client/sso.spec.ts

@@ -0,0 +1,115 @@
+import { getAuthorizationUrl } from './sso';
+
+describe('Public SSO Methods', () => {
+  describe('getAuthorizationUrl', () => {
+    it('builds correct URL with provider', () => {
+      const url = getAuthorizationUrl({
+        clientId: 'client_123',
+        redirectUri: 'https://app.com/callback',
+        provider: 'GoogleOAuth',
+      });
+
+      expect(url).toContain('https://api.workos.com/sso/authorize');
+      expect(url).toContain('client_id=client_123');
+      expect(url).toContain('redirect_uri=https%3A%2F%2Fapp.com%2Fcallback');
+      expect(url).toContain('provider=GoogleOAuth');
+      expect(url).toContain('response_type=code');
+    });
+
+    it('builds URL with organization', () => {
+      const url = getAuthorizationUrl({
+        clientId: 'client_123',
+        redirectUri: 'https://app.com/callback',
+        organization: 'org_123',
+      });
+
+      expect(url).toContain('organization=org_123');
+    });
+
+    it('builds URL with connection', () => {
+      const url = getAuthorizationUrl({
+        clientId: 'client_123',
+        redirectUri: 'https://app.com/callback',
+        connection: 'conn_123',
+      });
+
+      expect(url).toContain('connection=conn_123');
+    });
+
+    it('includes state parameter', () => {
+      const url = getAuthorizationUrl({
+        clientId: 'client_123',
+        redirectUri: 'https://app.com/callback',
+        provider: 'GoogleOAuth',
+        state: 'custom state',
+      });
+
+      expect(url).toContain('state=custom+state');
+    });
+
+    it('includes domainHint and loginHint', () => {
+      const url = getAuthorizationUrl({
+        clientId: 'client_123',
+        redirectUri: 'https://app.com/callback',
+        provider: 'GoogleOAuth',
+        domainHint: 'example.com',
+        loginHint: '[email protected]',
+      });
+
+      expect(url).toContain('domain_hint=example.com');
+      expect(url).toContain('login_hint=user%40example.com');
+    });
+
+    it('includes provider scopes', () => {
+      const url = getAuthorizationUrl({
+        clientId: 'client_123',
+        redirectUri: 'https://app.com/callback',
+        provider: 'GoogleOAuth',
+        providerScopes: ['read_api', 'read_repository'],
+      });
+
+      expect(url).toContain('provider_scopes=read_api');
+      expect(url).toContain('provider_scopes=read_repository');
+    });
+
+    it('includes provider query params', () => {
+      const url = getAuthorizationUrl({
+        clientId: 'client_123',
+        redirectUri: 'https://app.com/callback',
+        provider: 'GoogleOAuth',
+        providerQueryParams: {
+          foo: 'bar',
+          baz: 123,
+          bool: true,
+        },
+      });
+
+      expect(url).toContain('provider_query_params%5Bfoo%5D=bar');
+      expect(url).toContain('provider_query_params%5Bbaz%5D=123');
+      expect(url).toContain('provider_query_params%5Bbool%5D=true');
+    });
+
+    it('uses custom baseURL when provided', () => {
+      const url = getAuthorizationUrl({
+        clientId: 'client_123',
+        redirectUri: 'https://app.com/callback',
+        provider: 'GoogleOAuth',
+        baseURL: 'https://api.workos.dev',
+      });
+
+      expect(url).toContain('https://api.workos.dev/sso/authorize');
+    });
+
+    it('throws error when no provider, connection, or organization specified', () => {
+      expect(() => {
+        // @ts-expect-error Testing runtime validation with invalid input
+        getAuthorizationUrl({
+          clientId: 'client_123',
+          redirectUri: 'https://app.com/callback',
+        });
+      }).toThrow(
+        "Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.",
+      );
+    });
+  });
+});

src/client/sso.ts

@@ -0,0 +1,55 @@
+import { toQueryString } from './utils';
+import type { SSOAuthorizationURLOptions as BaseSSOAuthorizationURLOptions } from '../sso/interfaces';
+
+// Extend the base options to include baseURL for internal use
+export type SSOAuthorizationURLOptions = BaseSSOAuthorizationURLOptions & {
+  baseURL?: string;
+};
+
+/**
+ * Generates the authorization URL for SSO authentication.
+ * Does not require an API key, suitable for OAuth client operations.
+ *
+ * @param options - SSO authorization URL options
+ * @returns The authorization URL as a string
+ * @throws Error if required arguments are missing
+ */
+export function getAuthorizationUrl(
+  options: SSOAuthorizationURLOptions,
+): string {
+  const {
+    connection,
+    clientId,
+    domainHint,
+    loginHint,
+    organization,
+    provider,
+    providerQueryParams,
+    providerScopes,
+    redirectUri,
+    state,
+    baseURL = 'https://api.workos.com',
+  } = options;
+
+  if (!provider && !connection && !organization) {
+    throw new Error(
+      `Incomplete arguments. Need to specify either a 'connection', 'organization', or 'provider'.`,
+    );
+  }
+
+  const query = toQueryString({
+    connection,
+    organization,
+    domain_hint: domainHint,
+    login_hint: loginHint,
+    provider,
+    provider_query_params: providerQueryParams,
+    provider_scopes: providerScopes,
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: 'code',
+    state,
+  });
+
+  return `${baseURL}/sso/authorize?${query}`;
+}