@syncmatters/script-api 1.0.14 → 1.0.16

package/lib/connection.d.ts

@@ -17,6 +17,9 @@ export interface Connection {
         events: {
             [id: string]: () => Promise<EventTypeMeta>;
         };
+        discovery?(): Promise<DiscoverResult | undefined>;
+        /** Metadata refresh and discovery times recorded as connection state (`{ objects: {} }` when none recorded). */
+        readonly state: MetaState;
     };
     query: {
         [id: string]: (options?: QueryOptions) => QueryIterator<Row>;
@@ -33,12 +36,22 @@ export interface Connection {
     delete?: {
         [id: string]: (rows: any[]) => Promise<void>;
     };
-    /** Id's of all objects found on this connection. */
+    /** Id's of all objects collected on this connection. */
     objectIds: string[];
     /** Connect to the source, validating credentials etc ... */
     test(): Promise<TestResult>;
-    /** Retrieves the latest meta data (identity, object, field definitions, event types) from the connector. */
-    metaRefresh?(): Promise<void>;
+    /**
+     * Collects the catalogue of objects present in the system, without field detail, can also return setting defaults and caches the result. Does not change the
+     * selection or any setting. Present only when the connector implements discover().
+     */
+    discover?(): Promise<DiscoverResult>;
+    /**
+     * Retrieves the latest meta data (identity, object, field definitions, event types) from the connector.
+     * @param options.objectIds [optional] refresh only these objects.
+     */
+    metaRefresh?(options?: {
+        objectIds?: string[];
+    }): Promise<void>;
     /**
      * Creates/updates the meta data model of a connection. This method is only applicable to connectors with
      * data models that are managed by platform or user logic rather than through interrogation of the source application.
@@ -205,7 +218,7 @@ export interface QueryOptions {
     /** @deprecated  (use standard fields filter) system specific property filters; allowed values are defined in meta.queryFilter.propertyFilter */
     propertyFilter?: any;
 }
-export type RowMatchRuleType = "id" /** match by source row id (key) */ | "name[ci]" /** match by destination row name (case senstive) */ | "email[ci]" /** match by destination row email (case insenstive) */ | "domain[ci]" /** match by destination domain (case insenstive) */ | "first_and_last_name[ci]" /** match by destination first and last name (case insenstive) */ | "field_value_equals[ci]"; /** match by value in user selected field (case insenstive) */
+export type RowMatchRuleType = "id" /** match by source row id (key) */ | "name[ci]" /** match by destination row name (case insensitive) */ | "email[ci]" /** match by destination row email (case insensitive) */ | "domain[ci]" /** match by destination domain (case insensitive) */ | "first_and_last_name[ci]" /** match by destination first and last name (case insensitive) */ | "field_value_equals[ci]" /** match by value in user selected field (case insensitive) */ | "field_values_equal[ci]"; /** match by 1-5 user selected source/destination field pairs, all must be equal (case insensitive) */
 export type RowMatchRuleOrder = "oldest" | "newest" | "alphabetical";
 /** source row data used by the destination connector when matching a source row to a destination row */
 export interface RowMatchData {
@@ -227,6 +240,11 @@ export interface RowMatchData {
         lastname?: string;
         /** custom value to match */
         custom?: string | number;
+        /**
+         * field_values_equal[ci]: values to match, index-aligned with QueryMatchFilter.destFieldPaths. A blank ("") value
+         * means the destination field must be empty/absent - filter for "empty", never drop the filter.
+         */
+        customs?: Array<string | number>;
     };
 }
 /** unique ids (property names) used in the row match data passed to the destination when a match is saught */
@@ -300,6 +318,11 @@ export interface QueryMatchFilter {
     selectOrder?: RowMatchRuleOrder;
     /** if the rule references a field in the destination row the path to the destination field will be specified here (e.g. match value in a specific field) */
     destFieldPath?: Array<API.JsonValuePathPart>;
+    /**
+     * field_values_equal[ci]: paths to the destination fields to compare, index-aligned with RowMatchData.match.customs;
+     * a destination row matches when every pair is equal
+     */
+    destFieldPaths?: Array<Array<API.JsonValuePathPart>>;
     /** data to match */
     srcData: Array<RowMatchData>;
     /**
@@ -360,6 +383,48 @@ export interface ObjectMeta {
     systemIndexes?: ObjectIndex[];
     /** relationships that may be used to find rows of this object that relate to other objects */
     relationships?: ObjectRelationship[];
+    /** should the object be selected for inclusion on a new connection? */
+    default?: boolean;
+    /** set by meta() when a selected object can no longer be described (e.g. deleted); the platform keeps the cached copy */
+    unavailable?: ObjectUnavailableReason;
+}
+/**
+ * ObjectUnavailableReason describes why a selected object could not be returned in hte meta refresh response: "deleted" (gone
+ * from the system) or "unauthorized" (the API user may no longer read it).
+ */
+export type ObjectUnavailableReason = "deleted" | "unauthorized";
+/** DiscoveredObject is a catalogue object returned by discover(): a subset of {@link ObjectMeta}, same ids and meanings. */
+export type DiscoveredObject = Pick<ObjectMeta, "id" | "name" | "order" | "isCustom" | "data" | "default">;
+/** DiscoverResult is returned by the connector's discover() and cached on the connection. */
+export interface DiscoverResult {
+    /**
+     * Recommended per-setting default values, probed by the connector, only applied if the user has not set a value.
+     */
+    settingsMeta?: Record<string, Partial<ObjectSettingMeta>>;
+    /** every object the connector could describe, without field detail */
+    objects: DiscoveredObject[];
+    /** connector-private; echoed back as MetaOptions.discovery.data */
+    data?: unknown;
+}
+/** MetaStateObject holds the refresh state of one selected object. */
+export interface MetaStateObject {
+    /** ISO time the object's metadata was last refreshed */
+    lastRefresh: string;
+    /** set when the last refresh reported the object as unavailable */
+    unavailable?: ObjectUnavailableReason;
+}
+/** MetaState holds metadata refresh and discovery times, recorded as connection state rather than configuration. */
+export interface MetaState {
+    /** ISO time discover() last succeeded */
+    lastDiscovery?: string;
+    /** ISO time of the last successful meta() covering the all selected objects */
+    lastRefresh?: string;
+    /** an 'affectsMeta' or 'prerequisite' setting changed since lastRefresh */
+    metaStale?: boolean;
+    /** a prerequisite setting changed after lastDiscovery */
+    discoveryStale?: boolean;
+    /** refresh state per selected object */
+    objects: Record<string, MetaStateObject>;
 }
 /** ObjectSettingMeta holds metadata describing a setting */
 export interface ObjectSettingMeta {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/script-api",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "TypeScript type definitions for the SyncMatters script API (types only - scripts execute on the SyncMatters platform)",
   "types": "./index.d.ts",
   "exports": {
@@ -28,7 +28,7 @@
   "license": "MIT",
   "author": "SyncMatters",
   "homepage": "https://syncmatters.com",
-  "typesContentHash": "1908da7a9d689fba3b76a80a652493ef9028ab6cebb2e1c08db9f2cc3cb9ffa5",
+  "typesContentHash": "ded988637cd580ceb7908990a4b80426f350619a0a067f24f49b9ccf3fc51967",
   "dependencies": {
     "@types/node": "*"
   }

package/sdk-test/sdk-test.d.ts

@@ -354,6 +354,8 @@ export interface MatchData {
     srcData: API.RowMatchData[];
     /** path to the field on the dest row that holds the field to match with, if applicable to the rule */
     destFieldPath?: API.JsonValuePath;
+    /** field_values_equal[ci]: paths to the dest row fields to match with, index-aligned with srcData[].match.customs */
+    destFieldPaths?: API.JsonValuePath[];
     /** ids of dest rows expected back in response to the match query */
     expectedMatchRowIds: string[];
     /** optionally specify the fields to include in the match query */