@syncmatters/connector-sdk 1.0.5 → 1.0.6

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

@@ -75,7 +75,7 @@ same as "no list support". See [the query capability bar](#the-query-capability-
 | `canUpdateOptions: true`          | new picklist options may be added via `upsertFieldOptions()`                                                                                                                      |
 | `objectFields`                    | child fields when `type: "object"`                                                                                                                                                |
 | `arrayType` / `arrayObjectFields` | element type / element fields when `type: "array"`                                                                                                                                |
-| `constraints`                     | validation: `mandatory` (`"always"` · `"add"` · `"update"`), `max/min/maxLen/minLen`, `regex`, `email`, `integer`, `decimals`, `trim`, `dt: { format: "iso8601", "unix", ... }`   |
+| `constraints`                     | validation: `mandatory` (`"always"` · `"add"` · `"update"`; array children only when parent array is non-empty), `max/min/maxLen/minLen`, `regex`, `email`, `integer`, `decimals`, `trim`, `dt: { format: "iso8601", "unix", ... }`   |
 | `isCustom`                        | account-specific/custom field                                                                                                                                                     |
 | `data`                            | connector-private payload, echoed back in metadata                                                                                                                                |
 
@@ -215,6 +215,11 @@ last-modified filter actually exists on that object.
 - `mandatory` (`"always" | "add" | "update"`) raises a `ValueRequired` issue — and
   `mandatoryAccepts: ["null" | "blank_string"]` lets a mandatory field treat `null`/`""` as a
   satisfying value (for APIs where "explicitly blank" is meaningful).
+- For fields inside **`arrayObjectFields`**, `mandatory` is only checked when the parent array
+  has at least one element. An empty array (`[]`), a missing array property, or a missing parent
+  object does **not** raise `ValueRequired` for child fields — e.g. `ContactLinks.list.[0-n].CompanyId`
+  with `mandatory: "always"` is required per link object, but not when `list` is empty.
+  When the array is non-empty, **every** element must satisfy the mandatory constraint.
 
 ## `identity`
 

package/docs/06-upsert-delete.md

@@ -108,7 +108,8 @@ async upsertClean(options) {
   auto-created via your `upsertFieldOptions()` (resolved ids written back into the upsert).
   **Because it mutates, always run the verifies BEFORE `detectFirstChange`** — the production
   fleet does, without exception.
-- `verifyFieldConstraints` enforces your `ObjectField.constraints`.
+- `verifyFieldConstraints` enforces your `ObjectField.constraints` (including `mandatory` on
+  array item fields — only when the parent array is non-empty; see [04](./04-meta-objects-fields.md)).
 - Issues are `{ type, fatal?, fieldPath?, value?, option? }`; `fatal: true` blocks the row.
 - Returning `hasChanges` with no fatal issues queues the row; the platform batches queued rows
   and calls your `upsert()` with them later (clean order = write order; `upsertClean` calls

package/docs/09-testing.md

@@ -112,14 +112,9 @@ To disable those tests use `cannotTestReason` instead
   (`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`).
+- `checkpointFilterStep1Prepare` / `Step2Prepare` — the two-step round-trip test of your
+  differential contract; see [Checkpoint testing](#checkpoint-testing-what-the-two-steps-prove)
+  below, it is the most-misimplemented pair.
 - `matchFilterPrepare` — returns `MatchData` including `expectedMatchRowIds`.
 - `relatedFilterPrepare({ fromObjectMeta, toObjectMeta, fromRelationshipId })` —
   `fromObjectMeta` is the object where the relationship is DECLARED (the parent, in the
@@ -135,6 +130,44 @@ To disable those tests use `cannotTestReason` instead
   checks a flag field instead of row absence, and `afterDeleteMaxIndexWaitTimeMs` tolerates
   APIs whose deletions surface asynchronously.
 
+## Checkpoint testing: what the two steps prove
+
+The checkpoint contract is a ROUND-TRIP ([05](./05-query.md)): the platform stores whatever
+checkpoint string your final page emits and hands it back on the next differential run. One
+query can't test a round-trip — that's why there are two steps, and they prove different
+things:
+
+- **Step 1 proves your filter reads correctly**: given a checkpoint, the query returns
+  exactly the changed rows.
+- **Step 2 proves the checkpoint you EMIT is usable**: the harness takes the cursor your
+  step-1 query returned — not one you craft — and queries FROM it. This is the step that
+  catches the real bugs: an emitted cursor the query can't parse back, a `Date.now()`
+  checkpoint with no overlap (rows modified mid-query lost forever), a cursor in the wrong
+  timezone/format.
+
+Mechanics: `checkpointFilterStep1Prepare({ meta })` returns
+`{ nextCheckpoint, expectedRowIds }` — your chosen STARTING checkpoint and every row a query
+from it must return. The harness runs the query, verifies the rows, and captures the
+checkpoint your connector emitted. `checkpointFilterStep2Prepare({ meta, step1TestData,
+checkpointReceived })` then returns the `expectedRowIds` for a query from
+`checkpointReceived`.
+
+Three rules that decide whether your expectations are right:
+
+1. **The comparison is an exact set match, both steps** — a missing expected row fails AND
+   an unexpected returned row fails. Never guess; when in doubt, run the same
+   `checkpointFilter` query inside the prepare hook and report what it returns (the worked
+   hooks in [15](./15-example-test-file.md) do exactly this — a shared sandbox is never
+   quiet).
+2. **Your own overlap window works against you in step 2.** You emit checkpoints
+   `startTime - overlap` (05), so a query from `checkpointReceived` legitimately re-returns
+   step-1 rows modified inside the window. Expect them — the classic step-2 failure is
+   listing only the fresh mutation and being surprised by "Returned unexpected row".
+3. **Mutating data between the steps is optional.** Creating one fresh row step 2 must
+   surface is the strongest test, but on APIs where you can't create rows, a self-consistent
+   expectation (query from `checkpointReceived`, report what came back) is valid — the
+   round-trip and overlap behavior still get proven.
+
 ## What each test needs from your sandbox data
 
 Requirements that only surface as cryptic failures when unmet:
@@ -151,7 +184,8 @@ Requirements that only surface as cryptic failures when unmet:
   `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.
+- **Checkpoint step 2 does not have to create data** — see
+  [Checkpoint testing](#checkpoint-testing-what-the-two-steps-prove) above.
 
 ## Insert-only / immutable objects
 

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, 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, 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.5",
+  "version": "1.0.6",
   "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": "f0f72980b64b81d6019dbfd86756b2c4dc6ff60eb44b4d1824bde2f8a689fd6b",
+  "typesContentHash": "9d23ef0dc02fc7886f97e31eba1d50be7f8f6dae368c9b3ef4b1c969807d005c",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.4"
+    "@syncmatters/script-api": "^1.0.5"
   }
 }