@syncmatters/script-api 1.0.15 → 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.
@@ -370,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.15",
+  "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": "ad2f1f5cd5868f2362746920bfba5713dcf146857db7641a69ed90c72e101dff",
+  "typesContentHash": "ded988637cd580ceb7908990a4b80426f350619a0a067f24f49b9ccf3fc51967",
   "dependencies": {
     "@types/node": "*"
   }