@oneplatform/plugin-sdk / Connector
Interface: Connector¶
Defined in: packages/plugin-sdk/src/types/connector.ts:65
Methods¶
connect()¶
connect(
config,context):Promise\<ConnectorHandle>
Defined in: packages/plugin-sdk/src/types/connector.ts:84
Validate the plugin configuration and credentials, and establish a connection. Called once per ingestion job before the first fetchBatch call.
This method should be fast (< 5 seconds). If the external service requires a round-trip for auth (e.g., OAuth token refresh), do it here and cache the token in the context.cache.
Parameters¶
config¶
Record\<string, unknown>
context¶
Returns¶
Promise\<ConnectorHandle>
Throws¶
PluginConfigError if config is invalid or missing required fields.
Throws¶
PluginAuthError if credential validation fails.
disconnect()¶
disconnect(
handle,context):Promise\<void>
Defined in: packages/plugin-sdk/src/types/connector.ts:132
Clean up the connection. Called after the ingestion job completes or on error. Must not throw. If cleanup fails, log the error and return.
Resources to release: HTTP connections, open file handles, WebSocket connections. Do NOT revoke OAuth tokens here — they may be reused by the next ingestion run.
Parameters¶
handle¶
context¶
Returns¶
Promise\<void>
fetchBatch()¶
fetchBatch(
handle,cursor,context):Promise\<BatchResult>
Defined in: packages/plugin-sdk/src/types/connector.ts:101
Fetch the next batch of records from the external system.
cursor=null signals the first call (fetch from the beginning of available data). For incremental syncs, the cursor is the value returned by the previous fetchBatch. The platform stores the last successful cursor and resumes from it on retry.
Batch size should be controlled by the connector, typically 100-1000 records. Avoid batches larger than 10,000 records — the platform's ingestion queue has per-message limits.
Parameters¶
handle¶
cursor¶
string | null
context¶
Returns¶
Promise\<BatchResult>
Throws¶
PluginRateLimitError if the external API returns 429.
Throws¶
PluginTimeoutError if a network call exceeds the configured timeout.
Throws¶
PluginAuthError if the connection credentials have expired.
metadata()¶
metadata():
ConnectorMetadata
Defined in: packages/plugin-sdk/src/types/connector.ts:71
Return the connector's metadata. Called by the Plugin Service at install time to verify the entrypoint is valid, and by the Ingestion Service to display connector details in the data source catalog.
Returns¶
subscribeToEvents()?¶
optionalsubscribeToEvents(handle,callback,context):Promise\<Subscription>
Defined in: packages/plugin-sdk/src/types/connector.ts:119
Subscribe to real-time change events from the external system. Only implement if ConnectorMetadata.supportsRealtime is true.
The platform calls this method once when a real-time data source is activated. The callback receives individual change events as they arrive. Each callback invocation is an async operation — the connector must await it before processing the next event to maintain ordering.
The returned Subscription must remain active until unsubscribe() is called, which happens when the tenant disables real-time on the data source.
Parameters¶
handle¶
callback¶
context¶
Returns¶
Promise\<Subscription>