@oomol-lab/open-connector 1.7.0 → 1.9.0

package/src/server/api/openapi.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { jsonSchema } from "../../core/json-schema.js";
+import { triggerOperationSchema } from "../../triggers/request.js";
 import { actionInputMaxDepth, idempotencyKeyMaxBytes, idempotencyRetentionHours, } from "../actions/action-idempotency.js";
 import { oauthConnectionInput, apiKeyConnectionInput, customConnectionInput } from "./connection-input.js";
 import { policyRequestMaxBytes, policyRuleListMaxItems, policyRuleMaxBytes } from "./policy-input.js";
@@ -18,7 +19,10 @@ const errorResponseSchema = jsonSchema.object({
     description: "Standard error response.",
 });
 const actionResultMetaSchema = jsonSchema.object({
-    executionId: jsonSchema.string({ description: "Action execution identifier." }),
+    executionId: jsonSchema.string({ description: "Local action execution identifier." }),
+    remoteExecutionId: jsonSchema.string({
+        description: "SaaS execution identifier when available; distinct from the local executionId.",
+    }),
     actionId: jsonSchema.string({ description: "Executed action identifier." }),
     auditPersisted: jsonSchema.boolean({ description: "Whether the run audit record was stored." }),
 }, {
@@ -27,6 +31,9 @@ const actionResultMetaSchema = jsonSchema.object({
 });
 const actionFailureMetaSchema = jsonSchema.object({
     executionId: jsonSchema.string({ description: "Execution identifier when action execution began." }),
+    remoteExecutionId: jsonSchema.string({
+        description: "SaaS execution identifier when the remote failure supplies one.",
+    }),
     actionId: jsonSchema.string({ description: "Requested action identifier." }),
     auditPersisted: jsonSchema.boolean({ description: "Whether the run audit record was stored." }),
 }, {
@@ -40,7 +47,7 @@ const oauthClientConfigRequestSchema = jsonSchema.object({
     }),
     requestedScopes: jsonSchema.array(jsonSchema.string(), {
         minItems: 1,
-        description: "Non-empty provider-declared scope subset to request. Omit to use every provider default.",
+        description: "Complete non-empty scope list replacing the provider defaults. Each scope must be declared in scopes or optionalScopes. Omit to request every default scope and no optional scopes.",
     }),
     redirectUri: jsonSchema.string({
         description: "Absolute redirect URI registered with the provider instead of the runtime callback, such as a native app's custom scheme. Must not carry user info or a fragment; javascript, vbscript, data, file, blob, and about schemes are rejected. Omit or send an empty string to use the runtime callback.",
@@ -59,6 +66,7 @@ const oauthClientConfigRequestSchema = jsonSchema.object({
     required: ["clientId"],
     description: "User-provided OAuth app client configuration.",
 });
+const saasExecutionDescription = "SaaS connections execute remotely after local policy and input validation, using the selected account without local credentials or fallback. SaaS execution POSTs have a 300-second budget and a 64 MiB decoded JSON envelope limit. Responses retain the local executionId and add remoteExecutionId when available. Cancellation or a failed response does not guarantee that remote side effects were undone. ";
 const actionIdempotencyDescription = `Requests with the same Idempotency-Key, action, input, effective connection, and stored runtime token identity replay the original HTTP status and body of completed successes and failures during the ${idempotencyRetentionHours}-hour replay window. ` +
     "Requests that are still in progress, or whose outcome is uncertain, are not automatically dispatched again. " +
     "Duplicate suppression does not guarantee exactly-once execution by the provider.";
@@ -70,6 +78,13 @@ const actionIdParameter = {
 };
 const namedConnectionDescription = "Named connection. Same fact as MCP connectionName; HTTP alias, connectionName, and x-oo-connector-alias are equivalent. Defaults to default.";
 const namedConnectionParameters = [
+    {
+        name: "x-oo-connector-app-id",
+        in: "header",
+        required: false,
+        schema: jsonSchema.string(),
+        description: "Stable connection ID. If an alias is also supplied it must identify the same connection. Unknown IDs never select the default account.",
+    },
     {
         name: "x-oo-connector-alias",
         in: "header",
@@ -106,6 +121,9 @@ const idempotencyKeyParameter = {
 const idempotencyConflictDescription = "For idempotency, idempotency_request_in_progress means the original request is still running or its outcome is uncertain, while idempotency_key_conflict means the key was reused for a different action, input, effective connection, or stored runtime token. Other runtime conflicts may return their own error code with the same status.";
 const runtimeConnectionProperties = {
     id: jsonSchema.string({ description: "Stable local connection identifier." }),
+    providerAccountId: jsonSchema.string({
+        description: "Provider account identity from the stored credential profile.",
+    }),
     service: jsonSchema.string({ description: "Provider service identifier." }),
     status: { type: "string", enum: ["active", "disconnected"] },
     alias: jsonSchema.string({ description: namedConnectionDescription }),
@@ -262,6 +280,61 @@ export function createOpenApiDocument(providers, options = {}) {
         "/api/files/{fileId}": createTransitFilePath(),
         "/v1/actions/{actionId}": runPath,
         "/v1/proxy/{service}": createProxyPath(),
+        "/v1/providers/{service}/trigger-permissions": runtimeGetOperation("Triggers", "Read provider-native Trigger permission guidance.", {
+            data: { type: "array", items: { type: "object", additionalProperties: true } },
+            parameters: [{ name: "service", in: "path", required: true, schema: jsonSchema.string() }],
+            errorStatuses: [401, 404],
+        }),
+        "/v1/providers/{service}/triggers/{triggerId}/execute": {
+            post: {
+                tags: ["Triggers"],
+                summary: "Execute a registered Provider Trigger operation.",
+                description: "Requires independent Trigger grants. Stateful operations require a persistent runtime token and native local connection; remote state and credentials stay server-owned.",
+                parameters: [
+                    { name: "service", in: "path", required: true, schema: jsonSchema.string() },
+                    { name: "triggerId", in: "path", required: true, schema: jsonSchema.string() },
+                    ...namedConnectionParameters,
+                ],
+                requestBody: { required: true, content: { "application/json": { schema: triggerOperationSchema() } } },
+                responses: {
+                    200: jsonResponse(runtimeSuccessSchema({})),
+                    400: jsonResponse(runtimeFailureSchema()),
+                    401: jsonResponse(runtimeFailureSchema()),
+                    403: jsonResponse(runtimeFailureSchema()),
+                    404: jsonResponse(runtimeFailureSchema()),
+                    409: jsonResponse(runtimeFailureSchema()),
+                    413: jsonResponse(runtimeFailureSchema()),
+                    501: jsonResponse(runtimeFailureSchema()),
+                    503: jsonResponse(runtimeFailureSchema()),
+                },
+            },
+        },
+        "/api/trigger-subscriptions": getOperation("Triggers", "List owned subscriptions and cleanup status without secrets.", { type: "array", items: { type: "object", additionalProperties: true } }),
+        "/api/trigger-subscriptions/{id}/cancel": {
+            post: {
+                tags: ["Triggers"],
+                summary: "Cancel a subscription with retained original credentials.",
+                parameters: [{ name: "id", in: "path", required: true, schema: jsonSchema.string() }],
+                responses: {
+                    200: jsonResponse(jsonSchema.object({ ok: jsonSchema.boolean() })),
+                    404: jsonResponse(errorResponseSchema),
+                    409: jsonResponse(errorResponseSchema),
+                    503: jsonResponse(errorResponseSchema),
+                },
+            },
+        },
+        "/api/trigger-subscriptions/{id}/abandon": {
+            post: {
+                tags: ["Triggers"],
+                summary: "Explicitly abandon automatic cleanup; retain the uncleaned remote-resource record.",
+                parameters: [{ name: "id", in: "path", required: true, schema: jsonSchema.string() }],
+                responses: {
+                    200: jsonResponse(jsonSchema.object({ ok: jsonSchema.boolean() })),
+                    404: jsonResponse(errorResponseSchema),
+                    409: jsonResponse(errorResponseSchema),
+                },
+            },
+        },
         "/api/runs": createRunsPath(),
         "/api/runs/{id}": createRunDetailPath(),
         "/mcp": createMcpPath(),
@@ -287,7 +360,11 @@ export function createOpenApiDocument(providers, options = {}) {
             { name: "Access", description: "Runtime execution policy and bearer tokens for /v1 and MCP clients." },
             { name: "Files", description: "Local temporary file transit for provider actions." },
             { name: "Runs", description: "Local action execution and recent run history." },
-            { name: "Proxy", description: "Provider API proxy requests through local credentials." },
+            {
+                name: "Triggers",
+                description: "Registered provider Trigger operations and owned remote subscription cleanup.",
+            },
+            { name: "Proxy", description: "Provider API proxy requests using the selected local or SaaS connection." },
             { name: "MCP", description: "Stateless MCP POST endpoint and tool metadata." },
         ],
         paths,
@@ -419,6 +496,9 @@ export function createOpenApiDocument(providers, options = {}) {
                 }),
                 ConnectionSummary: jsonSchema.object({
                     id: jsonSchema.string({ description: "Stable local connection identifier." }),
+                    providerAccountId: jsonSchema.string({
+                        description: "Provider account identity from the stored credential profile.",
+                    }),
                     service: jsonSchema.string({ description: "Provider service identifier." }),
                     authType: jsonSchema.string({ description: "Connection authentication type." }),
                     configured: jsonSchema.boolean({ description: "Whether the provider is connected." }),
@@ -493,6 +573,7 @@ export function createOpenApiDocument(providers, options = {}) {
                     allowedActions: policyRuleArraySchema("Action allow rules applied to this stored runtime token."),
                     blockedActions: policyRuleArraySchema("Action block rules applied to this stored runtime token."),
                     allowedProxies: policyRuleArraySchema("Provider proxies explicitly granted to this token. An empty list grants no proxy access."),
+                    allowedTriggers: policyRuleArraySchema("Trigger IDs explicitly granted to this token. Omit or leave empty to deny all Trigger operations."),
                     allowedConnections: connectionIdArraySchema("Stable connection IDs granted to this stored runtime token. An empty list is unrestricted connection access. IDs are opaque values returned by the connection APIs. Virtual no_auth connections do not require grants."),
                     createdAt: jsonSchema.string({ description: "Creation timestamp." }),
                     lastUsedAt: jsonSchema.string({ description: "Last successful use timestamp." }),
@@ -504,6 +585,7 @@ export function createOpenApiDocument(providers, options = {}) {
                         "blockedActions",
                         "allowedProxies",
                         "allowedConnections",
+                        "allowedTriggers",
                         "createdAt",
                     ],
                     description: "Runtime API token summary. Plaintext tokens and token hashes are not returned.",
@@ -513,6 +595,7 @@ export function createOpenApiDocument(providers, options = {}) {
                     allowedActions: policyRuleArraySchema("Optional action allow rules for the new token."),
                     blockedActions: policyRuleArraySchema("Optional action block rules for the new token."),
                     allowedProxies: policyRuleArraySchema("Optional provider proxy grants for the new token. Omit or leave empty to deny proxy access."),
+                    allowedTriggers: policyRuleArraySchema("Trigger IDs explicitly granted to this token. Omit or leave empty to deny all Trigger operations."),
                     allowedConnections: connectionIdArraySchema("Optional stable connection IDs granted to the new token. Omit or leave empty for unrestricted connection access. A non-empty list matches exact opaque IDs returned by the connection APIs. Virtual no_auth connections do not require grants."),
                 }, {
                     required: ["name"],
@@ -522,10 +605,11 @@ export function createOpenApiDocument(providers, options = {}) {
                     allowedActions: policyRuleArraySchema("Action allow rules for this token."),
                     blockedActions: policyRuleArraySchema("Action block rules for this token."),
                     allowedProxies: policyRuleArraySchema("Provider proxies explicitly granted to this token. An empty list grants no proxy access."),
+                    allowedTriggers: policyRuleArraySchema("Trigger IDs explicitly granted to this token. Omit or leave empty to deny all Trigger operations."),
                     allowedConnections: connectionIdArraySchema("Stable connection IDs granted to this stored token. An empty list is unrestricted connection access. A non-empty list matches exact opaque IDs returned by the connection APIs. Virtual no_auth connections do not require grants."),
                 }, {
                     required: ["allowedActions", "blockedActions", "allowedProxies", "allowedConnections"],
-                    description: "Complete replacement of one stored runtime token's action, proxy, and connection permissions.",
+                    description: "Complete replacement of one stored runtime token's Action, Trigger, proxy, and connection permissions.",
                 }),
                 PolicyRules: policyRulesSchema(),
                 RuntimePolicyState: jsonSchema.object({
@@ -782,7 +866,7 @@ function createRuntimePolicyPath() {
         },
         put: {
             tags: ["Access"],
-            summary: "Replace the persisted Runtime action and proxy policy.",
+            summary: "Replace the persisted Runtime Action, Trigger, and proxy policy.",
             description: `Deployment policy remains read-only. Block rules take precedence and non-empty allowlists intersect. Policy request bodies must not exceed ${policyRequestMaxBytes} bytes.`,
             requestBody: {
                 required: true,
@@ -806,6 +890,8 @@ function policyRulesSchema() {
         allowedActions: policyRuleArraySchema("Action allow rules."),
         blockedActions: policyRuleArraySchema("Action block rules."),
         allowedProxies: policyRuleArraySchema("Proxy service allow rules."),
+        allowedTriggers: policyRuleArraySchema("Trigger allow rules. Non-empty allowlists intersect across policy layers."),
+        blockedTriggers: policyRuleArraySchema("Trigger block rules override all grants."),
         blockedProxies: policyRuleArraySchema("Proxy service block rules."),
     }, {
         required: ["allowedActions", "blockedActions", "allowedProxies", "blockedProxies"],
@@ -946,6 +1032,7 @@ function createRunPath() {
             tags: ["Runs"],
             summary: "Execute a runtime action.",
             description: "Use the action catalog to discover provider-specific input and output schemas. For a compact strongly typed OpenAPI document for one action, request /openapi.json?actionId=<actionId>. " +
+                saasExecutionDescription +
                 actionIdempotencyDescription,
             parameters: [actionIdParameter, idempotencyKeyParameter, ...namedConnectionParameters],
             requestBody: actionRunBody(jsonSchema.unknownObject("Action input matching the catalog schema. Omitted input is treated as {}."), "Generic action run creation request."),
@@ -958,7 +1045,7 @@ function createProxyPath() {
         post: {
             tags: ["Proxy"],
             summary: "Proxy one provider API request.",
-            description: "For providers with a local proxy executor, forwards a provider-relative HTTP request and applies stored provider credentials locally.",
+            description: "Executes through the selected connection. Local connections use the local provider proxy; SaaS connections use the project proxy without loading local credentials. SaaS accepts GET/POST/PUT/PATCH/DELETE, primitive query values, string non-authentication headers and JSON/text bodies only; accessGrant and unknown fields are rejected. SaaS execution has a 300-second POST budget and a 64 MiB decoded JSON envelope limit, preserves the upstream status inside data.status, and supplies distinct local executionId and remoteExecutionId in meta. Failed or cancelled calls are never automatically replayed; remote side effects may have completed.",
             parameters: [
                 {
                     name: "service",
@@ -975,7 +1062,7 @@ function createProxyPath() {
                         schema: jsonSchema.object({
                             endpoint: jsonSchema.string({ description: "Provider-relative path beginning with /." }),
                             method: jsonSchema.string({
-                                description: "HTTP method: DELETE, GET, HEAD, PATCH, POST, or PUT.",
+                                description: "HTTP method: DELETE, GET, HEAD, PATCH, POST, or PUT. SaaS connections reject HEAD.",
                             }),
                             query: {
                                 type: "object",
@@ -1005,7 +1092,7 @@ function createProxyPath() {
                         description: "Provider response headers.",
                     },
                     bodyEncoding: jsonSchema.string({
-                        description: "Present as base64 when the provider response is binary.",
+                        description: "Present as base64 when a local provider response is binary. SaaS proxy supports JSON/text responses and omits this field.",
                     }),
                     data: jsonSchema.unknown("Provider response payload."),
                 }, {
@@ -1021,6 +1108,9 @@ function createProxyPath() {
                 429: jsonResponse(runtimeFailureSchema()),
                 500: jsonResponse(runtimeFailureSchema()),
                 501: jsonResponse(runtimeFailureSchema()),
+                502: jsonResponse(runtimeFailureSchema()),
+                503: jsonResponse(runtimeFailureSchema()),
+                504: jsonResponse(runtimeFailureSchema()),
             },
         },
     };
@@ -1048,6 +1138,21 @@ function createConnectionPath() {
         delete: {
             tags: ["Connections"],
             summary: "Disconnect a provider.",
+            requestBody: {
+                required: false,
+                content: {
+                    "application/json": {
+                        schema: jsonSchema.object({
+                            connectionName: jsonSchema.string("Named connection. Defaults to default."),
+                            revoke: {
+                                type: "boolean",
+                                default: false,
+                                description: "Also request OAuth token revocation after deleting the local credential. Related connections may lose authorization depending on the provider's revocation policy.",
+                            },
+                        }),
+                    },
+                },
+            },
             responses: {
                 200: jsonResponse({
                     anyOf: [
@@ -1055,8 +1160,9 @@ function createConnectionPath() {
                         jsonSchema.object({
                             service: jsonSchema.string(),
                             configured: { const: false, type: "boolean" },
+                            revoked: jsonSchema.stringEnum("What the disconnect did about the grant at the provider: done (its revocation endpoint accepted the token), failed (it refused or could not be reached; the credential is deleted here regardless), unsupported (no revocation endpoint declared, no OAuth token held, or a SaaS connection) or skipped (the request body did not set revoke: true, the default).", ["done", "failed", "unsupported", "skipped"]),
                         }, {
-                            required: ["service", "configured"],
+                            required: ["service", "configured", "revoked"],
                             description: "Disconnected provider summary.",
                         }),
                     ],
@@ -1087,7 +1193,7 @@ function createOAuthAuthorizationPath() {
                             }),
                             requestedScopes: jsonSchema.array(jsonSchema.string(), {
                                 minItems: 1,
-                                description: "Optional non-empty provider-declared scope subset to request.",
+                                description: "Optional complete non-empty scope list replacing the provider defaults. Each scope must be declared in scopes or optionalScopes; default scopes are not added automatically.",
                             }),
                             redirectUri: jsonSchema.string({
                                 description: "Optional redirect URI registered with the connection-scoped OAuth app instead of the runtime callback. Same rules as OAuthClientConfigRequest.redirectUri.",
@@ -1132,7 +1238,7 @@ function createOAuthConfigPath() {
         put: {
             tags: ["OAuth"],
             summary: "Upsert local OAuth client configuration.",
-            description: "Open-source users provide their own OAuth app. requestedScopes may narrow the provider-declared defaults but cannot add scopes. Additional extra fields are declared by provider catalog auth metadata.",
+            description: "Open-source users provide their own OAuth app. requestedScopes replaces the default scope list with an explicit selection from the provider's scopes and optionalScopes; default scopes are not added automatically. Omit it to use the defaults without optional scopes. Undeclared scopes are refused. Additional extra fields are declared by provider catalog auth metadata.",
             requestBody: {
                 required: true,
                 content: {
@@ -1226,6 +1332,10 @@ function actionRunResponses(output) {
         413: jsonResponse(failure, "The provider response exceeded the runtime size limit, or the upstream answered 413."),
         429: jsonResponse(failure),
         500: jsonResponse(failure),
+        501: jsonResponse(failure),
+        502: jsonResponse(failure, "SaaS upstream, protocol or response size failure; execution may have completed."),
+        503: jsonResponse(failure, "SaaS project credentials or execution are unavailable."),
+        504: jsonResponse(failure, "SaaS execution timed out; execution may have completed."),
     };
 }
 function createConnectionUpsertRequestSchema() {
@@ -1250,7 +1360,7 @@ function createConcreteRunOperation(action) {
     return {
         tags: ["Runs"],
         summary: `Execute ${action.id}.`,
-        description: `${action.description} ${actionIdempotencyDescription}`,
+        description: `${action.description} ${saasExecutionDescription}${actionIdempotencyDescription}`,
         parameters: [actionIdParameter, idempotencyKeyParameter, ...namedConnectionParameters],
         requestBody: actionRunBody(action.inputSchema, `Run creation request for ${action.id}. Omitted input is treated as {}.`),
         responses: actionRunResponses(action.outputSchema),
@@ -1346,14 +1456,15 @@ function connectionManagementPaths() {
                 docsUrl: jsonSchema.optional(jsonSchema.string("Provider page where the OAuth app is registered.")),
                 steps: jsonSchema.stringArray("Ordered setup steps."),
             })),
-            scopes: jsonSchema.optional(jsonSchema.stringArray("Provider scopes the connector requests.")),
+            scopes: jsonSchema.optional(jsonSchema.stringArray("Default provider scopes when no explicit selection is made.")),
+            optionalScopes: jsonSchema.optional(jsonSchema.stringArray("Additional provider scopes for explicit selection. requestedScopes replaces the default scope list.")),
             authorizationOptions: jsonSchema.optional(jsonSchema.array(authorizationOption)),
         })),
-        oauthClient: jsonSchema.optional(jsonSchema.object("OAuth client configuration state; present when the provider supports OAuth.", {
+        oauthClient: jsonSchema.optional(jsonSchema.object("Default OAuth source configuration; present when the provider supports OAuth.", {
             configured: jsonSchema.boolean(),
-            customClientAvailable: jsonSchema.boolean("Whether connections may carry their own OAuth client."),
-            expectedRedirectUri: jsonSchema.string("Callback URL to register with the provider: the configured override, else the runtime callback."),
-            missingFields: jsonSchema.stringArray("Required client inputs absent from the stored configuration."),
+            customClientAvailable: jsonSchema.boolean("Whether connections may carry their own OAuth client; false for a SaaS default source."),
+            expectedRedirectUri: jsonSchema.string("Callback URL: the SaaS provider config callback for a SaaS source; otherwise the local override or runtime callback."),
+            missingFields: jsonSchema.stringArray("Required local client inputs absent from storage; empty for a SaaS source."),
         })),
     });
     const parameter = (name) => ({ name, in: "path", required: true, schema: { type: "string" } });
@@ -1379,8 +1490,8 @@ function connectionManagementPaths() {
         "/v1/connection-requests/{connectionRequestId}": runtimeGetOperation("Connections", "Get an OAuth authorization result.", {
             data: request,
             parameters: [parameter("connectionRequestId")],
-            errorStatuses: [401, 403, 404],
-            description: "Requires the initiating management principal. A consumed callback does not remove the result. Responses use Cache-Control: private, no-store.",
+            errorStatuses: [401, 403, 404, 409, 429, 502, 503, 504],
+            description: "Requires the initiating management principal. An explicit valid administrator Bearer token advances SaaS authorization; cookie-only and unauthenticated local GET requests only read stored results. Console uses same-origin POST /api/oauth/connection-requests/{id}/sync with X-OpenConnector-Request: sync. A consumed callback does not remove the result. Responses use Cache-Control: private, no-store.",
         }),
     };
     for (const reconnect of [false, true]) {
@@ -1407,6 +1518,10 @@ function connectionManagementPaths() {
                         403: jsonResponse(runtimeFailureSchema()),
                         404: jsonResponse(runtimeFailureSchema()),
                         409: jsonResponse(runtimeFailureSchema()),
+                        429: jsonResponse(runtimeFailureSchema()),
+                        502: jsonResponse(runtimeFailureSchema()),
+                        503: jsonResponse(runtimeFailureSchema()),
+                        504: jsonResponse(runtimeFailureSchema()),
                     },
                 },
             };

package/src/server/api/pattern-example.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Conservative pattern sampler for action-guide examples.
+ *
+ * A JSON Schema `pattern` is a validation contract; an example that does not
+ * match it is rejected by the runtime. This module turns the common shapes
+ * (digit runs, fixed-width identifiers, dates, times, literal prefixes, and
+ * alternations of them) into a short literal that matches, and returns
+ * `undefined` for constructs it cannot sample safely (lookbehind,
+ * backreferences, Unicode property escapes) so the caller can fall back.
+ */
+/**
+ * Sample a short literal that matches `pattern`, or `undefined` when the
+ * pattern uses constructs this sampler does not support. Lookaheads are checked against the result, without searching for a match.
+ *
+ * `minLength` grows unbounded quantifiers (`+`, `*`, `{n,}`) until the sample
+ * reaches the schema's minimum, when the pattern allows it. A `minLength`
+ * beyond the sample bound returns `undefined` so the caller can fall back to a
+ * placeholder that still honors it.
+ */
+export declare function samplePattern(pattern: string, options?: {
+    minLength?: number;
+}): string | undefined;