@slates/provider 1.0.0-rc.26 → 1.0.0-rc.28

package/dist/index.cjs

@@ -86,6 +86,7 @@ __export(index_exports, {
   isApiErrorRecord: () => isApiErrorRecord,
   isAxiosErrorLike: () => isAxiosErrorLike,
   isServiceErrorData: () => isServiceErrorData,
+  isUrlEmbeddedCredential: () => isUrlEmbeddedCredential,
   mapServiceErrorCode: () => mapServiceErrorCode,
   mapServiceErrorToSlateErrorInput: () => mapServiceErrorToSlateErrorInput,
   mergeScopes: () => mergeScopes,
@@ -406,7 +407,7 @@ var normalizeRetryable = (code, retryable) => {
 };
 var getDefaultMessage = (code, message) => {
   if (message?.trim()) return message;
-  return DEFAULT_MESSAGES[code] ?? DEFAULT_MESSAGES[DEFAULT_CODE];
+  return DEFAULT_MESSAGES[code] ?? DEFAULT_MESSAGES[DEFAULT_CODE] ?? "An unexpected internal error occurred.";
 };
 var cleanRecord = (value) => {
   if (!value) return void 0;
@@ -1074,10 +1075,14 @@ var AuthConfigSecretRedactor = class {
       return this.secretToPlaceholder.get(stringValue) ?? stringValue;
     });
   }
-  redactEmbedded(value) {
-    if (this.secretToPlaceholder.size === 0) return value;
+  /** `embeddable` limits which secrets are also replaced inside longer strings. */
+  redactEmbedded(value, embeddable = () => true) {
+    let secrets = [...this.secretToPlaceholder.entries()].filter(
+      ([secret, placeholder]) => embeddable(secret, placeholder.slice(AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX.length))
+    ).map(([secret]) => secret);
+    if (secrets.length === 0) return this.redact(value);
     let pattern = new RegExp(
-      [...this.secretToPlaceholder.keys()].sort((a, b) => b.length - a.length).map((secret) => secret.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"),
+      secrets.sort((a, b) => b.length - a.length).map((secret) => secret.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"),
       "g"
     );
     return this.transform(value, (stringValue) => {
@@ -1130,18 +1135,21 @@ var AuthConfigSecretRedactor = class {
     return typeof value === "object" && value !== null && !Array.isArray(value);
   }
 };
+var URL_CREDENTIAL_KEY = /^(?:.*[-_])?(?:token|secret|password|api[-_]?key)$/i;
+var isUrlEmbeddedCredential = (secret, path) => secret.length >= 8 && URL_CREDENTIAL_KEY.test(path.split(".").pop() ?? "");
 var redactUrlAttachmentSecrets = (attachments, authConfig) => {
   if (!authConfig || !attachments) return attachments;
   let redactor = new AuthConfigSecretRedactor(authConfig);
   return attachments.map((attachment) => {
     if (attachment.content.type !== "url") return attachment;
-    if (!attachment.content.headers && !attachment.content.query) return attachment;
+    let { url, headers, query } = attachment.content;
     return {
       ...attachment,
       content: {
         ...attachment.content,
-        headers: attachment.content.headers ? redactor.redactEmbedded(attachment.content.headers) : void 0,
-        query: attachment.content.query ? redactor.redactEmbedded(attachment.content.query) : void 0
+        url: redactor.redactEmbedded(url, isUrlEmbeddedCredential),
+        ...headers ? { headers: redactor.redactEmbedded(headers) } : {},
+        ...query ? { query: redactor.redactEmbedded(query) } : {}
       }
     };
   });
@@ -1191,6 +1199,7 @@ var getFileUrlTool = (spec2, handleGetFileUrl) => tool(spec2, {
   return {
     output: {
       ...output,
+      url: redactor.redactEmbedded(output.url, isUrlEmbeddedCredential),
       ...output.headers ? { headers: redactor.redactEmbedded(output.headers) } : {},
       ...output.query ? { query: redactor.redactEmbedded(output.query) } : {}
     },
@@ -1288,6 +1297,9 @@ var SlateTriggerGroup = class _SlateTriggerGroup {
   get webhook() {
     return this._params.webhook;
   }
+  get gateway() {
+    return this._params.gateway;
+  }
   get routingMatchers() {
     return this._params.routingMatchers;
   }
@@ -1304,6 +1316,7 @@ var SlateTriggerGroupBuilder = class {
   #source = null;
   #polling = null;
   #webhook = null;
+  #gateway = null;
   #routingMatchers = null;
   polling(props) {
     if (this.#source) {
@@ -1333,6 +1346,15 @@ var SlateTriggerGroupBuilder = class {
     };
     return this;
   }
+  /** Receive events over a platform-managed persistent connection (e.g. a WebSocket gateway). */
+  gateway(props) {
+    if (this.#source) {
+      throw new SlateDeclarationError("Trigger group invocation is already defined");
+    }
+    this.#source = "gateway";
+    this.#gateway = { connect: props.connect, receive: props.receive };
+    return this;
+  }
   routingMatchers(handler) {
     this.#routingMatchers = handler;
     return this;
@@ -1340,7 +1362,7 @@ var SlateTriggerGroupBuilder = class {
   build() {
     if (!this.#source) {
       throw new SlateDeclarationError(
-        "Trigger group invocation (polling or webhook) is not defined"
+        "Trigger group invocation (polling, webhook, or gateway) is not defined"
       );
     }
     if (!this.#routingMatchers) {
@@ -1351,6 +1373,7 @@ var SlateTriggerGroupBuilder = class {
       source: this.#source,
       polling: this.#polling ?? void 0,
       webhook: this.#webhook ?? void 0,
+      gateway: this.#gateway ?? void 0,
       routingMatchers: this.#routingMatchers
     });
   }
@@ -2140,6 +2163,7 @@ var redactHashFragment = (hash, redactor) => {
   );
   return redacted ? `#${redacted}` : "";
 };
+var isEmbeddedPathSecret = (secret, path) => secret.length >= 8 && isSecretKeyName(path.split(".").pop() ?? "");
 var sanitizeUrl = (value, redactor) => {
   if (!value) return value;
   try {
@@ -2148,6 +2172,7 @@ var sanitizeUrl = (value, redactor) => {
       url.username = "";
       url.password = "";
     }
+    if (redactor) url.pathname = redactor.redactEmbedded(url.pathname, isEmbeddedPathSecret);
     for (let key of Array.from(url.searchParams.keys())) {
       if (isUrlFormSecretKeyName(key)) {
         url.searchParams.set(key, REDACTED_VALUE);
@@ -2160,7 +2185,7 @@ var sanitizeUrl = (value, redactor) => {
     url.hash = redactHashFragment(url.hash, redactor);
     return decodeRedactedMarker(url.toString());
   } catch {
-    let text = redactor ? redactor.redact(value) : value;
+    let text = redactor ? redactor.redactEmbedded(value, isEmbeddedPathSecret) : value;
     return text.replace(
       /([?&]([^=&#]+)=)([^&#]+)/g,
       (_match, prefix, key, rawValue) => isUrlFormSecretKeyName(key) ? `${prefix}${REDACTED_VALUE}` : `${prefix}${rawValue}`
@@ -3012,6 +3037,7 @@ var skipWebhook = (reason, response) => ({
   isApiErrorRecord,
   isAxiosErrorLike,
   isServiceErrorData,
+  isUrlEmbeddedCredential,
   mapServiceErrorCode,
   mapServiceErrorToSlateErrorInput,
   mergeScopes,

package/dist/index.d.cts

@@ -50,15 +50,17 @@ declare class AuthConfigSecretRedactor {
     private readonly secretToPlaceholder;
     constructor(authConfig: Record<string, unknown> | undefined);
     redact<T>(value: T): T;
-    redactEmbedded<T>(value: T): T;
+    /** `embeddable` limits which secrets are also replaced inside longer strings. */
+    redactEmbedded<T>(value: T, embeddable?: (secret: string, path: string) => boolean): T;
     private buildSecretMap;
     private transform;
     private isPlainObject;
 }
+declare let isUrlEmbeddedCredential: (secret: string, path: string) => boolean;
 /**
  * Applied to every finalized attachment list right before it's sent over
  * `slates/action.tool.invoke` (see @slates/provider-handler). Only `type: 'url'` attachments
- * carry headers/query -- content/upload_reference attachments pass through untouched.
+ * carry credentials -- content/upload_reference attachments pass through untouched.
  */
 declare let redactUrlAttachmentSecrets: (attachments: SlateAttachment[] | undefined, authConfig: Record<string, unknown> | undefined) => SlateAttachment[] | undefined;
 
@@ -150,6 +152,7 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
         scope: string;
     }[];
     adapters?: string[];
+    syncTokensAcrossConnections?: boolean;
     docs?: SlateAuthDocsReference[];
     inputSchema?: z.ZodType<InputType>;
     onInputChanged?: (params: {
@@ -522,6 +525,41 @@ type SlateTriggerGroupPollHandler<ConfigType extends {}, AuthType extends {}> =
     }[];
     updatedState?: any;
 }>;
+interface SlateGatewayEvent {
+    payload: any;
+    idempotencyKey?: string;
+}
+type SlateTriggerGroupGatewayConnectHandler<ConfigType extends {}, AuthType extends {}> = (context: SlateContext<ConfigType, AuthType, {
+    state: any | null;
+}>) => Promise<{
+    url: string;
+    state?: any;
+}>;
+/** `closed` is set, with no frames, when the socket closed unexpectedly. */
+type SlateTriggerGroupGatewayReceiveHandler<ConfigType extends {}, AuthType extends {}> = (context: SlateContext<ConfigType, AuthType, {
+    state: any | null;
+    frames: string[];
+    closed?: {
+        code: number;
+        reason: string;
+    } | null;
+}>) => Promise<{
+    state?: any;
+    send?: string[];
+    events?: SlateGatewayEvent[];
+    /** With `expectsAck`, the hub reconnects when no `heartbeatAcked` arrives before the next beat. */
+    heartbeat?: {
+        intervalMs: number;
+        frame: string;
+        expectsAck?: boolean;
+    } | null;
+    /** Set when `frames` included the provider's heartbeat acknowledgement. */
+    heartbeatAcked?: boolean;
+    close?: {
+        reconnect: boolean;
+        reason?: string;
+    } | null;
+}>;
 type SlateWebhookTargetListHandler<ConfigType extends {}, AuthType extends {}> = (context: SlateContext<ConfigType, AuthType, {
     pageToken: any | null;
 }>) => Promise<{
@@ -573,6 +611,10 @@ interface SlateTriggerGroupPollingParameters<ConfigType extends {}, AuthType ext
     intervalSeconds: number;
     pollEvents: SlateTriggerGroupPollHandler<ConfigType, AuthType>;
 }
+interface SlateTriggerGroupGatewayParameters<ConfigType extends {}, AuthType extends {}> {
+    connect: SlateTriggerGroupGatewayConnectHandler<ConfigType, AuthType>;
+    receive: SlateTriggerGroupGatewayReceiveHandler<ConfigType, AuthType>;
+}
 interface SlateTriggerGroupWebhookAutoRegistrationParameters<ConfigType extends {}, AuthType extends {}> {
     webhookTargetList: SlateWebhookTargetListHandler<ConfigType, AuthType>;
     webhookRegister: SlateWebhookRegisterHandler<ConfigType, AuthType>;
@@ -597,9 +639,10 @@ interface SlateTriggerGroupCreateParameters<InputType extends {} = Record<string
     eventSchema?: z$1.ZodType<InputType>;
 }
 interface SlateTriggerGroupParameters<ConfigType extends {}, AuthType extends {}, InputType extends {} = Record<string, unknown>> extends SlateTriggerGroupCreateParameters<InputType> {
-    source: 'polling' | 'webhook';
+    source: 'polling' | 'webhook' | 'gateway';
     polling?: SlateTriggerGroupPollingParameters<ConfigType, AuthType>;
     webhook?: SlateTriggerGroupWebhookParameters<ConfigType, AuthType>;
+    gateway?: SlateTriggerGroupGatewayParameters<ConfigType, AuthType>;
     routingMatchers: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>;
 }
 declare class SlateTriggerGroup<ConfigType extends {}, AuthType extends {}, InputType extends {} = Record<string, unknown>> {
@@ -613,9 +656,10 @@ declare class SlateTriggerGroup<ConfigType extends {}, AuthType extends {}, Inpu
     get description(): string | undefined;
     get metadata(): Record<string, any> | undefined;
     get eventSchema(): z$1.ZodType<InputType, unknown, z$1.core.$ZodTypeInternals<InputType, unknown>>;
-    get source(): "polling" | "webhook";
+    get source(): "polling" | "webhook" | "gateway";
     get polling(): SlateTriggerGroupPollingParameters<ConfigType, AuthType> | undefined;
     get webhook(): SlateTriggerGroupWebhookParameters<ConfigType, AuthType> | undefined;
+    get gateway(): SlateTriggerGroupGatewayParameters<ConfigType, AuthType> | undefined;
     get routingMatchers(): SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>;
 }
 declare class SlateTriggerGroupBuilder<ConfigType extends {}, AuthType extends {}, InputType extends {} = Record<string, unknown>> {
@@ -633,6 +677,8 @@ declare class SlateTriggerGroupBuilder<ConfigType extends {}, AuthType extends {
         manualRegistration?: SlateTriggerGroupWebhookManualRegistrationParameters<UserConfigSchema, FullConfigSchema>;
         process: SlateWebhookProcessHandler;
     }): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType>;
+    /** Receive events over a platform-managed persistent connection (e.g. a WebSocket gateway). */
+    gateway(props: SlateTriggerGroupGatewayParameters<ConfigType, AuthType>): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType>;
     routingMatchers(handler: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType>;
     build(): SlateTriggerGroup<ConfigType, AuthType, InputType>;
 }
@@ -1093,4 +1139,4 @@ declare let skipWebhook: (reason: string, response?: Response | SlateWebhookHttp
     response: Response | SlateWebhookHttpResponseInit;
 };
 
-export { AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX, type ApiErrorBuildHelpers, type ApiErrorDetailOptions, type ApiErrorResponse, type ApiErrorStatus, type ApiServiceError, AuthConfigSecretRedactor, type BuildApiServiceErrorOptions, type CreateHmacSignatureOptions, GET_FILE_URL_TOOL_ID, type GetFileUrlHandler, type GetFileUrlToolInput, type GetFileUrlToolOutput, type NormalizeOAuthTokenResponseOptions, type OAuthExpiresAtOptions, type OAuthRefreshTokenFallbackMode, type OAuthTokenResponse, Slate, SlateAction, SlateActionBuilder, type SlateActionCreateParameters, type SlateActionDocsReference, type SlateActionParameters, type SlateActionParametersAny, type SlateActionParametersTool, type SlateActionParametersTrigger, type SlateActionScopeClause, type SlateActionScopeClauseInput, type SlateActionScopeValue, type SlateActionScopes, type SlateActionScopesInput, type SlateActionType, SlateAdapter, type SlateAdapterCapability, SlateAdapterSpec, type SlateAdapterSpecParameters, type SlateAddAttachmentContent, type SlateAddAttachmentInput, type SlateAttachment, type SlateAttachmentInlineContent, type SlateAttachmentUploadReferenceContent, type SlateAttachmentUrlContent, SlateAuth, type SlateAuthDocsReference, type SlateAuthType, type SlateAuthWithCustomData, type SlateAuthWithNone, type SlateAuthWithOauth, type SlateAuthWithServiceAccount, type SlateAuthWithToken, type SlateAuthenticatedAxiosDefaults, type SlateAxiosDefaults, type SlateAxiosErrorAdapter, type SlateAxiosErrorOptions, SlateConfig, type SlateConfigDocsReference, SlateContext, SlateDeclarationError, SlateDefaultPollingIntervalSeconds, type SlateDirectUploadInput, type SlateDocsReference, SlateError, type SlateErrorInput, type SlateErrorIssue, type SlateErrorKind, type SlateErrorProviderInfo, type SlateErrorResponse, type SlateErrorUpstreamInfo, type SlateLiveInvocationInfo, type SlateLogEntry, type SlateLogFields, type SlateLogListener, type SlateLogMessageInput, type SlateLogType, SlateLogger, type SlateProviderDocsReference, SlatePublicContext, SlatePublicTool, type SlatePublicToolInvocationHandler, type SlatePublicToolParameters, type SlateServiceErrorData, SlateSpecification, type SlateSpecificationCreateParameters, type SlateSpecificationParameters, SlateTool, type SlateToolInvocationHandler, type SlateToolParameters, SlateTrigger, SlateTriggerGroup, SlateTriggerGroupBuilder, type SlateTriggerGroupCreateParameters, type SlateTriggerGroupParameters, type SlateTriggerGroupPollHandler, type SlateTriggerGroupPollingParameters, type SlateTriggerGroupRoutingMatchersHandler, type SlateTriggerGroupWebhookAutoRegistrationParameters, type SlateTriggerGroupWebhookManualRegistrationParameters, type SlateTriggerGroupWebhookParameters, type SlateTriggerMappingHandler, type SlateTriggerMatchesHandler, type SlateTriggerParameters, type SlateTriggerRoutingMatcher, type SlateTypedDocsReference, type SlateWebhookHttpResponseInit, type SlateWebhookManualFinishHandler, type SlateWebhookManualSetupHandler, type SlateWebhookProcessHandler, type SlateWebhookRegisterHandler, type SlateWebhookSkipped, type SlateWebhookTarget, type SlateWebhookTargetListHandler, type SlateWebhookTargetOwnership, type SlateWebhookUnregisterHandler, type VerifyHmacSignatureOptions, adapterSpec, allOf, anyOf, auth, axios, buildApiServiceError, collectApiErrorDetails, config, createApiServiceError, createAuthenticatedAxios, createAxios, createBase64Attachment, createHmacSignature, createSlateError, createTextAttachment, createUrlAttachment, extractApiErrorMessage, getApiErrorResponse, getApiErrorStatus, getBase64ByteLength, getCurrentContext, getFileUrlTool, getFileUrlToolInputSchema, getFileUrlToolOutputSchema, getGraphWebhookValidationResponse, getMetaWebhookVerificationResponse, getOAuthExpiresAtFromExpiresIn, getResponseHeaderValue, getServiceErrorData, graphWebhookHttp, inferSlateErrorFromAxios, isApiErrorRecord, isAxiosErrorLike, isServiceErrorData, mapServiceErrorCode, mapServiceErrorToSlateErrorInput, mergeScopes, metaWebhookHttp, normalizeOAuthTokenResponse, pickDefined, publicTool, redactUrlAttachmentSecrets, requestAxios, requestAxiosData, runWithContext, scopeClause, setIfDefined, skipWebhook, spec, statusLabelForApiError, tool, trigger, triggerGroup, uploadAttachmentDirect, validateScopes, verifyHmacSignature };
+export { AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX, type ApiErrorBuildHelpers, type ApiErrorDetailOptions, type ApiErrorResponse, type ApiErrorStatus, type ApiServiceError, AuthConfigSecretRedactor, type BuildApiServiceErrorOptions, type CreateHmacSignatureOptions, GET_FILE_URL_TOOL_ID, type GetFileUrlHandler, type GetFileUrlToolInput, type GetFileUrlToolOutput, type NormalizeOAuthTokenResponseOptions, type OAuthExpiresAtOptions, type OAuthRefreshTokenFallbackMode, type OAuthTokenResponse, Slate, SlateAction, SlateActionBuilder, type SlateActionCreateParameters, type SlateActionDocsReference, type SlateActionParameters, type SlateActionParametersAny, type SlateActionParametersTool, type SlateActionParametersTrigger, type SlateActionScopeClause, type SlateActionScopeClauseInput, type SlateActionScopeValue, type SlateActionScopes, type SlateActionScopesInput, type SlateActionType, SlateAdapter, type SlateAdapterCapability, SlateAdapterSpec, type SlateAdapterSpecParameters, type SlateAddAttachmentContent, type SlateAddAttachmentInput, type SlateAttachment, type SlateAttachmentInlineContent, type SlateAttachmentUploadReferenceContent, type SlateAttachmentUrlContent, SlateAuth, type SlateAuthDocsReference, type SlateAuthType, type SlateAuthWithCustomData, type SlateAuthWithNone, type SlateAuthWithOauth, type SlateAuthWithServiceAccount, type SlateAuthWithToken, type SlateAuthenticatedAxiosDefaults, type SlateAxiosDefaults, type SlateAxiosErrorAdapter, type SlateAxiosErrorOptions, SlateConfig, type SlateConfigDocsReference, SlateContext, SlateDeclarationError, SlateDefaultPollingIntervalSeconds, type SlateDirectUploadInput, type SlateDocsReference, SlateError, type SlateErrorInput, type SlateErrorIssue, type SlateErrorKind, type SlateErrorProviderInfo, type SlateErrorResponse, type SlateErrorUpstreamInfo, type SlateGatewayEvent, type SlateLiveInvocationInfo, type SlateLogEntry, type SlateLogFields, type SlateLogListener, type SlateLogMessageInput, type SlateLogType, SlateLogger, type SlateProviderDocsReference, SlatePublicContext, SlatePublicTool, type SlatePublicToolInvocationHandler, type SlatePublicToolParameters, type SlateServiceErrorData, SlateSpecification, type SlateSpecificationCreateParameters, type SlateSpecificationParameters, SlateTool, type SlateToolInvocationHandler, type SlateToolParameters, SlateTrigger, SlateTriggerGroup, SlateTriggerGroupBuilder, type SlateTriggerGroupCreateParameters, type SlateTriggerGroupGatewayConnectHandler, type SlateTriggerGroupGatewayParameters, type SlateTriggerGroupGatewayReceiveHandler, type SlateTriggerGroupParameters, type SlateTriggerGroupPollHandler, type SlateTriggerGroupPollingParameters, type SlateTriggerGroupRoutingMatchersHandler, type SlateTriggerGroupWebhookAutoRegistrationParameters, type SlateTriggerGroupWebhookManualRegistrationParameters, type SlateTriggerGroupWebhookParameters, type SlateTriggerMappingHandler, type SlateTriggerMatchesHandler, type SlateTriggerParameters, type SlateTriggerRoutingMatcher, type SlateTypedDocsReference, type SlateWebhookHttpResponseInit, type SlateWebhookManualFinishHandler, type SlateWebhookManualSetupHandler, type SlateWebhookProcessHandler, type SlateWebhookRegisterHandler, type SlateWebhookSkipped, type SlateWebhookTarget, type SlateWebhookTargetListHandler, type SlateWebhookTargetOwnership, type SlateWebhookUnregisterHandler, type VerifyHmacSignatureOptions, adapterSpec, allOf, anyOf, auth, axios, buildApiServiceError, collectApiErrorDetails, config, createApiServiceError, createAuthenticatedAxios, createAxios, createBase64Attachment, createHmacSignature, createSlateError, createTextAttachment, createUrlAttachment, extractApiErrorMessage, getApiErrorResponse, getApiErrorStatus, getBase64ByteLength, getCurrentContext, getFileUrlTool, getFileUrlToolInputSchema, getFileUrlToolOutputSchema, getGraphWebhookValidationResponse, getMetaWebhookVerificationResponse, getOAuthExpiresAtFromExpiresIn, getResponseHeaderValue, getServiceErrorData, graphWebhookHttp, inferSlateErrorFromAxios, isApiErrorRecord, isAxiosErrorLike, isServiceErrorData, isUrlEmbeddedCredential, mapServiceErrorCode, mapServiceErrorToSlateErrorInput, mergeScopes, metaWebhookHttp, normalizeOAuthTokenResponse, pickDefined, publicTool, redactUrlAttachmentSecrets, requestAxios, requestAxiosData, runWithContext, scopeClause, setIfDefined, skipWebhook, spec, statusLabelForApiError, tool, trigger, triggerGroup, uploadAttachmentDirect, validateScopes, verifyHmacSignature };

package/dist/index.d.ts

@@ -50,15 +50,17 @@ declare class AuthConfigSecretRedactor {
     private readonly secretToPlaceholder;
     constructor(authConfig: Record<string, unknown> | undefined);
     redact<T>(value: T): T;
-    redactEmbedded<T>(value: T): T;
+    /** `embeddable` limits which secrets are also replaced inside longer strings. */
+    redactEmbedded<T>(value: T, embeddable?: (secret: string, path: string) => boolean): T;
     private buildSecretMap;
     private transform;
     private isPlainObject;
 }
+declare let isUrlEmbeddedCredential: (secret: string, path: string) => boolean;
 /**
  * Applied to every finalized attachment list right before it's sent over
  * `slates/action.tool.invoke` (see @slates/provider-handler). Only `type: 'url'` attachments
- * carry headers/query -- content/upload_reference attachments pass through untouched.
+ * carry credentials -- content/upload_reference attachments pass through untouched.
  */
 declare let redactUrlAttachmentSecrets: (attachments: SlateAttachment[] | undefined, authConfig: Record<string, unknown> | undefined) => SlateAttachment[] | undefined;
 
@@ -150,6 +152,7 @@ type SlateAuthWithOauth<InputType extends {}, OutputType extends {
         scope: string;
     }[];
     adapters?: string[];
+    syncTokensAcrossConnections?: boolean;
     docs?: SlateAuthDocsReference[];
     inputSchema?: z.ZodType<InputType>;
     onInputChanged?: (params: {
@@ -522,6 +525,41 @@ type SlateTriggerGroupPollHandler<ConfigType extends {}, AuthType extends {}> =
     }[];
     updatedState?: any;
 }>;
+interface SlateGatewayEvent {
+    payload: any;
+    idempotencyKey?: string;
+}
+type SlateTriggerGroupGatewayConnectHandler<ConfigType extends {}, AuthType extends {}> = (context: SlateContext<ConfigType, AuthType, {
+    state: any | null;
+}>) => Promise<{
+    url: string;
+    state?: any;
+}>;
+/** `closed` is set, with no frames, when the socket closed unexpectedly. */
+type SlateTriggerGroupGatewayReceiveHandler<ConfigType extends {}, AuthType extends {}> = (context: SlateContext<ConfigType, AuthType, {
+    state: any | null;
+    frames: string[];
+    closed?: {
+        code: number;
+        reason: string;
+    } | null;
+}>) => Promise<{
+    state?: any;
+    send?: string[];
+    events?: SlateGatewayEvent[];
+    /** With `expectsAck`, the hub reconnects when no `heartbeatAcked` arrives before the next beat. */
+    heartbeat?: {
+        intervalMs: number;
+        frame: string;
+        expectsAck?: boolean;
+    } | null;
+    /** Set when `frames` included the provider's heartbeat acknowledgement. */
+    heartbeatAcked?: boolean;
+    close?: {
+        reconnect: boolean;
+        reason?: string;
+    } | null;
+}>;
 type SlateWebhookTargetListHandler<ConfigType extends {}, AuthType extends {}> = (context: SlateContext<ConfigType, AuthType, {
     pageToken: any | null;
 }>) => Promise<{
@@ -573,6 +611,10 @@ interface SlateTriggerGroupPollingParameters<ConfigType extends {}, AuthType ext
     intervalSeconds: number;
     pollEvents: SlateTriggerGroupPollHandler<ConfigType, AuthType>;
 }
+interface SlateTriggerGroupGatewayParameters<ConfigType extends {}, AuthType extends {}> {
+    connect: SlateTriggerGroupGatewayConnectHandler<ConfigType, AuthType>;
+    receive: SlateTriggerGroupGatewayReceiveHandler<ConfigType, AuthType>;
+}
 interface SlateTriggerGroupWebhookAutoRegistrationParameters<ConfigType extends {}, AuthType extends {}> {
     webhookTargetList: SlateWebhookTargetListHandler<ConfigType, AuthType>;
     webhookRegister: SlateWebhookRegisterHandler<ConfigType, AuthType>;
@@ -597,9 +639,10 @@ interface SlateTriggerGroupCreateParameters<InputType extends {} = Record<string
     eventSchema?: z$1.ZodType<InputType>;
 }
 interface SlateTriggerGroupParameters<ConfigType extends {}, AuthType extends {}, InputType extends {} = Record<string, unknown>> extends SlateTriggerGroupCreateParameters<InputType> {
-    source: 'polling' | 'webhook';
+    source: 'polling' | 'webhook' | 'gateway';
     polling?: SlateTriggerGroupPollingParameters<ConfigType, AuthType>;
     webhook?: SlateTriggerGroupWebhookParameters<ConfigType, AuthType>;
+    gateway?: SlateTriggerGroupGatewayParameters<ConfigType, AuthType>;
     routingMatchers: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>;
 }
 declare class SlateTriggerGroup<ConfigType extends {}, AuthType extends {}, InputType extends {} = Record<string, unknown>> {
@@ -613,9 +656,10 @@ declare class SlateTriggerGroup<ConfigType extends {}, AuthType extends {}, Inpu
     get description(): string | undefined;
     get metadata(): Record<string, any> | undefined;
     get eventSchema(): z$1.ZodType<InputType, unknown, z$1.core.$ZodTypeInternals<InputType, unknown>>;
-    get source(): "polling" | "webhook";
+    get source(): "polling" | "webhook" | "gateway";
     get polling(): SlateTriggerGroupPollingParameters<ConfigType, AuthType> | undefined;
     get webhook(): SlateTriggerGroupWebhookParameters<ConfigType, AuthType> | undefined;
+    get gateway(): SlateTriggerGroupGatewayParameters<ConfigType, AuthType> | undefined;
     get routingMatchers(): SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>;
 }
 declare class SlateTriggerGroupBuilder<ConfigType extends {}, AuthType extends {}, InputType extends {} = Record<string, unknown>> {
@@ -633,6 +677,8 @@ declare class SlateTriggerGroupBuilder<ConfigType extends {}, AuthType extends {
         manualRegistration?: SlateTriggerGroupWebhookManualRegistrationParameters<UserConfigSchema, FullConfigSchema>;
         process: SlateWebhookProcessHandler;
     }): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType>;
+    /** Receive events over a platform-managed persistent connection (e.g. a WebSocket gateway). */
+    gateway(props: SlateTriggerGroupGatewayParameters<ConfigType, AuthType>): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType>;
     routingMatchers(handler: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType>;
     build(): SlateTriggerGroup<ConfigType, AuthType, InputType>;
 }
@@ -1093,4 +1139,4 @@ declare let skipWebhook: (reason: string, response?: Response | SlateWebhookHttp
     response: Response | SlateWebhookHttpResponseInit;
 };
 
-export { AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX, type ApiErrorBuildHelpers, type ApiErrorDetailOptions, type ApiErrorResponse, type ApiErrorStatus, type ApiServiceError, AuthConfigSecretRedactor, type BuildApiServiceErrorOptions, type CreateHmacSignatureOptions, GET_FILE_URL_TOOL_ID, type GetFileUrlHandler, type GetFileUrlToolInput, type GetFileUrlToolOutput, type NormalizeOAuthTokenResponseOptions, type OAuthExpiresAtOptions, type OAuthRefreshTokenFallbackMode, type OAuthTokenResponse, Slate, SlateAction, SlateActionBuilder, type SlateActionCreateParameters, type SlateActionDocsReference, type SlateActionParameters, type SlateActionParametersAny, type SlateActionParametersTool, type SlateActionParametersTrigger, type SlateActionScopeClause, type SlateActionScopeClauseInput, type SlateActionScopeValue, type SlateActionScopes, type SlateActionScopesInput, type SlateActionType, SlateAdapter, type SlateAdapterCapability, SlateAdapterSpec, type SlateAdapterSpecParameters, type SlateAddAttachmentContent, type SlateAddAttachmentInput, type SlateAttachment, type SlateAttachmentInlineContent, type SlateAttachmentUploadReferenceContent, type SlateAttachmentUrlContent, SlateAuth, type SlateAuthDocsReference, type SlateAuthType, type SlateAuthWithCustomData, type SlateAuthWithNone, type SlateAuthWithOauth, type SlateAuthWithServiceAccount, type SlateAuthWithToken, type SlateAuthenticatedAxiosDefaults, type SlateAxiosDefaults, type SlateAxiosErrorAdapter, type SlateAxiosErrorOptions, SlateConfig, type SlateConfigDocsReference, SlateContext, SlateDeclarationError, SlateDefaultPollingIntervalSeconds, type SlateDirectUploadInput, type SlateDocsReference, SlateError, type SlateErrorInput, type SlateErrorIssue, type SlateErrorKind, type SlateErrorProviderInfo, type SlateErrorResponse, type SlateErrorUpstreamInfo, type SlateLiveInvocationInfo, type SlateLogEntry, type SlateLogFields, type SlateLogListener, type SlateLogMessageInput, type SlateLogType, SlateLogger, type SlateProviderDocsReference, SlatePublicContext, SlatePublicTool, type SlatePublicToolInvocationHandler, type SlatePublicToolParameters, type SlateServiceErrorData, SlateSpecification, type SlateSpecificationCreateParameters, type SlateSpecificationParameters, SlateTool, type SlateToolInvocationHandler, type SlateToolParameters, SlateTrigger, SlateTriggerGroup, SlateTriggerGroupBuilder, type SlateTriggerGroupCreateParameters, type SlateTriggerGroupParameters, type SlateTriggerGroupPollHandler, type SlateTriggerGroupPollingParameters, type SlateTriggerGroupRoutingMatchersHandler, type SlateTriggerGroupWebhookAutoRegistrationParameters, type SlateTriggerGroupWebhookManualRegistrationParameters, type SlateTriggerGroupWebhookParameters, type SlateTriggerMappingHandler, type SlateTriggerMatchesHandler, type SlateTriggerParameters, type SlateTriggerRoutingMatcher, type SlateTypedDocsReference, type SlateWebhookHttpResponseInit, type SlateWebhookManualFinishHandler, type SlateWebhookManualSetupHandler, type SlateWebhookProcessHandler, type SlateWebhookRegisterHandler, type SlateWebhookSkipped, type SlateWebhookTarget, type SlateWebhookTargetListHandler, type SlateWebhookTargetOwnership, type SlateWebhookUnregisterHandler, type VerifyHmacSignatureOptions, adapterSpec, allOf, anyOf, auth, axios, buildApiServiceError, collectApiErrorDetails, config, createApiServiceError, createAuthenticatedAxios, createAxios, createBase64Attachment, createHmacSignature, createSlateError, createTextAttachment, createUrlAttachment, extractApiErrorMessage, getApiErrorResponse, getApiErrorStatus, getBase64ByteLength, getCurrentContext, getFileUrlTool, getFileUrlToolInputSchema, getFileUrlToolOutputSchema, getGraphWebhookValidationResponse, getMetaWebhookVerificationResponse, getOAuthExpiresAtFromExpiresIn, getResponseHeaderValue, getServiceErrorData, graphWebhookHttp, inferSlateErrorFromAxios, isApiErrorRecord, isAxiosErrorLike, isServiceErrorData, mapServiceErrorCode, mapServiceErrorToSlateErrorInput, mergeScopes, metaWebhookHttp, normalizeOAuthTokenResponse, pickDefined, publicTool, redactUrlAttachmentSecrets, requestAxios, requestAxiosData, runWithContext, scopeClause, setIfDefined, skipWebhook, spec, statusLabelForApiError, tool, trigger, triggerGroup, uploadAttachmentDirect, validateScopes, verifyHmacSignature };
+export { AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX, type ApiErrorBuildHelpers, type ApiErrorDetailOptions, type ApiErrorResponse, type ApiErrorStatus, type ApiServiceError, AuthConfigSecretRedactor, type BuildApiServiceErrorOptions, type CreateHmacSignatureOptions, GET_FILE_URL_TOOL_ID, type GetFileUrlHandler, type GetFileUrlToolInput, type GetFileUrlToolOutput, type NormalizeOAuthTokenResponseOptions, type OAuthExpiresAtOptions, type OAuthRefreshTokenFallbackMode, type OAuthTokenResponse, Slate, SlateAction, SlateActionBuilder, type SlateActionCreateParameters, type SlateActionDocsReference, type SlateActionParameters, type SlateActionParametersAny, type SlateActionParametersTool, type SlateActionParametersTrigger, type SlateActionScopeClause, type SlateActionScopeClauseInput, type SlateActionScopeValue, type SlateActionScopes, type SlateActionScopesInput, type SlateActionType, SlateAdapter, type SlateAdapterCapability, SlateAdapterSpec, type SlateAdapterSpecParameters, type SlateAddAttachmentContent, type SlateAddAttachmentInput, type SlateAttachment, type SlateAttachmentInlineContent, type SlateAttachmentUploadReferenceContent, type SlateAttachmentUrlContent, SlateAuth, type SlateAuthDocsReference, type SlateAuthType, type SlateAuthWithCustomData, type SlateAuthWithNone, type SlateAuthWithOauth, type SlateAuthWithServiceAccount, type SlateAuthWithToken, type SlateAuthenticatedAxiosDefaults, type SlateAxiosDefaults, type SlateAxiosErrorAdapter, type SlateAxiosErrorOptions, SlateConfig, type SlateConfigDocsReference, SlateContext, SlateDeclarationError, SlateDefaultPollingIntervalSeconds, type SlateDirectUploadInput, type SlateDocsReference, SlateError, type SlateErrorInput, type SlateErrorIssue, type SlateErrorKind, type SlateErrorProviderInfo, type SlateErrorResponse, type SlateErrorUpstreamInfo, type SlateGatewayEvent, type SlateLiveInvocationInfo, type SlateLogEntry, type SlateLogFields, type SlateLogListener, type SlateLogMessageInput, type SlateLogType, SlateLogger, type SlateProviderDocsReference, SlatePublicContext, SlatePublicTool, type SlatePublicToolInvocationHandler, type SlatePublicToolParameters, type SlateServiceErrorData, SlateSpecification, type SlateSpecificationCreateParameters, type SlateSpecificationParameters, SlateTool, type SlateToolInvocationHandler, type SlateToolParameters, SlateTrigger, SlateTriggerGroup, SlateTriggerGroupBuilder, type SlateTriggerGroupCreateParameters, type SlateTriggerGroupGatewayConnectHandler, type SlateTriggerGroupGatewayParameters, type SlateTriggerGroupGatewayReceiveHandler, type SlateTriggerGroupParameters, type SlateTriggerGroupPollHandler, type SlateTriggerGroupPollingParameters, type SlateTriggerGroupRoutingMatchersHandler, type SlateTriggerGroupWebhookAutoRegistrationParameters, type SlateTriggerGroupWebhookManualRegistrationParameters, type SlateTriggerGroupWebhookParameters, type SlateTriggerMappingHandler, type SlateTriggerMatchesHandler, type SlateTriggerParameters, type SlateTriggerRoutingMatcher, type SlateTypedDocsReference, type SlateWebhookHttpResponseInit, type SlateWebhookManualFinishHandler, type SlateWebhookManualSetupHandler, type SlateWebhookProcessHandler, type SlateWebhookRegisterHandler, type SlateWebhookSkipped, type SlateWebhookTarget, type SlateWebhookTargetListHandler, type SlateWebhookTargetOwnership, type SlateWebhookUnregisterHandler, type VerifyHmacSignatureOptions, adapterSpec, allOf, anyOf, auth, axios, buildApiServiceError, collectApiErrorDetails, config, createApiServiceError, createAuthenticatedAxios, createAxios, createBase64Attachment, createHmacSignature, createSlateError, createTextAttachment, createUrlAttachment, extractApiErrorMessage, getApiErrorResponse, getApiErrorStatus, getBase64ByteLength, getCurrentContext, getFileUrlTool, getFileUrlToolInputSchema, getFileUrlToolOutputSchema, getGraphWebhookValidationResponse, getMetaWebhookVerificationResponse, getOAuthExpiresAtFromExpiresIn, getResponseHeaderValue, getServiceErrorData, graphWebhookHttp, inferSlateErrorFromAxios, isApiErrorRecord, isAxiosErrorLike, isServiceErrorData, isUrlEmbeddedCredential, mapServiceErrorCode, mapServiceErrorToSlateErrorInput, mergeScopes, metaWebhookHttp, normalizeOAuthTokenResponse, pickDefined, publicTool, redactUrlAttachmentSecrets, requestAxios, requestAxiosData, runWithContext, scopeClause, setIfDefined, skipWebhook, spec, statusLabelForApiError, tool, trigger, triggerGroup, uploadAttachmentDirect, validateScopes, verifyHmacSignature };

package/dist/index.module.js

@@ -293,7 +293,7 @@ var normalizeRetryable = (code, retryable) => {
 };
 var getDefaultMessage = (code, message) => {
   if (message?.trim()) return message;
-  return DEFAULT_MESSAGES[code] ?? DEFAULT_MESSAGES[DEFAULT_CODE];
+  return DEFAULT_MESSAGES[code] ?? DEFAULT_MESSAGES[DEFAULT_CODE] ?? "An unexpected internal error occurred.";
 };
 var cleanRecord = (value) => {
   if (!value) return void 0;
@@ -961,10 +961,14 @@ var AuthConfigSecretRedactor = class {
       return this.secretToPlaceholder.get(stringValue) ?? stringValue;
     });
   }
-  redactEmbedded(value) {
-    if (this.secretToPlaceholder.size === 0) return value;
+  /** `embeddable` limits which secrets are also replaced inside longer strings. */
+  redactEmbedded(value, embeddable = () => true) {
+    let secrets = [...this.secretToPlaceholder.entries()].filter(
+      ([secret, placeholder]) => embeddable(secret, placeholder.slice(AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX.length))
+    ).map(([secret]) => secret);
+    if (secrets.length === 0) return this.redact(value);
     let pattern = new RegExp(
-      [...this.secretToPlaceholder.keys()].sort((a, b) => b.length - a.length).map((secret) => secret.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"),
+      secrets.sort((a, b) => b.length - a.length).map((secret) => secret.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"),
       "g"
     );
     return this.transform(value, (stringValue) => {
@@ -1017,18 +1021,21 @@ var AuthConfigSecretRedactor = class {
     return typeof value === "object" && value !== null && !Array.isArray(value);
   }
 };
+var URL_CREDENTIAL_KEY = /^(?:.*[-_])?(?:token|secret|password|api[-_]?key)$/i;
+var isUrlEmbeddedCredential = (secret, path) => secret.length >= 8 && URL_CREDENTIAL_KEY.test(path.split(".").pop() ?? "");
 var redactUrlAttachmentSecrets = (attachments, authConfig) => {
   if (!authConfig || !attachments) return attachments;
   let redactor = new AuthConfigSecretRedactor(authConfig);
   return attachments.map((attachment) => {
     if (attachment.content.type !== "url") return attachment;
-    if (!attachment.content.headers && !attachment.content.query) return attachment;
+    let { url, headers, query } = attachment.content;
     return {
       ...attachment,
       content: {
         ...attachment.content,
-        headers: attachment.content.headers ? redactor.redactEmbedded(attachment.content.headers) : void 0,
-        query: attachment.content.query ? redactor.redactEmbedded(attachment.content.query) : void 0
+        url: redactor.redactEmbedded(url, isUrlEmbeddedCredential),
+        ...headers ? { headers: redactor.redactEmbedded(headers) } : {},
+        ...query ? { query: redactor.redactEmbedded(query) } : {}
       }
     };
   });
@@ -1078,6 +1085,7 @@ var getFileUrlTool = (spec2, handleGetFileUrl) => tool(spec2, {
   return {
     output: {
       ...output,
+      url: redactor.redactEmbedded(output.url, isUrlEmbeddedCredential),
       ...output.headers ? { headers: redactor.redactEmbedded(output.headers) } : {},
       ...output.query ? { query: redactor.redactEmbedded(output.query) } : {}
     },
@@ -1175,6 +1183,9 @@ var SlateTriggerGroup = class _SlateTriggerGroup {
   get webhook() {
     return this._params.webhook;
   }
+  get gateway() {
+    return this._params.gateway;
+  }
   get routingMatchers() {
     return this._params.routingMatchers;
   }
@@ -1191,6 +1202,7 @@ var SlateTriggerGroupBuilder = class {
   #source = null;
   #polling = null;
   #webhook = null;
+  #gateway = null;
   #routingMatchers = null;
   polling(props) {
     if (this.#source) {
@@ -1220,6 +1232,15 @@ var SlateTriggerGroupBuilder = class {
     };
     return this;
   }
+  /** Receive events over a platform-managed persistent connection (e.g. a WebSocket gateway). */
+  gateway(props) {
+    if (this.#source) {
+      throw new SlateDeclarationError("Trigger group invocation is already defined");
+    }
+    this.#source = "gateway";
+    this.#gateway = { connect: props.connect, receive: props.receive };
+    return this;
+  }
   routingMatchers(handler) {
     this.#routingMatchers = handler;
     return this;
@@ -1227,7 +1248,7 @@ var SlateTriggerGroupBuilder = class {
   build() {
     if (!this.#source) {
       throw new SlateDeclarationError(
-        "Trigger group invocation (polling or webhook) is not defined"
+        "Trigger group invocation (polling, webhook, or gateway) is not defined"
       );
     }
     if (!this.#routingMatchers) {
@@ -1238,6 +1259,7 @@ var SlateTriggerGroupBuilder = class {
       source: this.#source,
       polling: this.#polling ?? void 0,
       webhook: this.#webhook ?? void 0,
+      gateway: this.#gateway ?? void 0,
       routingMatchers: this.#routingMatchers
     });
   }
@@ -2027,6 +2049,7 @@ var redactHashFragment = (hash, redactor) => {
   );
   return redacted ? `#${redacted}` : "";
 };
+var isEmbeddedPathSecret = (secret, path) => secret.length >= 8 && isSecretKeyName(path.split(".").pop() ?? "");
 var sanitizeUrl = (value, redactor) => {
   if (!value) return value;
   try {
@@ -2035,6 +2058,7 @@ var sanitizeUrl = (value, redactor) => {
       url.username = "";
       url.password = "";
     }
+    if (redactor) url.pathname = redactor.redactEmbedded(url.pathname, isEmbeddedPathSecret);
     for (let key of Array.from(url.searchParams.keys())) {
       if (isUrlFormSecretKeyName(key)) {
         url.searchParams.set(key, REDACTED_VALUE);
@@ -2047,7 +2071,7 @@ var sanitizeUrl = (value, redactor) => {
     url.hash = redactHashFragment(url.hash, redactor);
     return decodeRedactedMarker(url.toString());
   } catch {
-    let text = redactor ? redactor.redact(value) : value;
+    let text = redactor ? redactor.redactEmbedded(value, isEmbeddedPathSecret) : value;
     return text.replace(
       /([?&]([^=&#]+)=)([^&#]+)/g,
       (_match, prefix, key, rawValue) => isUrlFormSecretKeyName(key) ? `${prefix}${REDACTED_VALUE}` : `${prefix}${rawValue}`
@@ -2898,6 +2922,7 @@ export {
   isApiErrorRecord,
   isAxiosErrorLike,
   isServiceErrorData,
+  isUrlEmbeddedCredential,
   mapServiceErrorCode,
   mapServiceErrorToSlateErrorInput,
   mergeScopes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slates/provider",
-  "version": "1.0.0-rc.26",
+  "version": "1.0.0-rc.28",
   "publishConfig": {
     "access": "public"
   },

package/src/action/getFileUrlTool.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { AuthConfigSecretRedactor } from '../auth/redact';
+import { AuthConfigSecretRedactor, isUrlEmbeddedCredential } from '../auth/redact';
 import type { SlateContext } from '../context/context';
 import type { SlateSpecification } from '../specification/specification';
 import { tool } from './tool';
@@ -42,6 +42,7 @@ export let getFileUrlTool = <ConfigType extends {}, AuthType extends {}>(
       return {
         output: {
           ...output,
+          url: redactor.redactEmbedded(output.url, isUrlEmbeddedCredential),
           ...(output.headers ? { headers: redactor.redactEmbedded(output.headers) } : {}),
           ...(output.query ? { query: redactor.redactEmbedded(output.query) } : {})
         },

package/src/action/triggerGroup.ts

@@ -31,6 +31,39 @@ export type SlateTriggerGroupPollHandler<ConfigType extends {}, AuthType extends
   updatedState?: any;
 }>;
 
+export interface SlateGatewayEvent {
+  payload: any;
+  idempotencyKey?: string;
+}
+
+export type SlateTriggerGroupGatewayConnectHandler<
+  ConfigType extends {},
+  AuthType extends {}
+> = (
+  context: SlateContext<ConfigType, AuthType, { state: any | null }>
+) => Promise<{ url: string; state?: any }>;
+
+/** `closed` is set, with no frames, when the socket closed unexpectedly. */
+export type SlateTriggerGroupGatewayReceiveHandler<
+  ConfigType extends {},
+  AuthType extends {}
+> = (
+  context: SlateContext<
+    ConfigType,
+    AuthType,
+    { state: any | null; frames: string[]; closed?: { code: number; reason: string } | null }
+  >
+) => Promise<{
+  state?: any;
+  send?: string[];
+  events?: SlateGatewayEvent[];
+  /** With `expectsAck`, the hub reconnects when no `heartbeatAcked` arrives before the next beat. */
+  heartbeat?: { intervalMs: number; frame: string; expectsAck?: boolean } | null;
+  /** Set when `frames` included the provider's heartbeat acknowledgement. */
+  heartbeatAcked?: boolean;
+  close?: { reconnect: boolean; reason?: string } | null;
+}>;
+
 export type SlateWebhookTargetListHandler<ConfigType extends {}, AuthType extends {}> = (
   context: SlateContext<ConfigType, AuthType, { pageToken: any | null }>
 ) => Promise<{
@@ -121,6 +154,14 @@ export interface SlateTriggerGroupPollingParameters<
   pollEvents: SlateTriggerGroupPollHandler<ConfigType, AuthType>;
 }
 
+export interface SlateTriggerGroupGatewayParameters<
+  ConfigType extends {},
+  AuthType extends {}
+> {
+  connect: SlateTriggerGroupGatewayConnectHandler<ConfigType, AuthType>;
+  receive: SlateTriggerGroupGatewayReceiveHandler<ConfigType, AuthType>;
+}
+
 export interface SlateTriggerGroupWebhookAutoRegistrationParameters<
   ConfigType extends {},
   AuthType extends {}
@@ -164,9 +205,10 @@ export interface SlateTriggerGroupParameters<
   AuthType extends {},
   InputType extends {} = Record<string, unknown>
 > extends SlateTriggerGroupCreateParameters<InputType> {
-  source: 'polling' | 'webhook';
+  source: 'polling' | 'webhook' | 'gateway';
   polling?: SlateTriggerGroupPollingParameters<ConfigType, AuthType>;
   webhook?: SlateTriggerGroupWebhookParameters<ConfigType, AuthType>;
+  gateway?: SlateTriggerGroupGatewayParameters<ConfigType, AuthType>;
   routingMatchers: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>;
 }
 
@@ -227,6 +269,10 @@ export class SlateTriggerGroup<
     return this._params.webhook;
   }
 
+  get gateway() {
+    return this._params.gateway;
+  }
+
   get routingMatchers() {
     return this._params.routingMatchers;
   }
@@ -237,9 +283,10 @@ export class SlateTriggerGroupBuilder<
   AuthType extends {},
   InputType extends {} = Record<string, unknown>
 > {
-  #source: 'polling' | 'webhook' | null = null;
+  #source: 'polling' | 'webhook' | 'gateway' | null = null;
   #polling: SlateTriggerGroupPollingParameters<ConfigType, AuthType> | null = null;
   #webhook: SlateTriggerGroupWebhookParameters<ConfigType, AuthType> | null = null;
+  #gateway: SlateTriggerGroupGatewayParameters<ConfigType, AuthType> | null = null;
   #routingMatchers: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType> | null =
     null;
 
@@ -302,6 +349,20 @@ export class SlateTriggerGroupBuilder<
     return this;
   }
 
+  /** Receive events over a platform-managed persistent connection (e.g. a WebSocket gateway). */
+  gateway(
+    props: SlateTriggerGroupGatewayParameters<ConfigType, AuthType>
+  ): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType> {
+    if (this.#source) {
+      throw new SlateDeclarationError('Trigger group invocation is already defined');
+    }
+
+    this.#source = 'gateway';
+    this.#gateway = { connect: props.connect, receive: props.receive };
+
+    return this;
+  }
+
   routingMatchers(
     handler: SlateTriggerGroupRoutingMatchersHandler<ConfigType, AuthType>
   ): SlateTriggerGroupBuilder<ConfigType, AuthType, InputType> {
@@ -312,7 +373,7 @@ export class SlateTriggerGroupBuilder<
   build(): SlateTriggerGroup<ConfigType, AuthType, InputType> {
     if (!this.#source) {
       throw new SlateDeclarationError(
-        'Trigger group invocation (polling or webhook) is not defined'
+        'Trigger group invocation (polling, webhook, or gateway) is not defined'
       );
     }
     if (!this.#routingMatchers) {
@@ -324,6 +385,7 @@ export class SlateTriggerGroupBuilder<
       source: this.#source,
       polling: this.#polling ?? undefined,
       webhook: this.#webhook ?? undefined,
+      gateway: this.#gateway ?? undefined,
       routingMatchers: this.#routingMatchers
     });
   }

package/src/auth/redact.test.ts

@@ -167,7 +167,7 @@ describe('redactUrlAttachmentSecrets', () => {
     ]);
   });
 
-  it('only changes header and query values, preserving metadata and the original attachment', () => {
+  it('only changes credential values, preserving metadata and the original attachment', () => {
     let attachment: SlateAttachment = {
       mimeType: 'application/pdf',
       attachmentHash: 'file-hash',
@@ -187,6 +187,7 @@ describe('redactUrlAttachmentSecrets', () => {
         ...original,
         content: {
           ...original.content,
+          url: 'https://example.com/$$MT$secret$authConfig$token$$/file.pdf',
           headers: { Authorization: 'Bearer $$MT$secret$authConfig$token$$' },
           query: { key: '$$MT$secret$authConfig$nested.token2$$-suffix' }
         }
@@ -195,7 +196,35 @@ describe('redactUrlAttachmentSecrets', () => {
     expect(attachment).toEqual(original);
   });
 
-  it('leaves url attachments with no headers/query untouched', () => {
+  it('redacts a bot token embedded in the url path', () => {
+    let attachments = [
+      urlAttachment({ url: 'https://api.telegram.org/file/bot123:ABCDEFGH/photos/a.jpg' })
+    ];
+
+    expect(
+      redactUrlAttachmentSecrets(attachments, { token: '123:ABCDEFGH', botId: '12345678' })
+    ).toEqual([
+      urlAttachment({
+        url: 'https://api.telegram.org/file/bot$$MT$secret$authConfig$token$$/photos/a.jpg'
+      })
+    ]);
+  });
+
+  it('keeps non-credential and short auth values in the url', () => {
+    let attachments = [
+      urlAttachment({ url: 'https://example.com/AC12345678/12345678/abc/file.pdf' })
+    ];
+
+    expect(
+      redactUrlAttachmentSecrets(attachments, {
+        account_sid: 'AC12345678',
+        botId: '12345678',
+        token: 'abc'
+      })
+    ).toEqual(attachments);
+  });
+
+  it('leaves url attachments with no credentials untouched', () => {
     let attachments = [urlAttachment()];
     expect(redactUrlAttachmentSecrets(attachments, authConfig)).toEqual(attachments);
   });

package/src/auth/redact.ts

@@ -25,11 +25,20 @@ export class AuthConfigSecretRedactor {
     });
   }
 
-  public redactEmbedded<T>(value: T): T {
-    if (this.secretToPlaceholder.size === 0) return value;
+  /** `embeddable` limits which secrets are also replaced inside longer strings. */
+  public redactEmbedded<T>(
+    value: T,
+    embeddable: (secret: string, path: string) => boolean = () => true
+  ): T {
+    let secrets = [...this.secretToPlaceholder.entries()]
+      .filter(([secret, placeholder]) =>
+        embeddable(secret, placeholder.slice(AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX.length))
+      )
+      .map(([secret]) => secret);
+    if (secrets.length === 0) return this.redact(value);
 
     let pattern = new RegExp(
-      [...this.secretToPlaceholder.keys()]
+      secrets
         .sort((a, b) => b.length - a.length)
         // Escape regex metacharacters so values match literally; $& inserts the matched character.
         .map(secret => secret.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
@@ -102,10 +111,17 @@ export class AuthConfigSecretRedactor {
   }
 }
 
+// Credentials replaced inside URLs (e.g. Telegram's `/file/bot<token>/` path). Kept narrow:
+// a placeholder in a URL makes the hub proxy the download instead of handing out the link.
+let URL_CREDENTIAL_KEY = /^(?:.*[-_])?(?:token|secret|password|api[-_]?key)$/i;
+
+export let isUrlEmbeddedCredential = (secret: string, path: string) =>
+  secret.length >= 8 && URL_CREDENTIAL_KEY.test(path.split('.').pop() ?? '');
+
 /**
  * Applied to every finalized attachment list right before it's sent over
  * `slates/action.tool.invoke` (see @slates/provider-handler). Only `type: 'url'` attachments
- * carry headers/query -- content/upload_reference attachments pass through untouched.
+ * carry credentials -- content/upload_reference attachments pass through untouched.
  */
 export let redactUrlAttachmentSecrets = (
   attachments: SlateAttachment[] | undefined,
@@ -117,18 +133,15 @@ export let redactUrlAttachmentSecrets = (
 
   return attachments.map(attachment => {
     if (attachment.content.type !== 'url') return attachment;
-    if (!attachment.content.headers && !attachment.content.query) return attachment;
 
+    let { url, headers, query } = attachment.content;
     return {
       ...attachment,
       content: {
         ...attachment.content,
-        headers: attachment.content.headers
-          ? redactor.redactEmbedded(attachment.content.headers)
-          : undefined,
-        query: attachment.content.query
-          ? redactor.redactEmbedded(attachment.content.query)
-          : undefined
+        url: redactor.redactEmbedded(url, isUrlEmbeddedCredential),
+        ...(headers ? { headers: redactor.redactEmbedded(headers) } : {}),
+        ...(query ? { query: redactor.redactEmbedded(query) } : {})
       }
     };
   });

package/src/auth/types.ts

@@ -24,6 +24,10 @@ export type SlateAuthWithOauth<
 
   adapters?: string[];
 
+  // Set when the provider issues the same rotating token pair to every
+  // connection of one installation, so a refresh must update all of them.
+  syncTokensAcrossConnections?: boolean;
+
   docs?: SlateAuthDocsReference[];
 
   inputSchema?: z.ZodType<InputType>;

package/src/axios/trace.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { AuthConfigSecretRedactor } from '../auth/redact';
 import { __traceInternals } from './trace';
 
 let {
@@ -272,6 +273,26 @@ describe('sanitizeUrl', () => {
     expect(out).toContain('expires_in=3600');
   });
 
+  it('redacts long auth-config secrets embedded in the path', () => {
+    let redactor = new AuthConfigSecretRedactor({
+      token: '123456:ABCdefGHIjklMNOpqrSTU',
+      botId: '123456',
+      applicationId: '1503442063478362305'
+    });
+    expect(
+      sanitizeUrl('https://api.telegram.org/bot123456:ABCdefGHIjklMNOpqrSTU/getMe', redactor)
+    ).toBe('https://api.telegram.org/bot$$MT$secret$authConfig$token$$/getMe');
+    expect(sanitizeUrl('https://example.com/bots/123456/info', redactor)).toBe(
+      'https://example.com/bots/123456/info'
+    );
+    expect(
+      sanitizeUrl(
+        'https://discord.com/api/applications/1503442063478362305/commands',
+        redactor
+      )
+    ).toBe('https://discord.com/api/applications/1503442063478362305/commands');
+  });
+
   it('leaves innocuous URLs unchanged', () => {
     expect(sanitizeUrl('https://example.com/api?page=2&limit=10')).toBe(
       'https://example.com/api?page=2&limit=10'

package/src/axios/trace.ts

@@ -563,6 +563,10 @@ let redactHashFragment = (hash: string, redactor?: AuthConfigSecretRedactor) =>
   return redacted ? `#${redacted}` : '';
 };
 
+// Redacts secret-keyed auth values embedded in URL paths (e.g. Telegram's `/bot<token>/...`).
+let isEmbeddedPathSecret = (secret: string, path: string) =>
+  secret.length >= 8 && isSecretKeyName(path.split('.').pop() ?? '');
+
 let sanitizeUrl = (value: string, redactor?: AuthConfigSecretRedactor) => {
   if (!value) return value;
 
@@ -574,6 +578,8 @@ let sanitizeUrl = (value: string, redactor?: AuthConfigSecretRedactor) => {
       url.password = '';
     }
 
+    if (redactor) url.pathname = redactor.redactEmbedded(url.pathname, isEmbeddedPathSecret);
+
     for (let key of Array.from(url.searchParams.keys())) {
       if (isUrlFormSecretKeyName(key)) {
         url.searchParams.set(key, REDACTED_VALUE);
@@ -590,7 +596,7 @@ let sanitizeUrl = (value: string, redactor?: AuthConfigSecretRedactor) => {
 
     return decodeRedactedMarker(url.toString());
   } catch {
-    let text = redactor ? redactor.redact(value) : value;
+    let text = redactor ? redactor.redactEmbedded(value, isEmbeddedPathSecret) : value;
     return text.replace(
       /([?&]([^=&#]+)=)([^&#]+)/g,
       (_match, prefix: string, key: string, rawValue: string) =>

package/src/error/base.ts

@@ -12,7 +12,7 @@ import {
 } from './utils';
 
 export class SlateError extends Error {
-  cause?: unknown;
+  override cause?: unknown;
   data: SlateErrorResponse;
 
   constructor(input: SlateErrorInput) {

package/src/error/declaration.ts

@@ -11,7 +11,7 @@ export class SlateDeclarationError extends SlateError {
     this.name = 'SlateError.DeclarationError';
   }
 
-  static is(error: unknown): error is SlateDeclarationError {
+  static override is(error: unknown): error is SlateDeclarationError {
     return error instanceof SlateDeclarationError;
   }
 }

package/src/error/utils.ts

@@ -61,9 +61,13 @@ export let normalizeRetryable = (code: string, retryable?: boolean) => {
   );
 };
 
-export let getDefaultMessage = (code: string, message?: string) => {
+export let getDefaultMessage = (code: string, message?: string): string => {
   if (message?.trim()) return message;
-  return DEFAULT_MESSAGES[code] ?? DEFAULT_MESSAGES[DEFAULT_CODE];
+  return (
+    DEFAULT_MESSAGES[code] ??
+    DEFAULT_MESSAGES[DEFAULT_CODE] ??
+    'An unexpected internal error occurred.'
+  );
 };
 
 export let cleanRecord = <Value extends Record<string, unknown> | undefined>(value: Value) => {