@opengeni/capabilities 0.1.1 → 0.3.0-canary.0

package/dist/integration-definitions.d.ts

@@ -0,0 +1,57 @@
+export interface IntegrationDefinitionOAuth2Authentication {
+    readonly kind: "oauth2";
+    readonly provider: "google" | "microsoft";
+    readonly authorizationUrl: string;
+    readonly tokenUrl: string;
+    readonly scopes: readonly string[];
+    readonly tokenPlacement: {
+        readonly carrier: "header";
+        readonly name: "Authorization";
+        readonly prefix: "Bearer ";
+    };
+}
+export type IntegrationDefinitionSource = Readonly<{
+    kind: "google_discovery";
+    url: string;
+}> | Readonly<{
+    kind: "openapi";
+    url: string;
+    operationPathPrefixes?: readonly string[];
+}>;
+export interface IntegrationDefinition {
+    readonly id: string;
+    readonly name: string;
+    readonly summary: string;
+    readonly protocol: "openapi";
+    readonly provider: Readonly<{
+        id: "google" | "microsoft";
+        domain: string;
+    }>;
+    readonly source: IntegrationDefinitionSource;
+    readonly baseUrl: string;
+    readonly authentication: IntegrationDefinitionOAuth2Authentication;
+    readonly healthCheck?: Readonly<{
+        operationKey: string;
+        arguments: Readonly<Record<string, unknown>>;
+    }>;
+    readonly facets: readonly IntegrationFacetDefinition[];
+}
+export interface IntegrationFacetDefinition {
+    readonly facetKey: string;
+    readonly kind: "knowledge_source" | "inbound_trigger" | "delivery_destination" | "identity_link";
+    readonly configSchema: Readonly<Record<string, unknown>>;
+    readonly capabilities: Readonly<Record<string, unknown>>;
+}
+export declare const GOOGLE_DRIVE_INTEGRATION_DEFINITION: IntegrationDefinition;
+export declare const MICROSOFT_GRAPH_OPENAPI_URL = "https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml";
+export declare const MICROSOFT_GRAPH_BASE_URL = "https://graph.microsoft.com/v1.0";
+export declare const MICROSOFT_OUTLOOK_MAIL_INTEGRATION_DEFINITION: IntegrationDefinition;
+export declare const MICROSOFT_OUTLOOK_CALENDAR_INTEGRATION_DEFINITION: IntegrationDefinition;
+export declare const MICROSOFT_OUTLOOK_CONTACTS_INTEGRATION_DEFINITION: IntegrationDefinition;
+export declare const MICROSOFT_ONEDRIVE_INTEGRATION_DEFINITION: IntegrationDefinition;
+export declare const CORE_INTEGRATION_DEFINITIONS: readonly IntegrationDefinition[];
+export declare function integrationDefinitionById(id: string): IntegrationDefinition | undefined;
+export declare function integrationDefinitionProviderDomain(definition: IntegrationDefinition): string;
+export declare function integrationFacetDefinitions(definitionId: string | null | undefined): readonly IntegrationFacetDefinition[];
+export declare function filterOpenApiDocumentForDefinition(document: Record<string, unknown>, definition: IntegrationDefinition): Record<string, unknown>;
+export declare function googleDiscoveryToOpenApi(discovery: unknown): Record<string, unknown>;

package/dist/integration-presentations.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reviewed consent copy for the core API integration definitions.
+ *
+ * Presentation only: nothing here grants a scope, selects a connection, or
+ * replaces server-side authorization. The copy used to live hardcoded in the
+ * web bundle (`REVIEWED_INTEGRATION_EXPERIENCES`); it is served with the
+ * definition now so polishing a consent screen is a data change, not a
+ * frontend release. The web keeps its generic fallback for any definition or
+ * field missing here. Gmail's reviewed presentation lives on its catalog row
+ * instead (`data/catalog/curated.json`): Gmail is a Connector, not one of
+ * these API integration definitions.
+ *
+ * MCP connectors carry the same shape on their curated catalog row
+ * (`presentation` in `data/catalog/curated.json` -> importer ->
+ * `capability_catalog_items.metadata.presentation`).
+ */
+export type IntegrationPresentationIcon = "calendar" | "cloud" | "contacts" | "files" | "mail";
+export type IntegrationPresentationCopy = {
+    readonly providerName?: string;
+    readonly icon?: IntegrationPresentationIcon;
+    readonly introduction?: string;
+    readonly capabilities?: readonly {
+        readonly title: string;
+        readonly description: string;
+    }[];
+    readonly permissionSummary?: string;
+    readonly scopeLabels?: Readonly<Record<string, {
+        readonly label: string;
+        readonly description: string;
+    }>>;
+};
+export declare const INTEGRATION_DEFINITION_PRESENTATIONS: Readonly<Record<string, IntegrationPresentationCopy>>;

package/dist/mcp-bridge.d.ts

@@ -0,0 +1,41 @@
+import type { MCPServer } from "@openai/agents";
+export declare const LOCAL_MCP_BRIDGE_CONTRACT_VERSION: 1;
+export type LocalMcpBridgeAuthority = "connection" | "host" | "none";
+export type LocalMcpBridgeToolSurface = "static_reviewed";
+export type LocalMcpBridgeDestination = Readonly<{
+    origin: string;
+    pathPrefix: string;
+}>;
+/**
+ * Secret-free description of an in-process provider-to-MCP adapter.
+ *
+ * This is observability and registration metadata, not authorization. The
+ * adapter must still revalidate its named authority before each physical
+ * provider request and keep credentials outside tool results and schemas.
+ */
+export type LocalMcpBridgeDescriptor = Readonly<{
+    contractVersion: typeof LOCAL_MCP_BRIDGE_CONTRACT_VERSION;
+    adapterId: string;
+    providerId: string;
+    catalogIdentity: string;
+    transport: "in_process";
+    authority: LocalMcpBridgeAuthority;
+    toolSurface: LocalMcpBridgeToolSurface;
+    mutationReplay: "safe_reads_only";
+    destinations: readonly LocalMcpBridgeDestination[];
+}>;
+export interface LocalMcpBridgeServer extends MCPServer {
+    readonly bridge: LocalMcpBridgeDescriptor;
+}
+export interface LocalMcpBridgeAdapter<TConfig, TContext> {
+    readonly adapterId: string;
+    matches(config: TConfig): boolean;
+    create(config: TConfig, context: TContext): LocalMcpBridgeServer;
+}
+export declare function defineLocalMcpBridgeDescriptor(input: Omit<LocalMcpBridgeDescriptor, "contractVersion" | "transport">): LocalMcpBridgeDescriptor;
+export declare function isLocalMcpBridgeServer(server: MCPServer): server is LocalMcpBridgeServer;
+/**
+ * Select exactly one adapter for a runtime catalog row. Ambiguous matches fail
+ * closed so adding a bridge cannot silently replace another provider route.
+ */
+export declare function createLocalMcpBridgeFromAdapters<TConfig, TContext>(adapters: readonly LocalMcpBridgeAdapter<TConfig, TContext>[], config: TConfig, context: TContext): LocalMcpBridgeServer | null;

package/dist/openapi.d.ts

@@ -22,7 +22,7 @@ export interface OpenApiOperationBinding {
 }
 export type OpenApiRevision = IntegrationRevision<OpenApiOperationBinding, "openapi">;
 export interface CompileOpenApiOptions {
-    readonly integrationId: string;
+    readonly definitionId: string;
     readonly sourceUrl?: string;
     readonly baseUrl?: string;
     readonly provider?: string;

package/dist/types.d.ts

@@ -30,6 +30,8 @@ export interface IntegrationCredentialAudience {
 export interface ResolvedIntegrationCredential {
     readonly audience: IntegrationCredentialAudience;
     readonly placements: readonly IntegrationCredentialPlacement[];
+    /** Exact accepted-attempt fence invoked immediately before one HTTP request. */
+    readonly authorizeProviderRequest?: () => Promise<boolean>;
     readonly expiresAt?: string;
     readonly scope?: readonly string[];
 }
@@ -45,7 +47,7 @@ export interface IntegrationInvocationAuthority {
 }
 export interface ResolveIntegrationCredentialRequest extends IntegrationInvocationAuthority {
     readonly protocol: Exclude<IntegrationProtocol, "mcp">;
-    readonly integrationId: string;
+    readonly definitionId: string;
     readonly revisionId: string;
     readonly operationKey: string;
     readonly destinationUrl: string;
@@ -71,7 +73,7 @@ export type IntegrationRevisionSource = {
 export interface IntegrationRevision<TBinding = unknown, TProtocol extends Exclude<IntegrationProtocol, "mcp"> = Exclude<IntegrationProtocol, "mcp">> {
     readonly id: string;
     readonly protocol: TProtocol;
-    readonly integrationId: string;
+    readonly definitionId: string;
     readonly contentSha256: string;
     readonly source: IntegrationRevisionSource;
     readonly title: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/capabilities",
-  "version": "0.1.1",
+  "version": "0.3.0-canary.0",
   "description": "Protocol-neutral capability integration compilers and local MCP adapters for OpenGeni.",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@openai/agents": "0.14.3",
-    "@opengeni/network": "^0.2.2",
+    "@opengeni/network": "^0.2.2-canary.0",
     "graphql": "^16.12.0",
     "js-yaml": "4.1.1"
   },

package/src/graphql.ts

@@ -50,7 +50,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;
@@ -170,13 +170,13 @@ export function compileGraphqlRevision(
   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,
   };
@@ -243,7 +243,7 @@ export class GraphqlMcpServer implements MCPServer {
   readonly name: string;
 
   constructor(private readonly options: GraphqlServerOptions) {
-    this.name = `graphql:${stableToolId(options.revision.integrationId)}`;
+    this.name = `graphql:${stableToolId(options.revision.definitionId)}`;
   }
 
   async connect(): Promise<void> {}
@@ -330,7 +330,7 @@ export async function invokeGraphqlOperation(
   const request = { query, variables, operationName: binding.operationName };
   const firstCredential = await resolveGraphqlCredential(
     options,
-    options.revision.integrationId,
+    options.revision.definitionId,
     options.revision.id,
     toolId,
     false,
@@ -339,7 +339,7 @@ export async function invokeGraphqlOperation(
   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,
@@ -391,7 +391,7 @@ export async function invokeGraphqlOperation(
 
 async function resolveGraphqlCredential(
   options: Omit<GraphqlServerOptions, "revision"> | GraphqlServerOptions,
-  integrationId: string,
+  definitionId: string,
   revisionId: string,
   operationKey: string,
   forceRefresh: boolean,
@@ -400,7 +400,7 @@ async function resolveGraphqlCredential(
   const credential = await options.credentialResolver.resolve({
     ...options.authority,
     protocol: "graphql",
-    integrationId,
+    definitionId,
     revisionId,
     operationKey,
     destinationUrl: graphqlEndpoint(options).toString(),
@@ -428,6 +428,22 @@ async function sendGraphqlRequest(
   headers.set("accept", "application/json");
   headers.set("content-type", "application/json");
   if (credential) applyCredentialPlacements(endpoint, headers, credential);
+  if (credential?.authorizeProviderRequest) {
+    let authorized = false;
+    try {
+      authorized = await credential.authorizeProviderRequest();
+    } catch {
+      authorized = false;
+    }
+    if (!authorized) {
+      throw new IntegrationInvocationError(
+        "authorization_rejected",
+        "The connected account is no longer authorized for this operation",
+        "not_started",
+        false,
+      );
+    }
+  }
   return await fetchWithDeadline(
     options.transport,
     endpoint,

package/src/index.ts

@@ -2,7 +2,9 @@ export * from "./auth";
 export * from "./graphql";
 export * from "./http";
 export * from "./mcp-manifest";
+export * from "./mcp-bridge";
 export * from "./openapi";
-export * from "./providers";
+export * from "./integration-definitions";
+export * from "./integration-presentations";
 export * from "./revision";
 export * from "./types";