@lerianstudio/matcher-mcp 4.5.0-beta.13 → 4.5.0-beta.14

package/dist/spec/openapi.yaml

@@ -1347,6 +1347,12 @@ components:
     ConnectionResponse:
       additionalProperties: false
       properties:
+        baseURL:
+          description: Per-connection API base URL of a REST connector connection; absent when the deployment default applies and for database connectors
+          examples:
+            - https://sandbox.provider.example
+          format: uri
+          type: string
         configName:
           description: Connection configuration name
           examples:
@@ -1363,7 +1369,7 @@ components:
             - POSTGRESQL
           type: string
         host:
-          description: Database host
+          description: Database host; empty for REST connector connections, whose service address is reported as baseURL
           examples:
             - db.internal.example.com
           type: string
@@ -1414,6 +1420,25 @@ components:
         - schemaDiscovered
         - lastSeenAt
       type: object
+    ConnectionSchemaHistoryResponse:
+      additionalProperties: false
+      properties:
+        connectionId:
+          description: Internal Matcher connection identifier the history belongs to
+          examples:
+            - 3fa85f64-5717-4562-b3fc-2c963f66afa6
+          type: string
+        generations:
+          description: Prior generations of the schema map, oldest first; empty when the map has never changed
+          items:
+            $ref: "#/components/schemas/SchemaGenerationResponse"
+          type:
+            - array
+            - "null"
+      required:
+        - connectionId
+        - generations
+      type: object
     ConnectionSchemaResponse:
       additionalProperties: false
       properties:
@@ -1422,13 +1447,40 @@ components:
           examples:
             - 3fa85f64-5717-4562-b3fc-2c963f66afa6
           type: string
+        fieldReport:
+          description: "How the field lists in this map were obtained, recorded per row by the report that produced it and folded to one answer for the map: ENUMERATED means they come from the source's own catalog and are exhaustive for the credential that read it, so fewer fields than before is a real change in what the source reports; SAMPLED means they are inferred from a sample of the source's data (MongoDB reads the union of top-level keys over $sample-d documents), so they vary between reads with nothing changed at the source and no reduction is ever asserted from them — how the persisted field lists then build up, and what ends that, is stated in full in this operation's description. It is NEVER derived from this connection's current databaseType, which an operator can edit: a retype must not re-attribute field sets a different connector produced. Present only when every row of the map records the same kind: absent when the rows disagree, when any of them predates the recording of this fact, and when the probe that installed them could not show which connector produced its snapshot — in each case nothing is asserted about how the fields were obtained. It is the fact that separates routes (1) and (5) of notYetExtractableReason, whose remedies contradict each other"
+          enum:
+            - ENUMERATED
+            - SAMPLED
+          examples:
+            - SAMPLED
+          type: string
+        lastKnownMap:
+          description: "The tables are a retired generation, not the connection's live map: the source has not re-asserted them since they were archived. Absent when the rows served are live"
+          type: boolean
+        lastReadAt:
+          description: When the map was last successfully read from the source; absent when no map has ever been read
+          examples:
+            - "2026-07-26T14:03:00Z"
+          format: date-time
+          type: string
+        notYetExtractableReason:
+          description: "Why nothing in this map can be extracted from yet; absent when at least one table can. COLUMNS_NOT_ENUMERATED means Matcher holds no confirmed column observation for this connection that it could project into an extraction, and it arrives by five routes worth distinguishing, each named here so a client can tie an operator-facing sentence to one: (1) TABLES_WITHOUT_COLUMNS — every persisted table carries no column, the only route visible in the tables below; (2) COLUMNS_NEVER_CONFIRMED — no probe of this connection ever recorded a confirmed-columns observation, in which case the tables below may still show columns; (3) COLUMN_VISIBILITY_LOST — an established connection whose source enumerates its columns from a catalog returned columns for no table it still names, so that snapshot was refused and the tables below show their last confirmed columns; (4) NO_TABLES_NAMED — the source named no table at all; (5) SAMPLED_REPORT_NO_FIELDS — the source's field list is sampled from its data rather than enumerated from a catalog and the draw returned no field, so nothing was refused: the tables installed, no column was confirmed, and extraction reopens as soon as a draw returns fields. Routes 3, 4 and 5 arrive as the same response and a client states them as readings rather than picking one. Routes 1 and 5 also arrive as the same response — a map in which every table carries no column — and their remedies contradict each other, so fieldReport above says which of the two applies: SAMPLED is route 5 and no grant is involved, ENUMERATED is route 1 and the credential's column grants are the thing to check. Both must be stated when fieldReport is absent, which happens when the rows of this map disagree about how their field lists were obtained, when any of them predates the recording of that fact, or when the probe that installed them could not show which connector produced its snapshot — the connector registry is not consulted on this path at all, so a registered connector is neither what makes the kind present nor what its absence says anything about. No route distinguishes a source with no columns to give from columns this connection's credential can no longer read"
+          enum:
+            - COLUMNS_NOT_ENUMERATED
+          examples:
+            - COLUMNS_NOT_ENUMERATED
+          type: string
         tables:
-          description: All discovered table schemas for the connection
+          description: All discovered table schemas for the connection; the last known map even when the connection is unreachable
           items:
             $ref: "#/components/schemas/SchemaTableResponse"
           type:
             - array
             - "null"
+        unreachable:
+          description: "The connection could not be reached when this map was served: the tables are the last known map and may no longer match the source"
+          type: boolean
       required:
         - connectionId
         - tables
@@ -1506,6 +1558,13 @@ components:
           examples:
             - database
           type: string
+        requiredFields:
+          description: Credential field names a REST-category connector requires at provisioning time, in render order; absent for database connectors
+          items:
+            type: string
+          type:
+            - array
+            - "null"
         type:
           description: Canonical engine datasource-type token
           examples:
@@ -2282,6 +2341,9 @@ components:
             - https://example.com/errors/example
           format: uri
           type: string
+        upstream:
+          $ref: "#/components/schemas/Upstream"
+          description: "RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one."
       type: object
     DialectResponse:
       additionalProperties: false
@@ -5585,6 +5647,65 @@ components:
       required:
         - sample
       type: object
+    RESTConnectionRequest:
+      additionalProperties: false
+      properties:
+        apiKey:
+          description: Stripe restricted API key (sealed; never emitted)
+          maxLength: 512
+          type: string
+        baseURL:
+          description: Optional per-connection API base URL (http/https); when omitted the deployment default for the connector type is used
+          examples:
+            - https://sandbox.provider.example
+          format: uri
+          maxLength: 2048
+          type: string
+        clientCert:
+          description: PEM-encoded Pix mTLS client certificate (sealed; never emitted)
+          maxLength: 8192
+          type: string
+        clientID:
+          description: Pix OAuth2 client id (sealed; never emitted)
+          maxLength: 512
+          type: string
+        clientKey:
+          description: PEM-encoded Pix mTLS client private key (sealed; never emitted)
+          maxLength: 8192
+          type: string
+        clientSecret:
+          description: Pix OAuth2 client secret (sealed; never emitted)
+          maxLength: 512
+          type: string
+        configName:
+          description: Unique connection config name (tenant-scoped)
+          examples:
+            - pagbank-prod
+          maxLength: 255
+          minLength: 1
+          type: string
+        connectorType:
+          description: REST connector type this connection serves
+          enum:
+            - PAGBANK
+            - STRIPE
+            - PIX_BCB
+          examples:
+            - PAGBANK
+          minLength: 1
+          type: string
+        ediToken:
+          description: PagBank EDI token (sealed; never emitted)
+          maxLength: 512
+          type: string
+        establishmentID:
+          description: PagBank establishment id (sealed; never emitted)
+          maxLength: 512
+          type: string
+      required:
+        - configName
+        - connectorType
+      type: object
     ReadinessResponse:
       additionalProperties: false
       properties:
@@ -6162,16 +6283,77 @@ components:
       required:
         - name
       type: object
+    SchemaGenerationResponse:
+      additionalProperties: false
+      properties:
+        archivedAt:
+          description: When this generation stopped being the live schema map
+          examples:
+            - "2026-07-15T12:30:00Z"
+          format: date-time
+          type: string
+        fieldReport:
+          description: "How this retired generation's field lists were obtained, read off its own rows: ENUMERATED from the source's own catalog, exhaustively for the credential that read it, so this generation's column sets are a statement about the source; SAMPLED from a sample of the source's data (MongoDB reads the union of top-level keys over $sample-d documents), so it may name a field the source no longer held, because nothing observed a removal — how such a field list built up while this generation was live, and what closed the generation, is stated in full in this operation's description. Present only when every table of this generation records the same kind: absent when they disagree, for every generation retired before the fact was recorded per row, and when the probe that installed a table of it could not show which connector produced its snapshot. It is never derived from the connection's current databaseType: that field is editable and a generation's provenance is not"
+          enum:
+            - ENUMERATED
+            - SAMPLED
+          examples:
+            - SAMPLED
+          type: string
+        retirementCause:
+          description: What was observed of this whole generation when it was retired, when every table in it agrees; absent when one install retired different tables for different observed reasons, in which case each table carries its own. Values carry the same meanings as on a table, and none of them asserts that the source removed anything
+          enum:
+            - ABSENT_FROM_CATALOG
+            - COLUMN_SET_SUPERSEDED
+            - CONNECTION_RETIRED
+            - UNKNOWN_LEGACY
+          examples:
+            - ABSENT_FROM_CATALOG
+          type: string
+        tables:
+          description: The tables and columns this generation of the map asserted
+          items:
+            $ref: "#/components/schemas/SchemaTableResponse"
+          type:
+            - array
+            - "null"
+      required:
+        - archivedAt
+        - tables
+      type: object
     SchemaTableResponse:
       additionalProperties: false
       properties:
         columns:
-          description: Columns discovered for the table
+          description: "Columns discovered for the table. WHAT THIS LIST IS A STATEMENT ABOUT DEPENDS ON HOW THE CONNECTOR OBTAINED IT — see fieldReport on the map, or on the generation, that carries this table. WHERE THE FIELD LISTS ARE ENUMERATED from the source's own catalog, these are the columns the latest probe asserted for the credential that read it. WHERE THEY ARE SAMPLED from the source's data instead, a field listed here may appear in no document the source currently holds: it carries no marker saying so and stays extractable, deliberately, because nothing observed its removal. How a sampled connector's field lists build up, and what ends that, is stated in full in this operation's description — read it before authoring a field map against these columns"
           items:
             $ref: "#/components/schemas/SchemaColumnResponse"
           type:
             - array
             - "null"
+        columnsNarrowed:
+          description: "The source now reports FEWER columns for this table than the read before did: the columns shown were confirmed by the latest probe, and at least one column it used to report is no longer among them. The table stays extractable from the narrower set; a field map projecting a column that stopped being reported will fail at extraction. It says nothing about WHY the set narrowed — a narrowed grant and a dropped column are the same answer from a catalog"
+          type: boolean
+        columnsStale:
+          description: "The last probe named this table without confirming its columns, so the column list is the last CONFIRMED one and may no longer match the source. The table is still extractable from it; a field map authored against it may silently stop matching. ABSENT DOES NOT MEAN THE WHOLE LIST WAS CONFIRMED BY THE LATEST PROBE: it means that probe reported columns for this table, which confirms the list only where the field lists are ENUMERATED from a catalog. Where they are SAMPLED from the source's data a draw confirms only the fields it showed, and the rest of the list may include fields the latest draw did not show — see columns, and this operation's description, which states in full how such a list builds up and what ends it"
+          type: boolean
+        notYetExtractableReason:
+          description: Why this table cannot be extracted from yet; absent when it can. COLUMNS_NOT_ENUMERATED means the source named the table but no columns for it, which is indistinguishable between a source with no columns to give and columns the connection's credential cannot read
+          enum:
+            - COLUMNS_NOT_ENUMERATED
+          examples:
+            - COLUMNS_NOT_ENUMERATED
+          type: string
+        retirementCause:
+          description: What was observed when this table's row stopped being the live truth; absent on a live row. ABSENT_FROM_CATALOG means the source's catalog no longer listed the table, which does NOT distinguish a dropped table from one this connection's credential can no longer see. COLUMN_SET_SUPERSEDED means the catalog still listed it with a different non-empty column set, the same ambiguity one level down; it is recorded only for a report that ENUMERATED the source's catalog, because a report whose field list was sampled from the source's data retires no column set when a draw differs — so a sampled table reaches this cause when its connection is retyped to a connector that enumerates and the catalog list supersedes the accumulated union. CONNECTION_RETIRED means an operator retired the connection, the one cause that is genuinely known. UNKNOWN_LEGACY means the row was archived by an earlier release that recorded no cause
+          enum:
+            - ABSENT_FROM_CATALOG
+            - COLUMN_SET_SUPERSEDED
+            - CONNECTION_RETIRED
+            - UNKNOWN_LEGACY
+          examples:
+            - ABSENT_FROM_CATALOG
+          type: string
         tableName:
           description: Name of the discovered table
           examples:
@@ -7780,6 +7962,20 @@ components:
             - string
             - "null"
       type: object
+    Upstream:
+      additionalProperties: false
+      properties:
+        code:
+          description: The upstream provider's own error code, verbatim.
+          examples:
+            - E4001
+          type: string
+        message:
+          description: The upstream provider's own error message, verbatim (bounded, never its raw response body).
+          examples:
+            - account not found at provider
+          type: string
+      type: object
     VarianceReportRowResponse:
       additionalProperties: false
       properties:
@@ -10004,7 +10200,7 @@ paths:
         - Discovery
   /v1/discovery/connections/{connectionId}/schema:
     get:
-      description: Returns all discovered table schemas for a connection.
+      description: "Returns all discovered table schemas for a connection — the map a field map is authored against. WHERE THIS CONNECTION'S CONNECTOR SAMPLES ITS FIELD LISTS rather than enumerating them from a catalog (the connection's fieldReport is SAMPLED on the live schema map; MongoDB reads the union of top-level keys over $sample-d documents), a table's persisted field set is CUMULATIVE WITHIN ITS CURRENT GENERATION: it holds every field any draw has shown since that generation began, and no draw takes a field out of it, because a draw that missed a field is a fact about this service's own sample and never about the source. So a field the map lists may appear in no document the source currently holds; it carries no marker saying so and stays extractable, deliberately, because nothing observed its removal. CUMULATIVE WITHIN A GENERATION IS NOT CUMULATIVE FOREVER: a generation ENDS at any retirement that records why — ABSENT_FROM_CATALOG, COLUMN_SET_SUPERSEDED or CONNECTION_RETIRED, whose meanings the retirementCause property carries — and the next report opens a new generation holding its own fields alone, so a served field set CAN come back narrower across that boundary, with the wider generation dated, caused and still readable on the schema-history surface. WHERE THE FIELD LISTS ARE ENUMERATED from the source's own catalog none of this applies: a table's columns are what the latest probe asserted for the credential that read it, and a catalog list is authoritative over a sampled union — which is what COLUMN_SET_SUPERSEDED records when a connection's connector starts enumerating."
       operationId: getDiscoveryConnectionSchema
       parameters:
         - description: Connection ID (UUID)
@@ -10035,6 +10231,39 @@ paths:
       summary: Get connection schema
       tags:
         - Discovery
+  /v1/discovery/connections/{connectionId}/schema/history:
+    get:
+      description: "Returns the prior generations of a connection's schema map, oldest first, so this is every schema fact the connection ever persisted that stopped being live, dated with the instant it stopped. Producing one destroys nothing: a generation is RETIRED, and each one reports what was OBSERVED when it was retired, never that the source removed anything — a catalog cannot distinguish a dropped table from one this connection's credential can no longer see. WHERE THIS CONNECTION'S CONNECTOR SAMPLES ITS FIELD LISTS rather than enumerating them from a catalog (the connection's fieldReport is SAMPLED on the live schema map; MongoDB reads the union of top-level keys over $sample-d documents), a table's persisted field set is CUMULATIVE WITHIN ITS CURRENT GENERATION: it holds every field any draw has shown since that generation began, and no draw takes a field out of it, because a draw that missed a field is a fact about this service's own sample and never about the source. So a field the map lists may appear in no document the source currently holds; it carries no marker saying so and stays extractable, deliberately, because nothing observed its removal. CUMULATIVE WITHIN A GENERATION IS NOT CUMULATIVE FOREVER: a generation ENDS at any retirement that records why — ABSENT_FROM_CATALOG, COLUMN_SET_SUPERSEDED or CONNECTION_RETIRED, whose meanings the retirementCause property carries — and the next report opens a new generation holding its own fields alone, so a served field set CAN come back narrower across that boundary, with the wider generation dated, caused and still readable on the schema-history surface. WHERE THE FIELD LISTS ARE ENUMERATED from the source's own catalog none of this applies: a table's columns are what the latest probe asserted for the credential that read it, and a catalog list is authoritative over a sampled union — which is what COLUMN_SET_SUPERSEDED records when a connection's connector starts enumerating. The recorded causes are ABSENT_FROM_CATALOG (the source's catalog stopped listing the table), COLUMN_SET_SUPERSEDED (the catalog listed it again with a different non-empty column set; recorded only for a report that ENUMERATED the source's catalog, since a report whose field list was sampled from the source's data retires no column set when a draw differs — that difference is this service's own sample varying and asserts nothing about the source), CONNECTION_RETIRED (an operator retired the connection, the one cause that is genuinely known) and UNKNOWN_LEGACY (archived by an earlier release that recorded no cause)."
+      operationId: getDiscoveryConnectionSchemaHistory
+      parameters:
+        - description: Connection ID (UUID)
+          in: path
+          name: connectionId
+          required: true
+          schema:
+            description: Connection ID (UUID)
+            examples:
+              - 3fa85f64-5717-4562-b3fc-2c963f66afa6
+            format: uuid
+            type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConnectionSchemaHistoryResponse"
+          description: OK
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Get connection schema history
+      tags:
+        - Discovery
   /v1/discovery/connections/{connectionId}/test:
     post:
       description: Tests connectivity for a specific discovered connection owned by the current tenant.
@@ -10209,6 +10438,34 @@ paths:
       summary: Refresh discovery
       tags:
         - Discovery
+  /v1/discovery/rest-connections:
+    post:
+      description: "Provisions a REST acquirer connection (PagBank, Stripe, Pix BCB) and seals its multi-field credential. Which credential fields a connector type requires is published as `requiredFields` on GET /v1/discovery/connector-types — the SAME table this endpoint enforces, so advertisement and enforcement cannot diverge. An optional per-connection `baseURL` overrides the deployment-configured endpoint for that connector type, so one deployment can hold a provider's sandbox and production connections side by side. Database addressing is absent by design: no REST connector uses it. The supplied credential is sealed before persistence and is never returned. The created connection appears in GET /v1/discovery/connections like any other."
+      operationId: createRESTDiscoveryConnection
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RESTConnectionRequest"
+        required: true
+      responses:
+        "201":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConnectionResponse"
+          description: Created
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/Detail"
+          description: Error
+      security:
+        - BearerAuth: []
+      summary: Create REST discovery connection
+      tags:
+        - Discovery
   /v1/discovery/status:
     get:
       description: Returns the current Fetcher integration status including health and connection count.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lerianstudio/matcher-mcp",
-  "version": "4.5.0-beta.13",
+  "version": "4.5.0-beta.14",
   "type": "module",
   "description": "Model Context Protocol server for the Matcher reconciliation engine",
   "license": "Apache-2.0",