@slates/provider 1.0.0-rc.33 → 1.0.0-rc.35

package/dist/index.cjs

@@ -48,6 +48,7 @@ __export(index_exports, {
   SlateDefaultPollingIntervalSeconds: () => SlateDefaultPollingIntervalSeconds,
   SlateError: () => SlateError,
   SlateLogger: () => SlateLogger,
+  SlateOptionList: () => SlateOptionList,
   SlatePublicContext: () => SlatePublicContext,
   SlatePublicTool: () => SlatePublicTool,
   SlateSpecification: () => SlateSpecification,
@@ -59,6 +60,7 @@ __export(index_exports, {
   adapterSpec: () => adapterSpec,
   allOf: () => allOf,
   anyOf: () => anyOf,
+  assertNewPageToken: () => assertNewPageToken,
   auth: () => auth,
   axios: () => axios,
   buildApiServiceError: () => buildApiServiceError,
@@ -88,6 +90,7 @@ __export(index_exports, {
   getResponseHeaderValue: () => getResponseHeaderValue,
   getRuntimeInfo: () => getRuntimeInfo,
   getServiceErrorData: () => getServiceErrorData,
+  getUpstreamErrorStatus: () => getUpstreamErrorStatus,
   graphWebhookHttp: () => graphWebhookHttp,
   inferSlateErrorFromAxios: () => inferSlateErrorFromAxios,
   isApiErrorRecord: () => isApiErrorRecord,
@@ -100,19 +103,26 @@ __export(index_exports, {
   mergeScopes: () => mergeScopes,
   metaWebhookHttp: () => metaWebhookHttp,
   normalizeOAuthTokenResponse: () => normalizeOAuthTokenResponse,
+  optionList: () => optionList,
+  parseWithServiceError: () => parseWithServiceError,
   pickDefined: () => pickDefined,
+  pruneSeenEntries: () => pruneSeenEntries,
   publicTool: () => publicTool,
   pushBoundedApiErrorDetail: () => pushBoundedApiErrorDetail,
   readApiErrorText: () => readApiErrorText,
   redactUrlAttachmentSecrets: () => redactUrlAttachmentSecrets,
+  rememberPageToken: () => rememberPageToken,
   requestAxios: () => requestAxios,
   requestAxiosData: () => requestAxiosData,
   runWithContext: () => runWithContext,
   scopeClause: () => scopeClause,
+  seenEntryKey: () => seenEntryKey,
+  seenEntrySchema: () => seenEntrySchema,
   setIfDefined: () => setIfDefined,
   skipWebhook: () => skipWebhook,
   spec: () => spec,
   statusLabelForApiError: () => statusLabelForApiError,
+  timingSafeStringEqual: () => timingSafeStringEqual,
   tool: () => tool,
   toolCategory: () => toolCategory,
   trigger: () => trigger,
@@ -1392,6 +1402,11 @@ var getApiErrorResponse = (error) => {
   };
 };
 var getApiErrorStatus = (error) => getApiErrorResponse(error)?.status;
+var getUpstreamErrorStatus = (error) => {
+  let value = error instanceof import_error.ServiceError ? error.data.upstreamStatus : getApiErrorStatus(error);
+  let status = Number(value);
+  return Number.isInteger(status) && status >= 100 && status <= 599 ? status : void 0;
+};
 var getApiErrorResponseWithBody = (error) => {
   let response = getApiErrorResponse(error);
   if (response?.data !== void 0) return response;
@@ -1899,6 +1914,13 @@ var SlateDeclarationError = class _SlateDeclarationError extends SlateError {
   }
 };
 
+// src/error/parse.ts
+var parseWithServiceError = (schema, value, message, options = {}) => {
+  let result = schema.safeParse(value);
+  if (!result.success) throw createApiServiceError(message, options);
+  return result.data;
+};
+
 // src/action/scopes.ts
 var scopeClause = (...scopes) => {
   assertScopeValues(scopes);
@@ -1967,6 +1989,45 @@ var isClause = (value) => typeof value === "object" && value !== null && "OR" in
 var isScopes = (value) => typeof value === "object" && value !== null && "AND" in value && Array.isArray(value.AND);
 
 // src/action/builder.ts
+var EVENT_ATTRIBUTE_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+var EVENT_ATTRIBUTE_MAX_KEYS = 8;
+var checkEventAttributeNames = (fields) => {
+  if (!Array.isArray(fields)) {
+    throw new SlateDeclarationError("Event attributes must be a list of output field names");
+  }
+  if (fields.length > EVENT_ATTRIBUTE_MAX_KEYS) {
+    throw new SlateDeclarationError(
+      `A trigger can declare at most ${EVENT_ATTRIBUTE_MAX_KEYS} event attributes`
+    );
+  }
+  let seen = /* @__PURE__ */ new Set();
+  for (let field of fields) {
+    if (typeof field !== "string" || !EVENT_ATTRIBUTE_KEY_PATTERN.test(field)) {
+      throw new SlateDeclarationError(
+        `Event attribute "${field}" must start with a letter and contain only letters, digits and underscores (at most 64 characters)`
+      );
+    }
+    if (seen.has(field)) {
+      throw new SlateDeclarationError(`Event attribute "${field}" is declared more than once`);
+    }
+    seen.add(field);
+  }
+};
+var checkEventAttributeFields = (fields, outputSchema) => {
+  if (outputSchema._zod?.def?.type !== "object") {
+    throw new SlateDeclarationError(
+      "Event attributes require the output schema to be a zod object"
+    );
+  }
+  let shape = outputSchema.shape;
+  for (let field of fields) {
+    if (!Object.hasOwn(shape, field)) {
+      throw new SlateDeclarationError(
+        `Event attribute "${field}" is not a top-level property of the output schema`
+      );
+    }
+  }
+};
 var SlateActionBuilder = class {
   constructor(type, spec2, params, factory, isPublicTool = false) {
     this.type = type;
@@ -1992,6 +2053,7 @@ var SlateActionBuilder = class {
   #triggerGroup = null;
   #triggerMatches = null;
   #triggerMap = null;
+  #eventAttributes = null;
   #interfaceLocked = false;
   input(schema) {
     if (this.#interfaceLocked) {
@@ -2062,6 +2124,21 @@ var SlateActionBuilder = class {
     this.#triggerMap = handler;
     return this;
   }
+  /**
+   * Returns the values of these top-level output fields with every mapped event, so events
+   * can be filtered by them. Strings, finite numbers, booleans and arrays of those are used.
+   */
+  eventAttributes(fields) {
+    if (this.type !== "trigger") {
+      throw new SlateDeclarationError("eventAttributes can only be set for trigger actions");
+    }
+    checkEventAttributeNames(fields);
+    if (this.#outputSchema) {
+      checkEventAttributeFields(fields, this.#outputSchema);
+    }
+    this.#eventAttributes = [...fields];
+    return this;
+  }
   build() {
     let scopes = this.#scopes ?? this.params.scopes;
     if (scopes) {
@@ -2089,11 +2166,15 @@ var SlateActionBuilder = class {
     if (this.type === "trigger" && !this.#triggerMap) {
       throw new SlateDeclarationError("Trigger map handler is not defined");
     }
+    if (this.#eventAttributes) {
+      checkEventAttributeFields(this.#eventAttributes, this.#outputSchema);
+    }
     let triggerParams = this.type === "trigger" ? {
       type: "trigger",
       triggerGroup: this.#triggerGroup,
       matches: this.#triggerMatches,
-      map: this.#triggerMap
+      map: this.#triggerMap,
+      ...this.#eventAttributes?.length ? { eventAttributes: this.#eventAttributes } : {}
     } : null;
     return this.factory({
       ...this.params,
@@ -2165,6 +2246,41 @@ var getFileUrlTool = (spec2, handleGetFileUrl) => tool(spec2, {
   };
 }).build();
 
+// src/action/optionList.ts
+var import_zod2 = require("zod");
+var SlateOptionList = class _SlateOptionList {
+  constructor(_spec, _params, _paramsSchema) {
+    this._spec = _spec;
+    this._params = _params;
+    this._paramsSchema = _paramsSchema;
+  }
+  _spec;
+  _params;
+  _paramsSchema;
+  static create(spec2, params) {
+    let paramsSchema = params.paramsSchema ?? import_zod2.z.object({});
+    if (paramsSchema?._zod?.def?.type !== "object") {
+      throw new SlateDeclarationError(
+        `Option list "${params.key}" params schema must be a zod object`
+      );
+    }
+    return new _SlateOptionList(spec2, params, paramsSchema.strict());
+  }
+  get spec() {
+    return this._spec;
+  }
+  get key() {
+    return this._params.key;
+  }
+  get paramsSchema() {
+    return this._paramsSchema;
+  }
+  get list() {
+    return this._params.list;
+  }
+};
+var optionList = (spec2, params) => SlateOptionList.create(spec2, params);
+
 // src/action/publicTool.ts
 var SlatePublicTool = class {
   constructor() {
@@ -2218,11 +2334,13 @@ var SlateTrigger = class _SlateTrigger extends SlateAction {
   #triggerGroup;
   #matches;
   #map;
+  #eventAttributes;
   constructor(spec2, inputSchema, outputSchema, params) {
     super("trigger", spec2, inputSchema, outputSchema, params);
     this.#triggerGroup = params.triggerGroup;
     this.#matches = params.matches;
     this.#map = params.map;
+    this.#eventAttributes = params.eventAttributes ?? [];
   }
   static create(spec2, params) {
     return new SlateActionBuilder("trigger", spec2, params, (params2) => {
@@ -2239,12 +2357,53 @@ var SlateTrigger = class _SlateTrigger extends SlateAction {
   get map() {
     return this.#map;
   }
+  get eventAttributes() {
+    return [...this.#eventAttributes];
+  }
 };
 var trigger = (spec2, params) => SlateTrigger.create(spec2, params);
 
 // src/action/triggerGroup.ts
-var import_zod2 = require("zod");
+var import_zod3 = require("zod");
 var SlateDefaultPollingIntervalSeconds = 60 * 10;
+var LINKED_SLATE_PATTERN = /^[^/\s]+\/[^/\s]+$/;
+var checkSelectionOptions = (field, sources, shape) => {
+  if (!Object.hasOwn(shape, field)) {
+    throw new SlateDeclarationError(
+      `Selection field "${field}" is not a top-level property of the selection schema`
+    );
+  }
+  if (typeof sources !== "object" || sources === null) {
+    throw new SlateDeclarationError(
+      `Selection field "${field}" must be declared as { list, linked }`
+    );
+  }
+  let { list, linked } = sources;
+  if (!list && !linked) {
+    throw new SlateDeclarationError(
+      `Selection field "${field}" needs its own options list, a linked option list, or both`
+    );
+  }
+  if (list !== void 0 && typeof list !== "function") {
+    throw new SlateDeclarationError(`Selection field "${field}" list must be a function`);
+  }
+  if (linked) {
+    if (typeof linked.slate !== "string" || !LINKED_SLATE_PATTERN.test(linked.slate)) {
+      throw new SlateDeclarationError(
+        `Selection field "${field}" links to slate "${linked.slate}", which must be written as <scope>/<name>`
+      );
+    }
+    if (typeof linked.optionList !== "string" || !linked.optionList.trim()) {
+      throw new SlateDeclarationError(
+        `Selection field "${field}" must name the option list it links to`
+      );
+    }
+  }
+  return {
+    ...list ? { list } : {},
+    ...linked ? { linked } : {}
+  };
+};
 var SlateTriggerGroup = class _SlateTriggerGroup {
   constructor(_spec, _params) {
     this._spec = _spec;
@@ -2271,11 +2430,14 @@ var SlateTriggerGroup = class _SlateTriggerGroup {
     return this._params.metadata;
   }
   get eventSchema() {
-    return this._params.eventSchema ?? import_zod2.z.object({}).passthrough();
+    return this._params.eventSchema ?? import_zod3.z.object({}).passthrough();
   }
   get source() {
     return this._params.source;
   }
+  get selectionSchema() {
+    return this._params.selectionSchema;
+  }
   get polling() {
     return this._params.polling;
   }
@@ -2288,6 +2450,9 @@ var SlateTriggerGroup = class _SlateTriggerGroup {
   get routingMatchers() {
     return this._params.routingMatchers;
   }
+  get selectionOptions() {
+    return this._params.selectionOptions ?? {};
+  }
 };
 var SlateTriggerGroupBuilder = class {
   constructor(spec2, params, factory) {
@@ -2303,6 +2468,7 @@ var SlateTriggerGroupBuilder = class {
   #webhook = null;
   #gateway = null;
   #routingMatchers = null;
+  #selectionOptions = {};
   polling(props) {
     if (this.#source) {
       throw new SlateDeclarationError("Trigger group invocation is already defined");
@@ -2323,11 +2489,41 @@ var SlateTriggerGroupBuilder = class {
         "Webhook trigger groups require exactly one of autoRegistration or manualRegistration"
       );
     }
+    if (props.deliveryConfig !== void 0) {
+      if (!props.autoRegistration) {
+        throw new SlateDeclarationError(
+          "A webhook delivery config requires automatic webhook registration"
+        );
+      }
+      if (!props.deliveryConfig.finish) {
+        throw new SlateDeclarationError("A webhook delivery config requires a finish handler");
+      }
+      if (!props.deliveryConfig.authenticate) {
+        throw new SlateDeclarationError(
+          "A webhook delivery config requires an authenticate handler"
+        );
+      }
+    }
+    if (props.reconcileIntervalSeconds !== void 0) {
+      if (!Number.isSafeInteger(props.reconcileIntervalSeconds) || props.reconcileIntervalSeconds < 900) {
+        throw new SlateDeclarationError(
+          "Webhook reconciliation interval must be an integer of at least 900 seconds"
+        );
+      }
+      if (!props.expandWebhook) {
+        throw new SlateDeclarationError(
+          "Webhook reconciliation requires an expandWebhook handler"
+        );
+      }
+    }
     this.#source = "webhook";
     this.#webhook = {
       autoRegistration: props.autoRegistration,
       manualRegistration: props.manualRegistration,
-      process: props.process
+      deliveryConfig: props.deliveryConfig,
+      process: props.process,
+      expandWebhook: props.expandWebhook,
+      reconcileIntervalSeconds: props.reconcileIntervalSeconds
     };
     return this;
   }
@@ -2344,6 +2540,27 @@ var SlateTriggerGroupBuilder = class {
     this.#routingMatchers = handler;
     return this;
   }
+  /**
+   * Lets the dashboard offer a list for these selection fields instead of a typed-in value.
+   * Each field must be a top-level property of the selection schema, which must be a zod object.
+   * For an array property the listed options are values for its items.
+   */
+  selectionOptions(declarations) {
+    let schema = this.params.selectionSchema;
+    if (!schema) {
+      throw new SlateDeclarationError("Selection options require a selection schema");
+    }
+    if (schema._zod?.def?.type !== "object") {
+      throw new SlateDeclarationError(
+        "Selection options require the selection schema to be a zod object"
+      );
+    }
+    let shape = schema.shape;
+    for (let [field, sources] of Object.entries(declarations)) {
+      this.#selectionOptions[field] = checkSelectionOptions(field, sources, shape);
+    }
+    return this;
+  }
   build() {
     if (!this.#source) {
       throw new SlateDeclarationError(
@@ -2359,7 +2576,8 @@ var SlateTriggerGroupBuilder = class {
       polling: this.#polling ?? void 0,
       webhook: this.#webhook ?? void 0,
       gateway: this.#gateway ?? void 0,
-      routingMatchers: this.#routingMatchers
+      routingMatchers: this.#routingMatchers,
+      selectionOptions: this.#selectionOptions
     });
   }
 };
@@ -3107,13 +3325,29 @@ var createHmacSignature = ({
   digest,
   prefix = ""
 }) => `${prefix}${(0, import_crypto.createHmac)(algorithm, secret).update(payload).digest(digest)}`;
-var verifyHmacSignature = (options) => {
-  let expected = createHmacSignature(options);
+var timingSafeStringEqual = (expected, received) => {
   let expectedBytes = Buffer.from(expected);
-  let signatureBytes = Buffer.from(options.signature);
-  let lengthsMatch = signatureBytes.length === expectedBytes.length;
-  let comparableSignature = lengthsMatch ? signatureBytes : Buffer.alloc(expectedBytes.length);
-  return (0, import_crypto.timingSafeEqual)(comparableSignature, expectedBytes) && lengthsMatch;
+  let receivedBytes = Buffer.from(received ?? "");
+  let lengthsMatch = receivedBytes.length === expectedBytes.length;
+  let comparable = lengthsMatch ? receivedBytes : Buffer.alloc(expectedBytes.length);
+  return (0, import_crypto.timingSafeEqual)(comparable, expectedBytes) && lengthsMatch && expectedBytes.length > 0;
+};
+var verifyHmacSignature = (options) => timingSafeStringEqual(createHmacSignature(options), options.signature);
+
+// src/dedup/index.ts
+var import_crypto2 = require("crypto");
+var import_zod4 = require("zod");
+var seenEntrySchema = import_zod4.z.object({ key: import_zod4.z.string().min(1), at: import_zod4.z.number().finite() });
+var seenEntryKey = (idempotencyKey) => (0, import_crypto2.createHash)("sha256").update(idempotencyKey).digest("base64url").slice(0, 16);
+var pruneSeenEntries = (entries, options) => {
+  let kept = [];
+  for (let { key, at, retain } of entries) {
+    if (retain || at >= options.cutoff) kept.push({ key, at });
+  }
+  kept.sort((a, b) => b.at - a.at || (a.key < b.key ? -1 : 1));
+  if (kept.length <= options.maxEntries) return kept;
+  options.onOverflow?.(kept.length - options.maxEntries);
+  return kept.slice(0, options.maxEntries);
 };
 
 // src/file/index.ts
@@ -3243,15 +3477,26 @@ var setIfDefined = (target, key, value) => {
   return target;
 };
 
+// src/pagination/index.ts
+var rememberPageToken = (seen, token) => {
+  if (seen.has(token)) return false;
+  seen.add(token);
+  return true;
+};
+var assertNewPageToken = (seen, token, repeated) => {
+  if (token && !rememberPageToken(seen, token)) throw repeated();
+};
+
 // src/specification/slate.ts
 var Slate = class _Slate {
-  constructor(_spec, _actions, _adapters, _triggerGroups, _toolCategories, _toolCategoryKeysByActionKey) {
+  constructor(_spec, _actions, _adapters, _triggerGroups, _toolCategories, _toolCategoryKeysByActionKey, _optionLists) {
     this._spec = _spec;
     this._actions = _actions;
     this._adapters = _adapters;
     this._triggerGroups = _triggerGroups;
     this._toolCategories = _toolCategories;
     this._toolCategoryKeysByActionKey = _toolCategoryKeysByActionKey;
+    this._optionLists = _optionLists;
   }
   _spec;
   _actions;
@@ -3259,6 +3504,7 @@ var Slate = class _Slate {
   _triggerGroups;
   _toolCategories;
   _toolCategoryKeysByActionKey;
+  _optionLists;
   static create(params) {
     let adapters = params.adapters ?? [];
     let actions = [...params.triggers, ...params.tools];
@@ -3294,14 +3540,24 @@ var Slate = class _Slate {
       }
       seenTriggerGroupKeys.add(group.key);
     }
-    let manualWebhookTriggerGroups = triggerGroups.filter(
-      (group) => group.source === "webhook" && group.webhook?.manualRegistration
+    let configuredWebhookTriggerGroups = triggerGroups.filter(
+      (group) => group.source === "webhook" && (group.webhook?.manualRegistration || group.webhook?.deliveryConfig)
     );
-    if (manualWebhookTriggerGroups.length > 1) {
+    if (configuredWebhookTriggerGroups.length > 1) {
       throw new SlateDeclarationError(
-        `Only one trigger group may use manual webhook registration, but found: ${manualWebhookTriggerGroups.map((group) => group.key).join(", ")}`
+        `Only one trigger group may use manual webhook registration or a delivery config, but found: ${configuredWebhookTriggerGroups.map((group) => group.key).join(", ")}`
       );
     }
+    let optionLists = params.optionLists ?? [];
+    let seenOptionListKeys = /* @__PURE__ */ new Set();
+    for (let list of optionLists) {
+      if (seenOptionListKeys.has(list.key)) {
+        throw new SlateDeclarationError(
+          `Option list "${list.key}" is registered more than once`
+        );
+      }
+      seenOptionListKeys.add(list.key);
+    }
     let toolCategories = params.toolCategories ?? [];
     let toolCategoryKeysByActionKey = resolveToolCategoryMembership(toolCategories, actions);
     return new _Slate(
@@ -3310,7 +3566,8 @@ var Slate = class _Slate {
       adapters,
       triggerGroups,
       toolCategories,
-      toolCategoryKeysByActionKey
+      toolCategoryKeysByActionKey,
+      optionLists
     );
   }
   get spec() {
@@ -3328,6 +3585,9 @@ var Slate = class _Slate {
   get toolCategories() {
     return this._toolCategories ?? [];
   }
+  get optionLists() {
+    return this._optionLists ?? [];
+  }
   // Keys of the tool categories an action belongs to, in declared category order.
   getToolCategoryKeys(actionKey) {
     return [...this._toolCategoryKeysByActionKey?.get(actionKey) ?? []];
@@ -3401,7 +3661,7 @@ var resolveToolCategoryMembership = (toolCategories, actions) => {
 };
 
 // src/specification/specification.ts
-var import_zod3 = __toESM(require("zod"), 1);
+var import_zod5 = __toESM(require("zod"), 1);
 var SlateSpecification = class _SlateSpecification {
   constructor(_config, _auth, _params) {
     this._config = _config;
@@ -3418,7 +3678,7 @@ var SlateSpecification = class _SlateSpecification {
     return this._config.configSchema;
   }
   get authSchema() {
-    return "outputSchema" in this._auth ? this._auth.outputSchema : import_zod3.default.object({});
+    return "outputSchema" in this._auth ? this._auth.outputSchema : import_zod5.default.object({});
   }
   get config() {
     return this._config;
@@ -3523,6 +3783,7 @@ var skipWebhook = (reason, response) => ({
   SlateDefaultPollingIntervalSeconds,
   SlateError,
   SlateLogger,
+  SlateOptionList,
   SlatePublicContext,
   SlatePublicTool,
   SlateSpecification,
@@ -3534,6 +3795,7 @@ var skipWebhook = (reason, response) => ({
   adapterSpec,
   allOf,
   anyOf,
+  assertNewPageToken,
   auth,
   axios,
   buildApiServiceError,
@@ -3563,6 +3825,7 @@ var skipWebhook = (reason, response) => ({
   getResponseHeaderValue,
   getRuntimeInfo,
   getServiceErrorData,
+  getUpstreamErrorStatus,
   graphWebhookHttp,
   inferSlateErrorFromAxios,
   isApiErrorRecord,
@@ -3575,19 +3838,26 @@ var skipWebhook = (reason, response) => ({
   mergeScopes,
   metaWebhookHttp,
   normalizeOAuthTokenResponse,
+  optionList,
+  parseWithServiceError,
   pickDefined,
+  pruneSeenEntries,
   publicTool,
   pushBoundedApiErrorDetail,
   readApiErrorText,
   redactUrlAttachmentSecrets,
+  rememberPageToken,
   requestAxios,
   requestAxiosData,
   runWithContext,
   scopeClause,
+  seenEntryKey,
+  seenEntrySchema,
   setIfDefined,
   skipWebhook,
   spec,
   statusLabelForApiError,
+  timingSafeStringEqual,
   tool,
   toolCategory,
   trigger,