@oronts/vendure-data-hub-plugin 0.1.0

package/docs/developer-guide/README.md

@@ -0,0 +1,124 @@
+# Developer Guide
+
+This guide covers the code-first DSL, architecture, and extending the Data Hub plugin.
+
+<p align="center">
+  <img src="../images/04-hooks-events.png" alt="Pipeline Hooks" width="700">
+  <br>
+  <em>Pipeline Hooks - Execute custom code at every stage of pipeline execution</em>
+</p>
+
+## Contents
+
+1. [Architecture Overview](./architecture.md) - How the plugin works internally
+2. [DSL Reference](./dsl/README.md)
+   - [Pipeline Builder](./dsl/pipeline-builder.md) - Building pipelines with TypeScript
+   - [Schema Reference](./dsl/schema-reference.md) - Complete TypeScript interface reference
+   - [Operators](./dsl/operators.md) - All transform operators
+   - [Examples](./dsl/examples.md) - Real-world pipeline examples
+3. [Testing Guide](./testing.md) - Unit, integration, and end-to-end testing
+4. [Extending the Plugin](./extending/README.md)
+   - [Custom Extractors](./extending/custom-extractors.md)
+   - [Custom Loaders](./extending/custom-loaders.md)
+   - [Custom Operators](./extending/custom-operators.md)
+   - [Event Subscriptions](./extending/events.md) - Subscribe to pipeline lifecycle events
+   - **Hook Scripts** - Register functions for data modification at any pipeline stage
+   - **Wizard Templates** - Add custom templates for import/export wizards
+5. [GraphQL API](./graphql-api.md) - API reference for integration
+
+## When to Use Code-First
+
+Use the code-first DSL when:
+
+- Pipelines are part of your deployment
+- You want type-safe configurations
+- Pipelines don't change frequently
+- You need version control for pipeline definitions
+
+Use the visual builder when:
+
+- Non-developers create pipelines
+- Rapid iteration is needed
+- Pipelines change frequently
+- You want immediate feedback
+
+## Quick Example
+
+```typescript
+import { createPipeline } from '@oronts/vendure-data-hub-plugin';
+
+const pipeline = createPipeline()
+    .name('Product Sync')
+    .description('Sync products from ERP system')
+    .trigger('schedule', { type: 'SCHEDULE', cron: '0 2 * * *' })
+    .extract('fetch-erp', {
+        adapterCode: 'httpApi',
+        connectionCode: 'erp-api',
+        url: '/products',
+        dataPath: 'data.products',
+    })
+    .transform('map-fields', {
+        operators: [
+            { op: 'rename', args: { from: 'product_name', to: 'name' } },
+            { op: 'rename', args: { from: 'product_sku', to: 'sku' } },
+            { op: 'slugify', args: { source: 'sku', target: 'slug' } },
+        ],
+    })
+    .load('upsert-products', {
+        adapterCode: 'productUpsert',
+        strategy: 'UPSERT',
+        matchField: 'slug',
+    })
+    .edge('schedule', 'fetch-erp')
+    .edge('fetch-erp', 'map-fields')
+    .edge('map-fields', 'upsert-products')
+    .build();
+```
+
+## Hook Scripts
+
+Register functions that can modify records at any pipeline stage:
+
+```typescript
+DataHubPlugin.init({
+    scripts: {
+        'validate-sku': async (records, context) => {
+            return records.filter(r => r.sku && String(r.sku).length > 0);
+        },
+    },
+})
+
+// Then in pipeline:
+const pipeline = createPipeline()
+    .name('Product Sync')
+    // ... steps ...
+    .hooks({
+        AFTER_EXTRACT: [{ type: 'SCRIPT', scriptName: 'validate-sku' }],
+    })
+    .build();
+```
+
+24 hook stages are available (18 for step types and 6 global): BEFORE/AFTER for each step type (EXTRACT, TRANSFORM, VALIDATE, ENRICH, ROUTE, LOAD, EXPORT, FEED, SINK), plus PIPELINE_STARTED/COMPLETED/FAILED, ON_ERROR/ON_RETRY/ON_DEAD_LETTER.
+
+## Type Safety
+
+The DSL is fully typed. TypeScript will catch errors like:
+
+- Invalid adapter codes
+- Missing required fields
+- Wrong operator arguments
+- Invalid edge connections
+
+```typescript
+// TypeScript error: Property 'invalidOption' does not exist
+.extract('fetch', {
+    adapterCode: 'httpApi',
+    invalidOption: true,  // Error!
+})
+```
+
+## Next Steps
+
+- [Architecture](./architecture.md) - Understand how it works
+- [Pipeline Builder](./dsl/pipeline-builder.md) - Start building with DSL
+- [Examples](./dsl/examples.md) - See real-world patterns