@openhands/extensions 0.9.0 → 0.10.0

package/.github/workflows/deprecation-check.yml

@@ -0,0 +1,25 @@
+name: Deprecation deadlines
+
+# release-please opens its release PR with the OpenHands GitHub App token, so
+# this pull_request workflow also runs against the generated version bump.
+on:
+  pull_request:
+    branches: ["**"]
+  push:
+    branches: ["main", "master"]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Verify deprecation deadlines
+        run: uv run python scripts/check_deprecations.py

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.9.0"
+  ".": "0.10.0"
 }

package/integrations/README.md

@@ -18,6 +18,31 @@ integrations so clients can consume one source of truth.
 Each integration carries its OAuth/MCP connection data directly. Do not add a
 separate provider catalog or per-language provider data.
 
+Every entry must include `docsUrl`. Marketplace input fields must explicitly
+declare both their `type` and whether they are `required`, rather than relying
+on client defaults. When connection metadata includes an `identityMapping`, it
+must also identify the external principal. These requirements keep catalogs
+actionable and prevent clients from guessing security- or UX-relevant defaults.
+
+Connection options may also carry an optional `connectionModel`. This metadata
+lets consumers distinguish the authenticated principal from the external
+resource the credential can reach:
+
+- `principalType` describes who or what authenticated.
+- `credentialScope` describes the provider boundary enforced by the credential.
+- `resourceType` and `resourceCardinality` describe whether the grant represents
+  one workspace/site/tenant or can enumerate several.
+- `selectionMode` tells clients whether the resource is known during auth,
+  selected immediately after auth, or supplied at runtime.
+- `identityMapping` contains constrained dot paths for identity values returned
+  by OAuth, access-token claims, or a provider identity endpoint.
+- `resourceDiscovery` describes a read-only endpoint used to enumerate resources
+  when one grant covers several of them.
+
+These fields are descriptive; they never broaden the scopes enforced by the
+provider credential. Consumers must not claim resource-level isolation when a
+provider token is only account- or tenant-scoped.
+
 Consumers should use the read functions exported by the package:
 
 ```js

package/integrations/catalog/atlassian.json

@@ -24,6 +24,19 @@
     {
       "id": "oauth",
       "provider": "mcp",
+      "connectionModel": {
+        "principalType": "user",
+        "credentialScope": "account",
+        "resourceType": "site",
+        "resourceCardinality": "many",
+        "selectionMode": "post_auth",
+        "resourceDiscovery": {
+          "endpoint": "https://api.atlassian.com/oauth/token/accessible-resources",
+          "externalResourceIdPath": "id",
+          "resourceNamePath": "name",
+          "resourceUrlPath": "url"
+        }
+      },
       "transport": {
         "kind": "shttp",
         "url": "https://mcp.atlassian.com/v1/mcp"

package/integrations/catalog/github.json

@@ -14,6 +14,26 @@
     {
       "id": "oauth",
       "provider": "mcp",
+      "connectionModel": {
+        "principalType": "user",
+        "credentialScope": "account",
+        "resourceType": "organization",
+        "resourceCardinality": "many",
+        "selectionMode": "post_auth",
+        "identityMapping": {
+          "source": "identity_api",
+          "endpoint": "https://api.github.com/user",
+          "externalPrincipalIdPath": "id",
+          "resourceNamePath": "login",
+          "resourceUrlPath": "html_url"
+        },
+        "resourceDiscovery": {
+          "endpoint": "https://api.github.com/user/orgs",
+          "externalResourceIdPath": "id",
+          "resourceNamePath": "login",
+          "resourceUrlPath": "html_url"
+        }
+      },
       "auth": {
         "strategy": "oauth2",
         "oauth": {

package/integrations/catalog/microsoft-outlook.json

@@ -14,6 +14,19 @@
     {
       "id": "oauth",
       "provider": "http",
+      "connectionModel": {
+        "principalType": "user",
+        "credentialScope": "tenant",
+        "resourceType": "tenant",
+        "resourceCardinality": "one",
+        "selectionMode": "automatic",
+        "identityMapping": {
+          "source": "access_token_claims",
+          "externalPrincipalIdPath": "oid",
+          "externalTenantIdPath": "tid",
+          "externalResourceIdPath": "tid"
+        }
+      },
       "auth": {
         "strategy": "oauth2",
         "oauth": {

package/integrations/catalog/microsoft-teams.json

@@ -14,6 +14,19 @@
     {
       "id": "oauth",
       "provider": "http",
+      "connectionModel": {
+        "principalType": "user",
+        "credentialScope": "tenant",
+        "resourceType": "tenant",
+        "resourceCardinality": "one",
+        "selectionMode": "automatic",
+        "identityMapping": {
+          "source": "access_token_claims",
+          "externalPrincipalIdPath": "oid",
+          "externalTenantIdPath": "tid",
+          "externalResourceIdPath": "tid"
+        }
+      },
       "auth": {
         "strategy": "oauth2",
         "oauth": {

package/integrations/catalog/notion.json

@@ -13,6 +13,19 @@
     {
       "id": "oauth",
       "provider": "http",
+      "connectionModel": {
+        "principalType": "user",
+        "credentialScope": "resource",
+        "resourceType": "workspace",
+        "resourceCardinality": "one",
+        "selectionMode": "automatic",
+        "identityMapping": {
+          "source": "oauth_token_response",
+          "externalPrincipalIdPath": "owner.user.id",
+          "externalResourceIdPath": "workspace_id",
+          "resourceNamePath": "workspace_name"
+        }
+      },
       "auth": {
         "strategy": "oauth2",
         "oauth": {

package/integrations/catalog/onedrive.json

@@ -14,6 +14,19 @@
     {
       "id": "oauth",
       "provider": "http",
+      "connectionModel": {
+        "principalType": "user",
+        "credentialScope": "tenant",
+        "resourceType": "tenant",
+        "resourceCardinality": "one",
+        "selectionMode": "automatic",
+        "identityMapping": {
+          "source": "access_token_claims",
+          "externalPrincipalIdPath": "oid",
+          "externalTenantIdPath": "tid",
+          "externalResourceIdPath": "tid"
+        }
+      },
       "auth": {
         "strategy": "oauth2",
         "oauth": {

package/integrations/catalog/sharepoint.json

@@ -14,6 +14,19 @@
     {
       "id": "oauth",
       "provider": "http",
+      "connectionModel": {
+        "principalType": "user",
+        "credentialScope": "tenant",
+        "resourceType": "tenant",
+        "resourceCardinality": "one",
+        "selectionMode": "automatic",
+        "identityMapping": {
+          "source": "access_token_claims",
+          "externalPrincipalIdPath": "oid",
+          "externalTenantIdPath": "tid",
+          "externalResourceIdPath": "tid"
+        }
+      },
       "auth": {
         "strategy": "oauth2",
         "oauth": {

package/integrations/catalog/slack.json

@@ -14,6 +14,20 @@
     {
       "id": "oauth",
       "provider": "mcp",
+      "connectionModel": {
+        "principalType": "user",
+        "credentialScope": "resource",
+        "resourceType": "workspace",
+        "resourceCardinality": "one",
+        "selectionMode": "automatic",
+        "identityMapping": {
+          "source": "oauth_token_response",
+          "externalPrincipalIdPath": "authed_user.id",
+          "externalTenantIdPath": "enterprise.id",
+          "externalResourceIdPath": "team.id",
+          "resourceNamePath": "team.name"
+        }
+      },
       "auth": {
         "strategy": "oauth2",
         "oauth": {

package/integrations/catalog/vanta.json

@@ -0,0 +1,55 @@
+{
+  "id": "vanta",
+  "name": "Vanta",
+  "description": "Query Vanta compliance controls, tests, evidence, risks, and vulnerabilities from the agent.",
+  "categories": [
+    "Security",
+    "Compliance"
+  ],
+  "appUrl": "https://www.vanta.com",
+  "docsUrl": "https://developer.vanta.com/docs/vanta-mcp",
+  "notes": "Vanta's hosted remote MCP server (beta, requires a Vanta Admin role). Regional endpoints: US https://mcp.vanta.com/mcp, EU https://mcp.eu.vanta.com/mcp, AUS https://mcp.aus.vanta.com/mcp. Authentication is OAuth only - no API keys.",
+  "popularityRank": 64,
+  "connectionOptions": [
+    {
+      "id": "oauth",
+      "provider": "mcp",
+      "auth": {
+        "strategy": "oauth2",
+        "oauth": {
+          "authorizationUrl": "https://app.vanta.com/oauth/authorize",
+          "tokenUrl": "https://api.vanta.com/oauth/token",
+          "registrationUrl": "https://api.vanta.com/oauth/register",
+          "scopes": [
+            "mcp-api.all:read"
+          ],
+          "optionalScopes": [
+            "mcp-api.all:write"
+          ],
+          "pkce": true,
+          "clientAuthentication": "none",
+          "additionalAuthorizationParams": {
+            "resource": "https://mcp.vanta.com"
+          },
+          "additionalTokenParams": {
+            "resource": "https://mcp.vanta.com"
+          }
+        }
+      },
+      "transport": {
+        "kind": "shttp",
+        "url": "https://mcp.vanta.com/mcp"
+      }
+    }
+  ],
+  "iconBg": "#003D2B",
+  "keywords": [
+    "compliance",
+    "soc2",
+    "security",
+    "audit",
+    "risk",
+    "vanta"
+  ],
+  "installHint": "Connect via the OAuth MCP option. After connecting, complete the OAuth flow in your browser as a Vanta Admin. EU tenants should use https://mcp.eu.vanta.com/mcp and AUS tenants https://mcp.aus.vanta.com/mcp as the transport URL. The legacy local server @vantasdk/vanta-mcp-server is deprecated - prefer the hosted remote server."
+}

package/integrations/catalog-index.js

@@ -8,73 +8,74 @@ import entry2 from "./catalog/tavily.json" with { type: "json" };
 import entry3 from "./catalog/atlassian.json" with { type: "json" };
 import entry4 from "./catalog/linear.json" with { type: "json" };
 import entry5 from "./catalog/notion.json" with { type: "json" };
-import entry6 from "./catalog/ordinal.json" with { type: "json" };
-import entry7 from "./catalog/elevenlabs.json" with { type: "json" };
-import entry8 from "./catalog/bitbucket.json" with { type: "json" };
-import entry9 from "./catalog/xero.json" with { type: "json" };
-import entry10 from "./catalog/quickbooks.json" with { type: "json" };
-import entry11 from "./catalog/okta.json" with { type: "json" };
-import entry12 from "./catalog/netlify.json" with { type: "json" };
-import entry13 from "./catalog/vercel.json" with { type: "json" };
-import entry14 from "./catalog/supabase.json" with { type: "json" };
-import entry15 from "./catalog/posthog.json" with { type: "json" };
-import entry16 from "./catalog/sentry.json" with { type: "json" };
-import entry17 from "./catalog/datadog.json" with { type: "json" };
-import entry18 from "./catalog/canva.json" with { type: "json" };
-import entry19 from "./catalog/miro.json" with { type: "json" };
-import entry20 from "./catalog/webflow.json" with { type: "json" };
-import entry21 from "./catalog/zoom.json" with { type: "json" };
-import entry22 from "./catalog/discord.json" with { type: "json" };
-import entry23 from "./catalog/stripe.json" with { type: "json" };
-import entry24 from "./catalog/intercom.json" with { type: "json" };
-import entry25 from "./catalog/hubspot.json" with { type: "json" };
-import entry26 from "./catalog/salesforce.json" with { type: "json" };
-import entry27 from "./catalog/sharepoint.json" with { type: "json" };
-import entry28 from "./catalog/onedrive.json" with { type: "json" };
-import entry29 from "./catalog/microsoft-teams.json" with { type: "json" };
-import entry30 from "./catalog/microsoft-outlook.json" with { type: "json" };
-import entry31 from "./catalog/box.json" with { type: "json" };
-import entry32 from "./catalog/airtable.json" with { type: "json" };
-import entry33 from "./catalog/monday.json" with { type: "json" };
-import entry34 from "./catalog/trello.json" with { type: "json" };
-import entry35 from "./catalog/asana.json" with { type: "json" };
-import entry36 from "./catalog/confluence.json" with { type: "json" };
-import entry37 from "./catalog/jira.json" with { type: "json" };
-import entry38 from "./catalog/google-calendar.json" with { type: "json" };
-import entry39 from "./catalog/gmail.json" with { type: "json" };
-import entry40 from "./catalog/google-sheets.json" with { type: "json" };
-import entry41 from "./catalog/google-drive.json" with { type: "json" };
-import entry42 from "./catalog/figma.json" with { type: "json" };
-import entry43 from "./catalog/google-docs.json" with { type: "json" };
-import entry44 from "./catalog/apify.json" with { type: "json" };
-import entry45 from "./catalog/brave-search.json" with { type: "json" };
-import entry46 from "./catalog/browser-mcp.json" with { type: "json" };
-import entry47 from "./catalog/clickhouse.json" with { type: "json" };
-import entry48 from "./catalog/cloudflare-bindings.json" with { type: "json" };
-import entry49 from "./catalog/cloudflare-browser-rendering.json" with { type: "json" };
-import entry50 from "./catalog/cloudflare-builds.json" with { type: "json" };
-import entry51 from "./catalog/cloudflare-docs.json" with { type: "json" };
-import entry52 from "./catalog/cloudflare-observability.json" with { type: "json" };
-import entry53 from "./catalog/deepwiki.json" with { type: "json" };
-import entry54 from "./catalog/everything.json" with { type: "json" };
-import entry55 from "./catalog/exa.json" with { type: "json" };
-import entry56 from "./catalog/fetch.json" with { type: "json" };
-import entry57 from "./catalog/filesystem.json" with { type: "json" };
-import entry58 from "./catalog/firecrawl.json" with { type: "json" };
-import entry59 from "./catalog/git.json" with { type: "json" };
-import entry60 from "./catalog/huggingface.json" with { type: "json" };
-import entry61 from "./catalog/kagi.json" with { type: "json" };
-import entry62 from "./catalog/memory.json" with { type: "json" };
-import entry63 from "./catalog/mongodb.json" with { type: "json" };
-import entry64 from "./catalog/neon.json" with { type: "json" };
-import entry65 from "./catalog/obsidian.json" with { type: "json" };
-import entry66 from "./catalog/paypal.json" with { type: "json" };
-import entry67 from "./catalog/playwright.json" with { type: "json" };
-import entry68 from "./catalog/redis.json" with { type: "json" };
-import entry69 from "./catalog/resend.json" with { type: "json" };
-import entry70 from "./catalog/sequential-thinking.json" with { type: "json" };
-import entry71 from "./catalog/superhuman-mail.json" with { type: "json" };
-import entry72 from "./catalog/time.json" with { type: "json" };
+import entry6 from "./catalog/vanta.json" with { type: "json" };
+import entry7 from "./catalog/ordinal.json" with { type: "json" };
+import entry8 from "./catalog/elevenlabs.json" with { type: "json" };
+import entry9 from "./catalog/bitbucket.json" with { type: "json" };
+import entry10 from "./catalog/xero.json" with { type: "json" };
+import entry11 from "./catalog/quickbooks.json" with { type: "json" };
+import entry12 from "./catalog/okta.json" with { type: "json" };
+import entry13 from "./catalog/netlify.json" with { type: "json" };
+import entry14 from "./catalog/vercel.json" with { type: "json" };
+import entry15 from "./catalog/supabase.json" with { type: "json" };
+import entry16 from "./catalog/posthog.json" with { type: "json" };
+import entry17 from "./catalog/sentry.json" with { type: "json" };
+import entry18 from "./catalog/datadog.json" with { type: "json" };
+import entry19 from "./catalog/canva.json" with { type: "json" };
+import entry20 from "./catalog/miro.json" with { type: "json" };
+import entry21 from "./catalog/webflow.json" with { type: "json" };
+import entry22 from "./catalog/zoom.json" with { type: "json" };
+import entry23 from "./catalog/discord.json" with { type: "json" };
+import entry24 from "./catalog/stripe.json" with { type: "json" };
+import entry25 from "./catalog/intercom.json" with { type: "json" };
+import entry26 from "./catalog/hubspot.json" with { type: "json" };
+import entry27 from "./catalog/salesforce.json" with { type: "json" };
+import entry28 from "./catalog/sharepoint.json" with { type: "json" };
+import entry29 from "./catalog/onedrive.json" with { type: "json" };
+import entry30 from "./catalog/microsoft-teams.json" with { type: "json" };
+import entry31 from "./catalog/microsoft-outlook.json" with { type: "json" };
+import entry32 from "./catalog/box.json" with { type: "json" };
+import entry33 from "./catalog/airtable.json" with { type: "json" };
+import entry34 from "./catalog/monday.json" with { type: "json" };
+import entry35 from "./catalog/trello.json" with { type: "json" };
+import entry36 from "./catalog/asana.json" with { type: "json" };
+import entry37 from "./catalog/confluence.json" with { type: "json" };
+import entry38 from "./catalog/jira.json" with { type: "json" };
+import entry39 from "./catalog/google-calendar.json" with { type: "json" };
+import entry40 from "./catalog/gmail.json" with { type: "json" };
+import entry41 from "./catalog/google-sheets.json" with { type: "json" };
+import entry42 from "./catalog/google-drive.json" with { type: "json" };
+import entry43 from "./catalog/figma.json" with { type: "json" };
+import entry44 from "./catalog/google-docs.json" with { type: "json" };
+import entry45 from "./catalog/apify.json" with { type: "json" };
+import entry46 from "./catalog/brave-search.json" with { type: "json" };
+import entry47 from "./catalog/browser-mcp.json" with { type: "json" };
+import entry48 from "./catalog/clickhouse.json" with { type: "json" };
+import entry49 from "./catalog/cloudflare-bindings.json" with { type: "json" };
+import entry50 from "./catalog/cloudflare-browser-rendering.json" with { type: "json" };
+import entry51 from "./catalog/cloudflare-builds.json" with { type: "json" };
+import entry52 from "./catalog/cloudflare-docs.json" with { type: "json" };
+import entry53 from "./catalog/cloudflare-observability.json" with { type: "json" };
+import entry54 from "./catalog/deepwiki.json" with { type: "json" };
+import entry55 from "./catalog/everything.json" with { type: "json" };
+import entry56 from "./catalog/exa.json" with { type: "json" };
+import entry57 from "./catalog/fetch.json" with { type: "json" };
+import entry58 from "./catalog/filesystem.json" with { type: "json" };
+import entry59 from "./catalog/firecrawl.json" with { type: "json" };
+import entry60 from "./catalog/git.json" with { type: "json" };
+import entry61 from "./catalog/huggingface.json" with { type: "json" };
+import entry62 from "./catalog/kagi.json" with { type: "json" };
+import entry63 from "./catalog/memory.json" with { type: "json" };
+import entry64 from "./catalog/mongodb.json" with { type: "json" };
+import entry65 from "./catalog/neon.json" with { type: "json" };
+import entry66 from "./catalog/obsidian.json" with { type: "json" };
+import entry67 from "./catalog/paypal.json" with { type: "json" };
+import entry68 from "./catalog/playwright.json" with { type: "json" };
+import entry69 from "./catalog/redis.json" with { type: "json" };
+import entry70 from "./catalog/resend.json" with { type: "json" };
+import entry71 from "./catalog/sequential-thinking.json" with { type: "json" };
+import entry72 from "./catalog/superhuman-mail.json" with { type: "json" };
+import entry73 from "./catalog/time.json" with { type: "json" };
 
 export const INTEGRATION_CATALOG_ENTRIES = [
   entry0,
@@ -150,4 +151,5 @@ export const INTEGRATION_CATALOG_ENTRIES = [
   entry70,
   entry71,
   entry72,
+  entry73,
 ];

package/integrations/catalog.schema.json

@@ -5,7 +5,7 @@
   "description": "Strict schema for integrations/catalog/*.json. Mirrors integrations/index.d.ts and encodes the cross-field connectability rules the catalog contract depends on.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["id", "name", "description", "connectionOptions"],
+  "required": ["id", "name", "description", "docsUrl", "connectionOptions"],
   "properties": {
     "id": { "type": "string", "minLength": 1 },
     "name": { "type": "string", "minLength": 1 },
@@ -39,7 +39,7 @@
     "marketplaceField": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["key", "label"],
+      "required": ["key", "label", "type", "required"],
       "properties": {
         "key": { "type": "string", "minLength": 1 },
         "label": { "type": "string", "minLength": 1 },
@@ -91,6 +91,72 @@
         }
       }
     },
+    "identityPath": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+)*$",
+      "minLength": 1
+    },
+    "identityMapping": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "externalPrincipalIdPath"],
+      "properties": {
+        "source": {
+          "enum": ["oauth_token_response", "access_token_claims", "identity_api"]
+        },
+        "endpoint": { "type": "string", "pattern": "^https://", "minLength": 8 },
+        "externalPrincipalIdPath": { "$ref": "#/$defs/identityPath" },
+        "externalTenantIdPath": { "$ref": "#/$defs/identityPath" },
+        "externalResourceIdPath": { "$ref": "#/$defs/identityPath" },
+        "resourceNamePath": { "$ref": "#/$defs/identityPath" },
+        "resourceUrlPath": { "$ref": "#/$defs/identityPath" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "source": { "const": "identity_api" } } },
+          "then": { "required": ["endpoint"] },
+          "else": { "not": { "required": ["endpoint"] } }
+        }
+      ]
+    },
+    "resourceDiscovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["endpoint", "externalResourceIdPath"],
+      "properties": {
+        "endpoint": { "type": "string", "pattern": "^https://", "minLength": 8 },
+        "itemsPath": { "$ref": "#/$defs/identityPath" },
+        "externalResourceIdPath": { "$ref": "#/$defs/identityPath" },
+        "resourceNamePath": { "$ref": "#/$defs/identityPath" },
+        "resourceUrlPath": { "$ref": "#/$defs/identityPath" }
+      }
+    },
+    "connectionModel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "principalType",
+        "credentialScope",
+        "resourceType",
+        "resourceCardinality",
+        "selectionMode"
+      ],
+      "properties": {
+        "principalType": { "enum": ["user", "bot", "service_account", "application"] },
+        "credentialScope": { "enum": ["account", "tenant", "organization", "resource"] },
+        "resourceType": { "type": "string", "minLength": 1 },
+        "resourceCardinality": { "enum": ["one", "many"] },
+        "selectionMode": { "enum": ["automatic", "post_auth", "runtime"] },
+        "identityMapping": { "$ref": "#/$defs/identityMapping" },
+        "resourceDiscovery": { "$ref": "#/$defs/resourceDiscovery" }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "selectionMode": { "const": "post_auth" } } },
+          "then": { "required": ["resourceDiscovery"] }
+        }
+      ]
+    },
     "authConfig": {
       "type": "object",
       "additionalProperties": false,
@@ -186,7 +252,8 @@
         "provider": { "enum": ["mcp", "http"] },
         "transport": { "$ref": "#/$defs/transport" },
         "http": { "$ref": "#/$defs/httpConfig" },
-        "auth": { "$ref": "#/$defs/authConfig" }
+        "auth": { "$ref": "#/$defs/authConfig" },
+        "connectionModel": { "$ref": "#/$defs/connectionModel" }
       },
       "allOf": [
         {

package/integrations/index.d.ts

@@ -3,11 +3,11 @@ export type MarketplaceFieldType = "text" | "password";
 export interface MarketplaceField {
   key: string;
   label: string;
-  type?: MarketplaceFieldType;
+  type: MarketplaceFieldType;
   placeholder?: string;
   helperText?: string;
   helperLink?: string;
-  required?: boolean;
+  required: boolean;
 }
 
 export type IntegrationTransport =
@@ -95,12 +95,58 @@ export interface IntegrationHttpConfig {
   openApiUrl?: string;
 }
 
+export type IntegrationPrincipalType =
+  | "user"
+  | "bot"
+  | "service_account"
+  | "application";
+
+export type IntegrationCredentialScope =
+  | "account"
+  | "tenant"
+  | "organization"
+  | "resource";
+
+export type IntegrationIdentitySource =
+  | "oauth_token_response"
+  | "access_token_claims"
+  | "identity_api";
+
+export interface IntegrationIdentityMapping {
+  source: IntegrationIdentitySource;
+  endpoint?: string;
+  externalPrincipalIdPath: string;
+  externalTenantIdPath?: string;
+  externalResourceIdPath?: string;
+  resourceNamePath?: string;
+  resourceUrlPath?: string;
+}
+
+export interface IntegrationResourceDiscovery {
+  endpoint: string;
+  itemsPath?: string;
+  externalResourceIdPath: string;
+  resourceNamePath?: string;
+  resourceUrlPath?: string;
+}
+
+export interface IntegrationConnectionModel {
+  principalType: IntegrationPrincipalType;
+  credentialScope: IntegrationCredentialScope;
+  resourceType: string;
+  resourceCardinality: "one" | "many";
+  selectionMode: "automatic" | "post_auth" | "runtime";
+  identityMapping?: IntegrationIdentityMapping;
+  resourceDiscovery?: IntegrationResourceDiscovery;
+}
+
 export interface IntegrationConnectionOption {
   id: "oauth" | "api" | "none" | string;
   provider: IntegrationProvider;
   transport?: IntegrationTransport;
   http?: IntegrationHttpConfig;
   auth: IntegrationAuthConfig;
+  connectionModel?: IntegrationConnectionModel;
 }
 
 
@@ -110,7 +156,7 @@ export interface IntegrationCatalogEntry {
   description: string;
   categories?: string[];
   appUrl?: string;
-  docsUrl?: string;
+  docsUrl: string;
   notes?: string;
   iconBg?: string;
   iconColor?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",