CONNECTOR SDK REFERENCE4 of 10

Handler Examples

Real-world examples of common handlers. Use these as a starting point and adapt to your system.

OverviewRead HandlerSearch HandlerWrite HandlerEvent HandlersBatch HandlerError Handling

Good handler practices

Validate input and scopes

Use ids for idempotency

Map to your system model

Return structured errors

Log with correlationId

Handle pagination

Respect timeouts

Keep handlers stateless

Handler context

jsonCopy

{
 "tenantId":"tenant_123",
 "connectorId":"ehr_acme",
 "correlationId":"req_0138...",
 "user":{"id":"usr_456","scopes":["patient.read"]},
 "config":{"baseUrl":"https://api.acme.com/v1"}
}

Notes

All handlers are async and return Promises

Throw MediloopConnectorError for expected failures

Use context.logger for all logs

Never store secrets in code

All times are ISO 8601 (UTC)

Read Handler Example

typescriptCopy

export async function read(resourceType, id, ctx): Promise<ReadResponse> {
 if (!id) throw new MediloopConnectorError('INVALID_REQUEST','id is required');
 const url = `${ctx.config.baseUrl}/${resourceType}/${id}`;
 const headers = { Authorization: `Bearer ${ctx.secrets.accessToken}` };
 const res = await ctx.http.get(url, { headers, timeout: ctx.config.timeoutMs });
 if (res.status === 404) throw new MediloopConnectorError('NOT_FOUND');
 if (!res.ok) throw new MediloopConnectorError('UPSTREAM_ERROR');
 const data = await res.json();
 return { resourceType, resource: data, meta: { etag: data.meta?.versionId } };
}

Search Handler (excerpt)

typescriptCopy

export async function search(rt, query, ctx) {
 const url = ctx.config.baseUrl + '/' + rt + '?'+ query;
 return { resourceType:'Bundle', ...await ctx.http.get(url) };
}

Write Handler (create)

typescriptCopy

export async function write(rt, payload, ctx) {
 const res = await ctx.http.post(ctx.config.baseUrl+'/'+rt, payload);
 return { resourceType: rt, id: res.data.id };
}

Event Handler

typescriptCopy

export async function onEvent(event, ctx) {
 ctx.logger.info('event.received',{type:event.type,id:event.id});
 return context.emit(event);
}