@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/data-sources/modules/data-sources-08-api-reference.md

@@ -1,417 +1,417 @@
-# Module 8: API Reference
-
-**Level:** Reference
-**Category:** API Documentation
-
-## Overview
-
-Complete API reference for S3DataSource and SftpDataSource including all methods, configuration options, and TypeScript types.
-
-## Table of Contents
-
-- [S3DataSource API](#s3datasource-api)
-- [SftpDataSource API](#sftpdatasource-api)
-- [Configuration Interfaces](#configuration-interfaces)
-- [TypeScript Types](#typescript-types)
-- [Error Types](#error-types)
-
----
-
-## S3DataSource API
-
-### Constructor
-
-```typescript
-constructor(
-  config: DataSourceConfig,
-  log?: ILogger
-)
-```
-
-### Methods
-
-#### listFiles()
-
-```typescript
-async listFiles(options: {
-  keyPrefix?: string;
-  filePattern?: string;
-  maxKeys?: number;
-}): Promise<Array<{
-  key: string;
-  size: number;
-  lastModified: Date;
-}>>
-```
-
-**Example:**
-```typescript
-const files = await s3.listFiles({
-  keyPrefix: 'inventory/',
-  filePattern: '*.csv',
-  maxKeys: 100
-});
-```
-
-#### readFile()
-
-```typescript
-async readFile(key: string): Promise<string>
-```
-
-**Example:**
-```typescript
-const content = await s3.readFile('inventory/positions.csv');
-```
-
-#### readFileStream()
-
-```typescript
-async readFileStream(key: string): Promise<NodeJS.ReadableStream>
-```
-
-**Example:**
-```typescript
-const stream = await s3.readFileStream('large-file.csv');
-for await (const chunk of stream) {
-  console.log(chunk);
-}
-```
-
-#### writeFile()
-
-```typescript
-async writeFile(key: string, content: string | Buffer): Promise<void>
-```
-
-**Example:**
-```typescript
-await s3.writeFile('output/result.csv', csvContent);
-```
-
-#### deleteFile()
-
-```typescript
-async deleteFile(key: string): Promise<void>
-```
-
-**Example:**
-```typescript
-await s3.deleteFile('temp/old-file.csv');
-```
-
-#### moveFile()
-
-```typescript
-async moveFile(sourceKey: string, targetKey: string): Promise<void>
-```
-
-**Example:**
-```typescript
-await s3.moveFile(
-  'inventory/file.csv',
-  'inventory/archive/file.csv'
-);
-```
-
-#### dispose()
-
-```typescript
-async dispose(): Promise<void>
-```
-
-**Example:**
-```typescript
-await s3.dispose();  // Always call in finally block
-```
-
----
-
-## SftpDataSource API
-
-### Constructor
-
-```typescript
-constructor(
-  config: DataSourceConfig,
-  log?: ILogger
-)
-```
-
-### Methods
-
-#### listFiles()
-
-```typescript
-async listFiles(options: {
-  remotePath: string;
-  filePattern?: string;
-}): Promise<Array<{
-  filename: string;
-  size: number;
-  modifyTime: Date;
-  type: string;  // 'file' | 'directory' | 'link'
-}>>
-```
-
-**Example:**
-```typescript
-const files = await sftp.listFiles({
-  remotePath: '/inbound/inventory',
-  filePattern: '*.xml'
-});
-```
-
-#### readFile()
-
-```typescript
-async readFile(options: {
-  remotePath: string;
-  filename: string;
-  encoding?: string;
-}): Promise<string>
-```
-
-**Example:**
-```typescript
-const content = await sftp.readFile({
-  remotePath: '/inbound',
-  filename: 'inventory.csv',
-  encoding: 'utf8'
-});
-```
-
-#### uploadFile()
-
-```typescript
-async uploadFile(
-  encoding: string,
-  content: Buffer,
-  destinationPath: string
-): Promise<void>
-```
-
-**Example:**
-```typescript
-import { Buffer } from 'node:buffer';
-
-await sftp.uploadFile(
-  'utf8',
-  Buffer.from(csvContent),
-  '/outbound/positions.csv'
-);
-```
-
-#### deleteFile()
-
-```typescript
-async deleteFile(options: {
-  remotePath: string;
-  filename: string;
-}): Promise<void>
-```
-
-**Example:**
-```typescript
-await sftp.deleteFile({
-  remotePath: '/temp',
-  filename: 'old-file.csv'
-});
-```
-
-#### moveFile()
-
-```typescript
-async moveFile(options: {
-  oldPath: string;
-  newPath: string;
-}): Promise<void>
-```
-
-**Example:**
-```typescript
-await sftp.moveFile({
-  oldPath: '/inbound/file.csv',
-  newPath: '/archive/file.csv'
-});
-```
-
-#### dispose()
-
-```typescript
-async dispose(): Promise<void>
-```
-
-**Example:**
-```typescript
-await sftp.dispose();  // Close connection pool
-```
-
----
-
-## Configuration Interfaces
-
-### DataSourceConfig
-
-```typescript
-interface DataSourceConfig {
-  type: 'S3_CSV' | 'S3_JSON' | 'S3_XML' | 'S3_PARQUET' |
-        'SFTP_CSV' | 'SFTP_JSON' | 'SFTP_XML';
-  connectionId?: string;
-  name?: string;
-  settings: S3Settings | SftpSettings;
-}
-```
-
-### S3Settings
-
-```typescript
-interface S3Settings {
-  // Authentication
-  accessKeyId?: string;
-  secretAccessKey?: string;
-  sessionToken?: string;
-
-  // Configuration
-  region: string;
-  bucket: string;
-
-  // Optional
-  endpoint?: string;
-  forcePathStyle?: boolean;
-  signatureVersion?: string;
-  requestTimeout?: number;
-}
-```
-
-### SftpSettings
-
-```typescript
-interface SftpSettings {
-  // Connection
-  host: string;
-  port?: number;  // Default: 22
-
-  // Authentication
-  username: string;
-  password?: string;
-  privateKey?: string;
-  passphrase?: string;
-
-  // Connection Pool
-  maxConnections?: number;  // Default: 5
-  connectionTimeout?: number;  // Default: 30000 (30s)
-  keepAliveInterval?: number;  // Default: 10000 (10s)
-
-  // File Operations
-  remotePath?: string;
-  filePattern?: string;
-
-  // Retry Configuration
-  retry?: {
-    maxRetries?: number;
-    initialDelayMs?: number;
-    maxDelayMs?: number;
-    backoffMultiplier?: number;
-  };
-}
-```
-
----
-
-## TypeScript Types
-
-### FileInfo
-
-```typescript
-interface S3FileInfo {
-  key: string;
-  size: number;
-  lastModified: Date;
-}
-
-interface SftpFileInfo {
-  filename: string;
-  size: number;
-  modifyTime: Date;
-  type: 'file' | 'directory' | 'link';
-}
-```
-
-### ListOptions
-
-```typescript
-interface S3ListOptions {
-  keyPrefix?: string;
-  filePattern?: string;
-  maxKeys?: number;
-}
-
-interface SftpListOptions {
-  remotePath: string;
-  filePattern?: string;
-}
-```
-
-### ReadOptions
-
-```typescript
-interface SftpReadOptions {
-  remotePath: string;
-  filename: string;
-  encoding?: string;  // Default: 'utf8'
-}
-```
-
----
-
-## Error Types
-
-### S3 Errors
-
-```typescript
-class S3Error extends Error {
-  statusCode: number;
-  code: string;  // 'NoSuchBucket', 'AccessDenied', etc.
-  requestId: string;
-}
-```
-
-**Common S3 Errors:**
-- `NoSuchBucket` - Bucket doesn't exist
-- `NoSuchKey` - File not found
-- `AccessDenied` - Permission denied
-- `InvalidBucketName` - Invalid bucket name
-
-### SFTP Errors
-
-```typescript
-class SftpError extends Error {
-  code: string;  // 'ECONNREFUSED', 'ENOTFOUND', etc.
-}
-```
-
-**Common SFTP Errors:**
-- `ECONNREFUSED` - Connection refused
-- `ENOTFOUND` - Host not found
-- `ETIMEDOUT` - Connection timeout
-- `Permission denied` - Access denied
-
----
-
-## See Also
-
-**Related Modules:**
-- [Module 01: Foundations](./data-sources-01-foundations.md) - Concepts
-- [Module 02: S3 Operations](./data-sources-02-s3-operations.md) - S3 usage
-- [Module 03: SFTP Operations](./data-sources-03-sftp-operations.md) - SFTP usage
-
-**TypeScript Documentation:**
-- [Source Code](../../../../src/data-sources/) - Implementation
-
----
-
-**Navigation:**
-- [Back to Module List](./readme.md)
-- [Previous: Module 07 - Troubleshooting](./data-sources-07-troubleshooting.md)
-- [Back to Data Sources Guide](../data-sources-readme.md)
+# Module 8: API Reference
+
+**Level:** Reference
+**Category:** API Documentation
+
+## Overview
+
+Complete API reference for S3DataSource and SftpDataSource including all methods, configuration options, and TypeScript types.
+
+## Table of Contents
+
+- [S3DataSource API](#s3datasource-api)
+- [SftpDataSource API](#sftpdatasource-api)
+- [Configuration Interfaces](#configuration-interfaces)
+- [TypeScript Types](#typescript-types)
+- [Error Types](#error-types)
+
+---
+
+## S3DataSource API
+
+### Constructor
+
+```typescript
+constructor(
+  config: DataSourceConfig,
+  log?: ILogger
+)
+```
+
+### Methods
+
+#### listFiles()
+
+```typescript
+async listFiles(options: {
+  keyPrefix?: string;
+  filePattern?: string;
+  maxKeys?: number;
+}): Promise<Array<{
+  key: string;
+  size: number;
+  lastModified: Date;
+}>>
+```
+
+**Example:**
+```typescript
+const files = await s3.listFiles({
+  keyPrefix: 'inventory/',
+  filePattern: '*.csv',
+  maxKeys: 100
+});
+```
+
+#### readFile()
+
+```typescript
+async readFile(key: string): Promise<string>
+```
+
+**Example:**
+```typescript
+const content = await s3.readFile('inventory/positions.csv');
+```
+
+#### readFileStream()
+
+```typescript
+async readFileStream(key: string): Promise<NodeJS.ReadableStream>
+```
+
+**Example:**
+```typescript
+const stream = await s3.readFileStream('large-file.csv');
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+#### writeFile()
+
+```typescript
+async writeFile(key: string, content: string | Buffer): Promise<void>
+```
+
+**Example:**
+```typescript
+await s3.writeFile('output/result.csv', csvContent);
+```
+
+#### deleteFile()
+
+```typescript
+async deleteFile(key: string): Promise<void>
+```
+
+**Example:**
+```typescript
+await s3.deleteFile('temp/old-file.csv');
+```
+
+#### moveFile()
+
+```typescript
+async moveFile(sourceKey: string, targetKey: string): Promise<void>
+```
+
+**Example:**
+```typescript
+await s3.moveFile(
+  'inventory/file.csv',
+  'inventory/archive/file.csv'
+);
+```
+
+#### dispose()
+
+```typescript
+async dispose(): Promise<void>
+```
+
+**Example:**
+```typescript
+await s3.dispose();  // Always call in finally block
+```
+
+---
+
+## SftpDataSource API
+
+### Constructor
+
+```typescript
+constructor(
+  config: DataSourceConfig,
+  log?: ILogger
+)
+```
+
+### Methods
+
+#### listFiles()
+
+```typescript
+async listFiles(options: {
+  remotePath: string;
+  filePattern?: string;
+}): Promise<Array<{
+  filename: string;
+  size: number;
+  modifyTime: Date;
+  type: string;  // 'file' | 'directory' | 'link'
+}>>
+```
+
+**Example:**
+```typescript
+const files = await sftp.listFiles({
+  remotePath: '/inbound/inventory',
+  filePattern: '*.xml'
+});
+```
+
+#### readFile()
+
+```typescript
+async readFile(options: {
+  remotePath: string;
+  filename: string;
+  encoding?: string;
+}): Promise<string>
+```
+
+**Example:**
+```typescript
+const content = await sftp.readFile({
+  remotePath: '/inbound',
+  filename: 'inventory.csv',
+  encoding: 'utf8'
+});
+```
+
+#### uploadFile()
+
+```typescript
+async uploadFile(
+  encoding: string,
+  content: Buffer,
+  destinationPath: string
+): Promise<void>
+```
+
+**Example:**
+```typescript
+import { Buffer } from 'node:buffer';
+
+await sftp.uploadFile(
+  'utf8',
+  Buffer.from(csvContent),
+  '/outbound/positions.csv'
+);
+```
+
+#### deleteFile()
+
+```typescript
+async deleteFile(options: {
+  remotePath: string;
+  filename: string;
+}): Promise<void>
+```
+
+**Example:**
+```typescript
+await sftp.deleteFile({
+  remotePath: '/temp',
+  filename: 'old-file.csv'
+});
+```
+
+#### moveFile()
+
+```typescript
+async moveFile(options: {
+  oldPath: string;
+  newPath: string;
+}): Promise<void>
+```
+
+**Example:**
+```typescript
+await sftp.moveFile({
+  oldPath: '/inbound/file.csv',
+  newPath: '/archive/file.csv'
+});
+```
+
+#### dispose()
+
+```typescript
+async dispose(): Promise<void>
+```
+
+**Example:**
+```typescript
+await sftp.dispose();  // Close connection pool
+```
+
+---
+
+## Configuration Interfaces
+
+### DataSourceConfig
+
+```typescript
+interface DataSourceConfig {
+  type: 'S3_CSV' | 'S3_JSON' | 'S3_XML' | 'S3_PARQUET' |
+        'SFTP_CSV' | 'SFTP_JSON' | 'SFTP_XML';
+  connectionId?: string;
+  name?: string;
+  settings: S3Settings | SftpSettings;
+}
+```
+
+### S3Settings
+
+```typescript
+interface S3Settings {
+  // Authentication
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  sessionToken?: string;
+
+  // Configuration
+  region: string;
+  bucket: string;
+
+  // Optional
+  endpoint?: string;
+  forcePathStyle?: boolean;
+  signatureVersion?: string;
+  requestTimeout?: number;
+}
+```
+
+### SftpSettings
+
+```typescript
+interface SftpSettings {
+  // Connection
+  host: string;
+  port?: number;  // Default: 22
+
+  // Authentication
+  username: string;
+  password?: string;
+  privateKey?: string;
+  passphrase?: string;
+
+  // Connection Pool
+  maxConnections?: number;  // Default: 5
+  connectionTimeout?: number;  // Default: 30000 (30s)
+  keepAliveInterval?: number;  // Default: 10000 (10s)
+
+  // File Operations
+  remotePath?: string;
+  filePattern?: string;
+
+  // Retry Configuration
+  retry?: {
+    maxRetries?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffMultiplier?: number;
+  };
+}
+```
+
+---
+
+## TypeScript Types
+
+### FileInfo
+
+```typescript
+interface S3FileInfo {
+  key: string;
+  size: number;
+  lastModified: Date;
+}
+
+interface SftpFileInfo {
+  filename: string;
+  size: number;
+  modifyTime: Date;
+  type: 'file' | 'directory' | 'link';
+}
+```
+
+### ListOptions
+
+```typescript
+interface S3ListOptions {
+  keyPrefix?: string;
+  filePattern?: string;
+  maxKeys?: number;
+}
+
+interface SftpListOptions {
+  remotePath: string;
+  filePattern?: string;
+}
+```
+
+### ReadOptions
+
+```typescript
+interface SftpReadOptions {
+  remotePath: string;
+  filename: string;
+  encoding?: string;  // Default: 'utf8'
+}
+```
+
+---
+
+## Error Types
+
+### S3 Errors
+
+```typescript
+class S3Error extends Error {
+  statusCode: number;
+  code: string;  // 'NoSuchBucket', 'AccessDenied', etc.
+  requestId: string;
+}
+```
+
+**Common S3 Errors:**
+- `NoSuchBucket` - Bucket doesn't exist
+- `NoSuchKey` - File not found
+- `AccessDenied` - Permission denied
+- `InvalidBucketName` - Invalid bucket name
+
+### SFTP Errors
+
+```typescript
+class SftpError extends Error {
+  code: string;  // 'ECONNREFUSED', 'ENOTFOUND', etc.
+}
+```
+
+**Common SFTP Errors:**
+- `ECONNREFUSED` - Connection refused
+- `ENOTFOUND` - Host not found
+- `ETIMEDOUT` - Connection timeout
+- `Permission denied` - Access denied
+
+---
+
+## See Also
+
+**Related Modules:**
+- [Module 01: Foundations](./data-sources-01-foundations.md) - Concepts
+- [Module 02: S3 Operations](./data-sources-02-s3-operations.md) - S3 usage
+- [Module 03: SFTP Operations](./data-sources-03-sftp-operations.md) - SFTP usage
+
+**TypeScript Documentation:**
+- [Source Code](../../../../src/data-sources/) - Implementation
+
+---
+
+**Navigation:**
+- [Back to Module List](./readme.md)
+- [Previous: Module 07 - Troubleshooting](./data-sources-07-troubleshooting.md)
+- [Back to Data Sources Guide](../data-sources-readme.md)