@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/04-REFERENCE/troubleshooting/readme.md

@@ -1,144 +1,144 @@
-# Troubleshooting Guide
-
-> **Common issues and solutions for FC Connect SDK**
-> Quick fixes for authentication, parsing, connection, and runtime errors
-
-## Overview
-
-This guide provides solutions for common issues encountered when using the FC Connect SDK. Each issue includes symptoms, root cause, and verified solutions.
-
-## Quick Navigation
-
-### By Issue Type
-
-| Issue Type | Files | Common Problems |
-|------------|-------|-----------------|
-| **Authentication** | - | OAuth2 errors, credential issues |
-| **Parsing** | - | CSV, XML, JSON parsing failures |
-| **Data Sources** | - | S3, SFTP connection errors |
-| **Runtime** | [Deno SFTP Compatibility](./troubleshooting-deno-sftp-compatibility.md) | Platform-specific issues |
-| **Performance** | - | Slow queries, memory issues |
-| **GraphQL** | - | Schema validation errors |
-
-## Common Issues
-
-### Authentication Errors
-
-**Symptom:** `401 Unauthorized` or `Invalid credentials`
-
-**Causes:**
-- Wrong OAuth2 credentials
-- Missing `username`/`password` for password grant
-- Expired tokens
-
-**Solutions:**
-```typescript
-// ✅ CORRECT - Complete OAuth2 configuration
-const client = await createClient({
-  config: {
-    baseUrl: process.env.FLUENT_BASE_URL!,
-    clientId: process.env.FLUENT_CLIENT_ID!,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
-    username: process.env.FLUENT_USERNAME!,   // Required for password grant
-    password: process.env.FLUENT_PASSWORD!,   // Required for password grant
-    retailerId: process.env.FLUENT_RETAILER_ID!
-  }
-});
-```
-
-### Parsing Errors
-
-**Symptom:** `CSV parsing failed` or `XML parsing error`
-
-**Causes:**
-- Invalid file format
-- Encoding issues (UTF-8)
-- Malformed data
-
-**Solutions:**
-- Validate file format before parsing
-- Check file encoding (should be UTF-8)
-- Use error handling with try/catch
-
-### Connection Errors
-
-**Symptom:** `SFTP connection failed` or `S3 access denied`
-
-**Causes:**
-- Invalid credentials
-- Network/firewall issues
-- Missing permissions
-
-**Solutions:**
-- Verify credentials
-- Check network connectivity
-- Ensure proper IAM permissions (S3)
-- Always dispose connections: `await dataSource.dispose()`
-
-### Runtime Errors
-
-**Deno/Versori:**
-- **Buffer not defined** → Import: `import { Buffer } from 'node:buffer'`
-- **SFTP compatibility** → See [Deno SFTP Compatibility](./troubleshooting-deno-sftp-compatibility.md)
-
-**Node.js:**
-- **Module resolution** → Check `package.json` `type` field
-- **ES modules** → Use `.mjs` extension or `"type": "module"`
-
-### Performance Issues
-
-**Symptom:** Slow queries or high memory usage
-
-**Solutions:**
-- Use pagination with appropriate page sizes
-- Implement streaming for large files
-- Use batch processing with size limits
-- Monitor memory usage
-
-### GraphQL Schema Errors
-
-**Symptom:** `Field doesn't exist` or `Unknown type`
-
-**Solutions:**
-- Introspect schema: `npx fc-connect introspect-schema`
-- Validate queries before deployment
-- Check entity-specific field names (e.g., `onHand` vs `quantity`)
-
-## Platform-Specific Issues
-
-### Versori
-
-- **KV storage errors** → Check KV key format
-- **Connection not found** → Verify connection configuration
-- **Context API errors** → Ensure proper context destructuring
-
-### Deno
-
-- **Buffer errors** → Always import Buffer
-- **Permission errors** → Add required `--allow-*` flags
-- **SFTP issues** → See [Deno SFTP Compatibility](./troubleshooting-deno-sftp-compatibility.md)
-
-### Node.js
-
-- **Module resolution** → Check TypeScript configuration
-- **Environment variables** → Use dotenv for `.env` files
-
-## Getting Help
-
-If you can't find a solution:
-
-1. **Check the logs** - Enable debug logging
-2. **Review examples** - Check similar working examples
-3. **Validate schema** - Ensure GraphQL queries are valid
-4. **Test isolation** - Test components individually
-5. **Contact support** - support@fluentcommerce.com
-
-## Related Documentation
-
-- [Testing Guide](../testing/) - Test your integration
-- [Platform Guides](../platforms/) - Platform-specific patterns
-- [Schema Reference](../schema/) - Validate queries
-
-## Contributing
-
-Found a solution not documented here? Please contribute to this guide!
+# Troubleshooting Guide
+
+> **Common issues and solutions for FC Connect SDK**
+> Quick fixes for authentication, parsing, connection, and runtime errors
+
+## Overview
+
+This guide provides solutions for common issues encountered when using the FC Connect SDK. Each issue includes symptoms, root cause, and verified solutions.
+
+## Quick Navigation
+
+### By Issue Type
+
+| Issue Type | Files | Common Problems |
+|------------|-------|-----------------|
+| **Authentication** | - | OAuth2 errors, credential issues |
+| **Parsing** | - | CSV, XML, JSON parsing failures |
+| **Data Sources** | - | S3, SFTP connection errors |
+| **Runtime** | [Deno SFTP Compatibility](./troubleshooting-deno-sftp-compatibility.md) | Platform-specific issues |
+| **Performance** | - | Slow queries, memory issues |
+| **GraphQL** | - | Schema validation errors |
+
+## Common Issues
+
+### Authentication Errors
+
+**Symptom:** `401 Unauthorized` or `Invalid credentials`
+
+**Causes:**
+- Wrong OAuth2 credentials
+- Missing `username`/`password` for password grant
+- Expired tokens
+
+**Solutions:**
+```typescript
+// ✅ CORRECT - Complete OAuth2 configuration
+const client = await createClient({
+  config: {
+    baseUrl: process.env.FLUENT_BASE_URL!,
+    clientId: process.env.FLUENT_CLIENT_ID!,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET!,
+    username: process.env.FLUENT_USERNAME!,   // Required for password grant
+    password: process.env.FLUENT_PASSWORD!,   // Required for password grant
+    retailerId: process.env.FLUENT_RETAILER_ID!
+  }
+});
+```
+
+### Parsing Errors
+
+**Symptom:** `CSV parsing failed` or `XML parsing error`
+
+**Causes:**
+- Invalid file format
+- Encoding issues (UTF-8)
+- Malformed data
+
+**Solutions:**
+- Validate file format before parsing
+- Check file encoding (should be UTF-8)
+- Use error handling with try/catch
+
+### Connection Errors
+
+**Symptom:** `SFTP connection failed` or `S3 access denied`
+
+**Causes:**
+- Invalid credentials
+- Network/firewall issues
+- Missing permissions
+
+**Solutions:**
+- Verify credentials
+- Check network connectivity
+- Ensure proper IAM permissions (S3)
+- Always dispose connections: `await dataSource.dispose()`
+
+### Runtime Errors
+
+**Deno/Versori:**
+- **Buffer not defined** → Import: `import { Buffer } from 'node:buffer'`
+- **SFTP compatibility** → See [Deno SFTP Compatibility](./troubleshooting-deno-sftp-compatibility.md)
+
+**Node.js:**
+- **Module resolution** → Check `package.json` `type` field
+- **ES modules** → Use `.mjs` extension or `"type": "module"`
+
+### Performance Issues
+
+**Symptom:** Slow queries or high memory usage
+
+**Solutions:**
+- Use pagination with appropriate page sizes
+- Implement streaming for large files
+- Use batch processing with size limits
+- Monitor memory usage
+
+### GraphQL Schema Errors
+
+**Symptom:** `Field doesn't exist` or `Unknown type`
+
+**Solutions:**
+- Introspect schema: `npx fc-connect introspect-schema`
+- Validate queries before deployment
+- Check entity-specific field names (e.g., `onHand` vs `quantity`)
+
+## Platform-Specific Issues
+
+### Versori
+
+- **KV storage errors** → Check KV key format
+- **Connection not found** → Verify connection configuration
+- **Context API errors** → Ensure proper context destructuring
+
+### Deno
+
+- **Buffer errors** → Always import Buffer
+- **Permission errors** → Add required `--allow-*` flags
+- **SFTP issues** → See [Deno SFTP Compatibility](./troubleshooting-deno-sftp-compatibility.md)
+
+### Node.js
+
+- **Module resolution** → Check TypeScript configuration
+- **Environment variables** → Use dotenv for `.env` files
+
+## Getting Help
+
+If you can't find a solution:
+
+1. **Check the logs** - Enable debug logging
+2. **Review examples** - Check similar working examples
+3. **Validate schema** - Ensure GraphQL queries are valid
+4. **Test isolation** - Test components individually
+5. **Contact support** - support@fluentcommerce.com
+
+## Related Documentation
+
+- [Testing Guide](../testing/) - Test your integration
+- [Platform Guides](../platforms/) - Platform-specific patterns
+- [Schema Reference](../schema/) - Validate queries
+
+## Contributing
+
+Found a solution not documented here? Please contribute to this guide!