@syncmatters/connector-sdk 1.0.3 → 1.0.4

package/docs/06-upsert-delete.md

@@ -64,11 +64,12 @@ whole batch by throwing is correct; don't fabricate per-row placeholders.)
 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 needs
-`upsert.cannotTestReason` (the harness's upsert test always includes an update phase — see
-[09-testing.md](./09-testing.md#insert-only--immutable-objects)), and if creating a row has
+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 credentials or a no-send setting.
+use sandbox/test credentials or a no-send setting.
 
 ## `delete(options)` → `Promise<SDK.Row[]>`
 

package/docs/09-testing.md

@@ -146,7 +146,7 @@ Requirements that only surface as cryptic failures when unmet:
 - **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. There is no insert-only mode — see below for objects that cannot update.
+  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;
@@ -155,22 +155,33 @@ Requirements that only surface as cryptic failures when unmet:
 
 ## Insert-only / immutable objects
 
-Some objects can never pass the upsert test as written: messages that send on create and are
+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. The harness's upsert test always performs the update phase, so:
-
-- Set `upsert.cannotTestReason` on the object's features with a REAL explanation —
-  `"Messages are immutable once sent; update is NotImplimented by design"` — so the result
-  reads as a documented decision, not a gap. (`delete.cannotTestReason` likewise when rows
-  cannot be deleted.)
-- The insert path still deserves coverage: exercise it yourself in another prepare hook you
-  already need (e.g. `checkpointFilterStep1Prepare` inserting the row whose id it expects), so
-  the code path runs even though the formal upsert test is scoped out.
+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 credentials, and when the API has
-  no sandbox, gate sends behind a connector setting the test connection sets (a "suppress
-  sends" / no-send mode) — then say so in the `cannotTestReason` if that leaves upsert
-  untestable.
+  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
 

package/package.json

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