feat: Add selective extraction and control protocol v2 feature examples

README.md

@@ -17,3 +17,18 @@ the name, according to Step 2 above.
 
 While developing the AirSync snap-in, make sure to refer to the
 [AirSync snap-in documentation](https://developer.devrev.ai/airsync).
+
+## Local Fixture Testing
+
+From the `code/` directory, you can run the built-in fixture runner to test the
+template locally:
+
+```bash
+npm start -- --fixturePath start_extracting_external_sync_units
+npm start -- --fixturePath start_extracting_data
+npm start -- --fixturePath start_extracting_data_selective
+npm start -- --fixturePath start_loading_data
+```
+
+The runner reads `code/.env` and resolves `${TODO_API_KEY}` in fixture files,
+so copy `code/.env.example` before running the fixtures.

code/.env.example

@@ -0,0 +1,2 @@
+# TODO: add External system specific variables that will be replaced in the Fixture tests that you want to run.
+TODO_API_KEY=test-api-key

code/fixtures/start_extracting_data/event.json

@@ -0,0 +1,14 @@
+{
+  "payload": {
+    "connection_data": {
+      "org_id": "test_org",
+      "org_name": "Test Organization",
+      "key": "${TODO_API_KEY}",
+      "key_type": "pat"
+    },
+    "event_type": "START_EXTRACTING_DATA",
+    "event_context": {
+      "external_sync_unit_id": "test_external_sync_unit_id"
+    }
+  }
+}

code/fixtures/start_extracting_data/state.json

@@ -0,0 +1,5 @@
+{
+  "todos": { "completed": false },
+  "users": { "completed": false },
+  "attachments": { "completed": false }
+}

code/fixtures/start_extracting_data_selective/event.json

@@ -0,0 +1,14 @@
+{
+  "payload": {
+    "connection_data": {
+      "org_id": "test_org",
+      "org_name": "Test Organization",
+      "key": "${TODO_API_KEY}",
+      "key_type": "pat"
+    },
+    "event_type": "START_EXTRACTING_DATA",
+    "event_context": {
+      "external_sync_unit_id": "test_external_sync_unit_id"
+    }
+  }
+}

code/fixtures/start_extracting_data_selective/extraction_scope.json

@@ -0,0 +1,5 @@
+{
+  "todos": { "extract": true },
+  "users": { "extract": false },
+  "attachments": { "extract": false }
+}

code/fixtures/start_extracting_data_selective/state.json

@@ -0,0 +1,5 @@
+{
+  "todos": { "completed": false },
+  "users": { "completed": false },
+  "attachments": { "completed": false }
+}

code/fixtures/start_extracting_external_sync_units/event.json

@@ -0,0 +1,12 @@
+{
+  "function_name": "extraction",
+  "payload": {
+    "event_type": "START_EXTRACTING_EXTERNAL_SYNC_UNITS"
+  },
+  "connection_data": {
+    "org_id": "test_org",
+    "org_name": "Test Organization",
+    "key": "${TODO_API_KEY}",
+    "key_type": "pat"
+  }
+}

code/fixtures/start_loading_data/event.json

@@ -0,0 +1,14 @@
+{
+  "payload": {
+    "connection_data": {
+      "org_id": "test_org",
+      "org_name": "Test Organization",
+      "key": "${TODO_API_KEY}",
+      "key_type": "pat"
+    },
+    "event_type": "START_LOADING_DATA",
+    "event_context": {
+      "external_sync_unit_id": "test_external_sync_unit_id"
+    }
+  }
+}

code/fixtures/start_loading_data/state.json

@@ -0,0 +1 @@
+{}

code/package.json

@@ -56,7 +56,7 @@
     "yargs": "^17.6.2"
   },
   "dependencies": {
-    "@devrev/ts-adaas": "1.18.0",
+    "@devrev/ts-adaas": "1.19.1-beta.0",
     "@devrev/typescript-sdk": "1.1.63",
     "axios": "^1.9.0",
     "dotenv": "^16.0.3",

code/src/functions/external-system/data-denormalization.ts

@@ -1,5 +1,5 @@
-import { ExternalSystemItem } from '@devrev/ts-adaas';
-import { ExternalTodo } from './types';
+import { ExternalSystemAttachment, ExternalSystemItem } from '@devrev/ts-adaas';
+import { ExternalAttachment, ExternalTodo } from './types';
 
 // TODO: Replace with the actual denormalization function for your external
 // system. This function should take the normalized object and transform it into
@@ -15,3 +15,16 @@ export function denormalizeTodo(item: ExternalSystemItem): ExternalTodo {
     modified_date: item.modified_date,
   };
 }
+
+// TODO: Replace with the actual denormalization function for attachments.
+// Maps the normalized ExternalSystemAttachment (as received from the loading
+// pipeline) back into the format expected by the external system API.
+export function denormalizeAttachment(item: ExternalSystemAttachment): ExternalAttachment {
+  return {
+    id: item.reference_id,
+    url: item.url,
+    file_name: item.file_name,
+    author_id: item.created_by_id,
+    parent_id: item.parent_id ?? item.parent_reference_id,
+  };
+}