@syncmatters/connector-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SyncMatters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @syncmatters/connector-sdk
+
+TypeScript type definitions for the **SyncMatters Connector SDK**.
+
+This is a **types-only** package: it provides IntelliSense and type checking when developing
+SyncMatters connectors locally (for example in VS Code or Cursor). Connector code executes on the
+SyncMatters platform, which provides the runtime implementation of this SDK.
+
+## Usage
+
+```js
+import SDK from "@syncmatters/connector-sdk";
+
+export default class MyConnector {
+  /** @param {SDK.InitArgs} args @returns {Promise<void>} */
+  async init(args) {
+    SDK.verifyType(this);
+    // ...
+  }
+
+  /** @returns {Promise<SDK.TestResult>} */
+  async test() {
+    // ...
+  }
+}
+```
+
+Add `"checkJs": true` to your `jsconfig.json` to activate the JSDoc type annotations used in
+connector `.mjs` files.
+
+## Legacy package name
+
+`@ihq/connector-sdk` is the legacy name of this package (IntegrateHQ is now SyncMatters).
+Existing connectors importing the legacy name continue to work on-platform.
+
+## Support
+
+- <https://syncmatters.com>
+- <support@syncmatters.com>

package/index.d.ts

@@ -0,0 +1,3 @@
+import * as SDK from "./module.js";
+export default SDK;
+export * from "./module.js";

package/index.js

@@ -0,0 +1 @@
+throw new Error("This package contains type definitions only - connector and script code executes on the SyncMatters platform. See https://syncmatters.com");

package/lib/connector-error.d.ts

@@ -0,0 +1,38 @@
+import { CodedError } from "@syncmatters/script-api";
+/** ErrorCode values are common to all connectors. */
+export declare enum ErrorCode {
+    None = "CONN_NONE" /** default */,
+    ApiReportedError = "CONN_API_REPORTED_ERROR",
+    ApiTokenGenerationTerminated = "CONN_API_TOKEN_GENERATION_TERMINATED",
+    ApiUrlNotSupported = "CONN_API_URL_NOT_SUPPORTED",
+    InvalidApiKey = "CONN_INVALID_API_KEY",
+    InvalidFieldId = "CONN_INVALID_FIELD_ID",
+    InvalidFieldMeta = "CONN_INVALID_FIELD_METADATA",
+    InvalidCacheFileId = "CONN_INVALID_CACHE_FILE_ID",
+    InvalidCacheFilter = "CONN_INVALID_CACHE_FILTER",
+    InvalidCachePageFormat = "CONN_INVALID_CACHE_PAGE_FORMAT",
+    InvalidCacheRowKey = "CONN_INVALID_CACHE_ROW_KEY",
+    InvalidFilePath = "CONN_INVALID_FILE_PATH",
+    InvalidFilterParameter = "CONN_INVALID_FILTER_PARAMETER",
+    InvalidObjectId = "CONN_INVALID_OBJECT_ID",
+    InvalidEventId = "CONN_INVALID_EVENT_ID",
+    InvalidOperation = "CONN_INVALID_OPERATION",
+    InvalidOptionValue = "CONN_INVALID_OPTION_VALUE",
+    InvalidPassword = "CONN_INVALID_PASSWORD",
+    InvalidRecordId = "CONN_INVALID_RECORD_ID",
+    InvalidQueryResponse = "CONN_INVALID_QUERY_RESPONSE",
+    InvalidRelationshipMeta = "CONN_INVALID_RELATIONSHIP_METADATA",
+    InvalidUserName = "CONN_INVALID_USERNAME",
+    NotImplimented = "CONN_NOT_IMPLEMENTED",
+    ResourceAlreadyClosed = "CONN_RESOURCE_CLOSED"
+}
+/**
+ * ConnectorError extends error to expose a meaningful error code & optionally type-specific
+ * useful data for handling the error e.g.const err = new SDK.ConnectorError(SDK.ErrorCode.InvalidOptionValue,
+ * "supplied option not valid", {issues: [{objectId: "Deals", fieldId: "sales_rep", option: "Bob Smith"}]});
+ */
+export declare class ConnectorError extends Error implements CodedError {
+    readonly code: string;
+    readonly data: unknown;
+    constructor(code: ErrorCode, message?: string, data?: unknown);
+}

package/lib/connector.d.ts

@@ -0,0 +1,470 @@
+import { EventTypeMeta, Logger, ObjectField, UpsertIssue, ObjectIndex, ObjectMeta, ObjectMetaUpsert, Row, TestResult, ScriptType, UpsertFieldOptionMeta, QueryMatchFilter, QueryCheckpointFilter, JsonValuePathPart, SyncSession, ObjectFieldOption, RowMatchRuleType, SyncOptimalBatchSizeOperation, SyncOptimalBatchSizeBatchType } from "@syncmatters/script-api";
+import SDK from "../index.js";
+/**
+ * InitArgs are passed as the only argument to the connector init() function.
+ */
+export interface InitArgs {
+    /** id uniquely identifies the connection instance within the scripting environment */
+    readonly id: string;
+    /** display name of the connection */
+    readonly name: string;
+    /** identity is optionally returned by the meta() call and may supply a useful, system
+     * specific, identifier of the identity of the connection (e.g. email address used to
+     * connect) */
+    readonly identity?: string;
+    /** mode holds the reason for which the connection is being created */
+    readonly mode: ScriptType;
+    /** log can write messages to the platform log */
+    readonly log: Logger;
+    /** sourcePath is the directory holding the main connector file */
+    readonly sourcePath: string;
+    /** webhookUrl is connection specific webhook url */
+    readonly webhookUrl?: string;
+    /** webhookUid is a globally unique string used within the connection specific webhook url */
+    readonly webhookUid?: string;
+    /** settings holds the configured connection instance settings */
+    readonly settings: Map<string, any>;
+    /** if the connection has a managet OAuth2 token this provider will grant access to the access token */
+    oauth2Provider?: OAuth2TokenProvider;
+}
+/**
+ * Connector represents a connection to a system, exposing meta data and data.
+ */
+export interface Connector {
+    /** init is called exactly once for each instance of a connector reference by a script. */
+    init?(args: InitArgs): Promise<void>;
+    /** test attempts to connect to the system, so validating credentials and basic settings. */
+    test(): Promise<TestResult>;
+    /** meta connects to the system to retrieve system, object and field definitions (metadata). */
+    meta(): Promise<ConnectorMeta>;
+    /**
+     * query connects to the system to retrieve data from the object with the given id. The connector manages
+     * state needed for multi-page quesies using parameter 'queryState'. On the first call to query() 'queryState'
+     * will be undefined; on subseqent calls the 'queryState' will be supplied, holding the value of the 'queryState'
+     * returned by the prior call to query().
+     */
+    query?(options: QueryOptions): Promise<QueryPage>;
+    /** @deprecated cacheRefreshSpec generates the queryFilter etc ... needed to initate a refresh of the objects cached data. */
+    cacheRefreshOptions?(options: RefreshSpecOptions): Promise<RefreshSpec>;
+    /** upsert adds/updates records in the target system, returning rows in "query" result format. */
+    upsert?(options: UpsertOptions): Promise<Row[]>;
+    /** upsertClean may test whether the upsert request is well formed and repair/remove invalid field values. */
+    upsertClean?(options: UpsertCleanOptions): Promise<UpsertCleanResponse>;
+    /** upsertFieldOptions adds/updates field option values to picklist style fields. */
+    upsertFieldOptions?(options: UpsertOptionsOptions): Promise<UpsertOptionsResponse>;
+    /** delete records from the target system, returning the key's of deleted rows. */
+    delete?(options: DeleteOptions): Promise<Row[]>;
+    /** the endpoint can recommend batch sizes to used when querying/updating/deleting data */
+    optimalBatchSize?(options: OptimalBatchSizeOptions): Promise<OptimalBatchSizeResponse>;
+    /** parseEvents receives raw event payloads from webhooks and transforms it to ParsedEvent format. */
+    parseEvents?(optons: ParseEventsOptions): Promise<ParsedEvents>;
+    /**
+     * handleParsedEvent processes events emitted by the parseEvents(...) produces changed records that may be used
+     * to keep the cache up to date - e.g. some systems emit record deleted events, this handler can notify the cache
+     * that records have been deleted. This method is optional.
+     */
+    handleParsedEvent?(options: HandleParsedEventOptions): Promise<void>;
+    /** [optional] inpliment sync session begin/end if the connector needs to bootstrap internal caching for a sync group run */
+    syncSessionBegin?(session: SyncSession): Promise<void>;
+    syncSessionEnd?(session: SyncSession): Promise<void>;
+    /**
+     * [optional] implement this method if unmanaged resources must be destroyed when the process exits. Note that this
+     * function is run on a best-effort basis - i.e. it is possible for the process to exit abnormally without calling
+     * this method. */
+    dispose?(options: DisposeOptions): Promise<void>;
+    /**
+     * base may be implimented by a connector to return an underlying object that can be used to interact directly
+     * with a source system.
+     * <p>
+     * Note: connectors are often developed on top of 3rd party libraries. In such cases, for diagnostic reasons, it
+     * is appropriate to allow direct access to the instantiated instance of the base library via this method.
+     * </p>
+     */
+    base?(): Promise<any>;
+}
+/** verifyType may be used to check whether the connector class correctly impliments Connector */
+export declare function verifyType(_connector: Connector): void;
+/** QueryOptions are passed to the query function. */
+export interface QueryOptions {
+    /** log can record to the platform event store */
+    log: Logger;
+    /** id of the object being queried */
+    id: string;
+    /** metadata from the object being queried */
+    meta: ObjectMeta;
+    /** request cached metadata from any object on the connection */
+    objectMeta(id: string): Promise<ObjectMeta>;
+    /** request checkpoint data from a previous saved checkpointFilter */
+    checkpointData(checkpoint: string): Promise<SDK.FileProvider>;
+    /** options to apply to the query */
+    queryOptions?: {
+        /** max rows to return */
+        limit?: number;
+        /** should the reponse include a file for each row? */
+        file?: boolean;
+        /** fields the caller expects in the response */
+        fields?: Array<Array<JsonValuePathPart>>;
+        /** include fields needed to collect rows from selected relationships */
+        relationshipFields?: Array<string>;
+        /** retrieve a random sample of up to 'limit' records */
+        randomFilter?: boolean;
+        /** filter for rows by row id (key) */
+        idsFilter?: Array<string>;
+        /** filter for rows related to other rows */
+        relatedFilter?: QueryRelatedFilter;
+        /** filter for rows that meet a specific matching rule */
+        matchFilter?: QueryMatchFilter;
+        /** collect records changed since a particular checkpoint */
+        checkpointFilter?: QueryCheckpointFilter;
+        /** system specific row filters */
+        rowFilter?: any;
+        /** system specific property filters */
+        propertyFilter?: any;
+    };
+    queryState?: any;
+}
+/** QueryRelatedFilter holds filters to apply when querying rows from this object that relate to rows from another object. */
+export interface QueryRelatedFilter {
+    /** id of the other object for which related rows from this object are sought */
+    otherObjectId: string;
+    /** unique id of the relationship defined on the other object that describes how other object rows relate to rows on
+     * this object */
+    otherRelationshipId: string;
+    /** rows from the other object for which related rows from this object are sought */
+    otherRows: Array<Row>;
+}
+/** ParseEventsOptions are passed to the connector parseEvents(...) function. */
+export interface ParseEventsOptions {
+    /** request cached metadata from any object on the connection */
+    objectMeta(id: string): Promise<ObjectMeta>;
+    /** verify the hash of the payload using a server side managed key */
+    verifyHash: (options: {
+        strategy: "OAuth2.Sha256.Hex" | "OAuth2.Md5.Hex";
+        expression: string;
+        expected: string;
+    }) => Promise<{
+        success: boolean;
+    }>;
+    /** the raw event payload */
+    payload: {
+        webhookUid: string;
+        uri: string;
+        headers: {
+            [name: string]: string[];
+        };
+        method: string;
+        body: Buffer;
+    };
+}
+/** ParsedEvents are returned from the parseEvents(...) function. */
+export interface ParsedEvents {
+    events: ParsedEvent[];
+}
+/** ParsedEvent holds the details of an event as parsed by connector parseEvents(...) */
+export interface ParsedEvent {
+    eventIdentity: string;
+    uniqueId?: string;
+    typeId: string;
+    timestamp: number;
+    object?: {
+        id: string;
+        key: string;
+    };
+    data?: any;
+}
+/** HandleParsedEventOptions are passed to the handleParsedEvent function.  */
+export interface HandleParsedEventOptions {
+    id: string;
+    meta: ObjectMeta;
+    event: {
+        id: string;
+        timestamp: number;
+        key?: string;
+        data?: any;
+    };
+    reportChanges: (changes: {
+        id: string;
+        page: QueryPage;
+    }) => Promise<void>;
+}
+/** QueryPage is a page of data returned in response to a query. */
+export interface QueryPage {
+    /** rows of data from the page. */
+    rows: Row[];
+    /** Connector should store query specific details to the queryState, with subsequent calls passing the state back to
+     * the query(...) call.
+     * Typically holds pointers such as 'offset' and 'pageSize'. Only the first call to query(...) will have no queryState. */
+    queryState?: any;
+    /** Only applicable to checkpointFilter queries when returning the last row.. This should hold the next checkpoint filter
+     *  the caller should pass to retrieve rows that
+     *  were added/updated since this checkpoint query ran. Typlically only available when finalPage=true */
+    checkpoint?: string;
+    /** Only applicable to checkpointFilter queries when returning the last row. Can attach a file holding any required state
+     *  needed to respond to a future query to collect the rows from the checkpoint */
+    checkpointData?: SDK.FileProvider;
+    /** @deprecated cacheState is persisted for use across multiple integration runs. It is passed to cacheRefreshOptions(...)
+     * to allow preparation of
+     *  the query filter to pass to cache.refresh.ObjectId(...) in order to perform a differential refresh of the cached data. */
+    cacheState?: any;
+    /** Connector may set to true to indicate the query has no more pages of data return. Returning no QueryPage, no queryState
+     * or no rows has the same effect. */
+    finalPage?: boolean;
+}
+/** RefreshSpecOptions is passed to the cacheRefreshSpec function. */
+export interface RefreshSpecOptions {
+    id: string;
+    meta: ObjectMeta;
+    cacheState: any;
+}
+/** RefreshSpec holds connector specific options needed to initiate a cache refresh. */
+export interface RefreshSpec {
+    clearCache?: boolean;
+    queryOptions?: {
+        limit?: number;
+        rowFilter?: any;
+        propertyFilter?: any;
+    };
+}
+/** UpsertCleanOptions is passed to the upsertClean function. */
+export interface UpsertCleanOptions {
+    /** log can record to the platform event store */
+    log: Logger;
+    /** the ObjectId */
+    id: string;
+    /** Object field definitions etc ... */
+    meta: ObjectMeta;
+    /** request cached metadata from any object on the connection */
+    objectMeta(id: string): Promise<ObjectMeta>;
+    /** the row being upserted */
+    upsert: any;
+    /** the current row to compare with the upsert to detect changes */
+    current?: SDK.Row;
+    /** reference to the upsert field the caller would like populated with details of identified issues - included
+     * to allow the connector override the default strategy used to resolve the 'currentIssues' from the 'current'
+     * row as some connectors have the Upsert row shaped differently to the Query row (default strategy: the 'currentIssues'
+     * string is expected to be found here 'current.data.{path/jsonPath}') */
+    issuesField?: {
+        path?: string[];
+        jsonPath?: string;
+    };
+    /** tests whether values in the upsert's picklist fields represent valid options, identifies issues and optionally
+     * resolves or cleanses. */
+    verifyFieldOptions: (options: {
+        cleanAction: "DeleteUpsertField" | "None";
+        meta?: (fieldPath: string[], id: any) => UpsertFieldOptionMeta;
+        matchByName?: {
+            disabled?: boolean;
+            accept?: (fieldPath: string[], id: string, matchedName: string) => boolean;
+        };
+    }) => Promise<Array<UpsertIssue>>;
+    /** tests whether values in the upsert's fields meet the field constraints, identifies issues and cleanses. */
+    verifyFieldConstraints: (options?: {
+        timeZone?: string;
+    }) => Promise<Array<UpsertIssue>>;
+    /** detects the first change in the upsert when compared to the current row */
+    detectFirstChange: (options?: DetectFirstChangeOptions) => UpsertCleanResponse["change"] | undefined;
+}
+/** DetectFirstChangeOptions are passed to the detectFirstChange function. */
+export interface DetectFirstChangeOptions {
+    /** confirmChange is an optional handler that can confirm the change is real/reportable */
+    confirmChange?: (options: ConfirmChangeOptions) => boolean;
+    /** optionally override the default behavior of the detectFirstChange function */
+    overrides?: {
+        /** treat null as not equal to an empty array */
+        nullDoesNotEqualEmptyArray?: boolean;
+        /** treat null as not equal to an empty string */
+        nullDoesNotEqualEmptyString?: boolean;
+        /** treat null as not equal to an empty object */
+        nullDoesNotEqualEmptyObject?: boolean;
+        /** do not treat array element removal as a change */
+        doNotTreatArrayElementRemovalAsChange?: boolean;
+    };
+}
+/** ConfirmChangeOptions are passed to the optional confirmChange handler function */
+export interface ConfirmChangeOptions {
+    /** id of the object being upserted */
+    objectId: string;
+    /** path to the field that is being upserted */
+    fieldPath: string[];
+    /** metadata for the field that is being upserted */
+    fieldMeta?: ObjectField;
+    /** the value of the field before the upsert */
+    oldValue?: any;
+    /** the value of the field after the upsert */
+    newValue?: any;
+}
+/** UpsertCleanResponse is returned from the upsertClean function. */
+export interface UpsertCleanResponse {
+    /** indicates that changes were detected (ie. the row needed to be upserted) */
+    hasChanges: boolean;
+    /** details of the first change found */
+    change?: {
+        field: string;
+        oldValue?: string;
+        newValue?: string;
+    };
+    /** details of issues (includes any issues that were 'cleansed' to resolve) */
+    issues: UpsertIssue[];
+    /** if the default strategy to resolve 'currentIssues' from the 'current' row is overridden by the connector then
+     * 'currentIssues' should be extracted from 'current' row & returned here as a resolved/blank string (null/undefined
+     * indicates the detault strategy should be used) */
+    currentIssues?: string;
+}
+/** UpsertOptions is passed to the upsert function. */
+export interface UpsertOptions {
+    /** log can record to the platform event store */
+    log: Logger;
+    /** id of the object being updated */
+    id: string;
+    /** metadata from the object being updated */
+    meta: ObjectMeta;
+    /** request cached metadata from any object on the connection */
+    objectMeta(id: string): Promise<ObjectMeta>;
+    /** rows to be written */
+    rows: any[];
+}
+/** UpsertOptionsOptions is passed to the upsertFieldOptions function. */
+export interface UpsertOptionsOptions {
+    /** log can record to the platform event store */
+    log: Logger;
+    /** id of the object being updated */
+    id: string;
+    /** metadata from the object being updated */
+    meta: ObjectMeta;
+    /** request cached metadata from any object on the connection */
+    objectMeta(id: string): Promise<ObjectMeta>;
+    /** path to the field that is to have options updated */
+    fieldPath: string[];
+    /** picklist options to be added / updated */
+    options: Array<{
+        id: string;
+        meta?: {
+            name?: string;
+            order?: string;
+            pipeline?: string;
+            probability?: string;
+        };
+    }>;
+}
+/** UpsertOptionsResponse is returned from the upsertFieldOptions function. */
+export interface UpsertOptionsResponse {
+    /** holds details of option id's that were created/found in the system (e.g. system may
+     * generate its own unique option id's) */
+    resolvedIds: Array<{
+        id: string;
+        resolvedId: string;
+    }>;
+    /** count of new options added */
+    added: number;
+    /** count of existing options updated */
+    updated: number;
+    /** count of existing options that need not be changed */
+    unchanged: number;
+    /** count of options that could not be added/updated */
+    unresolved: number;
+    /** optionally return changed object metadata to avoid meta refresh */
+    metaUpdate?: {
+        /** changed options to be applied to the object, will apply to both query & upsert fields (use if the options are the only change) */
+        objectFieldOptions?: ObjectFieldOption[];
+        /** updated upsert field to be applied to the object (use if other field metadata changes are required) */
+        upsertField?: ObjectField;
+        /** updated query field to be applied to the object, same path as upsert field (use if other field metadata changes are required) */
+        queryField?: ObjectField;
+        /** updated objects to be applied to the connection (use if other object metadata changes are required) */
+        objects?: ObjectMetaUpsert[];
+    };
+}
+/** DeleteOptions is passed to the delete function. */
+export interface DeleteOptions {
+    /** log can record to the platform event store */
+    log: Logger;
+    /** id of the object that will have rows deleted */
+    id: string;
+    /** metadata from the object that will have rows deleted */
+    meta: ObjectMeta;
+    /** request cached metadata from any object on the connection */
+    objectMeta(id: string): Promise<ObjectMeta>;
+    /** connector specific details of rows to delete */
+    rows: any[];
+}
+/** OptimalBatchSizeOptions is passed to the optimalBatchSize function. */
+export interface OptimalBatchSizeOptions {
+    /** id of the object for which batch size info is sought */
+    id: string;
+    /** metadata from the object */
+    meta: ObjectMeta;
+    /** operation to determine the optimal batch size for */
+    operation: SyncOptimalBatchSizeOperation;
+    /** for relatedFilter operation, the other object id and relationship id may refine the response */
+    relatedFilter?: {
+        otherObjectId: string;
+        otherRelationshipId: string;
+    };
+    /** for matchFilter operation, the rule may refine the response */
+    matchFilter?: RowMatchRuleType;
+}
+/** OptimalBatchSizeResponse is returned from the optimalBatchSize function. */
+export interface OptimalBatchSizeResponse {
+    /** ideal batch size for the operation */
+    size: number;
+    /** for upsert & delete operations, optionally describe how batching behaves */
+    batchType?: SyncOptimalBatchSizeBatchType;
+}
+/** DisposeOptions is passed to the dispose function. */
+export interface DisposeOptions {
+    /** log can record to the platform event store */
+    log: Logger;
+}
+/** ConnectorMeta provides access to connector metadata. */
+export interface ConnectorMeta {
+    identity?: string;
+    objects: ObjectMetaUpsert[] | ObjectMetaSummary[];
+    events?: {
+        /** event identity should only be provided if the connector has a webhook mode of "per connector" */
+        identity?: string;
+        /** event types describe the events presented by this connecion */
+        types: EventTypeMeta[];
+    };
+}
+/** @deprecated ObjectMetaSummary provides access to a summary info for a single object. */
+export interface ObjectMetaSummary {
+    id: string;
+    name?: string;
+    order?: string;
+    detail: () => Promise<ObjectMetaDetail>;
+}
+/** @deprecated ObjectMetaDetail provides detailed info for a single object. */
+export interface ObjectMetaDetail {
+    queryFields?: ObjectField[];
+    queryFilter?: {
+        rowFilter?: ObjectField[];
+        propertyFilter?: ObjectField[];
+    };
+    queryFile?: boolean;
+    upsertFields?: ObjectField[];
+    deleteFields?: ObjectField[];
+    canUpsertClean?: boolean;
+    canUpsertFieldOptions?: boolean;
+    canAddCustomRelationships?: boolean;
+    systemIndexes?: ObjectIndex[];
+    data?: any;
+}
+/**
+ * OAuth2TokenProvider provides access to the auto-refreshing OAuth2 access token. Register a callback to the onRefresh
+ * event to e.g. auto update HTTP authentication headers.
+ */
+export interface OAuth2TokenProvider {
+    token: string;
+    authParams: {
+        [key: string]: string | string[];
+    };
+    /** called when the background process refreshes the token */
+    onRefresh: (cb: (token: string) => void) => void;
+    /** force an immediate refresh of the access token (only needed if token expiry is any) */
+    forceRefresh: () => Promise<void>;
+    /** introspect the current access token */
+    introspectToken?: () => Promise<unknown>;
+    scope?: string;
+    expiry?: number;
+    tokenExtras?: any;
+}

package/lib/environment.d.ts

@@ -0,0 +1,45 @@
+import { FileProvider, KvStore } from "@syncmatters/script-api";
+/**
+ * ApiSpec defines a temporary, dynamic API endpoint that will be hosted by the nodejs process; it will be torn down when
+ * the script
+ */
+export interface ApiSpec {
+    path: string;
+    apiKey: string;
+    handler: (request: ApiRequest, response: ApiResponse) => Promise<void>;
+}
+/** ApiRequest holds the request received at the cusom endpoint */
+export interface ApiRequest {
+    params: {
+        [name: string]: string;
+    };
+    body: any;
+    headers: {
+        [name: string]: string | string[] | undefined;
+    };
+    method: string;
+    path: string;
+    url: string;
+}
+/** ApiResponse is used by the custom api handler to send a response to the caller */
+export interface ApiResponse {
+    send: (code: number, body?: any) => void;
+}
+/**
+ * Environment is presented to the hosting platform. It uses dependency injection to supply production implementations
+ * of connector support classes for use within connector code, e.g. const limit = new SDK.RateLimiter();
+ */
+export interface Environment {
+    kvStore: () => KvStore;
+    fileProviderDisk: (path: string, deleteOnClose?: boolean) => FileProvider;
+    fileProviderBuffer: (source: Buffer) => FileProvider;
+    fileProviderString: (source: string) => FileProvider;
+    openApi3: (options: any) => any;
+    serveApi: (options: ApiSpec) => string;
+}
+/**
+ * envSet is called by the hosting platform to supply the runtime environment components.
+ * @param env
+ */
+export declare function envSet(env: Environment): void;
+export declare function envGet(): Environment;

package/lib/file-provider-buffer.d.ts

@@ -0,0 +1,11 @@
+import { FileProvider } from "@syncmatters/script-api";
+export declare class FileProviderBuffer implements FileProvider {
+    constructor(source: Buffer);
+    length(): Promise<number>;
+    stream(): Promise<NodeJS.ReadableStream>;
+    formDataValue(encoding?: "utf8" | "utf16le" | "ucs2"): Promise<unknown>;
+    blob(fileName?: string): Promise<Blob>;
+    save(path?: string): Promise<string>;
+    close(): Promise<void>;
+    toJSON(): string;
+}

package/lib/file-provider-disk.d.ts

@@ -0,0 +1,11 @@
+import { FileProvider } from "@syncmatters/script-api";
+export declare class FileProviderDisk implements FileProvider {
+    constructor(path: string, deleteOnClose?: boolean);
+    length(): Promise<number>;
+    stream(): Promise<NodeJS.ReadableStream>;
+    formDataValue(encoding?: "utf8" | "utf16le" | "ucs2"): Promise<unknown>;
+    blob(fileName?: string): Promise<Blob>;
+    save(path?: string): Promise<string>;
+    close(): Promise<void>;
+    toJSON(): string;
+}

package/lib/file-provider-string.d.ts

@@ -0,0 +1,11 @@
+import { FileProvider } from "@syncmatters/script-api";
+export declare class FileProviderString implements FileProvider {
+    constructor(source: string);
+    length(): Promise<number>;
+    stream(): Promise<NodeJS.ReadableStream>;
+    formDataValue(encoding?: "utf8" | "utf16le" | "ucs2"): Promise<unknown>;
+    blob(fileName?: string): Promise<Blob>;
+    save(path?: string): Promise<string>;
+    close(): Promise<void>;
+    toJSON(): string;
+}

package/lib/http-client.d.ts

@@ -0,0 +1,10 @@
+import API from "@syncmatters/script-api";
+/**
+ * This class exists as Connector SDK 1.0 exposed HttpClient as a helper class. Later this was moved to follow the API.utilities.helperFunc(...)
+ * paradigm to provide better consistency between the SDK and API.
+ */
+export declare class HttpClient {
+    #private;
+    constructor(options?: API.HttpClientOptions);
+    execute(r: API.HttpRequest): Promise<any>;
+}

package/lib/kv-store.d.ts

@@ -0,0 +1,7 @@
+import { KvStore as KvStoreIF, KvCollection } from "@syncmatters/script-api";
+export declare class KvStore implements KvStoreIF {
+    constructor();
+    open<T>(name: string): Promise<KvCollection<T>>;
+    close(name: string): Promise<void>;
+    exit(): Promise<void>;
+}

package/lib/open-api-3.d.ts

@@ -0,0 +1,30 @@
+import * as API from "@syncmatters/script-api";
+import { Logger, HttpClientOptions, RateLimiter, RateLimiterOptions } from "@syncmatters/script-api";
+import { OAuth2TokenProvider } from "./connector.js";
+export interface OpenApi3Options {
+    specPathYaml: string;
+    oauth2?: {
+        oauth2Provider: OAuth2TokenProvider;
+        securityName: string;
+    };
+    apiKey?: {
+        key: string;
+        securityName: string;
+    };
+    basicAuth?: {
+        username: string;
+        password: string;
+        securityName: string;
+    };
+    rateLimiterOptions?: RateLimiterOptions;
+    httpClientOverrides?: HttpClientOptions;
+    serverOverride?: string;
+    errLog?: Logger;
+}
+export declare class OpenApi3 {
+    static createAsync(options: OpenApi3Options): Promise<OpenApi3>;
+    private constructor();
+    get rateLimiter(): RateLimiter | undefined;
+    get httpClient(): typeof API.utilities.httpClient | undefined;
+    get apis(): any;
+}

package/lib/path-utils.d.ts

@@ -0,0 +1,18 @@
+export declare const PathUtils: {
+    pathify: typeof pathify;
+    unpathify: typeof unpathify;
+};
+/**
+ * converts an array of strings into a fully-qualified JSONPath path string, escaping
+ * part names as required (i.e. "\" becomes "\\" and "." becomes "\.").
+ * @param array The array to be converted
+ * @returns the converted string
+ */
+declare function pathify(array: string[]): string;
+/**
+ * converts a pathified string into an un-escaped array of path parts.
+ * @param pathStr the string to be un-pathified
+ * @returns the converted array, or undefined if no string is passed
+ */
+declare function unpathify(pathStr: string): string[];
+export {};

package/lib/rate-limiter.d.ts

@@ -0,0 +1,14 @@
+import API from "@syncmatters/script-api";
+/**
+ * This class exists as Connector SDK 1.0 exposed RateLimiter as a helper class. Later this was moved to follow the API.utilities.helperFunc(...)
+ * paradigm to provide better consistency between the SDK and API.
+ */
+export declare class RateLimiter implements API.RateLimiter {
+    #private;
+    constructor(options: API.RateLimiterOptions);
+    take(cost?: number): Promise<void>;
+    execute<T>(options: {
+        cost?: number;
+        exec: () => Promise<T>;
+    }): Promise<T>;
+}

package/lib/serve-api.d.ts

@@ -0,0 +1,4 @@
+import { ApiSpec } from "./environment.js";
+export declare class ServeApi {
+    static serveApi(options: ApiSpec): string;
+}

package/lib/utilities.d.ts

@@ -0,0 +1,9 @@
+import API, { ObjectField } from "@syncmatters/script-api";
+import { ServeApi } from "./serve-api.js";
+type ConnectorUtilities = typeof API.utilities & {
+    fieldsFromJSON: typeof fieldsFromJSON;
+    serveApi: typeof ServeApi.serveApi;
+};
+export declare const utilities: ConnectorUtilities;
+declare function fieldsFromJSON(json: any): ObjectField[];
+export {};

package/module.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Connector SDK (SDK) is a fusion of elements from the script API and
+ * SDK specific elements that would be of no interest to users of the API.
+ */
+export { EventScriptComplete } from "@syncmatters/script-api";
+export type { Cache, FileProvider, HttpRequest, HttpClientOptions, KvCollection, KvIterator, Logger, EventContext, TestResult, Row, ObjectMeta, ObjectField, ObjectFieldOption, RateLimiterOptions, ScriptType, } from "@syncmatters/script-api";
+export * from "./lib/connector.js";
+export * from "./lib/connector-error.js";
+export { envSet } from "./lib/environment.js";
+export type { Environment, ApiRequest, ApiResponse, ApiSpec } from "./lib/environment.js";
+export { FileProviderBuffer } from "./lib/file-provider-buffer.js";
+export { FileProviderDisk } from "./lib/file-provider-disk.js";
+export { FileProviderString } from "./lib/file-provider-string.js";
+export { OpenApi3 } from "./lib/open-api-3.js";
+export type { OpenApi3Options } from "./lib/open-api-3.js";
+export * from "./lib/kv-store.js";
+export { utilities } from "./lib/utilities.js";
+export { RateLimiter } from "./lib/rate-limiter.js";
+export { HttpClient } from "./lib/http-client.js";

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@syncmatters/connector-sdk",
+  "version": "1.0.0",
+  "description": "TypeScript type definitions for the SyncMatters connector SDK (types only - connectors execute on the SyncMatters platform)",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "license": "MIT",
+  "author": "SyncMatters",
+  "homepage": "https://syncmatters.com",
+  "typesContentHash": "39bdb6461d3d6962e0d284c2f4b6c71f1d08a6cd6a4b422754b3c731414fe6da",
+  "dependencies": {
+    "@types/node": "*",
+    "@syncmatters/script-api": "^1.0.0"
+  }
+}