@opengeni/capabilities 0.1.1 → 0.2.0

package/README.md

@@ -13,7 +13,7 @@ Security defaults:
 
 - credentials are resolved for one exact destination and verified before use;
 - header, query, and cookie placements are bounded and validated atomically;
-- Google/Microsoft preset OAuth stays in the normal encrypted Connection spine;
+- curated Google/Microsoft Integration Definition OAuth stays in the normal encrypted Connection spine;
 - redirects are never followed on credential-bearing requests;
 - response bodies, schemas, operation counts, and deadlines are bounded;
 - mutating operations are marked approval-required by default;

package/THIRD_PARTY_NOTICES

@@ -2,8 +2,8 @@ This package contains adapted portions of Executor (https://github.com/executorj
 copyright (c) 2026 Rhys Sullivan, used under the MIT License.
 
 The adapted concepts include deterministic MCP tool identifiers, OpenAPI and
-GraphQL extraction/invocation boundaries, auth-placement modeling, provider
-preset normalization, and MCP manifest projection. Executor's Effect/FumaDB
+GraphQL extraction/invocation boundaries, auth-placement modeling, curated
+Integration Definition normalization, and MCP manifest projection. Executor's Effect/FumaDB
 application architecture, persistence, secret stores, runtime hosts, and UI
 state are not included.
 

package/dist/graphql.d.ts

@@ -12,7 +12,7 @@ export interface GraphqlOperationBinding {
 }
 export type GraphqlRevision = IntegrationRevision<GraphqlOperationBinding, "graphql">;
 export interface CompileGraphqlOptions {
-    readonly integrationId: string;
+    readonly definitionId: string;
     readonly endpoint: string;
     readonly name?: string;
     readonly sourceUrl?: string;

package/dist/index.d.ts

@@ -3,6 +3,6 @@ export * from "./graphql.js";
 export * from "./http.js";
 export * from "./mcp-manifest.js";
 export * from "./openapi.js";
-export * from "./providers.js";
+export * from "./integration-definitions.js";
 export * from "./revision.js";
 export * from "./types.js";

package/dist/index.js

@@ -397,13 +397,13 @@ function compileGraphqlRevision(introspection, options) {
   return {
     id,
     protocol: "graphql",
-    integrationId: options.integrationId,
+    definitionId: options.definitionId,
     contentSha256,
     source: {
       url: options.sourceUrl ?? endpoint,
       ...options.provider ? { provider: options.provider } : {}
     },
-    title: options.name?.trim() || options.integrationId,
+    title: options.name?.trim() || options.definitionId,
     tools,
     bindings
   };
@@ -463,7 +463,7 @@ async function fetchGraphqlIntrospection(options) {
 var GraphqlMcpServer = class {
   constructor(options) {
     this.options = options;
-    this.name = `graphql:${stableToolId(options.revision.integrationId)}`;
+    this.name = `graphql:${stableToolId(options.revision.definitionId)}`;
   }
   cacheToolsList = true;
   useStructuredContent = true;
@@ -534,7 +534,7 @@ async function invokeGraphqlOperation(options, toolId, args, signal) {
   const request = { query, variables, operationName: binding.operationName };
   const firstCredential = await resolveGraphqlCredential(
     options,
-    options.revision.integrationId,
+    options.revision.definitionId,
     options.revision.id,
     toolId,
     false
@@ -543,7 +543,7 @@ async function invokeGraphqlOperation(options, toolId, args, signal) {
   if (response.status === 401 && options.credentialResolver && options.authority.connectionRef) {
     const refreshed = await resolveGraphqlCredential(
       options,
-      options.revision.integrationId,
+      options.revision.definitionId,
       options.revision.id,
       toolId,
       true
@@ -592,12 +592,12 @@ async function invokeGraphqlOperation(options, toolId, args, signal) {
     errors: graph.errors ?? null
   };
 }
-async function resolveGraphqlCredential(options, integrationId, revisionId, operationKey, forceRefresh) {
+async function resolveGraphqlCredential(options, definitionId, revisionId, operationKey, forceRefresh) {
   if (!options.credentialResolver || !options.authority.connectionRef) return null;
   const credential = await options.credentialResolver.resolve({
     ...options.authority,
     protocol: "graphql",
-    integrationId,
+    definitionId,
     revisionId,
     operationKey,
     destinationUrl: graphqlEndpoint(options).toString(),
@@ -947,13 +947,13 @@ function compileOpenApiRevision(source, options) {
   return {
     id: revisionId,
     protocol: "openapi",
-    integrationId: options.integrationId,
+    definitionId: options.definitionId,
     contentSha256,
     source: {
       ...options.sourceUrl ? { url: options.sourceUrl } : {},
       ...options.provider ? { provider: options.provider } : {}
     },
-    title: stringValue(info.title) ?? options.integrationId,
+    title: stringValue(info.title) ?? options.definitionId,
     ...stringValue(info.description) ? { description: stringValue(info.description) } : {},
     ...stringValue(info.version) ? { version: stringValue(info.version) } : {},
     tools,
@@ -986,7 +986,7 @@ function discoverOpenApiAuth(document) {
 var OpenApiMcpServer = class {
   constructor(options) {
     this.options = options;
-    this.name = `openapi:${stableToolId(options.revision.integrationId)}`;
+    this.name = `openapi:${stableToolId(options.revision.definitionId)}`;
   }
   cacheToolsList = true;
   useStructuredContent = true;
@@ -1103,7 +1103,7 @@ async function resolveOpenApiCredential(options, binding, toolId, args, forceRef
   const credential = await options.credentialResolver.resolve({
     ...options.authority,
     protocol: "openapi",
-    integrationId: options.revision.integrationId,
+    definitionId: options.revision.definitionId,
     revisionId: options.revision.id,
     operationKey: toolId,
     destinationUrl,
@@ -1435,9 +1435,9 @@ function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 
-// src/providers.ts
-var accountIdentityFeature = (provider) => ({
-  featureKey: "account-identity",
+// src/integration-definitions.ts
+var accountIdentityFacet = (provider) => ({
+  facetKey: "account-identity",
   kind: "identity_link",
   configSchema: { type: "object", properties: {}, additionalProperties: false },
   capabilities: {
@@ -1446,8 +1446,8 @@ var accountIdentityFeature = (provider) => ({
     identity: "connected_account"
   }
 });
-var driveKnowledgeFeature = (provider) => ({
-  featureKey: "drive-content",
+var driveKnowledgeFacet = (provider) => ({
+  facetKey: "drive-content",
   kind: "knowledge_source",
   configSchema: {
     type: "object",
@@ -1501,9 +1501,9 @@ var driveKnowledgeFeature = (provider) => ({
     cursor: provider === "google-drive" ? "page_token" : "delta_link"
   }
 });
-var mailboxFeatures = (provider) => [
+var mailboxFacets = (provider) => [
   {
-    featureKey: "mail-inbox",
+    facetKey: "mail-inbox",
     kind: "inbound_trigger",
     configSchema: {
       type: "object",
@@ -1521,7 +1521,7 @@ var mailboxFeatures = (provider) => [
     }
   },
   {
-    featureKey: "mail-delivery",
+    facetKey: "mail-delivery",
     kind: "delivery_destination",
     configSchema: {
       type: "object",
@@ -1537,90 +1537,104 @@ var mailboxFeatures = (provider) => [
       delivery: "email"
     }
   },
-  accountIdentityFeature(provider === "google-gmail" ? "google" : "microsoft")
+  accountIdentityFacet(provider === "google-gmail" ? "google" : "microsoft")
 ];
 var googleDiscoveryUrl = (service, version) => `https://www.googleapis.com/discovery/v1/apis/${service}/${version}/rest`;
 var googleOAuth = (scopes) => ({
+  kind: "oauth2",
+  provider: "google",
   authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
   tokenUrl: "https://oauth2.googleapis.com/token",
   scopes: ["openid", "email", "profile", ...scopes],
   tokenPlacement: { carrier: "header", name: "Authorization", prefix: "Bearer " }
 });
-var GOOGLE_DRIVE_PRESET = {
+var GOOGLE_DRIVE_INTEGRATION_DEFINITION = {
   id: "google-drive",
   name: "Google Drive",
   summary: "Files, folders, permissions, and shared drives.",
-  family: "google",
-  sourceFormat: "google-discovery",
-  sourceUrl: googleDiscoveryUrl("drive", "v3"),
+  protocol: "openapi",
+  provider: { id: "google", domain: "www.googleapis.com" },
+  source: { kind: "google_discovery", url: googleDiscoveryUrl("drive", "v3") },
   baseUrl: "https://www.googleapis.com/drive/v3/",
-  oauth: googleOAuth(["https://www.googleapis.com/auth/drive"]),
-  healthOperation: "drive.about.get",
-  healthArgs: { query: { fields: "user" } },
-  features: [driveKnowledgeFeature("google-drive"), accountIdentityFeature("google")]
+  authentication: googleOAuth(["https://www.googleapis.com/auth/drive"]),
+  healthCheck: {
+    operationKey: "drive.about.get",
+    arguments: { query: { fields: "user" } }
+  },
+  facets: [driveKnowledgeFacet("google-drive"), accountIdentityFacet("google")]
 };
-var GOOGLE_GMAIL_PRESET = {
+var GOOGLE_GMAIL_INTEGRATION_DEFINITION = {
   id: "google-gmail",
   name: "Gmail",
   summary: "Messages, threads, labels, drafts, and sending mail.",
-  family: "google",
-  sourceFormat: "google-discovery",
-  sourceUrl: googleDiscoveryUrl("gmail", "v1"),
+  protocol: "openapi",
+  provider: { id: "google", domain: "gmail.googleapis.com" },
+  source: { kind: "google_discovery", url: googleDiscoveryUrl("gmail", "v1") },
   baseUrl: "https://gmail.googleapis.com/",
-  oauth: googleOAuth(["https://mail.google.com/"]),
-  healthOperation: "gmail.users.labels.list",
-  healthArgs: { path: { userId: "me" } },
-  features: mailboxFeatures("google-gmail")
+  authentication: googleOAuth(["https://mail.google.com/"]),
+  healthCheck: {
+    operationKey: "gmail.users.labels.list",
+    arguments: { path: { userId: "me" } }
+  },
+  facets: mailboxFacets("google-gmail")
 };
 var MICROSOFT_GRAPH_OPENAPI_URL = "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml";
 var MICROSOFT_GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0";
 var microsoftOAuth = (scopes) => ({
+  kind: "oauth2",
+  provider: "microsoft",
   authorizationUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
   tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
   scopes: ["offline_access", "User.Read", ...scopes],
   tokenPlacement: { carrier: "header", name: "Authorization", prefix: "Bearer " }
 });
-var MICROSOFT_OUTLOOK_MAIL_PRESET = {
+var MICROSOFT_OUTLOOK_MAIL_INTEGRATION_DEFINITION = {
   id: "microsoft-outlook-mail",
   name: "Outlook Mail",
   summary: "Messages, folders, attachments, settings, and sending mail.",
-  family: "microsoft",
-  sourceFormat: "openapi",
-  sourceUrl: MICROSOFT_GRAPH_OPENAPI_URL,
+  protocol: "openapi",
+  provider: { id: "microsoft", domain: "graph.microsoft.com" },
+  source: {
+    kind: "openapi",
+    url: MICROSOFT_GRAPH_OPENAPI_URL,
+    operationPathPrefixes: [
+      "/me/messages",
+      "/me/mailFolders",
+      "/me/sendMail",
+      "/me/getMailTips",
+      "/me/inferenceClassification",
+      "/me/mailboxSettings",
+      "/me/outlook"
+    ]
+  },
   baseUrl: MICROSOFT_GRAPH_BASE_URL,
-  oauth: microsoftOAuth(["Mail.ReadWrite", "Mail.Send", "MailboxSettings.ReadWrite"]),
-  pathPrefixes: [
-    "/me/messages",
-    "/me/mailFolders",
-    "/me/sendMail",
-    "/me/getMailTips",
-    "/me/inferenceClassification",
-    "/me/mailboxSettings",
-    "/me/outlook"
-  ],
-  features: mailboxFeatures("microsoft-outlook-mail")
+  authentication: microsoftOAuth(["Mail.ReadWrite", "Mail.Send", "MailboxSettings.ReadWrite"]),
+  facets: mailboxFacets("microsoft-outlook-mail")
 };
-var MICROSOFT_OUTLOOK_CALENDAR_PRESET = {
+var MICROSOFT_OUTLOOK_CALENDAR_INTEGRATION_DEFINITION = {
   id: "microsoft-outlook-calendar",
   name: "Outlook Calendar",
   summary: "Calendars, events, availability, and scheduling.",
-  family: "microsoft",
-  sourceFormat: "openapi",
-  sourceUrl: MICROSOFT_GRAPH_OPENAPI_URL,
+  protocol: "openapi",
+  provider: { id: "microsoft", domain: "graph.microsoft.com" },
+  source: {
+    kind: "openapi",
+    url: MICROSOFT_GRAPH_OPENAPI_URL,
+    operationPathPrefixes: [
+      "/me/calendar",
+      "/me/calendars",
+      "/me/calendarGroups",
+      "/me/calendarView",
+      "/me/events",
+      "/me/findMeetingTimes",
+      "/me/reminderView"
+    ]
+  },
   baseUrl: MICROSOFT_GRAPH_BASE_URL,
-  oauth: microsoftOAuth(["Calendars.ReadWrite"]),
-  pathPrefixes: [
-    "/me/calendar",
-    "/me/calendars",
-    "/me/calendarGroups",
-    "/me/calendarView",
-    "/me/events",
-    "/me/findMeetingTimes",
-    "/me/reminderView"
-  ],
-  features: [
+  authentication: microsoftOAuth(["Calendars.ReadWrite"]),
+  facets: [
     {
-      featureKey: "calendar-events",
+      facetKey: "calendar-events",
       kind: "inbound_trigger",
       configSchema: {
         type: "object",
@@ -1638,7 +1652,7 @@ var MICROSOFT_OUTLOOK_CALENDAR_PRESET = {
       }
     },
     {
-      featureKey: "calendar-delivery",
+      facetKey: "calendar-delivery",
       kind: "delivery_destination",
       configSchema: {
         type: "object",
@@ -1653,70 +1667,79 @@ var MICROSOFT_OUTLOOK_CALENDAR_PRESET = {
         delivery: "calendar_event"
       }
     },
-    accountIdentityFeature("microsoft")
+    accountIdentityFacet("microsoft")
   ]
 };
-var MICROSOFT_OUTLOOK_CONTACTS_PRESET = {
+var MICROSOFT_OUTLOOK_CONTACTS_INTEGRATION_DEFINITION = {
   id: "microsoft-outlook-contacts",
   name: "Outlook Contacts",
   summary: "Contacts, contact folders, and people suggestions.",
-  family: "microsoft",
-  sourceFormat: "openapi",
-  sourceUrl: MICROSOFT_GRAPH_OPENAPI_URL,
+  protocol: "openapi",
+  provider: { id: "microsoft", domain: "graph.microsoft.com" },
+  source: {
+    kind: "openapi",
+    url: MICROSOFT_GRAPH_OPENAPI_URL,
+    operationPathPrefixes: ["/me/contacts", "/me/contactFolders", "/me/people"]
+  },
   baseUrl: MICROSOFT_GRAPH_BASE_URL,
-  oauth: microsoftOAuth(["Contacts.ReadWrite", "People.Read.All"]),
-  pathPrefixes: ["/me/contacts", "/me/contactFolders", "/me/people"],
-  features: [accountIdentityFeature("microsoft")]
+  authentication: microsoftOAuth(["Contacts.ReadWrite", "People.Read.All"]),
+  facets: [accountIdentityFacet("microsoft")]
 };
-var MICROSOFT_ONEDRIVE_PRESET = {
+var MICROSOFT_ONEDRIVE_INTEGRATION_DEFINITION = {
   id: "microsoft-onedrive",
   name: "OneDrive",
   summary: "Drives, files, folders, sharing links, and permissions.",
-  family: "microsoft",
-  sourceFormat: "openapi",
-  sourceUrl: MICROSOFT_GRAPH_OPENAPI_URL,
+  protocol: "openapi",
+  provider: { id: "microsoft", domain: "graph.microsoft.com" },
+  source: {
+    kind: "openapi",
+    url: MICROSOFT_GRAPH_OPENAPI_URL,
+    operationPathPrefixes: ["/me/drive", "/me/drives", "/me/followedSites", "/drives", "/shares"]
+  },
   baseUrl: MICROSOFT_GRAPH_BASE_URL,
-  oauth: microsoftOAuth(["Files.ReadWrite.All", "Sites.ReadWrite.All"]),
-  pathPrefixes: ["/me/drive", "/me/drives", "/me/followedSites", "/drives", "/shares"],
-  features: [driveKnowledgeFeature("microsoft-onedrive"), accountIdentityFeature("microsoft")]
+  authentication: microsoftOAuth(["Files.ReadWrite.All", "Sites.ReadWrite.All"]),
+  facets: [driveKnowledgeFacet("microsoft-onedrive"), accountIdentityFacet("microsoft")]
 };
-var CORE_PROVIDER_PRESETS = [
-  GOOGLE_DRIVE_PRESET,
-  GOOGLE_GMAIL_PRESET,
-  MICROSOFT_OUTLOOK_MAIL_PRESET,
-  MICROSOFT_OUTLOOK_CALENDAR_PRESET,
-  MICROSOFT_OUTLOOK_CONTACTS_PRESET,
-  MICROSOFT_ONEDRIVE_PRESET
+var CORE_INTEGRATION_DEFINITIONS = [
+  GOOGLE_DRIVE_INTEGRATION_DEFINITION,
+  GOOGLE_GMAIL_INTEGRATION_DEFINITION,
+  MICROSOFT_OUTLOOK_MAIL_INTEGRATION_DEFINITION,
+  MICROSOFT_OUTLOOK_CALENDAR_INTEGRATION_DEFINITION,
+  MICROSOFT_OUTLOOK_CONTACTS_INTEGRATION_DEFINITION,
+  MICROSOFT_ONEDRIVE_INTEGRATION_DEFINITION
 ];
-function providerPresetById(id) {
-  return CORE_PROVIDER_PRESETS.find((preset) => preset.id === id);
+function integrationDefinitionById(id) {
+  return CORE_INTEGRATION_DEFINITIONS.find((definition) => definition.id === id);
 }
-function providerDomainForPreset(preset) {
-  return new URL(preset.baseUrl).hostname.toLowerCase();
+function integrationDefinitionProviderDomain(definition) {
+  return definition.provider.domain;
 }
-function integrationFeaturesForPreset(presetId) {
-  return presetId ? providerPresetById(presetId)?.features ?? [] : [];
+function integrationFacetDefinitions(definitionId) {
+  return definitionId ? integrationDefinitionById(definitionId)?.facets ?? [] : [];
 }
-function filterOpenApiDocumentForPreset(document, preset) {
-  if (!preset.pathPrefixes?.length) return document;
+function filterOpenApiDocumentForDefinition(document, definition) {
+  if (definition.source.kind !== "openapi" || !definition.source.operationPathPrefixes?.length) {
+    return document;
+  }
+  const operationPathPrefixes = definition.source.operationPathPrefixes;
   if (!isRecord3(document.paths)) {
     throw new IntegrationProtocolError("openapi_paths", "OpenAPI document has no paths object");
   }
   const paths = Object.fromEntries(
     Object.entries(document.paths).filter(
-      ([path]) => preset.pathPrefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))
+      ([path]) => operationPathPrefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`))
     )
   );
   if (Object.keys(paths).length === 0) {
     throw new IntegrationProtocolError(
-      "provider_preset_empty",
-      `${preset.name} did not match any operations in the supplied OpenAPI document`
+      "integration_definition_empty",
+      `${definition.name} did not match any operations in the supplied OpenAPI document`
     );
   }
   return {
     ...document,
     paths,
-    ...preset.baseUrl ? { servers: [{ url: preset.baseUrl }] } : {}
+    servers: [{ url: definition.baseUrl }]
   };
 }
 function googleDiscoveryToOpenApi(discovery) {
@@ -1895,11 +1918,11 @@ function isRecord3(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 export {
-  CORE_PROVIDER_PRESETS,
+  CORE_INTEGRATION_DEFINITIONS,
   DEFAULT_INTEGRATION_RESPONSE_BYTES,
   DEFAULT_INTEGRATION_TIMEOUT_MS,
-  GOOGLE_DRIVE_PRESET,
-  GOOGLE_GMAIL_PRESET,
+  GOOGLE_DRIVE_INTEGRATION_DEFINITION,
+  GOOGLE_GMAIL_INTEGRATION_DEFINITION,
   GraphqlMcpServer,
   IntegrationInvocationError,
   IntegrationProtocolError,
@@ -1907,10 +1930,10 @@ export {
   MAX_INTEGRATION_TOOLS,
   MICROSOFT_GRAPH_BASE_URL,
   MICROSOFT_GRAPH_OPENAPI_URL,
-  MICROSOFT_ONEDRIVE_PRESET,
-  MICROSOFT_OUTLOOK_CALENDAR_PRESET,
-  MICROSOFT_OUTLOOK_CONTACTS_PRESET,
-  MICROSOFT_OUTLOOK_MAIL_PRESET,
+  MICROSOFT_ONEDRIVE_INTEGRATION_DEFINITION,
+  MICROSOFT_OUTLOOK_CALENDAR_INTEGRATION_DEFINITION,
+  MICROSOFT_OUTLOOK_CONTACTS_INTEGRATION_DEFINITION,
+  MICROSOFT_OUTLOOK_MAIL_INTEGRATION_DEFINITION,
   OpenApiMcpServer,
   applyCredentialPlacements,
   assertCredentialAudience,
@@ -1927,15 +1950,15 @@ export {
   fetchGraphqlIntrospection,
   fetchIntegrationSourceDocument,
   fetchWithDeadline,
-  filterOpenApiDocumentForPreset,
+  filterOpenApiDocumentForDefinition,
   googleDiscoveryToOpenApi,
   immutableRevisionId,
-  integrationFeaturesForPreset,
+  integrationDefinitionById,
+  integrationDefinitionProviderDomain,
+  integrationFacetDefinitions,
   invokeGraphqlOperation,
   invokeOpenApiOperation,
   parseOpenApiDocument,
-  providerDomainForPreset,
-  providerPresetById,
   readIntegrationResponse,
   sha256Hex,
   stableToolId,