@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/extraction/examples/extract-inventory-basic.ts

@@ -1,187 +1,187 @@
-/**
- * Basic Inventory Extraction Example
- *
- * This example demonstrates:
- * - Creating a Fluent client
- * - Writing a validated GraphQL query
- * - Using auto-pagination
- * - Processing results
- *
- * Complexity: Beginner
- * Estimated runtime: 30-60 seconds for 10K records
- */
-
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-async function extractInventoryBasic() {
-  console.log('=== Basic Inventory Extraction ===\n');
-
-  // Step 1: Create client
-  console.log('Step 1: Creating Fluent client...');
-  const client = await createClient({
-    config: {
-      baseUrl: process.env.FLUENT_BASE_URL!,
-      clientId: process.env.FLUENT_CLIENT_ID!,
-      clientSecret: process.env.FLUENT_CLIENT_SECRET!
-      // retailerId is OPTIONAL for GraphQL queries (only required for Job/Event API)
-    },
-  });
-  console.log('✓ Client created\n');
-
-  // Step 2: Define GraphQL query
-  console.log('Step 2: Defining GraphQL query...');
-  const query = `
-    query ExtractInventory($first: Int!, $after: String) {
-      inventoryPositions(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            ref
-            productRef
-            locationRef
-            qty
-            status
-            createdOn
-            updatedOn
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-    }
-  `;
-
-  console.log('✓ Query defined');
-  console.log('  Fields: id, ref, productRef, locationRef, qty, status, createdOn, updatedOn\n');
-
-  // Step 3: Execute with auto-pagination
-  console.log('Step 3: Executing query with auto-pagination...');
-  console.log('  Page size: 100 records');
-  console.log('  Max records: 10,000');
-  console.log('');
-
-  try {
-    const result = await client.graphql({
-      query,
-      variables: { first: 100 },
-      pagination: {
-        maxRecords: 10000,
-        onProgress: (page, totalRecords) => {
-          console.log(`  Page ${page}: ${totalRecords} records fetched`);
-        },
-      },
-    });
-
-    console.log('\n✓ Extraction complete\n');
-
-    // Step 4: Process results
-    console.log('Step 4: Processing results...');
-    const records = result.data.inventoryPositions.edges.map(e => e.node);
-
-    // Display statistics
-    console.log('\n=== Extraction Statistics ===');
-    console.log(`Total records: ${records.length}`);
-    console.log(`Pages fetched: ${result.extensions.autoPagination.totalPages}`);
-    console.log(`Time elapsed: ${result.extensions.autoPagination.timeElapsed}ms`);
-    console.log(
-      `Records/sec: ${((records.length / result.extensions.autoPagination.timeElapsed) * 1000).toFixed(0)}`
-    );
-
-    if (result.extensions.autoPagination.truncated) {
-      console.log('\n⚠️  Results truncated by safety limit');
-    }
-
-    // Display sample records
-    console.log('\n=== Sample Records (first 5) ===');
-    records.slice(0, 5).forEach((record, index) => {
-      console.log(`\n[${index + 1}] ${record.ref}`);
-      console.log(`    Product: ${record.productRef}`);
-      console.log(`    Location: ${record.locationRef}`);
-      console.log(`    Quantity: ${record.qty}`);
-      console.log(`    Status: ${record.status}`);
-    });
-
-    // Analyze data
-    console.log('\n=== Data Analysis ===');
-    const totalQuantity = records.reduce((sum, r) => sum + (parseInt(r.qty) || 0), 0);
-    const uniqueProducts = new Set(records.map(r => r.productRef)).size;
-    const uniqueLocations = new Set(records.map(r => r.locationRef)).size;
-
-    console.log(`Total quantity across all positions: ${totalQuantity}`);
-    console.log(`Unique products: ${uniqueProducts}`);
-    console.log(`Unique locations: ${uniqueLocations}`);
-
-    // Status breakdown
-    const statusCounts = records.reduce(
-      (acc, r) => {
-        const status = r.status || 'UNKNOWN';
-        acc[status] = (acc[status] || 0) + 1;
-        return acc;
-      },
-      {} as Record<string, number>
-    );
-
-    console.log('\nStatus breakdown:');
-    for (const [status, count] of Object.entries(statusCounts)) {
-      const percentage = ((count / records.length) * 100).toFixed(1);
-      console.log(`  ${status}: ${count} (${percentage}%)`);
-    }
-
-    return records;
-  } catch (error: any) {
-    console.error('\n✗ Extraction failed:', error.message);
-
-    if (error.message.includes('authentication')) {
-      console.error('\nAuthentication failed. Please check your credentials:');
-      console.error('  - FLUENT_CLIENT_ID');
-      console.error('  - FLUENT_CLIENT_SECRET');
-      console.error('  - FLUENT_RETAILER_ID');
-    } else if (error.message.includes('timeout')) {
-      console.error('\nRequest timeout. Try:');
-      console.error('  - Reducing page size');
-      console.error('  - Reducing maxRecords limit');
-    } else {
-      console.error('\nUnexpected error. Check:');
-      console.error('  - Network connectivity');
-      console.error('  - FLUENT_BASE_URL is correct');
-      console.error('  - GraphQL query syntax');
-    }
-
-    throw error;
-  }
-}
-
-// Run the extraction
-if (require.main === module) {
-  // Validate environment variables
-  const requiredEnvVars = [
-    'FLUENT_BASE_URL',
-    'FLUENT_CLIENT_ID',
-    'FLUENT_CLIENT_SECRET',
-    'FLUENT_RETAILER_ID',
-  ];
-
-  const missing = requiredEnvVars.filter(v => !process.env[v]);
-
-  if (missing.length > 0) {
-    console.error('❌ Missing required environment variables:');
-    missing.forEach(v => console.error(`   - ${v}`));
-    console.error('\nPlease set these variables and try again.');
-    process.exit(1);
-  }
-
-  // Run extraction
-  extractInventoryBasic()
-    .then(() => {
-      console.log('\n✓ Extraction workflow complete');
-      process.exit(0);
-    })
-    .catch(error => {
-      console.error('\n✗ Extraction workflow failed:', error.message);
-      process.exit(1);
-    });
-}
-
-export { extractInventoryBasic };
+/**
+ * Basic Inventory Extraction Example
+ *
+ * This example demonstrates:
+ * - Creating a Fluent client
+ * - Writing a validated GraphQL query
+ * - Using auto-pagination
+ * - Processing results
+ *
+ * Complexity: Beginner
+ * Estimated runtime: 30-60 seconds for 10K records
+ */
+
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+async function extractInventoryBasic() {
+  console.log('=== Basic Inventory Extraction ===\n');
+
+  // Step 1: Create client
+  console.log('Step 1: Creating Fluent client...');
+  const client = await createClient({
+    config: {
+      baseUrl: process.env.FLUENT_BASE_URL!,
+      clientId: process.env.FLUENT_CLIENT_ID!,
+      clientSecret: process.env.FLUENT_CLIENT_SECRET!
+      // retailerId is OPTIONAL for GraphQL queries (only required for Job/Event API)
+    },
+  });
+  console.log('✓ Client created\n');
+
+  // Step 2: Define GraphQL query
+  console.log('Step 2: Defining GraphQL query...');
+  const query = `
+    query ExtractInventory($first: Int!, $after: String) {
+      inventoryPositions(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            ref
+            productRef
+            locationRef
+            qty
+            status
+            createdOn
+            updatedOn
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+    }
+  `;
+
+  console.log('✓ Query defined');
+  console.log('  Fields: id, ref, productRef, locationRef, qty, status, createdOn, updatedOn\n');
+
+  // Step 3: Execute with auto-pagination
+  console.log('Step 3: Executing query with auto-pagination...');
+  console.log('  Page size: 100 records');
+  console.log('  Max records: 10,000');
+  console.log('');
+
+  try {
+    const result = await client.graphql({
+      query,
+      variables: { first: 100 },
+      pagination: {
+        maxRecords: 10000,
+        onProgress: (page, totalRecords) => {
+          console.log(`  Page ${page}: ${totalRecords} records fetched`);
+        },
+      },
+    });
+
+    console.log('\n✓ Extraction complete\n');
+
+    // Step 4: Process results
+    console.log('Step 4: Processing results...');
+    const records = result.data.inventoryPositions.edges.map(e => e.node);
+
+    // Display statistics
+    console.log('\n=== Extraction Statistics ===');
+    console.log(`Total records: ${records.length}`);
+    console.log(`Pages fetched: ${result.extensions.autoPagination.totalPages}`);
+    console.log(`Time elapsed: ${result.extensions.autoPagination.timeElapsed}ms`);
+    console.log(
+      `Records/sec: ${((records.length / result.extensions.autoPagination.timeElapsed) * 1000).toFixed(0)}`
+    );
+
+    if (result.extensions.autoPagination.truncated) {
+      console.log('\n⚠️  Results truncated by safety limit');
+    }
+
+    // Display sample records
+    console.log('\n=== Sample Records (first 5) ===');
+    records.slice(0, 5).forEach((record, index) => {
+      console.log(`\n[${index + 1}] ${record.ref}`);
+      console.log(`    Product: ${record.productRef}`);
+      console.log(`    Location: ${record.locationRef}`);
+      console.log(`    Quantity: ${record.qty}`);
+      console.log(`    Status: ${record.status}`);
+    });
+
+    // Analyze data
+    console.log('\n=== Data Analysis ===');
+    const totalQuantity = records.reduce((sum, r) => sum + (parseInt(r.qty) || 0), 0);
+    const uniqueProducts = new Set(records.map(r => r.productRef)).size;
+    const uniqueLocations = new Set(records.map(r => r.locationRef)).size;
+
+    console.log(`Total quantity across all positions: ${totalQuantity}`);
+    console.log(`Unique products: ${uniqueProducts}`);
+    console.log(`Unique locations: ${uniqueLocations}`);
+
+    // Status breakdown
+    const statusCounts = records.reduce(
+      (acc, r) => {
+        const status = r.status || 'UNKNOWN';
+        acc[status] = (acc[status] || 0) + 1;
+        return acc;
+      },
+      {} as Record<string, number>
+    );
+
+    console.log('\nStatus breakdown:');
+    for (const [status, count] of Object.entries(statusCounts)) {
+      const percentage = ((count / records.length) * 100).toFixed(1);
+      console.log(`  ${status}: ${count} (${percentage}%)`);
+    }
+
+    return records;
+  } catch (error: any) {
+    console.error('\n✗ Extraction failed:', error.message);
+
+    if (error.message.includes('authentication')) {
+      console.error('\nAuthentication failed. Please check your credentials:');
+      console.error('  - FLUENT_CLIENT_ID');
+      console.error('  - FLUENT_CLIENT_SECRET');
+      console.error('  - FLUENT_RETAILER_ID');
+    } else if (error.message.includes('timeout')) {
+      console.error('\nRequest timeout. Try:');
+      console.error('  - Reducing page size');
+      console.error('  - Reducing maxRecords limit');
+    } else {
+      console.error('\nUnexpected error. Check:');
+      console.error('  - Network connectivity');
+      console.error('  - FLUENT_BASE_URL is correct');
+      console.error('  - GraphQL query syntax');
+    }
+
+    throw error;
+  }
+}
+
+// Run the extraction
+if (require.main === module) {
+  // Validate environment variables
+  const requiredEnvVars = [
+    'FLUENT_BASE_URL',
+    'FLUENT_CLIENT_ID',
+    'FLUENT_CLIENT_SECRET',
+    'FLUENT_RETAILER_ID',
+  ];
+
+  const missing = requiredEnvVars.filter(v => !process.env[v]);
+
+  if (missing.length > 0) {
+    console.error('❌ Missing required environment variables:');
+    missing.forEach(v => console.error(`   - ${v}`));
+    console.error('\nPlease set these variables and try again.');
+    process.exit(1);
+  }
+
+  // Run extraction
+  extractInventoryBasic()
+    .then(() => {
+      console.log('\n✓ Extraction workflow complete');
+      process.exit(0);
+    })
+    .catch(error => {
+      console.error('\n✗ Extraction workflow failed:', error.message);
+      process.exit(1);
+    });
+}
+
+export { extractInventoryBasic };