@syncmatters/connector-sdk 1.0.13 → 1.0.15

package/docs/05-query.md

@@ -242,6 +242,16 @@ candidates }])` — the platform reserves un-mapped matches and returns the sele
 - **field_value_equals[ci]** - inspect the `match.custom` value and search in the selected `destFieldPath` (path to the field on the target system) to find rows holding this value (case insensitive) in this field.
 - **field_values_equal[ci]** - `destFieldPaths[k]` pairs with `match.customs[k]` (1-5 pairs); find rows where **every** pair is equal (case insensitive), i.e. `destFieldPaths[0] = customs[0] AND destFieldPaths[1] = customs[1] ...`. A `""` entry in `customs` means that destination field must be empty/absent: filter for "empty" (e.g. HubSpot `NOT_HAS_PROPERTY`, SOQL `= null`), never drop the filter, because dropping it widens the search. The platform only sends a blank when the user enabled "match blank values" for that pair, and never sends a row whose values are all blank.
 
+`destFieldPath` is set only for `id` and `field_value_equals[ci]`; `destFieldPaths` only for
+`field_values_equal[ci]`. Nested fields use the same path shape as `fields` (e.g.
+`[{ path: "custom_fields" }, { path: "tax_id" }]`). `srcData` is a batch — search them
+together where the API allows it. `match.id` already includes the user's source-id prefix when
+they configured one.
+
+The in-app Help article *Calling a connection from a script* has copy-paste `matchFilter`
+objects for every rule (same `rule` / `srcData` / `destFieldPath(s)` the platform sends here,
+plus `canUse` on this path). Do not duplicate that catalog in this file.
+
 ### relatedFilter
 
 Receives rows from a source object (`otherObjectId`) that has a defined relationship to this object, and collect the related rows from this object.

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.13",
+  "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": "b08f55c29df514e6a627b6c4fe49634d4c563c235420642189e63de96fe7af5c",
+  "typesContentHash": "c428bbb8ebc48254d9a04ea22755a73f6579fcccfc31d639633a935688655fd3",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.15"
+    "@syncmatters/script-api": "^1.0.16"
   }
 }