@x12i/memorix-service 3.11.0 → 3.12.0

package/dist/openapi/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Memorix Service API",
-    "version": "3.7.8",
+    "version": "3.12.0",
     "description": "One versioned product API over accepted Memorix packages. Scope: orgId + agentIds[]. Headers x-memorix-org-id and x-memorix-agent-ids (comma-separated). MX-CALLER-01: every /api request requires x-memorix-caller (calling app id). Intelligence never auto-installs. Relationships /links is forbidden. IntegrationsRegistry (Stage −1) and RestrictedStore (FG-A3 dual-mode blob)."
   },
   "servers": [
@@ -46,6 +46,10 @@
       "name": "Jobs",
       "description": "Jobs Manager repeated-work API. P3 reads and P4 writes live."
     },
+    {
+      "name": "Hooks",
+      "description": "Content hooks. A subscription is notified after one address is created, updated, or removed. The callback does not run a skill."
+    },
     {
       "name": "Connectors",
       "description": "Unified connector catalog (registry + builtins + MGC remote hosts)"
@@ -2567,6 +2571,17 @@
               "type": "string"
             },
             "description": "Optional SafeSort JSON"
+          },
+          {
+            "name": "count",
+            "in": "query",
+            "schema": {
+              "type": "string",
+              "enum": [
+                "true"
+              ]
+            },
+            "description": "When true, and every filter is eq, in, or exists on a path this agent's live property index names, the response is { count } and does not return the population. Unindexed filters ignore this and return the list."
           }
         ],
         "responses": {
@@ -2619,6 +2634,10 @@
                     "pageInfo": {
                       "$ref": "#/components/schemas/PageInfo"
                     },
+                    "count": {
+                      "type": "integer",
+                      "description": "Present when count=true is served from a live property index. The population is not returned."
+                    },
                     "currentRevision": {
                       "type": "integer",
                       "nullable": true
@@ -2865,6 +2884,10 @@
                       "$ref": "#/components/schemas/PatchOp"
                     }
                   },
+                  "suppressHooks": {
+                    "type": "boolean",
+                    "description": "When true, this write does not notify content-hook subscriptions. Not stored on the record. For bulk load and migration."
+                  },
                   "address": {
                     "$ref": "#/components/schemas/ContentAddress"
                   },
@@ -14377,6 +14400,384 @@
         }
       }
     },
+    "/api/analytics/indexes": {
+      "get": {
+        "operationId": "analyticsIndexesList",
+        "summary": "List property indexes for the caller's agent ids",
+        "description": "Another agent's indexes are not listed. An agent that has declared nothing gets an empty list.",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Indexes for this agent set",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "items"
+                  ],
+                  "properties": {
+                    "items": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/AnalyticsIndex"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics unavailable (no Mongo, or MEMORIX_ANALYTICS=0)",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "operationId": "analyticsIndexesRegister",
+        "summary": "Declare the stored paths Memorix indexes for this agent",
+        "description": "Names an object type, content type, and stored paths. No abstract. The caller's agent ids are the scope. The same definition does not scan again. A different definition needs replace: true.",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "definition"
+                ],
+                "properties": {
+                  "definition": {
+                    "type": "object",
+                    "required": [
+                      "id",
+                      "objectType",
+                      "contentType",
+                      "properties"
+                    ],
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "description": "Stable name for this agent set. Ids starting with @ are reserved."
+                      },
+                      "objectType": {
+                        "type": "string"
+                      },
+                      "contentType": {
+                        "type": "string"
+                      },
+                      "properties": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        },
+                        "description": "Stored paths, such as data.responsePriority. They do not have to be declared fields."
+                      }
+                    }
+                  },
+                  "replace": {
+                    "type": "boolean",
+                    "description": "Required when this id already exists with a different definition. Rebuilds that index only."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Accepted. Backfill scans that population once, then the index stays current from writes.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "id",
+                    "status",
+                    "index"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "status": {
+                      "type": "string"
+                    },
+                    "index": {
+                      "$ref": "#/components/schemas/AnalyticsIndex"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Definition invalid (error.details.issues). A body that includes abstractType is META-ANALYTICS.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "Definition differs without replace, or the same id belongs to another agent set",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/analytics/indexes/validate": {
+      "post": {
+        "operationId": "analyticsIndexesValidate",
+        "summary": "Validate a property index without registering it",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "definition": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Validation result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "ok",
+                    "issues"
+                  ],
+                  "properties": {
+                    "ok": {
+                      "type": "boolean"
+                    },
+                    "issues": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "additionalProperties": true
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/analytics/indexes/{id}": {
+      "get": {
+        "operationId": "analyticsIndexGet",
+        "summary": "One property index for the caller's agent ids",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Index",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AnalyticsIndex"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not declared for this agent set",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "analyticsIndexDelete",
+        "summary": "Drop this agent's property index",
+        "tags": [
+          "Analytics"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/XMemorixCaller"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixOrgId"
+          },
+          {
+            "$ref": "#/components/parameters/XMemorixAgentIds"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Removed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "removed": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not declared for this agent set",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "Analytics unavailable",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorEnvelope"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/api/analytics/source-census": {
       "get": {
         "operationId": "analyticsSourceCensus",
@@ -14530,6 +14931,106 @@
           }
         }
       }
+    },
+    "/api/hooks/v1/subscriptions": {
+      "get": {
+        "operationId": "hooksListSubscriptions",
+        "tags": ["Hooks"],
+        "summary": "List content-hook subscriptions for this org and agent set",
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" }
+        ],
+        "responses": {
+          "200": { "description": "Subscriptions. signingSecret is omitted." }
+        }
+      }
+    },
+    "/api/hooks/v1/subscriptions/{subscriptionId}": {
+      "put": {
+        "operationId": "hooksPutSubscription",
+        "tags": ["Hooks"],
+        "summary": "Create or replace a content-hook subscription",
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" },
+          { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HookSubscriptionWrite" } } }
+        },
+        "responses": {
+          "200": { "description": "Stored subscription. signingSecret is omitted." },
+          "400": { "description": "HOOK_SUBSCRIPTION_INVALID" },
+          "409": { "description": "subscriptionId belongs to a different agent scope" }
+        }
+      },
+      "get": {
+        "operationId": "hooksGetSubscription",
+        "tags": ["Hooks"],
+        "summary": "Read one content-hook subscription",
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" },
+          { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "responses": {
+          "200": { "description": "Subscription. signingSecret is omitted." },
+          "404": { "description": "HOOK_SUBSCRIPTION_NOT_FOUND" }
+        }
+      },
+      "patch": {
+        "operationId": "hooksPatchSubscription",
+        "tags": ["Hooks"],
+        "summary": "Update enabled, endpoint, or match",
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" },
+          { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "responses": {
+          "200": { "description": "Updated subscription. signingSecret is omitted." },
+          "400": { "description": "HOOK_SUBSCRIPTION_INVALID" },
+          "404": { "description": "HOOK_SUBSCRIPTION_NOT_FOUND" }
+        }
+      },
+      "delete": {
+        "operationId": "hooksDeleteSubscription",
+        "tags": ["Hooks"],
+        "summary": "Remove a subscription and stop pending delivery",
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" },
+          { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "responses": {
+          "200": { "description": "Removed" },
+          "404": { "description": "HOOK_SUBSCRIPTION_NOT_FOUND" }
+        }
+      }
+    },
+    "/api/hooks/v1/subscriptions/{subscriptionId}/deliveries": {
+      "get": {
+        "operationId": "hooksListDeliveries",
+        "tags": ["Hooks"],
+        "summary": "Recent delivery status, newest first",
+        "parameters": [
+          { "$ref": "#/components/parameters/XMemorixCaller" },
+          { "$ref": "#/components/parameters/XMemorixOrgId" },
+          { "$ref": "#/components/parameters/XMemorixAgentIds" },
+          { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" } },
+          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "delivered", "rejected", "failed"] } }
+        ],
+        "responses": {
+          "200": { "description": "Delivery rows. Not stored on the subject record." }
+        }
+      }
     }
   },
   "components": {
@@ -14570,6 +15071,36 @@
       }
     },
     "schemas": {
+      "HookSubscriptionWrite": {
+        "type": "object",
+        "required": ["endpoint", "match"],
+        "additionalProperties": false,
+        "properties": {
+          "endpoint": { "type": "string", "format": "uri" },
+          "enabled": { "type": "boolean" },
+          "signingSecret": { "type": "string", "description": "Required on create. Write-only. A later PUT that omits it keeps the stored secret." },
+          "match": {
+            "type": "object",
+            "required": ["objectType", "contentType", "events"],
+            "additionalProperties": false,
+            "properties": {
+              "objectType": { "type": "string" },
+              "contentType": { "type": "string" },
+              "discriminator": {
+                "type": "object",
+                "required": ["path", "equals"],
+                "additionalProperties": false,
+                "properties": {
+                  "path": { "type": "string" },
+                  "equals": {}
+                }
+              },
+              "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": ["created", "updated", "removed"] } },
+              "ignoreCallers": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      },
       "MemorixScope": {
         "type": "object",
         "required": [
@@ -16874,6 +17405,85 @@
           }
         }
       },
+      "AnalyticsIndex": {
+        "type": "object",
+        "required": [
+          "id",
+          "objectType",
+          "contentType",
+          "properties",
+          "status",
+          "generation",
+          "hash",
+          "agentIds",
+          "backfill"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "objectType": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": "string"
+          },
+          "properties": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "backfilling",
+              "live",
+              "error"
+            ]
+          },
+          "generation": {
+            "type": "integer"
+          },
+          "hash": {
+            "type": "string"
+          },
+          "agentIds": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "backfill": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "registeredAt": {
+            "type": "string"
+          },
+          "registeredBy": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "updatedAt": {
+            "type": "string"
+          },
+          "liveAt": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "error": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        }
+      },
       "AnalyticsCounter": {
         "type": "object",
         "required": [