@syncmatters/connector-sdk 1.0.2 → 1.0.4

package/docs/01-workspace-and-meta-json.md

@@ -38,6 +38,12 @@ not exist at runtime.
 ]
 ```
 
+> `sm push` pushes `module_script_file_paths` changes (the CLI maps the paths to platform
+> file ids from the workspace). Every referenced file must be tracked — a reference the CLI
+> can't map holds the whole wiring change back with a warning, so imports never half-wire.
+> A new module and the sidecar edits that wire it can go in ONE push: files are created
+> first, wiring follows automatically.
+
 Import style in code: static `import` for your main module; dynamic `await import("./acme-v3")`
 for version dispatch so only the selected version's code is loaded:
 
@@ -129,7 +135,9 @@ consent UI: items carry `label` plus `read`/`write`/`full` scope strings and opt
 
 - `.sm/` (CLI state), and the CLI-generated `package.json` / `jsconfig.json` / `AGENTS.md`
   managed block at the workspace root. They are editor tooling, never pushed.
-- Generated `mod ObjectTestFeatures.mjs` files (regenerate instead).
+- Generated `mod ObjectTestFeatures.mjs` files — regenerate with `sm connector features`
+  (or the web UI's feature-generate action) after `meta()` changes; new relationships/match
+  rules are not tested until regenerated ([09-testing.md](./09-testing.md)).
 - System-connector stubs: if a connector's settings include a hidden
   `systemFlag*` boolean, the real implementation is embedded in the platform runtime and the
   `.mjs` stub is deliberately a no-op — don't implement it.

package/docs/03-http-auth-ratelimit.md

@@ -76,7 +76,7 @@ async #call(request) {
 to wait before that retry. The proven policy shape:
 
 ```js
-const canRetry = (err, method, url, httpCode) => {
+const canRetry = (err, method, _url, httpCode) => {
   if ([400, 403, 404].includes(httpCode)) return false; // client errors don't heal
   if (method === "GET") return true; // reads are idempotent
   if ([429, 502, 504].includes(httpCode)) return true; // throttle/gateway blips
@@ -85,6 +85,10 @@ const canRetry = (err, method, url, httpCode) => {
 };
 ```
 
+The parameters are positional — keep every position up to the last one you read, and prefix
+the ones you don't use with `_` (as with `_url` above, or `(_err, method, _url, httpCode)` in
+a shorter policy) so `checkJs` doesn't flag them as unused.
+
 Non-idempotent writes: only retry when you know the API tolerates it. One real-world subtlety:
 writes that reference a _freshly created picklist option_ can fail transiently while the option
 propagates — returning ~10000 (10s backoff) from `canRetry` for that specific error is the

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

@@ -31,9 +31,13 @@ async meta() {
   queryFields: [ /* ObjectField[] returned by query */ ],
   upsertFields: [ /* ObjectField[] accepted by upsert */ ],
   deleteFields: [ /* ObjectField[] needed to identify rows to delete */ ],
-  queryFilter: {                  // system-specific extra filters
-    rowFilter: [ { id: "modifiedOnOrAfter", type: "string" } ],
-    propertyFilter: [ { id: "fields", type: "array", arrayType: "string" } ],
+  queryFilter: {                  // system-specific extra filters (rowFilter only - propertyFilter is deprecated)
+    rowFilter: [
+      { id: "companyType", name: "Company type", type: "string",
+        optionValues: [{ id: "customer" }, { id: "vendor" }, { id: "other" }],
+        // where users may combine this filter with the standard filters (05):
+        extends: [{ type: "checkpoint" }, { type: "list" }] },
+    ],
   },
   relationships: [                // enables related-row queries
     { id: "companies-companyId", name: "Company", relObjectId: "companies",
@@ -50,9 +54,9 @@ Other fields: `settingsMeta`/`settingsValues` (per-object settings), `order` (so
 rather than setting them `false` — `undefined` and `false` both mean "unsupported", and omitted
 reads cleaner.
 
-Only make a capability conditional when the API forces it: e.g. objects whose REST path embeds
-`{parentId}` can't `canQueryList` (there's no "all parents" call) — give them `canQueryByIds`
-and a `relatedFilter` path instead.
+Set flags only for behaviour you implemented — but investigate the workaround patterns below
+before concluding a capability is impossible. "The API has no list-all endpoint" is not the
+same as "no list support". See [the query capability bar](#the-query-capability-bar).
 
 ## `ObjectField`
 
@@ -109,6 +113,11 @@ upsertFields.unshift({
 `"first_and_last_name[ci]"`, `"field_value_equals[ci]"` (`[ci]` = case-insensitive). Declare
 only rules `query()` actually implements via `matchFilter` — see [05-query.md](./05-query.md).
 
+**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
+match rules at all; add this floor even when the API has no search endpoint.
+
 ### Relationships
 
 Relationships are defined on the source object and declare that given a row from the source object, the relationship allows row(s) from another object (`relObjectId`) that relate to this row to be collected. The canonical example is collecting the Company record that a Contact relates to.
@@ -117,6 +126,57 @@ Relationships are defined on the source object and declare that given a row from
 `id` unique per object; `data` is yours (a common pattern stores the FK field name so `query()`
 can build the related filter). Declaring relationships enables `relatedFilter` queries.
 
+**Which object declares it?** The one whose row you START from — not necessarily the child:
+
+- _Child holds a lookup to its parent_ (Contact → Company): declare on the **child**
+  (`contacts` gets `relObjectId: "companies"`, `OneToOne`). Related queries then arrive on
+  `companies`.
+- _Parent owns children with no child list endpoint_ (a Flow owns its Executions and the API
+  only exposes `/flows/{id}/executions`): declare on the **parent**
+  (`flows` gets `relObjectId: "executions"`, `OneToMany`). Related queries then arrive on the
+  **child** (`executions`, with `otherObjectId: "flows"`) — that is how consumers reach child
+  rows at all, so pair it with `canQueryByIds` on the child
+  ([05-query.md](./05-query.md#relatedfilter) has the direction rules and a checklist).
+
+Declaring it on the wrong object doesn't fail here — it fails later, when
+`relatedFilter` hands your `query()` keys of the wrong object. Decide direction at `meta()` time.
+
+## The query capability bar
+
+Syncs are built from these capabilities — an object missing one is an object syncs can only
+partially use. **For every object, strive to support all five; omit a flag only after the
+workaround patterns below have failed**, and note why in a comment so the next author doesn't
+re-investigate:
+
+1. `canQueryList`
+2. `canQueryByIds`
+3. `canQueryByCheckpoint`
+4. `matchRules` (+ `matchFilter` in `query()`)
+5. `relationships` (+ `relatedFilter` in `query()`)
+
+The recurring "the API is awkward" shapes, and the patterns that beat them:
+
+- **No cross-parent list endpoint → fan-out list.** Child resources reachable only via
+  `/parents/{id}/children` can still `canQueryList`: enumerate the parents (cache their ids in
+  `queryState` or a `kvStore`), then page each parent's children in turn. Pair it with an
+  optional parent-id `rowFilter` (`extends: [{ type: "list" }, { type: "checkpoint" }]`) so
+  callers can scope to one parent and skip the fan-out.
+- **No "changed-since" cursor → checkpoint from what the API has.** A created/modified date
+  param (`DateCreatedFrom`, `modified_since`, an OData `$filter`) mapped from
+  `checkpointFilter.value` is a legitimate checkpoint implementation — for insert-only
+  objects a creation-date high-water mark is exactly right. Keep the overlap rule (05).
+- **Match via whatever search the API offers.** `matchRules` don't need a dedicated search
+  API — a filter param on the list endpoint (`To=`, `ContentName=`, `$filter=email eq ...`)
+  implements `email[ci]`/`name[ci]` fine. Fetch candidates, compare case-insensitively
+  yourself, hand them to `matchFilter.canUse`. And the floor: `canQueryByIds` alone already
+  implements `field_value_equals[ci]` on the id field (see Match rules above).
+- **Parent-scoped children → relationship on the PARENT** (see
+  [Relationships](#relationships)) so `relatedFilter` traversal works — in ADDITION to
+  fan-out list, not instead of it.
+
+The flags-are-promises rule ([10](./10-style-and-pitfalls.md)) still holds: implement first,
+then declare. The bar is about how hard to try before giving up, not about optimistic flags.
+
 ## Building `meta()` maintainably
 
 Never hand-maintain a big field list twice. The proven generators, in order of preference:

package/docs/05-query.md

@@ -77,7 +77,7 @@ Rules that follow from the lifecycle:
 | `queryOptions.matchFilter`                  | find rows matching people/records — below                                                                                    |
 | `queryOptions.relatedFilter`                | rows related to another object's rows — below                                                                                |
 | `queryOptions.randomFilter`                 | random sample up to `limit`                                                                                                  |
-| `queryOptions.rowFilter` / `propertyFilter` | your system-specific filters as declared in `meta().queryFilter`                                                             |
+| `queryOptions.rowFilter`                    | your system-specific filters as declared in `meta().queryFilter.rowFilter` — may arrive WITH a standard filter when declared `extends` (below) |
 
 Throw `SDK.ConnectorError(SDK.ErrorCode.InvalidFilterParameter, ...)` when asked for a filter
 the object didn't declare — it's the single most-thrown error code in the fleet, and it fails
@@ -104,6 +104,47 @@ the final page; the platform stores it and hands it back as `checkpointFilter.va
   rows modified while your query ran would otherwise be lost forever. Re-reading a few rows is
   free; losing one is a data bug.
 
+### rowFilter — user-parameterized augmentation of the standard filters
+
+The system-specific filters you declared in `meta().queryFilter.rowFilter`
+([04](./04-meta-objects-fields.md)) arrive as `queryOptions.rowFilter` — an object keyed by
+your declared filter ids. Each declaration's **`extends`** array is the contract for
+COMBINING them with the standard filters:
+
+```js
+// meta(): let users scope companies by type, alone or on top of list/checkpoint queries
+queryFilter: {
+  rowFilter: [
+    { id: "companyType", name: "Company type", type: "string",
+      optionValues: [{ id: "customer" }, { id: "vendor" }, { id: "other" }],
+      extends: [{ type: "checkpoint" }, { type: "list" }] },
+  ],
+},
+```
+
+`extends: [{ type: "checkpoint" | "list" | "match", mandatory? }]` declares which standard
+filters this rowFilter may arrive WITH — so "vendors changed since the checkpoint" is ONE
+query: `queryOptions.checkpointFilter` and `queryOptions.rowFilter.companyType` together,
+AND semantics. `mandatory: true` means the standard filter never arrives on this object
+without the rowFilter (e.g. a child object whose list endpoint requires a parent id). Without
+`extends` the filter stands alone.
+
+In `query()`, treat each declared rowFilter as one more constraint alongside whatever
+standard filter drives the query:
+
+```js
+const companyType = options.queryOptions?.rowFilter?.companyType;
+if (companyType) params.push(`type=${encodeURIComponent(companyType)}`);   // AND with modified_since etc.
+```
+
+and keep throwing `InvalidFilterParameter` for filters the object didn't declare. The test
+contract has a `rowFiltersPrepare` hook, but the suite does not exercise rowFilters yet —
+cover yours with a direct query in another prepare hook
+([09-testing.md](./09-testing.md)).
+
+> `queryFilter.propertyFilter` is **deprecated** — the standard `fields` filter supersedes it.
+> Don't declare it in new connectors ([10](./10-style-and-pitfalls.md)).
+
 ### matchFilter
 
 `{ rule, selectOrder?, destFieldPath?, srcData: [{ srcRowId, match: { id?, name?, email?, domain?, firstname?, lastname?, custom? } }], canUse }`.
@@ -125,15 +166,34 @@ candidates }])` — the platform reserves un-mapped matches and returns the sele
 Receives rows from a source object (`otherObjectId`) that has a defined relationship to this object, and collect the related rows from this object.
 
 `{ otherObjectId, otherRelationshipId, otherRows }`. DIRECTION: the platform queries the
-relationship's TARGET object and passes the DECLARING object's rows — contacts declare
-contact→company, so a related query arrives on `companies` with `otherObjectId: "contacts"`.
-Resolve the relationship from the OTHER object's metadata
-(`await options.objectMeta(related.otherObjectId)` — it is NOT in `options.meta`; your
-`relationship.data` typically holds the FK field name), collect the FK values from
-`otherRows` (they name THIS object's keys), fetch those rows, and return them tagged with
-`relationship: { srcRowId, srcObjectId: otherObjectId, relationshipId: otherRelationshipId }` —
-one row instance per source row it relates to. See the worked implementation in
-[12-example-connector.md](./12-example-connector.md).
+relationship's TARGET object (`relObjectId`) and passes the DECLARING object's rows — contacts
+declare contact→company, so a related query arrives on `companies` with
+`otherObjectId: "contacts"`. The same rule covers the inverse, parent-owns-children shape:
+when the PARENT declares `flows → executions` (`OneToMany`, because the API only exposes
+`/flows/{id}/executions`), the related query arrives on the CHILD (`executions`) with
+`otherObjectId: "flows"` and `otherRows` = flow rows — your child `query()` reads each parent
+row's key and calls the nested endpoint. Which object declares the relationship is a `meta()`
+decision — see [04-meta-objects-fields.md](./04-meta-objects-fields.md#relationships).
+
+The implementation checklist (each step has been gotten wrong in a real connector):
+
+1. Declare the relationship on the SOURCE object in `meta()` (the object rows start from —
+   child for lookups, parent for owned children).
+2. Handle `queryOptions.relatedFilter` in the TARGET object's `query()` (`relObjectId`'s) —
+   not the declaring object's.
+3. Resolve the relationship definition from the OTHER object's metadata:
+   `await options.objectMeta(related.otherObjectId)` then find `otherRelationshipId` in its
+   `relationships`. It is NOT in `options.meta` — that is this object's metadata, which does
+   not declare the relationship. (`relationship.data` typically holds the FK field name.)
+4. Collect the linking values from `otherRows` — for a lookup they are FK values naming THIS
+   object's keys; for parent-owned children they are the parent keys your nested endpoint
+   needs.
+5. Return the related rows tagged with
+   `relationship: { srcRowId, srcObjectId: otherObjectId, relationshipId: otherRelationshipId }` —
+   one row instance per source row it relates to (the same related row appears once per
+   source row).
+
+See the worked implementation in [12-example-connector.md](./12-example-connector.md).
 
 ## Cross-page scratch state: `kvStore`
 

package/docs/06-upsert-delete.md

@@ -59,6 +59,18 @@ Inspect the API's per-row results. When a row fails, log the response and throw
 (If your API supports partial success and the platform batch mode is `"atomic"`, failing the
 whole batch by throwing is correct; don't fabricate per-row placeholders.)
 
+### Insert-only objects
+
+Some objects create but never update — messages that send on create, execution/run records,
+audit entries. Implement the insert path normally and throw
+`SDK.ConnectorError(SDK.ErrorCode.NotImplimented, ...)` for rows that would update (a row
+arriving with its key set). Two consequences: the object's test spec declares
+`upsert.insertOnly` so the harness tests the insert path and skips the update phase —
+`Passed (insert only)` — see
+[09-testing.md](./09-testing.md#insert-only--immutable-objects); and if creating a row has
+billable or externally visible side effects (a real message send), make sure test connections
+use sandbox/test credentials or a no-send setting.
+
 ## `delete(options)` → `Promise<SDK.Row[]>`
 
 `options.rows` carry the identifying fields you declared in `deleteFields` (usually just the

package/docs/09-testing.md

@@ -108,12 +108,26 @@ prepare hooks skip their test when they return `undefined` — with two exceptio
 To disable those tests use `cannotTestReason` instead
 ([15-example-test-file.md](./15-example-test-file.md) shows the worked semantics):
 
-- `listPrepare` / `idsFilterPrepare` / `rowFiltersPrepare` — arrange rows and return what the
-  suite should expect (row-filter testing is easy to forget: provide it when `meta()` exposes
-  `queryFilter.rowFilter`).
-- `checkpointFilterStep1Prepare` / `Step2Prepare` — step 1 seeds data and captures the
-  checkpoint; step 2 mutates data the differential query must then surface.
+- `listPrepare` / `idsFilterPrepare` — arrange rows and return what the suite should expect.
+  (`rowFiltersPrepare` exists in the contract but the suite does NOT run rowFilter tests yet —
+  when `meta()` exposes `queryFilter.rowFilter`, cover it yourself with a direct query in a
+  hook you already implement.)
+- `checkpointFilterStep1Prepare` / `Step2Prepare` — step 1 returns `expectedRowIds` for a
+  query from your chosen starting checkpoint (`nextCheckpoint`); the harness runs it and
+  captures the checkpoint the query emits. Step 2 receives that checkpoint
+  (`{ meta, step1TestData, checkpointReceived }`) and returns the `expectedRowIds` a query
+  FROM it must surface. Mutating data between the steps is one way to produce step-2 rows —
+  but not required: on APIs where you can't create rows in-test, pick a step-1 checkpoint far
+  enough back that existing rows fall on both sides (remember your connector's overlap window
+  re-surfaces recent rows in step 2 — include them in `expectedRowIds`).
 - `matchFilterPrepare` — returns `MatchData` including `expectedMatchRowIds`.
+- `relatedFilterPrepare({ fromObjectMeta, toObjectMeta, fromRelationshipId })` —
+  `fromObjectMeta` is the object where the relationship is DECLARED (the parent, in the
+  parent-owns-children shape), `toObjectMeta` is its `relObjectId`. Return
+  `{ srcRowId, expectedRelatedRowIds, ... }[]` where `srcRowId` is a row of the DECLARING
+  object; the harness fetches it via `idsFilter`, then queries the related object with
+  `relatedFilter` and compares against `expectedRelatedRowIds`. The test spec side
+  (`relationshipsTo`) also lives on the declaring object's features.
 - `upsertPrepare` — returns `UpsertData`; use `withIssueSimulators` / `UpsertIssueSimulator`
   (`verifyFields`, expected issue `type` + `fatal`) to deliberately exercise your
   `upsertClean` issue reporting.
@@ -121,14 +135,87 @@ To disable those tests use `cannotTestReason` instead
   checks a flag field instead of row absence, and `afterDeleteMaxIndexWaitTimeMs` tolerates
   APIs whose deletions surface asynchronously.
 
+## What each test needs from your sandbox data
+
+Requirements that only surface as cryptic failures when unmet:
+
+- **idsFilter needs two distinct ids.** `idsFilterPrepare` should return `{ id1, id2 }`; ids
+  you omit are collected via a list query when the object `canQueryList` — an object with only
+  one row (or no list support and no prepare hook) fails with `"No test data"`. Each id is
+  then queried alone and must return exactly that one row.
+- **The upsert test is insert THEN update, twice over.** `upsertPrepare` is called twice; both
+  rows are inserted, re-queried by `idsFilter` and compared on `verifyFields` (which must be
+  non-null on the payload), then BOTH are updated via the declared `upsert.key` and re-queried
+  again. Objects whose rows can never update declare `upsert.insertOnly` — see below.
+- **relatedFilterPrepare needs a declaring-object row that actually has related rows** —
+  `expectedRelatedRowIds` must be non-empty. In the parent-owns-children shape that means a
+  parent with at least one child in the sandbox (create one in `before()` when the API allows;
+  otherwise seed the sandbox account once and document it in the test file).
+- **Checkpoint step 2 does not have to create data** — see the hook notes above.
+
+## Insert-only / immutable objects
+
+Some objects create rows but never update them: messages that send on create and are
+immutable after (`update` correctly throws `NotImplimented`), execution/run records, audit
+logs. Declare that contract on the test spec and the harness tests exactly what exists:
+
+```js
+// in mod Test.mjs's before(), over the generated spec (same place as cannotTestReason)
+objectFeatures.messages.upsert.insertOnly = true;
+```
+
+With `upsert.insertOnly` the upsert test runs its insert + query-back + `verifyFields`
+phases as normal and SKIPS the update phase, reporting **`Passed (insert only)`** — a full
+pass, with the result string honest about what was covered. `upsertPrepare` then only needs
+`insert` and `verifyFields` (no `update` data). The `upsert.key` spec is still required —
+the inserted rows are re-queried by id. Requires a platform runner that understands the
+flag; older runners fail such objects with `"No test data for update"`.
+
+Escalate to the blunter knobs only when the situation is stricter than "no update":
+
+- `upsert.cannotTestReason` (with a REAL explanation) when even CREATING rows is off-limits —
+  a client's production system, or a billable/externally visible side effect with no safe
+  path. The object reports `Not tested` + reason and the suite result is `Partial`.
+  (`delete.cannotTestReason` likewise when rows cannot be deleted.)
+- **Billable or externally visible side effects** (a real SMS/WhatsApp send, an email) must
+  not fire from tests: point the test connection at sandbox/test credentials (e.g. Twilio's
+  test credentials with magic numbers), or gate sends behind a connector setting the test
+  connection sets (a "suppress sends" / no-send mode) — then `insertOnly` still gives the
+  insert path real coverage safely.
+
 ## Coverage bar
 
 Target **80%+ code coverage** (statements/branches/functions/lines) from the platform's
 connector test runs — reports are downloadable per run and retained ~90 days. Structure
 `mod Test.mjs` so every object with declared capabilities is exercised rather than scoped out.
 
-## Local dev loop
-
-The harness runs platform-side. Locally you get: `sm validate` (workspace structure),
-`checkJs` type checking against the SDK types, `sm push` and a platform-side test run. Keep
-`test()` cheap and `meta()` deterministic so the suite stays fast.
+## Running the suite
+
+The harness always executes platform-side. What each entry point actually runs:
+
+| Command                      | What runs                                                                                      |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- |
+| `sm test`                    | The FULL suite — `connection.test()` + `metaRefresh()` + every object feature above. Identical to the web UI's connector test. |
+| `sm test --only connection`  | `connection.test()` only — credentials check, nothing else. The harness has NOT run.            |
+| `sm test --only meta`        | `connection.metaRefresh()` only.                                                                |
+| `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.                                   |
+
+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
+names the missing one. The dev loop around it: `sm validate` (workspace structure), `checkJs`
+type checking against the SDK types, `sm push`, then `sm test`. Keep `test()` cheap and
+`meta()` deterministic so the suite stays fast.
+
+Two workspace facts that bite here:
+
+- `mod ObjectTestFeatures.mjs` is **generated** — regenerate it with
+  `sm connector features` (or the web UI's feature-generate action) after `meta()` changes;
+  new relationships/match rules will NOT be tested until you do, because the generated
+  `relationshipsTo`/`matchRules` spec still reflects the old metadata. The loop is:
+  edit `meta()` → `sm push` → `sm connector features` → `sm test`.
+- The typed test connection (the `API.connections.<connection_name>.Connection` `@typedef` in
+  the `mod Test.mjs` example above) resolves from **generated** typings:
+  `types/connections/*.d.ts` in a CLI workspace (`sm types` refreshes them; `sm pull` runs it
+  automatically) — never hand-write these.

package/docs/10-style-and-pitfalls.md

@@ -6,6 +6,10 @@
   `/** @param {SDK.InitArgs} args @returns {Promise<void>} */`. Fields:
   `/** @type {SDK.HttpClient | undefined} */ #http;`. Complex local types: `@typedef` blocks at
   the end of the file. Escape hatches (`/** @type any */ (x)`, `@ts-ignore`) sparingly.
+- **Prefix unused positional parameters with `_`** — callback signatures like
+  `canRetry(err, method, url, httpCode)` are positional, so a policy that only reads
+  `method`/`httpCode` still declares the earlier slots: `(_err, method, _url, httpCode)`.
+  The `_` prefix is what keeps `checkJs`/editors from flagging them as unused.
 - **Private `#fields`** for all connector state (`#log`, `#http`, `#token`, `#settings`).
 - First line of `init()`: `SDK.verifyType(this);`.
 - **Double quotes**, semicolons, CRLF line endings.
@@ -22,6 +26,7 @@
 | `cacheRefreshOptions()` / `RefreshSpec` / `QueryPage.cacheState`              | checkpoint queries ([05-query.md](./05-query.md))                                            |
 | `RateLimiter.take()`                                                          | `rateLimiter.execute({ cost, exec })` — or just pass the limiter to `httpClient`             |
 | `new SDK.HttpClient(...)` / `new SDK.RateLimiter(...)` classes                | `SDK.utilities.httpClient(...)` / `SDK.utilities.rateLimiter(...)`                           |
+| `queryFilter.propertyFilter` / `queryOptions.propertyFilter`                  | the standard `fields` filter (`queryOptions.fields`) — don't declare propertyFilter in new connectors |
 
 ## The trap list (each one has bitten a real connector)
 
@@ -55,8 +60,12 @@
 11. **`NotImplimented` is spelled that way.** The enum member (value `CONN_NOT_IMPLEMENTED`)
     and several long-standing message strings use the misspelling — it is load-bearing; match
     it exactly.
-12. **Objects with `{parentId}`-style paths can't support `canQueryList`** — expose
-    `canQueryByIds` + a relationship for `relatedFilter` traversal instead.
+12. **Don't give up on `canQueryList`/`canQueryByCheckpoint` for `{parentId}`-scoped
+    objects.** The naive reading ("no list-all endpoint → no list") under-delivers: fan out
+    over the parents, offer a parent-id `rowFilter` (`extends` list/checkpoint), and map a
+    creation/modified-date param to the checkpoint — see
+    [the query capability bar](./04-meta-objects-fields.md#the-query-capability-bar). Declare
+    the parent relationship as well (`relatedFilter` traversal), not instead.
 13. **Don't log secrets.** Debug logging of requests/responses must be gated behind an
     advanced `debug` setting, and auth headers/tokens should be excluded or masked.
 14. **A hidden `systemFlag*` setting means the connector is a runtime-embedded stub** — the
@@ -65,6 +74,13 @@
     only when `queryOptions.fields` asks for it ([13-file-fields.md](./13-file-fields.md)) —
     the `queryFile`/`queryOptions.file`/`Row.file` trio in older connectors is legacy; don't
     copy it.
+16. **A relationship declared on the wrong object fails far from the mistake.** Declare it on
+    the object rows START from — the child for a lookup (contact→company), the PARENT for
+    owned children with no child list endpoint (flow→executions). Get it backwards and
+    `relatedFilter` arrives on the wrong object carrying the wrong kind of keys — which
+    typically surfaces as a composite-key parse error or "row not found", nowhere near
+    `meta()`. Direction rules: [04](./04-meta-objects-fields.md#relationships),
+    [05](./05-query.md#relatedfilter).
 
 ## Useful utilities you might otherwise reimplement
 

package/docs/11-composite-keys.md

@@ -23,6 +23,11 @@ loudly on garbage, and self-documents which part is which. (A delimiter join lik
 `5678:1234` is acceptable only when the parts can never contain the delimiter — and it's
 harder to validate; prefer JSON.)
 
+The property names need not be field paths — any fixed, self-describing ids satisfy the rules,
+e.g. the API's own resource ids: `{"execution_sid":"FN...","flow_sid":"FW..."}`. What is
+non-negotiable is that the property SET and ORDER are fixed: sort the names, always emit every
+part, so the same row encodes byte-identically forever.
+
 > Changing the encoding of an existing object is a breaking change: every cached row's key
 > stops matching and the platform sees an entirely new set of rows. Pick the encoding once.
 
@@ -44,10 +49,13 @@ not conflict with real fielf identifiers on the object. When the caller maps val
 discrete key fields AND supplies `$compositeKey`, cross-check them against the parsed key parts
 and throw on mismatch; when the discrete fields are absent, populate them from the parsed key.
 
-Because `{parentId}`-path objects have no "fetch everything" endpoint, they usually can't
-declare `canQueryList` without a parent filter — declare a `rowFilter` entry
-(`{ id: "parentId", type: "number" }`) and/or a relationship to the parent so rows arrive via
-`relatedFilter` (see [04](./04-meta-objects-fields.md), [05](./05-query.md)).
+`{parentId}`-path objects have no "fetch everything" endpoint, but that does NOT mean no
+`canQueryList`: fan out over the parents (enumerate them, page each parent's children), offer
+a parent-id `rowFilter` (`{ id: "parentId", type: "number", extends: [{ type: "list" }, { type: "checkpoint" }] }`)
+so callers can scope to one parent, AND declare the relationship on the parent so rows also
+arrive via `relatedFilter` — see
+[the query capability bar](./04-meta-objects-fields.md#the-query-capability-bar) and
+[05](./05-query.md).
 
 ## The helper pair
 

package/docs/12-example-connector.md

@@ -6,7 +6,7 @@ business unit + order id) — plus a contact→company relationship, static + AP
 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 `sm run test` require — is
+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
@@ -101,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 },
@@ -235,6 +244,10 @@ 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")}`);
     }
+    // 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[]} */
@@ -578,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

package/docs/15-example-test-file.md

@@ -2,7 +2,7 @@
 
 The test-file counterpart to [12-example-connector.md](./12-example-connector.md): the complete
 `mod Test.mjs` + `mod ObjectTestFeatures.mjs` pair for the Acme connector, on one page. The
-platform's connector test suite AND `sm run test|meta|query` both require a file of sidecar
+platform's connector test suite AND the CLI's `sm test` both require a file of sidecar
 type `"connectortest"` in the connector's folder — **a connector without one cannot be
 run-tested at all**. Harness conventions and hook semantics live in
 [09-testing.md](./09-testing.md); this page shows them applied end to end against Acme's three
@@ -39,15 +39,17 @@ generated module via `module_script_file_paths`:
 }
 ```
 
-Keep exactly one `"connectortest"` file per connector folder — `sm run test` resolves the test
-module from the connector's folder and several candidates are ambiguous.
+Keep exactly one `"connectortest"` file per connector folder — `sm test` resolves the test
+module from the folder beside the connector's entry file, and several candidates are ambiguous
+(`<Name>.test.mjs` wins when present).
 
 ## `files/Connectors/Acme/mod ObjectTestFeatures.mjs` (generated)
 
 Generated from the sandbox connection's cached `meta()` — regenerate it whenever `meta()`
-changes; never hand-edit it. Note there are **no** `cannotTestReason` / `sameAsObjectId`
-entries here: the generator cannot know those, so the fine-grained scoping knobs are applied
-from `mod Test.mjs`'s `before()` (below), on top of this file.
+changes (`sm connector features`, or the web UI's feature-generate action); never hand-edit
+it. Note there are **no** `cannotTestReason` / `sameAsObjectId` entries here: the generator
+cannot know those, so the fine-grained scoping knobs are applied from `mod Test.mjs`'s
+`before()` (below), on top of this file.
 
 ```js
 /**

package/docs/connector-authoring.md

@@ -147,12 +147,20 @@ Implementing more methods unlocks more platform capability:
 3. **Make `test()` real**: cheapest authenticated call the API offers (02).
 4. **Describe objects** in `meta()` (04). Start with one object and its `isKey` field; grow from
    there. `SDK.utilities.fieldsFromJSON(sample)` can draft field lists from a sample response.
-5. **Implement `query()`** for `canQueryList`, then `idsFilter`, then `checkpointFilter` (05).
+5. **Implement `query()` capabilities in order**: list → ids → checkpoint → match → related
+   (05). For EVERY object aim for all five — syncs are built from them. When the API is
+   awkward (parent-scoped paths, no changed-since cursor), work the patterns in
+   [the query capability bar](./04-meta-objects-fields.md#the-query-capability-bar) (fan-out
+   list, `rowFilter` + `extends`, creation-date checkpoints, match via search params) before
+   leaving a flag unset.
 6. **Implement writes** if needed: `upsert()`, `delete()` (06).
 7. **Validate + push**: `sm validate`, `sm status` / `sm diff`, `sm push -m "message"`.
    A push 409 means the platform copy changed: `sm pull`, merge, push again — never force.
 8. **Test harness**: add `mod Test.mjs` (+ generated `mod ObjectTestFeatures.mjs`) so the
    platform's connector test suite can exercise your objects (09; worked example: 15).
+9. **Run it**: `sm test` = the full suite (identical to the web UI's connector test — including
+   write features, so use a sandbox connection); `--only connection|meta|query` narrows. A
+   passing `--only` run is NOT suite coverage (09).
 
 ## Support
 

package/lib/connector.d.ts

@@ -116,9 +116,9 @@ export interface QueryOptions {
         matchFilter?: QueryMatchFilter;
         /** collect records changed since a particular checkpoint */
         checkpointFilter?: QueryCheckpointFilter;
-        /** system specific row filters */
+        /** system specific row filters; allowed values are defined in meta.queryFilter.rowFilter */
         rowFilter?: any;
-        /** system specific property filters */
+        /** @deprecated  (use standard fields filter) system specific property filters; allowed values are defined in meta.queryFilter.propertyFilter */
         propertyFilter?: any;
     };
     queryState?: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/connector-sdk",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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": "1e322fcb4cda8d7a31d350d575470adeb2402009ea1929274efe27d7ccb7e041",
+  "typesContentHash": "b47810ca30415f646b1055512fb4e342e48f3cd7459411c2dabcc7ca29959271",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.1"
+    "@syncmatters/script-api": "^1.0.3"
   }
 }