@syncmatters/connector-sdk 1.0.7 → 1.0.9

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

@@ -70,6 +70,7 @@ same as "no list support". See [the query capability bar](#the-query-capability-
 | `type`                            | `"string"` · `"number"` · `"boolean"` · `"object"` · `"array"` · `"file"` · `"any"`                                                                                               |
 | `isKey: true`                     | this field is the row's unique id — its value becomes `row.meta.key`. Assign this (or `isUserKey`) to exactly one `queryFields`, plus one `upsertFields`, plus one `deleteFields` |
 | `isUserKey: true`                 | user-supplied natural key that can both add and update — see below                                                                                                                |
+| `isAlternateKey: true`            | scalar `queryFields` field holding a unique value the connector can resolve rows by (`queryOptions.idsFilterField`) — a COMMITMENT to honor that filter, see [05-query.md](./05-query.md) |
 | `canMatch: true`                  | field may be referenced by match rules (set on id/name/email-like fields; apply recursively into nested object fields where meaningful)                                           |
 | `optionValues`                    | picklist options `[{ id, name?, group? }]`                                                                                                                                        |
 | `canUpdateOptions: true`          | new picklist options may be added via `upsertFieldOptions()`                                                                                                                      |

package/docs/05-query.md

@@ -84,6 +84,7 @@ Rules that follow from the lifecycle:
 | `queryOptions.fields`                       | field paths the caller needs (used to fetch less when the API supports it)                                                   |
 | `queryOptions.file`                         | LEGACY - ignore; modern connectors include file content when `fields` contains a file-typed field's path (13)                |
 | `queryOptions.idsFilter`                    | `string[]` of row keys — return exactly those rows; row with the key not found? omit it, do not report an error              |
+| `queryOptions.idsFilterField`               | path of the alternate key field the `idsFilter` values refer to (absent = internal row id) — below                           |
 | `queryOptions.checkpointFilter`             | `{ value?: string }` — rows changed since your last checkpoint (undefined value = first differential run: return everything) |
 | `queryOptions.matchFilter`                  | find rows matching people/records — below                                                                                    |
 | `queryOptions.relatedFilter`                | rows related to another object's rows — below                                                                                |
@@ -106,6 +107,40 @@ null/empty ids so you never emit `id = 'undefined'`.
 
 When the row does not exist on the target system (e.g. deleted), do not report an error (e.g. API returns 404), simply do not return the row.
 
+### idsFilterField (alternate key lookup)
+
+When `queryOptions.idsFilterField` accompanies `idsFilter`, the ids are NOT row keys — they are
+values of the alternate key field at that path (a field you flagged `isAlternateKey: true` in
+`queryFields`). The platform only sends this option for flagged fields, so flagging a field is
+your commitment to honor it. The contract:
+
+- return only rows that matched one of the requested values (unmatched values: omit, do not
+  error — same as `idsFilter`)
+- the platform correlates each returned row back to a requested value. Two ways to support that:
+  1. **annotate the row**: set `row.relationship = { srcRowId: <requested value> }` — the same
+     annotation the related/match flows use. REQUIRED when a row can match via anything other
+     than the field's stored value verbatim (aliases such as HubSpot's `hs_additional_emails`,
+     case-insensitive resolution). A row that matched multiple requested values is returned once
+     per value, each annotated.
+  2. **rely on the field value**: when matching is exact, it is enough to include the alternate
+     key field in each returned row's `data` (even when the caller narrowed the response with
+     `fields`) — the platform reads the value from the row.
+- `row.meta.key` remains the REAL internal row id, never the alternate value
+
+```js
+const path = options.queryOptions?.idsFilterField;
+if (path) {
+  const propName = path[path.length - 1]?.path; // e.g. properties.my_unique_prop -> my_unique_prop
+  // resolve via your alternate-id capable endpoint (e.g. HubSpot batch-read with idProperty),
+  // then annotate each row with the requested value it matched
+}
+```
+
+You MUST throw `SDK.ErrorCode.InvalidFilterParameter` if the path does not resolve to a field
+you can retrieve by (unknown, or no longer unique — possible when stored metadata is newer than
+the deployed connector). The platform does NOT pre-validate this option — your throw is the only
+thing standing between a bad path and silently empty results.
+
 ### checkpointFilter (differential sync)
 
 The contract is a round-trip: you emit `checkpoint` (any string — ISO date is conventional) on

package/docs/09-testing.md

@@ -248,6 +248,13 @@ The harness always executes platform-side. What each entry point actually runs:
 | `sm test --only query`       | Every object's plain list query only — no ids/checkpoint/match/related, no writes.              |
 | Web UI (connector → test results → run) | Same engine, feature selection via the run dialog.                                   |
 
+Each feature test records the inputs it ran with and what the connector returned — pass or
+fail — onto the saved result as diagnostic `details` (the ids an `idsFilter` ran with and the
+rows returned; expected vs actual rows per match rule / relationship; upserted rows and their
+query-back). Review them on the web UI's test results screen instead of re-running with extra
+logging. Payloads over the size budget are dropped and flagged `truncated`; details hold real
+connection data and are scrubbed ~48 hours after the run (statuses are kept).
+
 Do not mistake a passing `--only connection` or `--only query` for suite coverage — only the
 full run exercises the prepare hooks and write features. `sm test` needs a developer token
 with the `scripts:read`, `connections:read` and `scripts:execute` scopes; a 403 from the CLI

package/lib/connector.d.ts

@@ -110,6 +110,8 @@ export interface QueryOptions {
         randomFilter?: boolean;
         /** filter for rows by row id (key) */
         idsFilter?: Array<string>;
+        /** path of the alternate key field that the idsFilter values refer to, if applicable */
+        idsFilterField?: Array<JsonValuePathPart>;
         /** filter for rows related to other rows */
         relatedFilter?: QueryRelatedFilter;
         /** filter for rows that meet a specific matching rule */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/connector-sdk",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "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": "ae459fd0936deb05ec10d5b85156b8a268d06d5568f1c94d2f81d97c1224efac",
+  "typesContentHash": "bc9f5a1637b46d39ef65a04b24338624b3c51f60df16d6646113067bdec0aa86",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.6"
+    "@syncmatters/script-api": "^1.0.9"
   }
 }