@syncmatters/connector-sdk 1.0.12 → 1.0.14

package/docs/04-meta-objects-fields.md

@@ -111,9 +111,18 @@ upsertFields.unshift({
 ### Match rules
 
 `matchRules` values: `"id"`, `"name[ci]"`, `"email[ci]"`, `"domain[ci]"`,
-`"first_and_last_name[ci]"`, `"field_value_equals[ci]"` (`[ci]` = case-insensitive). Declare
+`"first_and_last_name[ci]"`, `"field_value_equals[ci]"`, `"field_values_equal[ci]"`. Declare
 only rules `query()` actually implements via `matchFilter` — see [05-query.md](./05-query.md).
 
+`[ci]` = case-insensitive: text values compare ignoring case; enumeration/picklist, number, date
+and boolean values compare on the destination system's canonical stored value (for picklists, the
+option's internal id). Where the API allows, canonicalize the incoming value (e.g. resolve a
+picklist label or differently-cased id to the option id) before filtering.
+
+`"field_values_equal[ci]"` is the multi-field variant: 1-5 user-selected (source, destination)
+field pairs that must ALL be equal (`destA = a AND destB = b ...`). Declare it only when the API
+can apply several equality filters in one query (search filter groups, SOQL/OData `and`, ...).
+
 **Commonly forgotten:** an object that supports `idsFilter` can ALWAYS offer
 `"field_value_equals[ci]"` — with `canMatch: true` on its id field, the match is just a
 lookup of the supplied value by id. There is no reason for such an object to declare no

package/docs/05-query.md

@@ -227,7 +227,7 @@ cover yours with a direct query in another prepare hook
 
 ### matchFilter
 
-`{ rule, selectOrder?, destFieldPath?, srcData: [{ srcRowId, match: { id?, name?, email?, domain?, firstname?, lastname?, custom? } }], canUse }`.
+`{ rule, selectOrder?, destFieldPath?, destFieldPaths?, srcData: [{ srcRowId, match: { id?, name?, email?, domain?, firstname?, lastname?, custom?, customs? } }], canUse }`.
 
 For each `srcData` entry, search rows matching per the `rule` (e.g. `"email[ci]"` — compare
 case-insensitively). Collect candidates, then call `await options.matchFilter.canUse([{ srcRowId,
@@ -240,6 +240,17 @@ candidates }])` — the platform reserves un-mapped matches and returns the sele
 - **first_and_last_name[ci]** - inspect the `match.firstname` and values and `match.lastname` and search for rows with the same name.
 - **id** - inspect the `match.id` value and search in the selected `destFieldPath` (path to the field on the target system) to find rows holding this exact value in this field. This search is case sensitive.
 - **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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/connector-sdk",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "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": "fe69e2a25155db8cffec62e1bca9cf3e975e8dfe66c8e55fadbe84dd02d62438",
+  "typesContentHash": "09f69999930df0f8199bfd417a03cfa1bb882d929614b96a26f8f52e7acab0f9",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.14"
+    "@syncmatters/script-api": "^1.0.15"
   }
 }