@fourier-labs/harbour-contracts 0.44.0 → 0.46.0

package/schema/saas-connection.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.harbour.dev/saas-connection.schema.json",
+  "title": "SaasConnection",
+  "description": "Tenant-wide SaaS connection record (control table sk SAASCONN#<sourceId>, same tenant partition as database sources; alias uniqueness is enforced across both). IT maps each environment to a provider installation and logical channel aliases to channel IDs; apps only ever see the aliases. Contains references, never secrets: the client secret lives in Secrets Manager under clientSecretRef and installation tokens under their own token records.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sourceId", "kind", "provider", "displayName", "status", "version", "clientId", "environments", "operations", "developmentPreapproval"],
+  "properties": {
+    "sourceId": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+    "kind": { "type": "string", "const": "saas" },
+    "provider": { "type": "string", "enum": ["slack"] },
+    "displayName": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "status": { "$ref": "#/definitions/SaasConnectionStatus" },
+    "version": { "type": "integer", "minimum": 1, "description": "Optimistic-concurrency version; every write is conditional on it." },
+    "clientId": { "type": "string", "minLength": 1, "maxLength": 255 },
+    "clientSecretRef": {
+      "type": "string",
+      "pattern": "^secretref://[A-Za-z0-9][A-Za-z0-9/_.:-]*$",
+      "description": "secretref://tenant/{tenantId}/saas/{sourceId}/client"
+    },
+    "environments": {
+      "type": "object",
+      "additionalProperties": false,
+      "minProperties": 1,
+      "properties": {
+        "development": { "$ref": "#/definitions/SaasEnvironmentMapping" },
+        "preview": { "$ref": "#/definitions/SaasEnvironmentMapping" },
+        "production": { "$ref": "#/definitions/SaasEnvironmentMapping" }
+      }
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 2,
+      "uniqueItems": true,
+      "items": { "type": "string", "enum": ["slack.channel.history", "slack.message.post"] },
+      "description": "Operations IT allows apps to request on this connection."
+    },
+    "developmentPreapproval": { "$ref": "#/definitions/DevelopmentPreapproval" },
+    "installations": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/definitions/InstallationName" },
+      "additionalProperties": { "$ref": "#/definitions/SaasInstallation" },
+      "description": "Provider installations keyed by the installation name environments point at."
+    },
+    "createdAt": { "type": "string", "format": "date-time" },
+    "updatedAt": { "type": "string", "format": "date-time" }
+  },
+  "definitions": {
+    "SaasConnectionStatus": {
+      "type": "string",
+      "enum": ["ACTIVE", "DISABLED"],
+      "description": "DISABLED stops every app call immediately (details.code CONNECTION_DISABLED)."
+    },
+    "InstallationName": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,62}$" },
+    "SaasEnvironmentMapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["installation", "channels"],
+      "properties": {
+        "installation": { "$ref": "#/definitions/InstallationName" },
+        "channels": {
+          "type": "object",
+          "maxProperties": 64,
+          "propertyNames": { "$ref": "app-integrations-declaration.schema.json#/definitions/IntegrationAlias" },
+          "additionalProperties": { "type": "string", "pattern": "^[A-Z0-9]{1,32}$", "description": "Provider channel ID; only public, non-archived channels are valid." }
+        }
+      }
+    },
+    "DevelopmentPreapproval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "hours"],
+      "properties": {
+        "enabled": { "type": "boolean", "description": "Auto-approve development requests within the allowlist." },
+        "hours": { "type": "integer", "minimum": 1, "maximum": 168, "description": "Development grant duration; default 24." }
+      }
+    },
+    "SaasInstallation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tokenRecordId", "workspaceId", "botUserId", "status"],
+      "properties": {
+        "tokenRecordId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "workspaceId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "botUserId": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "status": { "type": "string", "enum": ["ACTIVE", "RECONNECT_REQUIRED", "REVOKED"] }
+      }
+    }
+  },
+  "examples": [
+    {
+      "sourceId": "company-slack",
+      "kind": "saas",
+      "provider": "slack",
+      "displayName": "Company Slack",
+      "status": "ACTIVE",
+      "version": 3,
+      "clientId": "1234567890.1234567890",
+      "clientSecretRef": "secretref://tenant/fourier/saas/company-slack/client",
+      "environments": {
+        "development": { "installation": "nonprod", "channels": { "team-updates": "C0123NONPROD" } },
+        "production": { "installation": "prod", "channels": { "team-updates": "C0123PROD" } }
+      },
+      "operations": ["slack.channel.history", "slack.message.post"],
+      "developmentPreapproval": { "enabled": true, "hours": 24 },
+      "installations": {
+        "nonprod": { "tokenRecordId": "tok_nonprod", "workspaceId": "T0NONPROD", "botUserId": "U0BOT", "status": "ACTIVE" }
+      },
+      "createdAt": "2026-09-09T08:00:00Z",
+      "updatedAt": "2026-09-09T08:00:00Z"
+    }
+  ]
+}