Contributing

workos-node/
├── src/               # TypeScript source code
│   ├── workos.ts      # Main WorkOS class
│   ├── user-management/
│   ├── sso/
│   ├── directory-sync/
│   └── ...
├── lib/               # Compiled output (generated)
├── package.json       # Package configuration
├── tsconfig.json      # TypeScript configuration
└── tsdown.config.ts   # Build configuration

# Development
npm run build          # Build the project
npm run build:watch    # Build in watch mode
npm run typecheck      # Check TypeScript types

# Testing
npm test               # Run tests
npm run test:watch     # Run tests in watch mode

# Code Quality
npm run lint           # Lint code
npm run format         # Format code with Prettier
npm run prettier       # Check formatting

# Runtime Checks
npm run check:runtimes # Test across Node.js, Deno, Bun, Cloudflare Workers
npm run check:types    # Validate type definitions

// ✅ Good: Explicit types
interface CreateUserOptions {
  email: string;
  firstName?: string;
  lastName?: string;
}

async function createUser(options: CreateUserOptions): Promise<User> {
  // Implementation
}

// ❌ Bad: Implicit any types
async function createUser(options) {
  // Implementation
}

module-name/
├── module-name.ts              # Main implementation
├── module-name.spec.ts         # Tests
├── interfaces/                  # TypeScript interfaces
│   ├── index.ts
│   ├── entity.interface.ts
│   └── options.interface.ts
└── serializers/                 # Data transformation
    ├── index.ts
    └── entity.serializer.ts

import { WorkOS } from '../workos';
import fetchMock from 'jest-fetch-mock';

describe('UserManagement', () => {
  beforeEach(() => fetchMock.resetMocks());
  
  describe('getUser', () => {
    it('should return a user', async () => {
      // Arrange
      const workos = new WorkOS('sk_test_123');
      fetchMock.mockResponseOnce(JSON.stringify({
        id: 'user_123',
        email: '[email protected]',
        // ...
      }));
      
      // Act
      const user = await workos.userManagement.getUser({ 
        userId: 'user_123' 
      });
      
      // Assert
      expect(user.id).toBe('user_123');
      expect(user.email).toBe('[email protected]');
    });
  });
});

# Run all tests
npm test

# Run specific test file
npm test user-management.spec.ts

# Run in watch mode
npm run test:watch

# Run with coverage
npm test -- --coverage

type(scope): description

Examples:
feat(user-management): add PKCE authentication support
fix(sso): correct authorization URL parameter handling
docs(readme): update installation instructions
test(directory-sync): add tests for custom attributes

/**
 * Get a user by ID.
 *
 * @param options - Options for getting a user
 * @param options.userId - The ID of the user to get
 * @returns The user object
 * @throws {NotFoundException} If the user is not found
 *
 * @example
 * ```typescript
 * const user = await workos.userManagement.getUser({ 
 *   userId: 'user_123' 
 * });
 * ```
 */
async getUser(options: GetUserOptions): Promise<User> {
  // Implementation
}