The Airdrop SDK for TypeScript helps developers build snap-ins that integrate with DevRev’s Airdrop platform. This SDK simplifies the workflow for handling data extraction and loading, event-driven actions, state management, and artifact handling.
It provides features such as:
- Type Definitions: Structured types for Airdrop control protocol
- Event Management: Easily emit events for different extraction or loading phases
- State Handling: Update and access state in real-time within tasks
- Artifact Management: Supports batched storage of artifacts
- Error & Timeout Support: Error handling and timeout management for long-running tasks
npm install @devrev/ts-adaasThis function initializes a new worker thread and oversees its lifecycle. It should be invoked when the snap-in receives a message from the Airdrop platform. The worker script provided then handles the event accordingly.
spawn({ event, initialState, workerPath, options })-
event
Required. An object of type AirdropEvent that is received from the Airdrop platform.
-
initialState
Required. Object of any type that represents the initial state of the snap-in.
-
workerPath
Required. A string that represents the path to the worker file.
-
options
Optional. An object of type WorkerAdapterOptions, which will be passed to the newly created worker. This worker will then initialize a
WorkerAdapterby invoking theprocessTaskfunction. The options include:-
isLocalDevelopmentA boolean flag. If set to
true, intermediary files containing extracted data will be stored on the local machine, which is useful during development. The default value isfalse. -
timeoutA number that specifies the timeout duration for the lambda function, in milliseconds. The default is 10 minutes (10 * 60 * 1000 milliseconds), with a maximum allowable duration of 13 minutes (13 * 60 * 1000 milliseconds).
-
batchSizeA number that determines the maximum number of items to be processed and saved to an intermediary file before being sent to the Airdrop platform. The default batch size is 2,000.
-
A promise that resolves once the worker has completed processing.
const run = async (events: AirdropEvent[]) => {
for (const event of events) {
const file = getWorkerPerExtractionPhase(event);
await spawn<ExtractorState>({
event,
initialState,
workerPath: file,
});
}
};The processTask function retrieves the current state from the Airdrop platform and initializes a new WorkerAdapter.
It executes the code specified in the task parameter, which contains the worker's functionality.
If a timeout occurs, the function handles it by executing the onTimeout callback, ensuring the worker exits gracefully.
Both functions receive an adapter parameter, representing the initialized WorkerAdapter object.
processTask({ task, onTimeout })-
task
Required. A function that defines the logic associated with the given event type.
-
onTimeout
Required. A function managing the timeout of the lambda invocation, including saving any necessary progress at the time of timeout.
// External sync units extraction
processTask({
task: async ({ adapter }) => {
const httpClient = new HttpClient(adapter.event);
const todoLists = await httpClient.getTodoLists();
const externalSyncUnits: ExternalSyncUnit[] = todoLists.map((todoList) => normalizeTodoList(todoList));
await adapter.emit(ExtractorEventType.ExtractionExternalSyncUnitsDone, {
external_sync_units: externalSyncUnits,
});
},
onTimeout: async ({ adapter }) => {
await adapter.emit(ExtractorEventType.ExtractionExternalSyncUnitsError, {
error: {
message: 'Failed to extract external sync units. Lambda timeout.',
},
});
},
});Used to interact with Airdrop platform. Provides utilities to emit events to the Airdrop platform, update the state of the snap-in and upload artifacts (files with data) to the platform.
new WorkerAdapter({
event,
adapterState,
options,
});-
event
Required. An object of type AirdropEvent that is received from the Airdrop platform.
-
adapterState
Required. An object of type State, which represents the initial state of the adapter.
-
options
Optional. An object of type WorkerAdapterOptions that specifies additional configuration options for the
WorkerAdapter. This object is passed via thespawnfunction.
const adapter = new WorkerAdapter<ConnectorState>({
event,
adapterState,
options,
});Getter and setter methods for working with the adapter state.
// get state
const adapterState = adapter.state;
// set state
adapter.state = newAdapterState;export const initialState: ExtractorState = {
users: { completed: false },
tasks: { completed: false },
attachments: { completed: false },
};
adapter.state = initialState;Initializes a Repo object for each item provided.
adapter.initializeRepos(repos);-
repos
Required. An array of objects of type
RepoInterface.
This should typically be called within the function passed as a parameter to the processTask function in the data extraction phase.
const repos = [
{
itemType: 'tasks',
normalize: normalizeTask,
}
];
adapter.initializeRepos(repos);Finds a Repo from the initialized repos.
adapter.getRepo(itemType);-
itemType
Required. A string that represents the itemType property for the searched repo.
An object of type Repo if the repo is found, otherwise undefined.
This should typically be called within the function passed as a parameter to the processTask function.
// Push users to the repository designated for 'users' data.
await adapter.getRepo('users')?.push(users);Emits an event to the Airdrop platform.
adapter.emit( newEventType, data ):-
newEventType
Required. The event type to be emitted, of type ExtractorEventType or LoaderEventType.
-
data
Optional. An object of type EventData which represents the data to be sent with the event.
A promise, which resolves to undefined after the emit function completes its execution or rejects with an error.
This should typically be called within the function passed as a parameter to the processTask function.
// Emitting successfully finished data extraction.
await adapter.emit(ExtractorEventType.ExtractionDataDone);
// Emitting a delay in attachments extraction phase.
await adapter.emit(ExtractorEventType.ExtractionAttachmentsDelay, {
delay: 10,
});
