npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.54 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.54 → 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 (475) hide show

package/docs/02-CORE-GUIDES/advanced-services/advanced-services-job-tracker.md CHANGED Viewed

@@ -1,627 +1,627 @@
-# JobTracker
-**Level:** Advanced
-**Category:** Production Services
-**Purpose:** Track job lifecycle and status across workflows
-## Overview
-`JobTracker` provides standardized job status tracking for Fluent Commerce integrations. It manages job lifecycle from creation through completion or failure, with automatic timestamp tracking and TTL support for cleanup.
-## Use Cases
-- ✅ Monitor scheduled workflow progress
-- ✅ Track webhook-triggered operations
-- ✅ Implement job retry logic
-- ✅ Display job status in dashboards
-- ✅ Debug failed jobs in production
-- ✅ Track processing stages (extraction → transformation → ingestion)
----
-## Installation
-```typescript
-import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-```
----
-## Basic Usage
-### Create and Track a Job
-```typescript
-import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-// Initialize tracker
-const kv = new VersoriKVAdapter(openKv(':project:'));
-const tracker = new JobTracker(kv, logger);
-// Create job
-const jobId = `scheduled_${Date.now()}`;
-await tracker.createJob(jobId, {
-  triggeredBy: 'schedule',
-  stage: 'initialization',
-  details: {
-    catalogueRef: 'DEFAULT:1',
-    workflow: 'inventory-sync'
-  }
-});
-// Update as processing
-await tracker.updateJob(jobId, {
-  status: 'processing',
-  stage: 'extraction',
-  message: 'Extracting inventory positions'
-});
-// Update stage
-await tracker.updateJob(jobId, {
-  stage: 'transformation',
-  message: 'Transforming 1000 records'
-});
-// Mark complete
-await tracker.markCompleted(jobId, {
-  recordCount: 1000,
-  fileName: 'inventory-2025-01-30.xml',
-  s3Key: 'exports/inventory-2025-01-30.xml'
-});
-```
----
-## API Reference
-### Constructor
-```typescript
-new JobTracker(
-  kv: KVAdapter,
-  logger: StructuredLogger,
-  ttl?: number
-)
-```
-**Parameters:**
-- `kv` - KV adapter (VersoriKVAdapter or custom implementation)
-- `logger` - Structured logger
-- `ttl` - Optional TTL in seconds (default: 604800 = 7 days)
-**Example:**
-```typescript
-const tracker = new JobTracker(
-  kvAdapter,
-  logger,
-  86400 // 24 hours
-);
-```
----
-### createJob()
-Create a new job with 'queued' status.
-```typescript
-await tracker.createJob(
-  jobId: string,
-  metadata: Partial<JobStatus>
-): Promise<void>
-```
-**Parameters:**
-- `jobId` - Unique job identifier (recommend timestamp-based: `scheduled_${Date.now()}`)
-- `metadata` - Initial job metadata
-  - `triggeredBy` - 'schedule' | 'webhook' | 'manual'
-  - `stage` - Current processing stage (optional)
-  - `message` - Human-readable message (optional)
-  - `details` - Additional job-specific data (optional)
-**Example:**
-```typescript
-await tracker.createJob('webhook_1706356800000', {
-  triggeredBy: 'webhook',
-  stage: 'validation',
-  message: 'Processing webhook payload',
-  details: {
-    webhookId: 'wh_123',
-    source: 'shopify'
-  }
-});
-```
----
-### updateJob()
-Update job status and metadata.
-```typescript
-await tracker.updateJob(
-  jobId: string,
-  updates: Partial<JobStatus>
-): Promise<void>
-```
-**Parameters:**
-- `jobId` - Job identifier
-- `updates` - Fields to update
-  - `status` - 'queued' | 'processing' | 'completed' | 'failed'
-  - `stage` - Current processing stage
-  - `message` - Status message
-  - `details` - Additional metadata (merged with existing)
-**Example:**
-```typescript
-// Update stage
-await tracker.updateJob(jobId, {
-  stage: 'transformation',
-  message: 'Mapping 500 records'
-});
-// Update status and stage
-await tracker.updateJob(jobId, {
-  status: 'processing',
-  stage: 'ingestion',
-  message: 'Submitting batches to Fluent API',
-  details: {
-    batchCount: 5,
-    recordsPerBatch: 100
-  }
-});
-```
----
-### markCompleted()
-Mark job as successfully completed.
-```typescript
-await tracker.markCompleted(
-  jobId: string,
-  finalDetails?: Record<string, any>
-): Promise<void>
-```
-**Parameters:**
-- `jobId` - Job identifier
-- `finalDetails` - Optional final metadata
-**Automatically sets:**
-- `status` = 'completed'
-- `completedAt` = current timestamp
-**Example:**
-```typescript
-await tracker.markCompleted(jobId, {
-  recordCount: 1000,
-  successCount: 995,
-  failedCount: 5,
-  durationMs: 45000,
-  fileName: 'export.xml',
-  s3Key: 'exports/2025/01/30/export.xml'
-});
-```
----
-### markFailed()
-Mark job as failed with error details.
-```typescript
-await tracker.markFailed(
-  jobId: string,
-  error: Error | string
-): Promise<void>
-```
-**Parameters:**
-- `jobId` - Job identifier
-- `error` - Error object or message
-**Automatically sets:**
-- `status` = 'failed'
-- `stage` = 'error'
-- `failedAt` = current timestamp
-- `message` = `"Job failed: {error message}"`
-- `error` = error message
-- `errorStack` = stack trace (if Error object)
-**Example:**
-```typescript
-try {
-  await processWorkflow();
-} catch (error) {
-  await tracker.markFailed(jobId, error);
-  throw error;
-}
-```
----
-### getJob()
-Retrieve current job status.
-```typescript
-const status = await tracker.getJob(
-  jobId: string
-): Promise<JobStatus | undefined>
-```
-**Returns:**
-- `JobStatus` object if job exists
-- `undefined` if job not found
-**Example:**
-```typescript
-const status = await tracker.getJob(jobId);
-if (status) {
-  console.log(`Job ${jobId} status: ${status.status}`);
-  console.log(`Current stage: ${status.stage}`);
-  console.log(`Message: ${status.message}`);
-  if (status.status === 'failed') {
-    console.error('Error:', status.error);
-  }
-} else {
-  console.log('Job not found or expired');
-}
-```
----
-## JobStatus Type
-```typescript
-interface JobStatus {
-  status: 'queued' | 'processing' | 'completed' | 'failed';
-  stage?: string;
-  message?: string;
-  createdAt?: string;         // ISO 8601 timestamp
-  startedAt?: string;          // Set when status becomes 'processing'
-  completedAt?: string;        // Set by markCompleted()
-  failedAt?: string;           // Set by markFailed()
-  triggeredBy: 'schedule' | 'webhook' | 'manual';
-  details?: Record<string, any>;
-  error?: string;              // Error message if failed
-  errorStack?: string;         // Stack trace if failed
-}
-```
----
-## Common Patterns
-### Pattern 1: Scheduled Workflow
-```typescript
-export const dailySync = schedule('daily-sync', '0 0 * * *').then(
-  http('process', { connection: 'fluent' }, async ctx => {
-    const { log, openKv } = ctx;
-    const kv = new VersoriKVAdapter(openKv(':project:'));
-    const tracker = new JobTracker(kv, log);
-    const jobId = `daily_sync_${Date.now()}`;
-    try {
-      // Create job
-      await tracker.createJob(jobId, {
-        triggeredBy: 'schedule',
-        stage: 'initialization'
-      });
-      // Extract
-      await tracker.updateJob(jobId, {
-        status: 'processing',
-        stage: 'extraction',
-        message: 'Extracting inventory data from Fluent'
-      });
-      const data = await extractInventory(client);
-      // Transform
-      await tracker.updateJob(jobId, {
-        stage: 'transformation',
-        message: `Transforming ${data.length} records`
-      });
-      const transformed = await transformData(data);
-      // Export
-      await tracker.updateJob(jobId, {
-        stage: 'export',
-        message: 'Uploading to SFTP'
-      });
-      await uploadToSftp(transformed);
-      // Complete
-      await tracker.markCompleted(jobId, {
-        recordCount: data.length,
-        fileName: 'export.xml'
-      });
-    } catch (error) {
-      await tracker.markFailed(jobId, error);
-      throw error;
-    }
-  })
-);
-```
----
-### Pattern 2: Webhook Handler
-```typescript
-export const webhookHandler = webhook('inventory-update', {
-  response: {
-    mode: 'sync',
-    onSuccess: (ctx) => new Response(
-      JSON.stringify({ status: 'accepted', jobId: ctx.data.jobId }),
-      { status: 202, headers: { 'Content-Type': 'application/json' } }
-    )
-  }
-}, async ctx => {
-  const { log, openKv, request } = ctx;
-  const kv = new VersoriKVAdapter(openKv(':project:'));
-  const tracker = new JobTracker(kv, log);
-  const jobId = `webhook_${Date.now()}`;
-  try {
-    // Create job
-    await tracker.createJob(jobId, {
-      triggeredBy: 'webhook',
-      stage: 'validation',
-      message: 'Validating webhook payload'
-    });
-    // Validate
-    const payload = await request.json();
-    validatePayload(payload);
-    // Process
-    await tracker.updateJob(jobId, {
-      status: 'processing',
-      stage: 'ingestion',
-      message: `Ingesting ${payload.items.length} items`
-    });
-    await processInventory(payload);
-    // Complete
-    await tracker.markCompleted(jobId, {
-      itemCount: payload.items.length
-    });
-    return { jobId, status: 'completed' };
-  } catch (error) {
-    await tracker.markFailed(jobId, error);
-    throw error;
-  }
-});
-```
----
-### Pattern 3: Job Retry Logic
-```typescript
-async function processWithRetry(jobId: string, maxRetries = 3) {
-  const tracker = new JobTracker(kv, logger);
-  for (let attempt = 1; attempt <= maxRetries; attempt++) {
-    try {
-      await tracker.updateJob(jobId, {
-        status: 'processing',
-        message: `Attempt ${attempt}/${maxRetries}`
-      });
-      await processWorkflow();
-      await tracker.markCompleted(jobId, {
-        attempts: attempt
-      });
-      return; // Success
-    } catch (error) {
-      if (attempt === maxRetries) {
-        // Final attempt failed - update with details before marking failed
-        await tracker.updateJob(jobId, {
-          details: {
-            attempts: attempt,
-            maxRetries
-          }
-        });
-        await tracker.markFailed(jobId, error);
-        throw error;
-      }
-      // Retry
-      await tracker.updateJob(jobId, {
-        message: `Attempt ${attempt} failed, retrying...`,
-        details: { lastError: error.message }
-      });
-      await sleep(1000 * attempt); // Exponential backoff
-    }
-  }
-}
-```
----
-### Pattern 4: Dashboard Status Display
-```typescript
-// Get status for dashboard
-const recentJobs = await Promise.all(
-  jobIds.map(id => tracker.getJob(id))
-);
-const summary = {
-  total: recentJobs.length,
-  completed: recentJobs.filter(j => j?.status === 'completed').length,
-  processing: recentJobs.filter(j => j?.status === 'processing').length,
-  failed: recentJobs.filter(j => j?.status === 'failed').length,
-  queued: recentJobs.filter(j => j?.status === 'queued').length
-};
-console.log('Job Summary:', summary);
-// Show currently processing jobs
-const activeJobs = recentJobs.filter(j => j?.status === 'processing');
-activeJobs.forEach(job => {
-  console.log(`${job.stage}: ${job.message}`);
-});
-```
----
-## TTL and Cleanup
-Jobs are automatically cleaned up after TTL expires.
-**Default TTL:** 7 days (604800 seconds)
-**Custom TTL:**
-```typescript
-// 24 hours
-const tracker = new JobTracker(kv, logger, 86400);
-// 30 days
-const tracker = new JobTracker(kv, logger, 2592000);
-```
-**Disable TTL:**
-```typescript
-const tracker = new JobTracker(kv, logger, 0);
-```
----
-## Error Handling
-`JobTracker` is designed to never throw on KV errors. All operations log warnings but continue execution.
-```typescript
-// Safe - never throws
-await tracker.createJob(jobId, metadata);
-await tracker.updateJob(jobId, updates);
-await tracker.markCompleted(jobId);
-// Even if KV is unavailable, your workflow continues
-```
-**Logging:**
-```typescript
-// On KV error, tracker logs warning:
-logger.warn('Failed to update job status', {
-  jobId,
-  error: error.message
-});
-// But doesn't throw - your workflow continues
-```
----
-### 1. Use Timestamp-Based Job IDs
-```typescript
-const jobId = `scheduled_${Date.now()}`;
-const jobId = `inventory_sync_${Date.now()}`;
-```
-### 2. Update Stage Frequently
-```typescript
-await tracker.updateJob(jobId, { stage: 'extraction', message: 'Fetching data' });
-await tracker.updateJob(jobId, { stage: 'transformation', message: 'Mapping 1000 records' });
-await tracker.updateJob(jobId, { stage: 'validation', message: 'Validating entities' });
-await tracker.updateJob(jobId, { stage: 'ingestion', message: 'Submitting batches' });
-```
-### 3. Include Useful Details
-```typescript
-await tracker.markCompleted(jobId, {
-  recordCount: 1000,
-  successCount: 995,
-  failedCount: 5,
-  durationMs: 45000,
-  s3Key: 'exports/file.xml',
-  batchCount: 10
-});
-```
-### 4. Always Mark Failed Jobs
-```typescript
-try {
-  await processWorkflow();
-  await tracker.markCompleted(jobId);
-} catch (error) {
-  await tracker.markFailed(jobId, error);
-  throw error;
-}
-```
----
-## Troubleshooting
-### Job Not Found
-**Problem:** `getJob()` returns `undefined`
-**Causes:**
-1. Job expired (TTL reached)
-2. Wrong jobId
-3. KV store cleared
-**Solution:**
-```typescript
-const status = await tracker.getJob(jobId);
-if (!status) {
-  logger.warn('Job not found', { jobId });
-  // Handle missing job
-}
-```
-### Jobs Stuck in 'processing'
-**Problem:** Jobs never reach 'completed' or 'failed'
-**Cause:** Missing `markCompleted()` or `markFailed()` calls
-**Solution:**
-```typescript
-// Always wrap in try/catch
-try {
-  await processWorkflow();
-  await tracker.markCompleted(jobId); // ✅
-} catch (error) {
-  await tracker.markFailed(jobId, error); // ✅
-  throw error;
-}
-```
----
-## See Also
-- [PartialBatchRecovery](./advanced-services-partial-batch-recovery.md) - Recover from partial failures
-- [State Management](../ingestion/modules/02-core-guides-ingestion-07-state-management.md) - File tracking
-- [Monitoring](./advanced-services-quick-reference.md) - Processing metrics (see JobTracker section)
-- [Advanced Services Overview](./advanced-services-readme.md) - All advanced services
----
-[← Back to Advanced Services](./advanced-services-readme.md) | [Next: PartialBatchRecovery →](./advanced-services-partial-batch-recovery.md)
+# JobTracker
+**Level:** Advanced
+**Category:** Production Services
+**Purpose:** Track job lifecycle and status across workflows
+## Overview
+`JobTracker` provides standardized job status tracking for Fluent Commerce integrations. It manages job lifecycle from creation through completion or failure, with automatic timestamp tracking and TTL support for cleanup.
+## Use Cases
+- ✅ Monitor scheduled workflow progress
+- ✅ Track webhook-triggered operations
+- ✅ Implement job retry logic
+- ✅ Display job status in dashboards
+- ✅ Debug failed jobs in production
+- ✅ Track processing stages (extraction → transformation → ingestion)
+---
+## Installation
+```typescript
+import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+```
+---
+## Basic Usage
+### Create and Track a Job
+```typescript
+import { JobTracker, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+// Initialize tracker
+const kv = new VersoriKVAdapter(openKv(':project:'));
+const tracker = new JobTracker(kv, logger);
+// Create job
+const jobId = `scheduled_${Date.now()}`;
+await tracker.createJob(jobId, {
+  triggeredBy: 'schedule',
+  stage: 'initialization',
+  details: {
+    catalogueRef: 'DEFAULT:1',
+    workflow: 'inventory-sync'
+  }
+});
+// Update as processing
+await tracker.updateJob(jobId, {
+  status: 'processing',
+  stage: 'extraction',
+  message: 'Extracting inventory positions'
+});
+// Update stage
+await tracker.updateJob(jobId, {
+  stage: 'transformation',
+  message: 'Transforming 1000 records'
+});
+// Mark complete
+await tracker.markCompleted(jobId, {
+  recordCount: 1000,
+  fileName: 'inventory-2025-01-30.xml',
+  s3Key: 'exports/inventory-2025-01-30.xml'
+});
+```
+---
+## API Reference
+### Constructor
+```typescript
+new JobTracker(
+  kv: KVAdapter,
+  logger: StructuredLogger,
+  ttl?: number
+)
+```
+**Parameters:**
+- `kv` - KV adapter (VersoriKVAdapter or custom implementation)
+- `logger` - Structured logger
+- `ttl` - Optional TTL in seconds (default: 604800 = 7 days)
+**Example:**
+```typescript
+const tracker = new JobTracker(
+  kvAdapter,
+  logger,
+  86400 // 24 hours
+);
+```
+---
+### createJob()
+Create a new job with 'queued' status.
+```typescript
+await tracker.createJob(
+  jobId: string,
+  metadata: Partial<JobStatus>
+): Promise<void>
+```
+**Parameters:**
+- `jobId` - Unique job identifier (recommend timestamp-based: `scheduled_${Date.now()}`)
+- `metadata` - Initial job metadata
+  - `triggeredBy` - 'schedule' | 'webhook' | 'manual'
+  - `stage` - Current processing stage (optional)
+  - `message` - Human-readable message (optional)
+  - `details` - Additional job-specific data (optional)
+**Example:**
+```typescript
+await tracker.createJob('webhook_1706356800000', {
+  triggeredBy: 'webhook',
+  stage: 'validation',
+  message: 'Processing webhook payload',
+  details: {
+    webhookId: 'wh_123',
+    source: 'shopify'
+  }
+});
+```
+---
+### updateJob()
+Update job status and metadata.
+```typescript
+await tracker.updateJob(
+  jobId: string,
+  updates: Partial<JobStatus>
+): Promise<void>
+```
+**Parameters:**
+- `jobId` - Job identifier
+- `updates` - Fields to update
+  - `status` - 'queued' | 'processing' | 'completed' | 'failed'
+  - `stage` - Current processing stage
+  - `message` - Status message
+  - `details` - Additional metadata (merged with existing)
+**Example:**
+```typescript
+// Update stage
+await tracker.updateJob(jobId, {
+  stage: 'transformation',
+  message: 'Mapping 500 records'
+});
+// Update status and stage
+await tracker.updateJob(jobId, {
+  status: 'processing',
+  stage: 'ingestion',
+  message: 'Submitting batches to Fluent API',
+  details: {
+    batchCount: 5,
+    recordsPerBatch: 100
+  }
+});
+```
+---
+### markCompleted()
+Mark job as successfully completed.
+```typescript
+await tracker.markCompleted(
+  jobId: string,
+  finalDetails?: Record<string, any>
+): Promise<void>
+```
+**Parameters:**
+- `jobId` - Job identifier
+- `finalDetails` - Optional final metadata
+**Automatically sets:**
+- `status` = 'completed'
+- `completedAt` = current timestamp
+**Example:**
+```typescript
+await tracker.markCompleted(jobId, {
+  recordCount: 1000,
+  successCount: 995,
+  failedCount: 5,
+  durationMs: 45000,
+  fileName: 'export.xml',
+  s3Key: 'exports/2025/01/30/export.xml'
+});
+```
+---
+### markFailed()
+Mark job as failed with error details.
+```typescript
+await tracker.markFailed(
+  jobId: string,
+  error: Error | string
+): Promise<void>
+```
+**Parameters:**
+- `jobId` - Job identifier
+- `error` - Error object or message
+**Automatically sets:**
+- `status` = 'failed'
+- `stage` = 'error'
+- `failedAt` = current timestamp
+- `message` = `"Job failed: {error message}"`
+- `error` = error message
+- `errorStack` = stack trace (if Error object)
+**Example:**
+```typescript
+try {
+  await processWorkflow();
+} catch (error) {
+  await tracker.markFailed(jobId, error);
+  throw error;
+}
+```
+---
+### getJob()
+Retrieve current job status.
+```typescript
+const status = await tracker.getJob(
+  jobId: string
+): Promise<JobStatus | undefined>
+```
+**Returns:**
+- `JobStatus` object if job exists
+- `undefined` if job not found
+**Example:**
+```typescript
+const status = await tracker.getJob(jobId);
+if (status) {
+  console.log(`Job ${jobId} status: ${status.status}`);
+  console.log(`Current stage: ${status.stage}`);
+  console.log(`Message: ${status.message}`);
+  if (status.status === 'failed') {
+    console.error('Error:', status.error);
+  }
+} else {
+  console.log('Job not found or expired');
+}
+```
+---
+## JobStatus Type
+```typescript
+interface JobStatus {
+  status: 'queued' | 'processing' | 'completed' | 'failed';
+  stage?: string;
+  message?: string;
+  createdAt?: string;         // ISO 8601 timestamp
+  startedAt?: string;          // Set when status becomes 'processing'
+  completedAt?: string;        // Set by markCompleted()
+  failedAt?: string;           // Set by markFailed()
+  triggeredBy: 'schedule' | 'webhook' | 'manual';
+  details?: Record<string, any>;
+  error?: string;              // Error message if failed
+  errorStack?: string;         // Stack trace if failed
+}
+```
+---
+## Common Patterns
+### Pattern 1: Scheduled Workflow
+```typescript
+export const dailySync = schedule('daily-sync', '0 0 * * *').then(
+  http('process', { connection: 'fluent' }, async ctx => {
+    const { log, openKv } = ctx;
+    const kv = new VersoriKVAdapter(openKv(':project:'));
+    const tracker = new JobTracker(kv, log);
+    const jobId = `daily_sync_${Date.now()}`;
+    try {
+      // Create job
+      await tracker.createJob(jobId, {
+        triggeredBy: 'schedule',
+        stage: 'initialization'
+      });
+      // Extract
+      await tracker.updateJob(jobId, {
+        status: 'processing',
+        stage: 'extraction',
+        message: 'Extracting inventory data from Fluent'
+      });
+      const data = await extractInventory(client);
+      // Transform
+      await tracker.updateJob(jobId, {
+        stage: 'transformation',
+        message: `Transforming ${data.length} records`
+      });
+      const transformed = await transformData(data);
+      // Export
+      await tracker.updateJob(jobId, {
+        stage: 'export',
+        message: 'Uploading to SFTP'
+      });
+      await uploadToSftp(transformed);
+      // Complete
+      await tracker.markCompleted(jobId, {
+        recordCount: data.length,
+        fileName: 'export.xml'
+      });
+    } catch (error) {
+      await tracker.markFailed(jobId, error);
+      throw error;
+    }
+  })
+);
+```
+---
+### Pattern 2: Webhook Handler
+```typescript
+export const webhookHandler = webhook('inventory-update', {
+  response: {
+    mode: 'sync',
+    onSuccess: (ctx) => new Response(
+      JSON.stringify({ status: 'accepted', jobId: ctx.data.jobId }),
+      { status: 202, headers: { 'Content-Type': 'application/json' } }
+    )
+  }
+}, async ctx => {
+  const { log, openKv, request } = ctx;
+  const kv = new VersoriKVAdapter(openKv(':project:'));
+  const tracker = new JobTracker(kv, log);
+  const jobId = `webhook_${Date.now()}`;
+  try {
+    // Create job
+    await tracker.createJob(jobId, {
+      triggeredBy: 'webhook',
+      stage: 'validation',
+      message: 'Validating webhook payload'
+    });
+    // Validate
+    const payload = await request.json();
+    validatePayload(payload);
+    // Process
+    await tracker.updateJob(jobId, {
+      status: 'processing',
+      stage: 'ingestion',
+      message: `Ingesting ${payload.items.length} items`
+    });
+    await processInventory(payload);
+    // Complete
+    await tracker.markCompleted(jobId, {
+      itemCount: payload.items.length
+    });
+    return { jobId, status: 'completed' };
+  } catch (error) {
+    await tracker.markFailed(jobId, error);
+    throw error;
+  }
+});
+```
+---
+### Pattern 3: Job Retry Logic
+```typescript
+async function processWithRetry(jobId: string, maxRetries = 3) {
+  const tracker = new JobTracker(kv, logger);
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      await tracker.updateJob(jobId, {
+        status: 'processing',
+        message: `Attempt ${attempt}/${maxRetries}`
+      });
+      await processWorkflow();
+      await tracker.markCompleted(jobId, {
+        attempts: attempt
+      });
+      return; // Success
+    } catch (error) {
+      if (attempt === maxRetries) {
+        // Final attempt failed - update with details before marking failed
+        await tracker.updateJob(jobId, {
+          details: {
+            attempts: attempt,
+            maxRetries
+          }
+        });
+        await tracker.markFailed(jobId, error);
+        throw error;
+      }
+      // Retry
+      await tracker.updateJob(jobId, {
+        message: `Attempt ${attempt} failed, retrying...`,
+        details: { lastError: error.message }
+      });
+      await sleep(1000 * attempt); // Exponential backoff
+    }
+  }
+}
+```
+---
+### Pattern 4: Dashboard Status Display
+```typescript
+// Get status for dashboard
+const recentJobs = await Promise.all(
+  jobIds.map(id => tracker.getJob(id))
+);
+const summary = {
+  total: recentJobs.length,
+  completed: recentJobs.filter(j => j?.status === 'completed').length,
+  processing: recentJobs.filter(j => j?.status === 'processing').length,
+  failed: recentJobs.filter(j => j?.status === 'failed').length,
+  queued: recentJobs.filter(j => j?.status === 'queued').length
+};
+console.log('Job Summary:', summary);
+// Show currently processing jobs
+const activeJobs = recentJobs.filter(j => j?.status === 'processing');
+activeJobs.forEach(job => {
+  console.log(`${job.stage}: ${job.message}`);
+});
+```
+---
+## TTL and Cleanup
+Jobs are automatically cleaned up after TTL expires.
+**Default TTL:** 7 days (604800 seconds)
+**Custom TTL:**
+```typescript
+// 24 hours
+const tracker = new JobTracker(kv, logger, 86400);
+// 30 days
+const tracker = new JobTracker(kv, logger, 2592000);
+```
+**Disable TTL:**
+```typescript
+const tracker = new JobTracker(kv, logger, 0);
+```
+---
+## Error Handling
+`JobTracker` is designed to never throw on KV errors. All operations log warnings but continue execution.
+```typescript
+// Safe - never throws
+await tracker.createJob(jobId, metadata);
+await tracker.updateJob(jobId, updates);
+await tracker.markCompleted(jobId);
+// Even if KV is unavailable, your workflow continues
+```
+**Logging:**
+```typescript
+// On KV error, tracker logs warning:
+logger.warn('Failed to update job status', {
+  jobId,
+  error: error.message
+});
+// But doesn't throw - your workflow continues
+```
+---
+### 1. Use Timestamp-Based Job IDs
+```typescript
+const jobId = `scheduled_${Date.now()}`;
+const jobId = `inventory_sync_${Date.now()}`;
+```
+### 2. Update Stage Frequently
+```typescript
+await tracker.updateJob(jobId, { stage: 'extraction', message: 'Fetching data' });
+await tracker.updateJob(jobId, { stage: 'transformation', message: 'Mapping 1000 records' });
+await tracker.updateJob(jobId, { stage: 'validation', message: 'Validating entities' });
+await tracker.updateJob(jobId, { stage: 'ingestion', message: 'Submitting batches' });
+```
+### 3. Include Useful Details
+```typescript
+await tracker.markCompleted(jobId, {
+  recordCount: 1000,
+  successCount: 995,
+  failedCount: 5,
+  durationMs: 45000,
+  s3Key: 'exports/file.xml',
+  batchCount: 10
+});
+```
+### 4. Always Mark Failed Jobs
+```typescript
+try {
+  await processWorkflow();
+  await tracker.markCompleted(jobId);
+} catch (error) {
+  await tracker.markFailed(jobId, error);
+  throw error;
+}
+```
+---
+## Troubleshooting
+### Job Not Found
+**Problem:** `getJob()` returns `undefined`
+**Causes:**
+1. Job expired (TTL reached)
+2. Wrong jobId
+3. KV store cleared
+**Solution:**
+```typescript
+const status = await tracker.getJob(jobId);
+if (!status) {
+  logger.warn('Job not found', { jobId });
+  // Handle missing job
+}
+```
+### Jobs Stuck in 'processing'
+**Problem:** Jobs never reach 'completed' or 'failed'
+**Cause:** Missing `markCompleted()` or `markFailed()` calls
+**Solution:**
+```typescript
+// Always wrap in try/catch
+try {
+  await processWorkflow();
+  await tracker.markCompleted(jobId); // ✅
+} catch (error) {
+  await tracker.markFailed(jobId, error); // ✅
+  throw error;
+}
+```
+---
+## See Also
+- [PartialBatchRecovery](./advanced-services-partial-batch-recovery.md) - Recover from partial failures
+- [State Management](../ingestion/modules/02-core-guides-ingestion-07-state-management.md) - File tracking
+- [Monitoring](./advanced-services-quick-reference.md) - Processing metrics (see JobTracker section)
+- [Advanced Services Overview](./advanced-services-readme.md) - All advanced services
+---
+[← Back to Advanced Services](./advanced-services-readme.md) | [Next: PartialBatchRecovery →](./advanced-services-partial-batch-recovery.md)