@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

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

@@ -1,597 +1,545 @@
-# Module 08: Types
-
-**Level:** Reference
-**Category:** TypeScript Definitions
-
-## Overview
-
-Complete TypeScript type definitions for the Fluent Commerce Connect SDK. This reference documents all interfaces, enums, and type aliases used throughout the SDK for type-safe development.
-
-## Table of Contents
-
-- [Core Response Types](#core-response-types)
-- [Enums](#enums)
-  - [BatchAction](#batchaction)
-  - [EntityType](#entitytype)
-  - [JobStatus](#jobstatus)
-  - [IngestionErrorCode](#ingestionerrorcode)
-  - [CsvDelimiter](#csvdelimiter)
-  - [FileEncoding](#fileencoding)
-  - [JobStrategy](#jobstrategy)
-- [Configuration Interfaces](#configuration-interfaces)
-  - [FieldMapping](#fieldmapping)
-  - [TransformationConfig](#transformationconfig)
-  - [KVStoreAdapter](#kvstoreadapter)
-  - [Lock](#lock)
-- [File & Data Interfaces](#file-data-interfaces)
-  - [FileMetadata](#filemetadata)
-  - [SftpConnection](#sftpconnection)
-  - [CsvRecord](#csvrecord)
-  - [ConnectionInfo](#connectioninfo)
-  - [ParquetDataRecord](#parquetdatarecord)
-- [See Also](#see-also)
-
----
-
-## Core Response Types
-
-### GraphQLResponse
-
-Response from GraphQL API operations.
-
-```typescript
-interface GraphQLResponse<T = JsonValue> {
-  data?: T;
-  errors?: Array<{
-    message: string;
-    locations?: Array<{ line: number; column: number }>;
-    path?: Array<string | number>;
-    extensions?: Record<string, JsonValue>;
-  }>;
-  extensions?: Record<string, unknown> & {
-    autoPagination?: {
-      totalPages: number;
-      totalRecords: number;
-      truncated: boolean;
-      truncationReason?: 'maxPages' | 'maxRecords' | 'timeout';
-    };
-  };
-}
-```
-
-**Usage:**
-
-```typescript
-const result = await client.graphql({
-  query: inventoryQuery,
-  variables: { first: 100 },
-});
-
-if (result.errors) {
-  result.errors.forEach(error => {
-    console.error(`GraphQL Error: ${error.message}`);
-    console.error(`Path: ${error.path?.join('.')}`);
-  });
-} else {
-  console.log('Data:', result.data);
-}
-```
-
-### FluentEventQueryParams
-
-Query params for Event Log/Audit search (`GET /api/v4.1/event`).
-
-```typescript
-interface FluentEventQueryParams {
-  start?: number;
-  count?: number;
-  from?: string;
-  to?: string;
-  name?: string;
-  category?: string;
-  retailerId?: string | number;
-  eventType?: string;
-  eventStatus?: string;
-  'context.rootEntityType'?: string;
-  'context.rootEntityId'?: string | number;
-  'context.rootEntityRef'?: string;
-  'context.entityType'?: string;
-  'context.entityId'?: string | number;
-  'context.entityRef'?: string;
-}
-```
-
-### FluentEventLogResponse
-
-Response from Event Log search (`client.getEvents()`).
-
-```typescript
-interface FluentEventLogResponse {
-  start: number;
-  count: number;
-  hasMore: boolean;
-  results: FluentEventLogItem[];
-}
-
-interface FluentEventLogItem {
-  id: string;
-  name: string;
-  type?: string;
-  accountId?: string;
-  retailerId?: string;
-  category?: string;
-  context?: FluentEventLogContext;
-  eventStatus?: string;
-  attributes?: FluentEventLogAttribute[] | Record<string, AttributeValue> | null;
-  source?: string | null;
-  generatedBy?: string;
-  generatedOn?: string;
-}
-```
-
-## Enums
-
-### BatchAction
-
-Action types for batch API operations.
-
-**Note**: Only UPSERT is currently supported by the Fluent Commerce Batch API.
-
-```typescript
-enum BatchAction {
-  UPSERT = 'UPSERT',
-}
-```
-
-**Usage:**
-
-```typescript
-import { BatchAction } from '@fluentcommerce/fc-connect-sdk';
-
-const batch = {
-  action: BatchAction.UPSERT,
-  entities: inventoryRecords,
-};
-```
-
-### EntityType
-
-Supported Fluent Commerce entity types.
-
-```typescript
-enum EntityType {
-  INVENTORY = 'INVENTORY',
-  PRODUCT = 'PRODUCT',
-  ORDER = 'ORDER',
-  CUSTOMER = 'CUSTOMER',
-  LOCATION = 'LOCATION',
-  FULFILLMENT = 'FULFILLMENT',
-}
-```
-
-**Usage:**
-
-```typescript
-import { EntityType } from '@fluentcommerce/fc-connect-sdk';
-
-const job = await client.createJob({
-  name: 'inventory-update',
-  entityType: EntityType.INVENTORY,
-  retailerId: '1',
-});
-```
-
-### JobStatus
-
-In the SDK types, job status is represented on `FluentJobStatus` as a string field `status: string` (no exported enum). Example usage:
-
-```typescript
-import { FluentJobStatus } from '@fluentcommerce/fc-connect-sdk';
-
-const status: FluentJobStatus = await client.getJobStatus(jobId);
-if (status.status === 'COMPLETED') {
-  // handle success
-}
-```
-
-### IngestionErrorCode
-
-SDK error classification codes.
-
-```typescript
-enum IngestionErrorCode {
-  VALIDATION_ERROR = 'VALIDATION_ERROR',
-  AUTHENTICATION_ERROR = 'AUTHENTICATION_ERROR',
-  AUTHORIZATION_ERROR = 'AUTHORIZATION_ERROR',
-  RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',
-  NETWORK_ERROR = 'NETWORK_ERROR',
-  JOB_EXPIRED = 'JOB_EXPIRED',
-  BATCH_FAILED = 'BATCH_FAILED',
-  PARSE_ERROR = 'PARSE_ERROR',
-  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
-}
-```
-
-**Usage:**
-
-```typescript
-import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
-
-try {
-  await client.sendBatch(jobId, data);
-} catch (error) {
-  if (error instanceof IngestionError) {
-    if (error.code === IngestionErrorCode.JOB_EXPIRED) {
-      // Create new job and retry
-    }
-  }
-}
-```
-
-### CsvDelimiter
-
-Common CSV delimiter characters.
-
-```typescript
-enum CsvDelimiter {
-  COMMA = ',',
-  SEMICOLON = ';',
-  TAB = '\t',
-  PIPE = '|',
-}
-```
-
-**Usage:**
-
-```typescript
-import { CsvDelimiter, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const parser = new CSVParserService();
-// Options go to parse() method, not constructor
-const records = await parser.parse(csvContent, {
-  delimiter: CsvDelimiter.PIPE,
-  columns: true, // headers: true becomes columns: true
-});
-```
-
-### FileEncoding
-
-Supported file encodings.
-
-```typescript
-enum FileEncoding {
-  UTF8 = 'utf8',
-  UTF16 = 'utf16le',
-  ASCII = 'ascii',
-  LATIN1 = 'latin1',
-}
-```
-
-**Usage:**
-
-```typescript
-import { FileEncoding } from '@fluentcommerce/fc-connect-sdk';
-
-const content = await s3.downloadFile('file.csv', {
-  encoding: FileEncoding.UTF8,
-});
-```
-
-### JobStrategy
-
-Batch job creation strategies.
-
-```typescript
-enum JobStrategy {
-  PER_FILE = 'PER_FILE',
-  DAILY = 'DAILY',
-  BATCHES_PER_JOB = 'BATCHES_PER_JOB',
-}
-```
-
-**Usage:**
-
-```typescript
-import { JobStrategy } from '@fluentcommerce/fc-connect-sdk';
-
-const result = await orchestrator.ingest({
-  jobStrategy: JobStrategy.DAILY,
-  batchSize: 500,
-});
-```
-
-## Configuration Interfaces
-
-### FieldMapping
-
-Map source fields to target fields with transformations.
-
-```typescript
-interface FieldMapping {
-  source: string; // Source field name
-  target: string; // Target field name
-  transform?: string | TransformFunction; // Transformation
-  defaultValue?: any; // Default if missing
-  required?: boolean; // Required field. See mapping documentation for validation timing with resolvers.
-}
-```
-
-**Usage:**
-
-```typescript
-const mapping: FieldMapping = {
-  source: 'sku_id',
-  target: 'skuRef',
-  required: true,
-};
-
-const mappings: FieldMapping[] = [
-  {
-    source: 'quantity',
-    target: 'qty',
-    transform: 'sdk.parseInt',
-    defaultValue: 0,
-  },
-  {
-    source: 'expiry_date',
-    target: 'expectedOn',
-    transform: 'sdk.formatDate',
-  },
-];
-```
-
-### TransformationConfig
-
-Configuration for data transformation operations.
-
-```typescript
-interface TransformationConfig {
-  mappings: FieldMapping[];
-  defaultValues?: Record<string, any>;
-  validations?: ValidationRule[];
-  errorHandler?: ErrorHandler;
-}
-```
-
-**Usage:**
-
-```typescript
-const config: TransformationConfig = {
-  mappings: [
-    { source: 'sku', target: 'productRef', required: true },
-    { source: 'qty', target: 'quantity', transform: 'sdk.parseInt' },
-  ],
-  defaultValues: {
-    status: 'AVAILABLE',
-    type: 'REGULAR',
-  },
-  validations: [
-    {
-      field: 'quantity',
-      rule: value => value > 0,
-      message: 'Quantity must be positive',
-    },
-  ],
-};
-```
-
-### KVStoreAdapter
-
-Key-value storage interface for state management.
-
-```typescript
-interface KVStoreAdapter {
-  get(key: string): Promise<any>;
-  set(key: string, value: any, ttl?: number): Promise<void>;
-  delete(key: string): Promise<void>;
-  exists(key: string): Promise<boolean>;
-  list(prefix?: string): Promise<string[]>;
-}
-```
-
-**Usage:**
-
-```typescript
-import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-const kv: KVStoreAdapter = new VersoriKVAdapter(openKv());
-
-// Store value
-await kv.set('processed:file123', { timestamp: Date.now() }, 3600);
-
-// Retrieve value
-const value = await kv.get('processed:file123');
-
-// Check existence
-if (await kv.exists('processed:file123')) {
-  console.log('File already processed');
-}
-
-// List keys with prefix
-const keys = await kv.list('processed:');
-```
-
-### Lock
-
-Distributed lock interface for concurrency control.
-
-```typescript
-interface Lock {
-  acquired: boolean;
-  key: string;
-  expiresAt: Date;
-  token: string;
-}
-```
-
-**Usage:**
-
-```typescript
-const lock = await lockService.acquire('inventory-import', 300);
-
-if (lock.acquired) {
-  try {
-    // Perform exclusive operation
-    await processInventory();
-  } finally {
-    await lockService.release(lock);
-  }
-}
-```
-
-## File & Data Interfaces
-
-### FileMetadata
-
-Metadata for files from S3 or SFTP data sources.
-
-```typescript
-interface FileMetadata {
-  path: string; // Full file path
-  name: string; // File name only
-  size?: number; // File size in bytes
-  lastModified?: string; // ISO timestamp
-  contentType?: string; // MIME type
-  source: 'S3' | 'SFTP'; // Data source type
-  etag?: string; // S3 ETag (S3 only)
-  bucket?: string; // S3 bucket (S3 only)
-  region?: string; // S3 region (S3 only)
-}
-```
-
-**Usage:**
-
-```typescript
-const files: FileMetadata[] = await s3.listFiles({
-  prefix: 'inventory/',
-});
-
-for (const file of files) {
-  console.log(`File: ${file.name}`);
-  console.log(`Size: ${file.size} bytes`);
-  console.log(`Modified: ${file.lastModified}`);
-  console.log(`Source: ${file.source}`);
-
-  if (file.source === 'S3') {
-    console.log(`Bucket: ${file.bucket}`);
-    console.log(`ETag: ${file.etag}`);
-  }
-}
-```
-
-### SftpConnection
-
-SFTP connection configuration (used for Versori platform integration).
-
-```typescript
-interface SftpConnection {
-  id: string;
-  name: string;
-  host: string;
-  port?: number;
-  username: string;
-  // Authentication handled by Versori platform
-}
-```
-
-**Usage:**
-
-```typescript
-const sftpConfig: SftpDataSourceConfig = {
-  type: 'SFTP_CSV',
-  connection: {
-    id: 'sftp-prod',
-    name: 'Production SFTP',
-    host: 'sftp.example.com',
-    port: 22,
-    username: 'user',
-  },
-  settings: {
-    remotePath: '/data',
-    filePattern: '*.csv',
-  },
-};
-```
-
-### CsvRecord
-
-A single CSV record as a key-value object.
-
-```typescript
-interface CsvRecord {
-  [key: string]: string | number | boolean;
-}
-```
-
-**Usage:**
-
-```typescript
-const records: CsvRecord[] = await csvParser.parse(buffer);
-
-for (const record of records) {
-  console.log(`SKU: ${record.sku}`);
-  console.log(`Quantity: ${record.quantity}`);
-  console.log(`Price: ${record.price}`);
-}
-```
-
-### ConnectionInfo
-
-SFTP connection debugging information.
-
-```typescript
-interface ConnectionInfo {
-  type: string; // Data source type
-  host: string; // SFTP host
-  port: number; // SFTP port
-  remotePath: string; // Remote directory path
-  filePattern: string; // File matching pattern
-  connectionPoolSize: number; // Current pool size
-  maxPoolSize: number; // Maximum pool size
-}
-```
-
-**Usage:**
-
-```typescript
-const info: ConnectionInfo = sftp.getConnectionInfo();
-
-console.log(`Connected to: ${info.host}:${info.port}`);
-console.log(`Remote path: ${info.remotePath}`);
-console.log(`Pattern: ${info.filePattern}`);
-console.log(`Pool: ${info.connectionPoolSize}/${info.maxPoolSize}`);
-```
-
-### ParquetDataRecord
-
-A single Parquet record.
-
-```typescript
-interface ParquetDataRecord {
-  [key: string]: string | number | boolean | Date | null | undefined;
-}
-```
-
-**Usage:**
-
-```typescript
-const { records } = await parquetParser.parse(arrayBuffer, 'data.parquet');
-
-for (const record of records as ParquetDataRecord[]) {
-  console.log(`Product: ${record.productRef}`);
-  console.log(`Quantity: ${record.qty}`);
-  console.log(`Updated: ${record.updatedAt}`);
-}
-```
-
-## See Also
-
-- [Module 01: Client](./api-reference-01-client-api.md) - Client initialization with configs
-- [Module 01: Client - Batch API](./api-reference-01-client-api.md#job-batch-operations) - Using batch types
-- [Module 05: Services](./api-reference-05-services.md#universal-mapper) - FieldMapping usage
-- [Module 06: Data Sources](./api-reference-06-data-sources.md) - FileMetadata usage
-- [Module 09: Error Handling](./api-reference-09-error-handling.md) - Error types
-
----
-
-**[← Previous: Module 07 - Parsers](./api-reference-07-parsers.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Module 09 - Error Handling →](./api-reference-09-error-handling.md)**
+# Module 08: Types
+
+**Level:** Reference
+**Category:** TypeScript Definitions
+
+## Overview
+
+Complete TypeScript type definitions for the Fluent Commerce Connect SDK. This reference documents all interfaces, enums, and type aliases used throughout the SDK for type-safe development.
+
+## Table of Contents
+
+- [Core Response Types](#core-response-types)
+- [Enums](#enums)
+  - [BatchAction](#batchaction)
+  - [EntityType](#entitytype)
+  - [JobStatus](#jobstatus)
+  - [IngestionErrorCode](#ingestionerrorcode)
+  - [CsvDelimiter](#csvdelimiter)
+  - [FileEncoding](#fileencoding)
+  - [JobStrategy](#jobstrategy)
+- [Configuration Interfaces](#configuration-interfaces)
+  - [FieldMapping](#fieldmapping)
+  - [TransformationConfig](#transformationconfig)
+  - [KVStoreAdapter](#kvstoreadapter)
+  - [Lock](#lock)
+- [File & Data Interfaces](#file-data-interfaces)
+  - [FileMetadata](#filemetadata)
+  - [SftpConnection](#sftpconnection)
+  - [CsvRecord](#csvrecord)
+  - [ConnectionInfo](#connectioninfo)
+  - [ParquetDataRecord](#parquetdatarecord)
+- [See Also](#see-also)
+
+---
+
+## Core Response Types
+
+### GraphQLResponse
+
+Response from GraphQL API operations.
+
+```typescript
+interface GraphQLResponse<T = JsonValue> {
+  data?: T;
+  errors?: Array<{
+    message: string;
+    locations?: Array<{ line: number; column: number }>;
+    path?: Array<string | number>;
+    extensions?: Record<string, JsonValue>;
+  }>;
+  extensions?: Record<string, unknown> & {
+    autoPagination?: {
+      totalPages: number;
+      totalRecords: number;
+      truncated: boolean;
+      truncationReason?: 'maxPages' | 'maxRecords' | 'timeout';
+    };
+  };
+}
+```
+
+**Usage:**
+
+```typescript
+const result = await client.graphql({
+  query: inventoryQuery,
+  variables: { first: 100 },
+});
+
+if (result.errors) {
+  result.errors.forEach(error => {
+    console.error(`GraphQL Error: ${error.message}`);
+    console.error(`Path: ${error.path?.join('.')}`);
+  });
+} else {
+  console.log('Data:', result.data);
+}
+```
+
+## Enums
+
+### BatchAction
+
+Action types for batch API operations.
+
+**Note**: Only UPSERT is currently supported by the Fluent Commerce Batch API.
+
+```typescript
+enum BatchAction {
+  UPSERT = 'UPSERT',
+}
+```
+
+**Usage:**
+
+```typescript
+import { BatchAction } from '@fluentcommerce/fc-connect-sdk';
+
+const batch = {
+  action: BatchAction.UPSERT,
+  entities: inventoryRecords,
+};
+```
+
+### EntityType
+
+Supported Fluent Commerce entity types.
+
+```typescript
+enum EntityType {
+  INVENTORY = 'INVENTORY',
+  PRODUCT = 'PRODUCT',
+  ORDER = 'ORDER',
+  CUSTOMER = 'CUSTOMER',
+  LOCATION = 'LOCATION',
+  FULFILLMENT = 'FULFILLMENT',
+}
+```
+
+**Usage:**
+
+```typescript
+import { EntityType } from '@fluentcommerce/fc-connect-sdk';
+
+const job = await client.createJob({
+  name: 'inventory-update',
+  entityType: EntityType.INVENTORY,
+  retailerId: '1',
+});
+```
+
+### JobStatus
+
+In the SDK types, job status is represented on `FluentJobStatus` as a string field `status: string` (no exported enum). Example usage:
+
+```typescript
+import { FluentJobStatus } from '@fluentcommerce/fc-connect-sdk';
+
+const status: FluentJobStatus = await client.getJobStatus(jobId);
+if (status.status === 'COMPLETED') {
+  // handle success
+}
+```
+
+### IngestionErrorCode
+
+SDK error classification codes.
+
+```typescript
+enum IngestionErrorCode {
+  VALIDATION_ERROR = 'VALIDATION_ERROR',
+  AUTHENTICATION_ERROR = 'AUTHENTICATION_ERROR',
+  AUTHORIZATION_ERROR = 'AUTHORIZATION_ERROR',
+  RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',
+  NETWORK_ERROR = 'NETWORK_ERROR',
+  JOB_EXPIRED = 'JOB_EXPIRED',
+  BATCH_FAILED = 'BATCH_FAILED',
+  PARSE_ERROR = 'PARSE_ERROR',
+  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
+}
+```
+
+**Usage:**
+
+```typescript
+import { IngestionError, IngestionErrorCode } from '@fluentcommerce/fc-connect-sdk';
+
+try {
+  await client.sendBatch(jobId, data);
+} catch (error) {
+  if (error instanceof IngestionError) {
+    if (error.code === IngestionErrorCode.JOB_EXPIRED) {
+      // Create new job and retry
+    }
+  }
+}
+```
+
+### CsvDelimiter
+
+Common CSV delimiter characters.
+
+```typescript
+enum CsvDelimiter {
+  COMMA = ',',
+  SEMICOLON = ';',
+  TAB = '\t',
+  PIPE = '|',
+}
+```
+
+**Usage:**
+
+```typescript
+import { CsvDelimiter, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const parser = new CSVParserService();
+// Options go to parse() method, not constructor
+const records = await parser.parse(csvContent, {
+  delimiter: CsvDelimiter.PIPE,
+  columns: true, // headers: true becomes columns: true
+});
+```
+
+### FileEncoding
+
+Supported file encodings.
+
+```typescript
+enum FileEncoding {
+  UTF8 = 'utf8',
+  UTF16 = 'utf16le',
+  ASCII = 'ascii',
+  LATIN1 = 'latin1',
+}
+```
+
+**Usage:**
+
+```typescript
+import { FileEncoding } from '@fluentcommerce/fc-connect-sdk';
+
+const content = await s3.downloadFile('file.csv', {
+  encoding: FileEncoding.UTF8,
+});
+```
+
+### JobStrategy
+
+Batch job creation strategies.
+
+```typescript
+enum JobStrategy {
+  PER_FILE = 'PER_FILE',
+  DAILY = 'DAILY',
+  BATCHES_PER_JOB = 'BATCHES_PER_JOB',
+}
+```
+
+**Usage:**
+
+```typescript
+import { JobStrategy } from '@fluentcommerce/fc-connect-sdk';
+
+const result = await orchestrator.ingest({
+  jobStrategy: JobStrategy.DAILY,
+  batchSize: 500,
+});
+```
+
+## Configuration Interfaces
+
+### FieldMapping
+
+Map source fields to target fields with transformations.
+
+```typescript
+interface FieldMapping {
+  source: string; // Source field name
+  target: string; // Target field name
+  transform?: string | TransformFunction; // Transformation
+  defaultValue?: any; // Default if missing
+  required?: boolean; // Required field. See mapping documentation for validation timing with resolvers.
+}
+```
+
+**Usage:**
+
+```typescript
+const mapping: FieldMapping = {
+  source: 'sku_id',
+  target: 'skuRef',
+  required: true,
+};
+
+const mappings: FieldMapping[] = [
+  {
+    source: 'quantity',
+    target: 'qty',
+    transform: 'sdk.parseInt',
+    defaultValue: 0,
+  },
+  {
+    source: 'expiry_date',
+    target: 'expectedOn',
+    transform: 'sdk.formatDate',
+  },
+];
+```
+
+### TransformationConfig
+
+Configuration for data transformation operations.
+
+```typescript
+interface TransformationConfig {
+  mappings: FieldMapping[];
+  defaultValues?: Record<string, any>;
+  validations?: ValidationRule[];
+  errorHandler?: ErrorHandler;
+}
+```
+
+**Usage:**
+
+```typescript
+const config: TransformationConfig = {
+  mappings: [
+    { source: 'sku', target: 'productRef', required: true },
+    { source: 'qty', target: 'quantity', transform: 'sdk.parseInt' },
+  ],
+  defaultValues: {
+    status: 'AVAILABLE',
+    type: 'REGULAR',
+  },
+  validations: [
+    {
+      field: 'quantity',
+      rule: value => value > 0,
+      message: 'Quantity must be positive',
+    },
+  ],
+};
+```
+
+### KVStoreAdapter
+
+Key-value storage interface for state management.
+
+```typescript
+interface KVStoreAdapter {
+  get(key: string): Promise<any>;
+  set(key: string, value: any, ttl?: number): Promise<void>;
+  delete(key: string): Promise<void>;
+  exists(key: string): Promise<boolean>;
+  list(prefix?: string): Promise<string[]>;
+}
+```
+
+**Usage:**
+
+```typescript
+import { VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+const kv: KVStoreAdapter = new VersoriKVAdapter(openKv());
+
+// Store value
+await kv.set('processed:file123', { timestamp: Date.now() }, 3600);
+
+// Retrieve value
+const value = await kv.get('processed:file123');
+
+// Check existence
+if (await kv.exists('processed:file123')) {
+  console.log('File already processed');
+}
+
+// List keys with prefix
+const keys = await kv.list('processed:');
+```
+
+### Lock
+
+Distributed lock interface for concurrency control.
+
+```typescript
+interface Lock {
+  acquired: boolean;
+  key: string;
+  expiresAt: Date;
+  token: string;
+}
+```
+
+**Usage:**
+
+```typescript
+const lock = await lockService.acquire('inventory-import', 300);
+
+if (lock.acquired) {
+  try {
+    // Perform exclusive operation
+    await processInventory();
+  } finally {
+    await lockService.release(lock);
+  }
+}
+```
+
+## File & Data Interfaces
+
+### FileMetadata
+
+Metadata for files from S3 or SFTP data sources.
+
+```typescript
+interface FileMetadata {
+  path: string; // Full file path
+  name: string; // File name only
+  size?: number; // File size in bytes
+  lastModified?: string; // ISO timestamp
+  contentType?: string; // MIME type
+  source: 'S3' | 'SFTP'; // Data source type
+  etag?: string; // S3 ETag (S3 only)
+  bucket?: string; // S3 bucket (S3 only)
+  region?: string; // S3 region (S3 only)
+}
+```
+
+**Usage:**
+
+```typescript
+const files: FileMetadata[] = await s3.listFiles({
+  prefix: 'inventory/',
+});
+
+for (const file of files) {
+  console.log(`File: ${file.name}`);
+  console.log(`Size: ${file.size} bytes`);
+  console.log(`Modified: ${file.lastModified}`);
+  console.log(`Source: ${file.source}`);
+
+  if (file.source === 'S3') {
+    console.log(`Bucket: ${file.bucket}`);
+    console.log(`ETag: ${file.etag}`);
+  }
+}
+```
+
+### SftpConnection
+
+SFTP connection configuration (used for Versori platform integration).
+
+```typescript
+interface SftpConnection {
+  id: string;
+  name: string;
+  host: string;
+  port?: number;
+  username: string;
+  // Authentication handled by Versori platform
+}
+```
+
+**Usage:**
+
+```typescript
+const sftpConfig: SftpDataSourceConfig = {
+  type: 'SFTP_CSV',
+  connection: {
+    id: 'sftp-prod',
+    name: 'Production SFTP',
+    host: 'sftp.example.com',
+    port: 22,
+    username: 'user',
+  },
+  settings: {
+    remotePath: '/data',
+    filePattern: '*.csv',
+  },
+};
+```
+
+### CsvRecord
+
+A single CSV record as a key-value object.
+
+```typescript
+interface CsvRecord {
+  [key: string]: string | number | boolean;
+}
+```
+
+**Usage:**
+
+```typescript
+const records: CsvRecord[] = await csvParser.parse(buffer);
+
+for (const record of records) {
+  console.log(`SKU: ${record.sku}`);
+  console.log(`Quantity: ${record.quantity}`);
+  console.log(`Price: ${record.price}`);
+}
+```
+
+### ConnectionInfo
+
+SFTP connection debugging information.
+
+```typescript
+interface ConnectionInfo {
+  type: string; // Data source type
+  host: string; // SFTP host
+  port: number; // SFTP port
+  remotePath: string; // Remote directory path
+  filePattern: string; // File matching pattern
+  connectionPoolSize: number; // Current pool size
+  maxPoolSize: number; // Maximum pool size
+}
+```
+
+**Usage:**
+
+```typescript
+const info: ConnectionInfo = sftp.getConnectionInfo();
+
+console.log(`Connected to: ${info.host}:${info.port}`);
+console.log(`Remote path: ${info.remotePath}`);
+console.log(`Pattern: ${info.filePattern}`);
+console.log(`Pool: ${info.connectionPoolSize}/${info.maxPoolSize}`);
+```
+
+### ParquetDataRecord
+
+A single Parquet record.
+
+```typescript
+interface ParquetDataRecord {
+  [key: string]: string | number | boolean | Date | null | undefined;
+}
+```
+
+**Usage:**
+
+```typescript
+const { records } = await parquetParser.parse(arrayBuffer, 'data.parquet');
+
+for (const record of records as ParquetDataRecord[]) {
+  console.log(`Product: ${record.productRef}`);
+  console.log(`Quantity: ${record.qty}`);
+  console.log(`Updated: ${record.updatedAt}`);
+}
+```
+
+## See Also
+
+- [Module 01: Client](./api-reference-01-client-api.md) - Client initialization with configs
+- [Module 01: Client - Batch API](./api-reference-01-client-api.md#job-batch-operations) - Using batch types
+- [Module 05: Services](./api-reference-05-services.md#universal-mapper) - FieldMapping usage
+- [Module 06: Data Sources](./api-reference-06-data-sources.md) - FileMetadata usage
+- [Module 09: Error Handling](./api-reference-09-error-handling.md) - Error types
+
+---
+
+**[← Previous: Module 07 - Parsers](./api-reference-07-parsers.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Module 09 - Error Handling →](./api-reference-09-error-handling.md)**