@syncmatters/connector-sdk 1.0.17 → 1.0.18

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

@@ -128,7 +128,7 @@ always stored, they were simply never written down here:
 | `mandatory: true`                                           | the form blocks save until the setting has a value                                                                                      |
 | `display_if` / `display_if_setting` / `display_if_values`   | conditional rendering (`displayIfHasValue` is the deprecated spelling, still accepted)                                                  |
 | `prerequisite: true`                                        | two-phase connectors only — see below                                                                                                   |
-| `affectsMeta: true`                                         | `meta()` reads this setting (a scope, a checkpoint column, an API version), so changing its value marks the connection's cached metadata stale until the next full refresh. Independent of `discovery`; implied by `prerequisite`; no effect on a `metaRefreshDisabled` connector |
+| `affects_meta: true`                                         | `meta()` reads this setting (a scope, a checkpoint column, an API version), so changing its value marks the connection's cached metadata stale until the next full refresh. Independent of `discovery`; implied by `prerequisite`; no effect on a `metaRefreshDisabled` connector |
 
 Use `control: "timezone"` for IANA time zone pickers (e.g. fleet `time_zone` setting). The stored
 value is a plain string (`"America/New_York"`, `"UTC"`, …); the UI renders a searchable list of
@@ -159,7 +159,7 @@ objects THIS account has — set `"discovery": true` and implement `discover()`
     "password": { "order": "02", "name": "Password", "type": "string", "control": "singlelinetext", "secret": true, "mandatory": true, "prerequisite": true },
     "database": { "order": "03", "name": "Database", "type": "string", "control": "singlelinetext", "mandatory": true, "prerequisite": true,
                   "description": "The catalogue lists this database's tables and views." },
-    "schema":   { "order": "04", "name": "Schema", "type": "string", "control": "select", "affectsMeta": true,
+    "schema":   { "order": "04", "name": "Schema", "type": "string", "control": "select", "affects_meta": true,
                   "description": "Restrict the catalogue to one schema; the options come from discovery." },
     "timeZone": { "order": "05", "name": "Time Zone", "type": "string", "control": "timezone" }
   }
@@ -169,14 +169,44 @@ objects THIS account has — set `"discovery": true` and implement `discover()`
 Rules worth knowing before you mark anything:
 
 - `defines_version: true` implies `prerequisite: true` (the version core has to be chosen before
-  anything can be discovered); `prerequisite: true` in turn implies `affectsMeta: true`.
+  anything can be discovered); `prerequisite: true` in turn implies `affects_meta: true`.
 - Changing a `prerequisite` setting on a live connection marks the stored catalogue stale — the
   previous result is kept and the user is offered a re-collect. Nothing is queued automatically.
 - A setting with no `options`, in the sidecar or in the overrides, renders as free text. The
   overrides may also supply `default`, `mandatory`, `readonly`, `hidden` and `description`.
 - `prerequisite` is ignored when `discovery` is absent, and `sm validate` rejects
-  `"discovery": true` with no `prerequisite` setting (or with no `discover()` on the entry class,
-  and vice versa).
+  `"discovery": true` with no `prerequisite` setting. It warns when it finds no `discover()` on
+  the entry class (and vice versa): the flag is what the platform reads, so a flagged class
+  without the method fails loudly in the wizard with `NotImplimented` rather than being treated
+  as single-phase.
+
+#### A version that cannot discover: `"discovery": false` on its option
+
+`discovery` is connector-wide, but on a multi-version connector one version core may be unable to
+produce a catalogue (a superseded API). Mark that version's option instead of throwing:
+
+```json
+"version": {
+  "order": "01", "name": "Version", "type": "string", "control": "select", "defines_version": true,
+  "default": { "type": "string", "expression": "3b" },
+  "options": [
+    { "id": "1",  "name": "Superseded - legacy API (v1)", "order": "00", "discovery": false },
+    { "id": "3b", "name": "3b (Recommended)",            "order": "03" }
+  ]
+}
+```
+
+A connection is two-phase when `connector_metadata.discovery` is `true` **and** no `prerequisite`
+(or `defines_version`) select setting has its selected option marked `"discovery": false`. An
+option without the field inherits the connector's flag, so a new version is two-phase with
+nothing written; the only thing you ever write is the exception, next to the "Superseded" label.
+A connection on a marked version gets the single-phase form, `discover()` is never called, and
+its metadata is collected on first use like a connector without discovery. The platform reads the
+connection's selected value, not the setting's `default`. Changing a live connection's version
+across the line keeps its cached objects either way: moving to a two-phase version turns them
+into the selection; moving to a marked version clears the selection, so the next refresh collects
+everything. `sm validate` rejects the field on a setting that is not a prerequisite, and on the
+setting's default option.
 
 ### `oauth2_provider`
 

package/docs/02-lifecycle-and-shape.md

@@ -171,4 +171,8 @@ implementation into per-version core modules. The entry class reads the setting
 delegates every SDK method to the selected core (`this.#core.query(options)` etc.), loading the
 core with a dynamic `await import("./acme-v3")` so unselected versions never load. `discover()`
 delegates like the rest: a `defines_version` setting is implicitly `prerequisite`, so the version
-is chosen before discovery runs and each core can discover its own way.
+is chosen before discovery runs and each core can discover its own way. A core that cannot
+discover at all (a superseded API) is marked on its option with `"discovery": false`
+([01](./01-workspace-and-meta-json.md#a-version-that-cannot-discover-discovery-false-on-its-option)):
+connections on that version stay single-phase and `discover()` is never called for them. Keep a
+`NotImplimented` throw in that core's `discover()` as the backstop.

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

@@ -99,6 +99,20 @@
     the first `init()` of a connection's life runs with only the prerequisite settings entered,
     so a connector that demands the rest up front fails discovery before the user can be shown
     the values ([02](./02-lifecycle-and-shape.md)). Validate them where they are used.
+20. **An unmarked version whose core cannot discover fails loudly in the wizard.** That is the
+    design: with `"discovery": true` every version is two-phase unless its option says
+    `"discovery": false`, so a new connection on an unmarked legacy version hits the core's
+    `NotImplimented` throw on Continue (shown inline, with Retry) instead of being silently
+    downgraded. Mark the option
+    ([01](./01-workspace-and-meta-json.md#a-version-that-cannot-discover-discovery-false-on-its-option)).
+    Marking the setting's default option is a `sm validate` error: every new connection would
+    be single-phase.
+21. **Reading another object's metadata through `objectMeta()` works on legacy connections and
+    fails on selected ones.** Keep an object self-contained: put what its own query/upsert needs
+    on its `data`; treat any other object's metadata as optional and fail with a clear
+    `ConnectorError` when it is absent. A two-phase connection caches only the objects the user
+    selected, so a companion object the parent reads its association ids or aliases from may
+    simply not be there.
 
 ## Useful utilities you might otherwise reimplement
 

package/docs/12-example-connector.md

@@ -590,7 +590,7 @@ Three deltas, nothing else changes.
   "discovery": true,
   "settings": {
     "api_key":      { "order": "00", "name": "API Key", "type": "string", "control": "singlelinetext", "secret": true, "mandatory": true, "prerequisite": true },
-    "businessUnit": { "order": "01", "name": "Business Unit", "type": "string", "control": "select", "affectsMeta": true,
+    "businessUnit": { "order": "01", "name": "Business Unit", "type": "string", "control": "select", "affects_meta": true,
                       "description": "Sales orders are scoped to this unit; the options come from your account." },
     "debug":        { "order": "02", "name": "Debug", "advanced": true, "type": "boolean", "control": "singlelinetext" }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/connector-sdk",
-  "version": "1.0.17",
+  "version": "1.0.18",
   "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": "314515b24178a1bb092c58fdf12782eb777f8ad583d83c9837536be02c751490",
+  "typesContentHash": "2d30d816e8bb71a9fe2d9390945f4aa62c8eff1f4f86e69ec8f965e8a42cd6c8",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.17"
+    "@syncmatters/script-api": "^1.0.19"
   }
 }