@syncmatters/connector-sdk 1.0.1 → 1.0.3

package/docs/12-example-connector.md

@@ -5,6 +5,9 @@ One canonical, end-to-end connector on a single page. Three objects — `compani
 business unit + order id) — plus a contact→company relationship, static + API-discovered
 custom fields, and full `query` / `upsert` / `delete`. Every pattern here follows the
 production fleet; copy this shape and adapt it. Topic-file cross-references are in comments.
+Its test-file counterpart — the `mod Test.mjs` + `mod ObjectTestFeatures.mjs` pair the
+platform test suite and the CLI's `sm test` require — is
+[15-example-test-file.md](./15-example-test-file.md).
 
 The imaginary Acme API: bearer-token REST at `https://api.example.com/v1/`, cursor pagination
 (`?after=<id>`), `modified_since` differential filter, a `/search` endpoint taking field
@@ -98,6 +101,15 @@ export default class Acme {
         canQueryByIds: true,
         canQueryByCheckpoint: true,
         matchRules: ["id", "name[ci]"],
+        queryFilter: {
+          // system-specific filter users may apply alone OR on top of list/checkpoint
+          // queries ('extends') - "vendors changed since the checkpoint" is one query (05)
+          rowFilter: [
+            { id: "companyType", name: "Company type", type: "string",
+              optionValues: [{ id: "customer" }, { id: "vendor" }, { id: "other" }],
+              extends: [{ type: "checkpoint" }, { type: "list" }] },
+          ],
+        },
         queryFields: [
           { id: "id", name: "ID", type: "string", isKey: true, canMatch: true },
           { id: "name", name: "Name", type: "string", canMatch: true },
@@ -211,6 +223,7 @@ export default class Acme {
     }
 
     if (qo.matchFilter) return await this.#queryMatch(options, qo.matchFilter);
+    if (qo.relatedFilter) return await this.#queryRelated(options, qo.relatedFilter);
     // composite-key ids arrive as key STRINGS - parse each and fetch directly (11)
     if (options.id === "salesorders" && qo.idsFilter) {
       return await this.#querySalesOrdersByIds(qo.idsFilter);
@@ -231,13 +244,14 @@ export default class Acme {
       // undefined value = first differential run: return everything (05)
       params.push(`modified_since=${encodeURIComponent(qo.checkpointFilter.value || "1970-01-01T00:00:00Z")}`);
     }
-    if (qo.relatedFilter) params.push(this.#relatedWhere(options, qo.relatedFilter));
-
+    // declared rowFilter (extends list/checkpoint): one more AND constraint when present (05)
+    if (options.id === "companies" && qo.rowFilter?.companyType) {
+      params.push(`type=${encodeURIComponent(qo.rowFilter.companyType)}`);
+    }
     const resp = await this.#call({ method: "GET", url: `${options.id}?${params.join("&")}` });
 
     /** @type {SDK.Row[]} */
     let rows = resp.items.map((/** @type {any} */ item) => this.#row(options.id, item));
-    if (qo.relatedFilter) rows = this.#tagRelationships(rows, qo.relatedFilter);
 
     queryState.after = resp.next_cursor || undefined;
     queryState.rowCount += rows.length;
@@ -334,35 +348,52 @@ export default class Acme {
     }
   }
 
-  /** Resolve the FK declared in meta().relationships via its data payload.
-   * @param {SDK.QueryOptions} options @param {SDK.QueryRelatedFilter} related */
-  #relatedWhere(options, related) {
-    const rel = (options.meta.relationships || []).find((r) => r.id === related.otherRelationshipId);
+  /** Fetch rows of THIS object that other-object rows relate to. DIRECTION MATTERS:
+   * the platform queries the relationship's TARGET (here: companies) and passes the
+   * DECLARING object's rows (contacts) - so the relationship is resolved from the
+   * OTHER object's metadata via options.objectMeta, never options.meta (05).
+   * @param {SDK.QueryOptions} options @param {SDK.QueryRelatedFilter} related
+   * @returns {Promise<SDK.QueryPage>} */
+  async #queryRelated(options, related) {
+    const otherMeta = await options.objectMeta(related.otherObjectId);
+    const rel = (otherMeta.relationships || []).find(
+      (r) => r.id === related.otherRelationshipId,
+    );
     if (!rel) {
       throw new SDK.ConnectorError(SDK.ErrorCode.InvalidFilterParameter,
-        `object ${options.id} has no relationship '${related.otherRelationshipId}'`);
+        `object ${related.otherObjectId} has no relationship '${related.otherRelationshipId}'`);
     }
+    // the FK lives on the DECLARING object's rows (contact.company_id names a company);
+    // rel.data is OUR round-trip payload from meta() (04)
     const fk = /** @type {{idField: string}} */ (rel.data).idField;
-    const ids = related.otherRows.map((r) => r.meta.key);
-    return `${fk}=${ids.map(encodeURIComponent).join(",")}`;
-  }
+    /** @type {Map<string, SDK.Row[]>} this-object key -> source rows referencing it */
+    const wanted = new Map();
+    for (const src of related.otherRows) {
+      const key = src.data?.[fk] != null ? String(src.data[fk]) : "";
+      if (!key) continue; // source row without the FK - skip, never guess (10)
+      if (!wanted.has(key)) wanted.set(key, []);
+      /** @type {SDK.Row[]} */ (wanted.get(key)).push(src);
+    }
+    if (wanted.size === 0) return { rows: [], finalPage: true };
 
-  /** One row instance per source row it relates to, tagged with the relationship (05).
-   * @param {SDK.Row[]} rows @param {SDK.QueryRelatedFilter} related @returns {SDK.Row[]} */
-  #tagRelationships(rows, related) {
-    const out = [];
-    for (const row of rows) {
-      for (const src of related.otherRows) {
-        if (String(row.data.company_id) === src.meta.key) {
-          out.push({ ...row, relationship: {
-            srcRowId: src.meta.key,
-            srcObjectId: related.otherObjectId,
-            relationshipId: related.otherRelationshipId,
-          } });
-        }
+    const resp = await this.#call({
+      method: "GET",
+      url: `${options.id}?ids=${[...wanted.keys()].map(encodeURIComponent).join(",")}`,
+    });
+    /** @type {SDK.Row[]} */
+    const rows = [];
+    for (const item of resp.items) {
+      const base = this.#row(options.id, item);
+      // one row INSTANCE per source row it relates to (05)
+      for (const src of wanted.get(base.meta.key) || []) {
+        rows.push({ ...base, relationship: {
+          srcRowId: src.meta.key,
+          srcObjectId: related.otherObjectId,
+          relationshipId: related.otherRelationshipId,
+        } });
       }
     }
-    return out;
+    return { rows, finalPage: true };
   }
 
   // ---------------------------------------------------------------- upsert / delete (06)
@@ -548,8 +579,11 @@ function parseSalesOrderKey(compositeKey) {
    verbatim** (never re-encoded) on update/delete.
 4. **The composite `$compositeKey` pseudo-field carries `isKey`** and is stripped from every
    API body; adds supply the parent part (`business_unit`) as a regular mandatory field.
-5. **`relationships[].data` is the connector's own round-trip payload** — `meta()` stores the
-   FK field name, `query()` reads it back from `options.meta` when resolving `relatedFilter`.
+5. **Related queries run on the relationship's TARGET object** — the platform queries
+   `companies` passing `contacts` rows, so the relationship is resolved from the OTHER
+   object's metadata (`options.objectMeta(otherObjectId)`), never `options.meta`; the FK
+   values on the source rows name the queried object's keys. `relationships[].data` is the
+   connector's own round-trip payload carrying that FK field name.
 6. **`query()` dispatches filters in one place**, throws `InvalidFilterParameter` for anything
    undeclared, and shares the pagination path across list/ids/checkpoint variants — except
    composite-key `idsFilter`, which parses each key and fetches directly.
@@ -557,6 +591,9 @@ function parseSalesOrderKey(compositeKey) {
 8. **Match queries end with `canUse`** — the platform picks the winners, you just supply
    candidates. `first_and_last_name[ci]` requires BOTH parts; sources missing either are
    skipped, never half-matched.
+9. **The `companyType` rowFilter declares `extends`** — users can apply it alone or ON TOP of
+   list/checkpoint queries; in `query()` it is one more AND constraint next to
+   `modified_since`, not a separate code path.
 9. **`upsertClean` runs the mutating verifies first, `detectFirstChange` last**, and only the
    object that declares `canUpsertClean` (contacts) is cleaned.
 10. **Upsert output is index-mapped back to input order** and throws rather than guessing when