expand upon js api (#2641)

* expand upon js api

* Make clear mutally exclusive options

Author: Logan-Dang

docs/src/pages/reference/integration.mdx

@@ -3,14 +3,191 @@ id: integration
 title: Integration
 ---
 
-## Import script
+## Programmatic Usage
 
-Orval gives you the possibility to import Orval.
+Orval provides a powerful programmatic API that allows you to integrate code generation into your build processes, scripts, or tools.
 
-It expose a function which takes a path to the Orval config as the argument.
+### Basic Usage
 
-```js
+#### Using the Default Export
+
+```typescript
 import orval from 'orval';
 
-orval('./orval.config.js');
+// Generate using a config file path
+await orval('./orval.config.js');
+
+// Generate using current directory's orval config
+await orval();
+```
+
+#### Using the Named Export
+
+```typescript
+import { generate } from 'orval';
+
+// Same functionality as default export
+await generate('./orval.config.js');
+```
+
+### Advanced Usage
+
+#### Direct Configuration Object
+
+You can pass a configuration object directly instead of using a config file:
+
+```typescript
+import { generate, type Options } from 'orval';
+
+const config: Options = {
+  input: {
+    target: './api-spec.yaml',
+  },
+  output: {
+    target: './src/api.ts',
+    client: 'axios',
+  },
+};
+
+await generate(config);
+```
+
+#### Global Options Override
+
+Pass global options to override config file settings. See the complete [GlobalOptions interface](https://github.com/orval-labs/orval/blob/master/packages/core/src/types.ts#L718) for all available options.
+
+```typescript
+import { generate, type GlobalOptions } from 'orval';
+
+const globalOptions: GlobalOptions = {
+  // File watching
+  watch: true,                    // Enable watch mode (boolean)
+  
+  // OR
+  // watch: './specs/**/*.yaml',     // Watch specific file pattern (string)
+  
+  // OR
+  // watch: ['./specs/*.yaml', './src/types.ts'], // Watch multiple patterns (string[])
+  
+  // Output control
+  clean: true,                    // Clean all output directories (boolean)
+  
+  // OR
+  // clean: ['./src/api', './types'], // Clean specific directories (string[])
+  
+  output: './src/generated',      // Override output directory
+  
+  // Code formatting
+  prettier: true,                 // Format with Prettier [Pretter Output Options](https://orval.dev/reference/configuration/output#prettier)
+  biome: true,                   // Format with Biome [Biome Output Options](https://orval.dev/reference/configuration/output#biome)
+  
+  // HTTP client configuration 
+  client: 'fetch',               // Override HTTP client: 'axios' | 'angular' | 'fetch' | 'swr' | 'react-query' | 'vue-query' | 'svelte-query' [Client Output Options](https://orval.dev/reference/configuration/output#client)
+  httpClient: 'fetch',           // HTTP implementation: 'axios' | 'fetch' [HttpClient Output Options](https://orval.dev/reference/configuration/output#httpclient)
+  
+  // Generation mode
+  mode: 'split',                 // Output mode: 'single' | 'split' | 'tags' | 'tags-split'
+  
+  // Mock data generation
+  mock: true,                    // Enable mock data generation (boolean)
+  
+  // OR 
+  // mock: {                        // Configure mock options (GlobalMockOptions)
+  //   type: 'msw',
+  //   delay: 1000,
+  // },
+  
+  // TypeScript configuration
+  // Use EITHER a custom tsconfig path (string)... 
+  tsconfig: './tsconfig.json',   // Custom tsconfig path (string)
+  // ...OR an inline tsconfig object:  
+  // tsconfig: {  
+  //   compilerOptions: {  
+  //     target: 'ES2020',  
+  //     esModuleInterop: true,  
+  //   },  
+  // },
+  
+  // Package configuration
+  packageJson: './package.json', // Custom package.json path
+  input: './api-spec.yaml',      // Override input specification
+};
+
+await generate('./orval.config.js', process.cwd(), globalOptions);
+```
+
+#### Custom Workspace
+
+Specify a custom workspace directory (default `process.cwd()`):
+
+```typescript
+import { generate } from 'orval';
+
+const workspace = '/path/to/your/project';
+await generate('./orval.config.js', workspace);
+```
+
+### Function Signature
+
+```typescript
+function generate(
+  optionsExport?: string | OptionsExport,
+  workspace?: string,
+  options?: GlobalOptions,
+): Promise<void>
 ```
+
+#### Parameters
+
+- **`optionsExport`** *(optional)*: Path to config file or configuration object
+- **`workspace`** *(optional)*: Working directory (defaults to `process.cwd()`)
+- **`options`** *(optional)*: Global options to override config settings
+
+### Watch Mode
+
+Enable file watching for automatic regeneration:
+
+```typescript
+import { generate } from 'orval';
+
+// Enable watch mode via global options
+await generate('./orval.config.js', process.cwd(), { 
+  watch: true 
+});
+
+// Watch specific files/directories
+await generate('./orval.config.js', process.cwd(), { 
+  watch: ['./specs/*.yaml', './src/custom-types.ts']
+});
+```
+
+### Build Scripts Integration
+
+#### npm/yarn scripts
+
+```json
+{
+  "scripts": {
+    "generate": "node scripts/generate-api.js",
+    "dev": "npm run generate && next dev",
+    "build": "npm run generate && next build"
+  }
+}
+```
+
+```javascript
+// scripts/generate-api.js
+const { generate } = require('orval');
+
+async function main() {
+  try {
+    await generate();
+    console.log('API client generated successfully');
+  } catch (error) {
+    console.error('Failed to generate API client:', error);
+    process.exit(1);
+  }
+}
+
+main();
+```