@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (495) hide show
  1. package/CHANGELOG.md +30 -2
  2. package/README.md +39 -0
  3. package/dist/cjs/auth/index.d.ts +3 -0
  4. package/dist/cjs/auth/index.js +13 -0
  5. package/dist/cjs/auth/profile-loader.d.ts +18 -0
  6. package/dist/cjs/auth/profile-loader.js +208 -0
  7. package/dist/cjs/client-factory.d.ts +4 -0
  8. package/dist/cjs/client-factory.js +10 -0
  9. package/dist/cjs/clients/fluent-client.js +13 -6
  10. package/dist/cjs/index.d.ts +3 -1
  11. package/dist/cjs/index.js +8 -2
  12. package/dist/cjs/utils/pagination-helpers.js +38 -2
  13. package/dist/cjs/versori/fluent-versori-client.js +11 -5
  14. package/dist/esm/auth/index.d.ts +3 -0
  15. package/dist/esm/auth/index.js +2 -0
  16. package/dist/esm/auth/profile-loader.d.ts +18 -0
  17. package/dist/esm/auth/profile-loader.js +169 -0
  18. package/dist/esm/client-factory.d.ts +4 -0
  19. package/dist/esm/client-factory.js +9 -0
  20. package/dist/esm/clients/fluent-client.js +13 -6
  21. package/dist/esm/index.d.ts +3 -1
  22. package/dist/esm/index.js +2 -1
  23. package/dist/esm/utils/pagination-helpers.js +38 -2
  24. package/dist/esm/versori/fluent-versori-client.js +11 -5
  25. package/dist/tsconfig.esm.tsbuildinfo +1 -1
  26. package/dist/tsconfig.tsbuildinfo +1 -1
  27. package/dist/tsconfig.types.tsbuildinfo +1 -1
  28. package/dist/types/auth/index.d.ts +3 -0
  29. package/dist/types/auth/profile-loader.d.ts +18 -0
  30. package/dist/types/client-factory.d.ts +4 -0
  31. package/dist/types/index.d.ts +3 -1
  32. package/docs/00-START-HERE/EXPORT-VALIDATION.md +158 -158
  33. package/docs/00-START-HERE/cli-analyze-source-structure-guide.md +655 -655
  34. package/docs/00-START-HERE/cli-documentation-index.md +202 -202
  35. package/docs/00-START-HERE/cli-quick-reference.md +252 -252
  36. package/docs/00-START-HERE/decision-tree.md +552 -552
  37. package/docs/00-START-HERE/getting-started.md +1070 -1070
  38. package/docs/00-START-HERE/mapper-quick-decision-guide.md +235 -235
  39. package/docs/00-START-HERE/readme.md +237 -237
  40. package/docs/00-START-HERE/retailerid-configuration.md +404 -404
  41. package/docs/00-START-HERE/sdk-philosophy.md +794 -794
  42. package/docs/00-START-HERE/troubleshooting-quick-reference.md +1086 -1086
  43. package/docs/01-TEMPLATES/faq.md +686 -686
  44. package/docs/01-TEMPLATES/patterns/pattern-templates-guide.md +68 -68
  45. package/docs/01-TEMPLATES/patterns/patterns-csv-schema-validation-and-rejection-report.md +233 -233
  46. package/docs/01-TEMPLATES/patterns/patterns-custom-resolvers.md +407 -407
  47. package/docs/01-TEMPLATES/patterns/patterns-error-handling-retry.md +511 -511
  48. package/docs/01-TEMPLATES/patterns/patterns-field-mapping-universal.md +701 -701
  49. package/docs/01-TEMPLATES/patterns/patterns-large-file-splitting.md +1430 -1430
  50. package/docs/01-TEMPLATES/patterns/patterns-master-data-etl.md +2399 -2399
  51. package/docs/01-TEMPLATES/patterns/patterns-pagination-streaming.md +447 -447
  52. package/docs/01-TEMPLATES/patterns/patterns-state-duplicate-prevention.md +385 -385
  53. package/docs/01-TEMPLATES/readme.md +957 -957
  54. package/docs/01-TEMPLATES/standalone/standalone-asn-inbound-processing.md +1209 -1209
  55. package/docs/01-TEMPLATES/standalone/standalone-graphql-query-export.md +1140 -1140
  56. package/docs/01-TEMPLATES/standalone/standalone-graphql-to-parquet-partitioned-s3.md +432 -432
  57. package/docs/01-TEMPLATES/standalone/standalone-multi-channel-inventory-sync.md +1185 -1185
  58. package/docs/01-TEMPLATES/standalone/standalone-multi-source-aggregation.md +1462 -1462
  59. package/docs/01-TEMPLATES/standalone/standalone-s3-csv-batch-api.md +1390 -1390
  60. package/docs/01-TEMPLATES/standalone/standalone-s3-csv-inventory-to-batch.md +330 -330
  61. package/docs/01-TEMPLATES/standalone/standalone-scripts-guide.md +87 -87
  62. package/docs/01-TEMPLATES/standalone/standalone-sftp-xml-graphql.md +1444 -1444
  63. package/docs/01-TEMPLATES/standalone/standalone-webhook-payload-processing.md +688 -688
  64. package/docs/01-TEMPLATES/versori/business-examples/business-examples-dropship-order-routing.md +193 -193
  65. package/docs/01-TEMPLATES/versori/business-examples/business-examples-graphql-parquet-extraction.md +518 -518
  66. package/docs/01-TEMPLATES/versori/business-examples/business-examples-inter-location-transfers.md +2162 -2162
  67. package/docs/01-TEMPLATES/versori/business-examples/business-examples-pre-order-allocation.md +2226 -2226
  68. package/docs/01-TEMPLATES/versori/business-examples/business-scenarios-guide.md +87 -87
  69. package/docs/01-TEMPLATES/versori/patterns/versori-patterns-connection-validation-pattern.md +656 -656
  70. package/docs/01-TEMPLATES/versori/patterns/versori-patterns-dual-workflow-connector.md +835 -835
  71. package/docs/01-TEMPLATES/versori/patterns/versori-patterns-guide.md +108 -108
  72. package/docs/01-TEMPLATES/versori/patterns/versori-patterns-kv-state-management.md +1533 -1533
  73. package/docs/01-TEMPLATES/versori/patterns/versori-patterns-xml-response-patterns.md +1160 -1160
  74. package/docs/01-TEMPLATES/versori/versori-platform-guide.md +201 -201
  75. package/docs/01-TEMPLATES/versori/webhooks/template-webhook-asn-purchase-order.md +1906 -1906
  76. package/docs/01-TEMPLATES/versori/webhooks/template-webhook-dropship-routing.md +1074 -1074
  77. package/docs/01-TEMPLATES/versori/webhooks/template-webhook-flash-sale-reserve.md +1395 -1395
  78. package/docs/01-TEMPLATES/versori/webhooks/template-webhook-generic-xml-order.md +888 -888
  79. package/docs/01-TEMPLATES/versori/webhooks/template-webhook-payment-gateway-integration.md +2478 -2478
  80. package/docs/01-TEMPLATES/versori/webhooks/template-webhook-rma-returns-comprehensive.md +2240 -2240
  81. package/docs/01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md +2029 -2029
  82. package/docs/01-TEMPLATES/versori/webhooks/webhook-templates-guide.md +140 -140
  83. package/docs/01-TEMPLATES/versori/workflows/_examples/sample-data/inventory-mapping.json +20 -20
  84. package/docs/01-TEMPLATES/versori/workflows/_examples/sample-data/products_2025-01-22.csv +11 -11
  85. package/docs/01-TEMPLATES/versori/workflows/_examples/sample-data/sample-data-guide.md +34 -34
  86. package/docs/01-TEMPLATES/versori/workflows/_examples/workflow-examples-guide.md +36 -36
  87. package/docs/01-TEMPLATES/versori/workflows/extraction/extraction-modes-guide.md +1038 -1038
  88. package/docs/01-TEMPLATES/versori/workflows/extraction/extraction-workflows-guide.md +138 -138
  89. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/graphql-extraction-guide.md +63 -63
  90. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-fulfillments-to-sftp-csv.md +2062 -2062
  91. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-fulfillments-to-sftp-xml.md +2294 -2294
  92. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-inventory-positions-to-s3-csv.md +2461 -2461
  93. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-inventory-positions-to-sftp-xml.md +2529 -2529
  94. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-inventory-quantities-to-s3-csv.md +2464 -2464
  95. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-inventory-quantities-to-s3-json.md +1959 -1959
  96. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-orders-to-s3-csv.md +1953 -1953
  97. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-orders-to-sftp-xml.md +2541 -2541
  98. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-products-to-s3-json.md +2384 -2384
  99. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-products-to-sftp-xml.md +2445 -2445
  100. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-virtual-positions-to-s3-csv.md +2355 -2355
  101. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-virtual-positions-to-s3-json.md +2042 -2042
  102. package/docs/01-TEMPLATES/versori/workflows/extraction/graphql-queries/template-extraction-virtual-positions-to-sftp-xml.md +2726 -2726
  103. package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/batch-api-guide.md +206 -206
  104. package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-cycle-count-reconciliation.md +2030 -2030
  105. package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-multi-channel-inventory-sync.md +1882 -1882
  106. package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md +2827 -2827
  107. package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-json-inventory-batch.md +1952 -1952
  108. package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-xml-inventory-batch.md +3289 -3289
  109. package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md +3064 -3064
  110. package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-json-inventory-batch.md +3238 -3238
  111. package/docs/01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-xml-inventory-batch.md +2977 -2977
  112. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/event-api-guide.md +321 -321
  113. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-payload-json-order-cancel-event.md +959 -959
  114. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-payload-xml-order-cancel-event.md +1170 -1170
  115. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-csv-product-event.md +2312 -2312
  116. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-json-product-event.md +2999 -2999
  117. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-parquet-product-event.md +2836 -2836
  118. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-s3-xml-product-event.md +2395 -2395
  119. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-sftp-csv-product-event.md +2295 -2295
  120. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-sftp-json-product-event.md +2602 -2602
  121. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-sftp-parquet-product-event.md +2589 -2589
  122. package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-sftp-xml-product-event.md +3578 -3578
  123. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/graphql-mutations-guide.md +93 -93
  124. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-payload-json-order-update-graphql.md +1260 -1260
  125. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-payload-xml-order-update-graphql.md +1472 -1472
  126. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-control-graphql.md +2417 -2417
  127. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-location-graphql.md +2811 -2811
  128. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-csv-price-graphql.md +2619 -2619
  129. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-json-location-graphql.md +2807 -2807
  130. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-s3-xml-location-graphql.md +2373 -2373
  131. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-csv-control-graphql.md +2740 -2740
  132. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-csv-location-graphql.md +2760 -2760
  133. package/docs/01-TEMPLATES/versori/workflows/ingestion/graphql-mutations/template-ingestion-sftp-json-location-graphql.md +1710 -1710
  134. package/docs/01-TEMPLATES/versori/workflows/ingestion/ingestion-workflows-guide.md +136 -136
  135. package/docs/01-TEMPLATES/versori/workflows/rubix-webhooks/rubix-webhooks-guide.md +520 -520
  136. package/docs/01-TEMPLATES/versori/workflows/rubix-webhooks/template-webhook-rubix-fulfilment-to-sftp-xml-inline.md +1418 -1418
  137. package/docs/01-TEMPLATES/versori/workflows/rubix-webhooks/template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md +1785 -1785
  138. package/docs/01-TEMPLATES/versori/workflows/rubix-webhooks/template-webhook-rubix-order-attribute-update.md +824 -824
  139. package/docs/01-TEMPLATES/versori/workflows/workflows-overview-guide.md +646 -646
  140. package/docs/02-CORE-GUIDES/advanced-services/advanced-services-batch-archival.md +724 -724
  141. package/docs/02-CORE-GUIDES/advanced-services/advanced-services-job-tracker.md +627 -627
  142. package/docs/02-CORE-GUIDES/advanced-services/advanced-services-partial-batch-recovery.md +561 -561
  143. package/docs/02-CORE-GUIDES/advanced-services/advanced-services-quick-reference.md +367 -367
  144. package/docs/02-CORE-GUIDES/advanced-services/advanced-services-readme.md +407 -407
  145. package/docs/02-CORE-GUIDES/advanced-services/readme.md +49 -49
  146. package/docs/02-CORE-GUIDES/api-reference/api-reference-quick-reference.md +548 -548
  147. package/docs/02-CORE-GUIDES/api-reference/event-api-input-output-reference.md +702 -1171
  148. package/docs/02-CORE-GUIDES/api-reference/examples/client-initialization.ts +286 -286
  149. package/docs/02-CORE-GUIDES/api-reference/graphql-error-classification.md +337 -337
  150. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-01-client-api.md +399 -482
  151. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-03-authentication.md +199 -199
  152. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md +925 -925
  153. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-05-services.md +1198 -1198
  154. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-06-data-sources.md +1083 -1083
  155. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md +1097 -1097
  156. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-08-pagination.md +513 -513
  157. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-08-types.md +545 -597
  158. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-09-error-handling.md +527 -527
  159. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-09-webhook-validation.md +514 -514
  160. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-10-extraction.md +557 -557
  161. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-10-utilities.md +412 -412
  162. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-11-cli-tools.md +423 -423
  163. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-11-error-handling.md +716 -716
  164. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-12-analyze-source-structure.md +518 -518
  165. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-12-partial-responses.md +212 -212
  166. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-12-testing.md +300 -300
  167. package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-13-resolver-builder.md +322 -322
  168. package/docs/02-CORE-GUIDES/api-reference/readme.md +279 -279
  169. package/docs/02-CORE-GUIDES/auto-pagination/auto-pagination-quick-reference.md +351 -351
  170. package/docs/02-CORE-GUIDES/auto-pagination/auto-pagination-readme.md +277 -277
  171. package/docs/02-CORE-GUIDES/auto-pagination/examples/auto-pagination-readme.md +178 -178
  172. package/docs/02-CORE-GUIDES/auto-pagination/examples/common-patterns.ts +351 -351
  173. package/docs/02-CORE-GUIDES/auto-pagination/examples/paginate-products.ts +384 -384
  174. package/docs/02-CORE-GUIDES/auto-pagination/examples/paginate-virtual-positions.ts +308 -308
  175. package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-01-foundations.md +470 -470
  176. package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-02-quick-start.md +713 -713
  177. package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-03-configuration.md +754 -754
  178. package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-04-advanced-patterns.md +732 -732
  179. package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-05-sdk-integration.md +847 -847
  180. package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-06-troubleshooting.md +359 -359
  181. package/docs/02-CORE-GUIDES/auto-pagination/modules/auto-pagination-07-api-reference.md +462 -462
  182. package/docs/02-CORE-GUIDES/auto-pagination/readme.md +54 -54
  183. package/docs/02-CORE-GUIDES/data-sources/data-sources-file-operations-error-handling.md +1487 -1487
  184. package/docs/02-CORE-GUIDES/data-sources/data-sources-quick-reference.md +836 -836
  185. package/docs/02-CORE-GUIDES/data-sources/data-sources-readme.md +276 -276
  186. package/docs/02-CORE-GUIDES/data-sources/data-sources-sftp-credential-access-security.md +553 -553
  187. package/docs/02-CORE-GUIDES/data-sources/examples/common-patterns.ts +409 -409
  188. package/docs/02-CORE-GUIDES/data-sources/examples/data-sources-readme.md +178 -178
  189. package/docs/02-CORE-GUIDES/data-sources/examples/s3-operations.ts +308 -308
  190. package/docs/02-CORE-GUIDES/data-sources/examples/sftp-operations.ts +371 -371
  191. package/docs/02-CORE-GUIDES/data-sources/modules/data-sources-01-foundations.md +735 -735
  192. package/docs/02-CORE-GUIDES/data-sources/modules/data-sources-02-s3-operations.md +1302 -1302
  193. package/docs/02-CORE-GUIDES/data-sources/modules/data-sources-03-sftp-operations.md +1379 -1379
  194. package/docs/02-CORE-GUIDES/data-sources/modules/data-sources-04-file-patterns.md +941 -941
  195. package/docs/02-CORE-GUIDES/data-sources/modules/data-sources-05-advanced-topics.md +813 -813
  196. package/docs/02-CORE-GUIDES/data-sources/modules/data-sources-06-integration-patterns.md +486 -486
  197. package/docs/02-CORE-GUIDES/data-sources/modules/data-sources-07-troubleshooting.md +387 -387
  198. package/docs/02-CORE-GUIDES/data-sources/modules/data-sources-08-api-reference.md +417 -417
  199. package/docs/02-CORE-GUIDES/data-sources/readme.md +77 -77
  200. package/docs/02-CORE-GUIDES/error-handling-guide.md +936 -936
  201. package/docs/02-CORE-GUIDES/extraction/examples/02-core-guides-extraction-readme.md +116 -116
  202. package/docs/02-CORE-GUIDES/extraction/examples/common-patterns.ts +428 -428
  203. package/docs/02-CORE-GUIDES/extraction/examples/extract-inventory-basic.ts +187 -187
  204. package/docs/02-CORE-GUIDES/extraction/extraction-quick-reference.md +596 -596
  205. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-01-foundations.md +514 -514
  206. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-02-basic-extraction.md +823 -823
  207. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-03-parquet-processing.md +507 -507
  208. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-04-data-enrichment.md +546 -546
  209. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-05-transformation.md +494 -494
  210. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-06-export-formats.md +458 -458
  211. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-06-performance.md +138 -138
  212. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-07-api-reference.md +148 -148
  213. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-07-optimization.md +692 -692
  214. package/docs/02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md +1008 -1008
  215. package/docs/02-CORE-GUIDES/extraction/readme.md +151 -151
  216. package/docs/02-CORE-GUIDES/ingestion/examples/_simple-kv-store.ts +40 -40
  217. package/docs/02-CORE-GUIDES/ingestion/examples/error-recovery.ts +728 -728
  218. package/docs/02-CORE-GUIDES/ingestion/examples/event-driven.ts +501 -501
  219. package/docs/02-CORE-GUIDES/ingestion/examples/local-file-ingestion.ts +88 -88
  220. package/docs/02-CORE-GUIDES/ingestion/examples/parquet-ingestion.ts +117 -117
  221. package/docs/02-CORE-GUIDES/ingestion/examples/performance-optimized.ts +647 -647
  222. package/docs/02-CORE-GUIDES/ingestion/examples/s3-csv-ingestion.ts +169 -169
  223. package/docs/02-CORE-GUIDES/ingestion/examples/sftp-csv-ingestion.ts +134 -134
  224. package/docs/02-CORE-GUIDES/ingestion/ingestion-quick-reference.md +546 -546
  225. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-01-introduction.md +626 -626
  226. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-02-quick-start.md +658 -658
  227. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-03-data-sources.md +1052 -1052
  228. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-04-field-mapping.md +763 -763
  229. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-05-advanced-parsers.md +676 -676
  230. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-06-batch-api.md +1295 -1295
  231. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-07-api-reference.md +138 -138
  232. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-07-state-management.md +1037 -1037
  233. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-08-performance-optimization.md +1349 -1349
  234. package/docs/02-CORE-GUIDES/ingestion/modules/02-core-guides-ingestion-09-best-practices.md +1893 -1893
  235. package/docs/02-CORE-GUIDES/ingestion/readme.md +160 -160
  236. package/docs/02-CORE-GUIDES/logging-guide.md +585 -585
  237. package/docs/02-CORE-GUIDES/mapping/error-handling-patterns.md +401 -401
  238. package/docs/02-CORE-GUIDES/mapping/examples/02-core-guides-mapping-readme.md +128 -128
  239. package/docs/02-CORE-GUIDES/mapping/examples/common-patterns.ts +273 -273
  240. package/docs/02-CORE-GUIDES/mapping/examples/csv-location-ingestion.json +36 -36
  241. package/docs/02-CORE-GUIDES/mapping/examples/csv-mapping.ts +242 -242
  242. package/docs/02-CORE-GUIDES/mapping/examples/graphql-to-parquet-extraction.json +36 -36
  243. package/docs/02-CORE-GUIDES/mapping/examples/json-mapping.ts +213 -213
  244. package/docs/02-CORE-GUIDES/mapping/examples/json-product-to-mutation.json +48 -48
  245. package/docs/02-CORE-GUIDES/mapping/examples/xml-mapping.ts +291 -291
  246. package/docs/02-CORE-GUIDES/mapping/examples/xml-order-to-mutation.json +45 -45
  247. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/graphql-mutation-mapping-quick-reference.md +463 -463
  248. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/graphql-mutation-mapping-readme.md +227 -227
  249. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-01-introduction.md +222 -222
  250. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-02-quick-start.md +351 -351
  251. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-03-schema-validation.md +569 -569
  252. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-04-mapping-patterns.md +471 -471
  253. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-05-configuration-reference.md +611 -611
  254. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-06-advanced-xpath.md +148 -148
  255. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-06-path-syntax.md +464 -464
  256. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-07-api-reference.md +94 -94
  257. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-07-array-handling.md +307 -307
  258. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-08-custom-resolvers.md +544 -544
  259. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-09-advanced-patterns.md +427 -427
  260. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-10-hooks-and-variables.md +336 -336
  261. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md +488 -488
  262. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-12-arguments-vs-nodes.md +383 -383
  263. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-13-best-practices.md +477 -477
  264. package/docs/02-CORE-GUIDES/mapping/graphql-mutation-mapping/readme.md +62 -62
  265. package/docs/02-CORE-GUIDES/mapping/mapping-format-decision-tree.md +480 -480
  266. package/docs/02-CORE-GUIDES/mapping/mapping-graphql-alias-batching-guide.md +820 -820
  267. package/docs/02-CORE-GUIDES/mapping/mapping-javascript-objects.md +2369 -2369
  268. package/docs/02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md +682 -682
  269. package/docs/02-CORE-GUIDES/mapping/modules/02-core-guides-mapping-07-api-reference.md +1327 -1327
  270. package/docs/02-CORE-GUIDES/mapping/modules/02-core-guides-mapping-08-error-handling.md +1142 -1142
  271. package/docs/02-CORE-GUIDES/mapping/modules/mapping-04-use-cases.md +891 -891
  272. package/docs/02-CORE-GUIDES/mapping/modules/mapping-06-helpers-resolvers.md +1126 -1126
  273. package/docs/02-CORE-GUIDES/mapping/modules/mapping-06-sdk-resolvers.md +199 -199
  274. package/docs/02-CORE-GUIDES/mapping/modules/mapping-07-api-reference.md +1319 -1319
  275. package/docs/02-CORE-GUIDES/mapping/readme.md +178 -178
  276. package/docs/02-CORE-GUIDES/mapping/resolver-registration.md +410 -410
  277. package/docs/02-CORE-GUIDES/mapping/resolvers/examples/common-patterns.ts +226 -226
  278. package/docs/02-CORE-GUIDES/mapping/resolvers/examples/custom-resolvers.ts +227 -227
  279. package/docs/02-CORE-GUIDES/mapping/resolvers/examples/sdk-resolvers-usage.ts +203 -203
  280. package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md +274 -274
  281. package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-api-reference.md +679 -679
  282. package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-cookbook.md +826 -826
  283. package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-guide.md +1330 -1330
  284. package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-helpers-reference.md +1437 -1437
  285. package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-parameters-reference.md +553 -553
  286. package/docs/02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-resolver-troubleshooting.md +854 -854
  287. package/docs/02-CORE-GUIDES/mapping/resolvers/readme.md +75 -75
  288. package/docs/02-CORE-GUIDES/parsers/examples/02-core-guides-parsers-readme.md +161 -161
  289. package/docs/02-CORE-GUIDES/parsers/examples/csv-parser-examples.ts +110 -110
  290. package/docs/02-CORE-GUIDES/parsers/examples/json-parser-examples.ts +33 -33
  291. package/docs/02-CORE-GUIDES/parsers/examples/parquet-parser-examples.ts +47 -47
  292. package/docs/02-CORE-GUIDES/parsers/examples/xml-parser-examples.ts +38 -38
  293. package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-01-foundations.md +355 -355
  294. package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-02-csv-parser.md +772 -772
  295. package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-03-json-parser.md +789 -789
  296. package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-04-xml-parser.md +857 -857
  297. package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-05-parquet-parser.md +603 -603
  298. package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-06-integration-patterns.md +702 -702
  299. package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-06-streaming.md +121 -121
  300. package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-07-api-reference.md +89 -89
  301. package/docs/02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-07-troubleshooting.md +727 -727
  302. package/docs/02-CORE-GUIDES/parsers/parsers-quick-reference.md +482 -482
  303. package/docs/02-CORE-GUIDES/parsers/parsers-readme.md +258 -258
  304. package/docs/02-CORE-GUIDES/parsers/readme.md +65 -65
  305. package/docs/02-CORE-GUIDES/readme.md +194 -194
  306. package/docs/02-CORE-GUIDES/webhook-validation/examples/basic-validation.ts +108 -108
  307. package/docs/02-CORE-GUIDES/webhook-validation/examples/common-patterns.ts +316 -316
  308. package/docs/02-CORE-GUIDES/webhook-validation/examples/webhook-validation-readme.md +61 -61
  309. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-01-foundations.md +440 -440
  310. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-02-quick-start.md +525 -525
  311. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-03-versori-integration.md +741 -741
  312. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-04-platform-integration.md +629 -629
  313. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-05-configuration.md +535 -535
  314. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-06-error-handling.md +611 -611
  315. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-06-troubleshooting.md +124 -124
  316. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-07-api-reference.md +511 -511
  317. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-08-rubix-webhooks.md +590 -590
  318. package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-09-rubix-event-vs-http-call.md +432 -432
  319. package/docs/02-CORE-GUIDES/webhook-validation/readme.md +239 -239
  320. package/docs/02-CORE-GUIDES/webhook-validation/webhook-validation-quick-reference.md +392 -392
  321. package/docs/03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-quick-reference.md +498 -498
  322. package/docs/03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-readme.md +313 -313
  323. package/docs/03-PATTERN-GUIDES/connector-scenarios/examples/common-patterns.ts +612 -612
  324. package/docs/03-PATTERN-GUIDES/connector-scenarios/examples/connector-scenarios-readme.md +253 -253
  325. package/docs/03-PATTERN-GUIDES/connector-scenarios/modules/connector-scenarios-01-foundations.md +452 -452
  326. package/docs/03-PATTERN-GUIDES/connector-scenarios/modules/connector-scenarios-02-simple-scenarios.md +681 -681
  327. package/docs/03-PATTERN-GUIDES/connector-scenarios/modules/connector-scenarios-03-intermediate-scenarios.md +637 -637
  328. package/docs/03-PATTERN-GUIDES/connector-scenarios/modules/connector-scenarios-04-advanced-scenarios.md +650 -650
  329. package/docs/03-PATTERN-GUIDES/connector-scenarios/modules/connector-scenarios-05-bidirectional-sync.md +233 -233
  330. package/docs/03-PATTERN-GUIDES/connector-scenarios/modules/connector-scenarios-06-production-patterns.md +442 -442
  331. package/docs/03-PATTERN-GUIDES/connector-scenarios/modules/connector-scenarios-07-reference.md +445 -445
  332. package/docs/03-PATTERN-GUIDES/connector-scenarios/readme.md +31 -31
  333. package/docs/03-PATTERN-GUIDES/enterprise-integration-patterns.md +1528 -1528
  334. package/docs/03-PATTERN-GUIDES/error-handling/comprehensive-error-handling-guide.md +1437 -1437
  335. package/docs/03-PATTERN-GUIDES/error-handling/error-handling-quick-reference.md +390 -390
  336. package/docs/03-PATTERN-GUIDES/error-handling/examples/common-patterns.ts +438 -438
  337. package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-01-foundations.md +362 -362
  338. package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-02-error-types.md +850 -850
  339. package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-03-utf8-handling.md +456 -456
  340. package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-04-error-scenarios.md +658 -658
  341. package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-05-calling-patterns.md +671 -671
  342. package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-06-retry-strategies.md +1034 -1034
  343. package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-07-monitoring.md +653 -653
  344. package/docs/03-PATTERN-GUIDES/error-handling/modules/error-handling-08-api-reference.md +847 -847
  345. package/docs/03-PATTERN-GUIDES/error-handling/readme.md +36 -36
  346. package/docs/03-PATTERN-GUIDES/examples/__tests__/readme.md +40 -40
  347. package/docs/03-PATTERN-GUIDES/examples/__tests__/resolver-examples.test.js +282 -282
  348. package/docs/03-PATTERN-GUIDES/examples/test-data/03-pattern-guides-readme.md +110 -110
  349. package/docs/03-PATTERN-GUIDES/examples/test-data/canonical-inventory.json +123 -123
  350. package/docs/03-PATTERN-GUIDES/examples/test-data/canonical-order.json +171 -171
  351. package/docs/03-PATTERN-GUIDES/examples/test-data/readme.md +28 -28
  352. package/docs/03-PATTERN-GUIDES/extraction/extraction-readme.md +15 -15
  353. package/docs/03-PATTERN-GUIDES/extraction/readme.md +25 -25
  354. package/docs/03-PATTERN-GUIDES/file-operations/examples/common-patterns.ts +407 -407
  355. package/docs/03-PATTERN-GUIDES/file-operations/examples/file-operations-readme.md +142 -142
  356. package/docs/03-PATTERN-GUIDES/file-operations/file-operations-quick-reference.md +462 -462
  357. package/docs/03-PATTERN-GUIDES/file-operations/file-operations-readme.md +379 -379
  358. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-01-foundations.md +430 -430
  359. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-02-quick-start.md +484 -484
  360. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-03-s3-operations.md +507 -507
  361. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-04-sftp-operations.md +963 -963
  362. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-05-streaming-performance.md +503 -503
  363. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-06-archive-patterns.md +386 -386
  364. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-06-error-handling.md +117 -117
  365. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-07-api-reference.md +78 -78
  366. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-07-testing-troubleshooting.md +567 -567
  367. package/docs/03-PATTERN-GUIDES/file-operations/modules/file-operations-08-api-reference.md +1055 -1055
  368. package/docs/03-PATTERN-GUIDES/file-operations/readme.md +32 -32
  369. package/docs/03-PATTERN-GUIDES/ingestion/ingestion-readme.md +15 -15
  370. package/docs/03-PATTERN-GUIDES/ingestion/readme.md +25 -25
  371. package/docs/03-PATTERN-GUIDES/integration-patterns/examples/batch-processing.ts +130 -130
  372. package/docs/03-PATTERN-GUIDES/integration-patterns/examples/common-patterns.ts +360 -360
  373. package/docs/03-PATTERN-GUIDES/integration-patterns/examples/delta-sync.ts +130 -130
  374. package/docs/03-PATTERN-GUIDES/integration-patterns/examples/integration-patterns-readme.md +100 -100
  375. package/docs/03-PATTERN-GUIDES/integration-patterns/examples/real-time-webhook.ts +398 -398
  376. package/docs/03-PATTERN-GUIDES/integration-patterns/integration-patterns-quick-reference.md +962 -962
  377. package/docs/03-PATTERN-GUIDES/integration-patterns/integration-patterns-readme.md +134 -134
  378. package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-01-real-time-processing.md +991 -991
  379. package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-02-batch-processing.md +1547 -1547
  380. package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-03-delta-sync.md +1108 -1108
  381. package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-04-webhook-patterns.md +1181 -1181
  382. package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-05-error-handling.md +1061 -1061
  383. package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-06-advanced-integration-services.md +1547 -1547
  384. package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-06-performance.md +109 -109
  385. package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-07-api-reference.md +34 -34
  386. package/docs/03-PATTERN-GUIDES/integration-patterns/readme.md +30 -30
  387. package/docs/03-PATTERN-GUIDES/logging-minimal-mode.md +128 -128
  388. package/docs/03-PATTERN-GUIDES/multiple-connections/examples/common-patterns.ts +380 -380
  389. package/docs/03-PATTERN-GUIDES/multiple-connections/examples/multiple-connections-readme.md +139 -139
  390. package/docs/03-PATTERN-GUIDES/multiple-connections/examples/parallel-root-connections.ts +149 -149
  391. package/docs/03-PATTERN-GUIDES/multiple-connections/examples/real-world-scenarios.ts +405 -405
  392. package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-01-foundations.md +378 -378
  393. package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-02-quick-start.md +566 -566
  394. package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-03-targeting-connections.md +659 -659
  395. package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-04-parallel-queries.md +656 -656
  396. package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-05-best-practices.md +624 -624
  397. package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-06-api-reference.md +824 -824
  398. package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-06-versori.md +119 -119
  399. package/docs/03-PATTERN-GUIDES/multiple-connections/modules/multiple-connections-07-api-reference.md +87 -87
  400. package/docs/03-PATTERN-GUIDES/multiple-connections/multiple-connections-quick-reference.md +353 -353
  401. package/docs/03-PATTERN-GUIDES/multiple-connections/multiple-connections-readme.md +270 -270
  402. package/docs/03-PATTERN-GUIDES/multiple-connections/readme.md +30 -30
  403. package/docs/03-PATTERN-GUIDES/pagination/pagination-readme.md +14 -14
  404. package/docs/03-PATTERN-GUIDES/pagination/readme.md +24 -24
  405. package/docs/03-PATTERN-GUIDES/parquet/examples/common-patterns.ts +180 -180
  406. package/docs/03-PATTERN-GUIDES/parquet/examples/read-parquet.ts +48 -48
  407. package/docs/03-PATTERN-GUIDES/parquet/examples/write-parquet.ts +65 -65
  408. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-01-introduction.md +393 -393
  409. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-02-quick-start.md +572 -572
  410. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-03-reading-parquet.md +525 -525
  411. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-04-writing-parquet.md +554 -554
  412. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-05-graphql-extraction.md +405 -405
  413. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-06-performance.md +104 -104
  414. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-06-s3-integration.md +511 -511
  415. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-07-api-reference.md +90 -90
  416. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-07-performance-optimization.md +525 -525
  417. package/docs/03-PATTERN-GUIDES/parquet/modules/03-pattern-guides-parquet-08-best-practices.md +712 -712
  418. package/docs/03-PATTERN-GUIDES/parquet/parquet-quick-reference.md +683 -683
  419. package/docs/03-PATTERN-GUIDES/parquet/parquet-readme.md +248 -248
  420. package/docs/03-PATTERN-GUIDES/parquet/readme.md +32 -32
  421. package/docs/03-PATTERN-GUIDES/parsers/parsers-readme.md +12 -12
  422. package/docs/03-PATTERN-GUIDES/parsers/readme.md +24 -24
  423. package/docs/03-PATTERN-GUIDES/readme.md +159 -159
  424. package/docs/03-PATTERN-GUIDES/webhooks/readme.md +24 -24
  425. package/docs/03-PATTERN-GUIDES/webhooks/webhooks-readme.md +8 -8
  426. package/docs/04-REFERENCE/architecture/architecture-01-overview.md +427 -427
  427. package/docs/04-REFERENCE/architecture/architecture-02-client-architecture.md +424 -424
  428. package/docs/04-REFERENCE/architecture/architecture-03-data-flow.md +690 -690
  429. package/docs/04-REFERENCE/architecture/architecture-04-service-layer.md +834 -834
  430. package/docs/04-REFERENCE/architecture/architecture-05-integration-architecture.md +655 -655
  431. package/docs/04-REFERENCE/architecture/architecture-06-state-management.md +653 -653
  432. package/docs/04-REFERENCE/architecture/architecture-adding-new-data-sources.md +686 -686
  433. package/docs/04-REFERENCE/architecture/readme.md +279 -279
  434. package/docs/04-REFERENCE/platforms/deno/readme.md +117 -117
  435. package/docs/04-REFERENCE/platforms/nodejs/readme.md +146 -146
  436. package/docs/04-REFERENCE/platforms/readme.md +135 -135
  437. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-01-introduction.md +398 -398
  438. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-02-quick-start.md +560 -560
  439. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-03-authentication.md +757 -757
  440. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md +2476 -2476
  441. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-05-connections.md +1167 -1167
  442. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-06-kv-storage.md +990 -990
  443. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-06-state-management.md +121 -121
  444. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-07-api-reference.md +68 -68
  445. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-07-deployment.md +731 -731
  446. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-08-best-practices.md +1111 -1111
  447. package/docs/04-REFERENCE/platforms/versori/modules/platforms-versori-09-signature-reference.md +766 -766
  448. package/docs/04-REFERENCE/platforms/versori/platforms-versori-readme.md +299 -299
  449. package/docs/04-REFERENCE/platforms/versori/platforms-versori-s3-sftp-configuration-guide.md +1425 -1425
  450. package/docs/04-REFERENCE/platforms/versori/platforms-versori-webhook-api-key-security.md +816 -816
  451. package/docs/04-REFERENCE/platforms/versori/platforms-versori-webhook-connection-security.md +681 -681
  452. package/docs/04-REFERENCE/platforms/versori/platforms-versori-workflow-task-types.md +708 -708
  453. package/docs/04-REFERENCE/platforms/versori/readme.md +108 -108
  454. package/docs/04-REFERENCE/readme.md +148 -148
  455. package/docs/04-REFERENCE/resolver-signature/examples/advanced-resolvers.ts +482 -482
  456. package/docs/04-REFERENCE/resolver-signature/examples/async-resolvers.ts +496 -496
  457. package/docs/04-REFERENCE/resolver-signature/examples/basic-resolvers.ts +343 -343
  458. package/docs/04-REFERENCE/resolver-signature/examples/resolver-signature-readme.md +188 -188
  459. package/docs/04-REFERENCE/resolver-signature/examples/testing-resolvers.ts +463 -463
  460. package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-01-foundations.md +286 -286
  461. package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-02-parameter-reference.md +643 -643
  462. package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-03-basic-examples.md +521 -521
  463. package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-04-advanced-patterns.md +739 -739
  464. package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-05-sdk-resolvers.md +531 -531
  465. package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-06-migration-guide.md +650 -650
  466. package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-06-testing.md +125 -125
  467. package/docs/04-REFERENCE/resolver-signature/modules/resolver-signature-07-api-reference.md +794 -794
  468. package/docs/04-REFERENCE/resolver-signature/readme.md +64 -64
  469. package/docs/04-REFERENCE/resolver-signature/resolver-signature-quick-reference.md +270 -270
  470. package/docs/04-REFERENCE/resolver-signature/resolver-signature-readme.md +351 -351
  471. package/docs/04-REFERENCE/schema/fluent-commerce-schema.json +764 -764
  472. package/docs/04-REFERENCE/schema/readme.md +141 -141
  473. package/docs/04-REFERENCE/testing/examples/04-reference-testing-readme.md +158 -158
  474. package/docs/04-REFERENCE/testing/examples/fluent-testing.ts +62 -62
  475. package/docs/04-REFERENCE/testing/examples/health-check.ts +155 -155
  476. package/docs/04-REFERENCE/testing/examples/integration-test.ts +119 -119
  477. package/docs/04-REFERENCE/testing/examples/performance-test.ts +183 -183
  478. package/docs/04-REFERENCE/testing/examples/s3-testing.ts +127 -127
  479. package/docs/04-REFERENCE/testing/modules/04-reference-testing-01-foundations.md +267 -267
  480. package/docs/04-REFERENCE/testing/modules/04-reference-testing-02-s3-testing.md +599 -599
  481. package/docs/04-REFERENCE/testing/modules/04-reference-testing-03-fluent-testing.md +589 -589
  482. package/docs/04-REFERENCE/testing/modules/04-reference-testing-04-integration-testing.md +699 -699
  483. package/docs/04-REFERENCE/testing/modules/04-reference-testing-05-debugging.md +478 -478
  484. package/docs/04-REFERENCE/testing/modules/04-reference-testing-06-cicd-integration.md +463 -463
  485. package/docs/04-REFERENCE/testing/modules/04-reference-testing-06-preflight-validation.md +131 -131
  486. package/docs/04-REFERENCE/testing/modules/04-reference-testing-07-best-practices.md +499 -499
  487. package/docs/04-REFERENCE/testing/modules/04-reference-testing-07-coverage-ci.md +165 -165
  488. package/docs/04-REFERENCE/testing/modules/04-reference-testing-08-api-reference.md +634 -634
  489. package/docs/04-REFERENCE/testing/readme.md +86 -86
  490. package/docs/04-REFERENCE/testing/testing-quick-reference.md +667 -667
  491. package/docs/04-REFERENCE/testing/testing-readme.md +286 -286
  492. package/docs/04-REFERENCE/troubleshooting/readme.md +144 -144
  493. package/docs/04-REFERENCE/troubleshooting/troubleshooting-deno-sftp-compatibility.md +392 -392
  494. package/docs/template-loading-matrix.md +242 -242
  495. package/package.json +5 -3
@@ -1,486 +1,486 @@
1
- # Module 6: Integration Patterns
2
-
3
- **Level:** Intermediate
4
- **Category:** Integration Workflows
5
-
6
- ## Overview
7
-
8
- Data sources become powerful when integrated with SDK services like parsers, mappers, and batch clients. This module covers common integration patterns for building complete ingestion and extraction workflows.
9
-
10
- ## Table of Contents
11
-
12
- - [Data Source + Parser Pipelines](#data-source-parser-pipelines)
13
- - [Ingestion Workflows](#ingestion-workflows)
14
- - [Extraction to S3](#extraction-to-s3)
15
- - [State Tracking with KV Stores](#state-tracking-with-kv-stores)
16
- - [Multi-Source Aggregation](#multi-source-aggregation)
17
- - [Error Recovery Patterns](#error-recovery-patterns)
18
- - [Performance Patterns](#performance-patterns)
19
- - [See Also](#see-also)
20
-
21
- ---
22
-
23
- ## Data Source + Parser Pipelines
24
-
25
- Combine data sources with parsers for complete file processing:
26
-
27
- ### CSV Pipeline
28
-
29
- ```typescript
30
- import { S3DataSource, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
31
-
32
- const s3 = new S3DataSource(config, log);
33
- const csvParser = new CSVParserService();
34
-
35
- // List CSV files
36
- const files = await s3.listFiles({
37
- keyPrefix: 'inventory/',
38
- filePattern: '*.csv'
39
- });
40
-
41
- // Parse each file
42
- for (const file of files) {
43
- const content = await s3.readFile(file.key);
44
- const records = await csvParser.parse(content);
45
-
46
- console.log(`Parsed ${records.length} records from ${file.key}`);
47
- // Process records...
48
- }
49
-
50
- await s3.dispose();
51
- ```
52
-
53
- ### XML Pipeline
54
-
55
- ```typescript
56
- import { SftpDataSource, XMLParserService } from '@fluentcommerce/fc-connect-sdk';
57
-
58
- const sftp = new SftpDataSource(config, log);
59
- const xmlParser = new XMLParserService();
60
-
61
- // List XML files
62
- const files = await sftp.listFiles({
63
- remotePath: '/inbound/orders',
64
- filePattern: '*.xml'
65
- });
66
-
67
- // Parse each file
68
- for (const file of files) {
69
- const content = await sftp.readFile({
70
- remotePath: '/inbound/orders',
71
- filename: file.filename
72
- });
73
-
74
- const parsed = await xmlParser.parse(content);
75
- const orders = await xmlParser.query(parsed, '//Order');
76
-
77
- console.log(`Found ${orders.length} orders in ${file.filename}`);
78
- // Process orders...
79
- }
80
-
81
- await sftp.dispose();
82
- ```
83
-
84
- ---
85
-
86
- ## Ingestion Workflows
87
-
88
- ### S3 CSV to Batch API
89
-
90
- ```typescript
91
- import {
92
- S3DataSource,
93
- CSVParserService,
94
- UniversalMapper,
95
- BatchAPIClient,
96
- createClient
97
- } from '@fluentcommerce/fc-connect-sdk';
98
-
99
- async function ingestInventory() {
100
- // Initialize services
101
- const client = await createClient({ config });
102
- const s3 = new S3DataSource(s3Config, log);
103
- const parser = new CSVParserService();
104
- const mapper = new UniversalMapper(mappingConfig);
105
- const batch = new BatchAPIClient(client, log);
106
-
107
- try {
108
- // Read file from S3
109
- const files = await s3.listFiles({
110
- keyPrefix: 'inventory/',
111
- filePattern: 'positions-*.csv'
112
- });
113
-
114
- for (const file of files) {
115
- // Parse CSV
116
- const content = await s3.readFile(file.key);
117
- const records = await parser.parse(content);
118
-
119
- // Map to Fluent format
120
- const mapped = records.map(r => mapper.map(r));
121
-
122
- // Send to Batch API
123
- const job = await batch.createJob({
124
- type: 'INVENTORY_UPDATE',
125
- retailerId: process.env.FLUENT_RETAILER_ID
126
- });
127
-
128
- await batch.sendBatch(job.id, mapped);
129
-
130
- // Archive processed file
131
- await s3.moveFile(
132
- file.key,
133
- file.key.replace('inventory/', 'inventory/archive/')
134
- );
135
-
136
- log.info(`Processed ${file.key}: ${records.length} records`);
137
- }
138
- } finally {
139
- await s3.dispose();
140
- }
141
- }
142
- ```
143
-
144
- ### SFTP XML to GraphQL
145
-
146
- ```typescript
147
- import {
148
- SftpDataSource,
149
- XMLParserService,
150
- GraphQLMutationMapper,
151
- createClient
152
- } from '@fluentcommerce/fc-connect-sdk';
153
-
154
- async function ingestOrders() {
155
- const client = await createClient({ config });
156
- const sftp = new SftpDataSource(sftpConfig, log);
157
- const xmlParser = new XMLParserService();
158
- const mapper = new GraphQLMutationMapper(mappingConfig);
159
-
160
- try {
161
- const files = await sftp.listFiles({
162
- remotePath: '/orders',
163
- filePattern: 'order-*.xml'
164
- });
165
-
166
- for (const file of files) {
167
- // Read and parse XML
168
- const xmlContent = await sftp.readFile({
169
- remotePath: '/orders',
170
- filename: file.filename
171
- });
172
-
173
- const parsed = await xmlParser.parse(xmlContent);
174
-
175
- // Generate GraphQL mutations
176
- const mutations = await mapper.generateMutations(parsed);
177
-
178
- // Execute mutations
179
- for (const mutation of mutations) {
180
- await client.mutate({
181
- mutation: mutation.mutation,
182
- variables: mutation.variables
183
- });
184
- }
185
-
186
- // Move to processed folder
187
- await sftp.moveFile({
188
- oldPath: `/orders/${file.filename}`,
189
- newPath: `/orders/processed/${file.filename}`
190
- });
191
-
192
- log.info(`Processed ${file.filename}: ${mutations.length} mutations`);
193
- }
194
- } finally {
195
- await sftp.dispose();
196
- }
197
- }
198
- ```
199
-
200
- ---
201
-
202
- ## Extraction to S3
203
-
204
- ### GraphQL to S3 Parquet
205
-
206
- ```typescript
207
- import {
208
- createClient,
209
- ExtractionOrchestrator,
210
- S3DataSource
211
- } from '@fluentcommerce/fc-connect-sdk';
212
-
213
- async function extractToDataLake() {
214
- const client = await createClient({ config });
215
- const orchestrator = new ExtractionOrchestrator(client, log);
216
-
217
- // Extract virtual positions to Parquet on S3
218
- await orchestrator.extractToS3({
219
- query: `
220
- query GetPositions($first: Int, $after: String) {
221
- virtualPositions(first: $first, after: $after) {
222
- edges {
223
- node {
224
- id
225
- ref
226
- productRef
227
- groupRef
228
- quantity
229
- status
230
- }
231
- }
232
- pageInfo {
233
- hasNextPage
234
- endCursor
235
- }
236
- }
237
- }
238
- `,
239
- connectionName: 'virtualPositions',
240
- outputFormat: 'parquet',
241
- s3Config: {
242
- bucket: 'datalake',
243
- keyPrefix: `fluent/positions/date=${new Date().toISOString().split('T')[0]}/`,
244
- filename: `positions-${Date.now()}.parquet`
245
- },
246
- pagination: {
247
- pageSize: 500,
248
- maxPages: Infinity
249
- }
250
- });
251
-
252
- log.info('Extraction to data lake complete');
253
- }
254
- ```
255
-
256
- ---
257
-
258
- ## State Tracking with KV Stores
259
-
260
- ### Prevent Duplicate Processing
261
-
262
- ```typescript
263
- import {
264
- S3DataSource,
265
- StateService,
266
- VersoriKVAdapter
267
- } from '@fluentcommerce/fc-connect-sdk';
268
-
269
- async function processFilesWithTracking(ctx) {
270
- const { openKv, log } = ctx;
271
- const kv = openKv(':project:');
272
- const kvAdapter = new VersoriKVAdapter(kv);
273
- const stateService = new StateService(kvAdapter);
274
-
275
- const s3 = new S3DataSource(config, log);
276
-
277
- try {
278
- const files = await s3.listFiles({
279
- keyPrefix: 'inventory/',
280
- filePattern: '*.csv'
281
- });
282
-
283
- for (const file of files) {
284
- const fileKey = file.key;
285
-
286
- // Check if already processed
287
- if (await stateService.isFileProcessed(fileKey)) {
288
- log.info(`Skipping ${fileKey} (already processed)`);
289
- continue;
290
- }
291
-
292
- // Process file
293
- const content = await s3.readFile(fileKey);
294
- await processFile(content);
295
-
296
- // Mark as processed
297
- await stateService.markFileProcessed(fileKey, {
298
- processedAt: new Date().toISOString(),
299
- size: file.size
300
- });
301
-
302
- log.info(`Processed ${fileKey}`);
303
- }
304
- } finally {
305
- await s3.dispose();
306
- }
307
- }
308
- ```
309
-
310
- ---
311
-
312
- ## Multi-Source Aggregation
313
-
314
- ### Combine S3 and SFTP Sources
315
-
316
- ```typescript
317
- import { S3DataSource, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
318
-
319
- async function aggregateInventory() {
320
- const s3 = new S3DataSource(s3Config, log);
321
- const sftp = new SftpDataSource(sftpConfig, log);
322
-
323
- try {
324
- // Fetch from S3
325
- const s3Files = await s3.listFiles({
326
- keyPrefix: 'warehouse-a/',
327
- filePattern: '*.csv'
328
- });
329
-
330
- // Fetch from SFTP
331
- const sftpFiles = await sftp.listFiles({
332
- remotePath: '/warehouse-b',
333
- filePattern: '*.csv'
334
- });
335
-
336
- // Process all files
337
- const allInventory = [];
338
-
339
- for (const file of s3Files) {
340
- const content = await s3.readFile(file.key);
341
- const records = await parseCSV(content);
342
- allInventory.push(...records);
343
- }
344
-
345
- for (const file of sftpFiles) {
346
- const content = await sftp.readFile({
347
- remotePath: '/warehouse-b',
348
- filename: file.filename
349
- });
350
- const records = await parseCSV(content);
351
- allInventory.push(...records);
352
- }
353
-
354
- log.info(`Aggregated ${allInventory.length} records from ${s3Files.length + sftpFiles.length} files`);
355
-
356
- return allInventory;
357
- } finally {
358
- await s3.dispose();
359
- await sftp.dispose();
360
- }
361
- }
362
- ```
363
-
364
- ---
365
-
366
- ## Error Recovery Patterns
367
-
368
- ### Retry Failed Files
369
-
370
- ```typescript
371
- async function processWithRetry(s3: S3DataSource, files: Array<any>) {
372
- const failedFiles = [];
373
-
374
- for (const file of files) {
375
- let retries = 0;
376
- const maxRetries = 3;
377
-
378
- while (retries < maxRetries) {
379
- try {
380
- const content = await s3.readFile(file.key);
381
- await processFile(content);
382
- break; // Success
383
- } catch (error) {
384
- retries++;
385
- log.warn(`Retry ${retries}/${maxRetries} for ${file.key}`, error);
386
-
387
- if (retries >= maxRetries) {
388
- failedFiles.push({ file, error: error.message });
389
- } else {
390
- // Exponential backoff
391
- await new Promise(resolve =>
392
- setTimeout(resolve, 1000 * Math.pow(2, retries))
393
- );
394
- }
395
- }
396
- }
397
- }
398
-
399
- if (failedFiles.length > 0) {
400
- log.error(`${failedFiles.length} files failed after retries`);
401
- // Export failed files report
402
- await exportFailedFiles(failedFiles);
403
- }
404
- }
405
- ```
406
-
407
- ---
408
-
409
- ## Performance Patterns
410
-
411
- ### Parallel File Processing
412
-
413
- ```typescript
414
- async function processFilesInParallel(s3: S3DataSource, files: Array<any>) {
415
- const CONCURRENCY = 5; // Process 5 files at a time
416
-
417
- // Split files into chunks
418
- for (let i = 0; i < files.length; i += CONCURRENCY) {
419
- const chunk = files.slice(i, i + CONCURRENCY);
420
-
421
- // Process chunk in parallel
422
- await Promise.all(
423
- chunk.map(async (file) => {
424
- const content = await s3.readFile(file.key);
425
- await processFile(content);
426
- log.info(`Processed ${file.key}`);
427
- })
428
- );
429
- }
430
- }
431
- ```
432
-
433
- ### Streaming Large Files
434
-
435
- ```typescript
436
- import { S3DataSource, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
437
-
438
- async function streamLargeFile(s3: S3DataSource, fileKey: string) {
439
- const parser = new CSVParserService();
440
-
441
- // Stream file in chunks
442
- const stream = await s3.readFileStream(fileKey);
443
-
444
- let batch = [];
445
- const BATCH_SIZE = 1000;
446
-
447
- for await (const chunk of parser.parseStreaming(stream)) {
448
- batch.push(chunk);
449
-
450
- if (batch.length >= BATCH_SIZE) {
451
- await processBatch(batch);
452
- batch = [];
453
- }
454
- }
455
-
456
- // Process remaining records
457
- if (batch.length > 0) {
458
- await processBatch(batch);
459
- }
460
- }
461
- ```
462
-
463
- ---
464
-
465
- ## See Also
466
-
467
- **Related Modules:**
468
- - [Module 01: Foundations](./data-sources-01-foundations.md) - Data source basics
469
- - [Module 02: S3 Operations](./data-sources-02-s3-operations.md) - S3DataSource API
470
- - [Module 03: SFTP Operations](./data-sources-03-sftp-operations.md) - SftpDataSource API
471
-
472
- **Complete Guides:**
473
- - [Ingestion Guide](../../ingestion/ingestion-readme.md) - Complete ingestion workflows
474
- - [Extraction Guide](../../extraction/extraction-readme.md) - Extraction patterns
475
- - [Parsers Guide](../../parsers/parsers-readme.md) - Parser integration
476
-
477
- **Templates:**
478
- - [S3 CSV Ingestion](../../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)
479
- - [SFTP XML Ingestion](../../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-xml-inventory-batch.md)
480
-
481
- ---
482
-
483
- **Navigation:**
484
- - [Back to Module List](./readme.md)
485
- - [Previous: Module 05 - Advanced Topics](./data-sources-05-advanced-topics.md)
486
- - [Next: Module 07 - Troubleshooting](./data-sources-07-troubleshooting.md)
1
+ # Module 6: Integration Patterns
2
+
3
+ **Level:** Intermediate
4
+ **Category:** Integration Workflows
5
+
6
+ ## Overview
7
+
8
+ Data sources become powerful when integrated with SDK services like parsers, mappers, and batch clients. This module covers common integration patterns for building complete ingestion and extraction workflows.
9
+
10
+ ## Table of Contents
11
+
12
+ - [Data Source + Parser Pipelines](#data-source-parser-pipelines)
13
+ - [Ingestion Workflows](#ingestion-workflows)
14
+ - [Extraction to S3](#extraction-to-s3)
15
+ - [State Tracking with KV Stores](#state-tracking-with-kv-stores)
16
+ - [Multi-Source Aggregation](#multi-source-aggregation)
17
+ - [Error Recovery Patterns](#error-recovery-patterns)
18
+ - [Performance Patterns](#performance-patterns)
19
+ - [See Also](#see-also)
20
+
21
+ ---
22
+
23
+ ## Data Source + Parser Pipelines
24
+
25
+ Combine data sources with parsers for complete file processing:
26
+
27
+ ### CSV Pipeline
28
+
29
+ ```typescript
30
+ import { S3DataSource, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
31
+
32
+ const s3 = new S3DataSource(config, log);
33
+ const csvParser = new CSVParserService();
34
+
35
+ // List CSV files
36
+ const files = await s3.listFiles({
37
+ keyPrefix: 'inventory/',
38
+ filePattern: '*.csv'
39
+ });
40
+
41
+ // Parse each file
42
+ for (const file of files) {
43
+ const content = await s3.readFile(file.key);
44
+ const records = await csvParser.parse(content);
45
+
46
+ console.log(`Parsed ${records.length} records from ${file.key}`);
47
+ // Process records...
48
+ }
49
+
50
+ await s3.dispose();
51
+ ```
52
+
53
+ ### XML Pipeline
54
+
55
+ ```typescript
56
+ import { SftpDataSource, XMLParserService } from '@fluentcommerce/fc-connect-sdk';
57
+
58
+ const sftp = new SftpDataSource(config, log);
59
+ const xmlParser = new XMLParserService();
60
+
61
+ // List XML files
62
+ const files = await sftp.listFiles({
63
+ remotePath: '/inbound/orders',
64
+ filePattern: '*.xml'
65
+ });
66
+
67
+ // Parse each file
68
+ for (const file of files) {
69
+ const content = await sftp.readFile({
70
+ remotePath: '/inbound/orders',
71
+ filename: file.filename
72
+ });
73
+
74
+ const parsed = await xmlParser.parse(content);
75
+ const orders = await xmlParser.query(parsed, '//Order');
76
+
77
+ console.log(`Found ${orders.length} orders in ${file.filename}`);
78
+ // Process orders...
79
+ }
80
+
81
+ await sftp.dispose();
82
+ ```
83
+
84
+ ---
85
+
86
+ ## Ingestion Workflows
87
+
88
+ ### S3 CSV to Batch API
89
+
90
+ ```typescript
91
+ import {
92
+ S3DataSource,
93
+ CSVParserService,
94
+ UniversalMapper,
95
+ BatchAPIClient,
96
+ createClient
97
+ } from '@fluentcommerce/fc-connect-sdk';
98
+
99
+ async function ingestInventory() {
100
+ // Initialize services
101
+ const client = await createClient({ config });
102
+ const s3 = new S3DataSource(s3Config, log);
103
+ const parser = new CSVParserService();
104
+ const mapper = new UniversalMapper(mappingConfig);
105
+ const batch = new BatchAPIClient(client, log);
106
+
107
+ try {
108
+ // Read file from S3
109
+ const files = await s3.listFiles({
110
+ keyPrefix: 'inventory/',
111
+ filePattern: 'positions-*.csv'
112
+ });
113
+
114
+ for (const file of files) {
115
+ // Parse CSV
116
+ const content = await s3.readFile(file.key);
117
+ const records = await parser.parse(content);
118
+
119
+ // Map to Fluent format
120
+ const mapped = records.map(r => mapper.map(r));
121
+
122
+ // Send to Batch API
123
+ const job = await batch.createJob({
124
+ type: 'INVENTORY_UPDATE',
125
+ retailerId: process.env.FLUENT_RETAILER_ID
126
+ });
127
+
128
+ await batch.sendBatch(job.id, mapped);
129
+
130
+ // Archive processed file
131
+ await s3.moveFile(
132
+ file.key,
133
+ file.key.replace('inventory/', 'inventory/archive/')
134
+ );
135
+
136
+ log.info(`Processed ${file.key}: ${records.length} records`);
137
+ }
138
+ } finally {
139
+ await s3.dispose();
140
+ }
141
+ }
142
+ ```
143
+
144
+ ### SFTP XML to GraphQL
145
+
146
+ ```typescript
147
+ import {
148
+ SftpDataSource,
149
+ XMLParserService,
150
+ GraphQLMutationMapper,
151
+ createClient
152
+ } from '@fluentcommerce/fc-connect-sdk';
153
+
154
+ async function ingestOrders() {
155
+ const client = await createClient({ config });
156
+ const sftp = new SftpDataSource(sftpConfig, log);
157
+ const xmlParser = new XMLParserService();
158
+ const mapper = new GraphQLMutationMapper(mappingConfig);
159
+
160
+ try {
161
+ const files = await sftp.listFiles({
162
+ remotePath: '/orders',
163
+ filePattern: 'order-*.xml'
164
+ });
165
+
166
+ for (const file of files) {
167
+ // Read and parse XML
168
+ const xmlContent = await sftp.readFile({
169
+ remotePath: '/orders',
170
+ filename: file.filename
171
+ });
172
+
173
+ const parsed = await xmlParser.parse(xmlContent);
174
+
175
+ // Generate GraphQL mutations
176
+ const mutations = await mapper.generateMutations(parsed);
177
+
178
+ // Execute mutations
179
+ for (const mutation of mutations) {
180
+ await client.mutate({
181
+ mutation: mutation.mutation,
182
+ variables: mutation.variables
183
+ });
184
+ }
185
+
186
+ // Move to processed folder
187
+ await sftp.moveFile({
188
+ oldPath: `/orders/${file.filename}`,
189
+ newPath: `/orders/processed/${file.filename}`
190
+ });
191
+
192
+ log.info(`Processed ${file.filename}: ${mutations.length} mutations`);
193
+ }
194
+ } finally {
195
+ await sftp.dispose();
196
+ }
197
+ }
198
+ ```
199
+
200
+ ---
201
+
202
+ ## Extraction to S3
203
+
204
+ ### GraphQL to S3 Parquet
205
+
206
+ ```typescript
207
+ import {
208
+ createClient,
209
+ ExtractionOrchestrator,
210
+ S3DataSource
211
+ } from '@fluentcommerce/fc-connect-sdk';
212
+
213
+ async function extractToDataLake() {
214
+ const client = await createClient({ config });
215
+ const orchestrator = new ExtractionOrchestrator(client, log);
216
+
217
+ // Extract virtual positions to Parquet on S3
218
+ await orchestrator.extractToS3({
219
+ query: `
220
+ query GetPositions($first: Int, $after: String) {
221
+ virtualPositions(first: $first, after: $after) {
222
+ edges {
223
+ node {
224
+ id
225
+ ref
226
+ productRef
227
+ groupRef
228
+ quantity
229
+ status
230
+ }
231
+ }
232
+ pageInfo {
233
+ hasNextPage
234
+ endCursor
235
+ }
236
+ }
237
+ }
238
+ `,
239
+ connectionName: 'virtualPositions',
240
+ outputFormat: 'parquet',
241
+ s3Config: {
242
+ bucket: 'datalake',
243
+ keyPrefix: `fluent/positions/date=${new Date().toISOString().split('T')[0]}/`,
244
+ filename: `positions-${Date.now()}.parquet`
245
+ },
246
+ pagination: {
247
+ pageSize: 500,
248
+ maxPages: Infinity
249
+ }
250
+ });
251
+
252
+ log.info('Extraction to data lake complete');
253
+ }
254
+ ```
255
+
256
+ ---
257
+
258
+ ## State Tracking with KV Stores
259
+
260
+ ### Prevent Duplicate Processing
261
+
262
+ ```typescript
263
+ import {
264
+ S3DataSource,
265
+ StateService,
266
+ VersoriKVAdapter
267
+ } from '@fluentcommerce/fc-connect-sdk';
268
+
269
+ async function processFilesWithTracking(ctx) {
270
+ const { openKv, log } = ctx;
271
+ const kv = openKv(':project:');
272
+ const kvAdapter = new VersoriKVAdapter(kv);
273
+ const stateService = new StateService(kvAdapter);
274
+
275
+ const s3 = new S3DataSource(config, log);
276
+
277
+ try {
278
+ const files = await s3.listFiles({
279
+ keyPrefix: 'inventory/',
280
+ filePattern: '*.csv'
281
+ });
282
+
283
+ for (const file of files) {
284
+ const fileKey = file.key;
285
+
286
+ // Check if already processed
287
+ if (await stateService.isFileProcessed(fileKey)) {
288
+ log.info(`Skipping ${fileKey} (already processed)`);
289
+ continue;
290
+ }
291
+
292
+ // Process file
293
+ const content = await s3.readFile(fileKey);
294
+ await processFile(content);
295
+
296
+ // Mark as processed
297
+ await stateService.markFileProcessed(fileKey, {
298
+ processedAt: new Date().toISOString(),
299
+ size: file.size
300
+ });
301
+
302
+ log.info(`Processed ${fileKey}`);
303
+ }
304
+ } finally {
305
+ await s3.dispose();
306
+ }
307
+ }
308
+ ```
309
+
310
+ ---
311
+
312
+ ## Multi-Source Aggregation
313
+
314
+ ### Combine S3 and SFTP Sources
315
+
316
+ ```typescript
317
+ import { S3DataSource, SftpDataSource } from '@fluentcommerce/fc-connect-sdk';
318
+
319
+ async function aggregateInventory() {
320
+ const s3 = new S3DataSource(s3Config, log);
321
+ const sftp = new SftpDataSource(sftpConfig, log);
322
+
323
+ try {
324
+ // Fetch from S3
325
+ const s3Files = await s3.listFiles({
326
+ keyPrefix: 'warehouse-a/',
327
+ filePattern: '*.csv'
328
+ });
329
+
330
+ // Fetch from SFTP
331
+ const sftpFiles = await sftp.listFiles({
332
+ remotePath: '/warehouse-b',
333
+ filePattern: '*.csv'
334
+ });
335
+
336
+ // Process all files
337
+ const allInventory = [];
338
+
339
+ for (const file of s3Files) {
340
+ const content = await s3.readFile(file.key);
341
+ const records = await parseCSV(content);
342
+ allInventory.push(...records);
343
+ }
344
+
345
+ for (const file of sftpFiles) {
346
+ const content = await sftp.readFile({
347
+ remotePath: '/warehouse-b',
348
+ filename: file.filename
349
+ });
350
+ const records = await parseCSV(content);
351
+ allInventory.push(...records);
352
+ }
353
+
354
+ log.info(`Aggregated ${allInventory.length} records from ${s3Files.length + sftpFiles.length} files`);
355
+
356
+ return allInventory;
357
+ } finally {
358
+ await s3.dispose();
359
+ await sftp.dispose();
360
+ }
361
+ }
362
+ ```
363
+
364
+ ---
365
+
366
+ ## Error Recovery Patterns
367
+
368
+ ### Retry Failed Files
369
+
370
+ ```typescript
371
+ async function processWithRetry(s3: S3DataSource, files: Array<any>) {
372
+ const failedFiles = [];
373
+
374
+ for (const file of files) {
375
+ let retries = 0;
376
+ const maxRetries = 3;
377
+
378
+ while (retries < maxRetries) {
379
+ try {
380
+ const content = await s3.readFile(file.key);
381
+ await processFile(content);
382
+ break; // Success
383
+ } catch (error) {
384
+ retries++;
385
+ log.warn(`Retry ${retries}/${maxRetries} for ${file.key}`, error);
386
+
387
+ if (retries >= maxRetries) {
388
+ failedFiles.push({ file, error: error.message });
389
+ } else {
390
+ // Exponential backoff
391
+ await new Promise(resolve =>
392
+ setTimeout(resolve, 1000 * Math.pow(2, retries))
393
+ );
394
+ }
395
+ }
396
+ }
397
+ }
398
+
399
+ if (failedFiles.length > 0) {
400
+ log.error(`${failedFiles.length} files failed after retries`);
401
+ // Export failed files report
402
+ await exportFailedFiles(failedFiles);
403
+ }
404
+ }
405
+ ```
406
+
407
+ ---
408
+
409
+ ## Performance Patterns
410
+
411
+ ### Parallel File Processing
412
+
413
+ ```typescript
414
+ async function processFilesInParallel(s3: S3DataSource, files: Array<any>) {
415
+ const CONCURRENCY = 5; // Process 5 files at a time
416
+
417
+ // Split files into chunks
418
+ for (let i = 0; i < files.length; i += CONCURRENCY) {
419
+ const chunk = files.slice(i, i + CONCURRENCY);
420
+
421
+ // Process chunk in parallel
422
+ await Promise.all(
423
+ chunk.map(async (file) => {
424
+ const content = await s3.readFile(file.key);
425
+ await processFile(content);
426
+ log.info(`Processed ${file.key}`);
427
+ })
428
+ );
429
+ }
430
+ }
431
+ ```
432
+
433
+ ### Streaming Large Files
434
+
435
+ ```typescript
436
+ import { S3DataSource, CSVParserService } from '@fluentcommerce/fc-connect-sdk';
437
+
438
+ async function streamLargeFile(s3: S3DataSource, fileKey: string) {
439
+ const parser = new CSVParserService();
440
+
441
+ // Stream file in chunks
442
+ const stream = await s3.readFileStream(fileKey);
443
+
444
+ let batch = [];
445
+ const BATCH_SIZE = 1000;
446
+
447
+ for await (const chunk of parser.parseStreaming(stream)) {
448
+ batch.push(chunk);
449
+
450
+ if (batch.length >= BATCH_SIZE) {
451
+ await processBatch(batch);
452
+ batch = [];
453
+ }
454
+ }
455
+
456
+ // Process remaining records
457
+ if (batch.length > 0) {
458
+ await processBatch(batch);
459
+ }
460
+ }
461
+ ```
462
+
463
+ ---
464
+
465
+ ## See Also
466
+
467
+ **Related Modules:**
468
+ - [Module 01: Foundations](./data-sources-01-foundations.md) - Data source basics
469
+ - [Module 02: S3 Operations](./data-sources-02-s3-operations.md) - S3DataSource API
470
+ - [Module 03: SFTP Operations](./data-sources-03-sftp-operations.md) - SftpDataSource API
471
+
472
+ **Complete Guides:**
473
+ - [Ingestion Guide](../../ingestion/ingestion-readme.md) - Complete ingestion workflows
474
+ - [Extraction Guide](../../extraction/extraction-readme.md) - Extraction patterns
475
+ - [Parsers Guide](../../parsers/parsers-readme.md) - Parser integration
476
+
477
+ **Templates:**
478
+ - [S3 CSV Ingestion](../../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)
479
+ - [SFTP XML Ingestion](../../../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-xml-inventory-batch.md)
480
+
481
+ ---
482
+
483
+ **Navigation:**
484
+ - [Back to Module List](./readme.md)
485
+ - [Previous: Module 05 - Advanced Topics](./data-sources-05-advanced-topics.md)
486
+ - [Next: Module 07 - Troubleshooting](./data-sources-07-troubleshooting.md)