@syncmatters/connector-sdk 1.0.14 → 1.0.15

package/lib/connector.d.ts

@@ -1,4 +1,4 @@
-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 { EventTypeMeta, Logger, ObjectField, UpsertIssue, ObjectIndex, ObjectMeta, ObjectMetaUpsert, Row, TestResult, ScriptType, UpsertFieldOptionMeta, QueryMatchFilter, QueryCheckpointFilter, JsonValuePathPart, SyncSession, ObjectFieldOption, RowMatchRuleType, SyncOptimalBatchSizeOperation, SyncOptimalBatchSizeBatchType, DiscoverResult } from "@syncmatters/script-api";
 import SDK from "../index.js";
 /**
  * InitArgs are passed as the only argument to the connector init() function.
@@ -35,8 +35,15 @@ export interface Connector {
     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>;
+    /**
+     * [optional] discover returns the catalogue of objects present in the system, without field detail. Called after init() once the settings
+     * tagged as 'prerequisite' are entered by a user setting up the connection.
+     */
+    discover?(options: DiscoverOptions): Promise<DiscoverResult>;
+    /**
+     * meta connects to the system to retrieve system, object and field definitions (metadata).
+     */
+    meta(options?: MetaOptions): 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'
@@ -84,6 +91,30 @@ export interface Connector {
 }
 /** verifyType may be used to check whether the connector class correctly impliments Connector */
 export declare function verifyType(_connector: Connector): void;
+/** DiscoverOptions are passed to the discover function. */
+export interface DiscoverOptions {
+    /** log can record to the platform event store */
+    log: Logger;
+    /** first setup ("newConnection"), or a re-collect of an existing result ("refresh") */
+    reason: "newConnection" | "refresh";
+    /** the previous discovery result from this connection, if any */
+    previous?: DiscoverResult;
+}
+/** MetaOptions are passed to the meta function. */
+export interface MetaOptions {
+    /** log can record to the platform event store */
+    log: Logger;
+    /** objects the connection has selected; undefined = all */
+    selectedObjectIds?: string[];
+    /** subset of selectedObjectIds to refresh; undefined = all selected objects */
+    refreshObjectIds?: string[];
+    /** cached ObjectMeta for any object - returns undefined when nothing cached */
+    objectMeta(id: string): Promise<ObjectMeta | undefined>;
+    /** cached event types - returns undefined when nothing cached */
+    events(): Promise<ConnectorMeta["events"] | undefined>;
+    /** the cached discovery result - undefined discover() not implimented or when nothing cached */
+    discovery?: DiscoverResult;
+}
 /** QueryOptions are passed to the query function. */
 export interface QueryOptions {
     /** log can record to the platform event store */

package/module.d.ts

@@ -3,7 +3,7 @@
  * 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, JsonValuePath, JsonValuePathPart, QueryMatchFilter, QueryCheckpointFilter, EventTypeMeta, ObjectIndex, ObjectMetaUpsert, ObjectRowFilter, ObjectRelationship, ObjectFieldConstraints, ObjectSettingMeta, UpsertIssue, UpsertFieldOptionMeta, RowMatchRuleType, RowMatchData, RowMatchRuleOrder, SyncSession, SyncOptimalBatchSizeOperation, SyncOptimalBatchSizeBatchType, } from "@syncmatters/script-api";
+export type { Cache, FileProvider, HttpRequest, HttpClientOptions, KvCollection, KvIterator, Logger, EventContext, TestResult, Row, ObjectMeta, ObjectField, ObjectFieldOption, RateLimiterOptions, ScriptType, JsonValuePath, JsonValuePathPart, QueryMatchFilter, QueryCheckpointFilter, EventTypeMeta, ObjectIndex, ObjectMetaUpsert, ObjectRowFilter, ObjectRelationship, ObjectFieldConstraints, ObjectSettingMeta, ObjectUnavailableReason, DiscoverResult, DiscoveredObject, MetaState, MetaStateObject, UpsertIssue, UpsertFieldOptionMeta, RowMatchRuleType, RowMatchData, RowMatchRuleOrder, SyncSession, SyncOptimalBatchSizeOperation, SyncOptimalBatchSizeBatchType, } from "@syncmatters/script-api";
 export * from "./lib/connector.js";
 export * from "./lib/connector-error.js";
 export { envSet } from "./lib/environment.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/connector-sdk",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "TypeScript type definitions for the SyncMatters connector SDK (types only - connectors execute on the SyncMatters platform)",
   "types": "./index.d.ts",
   "exports": {
@@ -12,9 +12,9 @@
   "license": "MIT",
   "author": "SyncMatters",
   "homepage": "https://syncmatters.com",
-  "typesContentHash": "09f69999930df0f8199bfd417a03cfa1bb882d929614b96a26f8f52e7acab0f9",
+  "typesContentHash": "c428bbb8ebc48254d9a04ea22755a73f6579fcccfc31d639633a935688655fd3",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.15"
+    "@syncmatters/script-api": "^1.0.16"
   }
 }