@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/api-reference/cli-profile-integration.md

@@ -1,377 +0,0 @@
-# Fluent CLI Profile Integration
-
-## Overview
-
-The SDK can read profiles created by the official Fluent CLI (`fluent profile create`), allowing you to create a fully configured `FluentClient` without hardcoding any credentials. This is the recommended approach for standalone Node.js and Deno scripts that run outside the Versori platform.
-
-Key benefits:
-
-- **No hardcoded credentials.** Reuse the same profiles you already created with the Fluent CLI.
-- **One-liner client creation.** `createClientFromProfile('MYPROFILE')` returns a ready-to-use `FluentClient`.
-- **Multi-retailer support.** Pass a `retailer` option to automatically load the correct retailer ID and user credentials.
-
-## How Fluent CLI Profiles Work
-
-When you run `fluent profile create`, the CLI writes JSON files under `~/.fluentcommerce/`. Each profile is a directory containing credentials and optional retailer configurations.
-
-```
-~/.fluentcommerce/
-├── PROFILE_BETA/
-│   ├── profile.json              -> { id, baseUrl, clientSecret, user }
-│   ├── retailer.RETAILER_ALPHA.json    -> { id, ref, user }
-│   └── user.profile_beta_admin.json    -> { username, password }
-└── PROFILE_ALPHA/
-    ├── profile.json
-    └── user.profile_alpha_admin.json
-```
-
-**File descriptions:**
-
-| File | Purpose | Key Fields |
-|------|---------|------------|
-| `profile.json` | Account-level config | `id` (clientId), `baseUrl`, `clientSecret`, `user` (default username ref) |
-| `retailer.<REF>.json` | Retailer-specific config | `id` (retailerId), `ref`, `user` (retailer-specific username ref) |
-| `user.<name>.json` | User credentials | `username`, `password` |
-
-**Loading chain:**
-
-1. Read `profile.json` to get `baseUrl`, `clientId`, `clientSecret`, and the default user reference.
-2. If a retailer is specified, read `retailer.<ref>.json` to get `retailerId` and an optional user override.
-3. Read `user.<resolvedUser>.json` to get the final `username` and `password`.
-
-## Quick Start
-
-```typescript
-import { createClientFromProfile, listFluentProfiles } from '@fluentcommerce/fc-connect-sdk';
-
-// List available profiles
-const profiles = listFluentProfiles();
-console.log(profiles); // ['PROFILE_BETA', 'PROFILE_ALPHA']
-
-// Create a client from a CLI profile
-const client = await createClientFromProfile('PROFILE_ALPHA');
-
-// Use it like any other FluentClient
-const events = await client.getEvents({ eventType: 'ORCHESTRATION_AUDIT' });
-```
-
-## Retailer Override
-
-When a profile has multiple retailers, the `retailer` option loads the correct retailer ID **and** switches to the retailer-specific user credentials automatically.
-
-```typescript
-const client = await createClientFromProfile('PROFILE_BETA', { retailer: 'RETAILER_ALPHA' });
-```
-
-What happens internally:
-
-1. `profile.json` is read. Default user is `profile_beta_admin`.
-2. `retailer.RETAILER_ALPHA.json` is read. It overrides the user to `retailer_alpha_admin` and provides `retailerId: '5'`.
-3. `user.retailer_alpha_admin.json` is read for the final credentials.
-4. The resulting `FluentClientConfig` contains `retailerId: '5'` and the `retailer_alpha_admin` credentials -- not the default `profile_beta_admin`.
-
-Without the `retailer` option, the profile's default user is used and no `retailerId` is set.
-
-## API Reference
-
-All functions below are exported from the main SDK entry point:
-
-```typescript
-import {
-  createClientFromProfile,
-  loadFluentProfile,
-  listFluentProfiles,
-  getFluentProfileInfo,
-  resolveProfileBaseDir,
-} from '@fluentcommerce/fc-connect-sdk';
-```
-
-### createClientFromProfile(profileName, options?)
-
-Creates a `FluentClient` from a Fluent CLI profile. This is the primary entry point for most use cases.
-
-```typescript
-async function createClientFromProfile(
-  profileName: string,
-  options?: FluentProfileOptions & CreateClientOptions & { logger?: Logger }
-): Promise<FluentClient>
-```
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `profileName` | `string` | Yes | CLI profile name (directory name under `~/.fluentcommerce/`) |
-| `options` | `object` | No | Merged options from `FluentProfileOptions`, `CreateClientOptions`, and `{ logger }` |
-
-**Returns:** `Promise<FluentClient>` -- a fully configured client with OAuth2 credentials loaded from disk.
-
-**Throws:** `Error` if the profile directory, `profile.json`, retailer file, or user credentials file is missing or malformed.
-
-**Examples:**
-
-```typescript
-// Basic usage
-const client = await createClientFromProfile('PROFILE_ALPHA');
-
-// With retailer and connection validation
-const client = await createClientFromProfile('PROFILE_BETA', {
-  retailer: 'RETAILER_ALPHA',
-  validateConnection: true,
-});
-
-// With custom logger and timeout
-const client = await createClientFromProfile('PROFILE_BETA', {
-  retailer: 'RETAILER_ALPHA',
-  timeout: 30000,
-  logger: myCustomLogger,
-});
-```
-
-When `validateConnection: true` is set, the factory executes `query { me { ref } }` immediately after creating the client to verify that authentication works. If it fails, the error is thrown before any business logic runs.
-
----
-
-### loadFluentProfile(profileName, options?)
-
-Loads a CLI profile and returns a raw `FluentClientConfig` object without creating a client. Useful when you need the config for custom client construction.
-
-```typescript
-function loadFluentProfile(
-  profileName: string,
-  options?: FluentProfileOptions
-): FluentClientConfig
-```
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `profileName` | `string` | Yes | CLI profile name |
-| `options` | `FluentProfileOptions` | No | Profile directory, retailer, timeout, retry overrides |
-
-**Returns:** `FluentClientConfig` with `baseUrl`, `clientId`, `clientSecret`, `username`, `password`, and optionally `retailerId`, `timeout`, `retryConfig`.
-
-**Throws:** `Error` if any required file is missing or contains invalid data.
-
-**Example:**
-
-```typescript
-const config = loadFluentProfile('PROFILE_BETA', { retailer: 'RETAILER_ALPHA' });
-// config = {
-//   baseUrl: 'https://profile-beta.api.fluentcommerce.com',
-//   clientId: 'PROFILE_BETA',
-//   clientSecret: '...',
-//   username: 'retailer_alpha_admin',
-//   password: '...',
-//   retailerId: '5',
-// }
-
-// Use with a custom client setup
-const client = new FluentClient(config, myLogger);
-```
-
----
-
-### listFluentProfiles(options?)
-
-Lists all valid CLI profiles found on disk. A directory is considered a valid profile if it contains a `profile.json` file. Hidden directories (e.g., `.sessions`) are skipped.
-
-```typescript
-function listFluentProfiles(options?: FluentProfileOptions): string[]
-```
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `options` | `FluentProfileOptions` | No | Only `profileDir` is relevant here |
-
-**Returns:** Alphabetically sorted array of profile names. Returns an empty array if the base directory does not exist or contains no valid profiles.
-
-**Example:**
-
-```typescript
-const profiles = listFluentProfiles();
-// ['PROFILE_BETA', 'PROFILE_ALPHA']
-
-// Custom directory
-const profiles = listFluentProfiles({ profileDir: '/opt/fluent/profiles' });
-```
-
----
-
-### getFluentProfileInfo(profileName, options?)
-
-Returns metadata about a profile without loading credentials. Useful for building profile selection UIs or diagnostic tools.
-
-```typescript
-function getFluentProfileInfo(
-  profileName: string,
-  options?: FluentProfileOptions
-): FluentProfileInfo | null
-```
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `profileName` | `string` | Yes | CLI profile name |
-| `options` | `FluentProfileOptions` | No | Only `profileDir` is relevant here |
-
-**Returns:** `FluentProfileInfo` object or `null` if the profile does not exist.
-
-**FluentProfileInfo shape:**
-
-```typescript
-interface FluentProfileInfo {
-  name: string;        // Profile name (directory name)
-  baseUrl: string;     // API base URL
-  accountId: string;   // Account/client ID
-  username: string;    // Default username reference
-  retailers: string[]; // Available retailer refs (from retailer.*.json files)
-}
-```
-
-**Example:**
-
-```typescript
-const info = getFluentProfileInfo('PROFILE_BETA');
-// {
-//   name: 'PROFILE_BETA',
-//   baseUrl: 'https://profile-beta.api.fluentcommerce.com',
-//   accountId: 'PROFILE_BETA',
-//   username: 'profile_beta_admin',
-//   retailers: ['RETAILER_ALPHA'],
-// }
-
-if (info && info.retailers.length > 0) {
-  console.log(`Profile has retailers: ${info.retailers.join(', ')}`);
-}
-```
-
----
-
-### resolveProfileBaseDir(options?)
-
-Returns the base directory where CLI profiles are stored. Useful for debugging or custom profile discovery logic.
-
-```typescript
-function resolveProfileBaseDir(options?: FluentProfileOptions): string
-```
-
-**Resolution order:**
-
-1. `options.profileDir` if provided.
-2. `FLUENT_PROFILE_DIR` environment variable if set.
-3. `~/.fluentcommerce/` (default).
-
-**Example:**
-
-```typescript
-const dir = resolveProfileBaseDir();
-// '/home/user/.fluentcommerce'
-
-const dir = resolveProfileBaseDir({ profileDir: '/opt/fluent/profiles' });
-// '/opt/fluent/profiles'
-```
-
-## FluentProfileOptions
-
-All profile-related functions accept a `FluentProfileOptions` object:
-
-```typescript
-interface FluentProfileOptions {
-  profileDir?: string;
-  retailer?: string;
-  timeout?: number;
-  retryConfig?: FluentClientConfig['retryConfig'];
-}
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `profileDir` | `string` | `~/.fluentcommerce/` | Override the base directory for profile discovery |
-| `retailer` | `string` | `undefined` | Retailer ref (e.g., `'RETAILER_ALPHA'`). Loads retailer-specific `retailerId` and user credentials |
-| `timeout` | `number` | `undefined` | Request timeout in milliseconds. Passed through to `FluentClientConfig` |
-| `retryConfig` | `object` | `undefined` | Retry configuration. Passed through to `FluentClientConfig` |
-
-`createClientFromProfile` additionally accepts:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `validateConnection` | `boolean` | `false` | Execute a test query immediately to verify authentication |
-| `logger` | `Logger` | `undefined` | Custom logger instance passed to the `FluentClient` constructor |
-
-## Profile Directory Resolution
-
-The SDK resolves the profile base directory in the following order:
-
-1. **Explicit option:** `options.profileDir` takes highest priority.
-2. **Environment variable:** `FLUENT_PROFILE_DIR`, useful for CI or non-standard installations.
-3. **Default path:** `~/.fluentcommerce/`, which is where the Fluent CLI stores profiles by default.
-
-```typescript
-// Use default (~/.fluentcommerce/)
-const client = await createClientFromProfile('MYPROFILE');
-
-// Use environment variable
-// export FLUENT_PROFILE_DIR=/opt/fluent/profiles
-const client = await createClientFromProfile('MYPROFILE');
-
-// Explicit override (takes priority over env var)
-const client = await createClientFromProfile('MYPROFILE', {
-  profileDir: '/opt/fluent/profiles',
-});
-```
-
-## Error Handling
-
-All profile functions throw descriptive errors with actionable messages. The error messages include the file path that was expected and, where possible, a list of available alternatives.
-
-| Condition | Error Message Pattern |
-|-----------|----------------------|
-| Profile name is empty or not a string | `Profile name is required` |
-| Profile directory does not exist | `Fluent CLI profile '<name>' not found at <path>. Available profiles: X, Y` |
-| `profile.json` missing | `profile.json not found in <dir>. This directory may not be a valid Fluent CLI profile.` |
-| Required field missing in `profile.json` | `Profile '<name>' is missing required field '<field>' in profile.json` |
-| Retailer file not found | `Retailer '<ref>' not found for profile '<name>' at <path>. Available retailers: X, Y` |
-| User credentials file missing | `User credentials file not found: <path>. Expected file for user '<user>' (set by retailer '<ref>').` |
-| User credentials missing fields | `User credentials file <path> is missing 'username' or 'password' field` |
-| JSON parse failure | `Failed to read <path>: <original error>` |
-
-**Example: Handling missing profiles gracefully**
-
-```typescript
-import { listFluentProfiles, createClientFromProfile } from '@fluentcommerce/fc-connect-sdk';
-
-const profiles = listFluentProfiles();
-if (profiles.length === 0) {
-  console.error('No Fluent CLI profiles found. Run: fluent profile create <NAME>');
-  process.exit(1);
-}
-
-try {
-  const client = await createClientFromProfile(profiles[0]);
-} catch (err) {
-  console.error('Failed to load profile:', err.message);
-  process.exit(1);
-}
-```
-
-## When NOT to Use CLI Profiles
-
-CLI profile integration is designed for local development and standalone scripts. It is **not** appropriate for every runtime context.
-
-| Context | Recommended Approach |
-|---------|---------------------|
-| **Versori platform** | Use `createClient({ fetch, log, activation })`. Versori manages auth via connections. |
-| **CI/CD pipelines** | Use environment variables (`FLUENT_CLIENT_ID`, `FLUENT_CLIENT_SECRET`, etc.) with `new FluentClient(config)`. |
-| **Docker containers** | Use environment variables or mounted secrets, not host filesystem profiles. |
-| **Local dev / standalone scripts** | Use `createClientFromProfile()`. This is its intended use case. |
-
-## Source Files
-
-- Implementation: `src/auth/profile-loader.ts`
-- Factory integration: `src/client-factory.ts` (lines 284-296)
-- Public exports: `src/index.ts`